From 98385b1302044a773d3dce785b18baa8b2cf6444 Mon Sep 17 00:00:00 2001
From: Test User <test@example.com>
Date: Sat, 13 Jun 2026 11:35:22 -0600
Subject: [PATCH 01/15] chore(agenda): add ORCHESTRATE implementation plan

Working artifact for feature/agenda. Implement in a fresh session from
this worktree. See docs/specs/SPEC-agenda-schedule-2026-06-13.md.
Delete this file during dev merge cleanup.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 ORCHESTRATE-agenda.md | 99 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 99 insertions(+)
 create mode 100644 ORCHESTRATE-agenda.md

diff --git a/ORCHESTRATE-agenda.md b/ORCHESTRATE-agenda.md
new file mode 100644
index 000000000..0697698ec
--- /dev/null
+++ b/ORCHESTRATE-agenda.md
@@ -0,0 +1,99 @@
+# ORCHESTRATE: agenda + forward-looking schedule layer
+
+> **Feature branch:** `feature/agenda` · **Base:** `dev` · **Worktree:** `~/.git-worktrees/flow-cli/agenda`
+> **Spec:** `docs/specs/SPEC-agenda-schedule-2026-06-13.md` (committed on `dev`)
+> **Plan:** `~/.claude/plans/eventual-bouncing-phoenix.md`
+> **Target version:** v7.10.0 (minor)
+
+## ⛔ Session boundary
+
+This file was created by the **planning session on `dev`**. Implementation happens **here, in a
+NEW `claude` session started from this worktree**:
+
+```bash
+cd ~/.git-worktrees/flow-cli/agenda && claude
+```
+
+Do NOT implement from the dev/planning session.
+
+---
+
+## Goal
+
+Add a forward-looking schedule layer: new `agenda` command + UPCOMING section in `dash` +
+dated enrichment of `morning`/`today`/`week`, driven by one shared engine `lib/schedule.zsh`.
+Works fully without atlas and without `yq`. See the spec for the full rationale and data model.
+
+## Reuse (read-only — do NOT reinvent)
+
+- `lib/date-parser.zsh` → `_date_load_config` (teaching dates: `week_N`/`exam_*`/`deadline_*`/`holiday_*`), `_date_add_days`, `_date_normalize`, `_date_compute_from_week`.
+- `lib/atlas-bridge.zsh` → `_flow_has_atlas`, `_flow_atlas_async`, `_flow_list_projects`, `_flow_timestamp`.
+- `commands/dash.zsh` → `_dash_find_project_path`, `_dash_get_status_field`, `_dash_detect_category`, `_dash_get_urgency`.
+- `lib/core.zsh` → `FLOW_COLORS`. Cache pattern → `_dash_quick_health_check`.
+
+## Tasks (TDD: write/extend the test, then implement; `./tests/run-all.sh` + `source flow.plugin.zsh` green before each commit)
+
+### 1. Engine — `lib/schedule.zsh` (new)  → `tests/test-schedule.zsh`
+- [ ] Module guard `_FLOW_SCHEDULE_LOADED`; `typeset -g SCHEDULE_DEFAULT_WINDOW=7`.
+- [ ] `_schedule_classify <iso> [window]` → `overdue|today|soon|later`.
+- [ ] `_schedule_relative_days <iso>` → "today"/"in 3d"/"overdue 2d".
+- [ ] `_schedule_parse_status <status_file>` → records from `## Schedule:` (no external cmds); infers `project=${status_file:h:t}`.
+- [ ] `_schedule_teach_items <teach_config> <project> [window]` → `local -A CONFIG_DATES; eval "$(_date_load_config ...)"`; map week/exam/deadline; holidays typed `holiday` (filtered unless `--all`); guarded by `command -v yq` + file exists.
+- [ ] `_schedule_expand_recurring <weekly:dow> <start> <end>` → concrete dates (`strftime '%u'` + `_date_add_days`).
+- [ ] `_schedule_collect [window] [category]` → orchestrate over `_flow_list_projects`; emit record stream; session cache.
+- [ ] `_schedule_filter_window <window>` (stdin) → in-window + always overdue.
+- [ ] `_schedule_sort` (stdin) → `sort -t'|' -k1,1`.
+- [ ] `_schedule_render_line <record>` → type icon + urgency color + relative-day + label + dim project.
+- [ ] `_flow_schedule_to_atlas <record...>` → `_flow_has_atlas || return 0`; cap-probe `_FLOW_ATLAS_HAS_SCHEDULE`; `_flow_atlas_async`; no-op if absent.
+- **Tests:** parse block; empty/malformed → no crash; classify boundaries (frozen "today" arg); expand across **month+year** boundary; window filter; teach parse (fixture w/ `start_date`); **no-yq fallback**; **atlas-absent no-op** (mock `_flow_atlas_async` asserts not called).
+- **Footguns:** no `local path=` / `local status=`; `local -A CONFIG_DATES`; split with `${(f)...}`.
+
+### 2. Wiring — `flow.plugin.zsh`
+- [ ] Source `lib/date-parser.zsh` (if not already global) **then** `lib/schedule.zsh` in the core library block, after `atlas-bridge.zsh`.
+
+### 3. Command — `commands/agenda.zsh` (new)  → `tests/test-agenda.zsh`
+- [ ] `agenda [today|-w/--week|-m/--month|<category>|--all|--overdue|-h/--help]`; default = 7d.
+- [ ] Pipeline `_schedule_collect | _schedule_filter_window | _schedule_sort` → bucketed render (OVERDUE/TODAY/THIS WEEK/LATER) + calm empty state; then async atlas push.
+- [ ] `_agenda_help` (dash-style, `_C_*` locals). Aliases `agt`/`agw`/`agm` (avoid `ag`).
+- **Tests:** `-h`; default/`--overdue`/category/`--all`/`today` vs `-m`; empty state; `run_isolated` + `FLOW_ATLAS_ENABLED=no` + temp `FLOW_PROJECTS_ROOT`.
+
+### 4. dash — `commands/dash.zsh`  → extend `tests/test-dash.zsh`
+- [ ] `_dash_upcoming` (top 3–4, 7d + overdue); insert in `dash()` **after `_dash_quick_wins`, before `_dash_quick_access`**; self-suppress when empty.
+- [ ] Date-keyed session cache (~600s TTL) shared with agenda/morning.
+
+### 5. Cadence — `commands/morning.zsh`
+- [ ] `_flow_morning_agenda` in `morning` (top 5, 7d + overdue) between projects and wins; quick mode one-liner.
+- [ ] `today` → "📅 Due today" (0d) + overdue. `week` → "📅 This week's deadlines" (7d, by weekday).
+
+### 6. Packaging
+- [ ] `completions/_agenda` (model `completions/_dash`): flags + category states.
+- [ ] `man/man1/agenda.1` (model `man/man1/g.1`); `.TH` = `flow-cli <FLOW_VERSION>`.
+- [ ] **Patch `tests/test-manpage-version-sync.zsh`** orphan check: add `[[ "$base" == "agenda" ]] && continue` next to the `flow` skip (~line 223). REQUIRED or CI fails.
+- [ ] Register `tests/test-schedule.zsh` + `tests/test-agenda.zsh` in `tests/run-all.sh`.
+- [ ] Add a fixture `.flow/teach-config.yml` with `weeks[].start_date` (demo uses `weeks[].date` → yields no `week_N`).
+
+### 7. Docs
+- [ ] `CLAUDE.md` (command list + Quick Reference), `docs/help/QUICK-REFERENCE.md` (`agenda` + aliases + `## Schedule:` snippet).
+- [ ] `docs/reference/MASTER-DISPATCHER-GUIDE.md` (commands section; note dash UPCOMING + cadence enrichment).
+- [ ] New `docs/guides/AGENDA-SCHEDULE-GUIDE.md`; add to `mkdocs.yml` nav (strict build).
+- [ ] `docs/ATLAS-CONTRACT.md` — document opportunistic `atlas schedule push --format=json` contract.
+
+## Verification (before PR)
+
+1. `source flow.plugin.zsh` clean (no errors / leaked vars).
+2. `./tests/run-all.sh` green (new + touched suites; 1 expected interactive timeout).
+3. Manual: temp `FLOW_PROJECTS_ROOT` with a `## Schedule:` block + teach project w/ `start_date`; run
+   `agenda`, `agenda --overdue`, `agenda research`, `agenda -m`, `agenda -h`; verify buckets/overdue/filter/empty.
+4. `dash` shows UPCOMING after QUICK WINS; suppresses when none. `morning`/`today`/`week` show dated blocks.
+5. `FLOW_ATLAS_ENABLED=no agenda` fully works; atlas-without-`schedule` → silent no-op.
+6. `mkdocs build --strict` passes.
+
+## Integrate
+
+- [ ] `git fetch origin dev && git rebase origin/dev` → `./tests/run-all.sh` → `gh pr create --base dev`.
+- [ ] Bump version (v7.10.0) per release flow when merging dev→main.
+- [ ] **Delete this `ORCHESTRATE-agenda.md` as part of the merge cleanup** (working artifact — belongs on the feature branch, not on `dev`).
+
+## Out of scope (v1)
+
+Atlas-side `schedule` command (separate atlas PR); `monthly:`/multi-day recurrence; ICS export; interactive `agenda add`.

From 0e86cbcb54187fd56aa53b78faeefd57dd5f71e8 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sat, 13 Jun 2026 20:05:20 +0000
Subject: [PATCH 02/15] feat(schedule): add forward-looking schedule engine

Add lib/schedule.zsh, the shared engine for the new agenda layer. It
aggregates dated activity from two greenfield sources and normalizes
them to a pipe-delimited record stream (date|label|type|project|
recurrence|source) so every surface renders identically:

- .STATUS `## Schedule:` blocks (ZSH-parseable, no yq)
- .flow/teach-config.yml teaching dates (via _date_load_config, yq-guarded)

Functions: _schedule_classify, _schedule_relative_days,
_schedule_parse_status, _schedule_teach_items, _schedule_expand_recurring
(weekly:<dow>, crosses month/year boundaries), _schedule_collect (session
cached), _schedule_filter_window, _schedule_sort, _schedule_render_line,
and _flow_schedule_to_atlas (opportunistic, capability-detected, silent
no-op when atlas/schedule absent).

Reuses date-parser + atlas-bridge + dash helpers + FLOW_COLORS; pure ZSH,
works without atlas and without yq. Wire date-parser.zsh then schedule.zsh
into the core library block (after atlas-bridge.zsh).

tests/test-schedule.zsh (32 cases) covers classification boundaries,
relative-day labels, .STATUS parsing (empty/malformed safe), recurrence
expansion across month+year boundaries, window filtering, the no-yq
fallback, and the atlas-absent no-op. Adds tests/fixtures/
teach-config-scheduled.yml (weeks[].start_date, which _date_load_config
requires; the demo fixture uses weeks[].date and yields no week_N).

Verified: test-schedule (32/32), source flow.plugin.zsh clean. Full
run-all.sh has 17 pre-existing environmental failures (atlas/git/chezmoi/
himalaya/network-dependent), unchanged by this commit (confirmed against
a stashed baseline).

https://claude.ai/code/session_014YpEdtSqYMRdcuoMQFgLXW
---
 flow.plugin.zsh                           |   2 +
 lib/schedule.zsh                          | 501 ++++++++++++++++++++++
 tests/fixtures/teach-config-scheduled.yml |  44 ++
 tests/test-schedule.zsh                   | 405 +++++++++++++++++
 4 files changed, 952 insertions(+)
 create mode 100644 lib/schedule.zsh
 create mode 100644 tests/fixtures/teach-config-scheduled.yml
 create mode 100644 tests/test-schedule.zsh

diff --git a/flow.plugin.zsh b/flow.plugin.zsh
index 0c8cd9896..17626f2b2 100644
--- a/flow.plugin.zsh
+++ b/flow.plugin.zsh
@@ -30,6 +30,8 @@ FLOW_PLUGIN_DIR=${0:A:h}
 source "$FLOW_PLUGIN_DIR/lib/core.zsh"
 source "$FLOW_PLUGIN_DIR/lib/config.zsh"
 source "$FLOW_PLUGIN_DIR/lib/atlas-bridge.zsh"
+source "$FLOW_PLUGIN_DIR/lib/date-parser.zsh"
+source "$FLOW_PLUGIN_DIR/lib/schedule.zsh"
 source "$FLOW_PLUGIN_DIR/lib/dotfile-helpers.zsh"
 source "$FLOW_PLUGIN_DIR/lib/project-detector.zsh"
 source "$FLOW_PLUGIN_DIR/lib/project-cache.zsh"
diff --git a/lib/schedule.zsh b/lib/schedule.zsh
new file mode 100644
index 000000000..8b5869ec9
--- /dev/null
+++ b/lib/schedule.zsh
@@ -0,0 +1,501 @@
+# lib/schedule.zsh - Forward-looking schedule engine for flow-cli
+#
+# Shared engine powering the `agenda` command, the dash UPCOMING section, and
+# the dated enrichment of morning/today/week. Aggregates forward-looking dated
+# activity from two greenfield sources:
+#
+#   1. `.STATUS` `## Schedule:` blocks (per project) — ZSH-parseable, no yq.
+#   2. `.flow/teach-config.yml` teaching dates (per teaching project) — via
+#      _date_load_config (lib/date-parser.zsh); guarded by yq + file existence.
+#
+# Records are normalized to a pipe-delimited stream so every surface renders
+# identically:
+#
+#     date|label|type|project|recurrence|source
+#
+#   date        ISO YYYY-MM-DD (concrete; recurring tokens are expanded)
+#   label       human text (must not contain `|`)
+#   type        teaching|research|general|recurring|holiday
+#   project     inferred from ${status_file:h:t}
+#   recurrence  `none` or `weekly:<dow>`
+#   source      status|teach-config
+#
+# Pure ZSH. Works fully without atlas and without yq (the teaching path is the
+# only one that needs yq; the research/general path needs none). Atlas is an
+# opportunistic, capability-detected sync target.
+#
+# Reuses (read-only): _date_load_config / _date_add_days (lib/date-parser.zsh);
+# _flow_has_atlas / _flow_atlas_async / _flow_list_projects (lib/atlas-bridge.zsh);
+# _dash_find_project_path / _dash_detect_category (commands/dash.zsh);
+# FLOW_COLORS (lib/core.zsh).
+
+# Module guard
+[[ -n "$_FLOW_SCHEDULE_LOADED" ]] && return
+typeset -g _FLOW_SCHEDULE_LOADED=1
+
+zmodload zsh/datetime 2>/dev/null
+
+# ============================================================================
+# CONSTANTS
+# ============================================================================
+
+# Default look-ahead window (days) for agenda / dash / cadence.
+typeset -g SCHEDULE_DEFAULT_WINDOW=7
+
+# Session cache (date+window+category keyed, ~600s TTL) shared across surfaces.
+typeset -g SCHEDULE_CACHE_TTL=600
+typeset -g _SCHEDULE_CACHE_RECORDS=""
+typeset -g _SCHEDULE_CACHE_KEY=""
+typeset -g _SCHEDULE_CACHE_TIME=0
+
+# Atlas `schedule` subcommand capability probe (cached per session).
+typeset -g _FLOW_ATLAS_HAS_SCHEDULE=""
+
+# ============================================================================
+# DATE HELPERS
+# ============================================================================
+
+# Today as ISO YYYY-MM-DD (ZSH-native).
+_schedule_today() {
+  strftime '%Y-%m-%d' $EPOCHSECONDS
+}
+
+# =============================================================================
+# Function: _schedule_classify
+# Purpose: Classify an ISO date relative to today + a window
+# Arguments:
+#   $1 - ISO date (YYYY-MM-DD)
+#   $2 - window in days [default: SCHEDULE_DEFAULT_WINDOW]
+# Output:
+#   stdout - overdue|today|soon|later
+# Notes:
+#   - Pure string comparison (ISO dates sort lexically) + _date_add_days.
+#   - "soon" = strictly future but within the window; "later" = beyond it.
+# =============================================================================
+_schedule_classify() {
+  local iso="$1"
+  local window="${2:-$SCHEDULE_DEFAULT_WINDOW}"
+  [[ -z "$iso" ]] && return 1
+
+  local today=$(_schedule_today)
+
+  if [[ "$iso" < "$today" ]]; then
+    echo "overdue"
+  elif [[ "$iso" == "$today" ]]; then
+    echo "today"
+  else
+    local window_end=$(_date_add_days "$today" "$window")
+    if [[ -n "$window_end" && "$iso" > "$window_end" ]]; then
+      echo "later"
+    else
+      echo "soon"
+    fi
+  fi
+}
+
+# =============================================================================
+# Function: _schedule_relative_days
+# Purpose: Human relative-day label for an ISO date
+# Output:
+#   stdout - "today" | "in Nd" | "overdue Nd"
+# Notes:
+#   - Parses at local noon (strftime -r) to avoid DST off-by-one.
+# =============================================================================
+_schedule_relative_days() {
+  local iso="$1"
+  [[ -z "$iso" ]] && return 1
+
+  local today=$(_schedule_today)
+  local e t
+  e=$(strftime -r '%Y-%m-%d %H:%M:%S' "$iso 12:00:00" 2>/dev/null) || return 1
+  t=$(strftime -r '%Y-%m-%d %H:%M:%S' "$today 12:00:00" 2>/dev/null) || return 1
+
+  local diff=$(( (e - t) / 86400 ))
+  if (( diff == 0 )); then
+    echo "today"
+  elif (( diff > 0 )); then
+    echo "in ${diff}d"
+  else
+    echo "overdue $(( -diff ))d"
+  fi
+}
+
+# =============================================================================
+# Function: _schedule_type_icon
+# Purpose: Map a record type to its display icon
+# =============================================================================
+_schedule_type_icon() {
+  case "$1" in
+    teaching)  echo "🎓" ;;
+    research)  echo "🔬" ;;
+    recurring) echo "🔁" ;;
+    holiday)   echo "🏖️" ;;
+    general|*) echo "📌" ;;
+  esac
+}
+
+# ============================================================================
+# PARSING — .STATUS `## Schedule:` section (no external commands)
+# ============================================================================
+
+# =============================================================================
+# Function: _schedule_parse_status
+# Purpose: Extract schedule records from a `.STATUS` `## Schedule:` block
+# Arguments:
+#   $1 - path to a .STATUS file
+# Output:
+#   stdout - records (date|label|type|project|recurrence|source)
+#            ISO entries carry a concrete date; `weekly:<dow>` entries carry an
+#            empty date field + recurrence token (expanded later by collect).
+# Grammar (one list item per line):
+#   - <when> | <label> [| <type>]
+#     when  = YYYY-MM-DD | weekly:<dow>
+#     type  = teaching|research|general|recurring (optional)
+# Notes:
+#   - `project` inferred from ${status_file:h:t}. Unknown tokens skipped, not
+#     fatal. Empty / malformed lines ignored.
+# =============================================================================
+_schedule_parse_status() {
+  local status_file="$1"
+  [[ -f "$status_file" ]] || return 0
+
+  local project="${status_file:h:t}"
+  local in_section=0 line
+
+  while IFS= read -r line || [[ -n "$line" ]]; do
+    # Enter the Schedule block
+    if [[ "$line" == "## Schedule:"* ]]; then
+      in_section=1
+      continue
+    fi
+    # Any other `## ` heading ends the block
+    if (( in_section )) && [[ "$line" == "## "* ]]; then
+      in_section=0
+      continue
+    fi
+    (( in_section )) || continue
+
+    # Only list items ("- ...")
+    [[ "$line" == "-"* ]] || continue
+    local body="${line#-}"
+    body="${body#"${body%%[![:space:]]*}"}"   # trim leading whitespace
+    [[ -z "$body" ]] && continue
+
+    # Split on `|`
+    local -a parts
+    parts=("${(@s:|:)body}")
+    local when="${parts[1]}" label="${parts[2]}" typ="${parts[3]}"
+
+    when="${when//[[:space:]]/}"                                   # strip ws
+    label="${label#"${label%%[![:space:]]*}"}"                    # ltrim
+    label="${label%"${label##*[![:space:]]}"}"                    # rtrim
+    typ="${typ//[[:space:]]/}"; typ="${typ:l}"
+
+    [[ -z "$when" || -z "$label" ]] && continue
+
+    if [[ "$when" == [0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9] ]]; then
+      [[ -z "$typ" ]] && typ="general"
+      echo "${when}|${label}|${typ}|${project}|none|status"
+    elif [[ "$when" == weekly:* ]]; then
+      local dow="${when#weekly:}"
+      [[ -z "$dow" ]] && continue
+      [[ -z "$typ" ]] && typ="recurring"
+      echo "|${label}|${typ}|${project}|weekly:${dow}|status"
+    fi
+    # unknown `when` tokens are silently skipped
+  done < "$status_file"
+}
+
+# ============================================================================
+# PARSING — teaching config (.flow/teach-config.yml via date-parser)
+# ============================================================================
+
+# =============================================================================
+# Function: _schedule_teach_items
+# Purpose: Derive schedule records from a teaching config's dated entries
+# Arguments:
+#   $1 - path to .flow/teach-config.yml
+#   $2 - project name
+#   $3 - window in days (unused for filtering here; kept for symmetry)
+# Output:
+#   stdout - records (date|label|type|project|none|teach-config)
+# Notes:
+#   - Reuses _date_load_config -> CONFIG_DATES (week_N / exam_* / deadline_* /
+#     holiday_*). Holidays typed `holiday` (callers filter unless --all).
+#   - Guarded by `command -v yq` + file existence; no-op (return 0) otherwise.
+#   - Uses `local -A CONFIG_DATES` per the date-parser contract.
+# =============================================================================
+_schedule_teach_items() {
+  local config="$1" project="$2"
+  [[ -f "$config" ]] || return 0
+  command -v yq >/dev/null 2>&1 || return 0
+
+  local -A CONFIG_DATES
+  eval "$(_date_load_config "$config" 2>/dev/null)"
+
+  local key val typ label
+  for key val in "${(@kv)CONFIG_DATES}"; do
+    [[ -z "$val" || "$val" == "null" ]] && continue
+    case "$key" in
+      week_*)
+        label="Week ${key#week_}"
+        typ="teaching"
+        ;;
+      exam_*)
+        label="Exam: ${${key#exam_}//_/ }"
+        typ="teaching"
+        ;;
+      deadline_*)
+        label="Due: ${${key#deadline_}//_/ }"
+        typ="teaching"
+        ;;
+      holiday_*)
+        label="Holiday: ${${key#holiday_}//_/ }"
+        typ="holiday"
+        ;;
+      *)
+        continue
+        ;;
+    esac
+    echo "${val}|${label}|${typ}|${project}|none|teach-config"
+  done
+}
+
+# ============================================================================
+# RECURRENCE EXPANSION
+# ============================================================================
+
+# =============================================================================
+# Function: _schedule_expand_recurring
+# Purpose: Expand a `weekly:<dow>` token into concrete in-range ISO dates
+# Arguments:
+#   $1 - recurrence token (e.g. weekly:fri)
+#   $2 - start ISO date (inclusive)
+#   $3 - end ISO date (inclusive)
+# Output:
+#   stdout - one ISO date per occurrence (may cross month/year boundaries)
+# Notes:
+#   - Jumps to the first matching weekday then strides +7 days (few iterations).
+#   - Uses strftime '%u' (1=Mon..7=Sun) + _date_add_days for cross-platform math.
+# =============================================================================
+_schedule_expand_recurring() {
+  local token="$1" start="$2" end="$3"
+  local dow="${token#weekly:}"
+
+  local -A dowmap=(
+    mon 1 tue 2 wed 3 thu 4 fri 5 sat 6 sun 7
+    monday 1 tuesday 2 wednesday 3 thursday 4 friday 5 saturday 6 sunday 7
+  )
+  local target="${dowmap[${dow:l}]}"
+  [[ -z "$target" || -z "$start" || -z "$end" ]] && return 0
+
+  local start_epoch
+  start_epoch=$(strftime -r '%Y-%m-%d %H:%M:%S' "$start 12:00:00" 2>/dev/null) || return 0
+  local start_dow=$(strftime '%u' "$start_epoch")
+  local delta=$(( (target - start_dow + 7) % 7 ))
+
+  local cur=$(_date_add_days "$start" "$delta")
+  local guard=0
+  while [[ -n "$cur" ]] && { [[ "$cur" < "$end" ]] || [[ "$cur" == "$end" ]]; }; do
+    echo "$cur"
+    cur=$(_date_add_days "$cur" 7)
+    (( ++guard >= 60 )) && break
+  done
+}
+
+# ============================================================================
+# COLLECTION + PIPELINE
+# ============================================================================
+
+# =============================================================================
+# Function: _schedule_collect
+# Purpose: Aggregate concrete-dated records across all projects
+# Arguments:
+#   $1 - window in days [default: SCHEDULE_DEFAULT_WINDOW]
+#   $2 - category filter (dev|r|research|teach|quarto|apps) [optional]
+# Output:
+#   stdout - record stream (recurring tokens expanded to concrete dates)
+# Notes:
+#   - Session cache keyed on today|window|category (TTL SCHEDULE_CACHE_TTL).
+#     Set FLOW_SCHEDULE_NO_CACHE=1 to bypass (tests).
+#   - Recurrence expansion window is capped at 90 days to keep output sane.
+# =============================================================================
+_schedule_collect() {
+  local window="${1:-$SCHEDULE_DEFAULT_WINDOW}"
+  local category="${2:-}"
+
+  local today=$(_schedule_today)
+  local cache_key="${today}|${window}|${category}"
+
+  if [[ -z "$FLOW_SCHEDULE_NO_CACHE" ]] \
+     && [[ "$_SCHEDULE_CACHE_KEY" == "$cache_key" ]] \
+     && (( EPOCHSECONDS - _SCHEDULE_CACHE_TIME < SCHEDULE_CACHE_TTL )); then
+    [[ -n "$_SCHEDULE_CACHE_RECORDS" ]] && print -r -- "$_SCHEDULE_CACHE_RECORDS"
+    return 0
+  fi
+
+  # recurrence expansion range (cap to keep output bounded for wide windows)
+  local rwin=$window
+  (( rwin > 90 )) && rwin=90
+  local rend=$(_date_add_days "$today" "$rwin")
+
+  local -a out=()
+  local project proj_path cat rec
+
+  while IFS= read -r project; do
+    [[ -z "$project" ]] && continue
+    proj_path=$(_dash_find_project_path "$project") || continue
+    [[ -z "$proj_path" ]] && continue
+
+    if [[ -n "$category" ]]; then
+      cat=$(_dash_detect_category "$proj_path")
+      [[ "$cat" != "$category" ]] && continue
+    fi
+
+    # 1. .STATUS schedule block
+    if [[ -f "$proj_path/.STATUS" ]]; then
+      while IFS= read -r rec; do
+        [[ -z "$rec" ]] && continue
+        if [[ "$rec" == "|"* ]]; then
+          # recurring: empty date field -> expand
+          local -a rf=("${(@s:|:)rec}")
+          local recurrence="${rf[5]}"
+          local tail="${rec#|}"   # label|type|project|recurrence|source
+          local d
+          for d in ${(f)"$(_schedule_expand_recurring "$recurrence" "$today" "$rend")"}; do
+            out+=("${d}|${tail}")
+          done
+        else
+          out+=("$rec")
+        fi
+      done < <(_schedule_parse_status "$proj_path/.STATUS")
+    fi
+
+    # 2. teaching config
+    if [[ -f "$proj_path/.flow/teach-config.yml" ]]; then
+      while IFS= read -r rec; do
+        [[ -z "$rec" ]] && continue
+        out+=("$rec")
+      done < <(_schedule_teach_items "$proj_path/.flow/teach-config.yml" "$project")
+    fi
+  done < <(_flow_list_projects)
+
+  local records=""
+  (( ${#out[@]} > 0 )) && records=$(print -rl -- "${out[@]}")
+
+  _SCHEDULE_CACHE_RECORDS="$records"
+  _SCHEDULE_CACHE_KEY="$cache_key"
+  _SCHEDULE_CACHE_TIME=$EPOCHSECONDS
+
+  [[ -n "$records" ]] && print -r -- "$records"
+  return 0
+}
+
+# =============================================================================
+# Function: _schedule_filter_window
+# Purpose: Keep records within the window (always keep overdue); drop `later`
+# Arguments:
+#   $1 - window in days [default: SCHEDULE_DEFAULT_WINDOW]
+# Input:  stdin  - record stream
+# Output: stdout - filtered record stream
+# Notes:
+#   - Holidays are passed through here; callers drop them unless `--all`.
+# =============================================================================
+_schedule_filter_window() {
+  local window="${1:-$SCHEDULE_DEFAULT_WINDOW}"
+  local rec date class
+  while IFS= read -r rec; do
+    [[ -z "$rec" ]] && continue
+    date="${rec%%|*}"
+    [[ -z "$date" ]] && continue
+    class=$(_schedule_classify "$date" "$window")
+    [[ "$class" == "later" ]] && continue
+    print -r -- "$rec"
+  done
+}
+
+# =============================================================================
+# Function: _schedule_sort
+# Purpose: Sort a record stream by date ascending (overdue first)
+# Input:  stdin  - record stream
+# Output: stdout - sorted record stream
+# =============================================================================
+_schedule_sort() {
+  sort -t'|' -k1,1
+}
+
+# =============================================================================
+# Function: _schedule_render_line
+# Purpose: Render a single record (type icon + urgency color + relative day)
+# Arguments:
+#   $1 - record (date|label|type|project|recurrence|source)
+# =============================================================================
+_schedule_render_line() {
+  local rec="$1"
+  [[ -z "$rec" ]] && return 0
+
+  local -a f=("${(@s:|:)rec}")
+  local date="${f[1]}" label="${f[2]}" typ="${f[3]}" project="${f[4]}" recurrence="${f[5]}"
+
+  local class=$(_schedule_classify "$date" "$SCHEDULE_DEFAULT_WINDOW")
+  local rel=$(_schedule_relative_days "$date")
+
+  local color="${FLOW_COLORS[muted]}"
+  case "$class" in
+    overdue) color="${FLOW_COLORS[error]}" ;;
+    today)   color="${FLOW_COLORS[warning]}" ;;
+    soon)    color="${FLOW_COLORS[info]}" ;;
+    later)   color="${FLOW_COLORS[muted]}" ;;
+  esac
+
+  local ticon=$(_schedule_type_icon "$typ")
+  local rmark=""
+  [[ -n "$recurrence" && "$recurrence" != "none" ]] && rmark=" 🔁"
+
+  printf "  %s ${color}%-11s${FLOW_COLORS[reset]} %s%s ${FLOW_COLORS[muted]}(%s)${FLOW_COLORS[reset]}\n" \
+    "$ticon" "$rel" "$label" "$rmark" "$project"
+}
+
+# ============================================================================
+# ATLAS (opportunistic, capability-detected)
+# ============================================================================
+
+# =============================================================================
+# Function: _flow_schedule_to_atlas
+# Purpose: Opportunistically push records to atlas (async, no-op if absent)
+# Arguments:
+#   $@ - records (date|label|type|project|recurrence|source)
+# Notes:
+#   - Silent no-op when atlas is absent OR lacks a `schedule` subcommand.
+#   - Capability is probed once and cached in _FLOW_ATLAS_HAS_SCHEDULE.
+#   - See docs/ATLAS-CONTRACT.md for the proposed `atlas schedule push` contract.
+# =============================================================================
+_flow_schedule_to_atlas() {
+  _flow_has_atlas || return 0
+
+  if [[ -z "$_FLOW_ATLAS_HAS_SCHEDULE" ]]; then
+    if atlas schedule --help >/dev/null 2>&1; then
+      _FLOW_ATLAS_HAS_SCHEDULE="yes"
+    else
+      _FLOW_ATLAS_HAS_SCHEDULE="no"
+    fi
+  fi
+  [[ "$_FLOW_ATLAS_HAS_SCHEDULE" == "yes" ]] || return 0
+
+  local -a records=("$@")
+  (( ${#records[@]} == 0 )) && return 0
+
+  local json="[" first=1 rec
+  for rec in "${records[@]}"; do
+    [[ -z "$rec" ]] && continue
+    local -a f=("${(@s:|:)rec}")
+    (( first )) || json+=","
+    first=0
+    json+=$(printf '{"date":"%s","label":"%s","type":"%s","project":"%s","recurrence":"%s","source":"%s"}' \
+      "${f[1]}" "${f[2]}" "${f[3]}" "${f[4]}" "${f[5]}" "${f[6]}")
+  done
+  json+="]"
+
+  _flow_atlas_async schedule push --format=json --data="$json"
+  return 0
+}
diff --git a/tests/fixtures/teach-config-scheduled.yml b/tests/fixtures/teach-config-scheduled.yml
new file mode 100644
index 000000000..3bd3f8f91
--- /dev/null
+++ b/tests/fixtures/teach-config-scheduled.yml
@@ -0,0 +1,44 @@
+# Fixture: teaching config with weeks[].start_date (schedule engine tests)
+#
+# The demo-course fixture uses weeks[].date, which _date_load_config does NOT
+# read (it requires weeks[].start_date) — so it yields no week_N entries. This
+# fixture exercises the full teaching path: week starts, exams, deadlines, and
+# a holiday, all consumed by _date_load_config -> CONFIG_DATES.
+
+course:
+  name: 'STAT-202'
+  full_name: 'STAT 202 - Intermediate Statistics'
+  semester: 'fall'
+  year: 2026
+
+semester_info:
+  start_date: '2026-08-31'
+  end_date: '2026-12-11'
+
+  weeks:
+    - number: 1
+      topic: 'Review and Foundations'
+      start_date: '2026-08-31'
+    - number: 2
+      topic: 'Linear Models'
+      start_date: '2026-09-07'
+    - number: 3
+      topic: 'Generalized Linear Models'
+      start_date: '2026-09-14'
+
+  exams:
+    - name: 'Midterm'
+      date: '2026-10-12'
+    - name: 'Final'
+      date: '2026-12-14'
+
+  deadlines:
+    project_proposal:
+      due_date: '2026-09-25'
+    final_report:
+      week: 3
+      offset_days: 4
+
+  holidays:
+    - name: 'Fall Break'
+      date: '2026-11-26'
diff --git a/tests/test-schedule.zsh b/tests/test-schedule.zsh
new file mode 100644
index 000000000..b1fc2d089
--- /dev/null
+++ b/tests/test-schedule.zsh
@@ -0,0 +1,405 @@
+#!/usr/bin/env zsh
+# Test script for the schedule engine (lib/schedule.zsh)
+# Tests: classification, relative days, .STATUS parsing, teach items,
+#        recurrence expansion (incl. month/year boundaries), window filter,
+#        no-yq fallback, atlas-absent no-op.
+
+# ============================================================================
+# FRAMEWORK
+# ============================================================================
+
+SCRIPT_DIR="${0:A:h}"
+PROJECT_ROOT="${SCRIPT_DIR:h}"
+source "$SCRIPT_DIR/test-framework.zsh" || { echo "ERROR: Cannot source test-framework.zsh"; exit 1 }
+
+# ============================================================================
+# SETUP
+# ============================================================================
+
+setup() {
+    if [[ ! -f "$PROJECT_ROOT/flow.plugin.zsh" ]]; then
+        echo "${RED}ERROR: Cannot find project root${RESET}"
+        exit 1
+    fi
+
+    FLOW_QUIET=1
+    FLOW_ATLAS_ENABLED=no
+    FLOW_PLUGIN_DIR="$PROJECT_ROOT"
+    FLOW_SCHEDULE_NO_CACHE=1
+    source "$PROJECT_ROOT/flow.plugin.zsh" 2>/dev/null || {
+        echo "${RED}Plugin failed to load${RESET}"
+        exit 1
+    }
+
+    exec < /dev/null
+
+    # Isolated project root with a research project that has a ## Schedule: block
+    TEST_ROOT=$(mktemp -d)
+    mkdir -p "$TEST_ROOT/research/mock-study"
+    FLOW_PROJECTS_ROOT="$TEST_ROOT"
+
+    # Pin "today" reference for date-sensitive assertions
+    zmodload zsh/datetime 2>/dev/null
+    TODAY=$(strftime '%Y-%m-%d' $EPOCHSECONDS)
+    PAST=$(_date_add_days "$TODAY" -2)
+    SOON=$(_date_add_days "$TODAY" 3)
+    FAR=$(_date_add_days "$TODAY" 20)
+
+    cat > "$TEST_ROOT/research/mock-study/.STATUS" <<EOF
+## Status: active
+## Focus: writing
+
+## Schedule:
+- $PAST | Overdue manuscript task | research
+- $TODAY | Due today item | research
+- $SOON | Submit revision | research
+- $FAR | Beta milestone | general
+- weekly:fri | Grading window | recurring
+- garbage line that should be ignored
+- not-a-date | still ignored | general
+
+## Notes:
+- this is not a schedule item
+EOF
+    STATUS_FILE="$TEST_ROOT/research/mock-study/.STATUS"
+}
+
+cleanup() {
+    reset_mocks
+    [[ -d "$TEST_ROOT" ]] && rm -rf "$TEST_ROOT"
+}
+trap cleanup EXIT
+
+# ============================================================================
+# TESTS: module loading + constants
+# ============================================================================
+
+test_engine_loaded() {
+    test_case "schedule engine module guard set"
+    assert_equals "$_FLOW_SCHEDULE_LOADED" "1" "_FLOW_SCHEDULE_LOADED should be 1" && test_pass
+}
+
+test_default_window() {
+    test_case "SCHEDULE_DEFAULT_WINDOW is 7"
+    assert_equals "$SCHEDULE_DEFAULT_WINDOW" "7" "default window should be 7" && test_pass
+}
+
+test_functions_exist() {
+    test_case "core engine functions exist"
+    assert_function_exists "_schedule_classify" && \
+    assert_function_exists "_schedule_relative_days" && \
+    assert_function_exists "_schedule_parse_status" && \
+    assert_function_exists "_schedule_teach_items" && \
+    assert_function_exists "_schedule_expand_recurring" && \
+    assert_function_exists "_schedule_collect" && \
+    assert_function_exists "_schedule_filter_window" && \
+    assert_function_exists "_schedule_sort" && \
+    assert_function_exists "_schedule_render_line" && \
+    assert_function_exists "_flow_schedule_to_atlas" && test_pass
+}
+
+# ============================================================================
+# TESTS: classification (frozen "today" arg)
+# ============================================================================
+
+test_classify_overdue() {
+    test_case "classify past date -> overdue"
+    assert_equals "$(_schedule_classify "$PAST" 7)" "overdue" && test_pass
+}
+
+test_classify_today() {
+    test_case "classify today -> today"
+    assert_equals "$(_schedule_classify "$TODAY" 7)" "today" && test_pass
+}
+
+test_classify_soon() {
+    test_case "classify in-window date -> soon"
+    assert_equals "$(_schedule_classify "$SOON" 7)" "soon" && test_pass
+}
+
+test_classify_later() {
+    test_case "classify beyond-window date -> later"
+    assert_equals "$(_schedule_classify "$FAR" 7)" "later" && test_pass
+}
+
+test_classify_boundary() {
+    test_case "classify exactly at window edge -> soon (inclusive)"
+    local edge=$(_date_add_days "$TODAY" 7)
+    assert_equals "$(_schedule_classify "$edge" 7)" "soon" && test_pass
+}
+
+# ============================================================================
+# TESTS: relative days
+# ============================================================================
+
+test_relative_today() {
+    test_case "relative days: today"
+    assert_equals "$(_schedule_relative_days "$TODAY")" "today" && test_pass
+}
+
+test_relative_future() {
+    test_case "relative days: in 3d"
+    assert_equals "$(_schedule_relative_days "$SOON")" "in 3d" && test_pass
+}
+
+test_relative_overdue() {
+    test_case "relative days: overdue 2d"
+    assert_equals "$(_schedule_relative_days "$PAST")" "overdue 2d" && test_pass
+}
+
+# ============================================================================
+# TESTS: .STATUS parsing
+# ============================================================================
+
+test_parse_status_count() {
+    test_case "parse_status emits 5 records (4 ISO + 1 recurring)"
+    local out=$(_schedule_parse_status "$STATUS_FILE")
+    local n=$(print -r -- "$out" | grep -c .)
+    assert_equals "$n" "5" "should parse exactly 5 records, got $n" && test_pass
+}
+
+test_parse_status_infers_project() {
+    test_case "parse_status infers project from path"
+    local out=$(_schedule_parse_status "$STATUS_FILE")
+    assert_contains "$out" "|mock-study|" "project should be mock-study" && test_pass
+}
+
+test_parse_status_recurring_empty_date() {
+    test_case "parse_status emits recurring with empty date + recurrence token"
+    local out=$(_schedule_parse_status "$STATUS_FILE")
+    assert_contains "$out" "|Grading window|recurring|mock-study|weekly:fri|status" && test_pass
+}
+
+test_parse_status_default_type() {
+    test_case "parse_status defaults ISO type to general when omitted"
+    # (mock-study has explicit types; test the default via a temp file)
+    local tmp=$(mktemp -d)/.STATUS
+    printf '## Schedule:\n- 2030-01-01 | Untyped item\n' > "$tmp"
+    local out=$(_schedule_parse_status "$tmp")
+    assert_contains "$out" "2030-01-01|Untyped item|general|" && test_pass
+}
+
+test_parse_status_empty_file() {
+    test_case "parse_status on missing file -> no crash, no output"
+    local out=$(_schedule_parse_status "/nonexistent/.STATUS" 2>&1)
+    assert_empty "$out" "should produce no output" && test_pass
+}
+
+test_parse_status_no_section() {
+    test_case "parse_status with no Schedule section -> empty"
+    local tmp=$(mktemp -d)/.STATUS
+    printf '## Status: active\n## Focus: x\n' > "$tmp"
+    local out=$(_schedule_parse_status "$tmp")
+    assert_empty "$out" "no schedule section should yield nothing" && test_pass
+}
+
+# ============================================================================
+# TESTS: recurrence expansion (month + year boundaries)
+# ============================================================================
+
+test_expand_basic() {
+    test_case "expand weekly:fri yields Fridays in range"
+    # 2026-06-01 is a Monday; first Friday is 2026-06-05
+    local out=$(_schedule_expand_recurring "weekly:fri" "2026-06-01" "2026-06-30")
+    assert_contains "$out" "2026-06-05" "first Friday" && \
+    assert_contains "$out" "2026-06-12" "second Friday" && \
+    assert_contains "$out" "2026-06-26" "last Friday in June" && test_pass
+}
+
+test_expand_month_boundary() {
+    test_case "expand crosses month boundary"
+    local out=$(_schedule_expand_recurring "weekly:wed" "2026-06-28" "2026-07-10")
+    # Wednesdays: 2026-07-01, 2026-07-08
+    assert_contains "$out" "2026-07-01" "Wed after month change" && \
+    assert_contains "$out" "2026-07-08" "next Wed" && test_pass
+}
+
+test_expand_year_boundary() {
+    test_case "expand crosses year boundary"
+    local out=$(_schedule_expand_recurring "weekly:thu" "2026-12-28" "2027-01-10")
+    # Thursdays: 2026-12-31, 2027-01-07
+    assert_contains "$out" "2026-12-31" "Thu in Dec" && \
+    assert_contains "$out" "2027-01-07" "Thu in Jan next year" && test_pass
+}
+
+test_expand_unknown_dow() {
+    test_case "expand unknown weekday -> no output"
+    local out=$(_schedule_expand_recurring "weekly:funday" "2026-06-01" "2026-06-30")
+    assert_empty "$out" "unknown dow should produce nothing" && test_pass
+}
+
+# ============================================================================
+# TESTS: collection + window filter
+# ============================================================================
+
+test_collect_runs() {
+    test_case "collect runs and includes overdue + soon items"
+    local out=$(_schedule_collect 7)
+    assert_contains "$out" "Overdue manuscript task" && \
+    assert_contains "$out" "Submit revision" && test_pass
+}
+
+test_collect_expands_recurring() {
+    test_case "collect expands recurring into concrete dates"
+    local out=$(_schedule_collect 7)
+    # recurring grading window should appear with a concrete ISO date prefix
+    assert_contains "$out" "Grading window" "recurring item present" && \
+    assert_contains "$out" "weekly:fri" "recurrence token preserved" && test_pass
+}
+
+test_collect_category_filter() {
+    test_case "collect honors category filter (dev finds nothing here)"
+    local out=$(_schedule_collect 7 dev)
+    assert_empty "$out" "no dev-category projects -> empty" && test_pass
+}
+
+test_filter_window_drops_later() {
+    test_case "filter_window drops beyond-window, keeps overdue"
+    local out=$(_schedule_collect 30 | _schedule_filter_window 7)
+    assert_contains "$out" "Overdue manuscript task" "overdue always kept" && \
+    assert_not_contains "$out" "Beta milestone" "20d item dropped at window 7" && test_pass
+}
+
+test_filter_window_wide_keeps() {
+    test_case "filter_window at 30d keeps the 20d item"
+    local out=$(_schedule_collect 30 | _schedule_filter_window 30)
+    assert_contains "$out" "Beta milestone" "20d item kept at window 30" && test_pass
+}
+
+test_sort_orders_by_date() {
+    test_case "sort orders overdue before future"
+    local out=$(_schedule_collect 30 | _schedule_filter_window 30 | _schedule_sort)
+    local first=$(print -r -- "$out" | head -1)
+    assert_contains "$first" "Overdue manuscript task" "earliest date first" && test_pass
+}
+
+# ============================================================================
+# TESTS: render line
+# ============================================================================
+
+test_render_line() {
+    test_case "render_line shows relative day, label, project"
+    local out=$(_schedule_render_line "${TODAY}|Demo task|research|myproj|none|status")
+    assert_contains "$out" "today" "relative day" && \
+    assert_contains "$out" "Demo task" "label" && \
+    assert_contains "$out" "myproj" "project" && test_pass
+}
+
+test_render_line_recurring_mark() {
+    test_case "render_line marks recurring items"
+    local out=$(_schedule_render_line "${TODAY}|Standup|recurring|myproj|weekly:mon|status")
+    assert_contains "$out" "🔁" "recurrence marker" && test_pass
+}
+
+# ============================================================================
+# TESTS: teach items (yq-guarded) + no-yq fallback
+# ============================================================================
+
+test_teach_items_no_yq_fallback() {
+    test_case "teach_items returns nothing without yq (graceful)"
+    # Shadow yq with a command -v that fails: run in a subshell w/ PATH cleared
+    local out=$(PATH="/nonexistent" _schedule_teach_items "/whatever/teach-config.yml" proj 2>&1)
+    assert_empty "$out" "no yq + no file -> empty" && test_pass
+}
+
+test_teach_items_with_fixture() {
+    test_case "teach_items parses fixture with weeks[].start_date"
+    if ! command -v yq >/dev/null 2>&1; then
+        test_skip "yq not installed"
+        return
+    fi
+    local fixture="$PROJECT_ROOT/tests/fixtures/teach-config-scheduled.yml"
+    if [[ ! -f "$fixture" ]]; then
+        test_skip "fixture not present"
+        return
+    fi
+    local out=$(_schedule_teach_items "$fixture" stat-202)
+    assert_contains "$out" "|teaching|stat-202|none|teach-config" "teaching records emitted" && \
+    assert_contains "$out" "Week 1" "week record present" && test_pass
+}
+
+# ============================================================================
+# TESTS: atlas opportunistic push (absent -> no-op)
+# ============================================================================
+
+test_atlas_noop_when_absent() {
+    test_case "atlas push is a no-op when atlas absent (async not called)"
+    # FLOW_ATLAS_ENABLED=no => _flow_has_atlas false
+    create_mock "_flow_atlas_async"
+    _flow_schedule_to_atlas "${TODAY}|x|research|p|none|status"
+    assert_mock_not_called "_flow_atlas_async" && test_pass
+    reset_mocks
+}
+
+# ============================================================================
+# RUN TESTS
+# ============================================================================
+
+main() {
+    test_suite_start "Schedule Engine Tests"
+    setup
+
+    echo "${CYAN}--- Module + constants ---${RESET}"
+    test_engine_loaded
+    test_default_window
+    test_functions_exist
+
+    echo ""
+    echo "${CYAN}--- Classification ---${RESET}"
+    test_classify_overdue
+    test_classify_today
+    test_classify_soon
+    test_classify_later
+    test_classify_boundary
+
+    echo ""
+    echo "${CYAN}--- Relative days ---${RESET}"
+    test_relative_today
+    test_relative_future
+    test_relative_overdue
+
+    echo ""
+    echo "${CYAN}--- .STATUS parsing ---${RESET}"
+    test_parse_status_count
+    test_parse_status_infers_project
+    test_parse_status_recurring_empty_date
+    test_parse_status_default_type
+    test_parse_status_empty_file
+    test_parse_status_no_section
+
+    echo ""
+    echo "${CYAN}--- Recurrence expansion ---${RESET}"
+    test_expand_basic
+    test_expand_month_boundary
+    test_expand_year_boundary
+    test_expand_unknown_dow
+
+    echo ""
+    echo "${CYAN}--- Collection + window filter ---${RESET}"
+    test_collect_runs
+    test_collect_expands_recurring
+    test_collect_category_filter
+    test_filter_window_drops_later
+    test_filter_window_wide_keeps
+    test_sort_orders_by_date
+
+    echo ""
+    echo "${CYAN}--- Render line ---${RESET}"
+    test_render_line
+    test_render_line_recurring_mark
+
+    echo ""
+    echo "${CYAN}--- Teach items + no-yq fallback ---${RESET}"
+    test_teach_items_no_yq_fallback
+    test_teach_items_with_fixture
+
+    echo ""
+    echo "${CYAN}--- Atlas opportunistic push ---${RESET}"
+    test_atlas_noop_when_absent
+
+    cleanup
+    test_suite_end
+    exit $?
+}
+
+main "$@"

From 49de8d0e4433409c9f624cd29b3bb0ef2c705858 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sat, 13 Jun 2026 20:07:23 +0000
Subject: [PATCH 03/15] feat(agenda): add forward-looking agenda command
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add commands/agenda.zsh — a top-level command (not a dispatcher) that
renders the schedule engine's records grouped into OVERDUE / TODAY /
THIS WEEK / LATER buckets with a calm empty state ("Nothing scheduled —
clear runway").

Flags: default/`-w`/`--week` (7d), `today` (0d + overdue), `-m`/`--month`
(30d, adds LATER), `--all` (no cap, includes holidays), `--overdue`
(overdue only), `<category>` (dev|r|research|teach|teaching|quarto|apps),
`-h`/`--help`. Pipeline: _schedule_collect | _schedule_filter_window |
_schedule_sort, then an async _flow_schedule_to_atlas push. Holidays are
filtered unless `--all`. Aliases agt/agw/agm (avoiding `ag`, which
collides with the silver-searcher binary). _agenda_help follows the
dash-style _C_* convention.

Also polish _schedule_render_line: drop the trailing 🔁 marker when the
type icon is already 🔁 (recurring type), keeping it for recurrence on
other types (e.g. a research weekly block).

tests/test-agenda.zsh (17 cases): help, windows, --overdue, category
filter, empty state, unknown option, and a run_isolated case with atlas
disabled + a temp FLOW_PROJECTS_ROOT. All green (agenda 17/17,
schedule 32/32); source flow.plugin.zsh clean.

https://claude.ai/code/session_014YpEdtSqYMRdcuoMQFgLXW
---
 commands/agenda.zsh     | 227 +++++++++++++++++++++++++++++++
 lib/schedule.zsh        |   4 +-
 tests/test-agenda.zsh   | 292 ++++++++++++++++++++++++++++++++++++++++
 tests/test-schedule.zsh |   8 +-
 4 files changed, 527 insertions(+), 4 deletions(-)
 create mode 100644 commands/agenda.zsh
 create mode 100644 tests/test-agenda.zsh

diff --git a/commands/agenda.zsh b/commands/agenda.zsh
new file mode 100644
index 000000000..fbd4e47f2
--- /dev/null
+++ b/commands/agenda.zsh
@@ -0,0 +1,227 @@
+# commands/agenda.zsh - Forward-looking schedule view
+#
+# `agenda` surfaces in-window + overdue dated activity across all projects —
+# assignment due dates, exam dates, manuscript/grant deadlines, milestones, and
+# recurring blocks — grouped into OVERDUE / TODAY / THIS WEEK / LATER buckets.
+#
+# Driven entirely by the shared engine (lib/schedule.zsh). Works fully without
+# atlas and without yq (the teaching path is the only one needing yq). `agenda`
+# is a top-level command (auto-loaded), NOT a dispatcher: it is not subject to
+# the binary-precedence guard and not in _FLOW_HELP_FUNCTIONS.
+
+# ============================================================================
+# AGENDA COMMAND
+# ============================================================================
+
+agenda() {
+  local arg="${1:-}"
+  local window=$SCHEDULE_DEFAULT_WINDOW
+  local category=""
+  local overdue_only=0
+  local show_all=0
+
+  case "$arg" in
+    -h|--help|help)
+      _agenda_help
+      return 0
+      ;;
+    ""|-w|--week)
+      window=7
+      ;;
+    today)
+      window=0
+      ;;
+    -m|--month)
+      window=30
+      ;;
+    --all)
+      window=3650
+      show_all=1
+      ;;
+    --overdue)
+      overdue_only=1
+      window=0
+      ;;
+    dev|r|research|teach|quarto|apps)
+      category="$arg"
+      window=7
+      ;;
+    teaching)
+      category="teach"
+      window=7
+      ;;
+    *)
+      _flow_log_warning "Unknown agenda option: $arg"
+      echo ""
+      _agenda_help
+      return 1
+      ;;
+  esac
+
+  # Pipeline: collect -> window filter -> sort
+  local records
+  records=$(_schedule_collect "$window" "$category" | _schedule_filter_window "$window" | _schedule_sort)
+
+  # Holidays are noise unless explicitly requested (--all)
+  if (( ! show_all )) && [[ -n "$records" ]]; then
+    records=$(print -r -- "$records" | grep -v '|holiday|')
+  fi
+
+  # Bucketize (THIS WEEK vs LATER split on the fixed 7-day horizon)
+  local -a b_overdue=() b_today=() b_week=() b_later=()
+  local rec date class
+  if [[ -n "$records" ]]; then
+    while IFS= read -r rec; do
+      [[ -z "$rec" ]] && continue
+      date="${rec%%|*}"
+      class=$(_schedule_classify "$date" "$SCHEDULE_DEFAULT_WINDOW")
+      case "$class" in
+        overdue) b_overdue+=("$rec") ;;
+        today)   b_today+=("$rec") ;;
+        soon)    b_week+=("$rec") ;;
+        later)   b_later+=("$rec") ;;
+      esac
+    done <<< "$records"
+  fi
+
+  # --overdue narrows to the overdue bucket only
+  if (( overdue_only )); then
+    b_today=(); b_week=(); b_later=()
+  fi
+
+  local total=$(( ${#b_overdue[@]} + ${#b_today[@]} + ${#b_week[@]} + ${#b_later[@]} ))
+
+  # Header
+  echo ""
+  echo "  📅 ${FLOW_COLORS[bold]}AGENDA${FLOW_COLORS[reset]} ${FLOW_COLORS[muted]}$(_agenda_window_label "$window" "$category" "$overdue_only" "$show_all")${FLOW_COLORS[reset]}"
+  echo ""
+
+  # Calm empty state
+  if (( total == 0 )); then
+    echo "  ${FLOW_COLORS[success]}📅 Nothing scheduled — clear runway${FLOW_COLORS[reset]}"
+    echo ""
+    _flow_schedule_to_atlas
+    return 0
+  fi
+
+  _agenda_render_bucket "OVERDUE"   "${FLOW_COLORS[error]}"   b_overdue
+  _agenda_render_bucket "TODAY"     "${FLOW_COLORS[warning]}" b_today
+  _agenda_render_bucket "THIS WEEK" "${FLOW_COLORS[info]}"    b_week
+  _agenda_render_bucket "LATER"     "${FLOW_COLORS[muted]}"   b_later
+
+  echo "  ${FLOW_COLORS[muted]}$total item$( (( total != 1 )) && echo s ) • 'agenda -h' for options${FLOW_COLORS[reset]}"
+  echo ""
+
+  # Opportunistic atlas sync (async, no-op when atlas/schedule absent)
+  if [[ -n "$records" ]]; then
+    local -a all_records=("${(@f)records}")
+    _flow_schedule_to_atlas "${all_records[@]}"
+  fi
+}
+
+# ============================================================================
+# RENDER HELPERS
+# ============================================================================
+
+# Render one labeled bucket (skips empty buckets). $3 = name of a record array.
+_agenda_render_bucket() {
+  local title="$1" color="$2" arr_name="$3"
+  local -a items=("${(@P)arr_name}")
+  (( ${#items[@]} == 0 )) && return 0
+
+  echo "  ${color}${FLOW_COLORS[bold]}$title${FLOW_COLORS[reset]} ${FLOW_COLORS[muted]}(${#items[@]})${FLOW_COLORS[reset]}"
+  local rec
+  for rec in "${items[@]}"; do
+    _schedule_render_line "$rec"
+  done
+  echo ""
+}
+
+# Build the dim window/scope label shown beside the AGENDA header.
+_agenda_window_label() {
+  local window="$1" category="$2" overdue_only="$3" show_all="$4"
+  local label=""
+
+  if (( overdue_only )); then
+    label="overdue only"
+  elif (( show_all )); then
+    label="everything"
+  elif (( window == 0 )); then
+    label="today"
+  elif (( window == 7 )); then
+    label="next 7 days"
+  elif (( window == 30 )); then
+    label="next 30 days"
+  else
+    label="next ${window} days"
+  fi
+
+  [[ -n "$category" ]] && label="$label • $category"
+  echo "($label)"
+}
+
+# ============================================================================
+# ALIASES (avoid `ag` — collides with the silver-searcher binary)
+# ============================================================================
+
+agt() { agenda today "$@"; }
+agw() { agenda -w "$@"; }
+agm() { agenda -m "$@"; }
+
+# ============================================================================
+# HELP
+# ============================================================================
+
+_agenda_help() {
+  local _C_BOLD="${_C_BOLD:-\033[1m}"
+  local _C_NC="${_C_NC:-\033[0m}"
+  local _C_GREEN="${_C_GREEN:-\033[0;32m}"
+  local _C_CYAN="${_C_CYAN:-\033[0;36m}"
+  local _C_BLUE="${_C_BLUE:-\033[0;34m}"
+  local _C_YELLOW="${_C_YELLOW:-\033[0;33m}"
+  local _C_DIM="${_C_DIM:-\033[2m}"
+
+  echo -e "
+${_C_BOLD}╭─────────────────────────────────────────────╮${_C_NC}
+${_C_BOLD}│ 📅 AGENDA - Forward-Looking Schedule        │${_C_NC}
+${_C_BOLD}╰─────────────────────────────────────────────╯${_C_NC}
+
+${_C_BOLD}Usage:${_C_NC} agenda [window | category | --overdue | --all]
+
+${_C_GREEN}🔥 MOST COMMON${_C_NC} ${_C_DIM}(80% of daily use)${_C_NC}:
+  ${_C_CYAN}agenda${_C_NC}            Next 7 days + overdue (default)
+  ${_C_CYAN}agenda today${_C_NC}      Due today + overdue
+  ${_C_CYAN}agenda --overdue${_C_NC}  Overdue items only
+
+${_C_YELLOW}💡 QUICK EXAMPLES${_C_NC}:
+  ${_C_DIM}\$${_C_NC} agenda                 ${_C_DIM}# This week's dated items${_C_NC}
+  ${_C_DIM}\$${_C_NC} agenda -m              ${_C_DIM}# Next 30 days (adds LATER)${_C_NC}
+  ${_C_DIM}\$${_C_NC} agenda research        ${_C_DIM}# Filter by category${_C_NC}
+  ${_C_DIM}\$${_C_NC} agenda --all           ${_C_DIM}# Everything, incl. holidays${_C_NC}
+
+${_C_BLUE}📋 WINDOWS${_C_NC}:
+  ${_C_CYAN}(none)${_C_NC}, ${_C_CYAN}-w${_C_NC}, ${_C_CYAN}--week${_C_NC}    Next 7 days (default)
+  ${_C_CYAN}today${_C_NC}             Today only (+ overdue)
+  ${_C_CYAN}-m${_C_NC}, ${_C_CYAN}--month${_C_NC}        Next 30 days
+  ${_C_CYAN}--all${_C_NC}             No window cap; includes holidays
+  ${_C_CYAN}--overdue${_C_NC}         Overdue items only
+  ${_C_CYAN}-h${_C_NC}, ${_C_CYAN}--help${_C_NC}         Show this help
+
+${_C_BLUE}📂 CATEGORIES${_C_NC}:
+  ${_C_CYAN}dev  r  research  teach  quarto  apps${_C_NC}
+
+${_C_BLUE}⚡ ALIASES${_C_NC}:
+  ${_C_CYAN}agt${_C_NC} = agenda today   ${_C_CYAN}agw${_C_NC} = agenda -w   ${_C_CYAN}agm${_C_NC} = agenda -m
+
+${_C_BLUE}📝 ADDING ITEMS${_C_NC} ${_C_DIM}(per-project .STATUS)${_C_NC}:
+  ${_C_DIM}## Schedule:${_C_NC}
+  ${_C_DIM}- 2026-06-20 | Submit JRSS-B revision | research${_C_NC}
+  ${_C_DIM}- weekly:fri | Grading window | recurring${_C_NC}
+  ${_C_DIM}Teaching dates derive from .flow/teach-config.yml automatically.${_C_NC}
+
+${_C_BLUE}🎨 ICONS${_C_NC}:
+  🎓 teaching   🔬 research   📌 general   🔁 recurring   🏖️ holiday
+
+${_C_DIM}See also:${_C_NC} dash help, morning, today, week
+"
+}
diff --git a/lib/schedule.zsh b/lib/schedule.zsh
index 8b5869ec9..1207c615b 100644
--- a/lib/schedule.zsh
+++ b/lib/schedule.zsh
@@ -449,8 +449,10 @@ _schedule_render_line() {
   esac
 
   local ticon=$(_schedule_type_icon "$typ")
+  # Trailing 🔁 flags recurrence for non-recurring TYPES (e.g. a research
+  # weekly block); skip it when the type icon is already 🔁 to avoid doubling.
   local rmark=""
-  [[ -n "$recurrence" && "$recurrence" != "none" ]] && rmark=" 🔁"
+  [[ -n "$recurrence" && "$recurrence" != "none" && "$typ" != "recurring" ]] && rmark=" 🔁"
 
   printf "  %s ${color}%-11s${FLOW_COLORS[reset]} %s%s ${FLOW_COLORS[muted]}(%s)${FLOW_COLORS[reset]}\n" \
     "$ticon" "$rel" "$label" "$rmark" "$project"
diff --git a/tests/test-agenda.zsh b/tests/test-agenda.zsh
new file mode 100644
index 000000000..0b3616b39
--- /dev/null
+++ b/tests/test-agenda.zsh
@@ -0,0 +1,292 @@
+#!/usr/bin/env zsh
+# Test script for the agenda command (commands/agenda.zsh)
+# Tests: help, windows (default/today/-m), --overdue, category filter,
+#        --all, calm empty state, aliases, atlas-disabled isolation.
+
+# ============================================================================
+# FRAMEWORK
+# ============================================================================
+
+SCRIPT_DIR="${0:A:h}"
+PROJECT_ROOT="${SCRIPT_DIR:h}"
+source "$SCRIPT_DIR/test-framework.zsh" || { echo "ERROR: Cannot source test-framework.zsh"; exit 1 }
+
+# ============================================================================
+# SETUP
+# ============================================================================
+
+setup() {
+    if [[ ! -f "$PROJECT_ROOT/flow.plugin.zsh" ]]; then
+        echo "${RED}ERROR: Cannot find project root${RESET}"
+        exit 1
+    fi
+
+    FLOW_QUIET=1
+    FLOW_ATLAS_ENABLED=no
+    FLOW_PLUGIN_DIR="$PROJECT_ROOT"
+    FLOW_SCHEDULE_NO_CACHE=1
+    source "$PROJECT_ROOT/flow.plugin.zsh" 2>/dev/null || {
+        echo "${RED}Plugin failed to load${RESET}"
+        exit 1
+    }
+    exec < /dev/null
+
+    zmodload zsh/datetime 2>/dev/null
+    TODAY=$(strftime '%Y-%m-%d' $EPOCHSECONDS)
+
+    # Isolated project root: a research project with dated + recurring items
+    TEST_ROOT=$(mktemp -d)
+    FLOW_PROJECTS_ROOT="$TEST_ROOT"
+    mkdir -p "$TEST_ROOT/research/study-x" "$TEST_ROOT/dev-tools/tool-y"
+
+    {
+        echo "## Status: active"
+        echo ""
+        echo "## Schedule:"
+        echo "- $(_date_add_days "$TODAY" -3) | Overdue paper review | research"
+        echo "- $TODAY | Standup notes | general"
+        echo "- $(_date_add_days "$TODAY" 2) | Submit revision | research"
+        echo "- $(_date_add_days "$TODAY" 15) | Beta milestone | general"
+        echo "- weekly:fri | Grading window | recurring"
+    } > "$TEST_ROOT/research/study-x/.STATUS"
+
+    {
+        echo "## Status: active"
+        echo ""
+        echo "## Schedule:"
+        echo "- $(_date_add_days "$TODAY" 1) | Ship v2 | general"
+    } > "$TEST_ROOT/dev-tools/tool-y/.STATUS"
+
+    # An empty project root for the empty-state test
+    EMPTY_ROOT=$(mktemp -d)
+}
+
+cleanup() {
+    reset_mocks
+    [[ -d "$TEST_ROOT" ]] && rm -rf "$TEST_ROOT"
+    [[ -d "$EMPTY_ROOT" ]] && rm -rf "$EMPTY_ROOT"
+}
+trap cleanup EXIT
+
+# ============================================================================
+# TESTS: existence + help
+# ============================================================================
+
+test_agenda_exists() {
+    test_case "agenda command exists"
+    assert_function_exists "agenda" && test_pass
+}
+
+test_agenda_help_exists() {
+    test_case "_agenda_help function exists"
+    assert_function_exists "_agenda_help" && test_pass
+}
+
+test_agenda_aliases_exist() {
+    test_case "agt/agw/agm alias functions exist"
+    assert_function_exists "agt" && \
+    assert_function_exists "agw" && \
+    assert_function_exists "agm" && test_pass
+}
+
+test_agenda_help_runs() {
+    test_case "agenda -h runs and shows usage"
+    local output=$(agenda -h 2>&1)
+    assert_exit_code $? 0 "agenda -h should exit 0"
+    assert_contains "$output" "AGENDA" "help shows title" && \
+    assert_contains "$output" "today" "help mentions today window" && \
+    assert_contains "$output" "--overdue" "help mentions --overdue" && test_pass
+}
+
+test_agenda_help_flag() {
+    test_case "agenda --help works"
+    local output=$(agenda --help 2>&1)
+    assert_contains "$output" "AGENDA" && test_pass
+}
+
+# ============================================================================
+# TESTS: default window + buckets
+# ============================================================================
+
+test_agenda_default_runs() {
+    test_case "agenda (default) runs without error"
+    local output=$(agenda 2>&1)
+    assert_exit_code $? 0 "agenda should exit 0"
+    assert_not_contains "$output" "command not found" && test_pass
+}
+
+test_agenda_default_buckets() {
+    test_case "agenda shows OVERDUE / TODAY / THIS WEEK buckets"
+    local output=$(agenda 2>&1)
+    assert_contains "$output" "OVERDUE" "overdue bucket" && \
+    assert_contains "$output" "TODAY" "today bucket" && \
+    assert_contains "$output" "THIS WEEK" "this-week bucket" && test_pass
+}
+
+test_agenda_default_items() {
+    test_case "agenda default lists in-window items, excludes 15d item"
+    local output=$(agenda 2>&1)
+    assert_contains "$output" "Overdue paper review" "overdue item" && \
+    assert_contains "$output" "Submit revision" "soon item" && \
+    assert_not_contains "$output" "Beta milestone" "15d item excluded at 7d" && test_pass
+}
+
+test_agenda_no_errors() {
+    test_case "agenda output has no error patterns"
+    local output=$(agenda 2>&1)
+    assert_not_contains "$output" "command not found" && \
+    assert_not_contains "$output" "parse error" && \
+    assert_not_contains "$output" "no such" && test_pass
+}
+
+# ============================================================================
+# TESTS: --overdue
+# ============================================================================
+
+test_agenda_overdue() {
+    test_case "agenda --overdue shows only overdue items"
+    local output=$(agenda --overdue 2>&1)
+    assert_contains "$output" "Overdue paper review" "overdue present" && \
+    assert_not_contains "$output" "Submit revision" "soon item excluded" && \
+    assert_not_contains "$output" "Standup notes" "today item excluded" && test_pass
+}
+
+# ============================================================================
+# TESTS: month window vs today window
+# ============================================================================
+
+test_agenda_month_has_later() {
+    test_case "agenda -m includes the LATER bucket + 15d item"
+    local output=$(agenda -m 2>&1)
+    assert_contains "$output" "LATER" "later bucket present" && \
+    assert_contains "$output" "Beta milestone" "15d item now in range" && test_pass
+}
+
+test_agenda_today_window() {
+    test_case "agenda today shows today + overdue only"
+    local output=$(agenda today 2>&1)
+    assert_contains "$output" "Standup notes" "today item" && \
+    assert_contains "$output" "Overdue paper review" "overdue item" && \
+    assert_not_contains "$output" "Submit revision" "future item excluded" && test_pass
+}
+
+# ============================================================================
+# TESTS: category filter
+# ============================================================================
+
+test_agenda_category_filter() {
+    test_case "agenda research filters to research project"
+    local output=$(agenda research 2>&1)
+    assert_contains "$output" "Submit revision" "research item present" && \
+    assert_not_contains "$output" "Ship v2" "dev item excluded" && test_pass
+}
+
+# ============================================================================
+# TESTS: empty state
+# ============================================================================
+
+test_agenda_empty_state() {
+    test_case "agenda shows calm empty state when nothing scheduled"
+    local saved="$FLOW_PROJECTS_ROOT"
+    FLOW_PROJECTS_ROOT="$EMPTY_ROOT"
+    local output=$(agenda 2>&1)
+    FLOW_PROJECTS_ROOT="$saved"
+    assert_contains "$output" "Nothing scheduled" "calm empty state" && test_pass
+}
+
+test_agenda_empty_category() {
+    test_case "agenda apps (no apps projects) -> empty state"
+    local output=$(agenda apps 2>&1)
+    assert_contains "$output" "Nothing scheduled" && test_pass
+}
+
+# ============================================================================
+# TESTS: unknown option
+# ============================================================================
+
+test_agenda_unknown_option() {
+    test_case "agenda <bogus> warns and shows help"
+    local output=$(agenda --bogus 2>&1)
+    assert_contains "$output" "Unknown" "warns on unknown option" && test_pass
+}
+
+# ============================================================================
+# TESTS: isolation (run_isolated, atlas disabled)
+# ============================================================================
+
+test_agenda_isolated() {
+    test_case "agenda runs cleanly under run_isolated (atlas disabled)"
+    _agenda_isolated_body() {
+        FLOW_SCHEDULE_NO_CACHE=1
+        local r=$(mktemp -d)
+        export FLOW_PROJECTS_ROOT="$r"
+        mkdir -p "$r/research/p"
+        zmodload zsh/datetime 2>/dev/null
+        local t=$(strftime '%Y-%m-%d' $EPOCHSECONDS)
+        {
+            echo "## Status: active"
+            echo "## Schedule:"
+            echo "- $t | Iso item | research"
+        } > "$r/research/p/.STATUS"
+        local out=$(agenda 2>&1)
+        rm -rf "$r"
+        [[ "$out" == *"Iso item"* ]] || { echo "missing Iso item: $out"; return 1; }
+        return 0
+    }
+    run_isolated _agenda_isolated_body && test_pass
+}
+
+# ============================================================================
+# RUN TESTS
+# ============================================================================
+
+main() {
+    test_suite_start "Agenda Command Tests"
+    setup
+
+    echo "${CYAN}--- Existence + help ---${RESET}"
+    test_agenda_exists
+    test_agenda_help_exists
+    test_agenda_aliases_exist
+    test_agenda_help_runs
+    test_agenda_help_flag
+
+    echo ""
+    echo "${CYAN}--- Default window + buckets ---${RESET}"
+    test_agenda_default_runs
+    test_agenda_default_buckets
+    test_agenda_default_items
+    test_agenda_no_errors
+
+    echo ""
+    echo "${CYAN}--- Overdue ---${RESET}"
+    test_agenda_overdue
+
+    echo ""
+    echo "${CYAN}--- Month / today windows ---${RESET}"
+    test_agenda_month_has_later
+    test_agenda_today_window
+
+    echo ""
+    echo "${CYAN}--- Category filter ---${RESET}"
+    test_agenda_category_filter
+
+    echo ""
+    echo "${CYAN}--- Empty state ---${RESET}"
+    test_agenda_empty_state
+    test_agenda_empty_category
+
+    echo ""
+    echo "${CYAN}--- Unknown option ---${RESET}"
+    test_agenda_unknown_option
+
+    echo ""
+    echo "${CYAN}--- Isolation ---${RESET}"
+    test_agenda_isolated
+
+    cleanup
+    test_suite_end
+    exit $?
+}
+
+main "$@"
diff --git a/tests/test-schedule.zsh b/tests/test-schedule.zsh
index b1fc2d089..3aa3b191e 100644
--- a/tests/test-schedule.zsh
+++ b/tests/test-schedule.zsh
@@ -286,9 +286,11 @@ test_render_line() {
 }
 
 test_render_line_recurring_mark() {
-    test_case "render_line marks recurring items"
-    local out=$(_schedule_render_line "${TODAY}|Standup|recurring|myproj|weekly:mon|status")
-    assert_contains "$out" "🔁" "recurrence marker" && test_pass
+    test_case "render_line flags recurrence for a non-recurring type"
+    # A research weekly block keeps its 🔬 type icon + a trailing 🔁 marker.
+    local out=$(_schedule_render_line "${TODAY}|Advisor meeting|research|myproj|weekly:mon|status")
+    assert_contains "$out" "🔬" "type icon preserved" && \
+    assert_contains "$out" "🔁" "recurrence marker present" && test_pass
 }
 
 # ============================================================================

From 6b11627664bb7a09480480e4c0b836ac7ca727aa Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sat, 13 Jun 2026 20:11:20 +0000
Subject: [PATCH 04/15] feat(dash): add UPCOMING section driven by the schedule
 engine
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Insert _dash_upcoming in dash() after QUICK WINS and before QUICK ACCESS.
It renders the next few dated items (7-day window + overdue) via the
shared engine (_schedule_collect | _schedule_filter_window | _schedule_sort),
caps at 4 with a "+N more — run 'agenda'" hint, filters holidays, and
self-suppresses when nothing is due. Reuses _schedule_collect's session
cache so it shares work with `agenda` and the morning cadence. Degrades
silently if the engine isn't loaded.

Extend tests/test-dash.zsh: a scheduled item in the fixture, asserts the
UPCOMING header + item render, and that the section self-suppresses on an
empty schedule. Also isolate FLOW_DATA_DIR in setup so the dashboard never
reads the real worklog (leaked session counts otherwise hit a latent
_dash_right_now arithmetic path that truncates output before UPCOMING).

Verified: test-dash 29/29.

https://claude.ai/code/session_014YpEdtSqYMRdcuoMQFgLXW
---
 commands/dash.zsh   | 36 ++++++++++++++++++++++++++++++
 tests/test-dash.zsh | 53 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 89 insertions(+)

diff --git a/commands/dash.zsh b/commands/dash.zsh
index fc326a79f..02c7a8970 100644
--- a/commands/dash.zsh
+++ b/commands/dash.zsh
@@ -78,6 +78,7 @@ dash() {
   _dash_current
   _dash_dotfiles
   _dash_quick_wins
+  _dash_upcoming
   _dash_quick_access
   _dash_recent_wins
 
@@ -411,6 +412,41 @@ _dash_quick_wins() {
   echo ""
 }
 
+# ============================================================================
+# UPCOMING - Forward-looking dated items (v7.10.0)
+# ============================================================================
+
+# Shows the next few dated items (7-day window + overdue) from the shared
+# schedule engine. Sits after QUICK WINS, before QUICK ACCESS. Self-suppresses
+# when nothing is due. Reuses _schedule_collect's session cache, so it shares
+# work with `agenda` and the morning cadence within a session.
+_dash_upcoming() {
+  # Engine may be absent in minimal sources; degrade silently.
+  typeset -f _schedule_collect >/dev/null 2>&1 || return 0
+
+  local records
+  records=$(_schedule_collect "$SCHEDULE_DEFAULT_WINDOW" | _schedule_filter_window "$SCHEDULE_DEFAULT_WINDOW" | _schedule_sort)
+  [[ -n "$records" ]] && records=$(print -r -- "$records" | grep -v '|holiday|')
+  [[ -z "$records" ]] && return 0
+
+  echo "  📅 ${FLOW_COLORS[bold]}UPCOMING${FLOW_COLORS[reset]} ${FLOW_COLORS[muted]}(next 7 days)${FLOW_COLORS[reset]}"
+
+  local count=0 max=4 rec
+  while IFS= read -r rec; do
+    [[ -z "$rec" ]] && continue
+    (( count >= max )) && break
+    _schedule_render_line "$rec"
+    ((count++))
+  done <<< "$records"
+
+  local total=$(print -r -- "$records" | grep -c .)
+  if (( total > max )); then
+    echo "  ${FLOW_COLORS[muted]}  +$((total - max)) more — run 'agenda' for the full view${FLOW_COLORS[reset]}"
+  fi
+
+  echo ""
+}
+
 # Get urgency level from .STATUS
 _dash_get_urgency() {
   local status_file="$1"
diff --git a/tests/test-dash.zsh b/tests/test-dash.zsh
index db179eed8..a72d43d6f 100644
--- a/tests/test-dash.zsh
+++ b/tests/test-dash.zsh
@@ -34,6 +34,11 @@ setup() {
     # Close stdin to prevent any interactive commands from blocking
     exec < /dev/null
 
+    # Isolate FLOW_DATA_DIR so the dashboard never reads the real worklog
+    # (leaked session counts hit a latent _dash_right_now arithmetic path and
+    # truncate output before the UPCOMING section renders).
+    export FLOW_DATA_DIR=$(mktemp -d)
+
     # Create isolated test project root (avoids scanning real ~/projects)
     TEST_ROOT=$(mktemp -d)
     mkdir -p "$TEST_ROOT/dev-tools/mock-dev" "$TEST_ROOT/apps/test-app" \
@@ -44,7 +49,19 @@ setup() {
                "$TEST_ROOT"/research/mock-study "$TEST_ROOT"/quarto/mock-site; do
         echo "## Status: active\n## Progress: 50" > "$dir/.STATUS"
     done
+
+    # Give one project a ## Schedule: block so UPCOMING has something to show
+    zmodload zsh/datetime 2>/dev/null
+    local td=$(strftime '%Y-%m-%d' $EPOCHSECONDS)
+    {
+        echo "## Status: active"
+        echo "## Progress: 50"
+        echo "## Schedule:"
+        echo "- $(_date_add_days "$td" 2) | Dash upcoming probe | research"
+    } > "$TEST_ROOT/research/mock-study/.STATUS"
+
     FLOW_PROJECTS_ROOT="$TEST_ROOT"
+    FLOW_SCHEDULE_NO_CACHE=1
 }
 
 # ============================================================================
@@ -54,6 +71,7 @@ setup() {
 cleanup() {
     reset_mocks
     [[ -d "$TEST_ROOT" ]] && rm -rf "$TEST_ROOT"
+    [[ -n "$FLOW_DATA_DIR" && -d "$FLOW_DATA_DIR" ]] && rm -rf "$FLOW_DATA_DIR"
 }
 trap cleanup EXIT
 
@@ -256,6 +274,35 @@ test_dash_interactive_function() {
     assert_function_exists "_dash_interactive" && test_pass
 }
 
+# ============================================================================
+# TESTS: UPCOMING section (schedule integration)
+# ============================================================================
+
+test_dash_upcoming_function() {
+    test_case "_dash_upcoming function exists"
+    assert_function_exists "_dash_upcoming" && test_pass
+}
+
+test_dash_upcoming_shows_items() {
+    test_case "dash shows UPCOMING section with dated item"
+    local output=$(dash 2>&1)
+    assert_contains "$output" "UPCOMING" "UPCOMING header present" && \
+    assert_contains "$output" "Dash upcoming probe" "scheduled item rendered" && test_pass
+}
+
+test_dash_upcoming_self_suppresses() {
+    test_case "UPCOMING self-suppresses when nothing scheduled"
+    local empty=$(mktemp -d)
+    mkdir -p "$empty/dev-tools/none"
+    echo "## Status: active" > "$empty/dev-tools/none/.STATUS"
+    local saved="$FLOW_PROJECTS_ROOT"
+    FLOW_PROJECTS_ROOT="$empty"
+    local output=$(dash 2>&1)
+    FLOW_PROJECTS_ROOT="$saved"
+    rm -rf "$empty"
+    assert_not_contains "$output" "UPCOMING" "no UPCOMING header when empty" && test_pass
+}
+
 # ============================================================================
 # RUN TESTS
 # ============================================================================
@@ -311,6 +358,12 @@ main() {
     test_dash_categories_function
     test_dash_interactive_function
 
+    echo ""
+    echo "${CYAN}--- UPCOMING section tests ---${RESET}"
+    test_dash_upcoming_function
+    test_dash_upcoming_shows_items
+    test_dash_upcoming_self_suppresses
+
     # Cleanup and summary
     cleanup
     test_suite_end

From e9f8c1219d03c749a33c3d084e5570449e90bb02 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sat, 13 Jun 2026 20:13:47 +0000
Subject: [PATCH 05/15] feat(morning): dated enrichment for morning/today/week
 cadence
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Wire the schedule engine into the daily/weekly cadence:

- morning: _flow_morning_agenda shows the next 5 dated items (7d + overdue)
  between the projects summary and yesterday's wins; self-suppresses when
  nothing is due. morning -q gains a "📅 N due soon" one-liner
  (_flow_agenda_count).
- today: _flow_today_agenda shows a "📅 Due today" block (window 0 → today
  + overdue).
- week: _flow_week_agenda shows "📅 This week's deadlines" (7d), grouped by
  weekday with an Overdue group first.

All blocks reuse _schedule_render_line for visual consistency and the
_schedule_collect session cache. Register test-schedule, test-agenda, and
the new test-cadence-agenda (6/6) in run-all.sh.

Verified: test-cadence-agenda 6/6; source flow.plugin.zsh clean.

https://claude.ai/code/session_014YpEdtSqYMRdcuoMQFgLXW
---
 commands/morning.zsh          | 114 +++++++++++++++++++++++--
 tests/run-all.sh              |   3 +
 tests/test-cadence-agenda.zsh | 152 ++++++++++++++++++++++++++++++++++
 3 files changed, 263 insertions(+), 6 deletions(-)
 create mode 100644 tests/test-cadence-agenda.zsh

diff --git a/commands/morning.zsh b/commands/morning.zsh
index 8ae748ce0..e3eb67ac5 100644
--- a/commands/morning.zsh
+++ b/commands/morning.zsh
@@ -25,11 +25,14 @@ morning() {
   
   # 2. Show active projects summary
   _flow_morning_projects
-  
-  # 3. Show today's wins (if any from yesterday)
+
+  # 3. Show upcoming dated items (7-day window + overdue)
+  _flow_morning_agenda
+
+  # 4. Show today's wins (if any from yesterday)
   _flow_morning_wins
   
-  # 4. Suggest what to work on
+  # 5. Suggest what to work on
   _flow_morning_suggest
   
   echo ""
@@ -98,6 +101,43 @@ _flow_morning_projects() {
   fi
 }
 
+# Upcoming dated items for the morning routine (top 5, 7-day window + overdue).
+# Self-suppresses when nothing is due. Driven by the shared schedule engine.
+_flow_morning_agenda() {
+  typeset -f _schedule_collect >/dev/null 2>&1 || return 0
+
+  local records
+  records=$(_schedule_collect 7 | _schedule_filter_window 7 | _schedule_sort)
+  [[ -n "$records" ]] && records=$(print -r -- "$records" | grep -v '|holiday|')
+  [[ -z "$records" ]] && return 0
+
+  echo ""
+  echo "  ${FLOW_COLORS[muted]}Upcoming (next 7 days):${FLOW_COLORS[reset]}"
+
+  local count=0 rec
+  while IFS= read -r rec; do
+    [[ -z "$rec" ]] && continue
+    (( count >= 5 )) && break
+    _schedule_render_line "$rec"
+    ((count++))
+  done <<< "$records"
+
+  local total=$(print -r -- "$records" | grep -c .)
+  if (( total > 5 )); then
+    echo "  ${FLOW_COLORS[muted]}  +$((total - 5)) more — run 'agenda'${FLOW_COLORS[reset]}"
+  fi
+}
+
+# Count of in-window (7d + overdue) dated items, for the quick one-liner.
+_flow_agenda_count() {
+  typeset -f _schedule_collect >/dev/null 2>&1 || { echo 0; return 0; }
+  local records
+  records=$(_schedule_collect 7 | _schedule_filter_window 7)
+  [[ -n "$records" ]] && records=$(print -r -- "$records" | grep -v '|holiday|')
+  [[ -z "$records" ]] && { echo 0; return 0; }
+  print -r -- "$records" | grep -c .
+}
+
 _flow_morning_wins() {
   local wins_file="${FLOW_DATA_DIR}/wins.md"
   
@@ -160,7 +200,12 @@ _flow_morning_quick() {
     active=$(_flow_list_projects "active" 2>/dev/null | wc -l | tr -d ' ')
   fi
   
-  echo "  📥 $inbox inbox  │  📂 $active active projects"
+  local due=$(_flow_agenda_count)
+  if (( due > 0 )); then
+    echo "  📥 $inbox inbox  │  📂 $active active projects  │  📅 $due due soon"
+  else
+    echo "  📥 $inbox inbox  │  📂 $active active projects"
+  fi
   echo ""
   echo "  ${FLOW_COLORS[accent]}→ js${FLOW_COLORS[reset]} to start working"
 }
@@ -198,13 +243,34 @@ today() {
     fi
   fi
   
+  # Show what's due today (+ overdue)
+  _flow_today_agenda
+
   # Show active work
   _flow_morning_projects
   echo ""
 }
 
+# Dated items due today plus anything overdue (window 0). Self-suppresses.
+_flow_today_agenda() {
+  typeset -f _schedule_collect >/dev/null 2>&1 || return 0
+
+  local records
+  records=$(_schedule_collect 0 | _schedule_filter_window 0 | _schedule_sort)
+  [[ -n "$records" ]] && records=$(print -r -- "$records" | grep -v '|holiday|')
+  [[ -z "$records" ]] && return 0
+
+  echo "  ${FLOW_COLORS[warning]}📅 Due today${FLOW_COLORS[reset]}"
+  local rec
+  while IFS= read -r rec; do
+    [[ -z "$rec" ]] && continue
+    _schedule_render_line "$rec"
+  done <<< "$records"
+  echo ""
+}
+
 # ============================================================================
-# WEEK COMMAND - Weekly review helper  
+# WEEK COMMAND - Weekly review helper
 # ============================================================================
 
 week() {
@@ -213,13 +279,16 @@ week() {
   echo "${FLOW_COLORS[muted]}Week of $(date '+%B %d, %Y')${FLOW_COLORS[reset]}"
   echo ""
   
+  # This week's deadlines (7-day window, grouped by weekday)
+  _flow_week_agenda
+
   # Session stats
   if _flow_has_atlas; then
     echo "  ${FLOW_COLORS[accent]}Sessions this week:${FLOW_COLORS[reset]}"
     _flow_atlas trail --days=7 2>/dev/null | head -10
     echo ""
   fi
-  
+
   # Wins this week
   local wins_file="${FLOW_DATA_DIR}/wins.md"
   if [[ -f "$wins_file" ]]; then
@@ -235,6 +304,39 @@ week() {
   echo ""
 }
 
+# This week's dated items (7-day window + overdue), grouped by weekday.
+# Self-suppresses when nothing is due.
+_flow_week_agenda() {
+  typeset -f _schedule_collect >/dev/null 2>&1 || return 0
+
+  local records
+  records=$(_schedule_collect 7 | _schedule_filter_window 7 | _schedule_sort)
+  [[ -n "$records" ]] && records=$(print -r -- "$records" | grep -v '|holiday|')
+  [[ -z "$records" ]] && return 0
+
+  echo "  ${FLOW_COLORS[accent]}📅 This week's deadlines:${FLOW_COLORS[reset]}"
+
+  zmodload zsh/datetime 2>/dev/null
+  local rec date last_day day_label
+  while IFS= read -r rec; do
+    [[ -z "$rec" ]] && continue
+    date="${rec%%|*}"
+    # Weekday header (printed once per day); overdue items grouped under "Overdue"
+    if [[ "$date" < "$(strftime '%Y-%m-%d' $EPOCHSECONDS)" ]]; then
+      day_label="Overdue"
+    else
+      local e=$(strftime -r '%Y-%m-%d %H:%M:%S' "$date 12:00:00" 2>/dev/null)
+      day_label=$(strftime '%A' "$e" 2>/dev/null)
+    fi
+    if [[ "$day_label" != "$last_day" ]]; then
+      echo "     ${FLOW_COLORS[muted]}${day_label}:${FLOW_COLORS[reset]}"
+      last_day="$day_label"
+    fi
+    _schedule_render_line "$rec"
+  done <<< "$records"
+  echo ""
+}
+
 # ============================================================================
 # ALIASES
 # ============================================================================
diff --git a/tests/run-all.sh b/tests/run-all.sh
index 4ce503140..0832d5dd0 100755
--- a/tests/run-all.sh
+++ b/tests/run-all.sh
@@ -74,6 +74,9 @@ echo "Core command tests:"
 # These tests source flow.plugin.zsh in non-interactive mode
 # (FLOW_PLUGIN_DIR, FLOW_QUIET, FLOW_ATLAS_ENABLED=no, exec < /dev/null)
 run_test ./tests/test-dash.zsh
+run_test ./tests/test-schedule.zsh
+run_test ./tests/test-agenda.zsh
+run_test ./tests/test-cadence-agenda.zsh
 run_test ./tests/test-work.zsh
 run_test ./tests/test-doctor.zsh 45
 run_test ./tests/test-capture.zsh
diff --git a/tests/test-cadence-agenda.zsh b/tests/test-cadence-agenda.zsh
new file mode 100644
index 000000000..e3c7bbf78
--- /dev/null
+++ b/tests/test-cadence-agenda.zsh
@@ -0,0 +1,152 @@
+#!/usr/bin/env zsh
+# Test script for schedule enrichment of the daily/weekly cadence commands
+# (commands/morning.zsh): morning, morning -q, today, week.
+
+# ============================================================================
+# FRAMEWORK
+# ============================================================================
+
+SCRIPT_DIR="${0:A:h}"
+PROJECT_ROOT="${SCRIPT_DIR:h}"
+source "$SCRIPT_DIR/test-framework.zsh" || { echo "ERROR: Cannot source test-framework.zsh"; exit 1 }
+
+# ============================================================================
+# SETUP
+# ============================================================================
+
+setup() {
+    FLOW_QUIET=1
+    FLOW_ATLAS_ENABLED=no
+    FLOW_PLUGIN_DIR="$PROJECT_ROOT"
+    FLOW_SCHEDULE_NO_CACHE=1
+    source "$PROJECT_ROOT/flow.plugin.zsh" 2>/dev/null || {
+        echo "${RED}Plugin failed to load${RESET}"
+        exit 1
+    }
+    exec < /dev/null
+
+    # Isolate data dir (worklog) to keep dashboard/cadence output deterministic
+    export FLOW_DATA_DIR=$(mktemp -d)
+
+    zmodload zsh/datetime 2>/dev/null
+    TODAY=$(strftime '%Y-%m-%d' $EPOCHSECONDS)
+
+    TEST_ROOT=$(mktemp -d)
+    FLOW_PROJECTS_ROOT="$TEST_ROOT"
+    mkdir -p "$TEST_ROOT/research/study-x"
+    {
+        echo "## Status: active"
+        echo "## Schedule:"
+        echo "- $(_date_add_days "$TODAY" -2) | Late paper | research"
+        echo "- $TODAY | Daily standup | general"
+        echo "- $(_date_add_days "$TODAY" 3) | Submit revision | research"
+    } > "$TEST_ROOT/research/study-x/.STATUS"
+
+    EMPTY_ROOT=$(mktemp -d)
+    mkdir -p "$EMPTY_ROOT/research/none"
+    echo "## Status: active" > "$EMPTY_ROOT/research/none/.STATUS"
+}
+
+cleanup() {
+    reset_mocks
+    [[ -d "$TEST_ROOT" ]] && rm -rf "$TEST_ROOT"
+    [[ -d "$EMPTY_ROOT" ]] && rm -rf "$EMPTY_ROOT"
+    [[ -n "$FLOW_DATA_DIR" && -d "$FLOW_DATA_DIR" ]] && rm -rf "$FLOW_DATA_DIR"
+}
+trap cleanup EXIT
+
+# ============================================================================
+# TESTS: function existence
+# ============================================================================
+
+test_cadence_functions_exist() {
+    test_case "cadence agenda helpers exist"
+    assert_function_exists "_flow_morning_agenda" && \
+    assert_function_exists "_flow_today_agenda" && \
+    assert_function_exists "_flow_week_agenda" && \
+    assert_function_exists "_flow_agenda_count" && test_pass
+}
+
+# ============================================================================
+# TESTS: morning
+# ============================================================================
+
+test_morning_shows_upcoming() {
+    test_case "morning shows the Upcoming block with dated items"
+    local out=$(morning 2>&1)
+    assert_contains "$out" "Upcoming" "upcoming header" && \
+    assert_contains "$out" "Late paper" "overdue item" && \
+    assert_contains "$out" "Submit revision" "soon item" && test_pass
+}
+
+test_morning_upcoming_suppresses() {
+    test_case "morning Upcoming self-suppresses when nothing due"
+    local saved="$FLOW_PROJECTS_ROOT"
+    FLOW_PROJECTS_ROOT="$EMPTY_ROOT"
+    local out=$(morning 2>&1)
+    FLOW_PROJECTS_ROOT="$saved"
+    assert_not_contains "$out" "Upcoming (next 7 days)" "no upcoming block" && test_pass
+}
+
+test_morning_quick_oneliner() {
+    test_case "morning -q shows 'due soon' count"
+    local out=$(morning -q 2>&1)
+    assert_contains "$out" "due soon" "quick one-liner shows due count" && test_pass
+}
+
+# ============================================================================
+# TESTS: today
+# ============================================================================
+
+test_today_due_today() {
+    test_case "today shows 'Due today' with today + overdue items"
+    local out=$(today 2>&1)
+    assert_contains "$out" "Due today" "due-today header" && \
+    assert_contains "$out" "Daily standup" "today item" && \
+    assert_contains "$out" "Late paper" "overdue item" && \
+    assert_not_contains "$out" "Submit revision" "future item excluded" && test_pass
+}
+
+# ============================================================================
+# TESTS: week
+# ============================================================================
+
+test_week_deadlines() {
+    test_case "week shows 'This week's deadlines' grouped by weekday"
+    local out=$(week 2>&1)
+    assert_contains "$out" "This week's deadlines" "deadlines header" && \
+    assert_contains "$out" "Overdue:" "overdue group label" && \
+    assert_contains "$out" "Submit revision" "in-window item" && test_pass
+}
+
+# ============================================================================
+# RUN TESTS
+# ============================================================================
+
+main() {
+    test_suite_start "Cadence Agenda Enrichment Tests"
+    setup
+
+    echo "${CYAN}--- Function existence ---${RESET}"
+    test_cadence_functions_exist
+
+    echo ""
+    echo "${CYAN}--- morning ---${RESET}"
+    test_morning_shows_upcoming
+    test_morning_upcoming_suppresses
+    test_morning_quick_oneliner
+
+    echo ""
+    echo "${CYAN}--- today ---${RESET}"
+    test_today_due_today
+
+    echo ""
+    echo "${CYAN}--- week ---${RESET}"
+    test_week_deadlines
+
+    cleanup
+    test_suite_end
+    exit $?
+}
+
+main "$@"

From 4e9f4ee594e12c890736e890e68acc1359a20db7 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sat, 13 Jun 2026 20:14:47 +0000
Subject: [PATCH 06/15] feat(agenda): add completion, man page, and
 manpage-guard patch
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- completions/_agenda: completes windows (today/-w/-m/--all/--overdue/-h)
  and project categories; also covers the agt/agw/agm aliases.
- man/man1/agenda.1: full page (modeled on g.1); .TH product/version is
  "flow-cli 7.9.0" to match FLOW_VERSION (the version-sync guard enforces
  this).
- tests/test-manpage-version-sync.zsh: skip `agenda` in the orphan check
  (next to the `flow` skip) — agenda is a top-level command, not a
  dispatcher, so it has no dispatcher function for the coverage scan to
  match. REQUIRED or the guard flags agenda.1 as an orphan page.

Verified: test-manpage-version-sync 12/12; zsh -n completions/_agenda
clean; man -l agenda.1 renders without warnings.

https://claude.ai/code/session_014YpEdtSqYMRdcuoMQFgLXW
---
 completions/_agenda                 |  47 +++++++++
 man/man1/agenda.1                   | 148 ++++++++++++++++++++++++++++
 tests/test-manpage-version-sync.zsh |   1 +
 3 files changed, 196 insertions(+)
 create mode 100644 completions/_agenda
 create mode 100644 man/man1/agenda.1

diff --git a/completions/_agenda b/completions/_agenda
new file mode 100644
index 000000000..7cdfc5bc6
--- /dev/null
+++ b/completions/_agenda
@@ -0,0 +1,47 @@
+#compdef agenda agt agw agm
+
+# Completion for the agenda command - forward-looking schedule view
+
+_agenda() {
+  local -a windows categories
+
+  windows=(
+    'today:Today only (+ overdue)'
+    '--week:Next 7 days (default)'
+    '--month:Next 30 days (adds LATER)'
+    '--all:Everything, including holidays'
+    '--overdue:Overdue items only'
+    '--help:Show help'
+  )
+
+  categories=(
+    'dev:Development tools'
+    'r:R packages'
+    'research:Research projects'
+    'teach:Teaching projects'
+    'teaching:Teaching projects (alias)'
+    'quarto:Quarto projects'
+    'apps:Applications'
+  )
+
+  _arguments -s \
+    '(- *)-h[Show help]' \
+    '(- *)--help[Show help]' \
+    '(- *)-w[Next 7 days (default)]' \
+    '(- *)--week[Next 7 days (default)]' \
+    '(- *)-m[Next 30 days]' \
+    '(- *)--month[Next 30 days]' \
+    '(- *)--all[Everything, including holidays]' \
+    '(- *)--overdue[Overdue items only]' \
+    '1:window or category:->choices' \
+  && return 0
+
+  case "$state" in
+    choices)
+      _describe -t windows 'window' windows
+      _describe -t categories 'category' categories
+      ;;
+  esac
+}
+
+_agenda "$@"
diff --git a/man/man1/agenda.1 b/man/man1/agenda.1
new file mode 100644
index 000000000..2c91936df
--- /dev/null
+++ b/man/man1/agenda.1
@@ -0,0 +1,148 @@
+.\" Man page for the agenda command (forward-looking schedule view)
+.\" Updated: June 2026
+.TH AGENDA 1 "June 2026" "flow-cli 7.9.0" "User Commands"
+.SH NAME
+agenda \- forward-looking schedule across all projects
+.SH SYNOPSIS
+.B agenda
+[\fIwindow\fR | \fIcategory\fR | \fB--overdue\fR | \fB--all\fR | \fB-h\fR]
+.SH DESCRIPTION
+.B agenda
+surfaces in-window and overdue dated activity across every project —
+assignment due dates, exam dates, manuscript and grant deadlines, milestones,
+and recurring blocks — grouped into
+.BR OVERDUE ,
+.BR TODAY ,
+.B "THIS WEEK"
+and
+.B LATER
+buckets, with a calm empty state when nothing is due.
+.PP
+Items come from two greenfield sources, with no migration required:
+.RS
+.IP \(bu 2
+A
+.B "## Schedule:"
+section in a project's
+.B .STATUS
+file (ZSH-parseable, no
+.BR yq ).
+.IP \(bu 2
+A teaching project's
+.B .flow/teach-config.yml
+(week topics, exams, deadlines, holidays) — derived automatically.
+.RE
+.PP
+.B agenda
+works fully without atlas and without
+.BR yq
+(the teaching path is the only one that needs
+.BR yq ).
+When atlas is present and exposes a
+.B schedule
+subcommand, the collected items are pushed opportunistically and
+asynchronously; otherwise the push is a silent no-op.
+.SH WINDOWS
+.TP
+.B (none)\fR, \fB-w\fR, \fB--week
+Next 7 days plus overdue (default).
+.TP
+.B today
+Today only, plus overdue.
+.TP
+.B -m\fR, \fB--month
+Next 30 days; adds the LATER bucket.
+.TP
+.B --all
+No window cap; includes holidays.
+.TP
+.B --overdue
+Overdue items only.
+.TP
+.B -h\fR, \fB--help
+Show help.
+.SH CATEGORIES
+Restrict to one project category:
+.RS
+.nf
+dev  r  research  teach  quarto  apps
+.fi
+.RE
+.SH "SCHEDULE GRAMMAR"
+Lines in a project's
+.B .STATUS
+.B "## Schedule:"
+section take the form
+.IR "- <when> | <label> [| <type>]" :
+.RS
+.nf
+## Schedule:
+- 2026-06-20 | Submit JRSS-B revision | research
+- 2026-07-01 | Project beta milestone | general
+- weekly:fri | Grading window | recurring
+- weekly:mon | Advisor meeting | research
+.fi
+.RE
+.PP
+.I when
+is an ISO date
+.RB ( YYYY-MM-DD )
+or a recurring token
+.RB ( weekly: <\fIdow\fR>).
+.I type
+is one of
+.BR teaching ,
+.BR research ,
+.BR general ,
+or
+.BR recurring
+(optional; defaults to
+.B general
+for dated items and
+.B recurring
+for
+.B weekly:
+tokens).
+.SH ICONS
+.RS
+.nf
+🎓 teaching   🔬 research   📌 general   🔁 recurring   🏖️ holiday
+.fi
+.RE
+.SH ALIASES
+.TP
+.B agt
+Equivalent to \fBagenda today\fR.
+.TP
+.B agw
+Equivalent to \fBagenda -w\fR.
+.TP
+.B agm
+Equivalent to \fBagenda -m\fR.
+.SH EXAMPLES
+This week's dated items:
+.RS
+.nf
+agenda
+.fi
+.RE
+.PP
+Only what is overdue:
+.RS
+.nf
+agenda --overdue
+.fi
+.RE
+.PP
+Next 30 days for research projects:
+.RS
+.nf
+agenda -m
+agenda research
+.fi
+.RE
+.SH "SEE ALSO"
+.BR dash (1),
+.BR flow (1)
+.SH AUTHOR
+DT
diff --git a/tests/test-manpage-version-sync.zsh b/tests/test-manpage-version-sync.zsh
index 9003f3fbc..af46ae1a7 100644
--- a/tests/test-manpage-version-sync.zsh
+++ b/tests/test-manpage-version-sync.zsh
@@ -221,6 +221,7 @@ run_check "no orphan flow-cli dispatcher page (page without a dispatcher)" '
         [[ "$(_th_product "$p")" == "flow-cli" ]] || continue   # skip vendored
         base="${p:t:r}"
         [[ "$base" == "flow" ]] && continue                     # flow is the index, not a dispatcher
+        [[ "$base" == "agenda" ]] && continue                   # agenda is a top-level command, not a dispatcher
         print -r -- "$cmds" | grep -qx "$base" || orphan+="$base "
     done
     if [[ -n "$orphan" ]]; then

From 127932fb939fb2ca7b16d56567634cc6f8c841e4 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sat, 13 Jun 2026 20:19:23 +0000
Subject: [PATCH 07/15] docs(agenda): document the agenda + schedule layer
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- New docs/guides/AGENDA-SCHEDULE-GUIDE.md (command, .STATUS `## Schedule:`
  grammar, teaching-config source, icons, dash/morning/today/week
  surfaces, atlas integration) + mkdocs.yml nav entry.
- docs/help/QUICK-REFERENCE.md: Agenda subsection (windows, aliases,
  schedule snippet), dash UPCOMING tip, TOC update.
- docs/reference/MASTER-DISPATCHER-GUIDE.md: top-level commands note
  covering agenda, dash UPCOMING, and cadence enrichment.
- docs/ATLAS-CONTRACT.md: opportunistic, capability-detected
  `atlas schedule push --format=json` contract (payload schema, probe,
  upsert semantics).
- CLAUDE.md: add agenda to Core Commands; note dash UPCOMING.

Verified: all internal doc links resolve; nav target exists. Full
`mkdocs build --strict` could not be run in this sandbox (mkdocs-exclude
won't compile here and the available mkdocs-material/pymdownx versions
differ from the project's pinned toolchain) — validated links + nav by
hand instead.

https://claude.ai/code/session_014YpEdtSqYMRdcuoMQFgLXW
---
 CLAUDE.md                                 |   3 +-
 docs/ATLAS-CONTRACT.md                    |  47 ++++++
 docs/guides/AGENDA-SCHEDULE-GUIDE.md      | 171 ++++++++++++++++++++++
 docs/help/QUICK-REFERENCE.md              |  48 +++++-
 docs/reference/MASTER-DISPATCHER-GUIDE.md |  10 ++
 mkdocs.yml                                |   1 +
 6 files changed, 278 insertions(+), 2 deletions(-)
 create mode 100644 docs/guides/AGENDA-SCHEDULE-GUIDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
index 1fc56c21d..8de9b2478 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -71,7 +71,8 @@ work <project>    # Start session (cd + context, no editor)
 work <proj> -e    # Start session + open $EDITOR
 finish [note]     # End session (optional commit)
 hop <project>     # Quick switch (tmux)
-dash [category]   # Project dashboard
+dash [category]   # Project dashboard (shows UPCOMING schedule section)
+agenda [window]   # Forward-looking schedule (today|-w|-m|--all|--overdue|<cat>)
 catch <text>      # Quick capture
 js                # Just start (auto-picks project)
 flow doctor       # Health check
diff --git a/docs/ATLAS-CONTRACT.md b/docs/ATLAS-CONTRACT.md
index 4c33754ea..e5798c9f0 100644
--- a/docs/ATLAS-CONTRACT.md
+++ b/docs/ATLAS-CONTRACT.md
@@ -49,6 +49,53 @@ These commands require Atlas CLI. flow-cli shows an install message if Atlas is
 
 ---
 
+## Opportunistic Commands (Capability-Detected, Optional)
+
+These commands are **not required**. flow-cli detects them at runtime and uses
+them only if present; otherwise the call is a **silent no-op**. flow-cli owns
+the data model and degrades fully without atlas.
+
+| Command | Description | Direction |
+|---------|-------------|-----------|
+| `atlas schedule push --format=json --data=<json>` | Ingest forward-looking dated items | flow-cli → atlas |
+
+### `atlas schedule push` (proposed)
+
+The `agenda` layer (`lib/schedule.zsh`) aggregates dated activity from each
+project's `.STATUS` `## Schedule:` block and `.flow/teach-config.yml`, then
+pushes it opportunistically and **asynchronously** (fire-and-forget) so it never
+blocks the prompt.
+
+**Capability probe.** flow-cli runs `atlas schedule --help` once per session and
+caches the result (`_FLOW_ATLAS_HAS_SCHEDULE`). If atlas is absent, or present
+but lacks a `schedule` subcommand, `_flow_schedule_to_atlas` returns without
+calling atlas.
+
+**Payload.** A JSON array of normalized records:
+
+```json
+[
+  {"date":"2026-06-20","label":"Submit JRSS-B revision","type":"research","project":"manuscript-x","recurrence":"none","source":"status"},
+  {"date":"2026-06-26","label":"Grading window","type":"recurring","project":"stat-101","recurrence":"weekly:fri","source":"status"}
+]
+```
+
+| Field | Meaning |
+|-------|---------|
+| `date` | ISO `YYYY-MM-DD` (recurring tokens are expanded to concrete dates) |
+| `label` | Human text |
+| `type` | `teaching` · `research` · `general` · `recurring` · `holiday` |
+| `project` | Source project name |
+| `recurrence` | `none` or `weekly:<dow>` |
+| `source` | `status` or `teach-config` |
+
+**Suggested semantics.** Upsert keyed on `(project, date, label)`. Exit code per
+the standard contract; flow-cli ignores the result (async). This is a *proposed*
+contract — the atlas-side `schedule` command is a separate atlas PR; flow-cli
+ships with the silent no-op until it lands.
+
+---
+
 ## Output Format Specifications
 
 Atlas CLI supports 4 output formats via the `--format` flag:
diff --git a/docs/guides/AGENDA-SCHEDULE-GUIDE.md b/docs/guides/AGENDA-SCHEDULE-GUIDE.md
new file mode 100644
index 000000000..30d996f84
--- /dev/null
+++ b/docs/guides/AGENDA-SCHEDULE-GUIDE.md
@@ -0,0 +1,171 @@
+---
+tags:
+  - guides
+  - commands
+  - adhd
+---
+
+# 📅 Agenda & Schedule Guide
+
+!!! tldr "What this gives you"
+    A single forward-looking view of everything *due soon* across all your
+    projects — assignment due dates, exam dates, manuscript/grant deadlines,
+    milestones, and recurring blocks — so deadlines stop living siloed in
+    course configs or in your head.
+
+`dash`, `morning`, `today`, and `week` have always been present- and
+backward-looking (status, current session, wins). The **agenda layer** adds the
+missing forward-looking dimension, driven by one shared engine
+(`lib/schedule.zsh`). It works fully **without atlas** and **without `yq`**.
+
+---
+
+## The `agenda` command
+
+```bash
+agenda                # Next 7 days + overdue (default)
+agenda today          # Due today + overdue
+agenda -w / --week    # Next 7 days (same as default)
+agenda -m / --month   # Next 30 days (adds a LATER bucket)
+agenda --all          # Everything, including holidays
+agenda --overdue      # Overdue items only
+agenda <category>     # Filter: dev | r | research | teach | quarto | apps
+agenda -h             # Help
+```
+
+Items are grouped into **OVERDUE → TODAY → THIS WEEK → LATER** buckets, with
+overdue surfaced loudly (🔥 colors first) and a calm empty state when nothing
+is due:
+
+```
+  📅 AGENDA (next 7 days)
+
+  OVERDUE (1)
+  🔬 overdue 3d  Submit JRSS-B revision (manuscript-x)
+
+  TODAY (1)
+  📌 today       Project beta milestone (app-y)
+
+  THIS WEEK (2)
+  🔬 in 2d       Advisor meeting 🔁 (study-z)
+  🔁 in 4d       Grading window (stat-101)
+
+  4 items • 'agenda -h' for options
+```
+
+### Aliases
+
+| Alias | Expands to |
+|-------|-----------|
+| `agt` | `agenda today` |
+| `agw` | `agenda -w` |
+| `agm` | `agenda -m` |
+
+!!! note "Why not `ag`?"
+    `ag` collides with the silver-searcher binary, so the aliases are
+    `agt`/`agw`/`agm`.
+
+---
+
+## Where items come from
+
+### 1. `## Schedule:` in a project's `.STATUS` (no `yq` needed)
+
+Add a `## Schedule:` section to any project's `.STATUS` file:
+
+```markdown
+## Schedule:
+- 2026-06-20 | Submit JRSS-B revision | research
+- 2026-07-01 | Project beta milestone | general
+- weekly:fri | Grading window | recurring
+- weekly:mon | Advisor meeting | research
+```
+
+Grammar — one list item per line:
+
+```
+- <when> | <label> [| <type>]
+```
+
+| Field | Values |
+|-------|--------|
+| `when`  | ISO date `YYYY-MM-DD`, or a recurring token `weekly:<dow>` (`mon`…`sun`) |
+| `label` | Free text (must not contain `\|`) |
+| `type`  | `teaching` · `research` · `general` · `recurring` (optional) |
+
+If `type` is omitted it defaults to `general` for dated items and `recurring`
+for `weekly:` tokens. The **project** is inferred from the directory name.
+Unknown tokens are skipped silently — never fatal.
+
+Recurring `weekly:<dow>` tokens are expanded into concrete dates within the
+view's window (correctly across month and year boundaries).
+
+### 2. Teaching dates from `.flow/teach-config.yml` (automatic)
+
+For teaching projects, week start dates, exams, deadlines, and holidays are
+read straight from your existing `.flow/teach-config.yml` via the teaching date
+engine — no re-entry. This path uses `yq`; if `yq` is absent the rest of the
+agenda still works, the teaching items are just skipped.
+
+!!! warning "`weeks[].start_date` required"
+    The teaching date loader reads `semester_info.weeks[].start_date`. A config
+    that only has `weeks[].date` yields no week items.
+
+Holidays are typed `holiday` and hidden unless you pass `--all`.
+
+---
+
+## Icons
+
+| Icon | Meaning |
+|------|---------|
+| 🎓 | teaching |
+| 🔬 | research |
+| 📌 | general |
+| 🔁 | recurring |
+| 🏖️ | holiday (only with `--all`) |
+
+A trailing 🔁 also flags a recurring item whose *type* isn't `recurring`
+(e.g. a research weekly block).
+
+---
+
+## Where the schedule shows up
+
+The same engine feeds every surface, so they all render consistently:
+
+| Surface | What it adds |
+|---------|--------------|
+| `dash` | **UPCOMING** section (after QUICK WINS) — next 4 items, 7d + overdue; self-suppresses when empty. |
+| `morning` | **Upcoming (next 7 days)** block — top 5; `morning -q` adds a `📅 N due soon` one-liner. |
+| `today` | **📅 Due today** — today + overdue (window 0). |
+| `week` | **📅 This week's deadlines** — 7 days, grouped by weekday (overdue first). |
+
+Results are cached per session (date + window keyed, ~10 min TTL), so running
+`agenda` and then `dash` reuses the work.
+
+---
+
+## Atlas integration (optional)
+
+When atlas is installed **and** exposes a `schedule` subcommand, `agenda` pushes
+the collected items opportunistically and asynchronously
+(`atlas schedule push --format=json`). When atlas is absent — or present but
+without that subcommand — the push is a silent no-op. flow-cli owns the model;
+atlas is just a sync target. See [ATLAS-CONTRACT](../ATLAS-CONTRACT.md).
+
+---
+
+## Examples
+
+```bash
+# Morning triage: what's on fire?
+agenda --overdue
+
+# Plan the month for a single research project
+agenda -m research
+
+# Quick glance without leaving your flow
+agt            # just today
+agw            # this week
+```
diff --git a/docs/help/QUICK-REFERENCE.md b/docs/help/QUICK-REFERENCE.md
index 08588ae20..ed88c1313 100644
--- a/docs/help/QUICK-REFERENCE.md
+++ b/docs/help/QUICK-REFERENCE.md
@@ -18,7 +18,7 @@ tags:
 
 ## Table of Contents
 
-- [Core Commands](#core-commands) - work, finish, dash, hop, catch
+- [Core Commands](#core-commands) - work, finish, dash, agenda, hop, catch
 - [Git Dispatcher (g)](#git-dispatcher-g) - Git workflows
 - [Claude Code (cc)](#claude-code-cc) - AI pair programming
 - [R Dispatcher (r)](#r-dispatcher-r) - R package development
@@ -121,6 +121,52 @@ dash -w 10       # Custom interval (seconds)
 dash -f
 ```
 
+!!! tip "UPCOMING section"
+    `dash` now shows an **UPCOMING** block (next 7 days + overdue) after QUICK
+    WINS. It self-suppresses when nothing is scheduled. Full view: `agenda`.
+
+---
+
+### Agenda (forward-looking schedule)
+
+```bash
+# Next 7 days + overdue (default)
+agenda
+
+# Windows
+agenda today        # Due today + overdue
+agenda -w           # Next 7 days
+agenda -m           # Next 30 days (adds LATER bucket)
+agenda --all        # Everything, including holidays
+agenda --overdue    # Overdue items only
+
+# Filter by category
+agenda research
+agenda teach
+
+# Aliases (avoid `ag` — collides with silver-searcher)
+agt                 # = agenda today
+agw                 # = agenda -w
+agm                 # = agenda -m
+
+# Help
+agenda -h
+```
+
+Add dated items to any project's `.STATUS` (no `yq` needed). Teaching dates come
+from `.flow/teach-config.yml` automatically.
+
+```markdown
+## Schedule:
+- 2026-06-20 | Submit JRSS-B revision | research
+- 2026-07-01 | Project beta milestone | general
+- weekly:fri | Grading window | recurring
+- weekly:mon | Advisor meeting | research
+```
+
+`morning`, `today`, and `week` also show dated blocks. Full guide:
+[Agenda & Schedule](../guides/AGENDA-SCHEDULE-GUIDE.md).
+
 ---
 
 ### Project Picker
diff --git a/docs/reference/MASTER-DISPATCHER-GUIDE.md b/docs/reference/MASTER-DISPATCHER-GUIDE.md
index 55bbb92ab..5c0c47883 100644
--- a/docs/reference/MASTER-DISPATCHER-GUIDE.md
+++ b/docs/reference/MASTER-DISPATCHER-GUIDE.md
@@ -54,6 +54,16 @@ teach init            # Initialize course
 | [em](#em-dispatcher) | Email (himalaya) | 31 | Beginner → Advanced |
 | [at](#at-atlas-project-intelligence) | Atlas project intelligence | 12+ | Beginner → Intermediate |
 
+### Top-Level Commands (not dispatchers)
+
+Alongside the dispatchers, flow-cli ships top-level commands like `work`,
+`finish`, `dash`, and **`agenda`** — the forward-looking schedule view
+(`agenda [today|-w|-m|--all|--overdue|<category>]`, aliases `agt`/`agw`/`agm`).
+The same schedule engine (`lib/schedule.zsh`) also enriches other surfaces:
+`dash` gains an **UPCOMING** section (after QUICK WINS), and `morning`/`today`/
+`week` show dated blocks. See the
+[Agenda & Schedule guide](../guides/AGENDA-SCHEDULE-GUIDE.md).
+
 ---
 
 ## How to Use This Guide
diff --git a/mkdocs.yml b/mkdocs.yml
index 85aa9deb4..13b979c9f 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -236,6 +236,7 @@ nav:
       - guides/index.md
       - Start Here: guides/00-START-HERE.md
       - Quick Wins: guides/WORKFLOWS-QUICK-WINS.md
+      - 📅 Agenda & Schedule: guides/AGENDA-SCHEDULE-GUIDE.md
       - Git & Branching:
           - Git Dispatcher (g): reference/REFCARD-GIT-DISPATCHER.md
           - Git Feature Flow: tutorials/08-git-feature-workflow.md

From 72906e72a45da8488a627e421e2597b39d83b092 Mon Sep 17 00:00:00 2001
From: Test User <test@example.com>
Date: Sat, 13 Jun 2026 15:43:52 -0600
Subject: [PATCH 08/15] fix(agenda): filter by item type, not just project
 category
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`agenda <filter>` previously matched only the project's detected category
(_dash_detect_category), so a `- … | research` item kept in a project that
flow-cli classifies as `dev`/`r`/`quarto` was silently dropped from
`agenda research` — contradicting the `## Schedule:` data model, which invites
tagging each item with a type.

The filter now matches a record's own TYPE (research|teaching|general|recurring)
OR the project's category (dev|r|teach|quarto|apps), via a new
_schedule_category_match helper. `teach`/`teaching` are treated as synonyms.
Filtering moved from per-project to per-record in _schedule_collect. The command
arg parser now also accepts `general`/`recurring` (were rejected as "unknown").

Tests: +3 engine (test-schedule 32→35), +2 command (test-agenda 17→19) covering
cross-category type match, type precision, and the teach/teaching synonym.
Docs/man/completions/help updated to describe type-or-category filtering.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 commands/agenda.zsh                       | 16 +++----
 completions/_agenda                       | 18 +++++--
 docs/guides/AGENDA-SCHEDULE-GUIDE.md      | 16 ++++++-
 docs/help/QUICK-REFERENCE.md              |  7 +--
 docs/reference/MASTER-DISPATCHER-GUIDE.md |  4 +-
 lib/schedule.zsh                          | 57 ++++++++++++++++++++---
 man/man1/agenda.1                         | 17 +++++--
 tests/test-agenda.zsh                     | 23 +++++++++
 tests/test-schedule.zsh                   | 37 +++++++++++++++
 9 files changed, 167 insertions(+), 28 deletions(-)

diff --git a/commands/agenda.zsh b/commands/agenda.zsh
index fbd4e47f2..34b4af102 100644
--- a/commands/agenda.zsh
+++ b/commands/agenda.zsh
@@ -42,14 +42,13 @@ agenda() {
       overdue_only=1
       window=0
       ;;
-    dev|r|research|teach|quarto|apps)
+    dev|r|research|teach|teaching|general|recurring|quarto|apps)
+      # Filter matches the record's TYPE (research/teaching/general/recurring)
+      # OR the project's detected category (dev/r/quarto/apps). teach/teaching
+      # are synonyms — see _schedule_category_match.
       category="$arg"
       window=7
       ;;
-    teaching)
-      category="teach"
-      window=7
-      ;;
     *)
       _flow_log_warning "Unknown agenda option: $arg"
       echo ""
@@ -196,7 +195,7 @@ ${_C_GREEN}🔥 MOST COMMON${_C_NC} ${_C_DIM}(80% of daily use)${_C_NC}:
 ${_C_YELLOW}💡 QUICK EXAMPLES${_C_NC}:
   ${_C_DIM}\$${_C_NC} agenda                 ${_C_DIM}# This week's dated items${_C_NC}
   ${_C_DIM}\$${_C_NC} agenda -m              ${_C_DIM}# Next 30 days (adds LATER)${_C_NC}
-  ${_C_DIM}\$${_C_NC} agenda research        ${_C_DIM}# Filter by category${_C_NC}
+  ${_C_DIM}\$${_C_NC} agenda research        ${_C_DIM}# Filter by item type or project category${_C_NC}
   ${_C_DIM}\$${_C_NC} agenda --all           ${_C_DIM}# Everything, incl. holidays${_C_NC}
 
 ${_C_BLUE}📋 WINDOWS${_C_NC}:
@@ -207,8 +206,9 @@ ${_C_BLUE}📋 WINDOWS${_C_NC}:
   ${_C_CYAN}--overdue${_C_NC}         Overdue items only
   ${_C_CYAN}-h${_C_NC}, ${_C_CYAN}--help${_C_NC}         Show this help
 
-${_C_BLUE}📂 CATEGORIES${_C_NC}:
-  ${_C_CYAN}dev  r  research  teach  quarto  apps${_C_NC}
+${_C_BLUE}📂 FILTERS${_C_NC} ${_C_DIM}(match item type OR project category)${_C_NC}:
+  ${_C_CYAN}research  teaching  general  recurring${_C_NC}  ${_C_DIM}(item type)${_C_NC}
+  ${_C_CYAN}dev  r  teach  quarto  apps${_C_NC}            ${_C_DIM}(project category)${_C_NC}
 
 ${_C_BLUE}⚡ ALIASES${_C_NC}:
   ${_C_CYAN}agt${_C_NC} = agenda today   ${_C_CYAN}agw${_C_NC} = agenda -w   ${_C_CYAN}agm${_C_NC} = agenda -m
diff --git a/completions/_agenda b/completions/_agenda
index 7cdfc5bc6..802495a7b 100644
--- a/completions/_agenda
+++ b/completions/_agenda
@@ -3,7 +3,7 @@
 # Completion for the agenda command - forward-looking schedule view
 
 _agenda() {
-  local -a windows categories
+  local -a windows types categories
 
   windows=(
     'today:Today only (+ overdue)'
@@ -14,12 +14,19 @@ _agenda() {
     '--help:Show help'
   )
 
+  # Filter by a record's own type...
+  types=(
+    'research:Research items'
+    'teaching:Teaching items'
+    'general:General items'
+    'recurring:Recurring items'
+  )
+
+  # ...or by a project's detected category
   categories=(
     'dev:Development tools'
     'r:R packages'
-    'research:Research projects'
     'teach:Teaching projects'
-    'teaching:Teaching projects (alias)'
     'quarto:Quarto projects'
     'apps:Applications'
   )
@@ -33,13 +40,14 @@ _agenda() {
     '(- *)--month[Next 30 days]' \
     '(- *)--all[Everything, including holidays]' \
     '(- *)--overdue[Overdue items only]' \
-    '1:window or category:->choices' \
+    '1:window or filter:->choices' \
   && return 0
 
   case "$state" in
     choices)
       _describe -t windows 'window' windows
-      _describe -t categories 'category' categories
+      _describe -t types 'item type' types
+      _describe -t categories 'project category' categories
       ;;
   esac
 }
diff --git a/docs/guides/AGENDA-SCHEDULE-GUIDE.md b/docs/guides/AGENDA-SCHEDULE-GUIDE.md
index 30d996f84..f67deb36d 100644
--- a/docs/guides/AGENDA-SCHEDULE-GUIDE.md
+++ b/docs/guides/AGENDA-SCHEDULE-GUIDE.md
@@ -29,10 +29,24 @@ agenda -w / --week    # Next 7 days (same as default)
 agenda -m / --month   # Next 30 days (adds a LATER bucket)
 agenda --all          # Everything, including holidays
 agenda --overdue      # Overdue items only
-agenda <category>     # Filter: dev | r | research | teach | quarto | apps
+agenda <filter>       # Filter by item type or project category (see below)
 agenda -h             # Help
 ```
 
+### Filtering
+
+A filter argument matches a record's own **type** *or* the project's detected
+**category** — whichever hits first:
+
+| Filter | Matches |
+|--------|---------|
+| `research`, `teaching`, `general`, `recurring` | items with that **type** (`- … \| research`), in any project |
+| `dev`, `r`, `teach`, `quarto`, `apps` | items in a project of that **category** |
+
+So `agenda research` surfaces every item you tagged `| research` no matter which
+project it lives in — a manuscript deadline kept in a `dev`-category repo still
+shows up. `teach` and `teaching` are synonyms.
+
 Items are grouped into **OVERDUE → TODAY → THIS WEEK → LATER** buckets, with
 overdue surfaced loudly (🔥 colors first) and a calm empty state when nothing
 is due:
diff --git a/docs/help/QUICK-REFERENCE.md b/docs/help/QUICK-REFERENCE.md
index ed88c1313..d43e90a9b 100644
--- a/docs/help/QUICK-REFERENCE.md
+++ b/docs/help/QUICK-REFERENCE.md
@@ -140,9 +140,10 @@ agenda -m           # Next 30 days (adds LATER bucket)
 agenda --all        # Everything, including holidays
 agenda --overdue    # Overdue items only
 
-# Filter by category
-agenda research
-agenda teach
+# Filter by item type (research|teaching|general|recurring)
+# OR project category (dev|r|teach|quarto|apps)
+agenda research     # every item tagged `| research`, any project
+agenda teach        # teaching items + teach-category projects
 
 # Aliases (avoid `ag` — collides with silver-searcher)
 agt                 # = agenda today
diff --git a/docs/reference/MASTER-DISPATCHER-GUIDE.md b/docs/reference/MASTER-DISPATCHER-GUIDE.md
index 5c0c47883..903da753c 100644
--- a/docs/reference/MASTER-DISPATCHER-GUIDE.md
+++ b/docs/reference/MASTER-DISPATCHER-GUIDE.md
@@ -58,7 +58,9 @@ teach init            # Initialize course
 
 Alongside the dispatchers, flow-cli ships top-level commands like `work`,
 `finish`, `dash`, and **`agenda`** — the forward-looking schedule view
-(`agenda [today|-w|-m|--all|--overdue|<category>]`, aliases `agt`/`agw`/`agm`).
+(`agenda [today|-w|-m|--all|--overdue|<type-or-category>]`, aliases `agt`/`agw`/`agm`;
+the filter matches an item's type — research/teaching/general/recurring — or a
+project category — dev/r/teach/quarto/apps).
 The same schedule engine (`lib/schedule.zsh`) also enriches other surfaces:
 `dash` gains an **UPCOMING** section (after QUICK WINS), and `morning`/`today`/
 `week` show dated blocks. See the
diff --git a/lib/schedule.zsh b/lib/schedule.zsh
index 1207c615b..71268b37f 100644
--- a/lib/schedule.zsh
+++ b/lib/schedule.zsh
@@ -307,12 +307,47 @@ _schedule_expand_recurring() {
 # COLLECTION + PIPELINE
 # ============================================================================
 
+# =============================================================================
+# Function: _schedule_category_match
+# Purpose: Decide whether a record passes a category filter
+# Arguments:
+#   $1 - requested category (e.g. research, teach, dev, r, quarto, apps)
+#   $2 - the record's own type field (teaching|research|general|recurring|holiday)
+#   $3 - the project's detected category (_dash_detect_category)
+# Returns:
+#   0 if the record matches (or no filter requested), 1 otherwise
+# Notes:
+#   - Matches on the record TYPE *or* the project category, so a `| research`
+#     item surfaces under `agenda research` no matter what category its project
+#     is detected as. Project-only categories (dev/r/quarto/apps) keep working
+#     via the project-category arm.
+#   - `teach` and `teaching` are synonyms (command uses `teach`; record type and
+#     teach-config items use `teaching`).
+# =============================================================================
+_schedule_category_match() {
+  local want="${1:l}" rtype="${2:l}" pcat="${3:l}"
+  [[ -z "$want" ]] && return 0
+
+  local -a accept=("$want")
+  case "$want" in
+    teach|teaching) accept=(teach teaching) ;;
+  esac
+
+  local a
+  for a in "${accept[@]}"; do
+    [[ "$rtype" == "$a" || "$pcat" == "$a" ]] && return 0
+  done
+  return 1
+}
+
 # =============================================================================
 # Function: _schedule_collect
 # Purpose: Aggregate concrete-dated records across all projects
 # Arguments:
 #   $1 - window in days [default: SCHEDULE_DEFAULT_WINDOW]
-#   $2 - category filter (dev|r|research|teach|quarto|apps) [optional]
+#   $2 - category filter [optional] — matched against each record's TYPE
+#        (teaching|research|general|recurring) OR the project's detected
+#        category (dev|r|research|teach|quarto|apps). See _schedule_category_match.
 # Output:
 #   stdout - record stream (recurring tokens expanded to concrete dates)
 # Notes:
@@ -340,25 +375,30 @@ _schedule_collect() {
   local rend=$(_date_add_days "$today" "$rwin")
 
   local -a out=()
-  local project proj_path cat rec
+  local project proj_path proj_cat rec rtype
 
   while IFS= read -r project; do
     [[ -z "$project" ]] && continue
     proj_path=$(_dash_find_project_path "$project") || continue
     [[ -z "$proj_path" ]] && continue
 
-    if [[ -n "$category" ]]; then
-      cat=$(_dash_detect_category "$proj_path")
-      [[ "$cat" != "$category" ]] && continue
-    fi
+    # Resolve the project's detected category once (only needed when filtering).
+    # Filtering is applied per-record so a `| research` item surfaces under
+    # `agenda research` regardless of its project's detected category.
+    proj_cat=""
+    [[ -n "$category" ]] && proj_cat=$(_dash_detect_category "$proj_path")
 
     # 1. .STATUS schedule block
     if [[ -f "$proj_path/.STATUS" ]]; then
       while IFS= read -r rec; do
         [[ -z "$rec" ]] && continue
+        # type is field 3 in both concrete (date|...) and recurring (|...) forms
+        local -a rf=("${(@s:|:)rec}")
+        rtype="${rf[3]}"
+        [[ -n "$category" ]] && ! _schedule_category_match "$category" "$rtype" "$proj_cat" && continue
+
         if [[ "$rec" == "|"* ]]; then
           # recurring: empty date field -> expand
-          local -a rf=("${(@s:|:)rec}")
           local recurrence="${rf[5]}"
           local tail="${rec#|}"   # label|type|project|recurrence|source
           local d
@@ -375,6 +415,9 @@ _schedule_collect() {
     if [[ -f "$proj_path/.flow/teach-config.yml" ]]; then
       while IFS= read -r rec; do
         [[ -z "$rec" ]] && continue
+        local -a rf=("${(@s:|:)rec}")
+        rtype="${rf[3]}"
+        [[ -n "$category" ]] && ! _schedule_category_match "$category" "$rtype" "$proj_cat" && continue
         out+=("$rec")
       done < <(_schedule_teach_items "$proj_path/.flow/teach-config.yml" "$project")
     fi
diff --git a/man/man1/agenda.1 b/man/man1/agenda.1
index 2c91936df..cb3eea5ea 100644
--- a/man/man1/agenda.1
+++ b/man/man1/agenda.1
@@ -61,11 +61,22 @@ Overdue items only.
 .TP
 .B -h\fR, \fB--help
 Show help.
-.SH CATEGORIES
-Restrict to one project category:
+.SH FILTERS
+A filter argument matches a record's own
+.I type
+.RB ( research ", " teaching ", " general ", " recurring )
+OR the project's detected category
+.RB ( dev ", " r ", " teach ", " quarto ", " apps ).
+So
+.B agenda research
+surfaces every item tagged
+.I "| research"
+no matter which project it lives in.
+.RB ( teach " and " teaching " are synonyms.)"
 .RS
 .nf
-dev  r  research  teach  quarto  apps
+research  teaching  general  recurring   (item type)
+dev  r  teach  quarto  apps               (project category)
 .fi
 .RE
 .SH "SCHEDULE GRAMMAR"
diff --git a/tests/test-agenda.zsh b/tests/test-agenda.zsh
index 0b3616b39..913a0df8e 100644
--- a/tests/test-agenda.zsh
+++ b/tests/test-agenda.zsh
@@ -181,6 +181,27 @@ test_agenda_category_filter() {
     assert_not_contains "$output" "Ship v2" "dev item excluded" && test_pass
 }
 
+test_agenda_filter_matches_type() {
+    test_case "agenda research surfaces a research item from a dev-category project"
+    # 'webapp' at the root is detected as a dev project, but carries a
+    # research-TYPED item — type filtering must surface it.
+    mkdir -p "$TEST_ROOT/webapp"
+    {
+        echo "## Schedule:"
+        echo "- $(_date_add_days "$TODAY" 2) | JRSS-B revision | research"
+    } > "$TEST_ROOT/webapp/.STATUS"
+    local output=$(agenda research 2>&1)
+    rm -rf "$TEST_ROOT/webapp"
+    assert_contains "$output" "JRSS-B revision" "research-typed item from a non-research project matches" && test_pass
+}
+
+test_agenda_general_type_accepted() {
+    test_case "agenda general is a valid type filter (not 'unknown')"
+    local output=$(agenda general 2>&1)
+    assert_not_contains "$output" "Unknown" "general accepted as a filter" && \
+    assert_contains "$output" "Standup notes" "general-typed item surfaces" && test_pass
+}
+
 # ============================================================================
 # TESTS: empty state
 # ============================================================================
@@ -270,6 +291,8 @@ main() {
     echo ""
     echo "${CYAN}--- Category filter ---${RESET}"
     test_agenda_category_filter
+    test_agenda_filter_matches_type
+    test_agenda_general_type_accepted
 
     echo ""
     echo "${CYAN}--- Empty state ---${RESET}"
diff --git a/tests/test-schedule.zsh b/tests/test-schedule.zsh
index 3aa3b191e..a00c812ec 100644
--- a/tests/test-schedule.zsh
+++ b/tests/test-schedule.zsh
@@ -253,6 +253,40 @@ test_collect_category_filter() {
     assert_empty "$out" "no dev-category projects -> empty" && test_pass
 }
 
+test_collect_category_by_type() {
+    test_case "category filter matches record TYPE across project categories"
+    # 'webapp' lives at the root -> detected category 'dev', but it carries a
+    # research-TYPED schedule item. Filtering by 'research' must surface it.
+    mkdir -p "$TEST_ROOT/webapp"
+    cat > "$TEST_ROOT/webapp/.STATUS" <<EOF
+## Schedule:
+- $SOON | JRSS-B revision | research
+EOF
+    local out=$(_schedule_collect 30 research)
+    rm -rf "$TEST_ROOT/webapp"
+    assert_contains "$out" "JRSS-B revision" "research item in a dev-category project matches 'research'" && \
+    assert_contains "$out" "Submit revision" "research items in a research-category project still match" && test_pass
+}
+
+test_collect_category_type_precision() {
+    test_case "category filter excludes records of other types"
+    local out=$(_schedule_collect 30 general)
+    assert_contains "$out" "Beta milestone" "general-typed item matches 'general'" && \
+    assert_not_contains "$out" "Submit revision" "research-typed item excluded from 'general'" && test_pass
+}
+
+test_collect_category_teach_synonym() {
+    test_case "category 'teach' matches record type 'teaching' (synonym)"
+    mkdir -p "$TEST_ROOT/webapp2"
+    cat > "$TEST_ROOT/webapp2/.STATUS" <<EOF
+## Schedule:
+- $SOON | Lecture 5 prep | teaching
+EOF
+    local out=$(_schedule_collect 30 teach)
+    rm -rf "$TEST_ROOT/webapp2"
+    assert_contains "$out" "Lecture 5 prep" "teaching-typed item matches 'teach' synonym" && test_pass
+}
+
 test_filter_window_drops_later() {
     test_case "filter_window drops beyond-window, keeps overdue"
     local out=$(_schedule_collect 30 | _schedule_filter_window 7)
@@ -381,6 +415,9 @@ main() {
     test_collect_runs
     test_collect_expands_recurring
     test_collect_category_filter
+    test_collect_category_by_type
+    test_collect_category_type_precision
+    test_collect_category_teach_synonym
     test_filter_window_drops_later
     test_filter_window_wide_keeps
     test_sort_orders_by_date

From 55c246fd13adaae7bb002af726a00f41f078da32 Mon Sep 17 00:00:00 2001
From: Test User <test@example.com>
Date: Sat, 13 Jun 2026 15:49:59 -0600
Subject: [PATCH 09/15] docs(agenda): sync counts + README, fix MD040 in
 schedule guide
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- CLAUDE.md: lib 74→77, command files 31→32 (schedule.zsh + agenda.zsh
  added this branch); note agenda in the command-list hint; clarify the
  agenda filter accepts <type|cat>.
- README.md: list `agenda` in the "Stay Oriented" core commands.
- AGENDA-SCHEDULE-GUIDE.md: add `text` language to two terminal-output
  fences (MD040); markdownlint clean, mkdocs --strict passes.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md                            | 6 +++---
 README.md                            | 1 +
 docs/guides/AGENDA-SCHEDULE-GUIDE.md | 4 ++--
 3 files changed, 6 insertions(+), 5 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 8de9b2478..17a783eda 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -72,7 +72,7 @@ work <proj> -e    # Start session + open $EDITOR
 finish [note]     # End session (optional commit)
 hop <project>     # Quick switch (tmux)
 dash [category]   # Project dashboard (shows UPCOMING schedule section)
-agenda [window]   # Forward-looking schedule (today|-w|-m|--all|--overdue|<cat>)
+agenda [window]   # Forward-looking schedule (today|-w|-m|--all|--overdue|<type|cat>)
 catch <text>      # Quick capture
 js                # Just start (auto-picks project)
 flow doctor       # Health check
@@ -123,13 +123,13 @@ at <cmd>      # Atlas bridge (project intelligence, optional)
 ```zsh
 flow-cli/
 ├── flow.plugin.zsh           # Plugin entry point
-├── lib/                      # Core libraries (74 files)
+├── lib/                      # Core libraries (77 files)
 │   ├── core.zsh              # Colors, logging, utilities
 │   ├── git-helpers.zsh       # Git integration + smart commits
 │   ├── keychain-helpers.zsh  # macOS Keychain secrets
 │   ├── tui.zsh               # Terminal UI components
 │   └── dispatchers/          # 14 smart command dispatchers
-├── commands/                 # 31 command files (work, dash, doctor, teach-*, etc.)
+├── commands/                 # 32 command files (work, dash, agenda, doctor, teach-*, etc.)
 ├── setup/                    # Installation & setup
 ├── completions/              # ZSH completions
 ├── hooks/                    # ZSH hooks
diff --git a/README.md b/README.md
index 9465e1744..98cfaef6d 100644
--- a/README.md
+++ b/README.md
@@ -126,6 +126,7 @@ flow goal set 3         # Daily target
 
 ```bash
 dash           # What's happening?
+agenda         # What's due soon? (deadlines, exams, milestones)
 why            # Where was I?
 pick           # Choose a project
 ```
diff --git a/docs/guides/AGENDA-SCHEDULE-GUIDE.md b/docs/guides/AGENDA-SCHEDULE-GUIDE.md
index f67deb36d..d27b8bff1 100644
--- a/docs/guides/AGENDA-SCHEDULE-GUIDE.md
+++ b/docs/guides/AGENDA-SCHEDULE-GUIDE.md
@@ -51,7 +51,7 @@ Items are grouped into **OVERDUE → TODAY → THIS WEEK → LATER** buckets, wi
 overdue surfaced loudly (🔥 colors first) and a calm empty state when nothing
 is due:
 
-```
+```text
   📅 AGENDA (next 7 days)
 
   OVERDUE (1)
@@ -97,7 +97,7 @@ Add a `## Schedule:` section to any project's `.STATUS` file:
 
 Grammar — one list item per line:
 
-```
+```text
 - <when> | <label> [| <type>]
 ```
 

From 6f489ac7d42cd2cb64a6713167e2f5d4ef97d67b Mon Sep 17 00:00:00 2001
From: Test User <test@example.com>
Date: Sat, 13 Jun 2026 16:20:29 -0600
Subject: [PATCH 10/15] fix(agenda): harden parser, holiday filter, cache key,
 atlas JSON (review)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Addresses adversarial-review findings A–F on this branch:

A. Test integrity (test-agenda.zsh): `local out=$(agenda…); assert_exit_code $?`
   always read the `local` builtin's status (0), so the exit-code assertions
   were inert. Split declaration/assignment to capture the real rc.

B. _schedule_parse_status corrupted records when a label contained `|`
   (label truncated, type mis-assigned). Now the last field is treated as the
   type only when it is a known token; the middle is the label; any leftover
   `|` in the label is collapsed to `/` so the pipe-delimited record stays
   well-formed (6 fields, correct type). teach→teaching normalized.

C. Holiday filtering used `grep -v '|holiday|'` (substring) across 6 call
   sites — a general item literally labeled "holiday" was wrongly dropped.
   New `_schedule_drop_holidays` filters the TYPE field via awk; all 6 sites
   (agenda/dash/morning×4) use it.

D. _schedule_collect cache key omitted FLOW_PROJECTS_ROOT → stale cross-root
   results when the cache persisted. Root added to the key.

E. Added command-path coverage for holiday hide/--all-show and pipe-in-label
   rendering (were untested).

F. _flow_schedule_to_atlas built JSON via raw printf interpolation → invalid
   JSON when a label contained `"`/`\`. New _schedule_json_escape +
   _schedule_records_to_json (pure ZSH, no jq) emit valid escaped JSON.

Tests: test-schedule 35→39, test-agenda 19→22; full suite 60/60 (2 pre-existing
environmental fails, 1 expected timeout — unchanged). source clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 commands/agenda.zsh     |  2 +-
 commands/dash.zsh       |  2 +-
 commands/morning.zsh    |  8 ++--
 lib/schedule.zsh        | 99 ++++++++++++++++++++++++++++++++++-------
 tests/test-agenda.zsh   | 50 +++++++++++++++++++--
 tests/test-schedule.zsh | 64 ++++++++++++++++++++++++++
 6 files changed, 200 insertions(+), 25 deletions(-)

diff --git a/commands/agenda.zsh b/commands/agenda.zsh
index 34b4af102..b3da0c681 100644
--- a/commands/agenda.zsh
+++ b/commands/agenda.zsh
@@ -63,7 +63,7 @@ agenda() {
 
   # Holidays are noise unless explicitly requested (--all)
   if (( ! show_all )) && [[ -n "$records" ]]; then
-    records=$(print -r -- "$records" | grep -v '|holiday|')
+    records=$(print -r -- "$records" | _schedule_drop_holidays)
   fi
 
   # Bucketize (THIS WEEK vs LATER split on the fixed 7-day horizon)
diff --git a/commands/dash.zsh b/commands/dash.zsh
index 02c7a8970..0091a48c0 100644
--- a/commands/dash.zsh
+++ b/commands/dash.zsh
@@ -426,7 +426,7 @@ _dash_upcoming() {
 
   local records
   records=$(_schedule_collect "$SCHEDULE_DEFAULT_WINDOW" | _schedule_filter_window "$SCHEDULE_DEFAULT_WINDOW" | _schedule_sort)
-  [[ -n "$records" ]] && records=$(print -r -- "$records" | grep -v '|holiday|')
+  [[ -n "$records" ]] && records=$(print -r -- "$records" | _schedule_drop_holidays)
   [[ -z "$records" ]] && return 0
 
   echo "  📅 ${FLOW_COLORS[bold]}UPCOMING${FLOW_COLORS[reset]} ${FLOW_COLORS[muted]}(next 7 days)${FLOW_COLORS[reset]}"
diff --git a/commands/morning.zsh b/commands/morning.zsh
index e3eb67ac5..aed2278d8 100644
--- a/commands/morning.zsh
+++ b/commands/morning.zsh
@@ -108,7 +108,7 @@ _flow_morning_agenda() {
 
   local records
   records=$(_schedule_collect 7 | _schedule_filter_window 7 | _schedule_sort)
-  [[ -n "$records" ]] && records=$(print -r -- "$records" | grep -v '|holiday|')
+  [[ -n "$records" ]] && records=$(print -r -- "$records" | _schedule_drop_holidays)
   [[ -z "$records" ]] && return 0
 
   echo ""
@@ -133,7 +133,7 @@ _flow_agenda_count() {
   typeset -f _schedule_collect >/dev/null 2>&1 || { echo 0; return 0; }
   local records
   records=$(_schedule_collect 7 | _schedule_filter_window 7)
-  [[ -n "$records" ]] && records=$(print -r -- "$records" | grep -v '|holiday|')
+  [[ -n "$records" ]] && records=$(print -r -- "$records" | _schedule_drop_holidays)
   [[ -z "$records" ]] && { echo 0; return 0; }
   print -r -- "$records" | grep -c .
 }
@@ -257,7 +257,7 @@ _flow_today_agenda() {
 
   local records
   records=$(_schedule_collect 0 | _schedule_filter_window 0 | _schedule_sort)
-  [[ -n "$records" ]] && records=$(print -r -- "$records" | grep -v '|holiday|')
+  [[ -n "$records" ]] && records=$(print -r -- "$records" | _schedule_drop_holidays)
   [[ -z "$records" ]] && return 0
 
   echo "  ${FLOW_COLORS[warning]}📅 Due today${FLOW_COLORS[reset]}"
@@ -311,7 +311,7 @@ _flow_week_agenda() {
 
   local records
   records=$(_schedule_collect 7 | _schedule_filter_window 7 | _schedule_sort)
-  [[ -n "$records" ]] && records=$(print -r -- "$records" | grep -v '|holiday|')
+  [[ -n "$records" ]] && records=$(print -r -- "$records" | _schedule_drop_holidays)
   [[ -z "$records" ]] && return 0
 
   echo "  ${FLOW_COLORS[accent]}📅 This week's deadlines:${FLOW_COLORS[reset]}"
diff --git a/lib/schedule.zsh b/lib/schedule.zsh
index 71268b37f..23d088bb0 100644
--- a/lib/schedule.zsh
+++ b/lib/schedule.zsh
@@ -181,15 +181,35 @@ _schedule_parse_status() {
     body="${body#"${body%%[![:space:]]*}"}"   # trim leading whitespace
     [[ -z "$body" ]] && continue
 
-    # Split on `|`
+    # Split on `|`. Labels MAY contain `|` — keep the last field as the type
+    # only when it is a known type token, treat everything between as the
+    # label, then collapse any leftover `|` in the label (the internal record
+    # format is pipe-delimited) so downstream fields never shift.
     local -a parts
     parts=("${(@s:|:)body}")
-    local when="${parts[1]}" label="${parts[2]}" typ="${parts[3]}"
+    local n=${#parts}
+
+    local when="${parts[1]}"
+    when="${when//[[:space:]]/}"
+
+    local label="" typ=""
+    if (( n >= 3 )); then
+      local last="${parts[n]//[[:space:]]/}"; last="${last:l}"
+      case "$last" in
+        teach|teaching)
+          typ="teaching"; label="${(j:|:)parts[2,-2]}" ;;
+        research|general|recurring|holiday)
+          typ="$last";    label="${(j:|:)parts[2,-2]}" ;;
+        *)
+          label="${(j:|:)parts[2,-1]}" ;;   # last field is part of the label
+      esac
+    else
+      label="${(j:|:)parts[2,-1]}"          # n<=2: parts[2] (empty when n==1)
+    fi
 
-    when="${when//[[:space:]]/}"                                   # strip ws
+    local _slash='/'; label="${label//[|]/$_slash}"               # sanitize `|`
     label="${label#"${label%%[![:space:]]*}"}"                    # ltrim
     label="${label%"${label##*[![:space:]]}"}"                    # rtrim
-    typ="${typ//[[:space:]]/}"; typ="${typ:l}"
 
     [[ -z "$when" || -z "$label" ]] && continue
 
@@ -360,7 +380,7 @@ _schedule_collect() {
   local category="${2:-}"
 
   local today=$(_schedule_today)
-  local cache_key="${today}|${window}|${category}"
+  local cache_key="${FLOW_PROJECTS_ROOT}|${today}|${window}|${category}"
 
   if [[ -z "$FLOW_SCHEDULE_NO_CACHE" ]] \
      && [[ "$_SCHEDULE_CACHE_KEY" == "$cache_key" ]] \
@@ -467,6 +487,19 @@ _schedule_sort() {
   sort -t'|' -k1,1
 }
 
+# =============================================================================
+# Function: _schedule_drop_holidays
+# Purpose: Drop records whose TYPE is `holiday` (callers use this unless --all)
+# Input:  stdin  - record stream
+# Output: stdout - records with type != holiday
+# Notes:
+#   - Filters on the type FIELD (column 3), not a substring, so a legitimate
+#     item whose label happens to be "holiday" is not wrongly dropped.
+# =============================================================================
+_schedule_drop_holidays() {
+  awk -F'|' '$3 != "holiday"'
+}
+
 # =============================================================================
 # Function: _schedule_render_line
 # Purpose: Render a single record (type icon + urgency color + relative day)
@@ -505,6 +538,51 @@ _schedule_render_line() {
 # ATLAS (opportunistic, capability-detected)
 # ============================================================================
 
+# =============================================================================
+# Function: _schedule_json_escape
+# Purpose: Escape a string for safe inclusion in a JSON double-quoted value
+# Arguments:
+#   $1 - raw string
+# Output:
+#   stdout - escaped string (\\, \", \t, \n, \r)
+# Notes:
+#   - Pure ZSH (no jq dependency). Backslash MUST be escaped first.
+# =============================================================================
+_schedule_json_escape() {
+  local s="$1"
+  s="${s//\\/\\\\}"      # backslash -> \\  (first!)
+  s="${s//\"/\\\"}"      # quote     -> \"
+  s="${s//$'\t'/\\t}"    # tab
+  s="${s//$'\n'/\\n}"    # newline
+  s="${s//$'\r'/\\r}"    # carriage return
+  print -r -- "$s"
+}
+
+# =============================================================================
+# Function: _schedule_records_to_json
+# Purpose: Serialize records into a JSON array (each field escaped)
+# Arguments:
+#   $@ - records (date|label|type|project|recurrence|source)
+# Output:
+#   stdout - JSON array string (valid even when labels contain " or \)
+# =============================================================================
+_schedule_records_to_json() {
+  local -a records=("$@")
+  local json="[" first=1 rec
+  for rec in "${records[@]}"; do
+    [[ -z "$rec" ]] && continue
+    local -a f=("${(@s:|:)rec}")
+    (( first )) || json+=","
+    first=0
+    json+=$(printf '{"date":"%s","label":"%s","type":"%s","project":"%s","recurrence":"%s","source":"%s"}' \
+      "$(_schedule_json_escape "${f[1]}")" "$(_schedule_json_escape "${f[2]}")" \
+      "$(_schedule_json_escape "${f[3]}")" "$(_schedule_json_escape "${f[4]}")" \
+      "$(_schedule_json_escape "${f[5]}")" "$(_schedule_json_escape "${f[6]}")")
+  done
+  json+="]"
+  print -r -- "$json"
+}
+
 # =============================================================================
 # Function: _flow_schedule_to_atlas
 # Purpose: Opportunistically push records to atlas (async, no-op if absent)
@@ -530,16 +608,7 @@ _flow_schedule_to_atlas() {
   local -a records=("$@")
   (( ${#records[@]} == 0 )) && return 0
 
-  local json="[" first=1 rec
-  for rec in "${records[@]}"; do
-    [[ -z "$rec" ]] && continue
-    local -a f=("${(@s:|:)rec}")
-    (( first )) || json+=","
-    first=0
-    json+=$(printf '{"date":"%s","label":"%s","type":"%s","project":"%s","recurrence":"%s","source":"%s"}' \
-      "${f[1]}" "${f[2]}" "${f[3]}" "${f[4]}" "${f[5]}" "${f[6]}")
-  done
-  json+="]"
+  local json=$(_schedule_records_to_json "${records[@]}")
 
   _flow_atlas_async schedule push --format=json --data="$json"
   return 0
diff --git a/tests/test-agenda.zsh b/tests/test-agenda.zsh
index 913a0df8e..5df2078e6 100644
--- a/tests/test-agenda.zsh
+++ b/tests/test-agenda.zsh
@@ -91,8 +91,9 @@ test_agenda_aliases_exist() {
 
 test_agenda_help_runs() {
     test_case "agenda -h runs and shows usage"
-    local output=$(agenda -h 2>&1)
-    assert_exit_code $? 0 "agenda -h should exit 0"
+    local output rc
+    output=$(agenda -h 2>&1); rc=$?
+    assert_exit_code $rc 0 "agenda -h should exit 0"
     assert_contains "$output" "AGENDA" "help shows title" && \
     assert_contains "$output" "today" "help mentions today window" && \
     assert_contains "$output" "--overdue" "help mentions --overdue" && test_pass
@@ -110,8 +111,9 @@ test_agenda_help_flag() {
 
 test_agenda_default_runs() {
     test_case "agenda (default) runs without error"
-    local output=$(agenda 2>&1)
-    assert_exit_code $? 0 "agenda should exit 0"
+    local output rc
+    output=$(agenda 2>&1); rc=$?
+    assert_exit_code $rc 0 "agenda should exit 0"
     assert_not_contains "$output" "command not found" && test_pass
 }
 
@@ -221,6 +223,40 @@ test_agenda_empty_category() {
     assert_contains "$output" "Nothing scheduled" && test_pass
 }
 
+# ============================================================================
+# TESTS: holiday filtering (default hides, --all shows)
+# ============================================================================
+
+test_agenda_default_excludes_holiday() {
+    test_case "agenda (default) hides holiday-typed items"
+    mkdir -p "$TEST_ROOT/hol"
+    printf '## Schedule:\n- %s | Fall Break | holiday\n' "$(_date_add_days "$TODAY" 2)" > "$TEST_ROOT/hol/.STATUS"
+    local output=$(agenda 2>&1)
+    rm -rf "$TEST_ROOT/hol"
+    assert_not_contains "$output" "Fall Break" "holiday hidden by default" && test_pass
+}
+
+test_agenda_all_includes_holiday() {
+    test_case "agenda --all shows holiday-typed items"
+    mkdir -p "$TEST_ROOT/hol"
+    printf '## Schedule:\n- %s | Fall Break | holiday\n' "$(_date_add_days "$TODAY" 2)" > "$TEST_ROOT/hol/.STATUS"
+    local output=$(agenda --all 2>&1)
+    rm -rf "$TEST_ROOT/hol"
+    assert_contains "$output" "Fall Break" "holiday shown under --all" && test_pass
+}
+
+test_agenda_label_with_pipe_renders() {
+    test_case "agenda renders a label containing '|' without field corruption"
+    mkdir -p "$TEST_ROOT/pipe"
+    printf '## Schedule:\n- %s | Fix bug | crash | research\n' "$(_date_add_days "$TODAY" 1)" > "$TEST_ROOT/pipe/.STATUS"
+    local output=$(agenda research 2>&1)
+    rm -rf "$TEST_ROOT/pipe"
+    # type stayed 'research' (item appears under the research filter) and the
+    # label is sanitized, not truncated at the first pipe
+    assert_contains "$output" "Fix bug" "label present" && \
+    assert_not_contains "$output" "command not found" "no breakage" && test_pass
+}
+
 # ============================================================================
 # TESTS: unknown option
 # ============================================================================
@@ -299,6 +335,12 @@ main() {
     test_agenda_empty_state
     test_agenda_empty_category
 
+    echo ""
+    echo "${CYAN}--- Holiday filtering + pipe-in-label ---${RESET}"
+    test_agenda_default_excludes_holiday
+    test_agenda_all_includes_holiday
+    test_agenda_label_with_pipe_renders
+
     echo ""
     echo "${CYAN}--- Unknown option ---${RESET}"
     test_agenda_unknown_option
diff --git a/tests/test-schedule.zsh b/tests/test-schedule.zsh
index a00c812ec..25bf37f98 100644
--- a/tests/test-schedule.zsh
+++ b/tests/test-schedule.zsh
@@ -193,6 +193,18 @@ test_parse_status_no_section() {
     assert_empty "$out" "no schedule section should yield nothing" && test_pass
 }
 
+test_parse_status_pipe_in_label() {
+    test_case "parse_status keeps a well-formed record when the label contains '|'"
+    local tmp=$(mktemp -d)/.STATUS
+    printf '## Schedule:\n- 2030-02-02 | Submit A|B revision | research\n' > "$tmp"
+    local out=$(_schedule_parse_status "$tmp")
+    local nf=$(print -r -- "$out" | awk -F'|' '{print NF}')
+    local typ=$(print -r -- "$out" | awk -F'|' '{print $3}')
+    assert_equals "$nf" "6" "record must stay 6 fields despite pipe in label (got $nf)" && \
+    assert_equals "$typ" "research" "type must be research, not corrupted (got '$typ')" && \
+    assert_contains "$out" "Submit A/B revision" "inner pipe sanitized to '/'" && test_pass
+}
+
 # ============================================================================
 # TESTS: recurrence expansion (month + year boundaries)
 # ============================================================================
@@ -287,6 +299,40 @@ EOF
     assert_contains "$out" "Lecture 5 prep" "teaching-typed item matches 'teach' synonym" && test_pass
 }
 
+test_drop_holidays_by_type_field() {
+    test_case "drop_holidays filters the TYPE field, not a substring"
+    # A general item whose LABEL is literally 'holiday' must survive; only
+    # records TYPED holiday are dropped.
+    local input="2030-01-01|holiday|general|p|none|status
+2030-01-02|Fall break|holiday|p|none|status"
+    local out=$(print -r -- "$input" | _schedule_drop_holidays)
+    assert_contains "$out" "2030-01-01|holiday|general" "general item labeled 'holiday' kept" && \
+    assert_not_contains "$out" "Fall break" "holiday-TYPED record dropped" && test_pass
+}
+
+test_collect_cache_keyed_on_root() {
+    test_case "collect cache is keyed on FLOW_PROJECTS_ROOT (no cross-root leak)"
+    local saved_nc="${FLOW_SCHEDULE_NO_CACHE:-}" saved_root="$FLOW_PROJECTS_ROOT"
+    unset FLOW_SCHEDULE_NO_CACHE                       # enable caching
+    _SCHEDULE_CACHE_KEY=""; _SCHEDULE_CACHE_RECORDS=""; _SCHEDULE_CACHE_TIME=0
+    local r1=$(mktemp -d) r2=$(mktemp -d)
+    local f1=$(mktemp) f2=$(mktemp)
+    mkdir -p "$r1/a" "$r2/b"
+    printf '## Schedule:\n- 2030-03-03 | Root1 item | general\n' > "$r1/a/.STATUS"
+    printf '## Schedule:\n- 2030-03-03 | Root2 item | general\n' > "$r2/b/.STATUS"
+    # Call with redirection (NOT $(...)) so the session cache persists in this
+    # shell — that is what exposes a root-agnostic cache key.
+    FLOW_PROJECTS_ROOT="$r1"; _schedule_collect 3650 > "$f1"
+    FLOW_PROJECTS_ROOT="$r2"; _schedule_collect 3650 > "$f2"
+    local out2=$(<"$f2")
+    FLOW_PROJECTS_ROOT="$saved_root"
+    [[ -n "$saved_nc" ]] && FLOW_SCHEDULE_NO_CACHE="$saved_nc"
+    _SCHEDULE_CACHE_KEY=""; _SCHEDULE_CACHE_RECORDS=""; _SCHEDULE_CACHE_TIME=0
+    rm -rf "$r1" "$r2" "$f1" "$f2"
+    assert_contains "$out2" "Root2 item" "second root returns its own items" && \
+    assert_not_contains "$out2" "Root1 item" "no stale cross-root cache leak" && test_pass
+}
+
 test_filter_window_drops_later() {
     test_case "filter_window drops beyond-window, keeps overdue"
     local out=$(_schedule_collect 30 | _schedule_filter_window 7)
@@ -367,6 +413,20 @@ test_atlas_noop_when_absent() {
     reset_mocks
 }
 
+test_records_to_json_valid() {
+    test_case "records_to_json escapes quotes/backslashes into valid JSON"
+    local rec='2030-01-01|He said "hi" \ done|research|p|none|status'
+    local json=$(_schedule_records_to_json "$rec")
+    if command -v python3 >/dev/null 2>&1; then
+        local ok=$(print -r -- "$json" | python3 -c 'import sys,json; json.load(sys.stdin); print("VALID")' 2>/dev/null)
+        assert_equals "$ok" "VALID" "output must be parseable JSON (got: $json)" && \
+        assert_contains "$json" '\"hi\"' "quotes escaped" && test_pass
+    else
+        assert_contains "$json" '\"hi\"' "quotes escaped" && \
+        assert_contains "$json" '\\ done' "backslash escaped" && test_pass
+    fi
+}
+
 # ============================================================================
 # RUN TESTS
 # ============================================================================
@@ -402,6 +462,7 @@ main() {
     test_parse_status_default_type
     test_parse_status_empty_file
     test_parse_status_no_section
+    test_parse_status_pipe_in_label
 
     echo ""
     echo "${CYAN}--- Recurrence expansion ---${RESET}"
@@ -418,6 +479,8 @@ main() {
     test_collect_category_by_type
     test_collect_category_type_precision
     test_collect_category_teach_synonym
+    test_drop_holidays_by_type_field
+    test_collect_cache_keyed_on_root
     test_filter_window_drops_later
     test_filter_window_wide_keeps
     test_sort_orders_by_date
@@ -435,6 +498,7 @@ main() {
     echo ""
     echo "${CYAN}--- Atlas opportunistic push ---${RESET}"
     test_atlas_noop_when_absent
+    test_records_to_json_valid
 
     cleanup
     test_suite_end

From f995e2475313ab19c637426c56848bb675f0aabd Mon Sep 17 00:00:00 2001
From: Test User <test@example.com>
Date: Sat, 13 Jun 2026 16:33:10 -0600
Subject: [PATCH 11/15] docs(man): add man pages for dash, morning, today, week
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The agenda feature surfaced that the schedule-aware top-level commands lacked
man pages (only dispatchers + flow + agenda had them). Add full troff pages
modeled on agenda.1 / g.1:

- dash.1     — dashboard + UPCOMING section, all flags (-a/-i/-w/-f/--inventory)
- morning.1  — daily briefing + Upcoming block; documents the `am` alias
- today.1    — "Due today" + overdue snapshot
- week.1     — "This week's deadlines" grouped by weekday

All .TH = "flow-cli 7.9.0" (== FLOW_VERSION); each cross-references the others
and agenda(1). These are top-level commands, not dispatchers, so the
manpage-version-sync orphan check gains a skip case for them (same pattern as
the existing flow/agenda skips).

Verified: manpage guard 12/12, mandoc lint clean (only the project-wide
verbatim-date warning shared by every flow-cli page), full suite unchanged
(60 pass / 2 pre-existing env fails / 1 expected timeout).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 man/man1/dash.1                     | 88 +++++++++++++++++++++++++++++
 man/man1/morning.1                  | 58 +++++++++++++++++++
 man/man1/today.1                    | 39 +++++++++++++
 man/man1/week.1                     | 38 +++++++++++++
 tests/test-manpage-version-sync.zsh |  5 +-
 5 files changed, 227 insertions(+), 1 deletion(-)
 create mode 100644 man/man1/dash.1
 create mode 100644 man/man1/morning.1
 create mode 100644 man/man1/today.1
 create mode 100644 man/man1/week.1

diff --git a/man/man1/dash.1 b/man/man1/dash.1
new file mode 100644
index 000000000..bfd1fb1af
--- /dev/null
+++ b/man/man1/dash.1
@@ -0,0 +1,88 @@
+.\" Man page for the dash command (project dashboard)
+.\" Updated: June 2026
+.TH DASH 1 "June 2026" "flow-cli 7.9.0" "User Commands"
+.SH NAME
+dash \- ADHD-friendly project dashboard
+.SH SYNOPSIS
+.B dash
+[\fIcategory\fR | \fB-a\fR | \fB-i\fR | \fB-w\fR [\fIseconds\fR]]
+.br
+.B dash
+[\fB-f\fR | \fB--inventory\fR [\fIformat\fR] | \fB-h\fR]
+.SH DESCRIPTION
+.B dash
+prints a fast, scannable overview of what is happening across your projects:
+the current session, a single high-signal "right now" suggestion, dotfile
+status, quick wins, quick access, recent wins, and an
+.B UPCOMING
+section of forward-looking dated items (deadlines, exams, milestones, and
+recurring blocks) drawn from the shared schedule engine.
+.PP
+The
+.B UPCOMING
+section appears after QUICK WINS and self-suppresses when nothing is due
+within the next seven days (overdue items are always shown). It shares the
+schedule engine with
+.BR agenda (1)
+and the cadence commands, and works fully without atlas and without
+.BR yq .
+.SH OPTIONS
+.TP
+.B (none)
+Default dashboard.
+.TP
+.B dev\fR, \fBr\fR, \fBresearch\fR, \fBteach\fR, \fBquarto\fR, \fBapps
+Expand a single project category.
+.TP
+.B -a\fR, \fB--all
+Show all projects (no category collapsing).
+.TP
+.B -i\fR, \fB--interactive
+Interactive picker (fzf).
+.TP
+.B -w\fR, \fB--watch \fR[\fIseconds\fR]
+Auto-refreshing watch mode (default interval 5 seconds).
+.TP
+.B --inventory \fR[\fIformat\fR]
+Generate a tool inventory from
+.B .STATUS
+files (default format
+.BR table ).
+.TP
+.B -f\fR, \fB--full
+Full TUI dashboard (requires atlas; falls back to the standard view).
+.TP
+.B -h\fR, \fB--help
+Show help.
+.SH "UPCOMING ITEMS"
+Add dated items to a project's
+.B .STATUS
+file under a
+.B "## Schedule:"
+section; see
+.BR agenda (1)
+for the grammar. Teaching dates are derived automatically from a project's
+.BR .flow/teach-config.yml .
+.SH EXAMPLES
+The standard dashboard:
+.RS
+.nf
+dash
+.fi
+.RE
+.PP
+Expand research projects, or watch the board refresh every 10 seconds:
+.RS
+.nf
+dash research
+dash -w 10
+.fi
+.RE
+.SH "SEE ALSO"
+.BR agenda (1),
+.BR morning (1),
+.BR today (1),
+.BR week (1),
+.BR flow (1)
+.SH AUTHOR
+DT
diff --git a/man/man1/morning.1 b/man/man1/morning.1
new file mode 100644
index 000000000..5db25a646
--- /dev/null
+++ b/man/man1/morning.1
@@ -0,0 +1,58 @@
+.\" Man page for the morning command (daily startup routine)
+.\" Updated: June 2026
+.TH MORNING 1 "June 2026" "flow-cli 7.9.0" "User Commands"
+.SH NAME
+morning \- ADHD-friendly daily startup routine
+.SH SYNOPSIS
+.B morning
+[\fB-q\fR | \fB--quick\fR]
+.br
+.B am
+.SH DESCRIPTION
+.B morning
+reduces start-of-day decision fatigue with a single scannable briefing:
+inbox count, a summary of active projects, an
+.B Upcoming
+block of dated items (the next seven days plus anything overdue), yesterday's
+wins, and a suggestion for what to work on next.
+.PP
+The Upcoming block is driven by the shared schedule engine (the same one behind
+.BR agenda (1)
+and the
+.B "## Schedule:"
+section of each project's
+.B .STATUS
+file). It self-suppresses when nothing is due and works fully without atlas and
+without
+.BR yq .
+Holiday-typed items are omitted from this view.
+.SH OPTIONS
+.TP
+.B -q\fR, \fB--quick
+Quick mode: a compact briefing with the essentials only.
+.SH ALIASES
+.TP
+.B am
+Equivalent to \fBmorning -q\fR (quick briefing).
+.SH EXAMPLES
+Full morning briefing:
+.RS
+.nf
+morning
+.fi
+.RE
+.PP
+A quick check on the way past:
+.RS
+.nf
+am
+.fi
+.RE
+.SH "SEE ALSO"
+.BR today (1),
+.BR week (1),
+.BR agenda (1),
+.BR dash (1),
+.BR flow (1)
+.SH AUTHOR
+DT
diff --git a/man/man1/today.1 b/man/man1/today.1
new file mode 100644
index 000000000..0d398f3de
--- /dev/null
+++ b/man/man1/today.1
@@ -0,0 +1,39 @@
+.\" Man page for the today command (quick daily status)
+.\" Updated: June 2026
+.TH TODAY 1 "June 2026" "flow-cli 7.9.0" "User Commands"
+.SH NAME
+today \- quick daily status
+.SH SYNOPSIS
+.B today
+.SH DESCRIPTION
+.B today
+prints a focused snapshot of the current day: the active session (when atlas is
+present), today's logged wins, a
+.B "Due today"
+block of dated items due today plus anything overdue, and a summary of active
+work.
+.PP
+The
+.B "Due today"
+block uses the shared schedule engine with a zero-day window (plus overdue),
+drawing items from each project's
+.B "## Schedule:"
+section (see
+.BR agenda (1))
+and from teaching configs. It self-suppresses when nothing is due, omits
+holiday-typed items, and works without atlas or
+.BR yq .
+.SH EXAMPLES
+.RS
+.nf
+today
+.fi
+.RE
+.SH "SEE ALSO"
+.BR week (1),
+.BR morning (1),
+.BR agenda (1),
+.BR dash (1),
+.BR flow (1)
+.SH AUTHOR
+DT
diff --git a/man/man1/week.1 b/man/man1/week.1
new file mode 100644
index 000000000..ef7224954
--- /dev/null
+++ b/man/man1/week.1
@@ -0,0 +1,38 @@
+.\" Man page for the week command (weekly review helper)
+.\" Updated: June 2026
+.TH WEEK 1 "June 2026" "flow-cli 7.9.0" "User Commands"
+.SH NAME
+week \- weekly review helper
+.SH SYNOPSIS
+.B week
+.SH DESCRIPTION
+.B week
+is a retrospective-plus-lookahead for the week: it opens with
+.B "This week's deadlines"
+\(em dated items in the next seven days (plus overdue), grouped by weekday \(em
+then shows this week's sessions (when atlas is present) and this week's wins.
+.PP
+The deadlines block is driven by the shared schedule engine, drawing from each
+project's
+.B "## Schedule:"
+section (see
+.BR agenda (1))
+and from teaching configs. Overdue items are grouped under an
+.B Overdue
+heading; the block self-suppresses when nothing is due, omits holiday-typed
+items, and works without atlas or
+.BR yq .
+.SH EXAMPLES
+.RS
+.nf
+week
+.fi
+.RE
+.SH "SEE ALSO"
+.BR today (1),
+.BR morning (1),
+.BR agenda (1),
+.BR dash (1),
+.BR flow (1)
+.SH AUTHOR
+DT
diff --git a/tests/test-manpage-version-sync.zsh b/tests/test-manpage-version-sync.zsh
index af46ae1a7..b752e23fc 100644
--- a/tests/test-manpage-version-sync.zsh
+++ b/tests/test-manpage-version-sync.zsh
@@ -221,7 +221,10 @@ run_check "no orphan flow-cli dispatcher page (page without a dispatcher)" '
         [[ "$(_th_product "$p")" == "flow-cli" ]] || continue   # skip vendored
         base="${p:t:r}"
         [[ "$base" == "flow" ]] && continue                     # flow is the index, not a dispatcher
-        [[ "$base" == "agenda" ]] && continue                   # agenda is a top-level command, not a dispatcher
+        # Top-level commands (not dispatchers) that ship their own page:
+        case "$base" in
+          agenda|dash|morning|today|week) continue ;;
+        esac
         print -r -- "$cmds" | grep -qx "$base" || orphan+="$base "
     done
     if [[ -n "$orphan" ]]; then

From 634219c041b5190d183ebd4c16579ad5c7ff38df Mon Sep 17 00:00:00 2001
From: Test User <test@example.com>
Date: Sat, 13 Jun 2026 16:53:24 -0600
Subject: [PATCH 12/15] test(agenda): add e2e + dogfood suites; fix dash
 non-TTY abort
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds the missing per-feature test pair (every major feature has both):

- tests/e2e-agenda.zsh (19 tests) — drives the real commands against a seeded
  multi-project root: windows, --overdue, today/-m, type+category filters,
  holiday hide/--all, recurring expansion, pipe-in-label sanitization, the
  dash UPCOMING section, today/week/morning cadence, the empty state, and the
  yq-gated teaching path.
- tests/dogfood-agenda.zsh (15 tests) — structural wiring: engine/command/alias
  functions defined, source order, dash/cadence call the engine, holiday filter
  uses the helper (no raw grep left), no local path=/status= footguns, no var
  leakage, and packaging (man pages, completion, docs, .TH == FLOW_VERSION).
- Registered both in tests/run-all.sh.

Fix surfaced by the e2e: commands/dash.zsh used `$(( cond ? 's' : '' ))`
(arithmetic ternary with STRING operands) in _dash_right_now. Interactive
shells tolerate the resulting "bad math expression"; non-interactive shells
(command substitution, pipes, tests) treat it as fatal, so `dash` aborted
before reaching _dash_upcoming — i.e. the new UPCOMING section never rendered
when dash output was captured/piped. Pre-existing on dev (3 sites); replaced
with the codebase's safe idiom `$( (( cond )) && echo s )`.

Suite: 62 passed / 2 pre-existing env fails / 1 expected timeout.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 commands/dash.zsh        |   6 +-
 tests/dogfood-agenda.zsh | 204 ++++++++++++++++++++++++++
 tests/e2e-agenda.zsh     | 310 +++++++++++++++++++++++++++++++++++++++
 tests/run-all.sh         |   2 +
 4 files changed, 519 insertions(+), 3 deletions(-)
 create mode 100644 tests/dogfood-agenda.zsh
 create mode 100644 tests/e2e-agenda.zsh

diff --git a/commands/dash.zsh b/commands/dash.zsh
index 0091a48c0..6019b1c22 100644
--- a/commands/dash.zsh
+++ b/commands/dash.zsh
@@ -283,7 +283,7 @@ _dash_right_now() {
   elif (( streak == 0 && today_sessions > 0 )); then
     goal_msg="🎯 Goal: Complete session to start streak"
   elif (( today_sessions < daily_goal )); then
-    goal_msg="🎯 Goal: ${daily_goal} session$(( daily_goal > 1 ? 's' : '' )) today"
+    goal_msg="🎯 Goal: ${daily_goal} session$( (( daily_goal > 1 )) && echo s ) today"
   else
     goal_msg="✅ Daily goal achieved!"
   fi
@@ -291,7 +291,7 @@ _dash_right_now() {
   # Format today stats
   local sessions_text="0 sessions"
   if (( today_sessions > 0 )); then
-    sessions_text="$today_sessions session$(( today_sessions > 1 ? 's' : '' ))"
+    sessions_text="$today_sessions session$( (( today_sessions > 1 )) && echo s )"
   fi
   
   local time_text="0m"
@@ -303,7 +303,7 @@ _dash_right_now() {
   
   local streak_text="0 day"
   if (( streak > 0 )); then
-    streak_text="$streak day$(( streak > 1 ? 's' : '' ))"
+    streak_text="$streak day$( (( streak > 1 )) && echo s )"
   fi
   
   # Display RIGHT NOW section
diff --git a/tests/dogfood-agenda.zsh b/tests/dogfood-agenda.zsh
new file mode 100644
index 000000000..3839c84a8
--- /dev/null
+++ b/tests/dogfood-agenda.zsh
@@ -0,0 +1,204 @@
+#!/usr/bin/env zsh
+# dogfood-agenda.zsh - Structural dogfood tests for the agenda / schedule layer
+#
+# Verifies the feature is properly WIRED (not behavior — see e2e-agenda.zsh):
+# - engine + command + alias functions are defined after a clean plugin load
+# - the engine is sourced after date-parser/atlas-bridge in flow.plugin.zsh
+# - dash/morning/today/week call into the shared engine
+# - holiday filtering goes through the helper (no raw grep -v '|holiday|' left)
+# - no ZSH footguns (local path= / local status=) in the engine
+# - packaging is present: man pages, completion, docs references
+#
+# Usage: zsh tests/dogfood-agenda.zsh
+
+SCRIPT_DIR="${0:A:h}"
+PROJECT_ROOT="${SCRIPT_DIR:h}"
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[0;33m'
+CYAN='\033[0;36m'
+DIM='\033[2m'
+RESET='\033[0m'
+
+TESTS_RUN=0
+TESTS_PASSED=0
+TESTS_FAILED=0
+
+run_test() {
+    local test_name="$1"
+    local test_func="$2"
+
+    TESTS_RUN=$((TESTS_RUN + 1))
+    echo -n "  ${CYAN}[$TESTS_RUN] $test_name...${RESET} "
+
+    local output
+    output=$(eval "$test_func" 2>&1)
+    local rc=$?
+
+    if [[ $rc -eq 0 ]]; then
+        echo "${GREEN}PASS${RESET}"
+        TESTS_PASSED=$((TESTS_PASSED + 1))
+    elif [[ $rc -eq 77 ]]; then
+        echo "${YELLOW}SKIP${RESET}"
+    else
+        echo "${RED}FAIL${RESET}"
+        [[ -n "$output" ]] && echo "    ${DIM}${output:0:200}${RESET}"
+        TESTS_FAILED=$((TESTS_FAILED + 1))
+    fi
+}
+
+echo ""
+echo "${CYAN}══════════════════════════════════════════════════════════════${RESET}"
+echo "${CYAN}  Agenda / Schedule Layer - Dogfood Test${RESET}"
+echo "${CYAN}══════════════════════════════════════════════════════════════${RESET}"
+echo ""
+
+FLOW_QUIET=1
+FLOW_ATLAS_ENABLED=no
+FLOW_PLUGIN_DIR="$PROJECT_ROOT"
+source "$PROJECT_ROOT/flow.plugin.zsh" 2>/dev/null || {
+    echo "${RED}Failed to load plugin${RESET}"
+    exit 1
+}
+
+# ============================================================================
+# SECTION 1: command + alias functions wired
+# ============================================================================
+
+echo "${CYAN}--- Section 1: Command surface ---${RESET}"
+
+run_test "agenda command is defined" '
+    typeset -f agenda >/dev/null 2>&1 || return 1
+'
+
+run_test "agt/agw/agm aliases are defined and delegate to agenda" '
+    for a in agt agw agm; do
+        typeset -f "$a" >/dev/null 2>&1 || { echo "missing $a"; return 1; }
+        typeset -f "$a" | grep -q "agenda" || { echo "$a does not call agenda"; return 1; }
+    done
+'
+
+run_test "_agenda_help is defined" '
+    typeset -f _agenda_help >/dev/null 2>&1 || return 1
+'
+
+# ============================================================================
+# SECTION 2: engine functions wired
+# ============================================================================
+
+echo ""
+echo "${CYAN}--- Section 2: Engine functions ---${RESET}"
+
+run_test "all schedule engine functions are defined" '
+    local fns=(
+        _schedule_classify _schedule_relative_days _schedule_parse_status
+        _schedule_teach_items _schedule_expand_recurring _schedule_collect
+        _schedule_filter_window _schedule_sort _schedule_render_line
+        _schedule_category_match _schedule_drop_holidays
+        _schedule_json_escape _schedule_records_to_json _flow_schedule_to_atlas
+    )
+    local missing=""
+    for f in "${fns[@]}"; do
+        typeset -f "$f" >/dev/null 2>&1 || missing+="$f "
+    done
+    [[ -z "$missing" ]] || { echo "missing: $missing"; return 1; }
+'
+
+run_test "module guard _FLOW_SCHEDULE_LOADED is set" '
+    [[ "$_FLOW_SCHEDULE_LOADED" == "1" ]] || return 1
+'
+
+run_test "engine is sourced after date-parser in flow.plugin.zsh" '
+    local f="$PROJECT_ROOT/flow.plugin.zsh"
+    local dp=$(grep -n "date-parser.zsh" "$f" | head -1 | cut -d: -f1)
+    local sc=$(grep -n "schedule.zsh" "$f" | grep -v date | head -1 | cut -d: -f1)
+    [[ -n "$dp" && -n "$sc" ]] || { echo "dp=$dp sc=$sc"; return 1; }
+    (( dp < sc )) || { echo "date-parser ($dp) must precede schedule ($sc)"; return 1; }
+'
+
+# ============================================================================
+# SECTION 3: surface integration (dash / cadence)
+# ============================================================================
+
+echo ""
+echo "${CYAN}--- Section 3: Surface integration ---${RESET}"
+
+run_test "dash() calls _dash_upcoming" '
+    typeset -f dash | grep -q "_dash_upcoming" || return 1
+'
+
+run_test "morning/today/week call the schedule helpers" '
+    typeset -f morning | grep -q "_flow_morning_agenda" || { echo "morning"; return 1; }
+    typeset -f today   | grep -q "_flow_today_agenda"   || { echo "today"; return 1; }
+    typeset -f week    | grep -q "_flow_week_agenda"    || { echo "week"; return 1; }
+'
+
+run_test "holiday filtering goes through _schedule_drop_holidays (no raw grep left)" '
+    local hits
+    hits=$(grep -rn "grep -v .|holiday|." "$PROJECT_ROOT/commands" 2>/dev/null)
+    [[ -z "$hits" ]] || { echo "raw holiday grep remains: $hits"; return 1; }
+'
+
+# ============================================================================
+# SECTION 4: robustness / footguns
+# ============================================================================
+
+echo ""
+echo "${CYAN}--- Section 4: Robustness ---${RESET}"
+
+run_test "engine has no local path= / local status= footguns" '
+    local hits
+    hits=$(grep -nE "local +(path|status)=" "$PROJECT_ROOT/lib/schedule.zsh" "$PROJECT_ROOT/commands/agenda.zsh" 2>/dev/null)
+    [[ -z "$hits" ]] || { echo "$hits"; return 1; }
+'
+
+run_test "agenda runs without leaking engine vars into the shell" '
+    local before after
+    agenda -h >/dev/null 2>&1
+    for v in rtype cat rec proj_cat out b_overdue b_today b_week b_later; do
+        typeset -p "$v" >/dev/null 2>&1 && { echo "leaked: $v"; return 1; }
+    done
+    return 0
+'
+
+# ============================================================================
+# SECTION 5: packaging (man / completion / docs)
+# ============================================================================
+
+echo ""
+echo "${CYAN}--- Section 5: Packaging ---${RESET}"
+
+run_test "man pages exist for agenda + cadence commands" '
+    for p in agenda dash morning today week; do
+        [[ -f "$PROJECT_ROOT/man/man1/$p.1" ]] || { echo "missing man/man1/$p.1"; return 1; }
+    done
+'
+
+run_test "agenda man page .TH matches FLOW_VERSION" '
+    local want=$(grep -oE "FLOW_VERSION=\"?[0-9]+\.[0-9]+\.[0-9]+" "$PROJECT_ROOT/flow.plugin.zsh" | grep -oE "[0-9]+\.[0-9]+\.[0-9]+" | head -1)
+    grep -q "flow-cli $want" "$PROJECT_ROOT/man/man1/agenda.1" || { echo "expected flow-cli $want"; return 1; }
+'
+
+run_test "completion file _agenda exists" '
+    [[ -f "$PROJECT_ROOT/completions/_agenda" ]] || return 1
+'
+
+run_test "docs reference the agenda command" '
+    grep -q "agenda" "$PROJECT_ROOT/docs/help/QUICK-REFERENCE.md" || { echo "QUICK-REFERENCE"; return 1; }
+    [[ -f "$PROJECT_ROOT/docs/guides/AGENDA-SCHEDULE-GUIDE.md" ]] || { echo "guide missing"; return 1; }
+'
+
+# ============================================================================
+# SUMMARY
+# ============================================================================
+
+echo ""
+echo "${CYAN}══════════════════════════════════════════════════════════════${RESET}"
+if [[ $TESTS_FAILED -eq 0 ]]; then
+    echo "${GREEN}All $TESTS_PASSED/$TESTS_RUN dogfood tests passed${RESET}"
+    exit 0
+else
+    echo "${RED}$TESTS_FAILED/$TESTS_RUN tests failed (${TESTS_PASSED} passed)${RESET}"
+    exit 1
+fi
diff --git a/tests/e2e-agenda.zsh b/tests/e2e-agenda.zsh
new file mode 100644
index 000000000..74297391c
--- /dev/null
+++ b/tests/e2e-agenda.zsh
@@ -0,0 +1,310 @@
+#!/usr/bin/env zsh
+# e2e-agenda.zsh - End-to-end tests for the forward-looking schedule layer
+#
+# Drives the real user-facing commands (agenda / dash / morning / today / week)
+# against a seeded multi-project FLOW_PROJECTS_ROOT and asserts the rendered
+# output. Covers windows, overdue, type/category filters, holiday hide/--all,
+# recurring expansion, pipe-in-label sanitization, the dash UPCOMING section,
+# cadence enrichment, the empty state, and atlas-disabled operation.
+#
+# Pure .STATUS-driven (no yq needed); the teaching path is exercised only when
+# yq is present (skips otherwise).
+#
+# Usage: zsh tests/e2e-agenda.zsh
+
+SCRIPT_DIR="${0:A:h}"
+PROJECT_ROOT="${SCRIPT_DIR:h}"
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[0;33m'
+CYAN='\033[0;36m'
+DIM='\033[2m'
+RESET='\033[0m'
+
+TESTS_RUN=0
+TESTS_PASSED=0
+TESTS_FAILED=0
+
+run_test() {
+    local test_name="$1"
+    local test_func="$2"
+
+    TESTS_RUN=$((TESTS_RUN + 1))
+    echo -n "  ${CYAN}[$TESTS_RUN] $test_name...${RESET} "
+
+    local output
+    output=$(eval "$test_func" 2>&1)
+    local rc=$?
+
+    if [[ $rc -eq 0 ]]; then
+        echo "${GREEN}PASS${RESET}"
+        TESTS_PASSED=$((TESTS_PASSED + 1))
+    elif [[ $rc -eq 77 ]]; then
+        echo "${YELLOW}SKIP${RESET}"
+    else
+        echo "${RED}FAIL${RESET}"
+        [[ -n "$output" ]] && echo "    ${DIM}${output:0:300}${RESET}"
+        TESTS_FAILED=$((TESTS_FAILED + 1))
+    fi
+}
+
+# ============================================================================
+# SETUP
+# ============================================================================
+
+echo ""
+echo "${CYAN}══════════════════════════════════════════════════════════════${RESET}"
+echo "${CYAN}  E2E: Agenda / Schedule Layer${RESET}"
+echo "${CYAN}══════════════════════════════════════════════════════════════${RESET}"
+echo ""
+
+FLOW_QUIET=1
+FLOW_ATLAS_ENABLED=no
+FLOW_SCHEDULE_NO_CACHE=1
+FLOW_PLUGIN_DIR="$PROJECT_ROOT"
+source "$PROJECT_ROOT/flow.plugin.zsh" 2>/dev/null || {
+    echo "${RED}Failed to load plugin${RESET}"
+    exit 1
+}
+
+exec < /dev/null
+zmodload zsh/datetime 2>/dev/null
+
+# Date anchors relative to "today" so the suite never goes stale
+TODAY=$(strftime '%Y-%m-%d' $EPOCHSECONDS)
+PAST=$(_date_add_days "$TODAY" -2)      # overdue
+SOON=$(_date_add_days "$TODAY" 3)       # this week
+FAR=$(_date_add_days "$TODAY" 20)       # later (outside 7d)
+HOL=$(_date_add_days "$TODAY" 2)        # holiday in-window
+
+# Isolated project root with a research project and a dev-category project
+TEST_ROOT=$(mktemp -d)
+EMPTY_ROOT=$(mktemp -d)
+mkdir -p "$TEST_ROOT/research/paper-x" "$TEST_ROOT/webapp"
+
+cat > "$TEST_ROOT/research/paper-x/.STATUS" <<EOF
+## Status: active
+
+## Schedule:
+- $PAST | Overdue reviewer response | research
+- $TODAY | Submit revision today | research
+- $SOON | Beta milestone | general
+- $FAR | Grant LOI deadline | research
+- weekly:mon | Advisor meeting | research
+EOF
+
+# webapp is detected as a 'dev' project but carries a research-typed item plus
+# a holiday and a label that contains a pipe.
+cat > "$TEST_ROOT/webapp/.STATUS" <<EOF
+## Status: active
+
+## Schedule:
+- $SOON | Ship v2 | general
+- $SOON | Fix bug | crash | research
+- $HOL | Fall Break | holiday
+EOF
+
+FLOW_PROJECTS_ROOT="$TEST_ROOT"
+
+ORIGINAL_DIR=$(pwd)
+cleanup() {
+    cd "$ORIGINAL_DIR"
+    rm -rf "$TEST_ROOT" "$EMPTY_ROOT"
+}
+trap cleanup EXIT
+
+# ============================================================================
+# SECTION 1: agenda windows
+# ============================================================================
+
+echo "${CYAN}--- Section 1: Windows ---${RESET}"
+
+run_test "agenda -h exits 0 and shows usage" '
+    local output rc
+    output=$(agenda -h 2>&1); rc=$?
+    [[ $rc -eq 0 ]] || { echo "rc=$rc"; return 1; }
+    [[ "$output" == *"AGENDA"* ]] || return 1
+'
+
+run_test "agenda (default) shows buckets + in-window items, hides far item" '
+    local output
+    output=$(agenda 2>&1)
+    [[ "$output" == *"OVERDUE"* ]] || { echo "no OVERDUE"; return 1; }
+    [[ "$output" == *"Submit revision today"* ]] || { echo "no today item"; return 1; }
+    [[ "$output" == *"Beta milestone"* ]] || { echo "no soon item"; return 1; }
+    [[ "$output" != *"Grant LOI deadline"* ]] || { echo "far item leaked at 7d"; return 1; }
+'
+
+run_test "agenda --overdue shows only overdue" '
+    local output
+    output=$(agenda --overdue 2>&1)
+    [[ "$output" == *"Overdue reviewer response"* ]] || return 1
+    [[ "$output" != *"Beta milestone"* ]] || { echo "soon item leaked"; return 1; }
+'
+
+run_test "agenda today shows today + overdue, hides future" '
+    local output
+    output=$(agenda today 2>&1)
+    [[ "$output" == *"Submit revision today"* ]] || return 1
+    [[ "$output" == *"Overdue reviewer response"* ]] || return 1
+    [[ "$output" != *"Beta milestone"* ]] || { echo "future leaked"; return 1; }
+'
+
+run_test "agenda -m includes the LATER far item" '
+    local output
+    output=$(agenda -m 2>&1)
+    [[ "$output" == *"Grant LOI deadline"* ]] || return 1
+    [[ "$output" == *"LATER"* ]] || return 1
+'
+
+# ============================================================================
+# SECTION 2: filters (type + category)
+# ============================================================================
+
+echo ""
+echo "${CYAN}--- Section 2: Filters ---${RESET}"
+
+run_test "agenda research matches a research item in a dev-category project" '
+    local output
+    output=$(agenda research 2>&1)
+    [[ "$output" == *"Fix bug"* ]] || { echo "cross-category research item missing"; return 1; }
+    [[ "$output" != *"Ship v2"* ]] || { echo "general item leaked into research"; return 1; }
+'
+
+run_test "agenda general is accepted (not unknown) and filters by type" '
+    local output
+    output=$(agenda general 2>&1)
+    [[ "$output" != *"Unknown"* ]] || { echo "general rejected"; return 1; }
+    [[ "$output" == *"Beta milestone"* ]] || return 1
+    [[ "$output" != *"Overdue reviewer response"* ]] || { echo "research leaked into general"; return 1; }
+'
+
+# ============================================================================
+# SECTION 3: holidays + recurring + pipe-in-label
+# ============================================================================
+
+echo ""
+echo "${CYAN}--- Section 3: Holidays / recurring / pipe label ---${RESET}"
+
+run_test "agenda (default) hides holiday-typed items" '
+    local output
+    output=$(agenda -m 2>&1)
+    [[ "$output" != *"Fall Break"* ]] || { echo "holiday shown without --all"; return 1; }
+'
+
+run_test "agenda --all reveals holiday-typed items" '
+    local output
+    output=$(agenda --all 2>&1)
+    [[ "$output" == *"Fall Break"* ]] || { echo "holiday hidden under --all"; return 1; }
+'
+
+run_test "recurring weekly:mon expands into a concrete dated occurrence" '
+    local output
+    output=$(agenda -m 2>&1)
+    [[ "$output" == *"Advisor meeting"* ]] || return 1
+'
+
+run_test "label containing a pipe renders sanitized, type intact" '
+    local output
+    output=$(agenda research 2>&1)
+    [[ "$output" == *"Fix bug / crash"* ]] || { echo "pipe not sanitized: $output"; return 1; }
+'
+
+# ============================================================================
+# SECTION 4: empty state + atlas-disabled
+# ============================================================================
+
+echo ""
+echo "${CYAN}--- Section 4: Empty state ---${RESET}"
+
+run_test "agenda shows a calm empty state when nothing is scheduled" '
+    local output
+    output=$(FLOW_PROJECTS_ROOT="$EMPTY_ROOT" agenda 2>&1)
+    [[ "$output" == *"Nothing scheduled"* ]] || return 1
+'
+
+run_test "agenda emits no error markers (atlas disabled)" '
+    local output
+    output=$(agenda 2>&1)
+    [[ "$output" != *"command not found"* ]] || return 1
+    [[ "$output" != *"no such"* ]] || return 1
+    [[ "$output" != *"parse error"* ]] || return 1
+'
+
+# ============================================================================
+# SECTION 5: dash + cadence integration
+# ============================================================================
+
+echo ""
+echo "${CYAN}--- Section 5: dash + cadence surfaces ---${RESET}"
+
+run_test "dash includes an UPCOMING section fed by the engine" '
+    local output
+    output=$(dash 2>&1)
+    [[ "$output" == *"UPCOMING"* ]] || { echo "no UPCOMING in dash"; return 1; }
+    [[ "$output" == *"Submit revision today"* ]] || return 1
+'
+
+run_test "dash UPCOMING self-suppresses with no schedule data" '
+    local output
+    output=$(FLOW_PROJECTS_ROOT="$EMPTY_ROOT" dash 2>&1)
+    [[ "$output" != *"UPCOMING"* ]] || { echo "empty UPCOMING header leaked"; return 1; }
+'
+
+run_test "today shows a Due today block" '
+    local output
+    output=$(today 2>&1)
+    [[ "$output" == *"Due today"* ]] || return 1
+    [[ "$output" == *"Submit revision today"* ]] || return 1
+'
+
+run_test "week shows This week deadlines grouped by weekday" '
+    local output
+    output=$(week 2>&1)
+    [[ "$output" == *"This week"*"deadlines"* ]] || return 1
+    [[ "$output" == *"Beta milestone"* ]] || return 1
+'
+
+run_test "morning includes the upcoming block without error" '
+    local output
+    output=$(morning 2>&1)
+    [[ "$output" != *"command not found"* ]] || return 1
+    [[ "$output" == *"Beta milestone"* ]] || { echo "morning missing upcoming item"; return 1; }
+'
+
+# ============================================================================
+# SECTION 6: teaching path (yq-gated)
+# ============================================================================
+
+echo ""
+echo "${CYAN}--- Section 6: Teaching config (yq-gated) ---${RESET}"
+
+run_test "teach-config items surface in agenda when yq present" '
+    command -v yq >/dev/null 2>&1 || return 77
+    local fixture="$PROJECT_ROOT/tests/fixtures/teach-config-scheduled.yml"
+    [[ -f "$fixture" ]] || return 77
+    mkdir -p "$TEST_ROOT/teaching/stat-202/.flow"
+    cp "$fixture" "$TEST_ROOT/teaching/stat-202/.flow/teach-config.yml"
+    # A project is discovered via its .STATUS file (real teach projects have one)
+    printf "## Status: active\n" > "$TEST_ROOT/teaching/stat-202/.STATUS"
+    local output
+    output=$(agenda --all 2>&1)
+    rm -rf "$TEST_ROOT/teaching"
+    [[ "$output" == *"Week"* ]] || { echo "no teaching week records"; return 1; }
+'
+
+# ============================================================================
+# SUMMARY
+# ============================================================================
+
+echo ""
+cd "$ORIGINAL_DIR"
+echo "${CYAN}══════════════════════════════════════════════════════════════${RESET}"
+if [[ $TESTS_FAILED -eq 0 ]]; then
+    echo "${GREEN}All $TESTS_PASSED/$TESTS_RUN e2e tests passed${RESET}"
+    exit 0
+else
+    echo "${RED}$TESTS_FAILED/$TESTS_RUN tests failed (${TESTS_PASSED} passed)${RESET}"
+    exit 1
+fi
diff --git a/tests/run-all.sh b/tests/run-all.sh
index 0832d5dd0..4edc5b719 100755
--- a/tests/run-all.sh
+++ b/tests/run-all.sh
@@ -123,6 +123,7 @@ run_test ./tests/dogfood-teach-doctor-v2.zsh
 run_test ./tests/dogfood-em-dispatcher.zsh
 run_test ./tests/dogfood-atlas-bridge.zsh
 run_test ./tests/dogfood-scholar-config-sync.zsh
+run_test ./tests/dogfood-agenda.zsh
 
 echo ""
 echo "E2E tests:"
@@ -138,6 +139,7 @@ run_test ./tests/e2e-em-dispatcher.zsh
 run_test ./tests/e2e-atlas-bridge.zsh
 run_test ./tests/e2e-scholar-config-sync.zsh
 run_test ./tests/e2e-tok-sync.zsh
+run_test ./tests/e2e-agenda.zsh
 
 echo ""
 echo "Atlas contract tests:"

From e2cb5724fd77da9efaa867df3e8f61e5fd4b3ee5 Mon Sep 17 00:00:00 2001
From: Test User <test@example.com>
Date: Sat, 13 Jun 2026 17:03:19 -0600
Subject: [PATCH 13/15] chore(release): bump version to v7.10.0 + agenda
 CHANGELOG

Forward-looking schedule layer (agenda command + dash UPCOMING + cadence
enrichment) ships as a minor bump. Updates FLOW_VERSION, package.json,
CLAUDE.md, and all man-page .TH lines; adds mirrored CHANGELOG entries
(root + docs); refreshes suite/test-file counts (64/64, 213 files).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md       | 41 +++++++++++++++++++++++++++++++++++++++++
 CLAUDE.md          | 10 +++++-----
 docs/CHANGELOG.md  | 41 +++++++++++++++++++++++++++++++++++++++++
 flow.plugin.zsh    |  2 +-
 man/man1/agenda.1  |  2 +-
 man/man1/at.1      |  2 +-
 man/man1/cc.1      |  2 +-
 man/man1/dash.1    |  2 +-
 man/man1/dots.1    |  2 +-
 man/man1/em.1      |  2 +-
 man/man1/flow.1    |  2 +-
 man/man1/g.1       |  2 +-
 man/man1/mcp.1     |  2 +-
 man/man1/morning.1 |  2 +-
 man/man1/prompt.1  |  2 +-
 man/man1/qu.1      |  2 +-
 man/man1/r.1       |  2 +-
 man/man1/sec.1     |  2 +-
 man/man1/teach.1   |  2 +-
 man/man1/tm.1      |  2 +-
 man/man1/today.1   |  2 +-
 man/man1/tok.1     |  2 +-
 man/man1/v.1       |  2 +-
 man/man1/week.1    |  2 +-
 man/man1/wt.1      |  2 +-
 package.json       |  2 +-
 26 files changed, 110 insertions(+), 28 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5999ec7c1..065814fbc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,47 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [7.10.0] — 2026-06-13 — forward-looking schedule layer (`agenda` + dash UPCOMING)
+
+### Added
+
+- **`agenda` command** (`commands/agenda.zsh`) — a forward-looking view of dated
+  activity across all projects: deadlines, exams, milestones, and recurring blocks.
+  Buckets results into **OVERDUE / TODAY / THIS WEEK / LATER** with a calm empty
+  state. Windows: default/`-w` (7d), `today` (0d), `-m` (30d), `--all` (uncapped +
+  holidays), `--overdue` (overdue only). Category/type filters
+  (`research`/`general`/`recurring`/`teach`/`dev`/`r`/`quarto`/`apps`) match the
+  record **type** OR the project category. Aliases: `agt`/`agw`/`agm`.
+- **Shared schedule engine** (`lib/schedule.zsh`) — pure-ZSH, no `yq`/atlas required.
+  Parses an optional `## Schedule:` section in each project's `.STATUS`
+  (`- <when> | <label> [| <type>]`, where `<when>` is an ISO date or `weekly:<dow>`),
+  derives teaching dates from `.flow/teach-config.yml` when `yq` is present, expands
+  `weekly:` recurrences into concrete dates (month/year-rollover safe), and emits
+  normalized `date|label|type|project|recurrence|source` records. Opportunistically
+  pushes to atlas (capability-probed, async, silent no-op when unsupported).
+- **`dash` UPCOMING section** — surfaces in-window + overdue items after QUICK WINS;
+  self-suppresses when nothing is scheduled.
+- **`morning`/`today`/`week` enrichment** — dated blocks (next-7d + overdue,
+  "Due today", "This week's deadlines" grouped by weekday) fed by the same engine.
+- **Man pages** for `agenda`, `dash`, `morning`, `today`, `week`; `_agenda`
+  completion; `docs/guides/AGENDA-SCHEDULE-GUIDE.md`.
+- **Tests** — `test-schedule`, `test-agenda`, `test-cadence-agenda`, plus a dedicated
+  `e2e-agenda` (19 behavioral tests) + `dogfood-agenda` (15 structural tests) pair.
+
+### Fixed
+
+- **`dash` aborted in non-TTY / captured-output contexts** — three
+  `$(( cond ? 's' : '' ))` arithmetic-string ternaries in `_dash_right_now` were
+  fatal in non-interactive shells, suppressing the dashboard before the UPCOMING
+  section rendered. Replaced with the safe `$( (( cond )) && echo s )` idiom.
+- **Schedule parser** — labels containing `|` are now preserved (sanitized to `/`)
+  instead of being mis-split into the type field; the type is only taken from the
+  last field when it is a known token.
+- **Holiday filtering** routes through `_schedule_drop_holidays` (type-field match)
+  instead of a substring `grep`, so labels mentioning "holiday" are no longer hidden.
+- **Schedule cache key** now includes `FLOW_PROJECTS_ROOT`, preventing stale results
+  when the project root changes within a session.
+
 ## [7.9.0] — 2026-06-05 — obs dispatcher removed + binary-precedence guard
 
 ### Removed
diff --git a/CLAUDE.md b/CLAUDE.md
index 17a783eda..c775e6054 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -7,7 +7,7 @@ This file provides guidance to Claude Code when working with code in this reposi
 **flow-cli** - Pure ZSH plugin for ADHD-optimized workflow management. Zero dependencies. Standalone (works without Oh-My-Zsh or any plugin manager).
 
 - **Architecture:** Pure ZSH plugin (no Node.js runtime required)
-- **Current Version:** v7.9.0
+- **Current Version:** v7.10.0
 - **Install:** Homebrew (recommended), or any plugin manager
 - **Source:** `source /opt/homebrew/opt/flow-cli/flow.plugin.zsh` (via Homebrew)
 - **Optional:** Atlas integration for enhanced state management
@@ -136,7 +136,7 @@ flow-cli/
 ├── docs/                     # Documentation (MkDocs)
 │   └── internal/             # Internal conventions & contributor templates
 ├── scripts/                  # Standalone validators (check-math.zsh)
-├── tests/                    # 211 test files, 12000+ test functions
+├── tests/                    # 213 test files, 12000+ test functions
 │   └── fixtures/demo-course/ # STAT-101 demo course for E2E
 └── .archive/                 # Archived Node.js CLI
 ```
@@ -181,7 +181,7 @@ flow-cli/
 
 ## Testing
 
-**211 test files, 12000+ test functions.** Run: `./tests/run-all.sh` (59/59 passing, 1 expected interactive/tmux timeout) or individual suites in `tests/`.
+**213 test files, 12000+ test functions.** Run: `./tests/run-all.sh` (64/64 passing, 1 expected interactive/tmux timeout) or individual suites in `tests/`.
 
 See `docs/guides/TESTING.md` for patterns, mocks, assertions, TDD workflow.
 
@@ -215,8 +215,8 @@ export FLOW_FORCE_DISPATCHER_OBS=1           # Force-keep one dispatcher (FLOW_F
 
 ## Current Status
 
-**Version:** v7.9.0 | **Tests:** 12000+ (59/59 suite, 1 interactive timeout) | **Docs:** https://Data-Wise.github.io/flow-cli/
+**Version:** v7.10.0 | **Tests:** 12000+ (64/64 suite, 1 interactive timeout) | **Docs:** https://Data-Wise.github.io/flow-cli/
 
 ---
 
-**Last Updated:** 2026-06-04 (v7.9.0)
+**Last Updated:** 2026-06-13 (v7.10.0)
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index 09a422c06..44422dacb 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -8,6 +8,47 @@ The format follows [Keep a Changelog](https://keepachangelog.com/), and this pro
 
 ## [Unreleased]
 
+## [7.10.0] — 2026-06-13 — forward-looking schedule layer (`agenda` + dash UPCOMING)
+
+### Added
+
+- **`agenda` command** (`commands/agenda.zsh`) — a forward-looking view of dated
+  activity across all projects: deadlines, exams, milestones, and recurring blocks.
+  Buckets results into **OVERDUE / TODAY / THIS WEEK / LATER** with a calm empty
+  state. Windows: default/`-w` (7d), `today` (0d), `-m` (30d), `--all` (uncapped +
+  holidays), `--overdue` (overdue only). Category/type filters
+  (`research`/`general`/`recurring`/`teach`/`dev`/`r`/`quarto`/`apps`) match the
+  record **type** OR the project category. Aliases: `agt`/`agw`/`agm`.
+- **Shared schedule engine** (`lib/schedule.zsh`) — pure-ZSH, no `yq`/atlas required.
+  Parses an optional `## Schedule:` section in each project's `.STATUS`
+  (`- <when> | <label> [| <type>]`, where `<when>` is an ISO date or `weekly:<dow>`),
+  derives teaching dates from `.flow/teach-config.yml` when `yq` is present, expands
+  `weekly:` recurrences into concrete dates (month/year-rollover safe), and emits
+  normalized `date|label|type|project|recurrence|source` records. Opportunistically
+  pushes to atlas (capability-probed, async, silent no-op when unsupported).
+- **`dash` UPCOMING section** — surfaces in-window + overdue items after QUICK WINS;
+  self-suppresses when nothing is scheduled.
+- **`morning`/`today`/`week` enrichment** — dated blocks (next-7d + overdue,
+  "Due today", "This week's deadlines" grouped by weekday) fed by the same engine.
+- **Man pages** for `agenda`, `dash`, `morning`, `today`, `week`; `_agenda`
+  completion; `docs/guides/AGENDA-SCHEDULE-GUIDE.md`.
+- **Tests** — `test-schedule`, `test-agenda`, `test-cadence-agenda`, plus a dedicated
+  `e2e-agenda` (19 behavioral tests) + `dogfood-agenda` (15 structural tests) pair.
+
+### Fixed
+
+- **`dash` aborted in non-TTY / captured-output contexts** — three
+  `$(( cond ? 's' : '' ))` arithmetic-string ternaries in `_dash_right_now` were
+  fatal in non-interactive shells, suppressing the dashboard before the UPCOMING
+  section rendered. Replaced with the safe `$( (( cond )) && echo s )` idiom.
+- **Schedule parser** — labels containing `|` are now preserved (sanitized to `/`)
+  instead of being mis-split into the type field; the type is only taken from the
+  last field when it is a known token.
+- **Holiday filtering** routes through `_schedule_drop_holidays` (type-field match)
+  instead of a substring `grep`, so labels mentioning "holiday" are no longer hidden.
+- **Schedule cache key** now includes `FLOW_PROJECTS_ROOT`, preventing stale results
+  when the project root changes within a session.
+
 ## [7.9.0] — 2026-06-05 — obs dispatcher removed + binary-precedence guard
 
 ### Removed
diff --git a/flow.plugin.zsh b/flow.plugin.zsh
index 17626f2b2..d7f6661f4 100644
--- a/flow.plugin.zsh
+++ b/flow.plugin.zsh
@@ -186,7 +186,7 @@ _flow_plugin_init
 
 # Export loaded marker
 export FLOW_PLUGIN_LOADED=1
-export FLOW_VERSION="7.9.0"
+export FLOW_VERSION="7.10.0"
 
 # Register exit hook for plugin cleanup
 add-zsh-hook zshexit _flow_plugin_cleanup
diff --git a/man/man1/agenda.1 b/man/man1/agenda.1
index cb3eea5ea..2fdb50cea 100644
--- a/man/man1/agenda.1
+++ b/man/man1/agenda.1
@@ -1,6 +1,6 @@
 .\" Man page for the agenda command (forward-looking schedule view)
 .\" Updated: June 2026
-.TH AGENDA 1 "June 2026" "flow-cli 7.9.0" "User Commands"
+.TH AGENDA 1 "June 2026" "flow-cli 7.10.0" "User Commands"
 .SH NAME
 agenda \- forward-looking schedule across all projects
 .SH SYNOPSIS
diff --git a/man/man1/at.1 b/man/man1/at.1
index aba92204e..8cee58c20 100644
--- a/man/man1/at.1
+++ b/man/man1/at.1
@@ -1,6 +1,6 @@
 .\" Man page for at dispatcher (Atlas bridge)
 .\" Generated: June 2026
-.TH AT 1 "June 2026" "flow-cli 7.9.0" "User Commands"
+.TH AT 1 "June 2026" "flow-cli 7.10.0" "User Commands"
 .SH NAME
 at \- Atlas project intelligence bridge (optional integration)
 .SH SYNOPSIS
diff --git a/man/man1/cc.1 b/man/man1/cc.1
index c215fed99..045b3a460 100644
--- a/man/man1/cc.1
+++ b/man/man1/cc.1
@@ -1,6 +1,6 @@
 .\" Man page for cc dispatcher (Claude Code launcher)
 .\" Generated: June 2026
-.TH CC 1 "June 2026" "flow-cli 7.9.0" "User Commands"
+.TH CC 1 "June 2026" "flow-cli 7.10.0" "User Commands"
 .SH NAME
 cc \- Claude Code launcher and dispatcher
 .SH SYNOPSIS
diff --git a/man/man1/dash.1 b/man/man1/dash.1
index bfd1fb1af..fd19b599b 100644
--- a/man/man1/dash.1
+++ b/man/man1/dash.1
@@ -1,6 +1,6 @@
 .\" Man page for the dash command (project dashboard)
 .\" Updated: June 2026
-.TH DASH 1 "June 2026" "flow-cli 7.9.0" "User Commands"
+.TH DASH 1 "June 2026" "flow-cli 7.10.0" "User Commands"
 .SH NAME
 dash \- ADHD-friendly project dashboard
 .SH SYNOPSIS
diff --git a/man/man1/dots.1 b/man/man1/dots.1
index 3e5ed2c39..8c51025ff 100644
--- a/man/man1/dots.1
+++ b/man/man1/dots.1
@@ -1,6 +1,6 @@
 .\" Man page for dots dispatcher (Dotfile Management)
 .\" Generated: June 2026
-.TH DOTS 1 "June 2026" "flow-cli 7.9.0" "User Commands"
+.TH DOTS 1 "June 2026" "flow-cli 7.10.0" "User Commands"
 .SH NAME
 dots \- Dotfile management dispatcher (chezmoi wrapper)
 .SH SYNOPSIS
diff --git a/man/man1/em.1 b/man/man1/em.1
index c8308a6a0..9dd8aab73 100644
--- a/man/man1/em.1
+++ b/man/man1/em.1
@@ -1,6 +1,6 @@
 .\" Man page for em dispatcher (Email / himalaya)
 .\" Generated: June 2026
-.TH EM 1 "June 2026" "flow-cli 7.9.0" "User Commands"
+.TH EM 1 "June 2026" "flow-cli 7.10.0" "User Commands"
 .SH NAME
 em \- Email dispatcher (himalaya wrapper)
 .SH SYNOPSIS
diff --git a/man/man1/flow.1 b/man/man1/flow.1
index 7e1ff9f0b..7f65098ff 100644
--- a/man/man1/flow.1
+++ b/man/man1/flow.1
@@ -1,6 +1,6 @@
 .\" Man page for flow command
 .\" Updated: June 2026
-.TH FLOW 1 "June 2026" "flow-cli 7.9.0" "User Commands"
+.TH FLOW 1 "June 2026" "flow-cli 7.10.0" "User Commands"
 .SH NAME
 flow \- ADHD-friendly workflow CLI for developers
 .SH SYNOPSIS
diff --git a/man/man1/g.1 b/man/man1/g.1
index 34d7e8fe7..c519320b2 100644
--- a/man/man1/g.1
+++ b/man/man1/g.1
@@ -1,6 +1,6 @@
 .\" Man page for g dispatcher (Git workflows)
 .\" Updated: June 2026
-.TH G 1 "June 2026" "flow-cli 7.9.0" "User Commands"
+.TH G 1 "June 2026" "flow-cli 7.10.0" "User Commands"
 .SH NAME
 g \- Git commands dispatcher
 .SH SYNOPSIS
diff --git a/man/man1/mcp.1 b/man/man1/mcp.1
index 2079ad676..fd507991e 100644
--- a/man/man1/mcp.1
+++ b/man/man1/mcp.1
@@ -1,6 +1,6 @@
 .\" Man page for mcp dispatcher (MCP server management)
 .\" Updated: June 2026
-.TH MCP 1 "June 2026" "flow-cli 7.9.0" "User Commands"
+.TH MCP 1 "June 2026" "flow-cli 7.10.0" "User Commands"
 .SH NAME
 mcp \- MCP server management dispatcher
 .SH SYNOPSIS
diff --git a/man/man1/morning.1 b/man/man1/morning.1
index 5db25a646..9f71a7a3e 100644
--- a/man/man1/morning.1
+++ b/man/man1/morning.1
@@ -1,6 +1,6 @@
 .\" Man page for the morning command (daily startup routine)
 .\" Updated: June 2026
-.TH MORNING 1 "June 2026" "flow-cli 7.9.0" "User Commands"
+.TH MORNING 1 "June 2026" "flow-cli 7.10.0" "User Commands"
 .SH NAME
 morning \- ADHD-friendly daily startup routine
 .SH SYNOPSIS
diff --git a/man/man1/prompt.1 b/man/man1/prompt.1
index f306a0da1..c2df84b54 100644
--- a/man/man1/prompt.1
+++ b/man/man1/prompt.1
@@ -1,6 +1,6 @@
 .\" Man page for prompt dispatcher (Prompt Engine Switcher)
 .\" Generated: June 2026
-.TH PROMPT 1 "June 2026" "flow-cli 7.9.0" "User Commands"
+.TH PROMPT 1 "June 2026" "flow-cli 7.10.0" "User Commands"
 .SH NAME
 prompt \- Prompt engine switcher
 .SH SYNOPSIS
diff --git a/man/man1/qu.1 b/man/man1/qu.1
index 72fc757f4..971827cd3 100644
--- a/man/man1/qu.1
+++ b/man/man1/qu.1
@@ -1,6 +1,6 @@
 .\" Man page for qu dispatcher (Quarto publishing)
 .\" Updated: June 2026
-.TH QU 1 "June 2026" "flow-cli 7.9.0" "User Commands"
+.TH QU 1 "June 2026" "flow-cli 7.10.0" "User Commands"
 .SH NAME
 qu \- Quarto publishing dispatcher
 .SH SYNOPSIS
diff --git a/man/man1/r.1 b/man/man1/r.1
index b4e21ce56..9bb4e34b2 100644
--- a/man/man1/r.1
+++ b/man/man1/r.1
@@ -1,6 +1,6 @@
 .\" Man page for r dispatcher (R package development)
 .\" Updated: June 2026
-.TH R 1 "June 2026" "flow-cli 7.9.0" "User Commands"
+.TH R 1 "June 2026" "flow-cli 7.10.0" "User Commands"
 .SH NAME
 r \- R package development dispatcher
 .SH SYNOPSIS
diff --git a/man/man1/sec.1 b/man/man1/sec.1
index 7da52330d..3dc5078d5 100644
--- a/man/man1/sec.1
+++ b/man/man1/sec.1
@@ -1,6 +1,6 @@
 .\" Man page for sec dispatcher (Secret Management)
 .\" Generated: June 2026
-.TH SEC 1 "June 2026" "flow-cli 7.9.0" "User Commands"
+.TH SEC 1 "June 2026" "flow-cli 7.10.0" "User Commands"
 .SH NAME
 sec \- Secret management dispatcher (Keychain and Bitwarden)
 .SH SYNOPSIS
diff --git a/man/man1/teach.1 b/man/man1/teach.1
index 01d94e0a6..822655a2d 100644
--- a/man/man1/teach.1
+++ b/man/man1/teach.1
@@ -1,6 +1,6 @@
 .\" Man page for teach dispatcher (Teaching Workflow)
 .\" Generated: June 2026
-.TH TEACH 1 "June 2026" "flow-cli 7.9.0" "User Commands"
+.TH TEACH 1 "June 2026" "flow-cli 7.10.0" "User Commands"
 .SH NAME
 teach \- Teaching workflow dispatcher (Scholar integration)
 .SH SYNOPSIS
diff --git a/man/man1/tm.1 b/man/man1/tm.1
index 49efcc372..8ebda68ad 100644
--- a/man/man1/tm.1
+++ b/man/man1/tm.1
@@ -1,6 +1,6 @@
 .\" Man page for tm dispatcher (Terminal Manager)
 .\" Generated: June 2026
-.TH TM 1 "June 2026" "flow-cli 7.9.0" "User Commands"
+.TH TM 1 "June 2026" "flow-cli 7.10.0" "User Commands"
 .SH NAME
 tm \- Terminal manager dispatcher
 .SH SYNOPSIS
diff --git a/man/man1/today.1 b/man/man1/today.1
index 0d398f3de..56e36b6af 100644
--- a/man/man1/today.1
+++ b/man/man1/today.1
@@ -1,6 +1,6 @@
 .\" Man page for the today command (quick daily status)
 .\" Updated: June 2026
-.TH TODAY 1 "June 2026" "flow-cli 7.9.0" "User Commands"
+.TH TODAY 1 "June 2026" "flow-cli 7.10.0" "User Commands"
 .SH NAME
 today \- quick daily status
 .SH SYNOPSIS
diff --git a/man/man1/tok.1 b/man/man1/tok.1
index c98e5d276..24d569836 100644
--- a/man/man1/tok.1
+++ b/man/man1/tok.1
@@ -1,6 +1,6 @@
 .\" Man page for tok dispatcher (Token Management)
 .\" Generated: June 2026
-.TH TOK 1 "June 2026" "flow-cli 7.9.0" "User Commands"
+.TH TOK 1 "June 2026" "flow-cli 7.10.0" "User Commands"
 .SH NAME
 tok \- Token lifecycle management dispatcher
 .SH SYNOPSIS
diff --git a/man/man1/v.1 b/man/man1/v.1
index 76087022d..437681aa2 100644
--- a/man/man1/v.1
+++ b/man/man1/v.1
@@ -1,6 +1,6 @@
 .\" Man page for v dispatcher (Vibe / Workflow Automation)
 .\" Generated: June 2026
-.TH V 1 "June 2026" "flow-cli 7.9.0" "User Commands"
+.TH V 1 "June 2026" "flow-cli 7.10.0" "User Commands"
 .SH NAME
 v \- Workflow automation dispatcher (vibe coding mode)
 .SH SYNOPSIS
diff --git a/man/man1/week.1 b/man/man1/week.1
index ef7224954..59aa16be5 100644
--- a/man/man1/week.1
+++ b/man/man1/week.1
@@ -1,6 +1,6 @@
 .\" Man page for the week command (weekly review helper)
 .\" Updated: June 2026
-.TH WEEK 1 "June 2026" "flow-cli 7.9.0" "User Commands"
+.TH WEEK 1 "June 2026" "flow-cli 7.10.0" "User Commands"
 .SH NAME
 week \- weekly review helper
 .SH SYNOPSIS
diff --git a/man/man1/wt.1 b/man/man1/wt.1
index 4762a6b8a..25a7bae74 100644
--- a/man/man1/wt.1
+++ b/man/man1/wt.1
@@ -1,6 +1,6 @@
 .\" Man page for wt dispatcher (Git Worktree Management)
 .\" Generated: June 2026
-.TH WT 1 "June 2026" "flow-cli 7.9.0" "User Commands"
+.TH WT 1 "June 2026" "flow-cli 7.10.0" "User Commands"
 .SH NAME
 wt \- Git worktree management dispatcher
 .SH SYNOPSIS
diff --git a/package.json b/package.json
index 5e5ec61e9..a712291b7 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "flow-cli",
-  "version": "7.9.0",
+  "version": "7.10.0",
   "description": "ADHD-optimized ZSH workflow plugin",
   "private": true,
   "scripts": {

From 302e2113a315b50a7d30cdcc05f330eab573e817 Mon Sep 17 00:00:00 2001
From: Test User <test@example.com>
Date: Sat, 13 Jun 2026 17:15:57 -0600
Subject: [PATCH 14/15] refactor(schedule): share surface pipeline, drop
 grep-based counting

Review polish (non-blocking nits from the PR #463 review):

- Add _schedule_window_records (collect | filter-window | sort | drop-holidays)
  so dash UPCOMING, morning/today/week, and the quick count no longer each
  repeat the four-stage pipeline.
- Add _schedule_render_capped (renders a stream capped at N with a "+M more"
  footer), counting via an array split instead of `grep -c .`.
- Route _dash_upcoming, _flow_morning_agenda, _flow_today_agenda,
  _flow_week_agenda, and _flow_agenda_count through the helpers.

`agenda` itself keeps its own pipeline (category-aware + conditional holiday
drop for --all), so it is intentionally not folded in.

No behavior change. Verified: test-schedule 39/39, test-agenda 22/22,
test-cadence-agenda 6/6, test-dash 29/29, e2e-agenda 19/19, dogfood-agenda 15/15.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 commands/dash.zsh    | 20 +++----------------
 commands/morning.zsh | 36 ++++++++++------------------------
 lib/schedule.zsh     | 46 ++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 59 insertions(+), 43 deletions(-)

diff --git a/commands/dash.zsh b/commands/dash.zsh
index 6019b1c22..980fabbf0 100644
--- a/commands/dash.zsh
+++ b/commands/dash.zsh
@@ -422,28 +422,14 @@ _dash_quick_wins() {
 # work with `agenda` and the morning cadence within a session.
 _dash_upcoming() {
   # Engine may be absent in minimal sources; degrade silently.
-  typeset -f _schedule_collect >/dev/null 2>&1 || return 0
+  typeset -f _schedule_window_records >/dev/null 2>&1 || return 0
 
   local records
-  records=$(_schedule_collect "$SCHEDULE_DEFAULT_WINDOW" | _schedule_filter_window "$SCHEDULE_DEFAULT_WINDOW" | _schedule_sort)
-  [[ -n "$records" ]] && records=$(print -r -- "$records" | _schedule_drop_holidays)
+  records=$(_schedule_window_records "$SCHEDULE_DEFAULT_WINDOW")
   [[ -z "$records" ]] && return 0
 
   echo "  📅 ${FLOW_COLORS[bold]}UPCOMING${FLOW_COLORS[reset]} ${FLOW_COLORS[muted]}(next 7 days)${FLOW_COLORS[reset]}"
-
-  local count=0 max=4 rec
-  while IFS= read -r rec; do
-    [[ -z "$rec" ]] && continue
-    (( count >= max )) && break
-    _schedule_render_line "$rec"
-    ((count++))
-  done <<< "$records"
-
-  local total=$(print -r -- "$records" | grep -c .)
-  if (( total > max )); then
-    echo "  ${FLOW_COLORS[muted]}  +$((total - max)) more — run 'agenda' for the full view${FLOW_COLORS[reset]}"
-  fi
-
+  print -r -- "$records" | _schedule_render_capped 4 "run 'agenda' for the full view"
   echo ""
 }
 
diff --git a/commands/morning.zsh b/commands/morning.zsh
index aed2278d8..0de6e06c5 100644
--- a/commands/morning.zsh
+++ b/commands/morning.zsh
@@ -104,38 +104,24 @@ _flow_morning_projects() {
 # Upcoming dated items for the morning routine (top 5, 7-day window + overdue).
 # Self-suppresses when nothing is due. Driven by the shared schedule engine.
 _flow_morning_agenda() {
-  typeset -f _schedule_collect >/dev/null 2>&1 || return 0
+  typeset -f _schedule_window_records >/dev/null 2>&1 || return 0
 
   local records
-  records=$(_schedule_collect 7 | _schedule_filter_window 7 | _schedule_sort)
-  [[ -n "$records" ]] && records=$(print -r -- "$records" | _schedule_drop_holidays)
+  records=$(_schedule_window_records 7)
   [[ -z "$records" ]] && return 0
 
   echo ""
   echo "  ${FLOW_COLORS[muted]}Upcoming (next 7 days):${FLOW_COLORS[reset]}"
-
-  local count=0 rec
-  while IFS= read -r rec; do
-    [[ -z "$rec" ]] && continue
-    (( count >= 5 )) && break
-    _schedule_render_line "$rec"
-    ((count++))
-  done <<< "$records"
-
-  local total=$(print -r -- "$records" | grep -c .)
-  if (( total > 5 )); then
-    echo "  ${FLOW_COLORS[muted]}  +$((total - 5)) more — run 'agenda'${FLOW_COLORS[reset]}"
-  fi
+  print -r -- "$records" | _schedule_render_capped 5 "run 'agenda'"
 }
 
 # Count of in-window (7d + overdue) dated items, for the quick one-liner.
 _flow_agenda_count() {
-  typeset -f _schedule_collect >/dev/null 2>&1 || { echo 0; return 0; }
   local records
-  records=$(_schedule_collect 7 | _schedule_filter_window 7)
-  [[ -n "$records" ]] && records=$(print -r -- "$records" | _schedule_drop_holidays)
+  records=$(_schedule_window_records 7)
   [[ -z "$records" ]] && { echo 0; return 0; }
-  print -r -- "$records" | grep -c .
+  local -a lines=("${(@f)records}")
+  echo ${#lines}
 }
 
 _flow_morning_wins() {
@@ -253,11 +239,10 @@ today() {
 
 # Dated items due today plus anything overdue (window 0). Self-suppresses.
 _flow_today_agenda() {
-  typeset -f _schedule_collect >/dev/null 2>&1 || return 0
+  typeset -f _schedule_window_records >/dev/null 2>&1 || return 0
 
   local records
-  records=$(_schedule_collect 0 | _schedule_filter_window 0 | _schedule_sort)
-  [[ -n "$records" ]] && records=$(print -r -- "$records" | _schedule_drop_holidays)
+  records=$(_schedule_window_records 0)
   [[ -z "$records" ]] && return 0
 
   echo "  ${FLOW_COLORS[warning]}📅 Due today${FLOW_COLORS[reset]}"
@@ -307,11 +292,10 @@ week() {
 # This week's dated items (7-day window + overdue), grouped by weekday.
 # Self-suppresses when nothing is due.
 _flow_week_agenda() {
-  typeset -f _schedule_collect >/dev/null 2>&1 || return 0
+  typeset -f _schedule_window_records >/dev/null 2>&1 || return 0
 
   local records
-  records=$(_schedule_collect 7 | _schedule_filter_window 7 | _schedule_sort)
-  [[ -n "$records" ]] && records=$(print -r -- "$records" | _schedule_drop_holidays)
+  records=$(_schedule_window_records 7)
   [[ -z "$records" ]] && return 0
 
   echo "  ${FLOW_COLORS[accent]}📅 This week's deadlines:${FLOW_COLORS[reset]}"
diff --git a/lib/schedule.zsh b/lib/schedule.zsh
index 23d088bb0..83227010e 100644
--- a/lib/schedule.zsh
+++ b/lib/schedule.zsh
@@ -534,6 +534,52 @@ _schedule_render_line() {
     "$ticon" "$rel" "$label" "$rmark" "$project"
 }
 
+# =============================================================================
+# Function: _schedule_window_records
+# Purpose: The shared surface pipeline — collect, window-filter, sort, and drop
+#          holidays — in one place (dash UPCOMING, morning/today/week, counts).
+# Arguments:
+#   $1 - window in days [default: SCHEDULE_DEFAULT_WINDOW]
+# Output:
+#   stdout - the resulting record stream (empty when nothing is due)
+# Notes:
+#   - Returns 0 with no output when the engine is unavailable or nothing matches,
+#     so callers can `records=$(_schedule_window_records …); [[ -z … ]] && return`.
+# =============================================================================
+_schedule_window_records() {
+  local window="${1:-$SCHEDULE_DEFAULT_WINDOW}"
+  typeset -f _schedule_collect >/dev/null 2>&1 || return 0
+  _schedule_collect "$window" \
+    | _schedule_filter_window "$window" \
+    | _schedule_sort \
+    | _schedule_drop_holidays
+}
+
+# =============================================================================
+# Function: _schedule_render_capped
+# Purpose: Render a record stream (from stdin), capped at <max> lines, with a
+#          "+N more — <hint>" footer when truncated.
+# Arguments:
+#   $1 - max lines to render
+#   $2 - hint shown in the "+N more" footer (e.g. "run 'agenda'")
+# Input:  stdin  - record stream (newline-delimited)
+# Notes:
+#   - Counts via an array split (no `grep -c`); no-op on empty input.
+# =============================================================================
+_schedule_render_capped() {
+  local max="$1" hint="$2"
+  local input; input="$(cat)"
+  [[ -z "$input" ]] && return 0
+
+  local -a lines=("${(@f)input}")
+  local total=${#lines} i
+  for (( i = 1; i <= total && i <= max; i++ )); do
+    _schedule_render_line "${lines[i]}"
+  done
+  (( total > max )) && \
+    print -r -- "  ${FLOW_COLORS[muted]}  +$((total - max)) more — ${hint}${FLOW_COLORS[reset]}"
+}
+
 # ============================================================================
 # ATLAS (opportunistic, capability-detected)
 # ============================================================================

From bc39c990d3988c295d74a7ebedb6d0bfcd0a484a Mon Sep 17 00:00:00 2001
From: Test User <test@example.com>
Date: Sat, 13 Jun 2026 17:17:26 -0600
Subject: [PATCH 15/15] chore(agenda): remove ORCHESTRATE working artifact
 before dev merge

ORCHESTRATE-*.md files are feature-branch working artifacts and should not
land on dev (per CLAUDE.md merge-cleanup convention).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 ORCHESTRATE-agenda.md | 99 -------------------------------------------
 1 file changed, 99 deletions(-)
 delete mode 100644 ORCHESTRATE-agenda.md

diff --git a/ORCHESTRATE-agenda.md b/ORCHESTRATE-agenda.md
deleted file mode 100644
index 0697698ec..000000000
--- a/ORCHESTRATE-agenda.md
+++ /dev/null
@@ -1,99 +0,0 @@
-# ORCHESTRATE: agenda + forward-looking schedule layer
-
-> **Feature branch:** `feature/agenda` · **Base:** `dev` · **Worktree:** `~/.git-worktrees/flow-cli/agenda`
-> **Spec:** `docs/specs/SPEC-agenda-schedule-2026-06-13.md` (committed on `dev`)
-> **Plan:** `~/.claude/plans/eventual-bouncing-phoenix.md`
-> **Target version:** v7.10.0 (minor)
-
-## ⛔ Session boundary
-
-This file was created by the **planning session on `dev`**. Implementation happens **here, in a
-NEW `claude` session started from this worktree**:
-
-```bash
-cd ~/.git-worktrees/flow-cli/agenda && claude
-```
-
-Do NOT implement from the dev/planning session.
-
----
-
-## Goal
-
-Add a forward-looking schedule layer: new `agenda` command + UPCOMING section in `dash` +
-dated enrichment of `morning`/`today`/`week`, driven by one shared engine `lib/schedule.zsh`.
-Works fully without atlas and without `yq`. See the spec for the full rationale and data model.
-
-## Reuse (read-only — do NOT reinvent)
-
-- `lib/date-parser.zsh` → `_date_load_config` (teaching dates: `week_N`/`exam_*`/`deadline_*`/`holiday_*`), `_date_add_days`, `_date_normalize`, `_date_compute_from_week`.
-- `lib/atlas-bridge.zsh` → `_flow_has_atlas`, `_flow_atlas_async`, `_flow_list_projects`, `_flow_timestamp`.
-- `commands/dash.zsh` → `_dash_find_project_path`, `_dash_get_status_field`, `_dash_detect_category`, `_dash_get_urgency`.
-- `lib/core.zsh` → `FLOW_COLORS`. Cache pattern → `_dash_quick_health_check`.
-
-## Tasks (TDD: write/extend the test, then implement; `./tests/run-all.sh` + `source flow.plugin.zsh` green before each commit)
-
-### 1. Engine — `lib/schedule.zsh` (new)  → `tests/test-schedule.zsh`
-- [ ] Module guard `_FLOW_SCHEDULE_LOADED`; `typeset -g SCHEDULE_DEFAULT_WINDOW=7`.
-- [ ] `_schedule_classify <iso> [window]` → `overdue|today|soon|later`.
-- [ ] `_schedule_relative_days <iso>` → "today"/"in 3d"/"overdue 2d".
-- [ ] `_schedule_parse_status <status_file>` → records from `## Schedule:` (no external cmds); infers `project=${status_file:h:t}`.
-- [ ] `_schedule_teach_items <teach_config> <project> [window]` → `local -A CONFIG_DATES; eval "$(_date_load_config ...)"`; map week/exam/deadline; holidays typed `holiday` (filtered unless `--all`); guarded by `command -v yq` + file exists.
-- [ ] `_schedule_expand_recurring <weekly:dow> <start> <end>` → concrete dates (`strftime '%u'` + `_date_add_days`).
-- [ ] `_schedule_collect [window] [category]` → orchestrate over `_flow_list_projects`; emit record stream; session cache.
-- [ ] `_schedule_filter_window <window>` (stdin) → in-window + always overdue.
-- [ ] `_schedule_sort` (stdin) → `sort -t'|' -k1,1`.
-- [ ] `_schedule_render_line <record>` → type icon + urgency color + relative-day + label + dim project.
-- [ ] `_flow_schedule_to_atlas <record...>` → `_flow_has_atlas || return 0`; cap-probe `_FLOW_ATLAS_HAS_SCHEDULE`; `_flow_atlas_async`; no-op if absent.
-- **Tests:** parse block; empty/malformed → no crash; classify boundaries (frozen "today" arg); expand across **month+year** boundary; window filter; teach parse (fixture w/ `start_date`); **no-yq fallback**; **atlas-absent no-op** (mock `_flow_atlas_async` asserts not called).
-- **Footguns:** no `local path=` / `local status=`; `local -A CONFIG_DATES`; split with `${(f)...}`.
-
-### 2. Wiring — `flow.plugin.zsh`
-- [ ] Source `lib/date-parser.zsh` (if not already global) **then** `lib/schedule.zsh` in the core library block, after `atlas-bridge.zsh`.
-
-### 3. Command — `commands/agenda.zsh` (new)  → `tests/test-agenda.zsh`
-- [ ] `agenda [today|-w/--week|-m/--month|<category>|--all|--overdue|-h/--help]`; default = 7d.
-- [ ] Pipeline `_schedule_collect | _schedule_filter_window | _schedule_sort` → bucketed render (OVERDUE/TODAY/THIS WEEK/LATER) + calm empty state; then async atlas push.
-- [ ] `_agenda_help` (dash-style, `_C_*` locals). Aliases `agt`/`agw`/`agm` (avoid `ag`).
-- **Tests:** `-h`; default/`--overdue`/category/`--all`/`today` vs `-m`; empty state; `run_isolated` + `FLOW_ATLAS_ENABLED=no` + temp `FLOW_PROJECTS_ROOT`.
-
-### 4. dash — `commands/dash.zsh`  → extend `tests/test-dash.zsh`
-- [ ] `_dash_upcoming` (top 3–4, 7d + overdue); insert in `dash()` **after `_dash_quick_wins`, before `_dash_quick_access`**; self-suppress when empty.
-- [ ] Date-keyed session cache (~600s TTL) shared with agenda/morning.
-
-### 5. Cadence — `commands/morning.zsh`
-- [ ] `_flow_morning_agenda` in `morning` (top 5, 7d + overdue) between projects and wins; quick mode one-liner.
-- [ ] `today` → "📅 Due today" (0d) + overdue. `week` → "📅 This week's deadlines" (7d, by weekday).
-
-### 6. Packaging
-- [ ] `completions/_agenda` (model `completions/_dash`): flags + category states.
-- [ ] `man/man1/agenda.1` (model `man/man1/g.1`); `.TH` = `flow-cli <FLOW_VERSION>`.
-- [ ] **Patch `tests/test-manpage-version-sync.zsh`** orphan check: add `[[ "$base" == "agenda" ]] && continue` next to the `flow` skip (~line 223). REQUIRED or CI fails.
-- [ ] Register `tests/test-schedule.zsh` + `tests/test-agenda.zsh` in `tests/run-all.sh`.
-- [ ] Add a fixture `.flow/teach-config.yml` with `weeks[].start_date` (demo uses `weeks[].date` → yields no `week_N`).
-
-### 7. Docs
-- [ ] `CLAUDE.md` (command list + Quick Reference), `docs/help/QUICK-REFERENCE.md` (`agenda` + aliases + `## Schedule:` snippet).
-- [ ] `docs/reference/MASTER-DISPATCHER-GUIDE.md` (commands section; note dash UPCOMING + cadence enrichment).
-- [ ] New `docs/guides/AGENDA-SCHEDULE-GUIDE.md`; add to `mkdocs.yml` nav (strict build).
-- [ ] `docs/ATLAS-CONTRACT.md` — document opportunistic `atlas schedule push --format=json` contract.
-
-## Verification (before PR)
-
-1. `source flow.plugin.zsh` clean (no errors / leaked vars).
-2. `./tests/run-all.sh` green (new + touched suites; 1 expected interactive timeout).
-3. Manual: temp `FLOW_PROJECTS_ROOT` with a `## Schedule:` block + teach project w/ `start_date`; run
-   `agenda`, `agenda --overdue`, `agenda research`, `agenda -m`, `agenda -h`; verify buckets/overdue/filter/empty.
-4. `dash` shows UPCOMING after QUICK WINS; suppresses when none. `morning`/`today`/`week` show dated blocks.
-5. `FLOW_ATLAS_ENABLED=no agenda` fully works; atlas-without-`schedule` → silent no-op.
-6. `mkdocs build --strict` passes.
-
-## Integrate
-
-- [ ] `git fetch origin dev && git rebase origin/dev` → `./tests/run-all.sh` → `gh pr create --base dev`.
-- [ ] Bump version (v7.10.0) per release flow when merging dev→main.
-- [ ] **Delete this `ORCHESTRATE-agenda.md` as part of the merge cleanup** (working artifact — belongs on the feature branch, not on `dev`).
-
-## Out of scope (v1)
-
-Atlas-side `schedule` command (separate atlas PR); `monthly:`/multi-day recurrence; ICS export; interactive `agenda add`.