Merge pull request #376 from Data-Wise/dev

Release v7.0.0 — Email Dispatcher

Author: Data-Wise

.STATUS

@@ -4,25 +4,37 @@
 ## Project: flow-cli
 ## Type: zsh-plugin
 ## Status: active
-## Focus: PR #368 Review — Math Blanks Preflight
+## Focus: --help
 ## Phase: Active Development
 ## Priority: 2
-## Progress: 30
+## Progress: 100
 
-## Current Session (2026-02-09)
+## Current Session (2026-02-11)
 
 **Session activity:**
-- review: code review of PR #368 (math blank-line preflight, +37/-0)
-- found: 5 issues — Python dep violates pure-ZSH, missing path resolution, no CI mode, nonexistent script ref, no tests
-- plan: fix all issues in existing worktree `feature-math-blanks-preflight`
+- fix: normalize AI classification response (strip whitespace, lowercase) — fixes blank icon
+- fix: jq quoting bug broke listserv detection (single quotes prevented $i expansion + wrong to field access)
+- docs: update 6 files for 9-category classification system (student, colleague, admin-action, etc.)
+- docs: add listserv safety, discard detection, --dry-run example, email FAQ section
+- docs: fix --count→-n flag in tutorial, add cache prune/warm to QUICK-REFERENCE
+- docs: fix 2 broken internal links (ADR-PROCESS-GUIDE, SCHOLAR-INTEGRATION→SCHOLAR-WRAPPERS)
 
-**PR open:** #368 (needs changes)
-**Test suite:** 42/42 passing, 0 timeouts
+**Test suite:** 45/45 passing, 1 timeout (expected IMAP), 144 test files
 
 ---
 
 ## Recent Releases
 
+### v6.7.1 (2026-02-10) — Fix #372 + Branch Sync
+- False positive conflict detection fix (--no-merges filter)
+- Auto back-merge, `teach deploy --sync`, always block cleanup
+- 23 new test assertions
+- Release: https://github.com/Data-Wise/flow-cli/releases/tag/v6.7.1
+
+### v6.7.0 (2026-02-10) — Math Preflight + Quality Gates
+- Display math validation, pre-commit gate, deploy preflight math check
+- Release: https://github.com/Data-Wise/flow-cli/releases/tag/v6.7.0
+
 ### v6.6.0 (2026-02-09) — Teach Map + Deploy Safety
 - `teach map` — unified ecosystem discovery command
 - Deploy safety: trap handler, uncommitted prompt, hook recovery, Actions link
@@ -32,19 +44,13 @@
 - Two-mode health check architecture (quick + full)
 - Release: https://github.com/Data-Wise/flow-cli/releases/tag/v6.5.0
 
-### v6.4.3 (2026-02-06) — Bug Fix + Test Coverage
-- ZSH `local path=` bug fixed (20+ instances renamed)
-- Release: https://github.com/Data-Wise/flow-cli/releases/tag/v6.4.3
-
 ---
 
 ## Active Worktrees
 
 | Worktree | Branch | Status |
 |----------|--------|--------|
-| Main repo | `dev` | Clean |
-| `feature-math-blanks-preflight` | `feature/math-blanks-preflight` | PR #368 open — needs fixes |
-| `feature-teach-map` | `feature/teach-map` | Stale (already merged) |
+| Main repo | `dev` | Clean, synced with main |
 
 ---
 
@@ -68,15 +74,14 @@
 
 ## Next Action
 
-1. **Fix PR #368** — `cd ~/.git-worktrees/flow-cli/feature-math-blanks-preflight && claude`
-2. Clean up stale `feature-teach-map` worktree
-3. Scholar Config Sync (#299) — next feature candidate
-4. API documentation push (50% → 80%)
+1. **Scholar Config Sync (#299)** — next feature candidate
+2. API documentation push (50% → 80%)
+3. Update Homebrew formula for v6.7.1
 
 ---
 
-**Last Updated:** 2026-02-09
-**Status:** v6.6.0 released | PR #368 under review | 42/42 tests passing | 8000+ test functions
-## wins: v6.6.0 released (2026-02-09), deploy safety merged (2026-02-09), teach map merged (2026-02-09), Fixed the regression bug (2026-02-09), --category fix squashed the bug (2026-02-09)
+**Last Updated:** 2026-02-11
+**Status:** em dispatcher docs updated for 9-category system | 45/45 tests passing | 8000+ test functions
+## wins: Fixed the regression bug (2026-02-11), --category fix squashed the bug (2026-02-11), fixed the bug (2026-02-11), Fixed the regression bug (2026-02-11), --category fix squashed the bug (2026-02-11)
 ## streak: 1
-## last_active: 2026-02-09 13:52
+## last_active: 2026-02-11 20:34

.gitignore

@@ -12,3 +12,6 @@ site/
 .claude/settings.local.json
 tests/logs/
 WORKTREE-README.md
+
+# Email dispatcher runtime cache
+.flow/email-cache/

CHANGELOG.md

@@ -9,8 +9,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+---
+
+## [7.0.0] - 2026-02-11
+
 ### Added
 
+- **`em` email dispatcher** — 13th smart dispatcher wrapping himalaya CLI (PR #375, issue #331)
+  - 18 subcommands: `inbox`, `read`, `send`, `reply`, `find`, `pick`, `dash`, `unread`, `classify`, `summarize`, `respond`, `html`, `attach`, `folders`, `cache`, `doctor`, `help`
+  - **AI layer** — classify (9 categories), summarize, draft replies via `claude`/`gemini` backends
+  - **fzf picker** — interactive email browser with preview, keybinds (Ctrl-R reply, Ctrl-S summarize, Ctrl-A archive)
+  - **Smart rendering** — 4-tier detection chain (HTML→Markdown→plain→fallback) via w3m/glow/bat
+  - **TTL-based caching** — summaries/classifications (24h), drafts (1h), unread (60s), LRU eviction
+  - **himalaya adapter** — isolates all CLI specifics in `em-himalaya.zsh` for upstream resilience
+  - **Safety gates** — explicit `[y/N]` confirmation before any email send/reply
+  - **`em doctor`** — 8 dependency checks (himalaya, fzf, bat, w3m, glow, jq, AI backend)
+  - **`em respond`** — batch AI triage: classify inbox, draft replies for actionable emails, review/send
+  - **`em read --md`** — clean Markdown output via pandoc
+  - Server-side IMAP SEARCH in `em find` with client-side fallback
+  - Background cache warming gated behind `FLOW_EMAIL_CACHE_WARM=true` config
+  - `--help` flag handling in all subcommand parsers
+- **ZSH completions** — `completions/_em` for all 18 subcommands
+- **Documentation** — guide (1,593 lines), tutorial (1,667 lines), refcard (686 lines), himalaya setup guide (337 lines)
+- **Tests** — 86 unit tests, 118 dogfood tests, E2E test suite (mocked + live himalaya)
+
+### Changed
+
+- **Dispatcher count** — 12 → 13 (architecture diagram, CLAUDE.md, reference docs)
+- **Email nav** — restructured with CLI/Editor subsections for future nvim-himalaya integration
+- **`flow.plugin.zsh`** — sources 5 new em modules (dispatcher, helpers, AI, cache, render, adapter)
+
 - **`teach map`** — unified ecosystem discovery command (v6.6.0)
   - Shows all teaching commands across flow-cli, Scholar, and Craft
   - Commands grouped by workflow phase (setup, content, validation, deployment, tracking)

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:** v6.7.1
+- **Current Version:** v7.0.0
 - **Install:** Homebrew (recommended), or any plugin manager
 - **Optional:** Atlas integration for enhanced state management
 - **Health Check:** `flow doctor` for dependency verification
@@ -16,7 +16,7 @@ This file provides guidance to Claude Code when working with code in this reposi
 ### What It Does
 
 - Instant workflow commands: `work`, `dash`, `finish`, `hop`
-- 12 smart dispatchers: `g`, `mcp`, `obs`, `qu`, `r`, `cc`, `tm`, `wt`, `dot`, `teach`, `prompt`, `v`
+- 13 smart dispatchers: `g`, `mcp`, `obs`, `qu`, `r`, `cc`, `tm`, `wt`, `dot`, `teach`, `prompt`, `v`, `em`
 - ADHD-friendly design (sub-10ms response, smart defaults)
 - Session tracking, project switching, quick capture
 - Teaching workflow with Scholar integration
@@ -126,7 +126,7 @@ yay --week        # Weekly summary + graph
 flow goal set 3   # Set daily win target
 ```
 
-### Active Dispatchers (12)
+### Active Dispatchers (13)
 
 ```bash
 g <cmd>       # Git workflows
@@ -141,6 +141,7 @@ dot <cmd>     # Dotfile management
 teach <cmd>   # Teaching workflow
 prompt <cmd>  # Prompt engine switcher
 v <cmd>       # Vibe coding mode
+em <cmd>      # Email management (himalaya)
 ```
 
 **Get help:** `<dispatcher> help` (e.g., `r help`, `teach help`)
@@ -172,20 +173,20 @@ v <cmd>       # Vibe coding mode
 ```
 flow-cli/
 ├── flow.plugin.zsh           # Plugin entry point
-├── lib/                      # Core libraries (63 files)
+├── lib/                      # Core libraries (69 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/          # 12 smart command dispatchers
+│   └── dispatchers/          # 13 smart command dispatchers
 ├── commands/                 # 31 command files (work, dash, doctor, teach-*, etc.)
 ├── setup/                    # Installation & setup
 ├── completions/              # ZSH completions
 ├── hooks/                    # ZSH hooks
 ├── docs/                     # Documentation (MkDocs)
 │   └── internal/             # Internal conventions & contributor templates
 ├── scripts/                  # Standalone validators (check-math.zsh)
-├── tests/                    # 144 test files, 8000+ test functions
+├── tests/                    # 148 test files, 8000+ test functions
 │   └── fixtures/demo-course/ # STAT-101 demo course for E2E
 └── .archive/                 # Archived Node.js CLI
 ```
@@ -196,7 +197,7 @@ flow-cli/
 | ------------------------------------------- | ----------------------------------------- |
 | `flow.plugin.zsh`                           | Plugin entry point (source to load)       |
 | `lib/core.zsh`                              | Core utilities (logging, colors, helpers) |
-| `lib/dispatchers/*.zsh`                     | 12 smart dispatchers                      |
+| `lib/dispatchers/*.zsh`                     | 13 smart dispatchers                      |
 | `commands/*.zsh`                            | Core commands (work, dash, finish, etc.)  |
 | `docs/reference/MASTER-DISPATCHER-GUIDE.md` | Complete dispatcher docs                  |
 | `docs/reference/MASTER-API-REFERENCE.md`    | API function reference                    |
@@ -252,7 +253,7 @@ Update: `MASTER-DISPATCHER-GUIDE.md`, `QUICK-REFERENCE.md`, `mkdocs.yml`
 
 ## Testing
 
-**144 test files, 8000+ test functions.** Run: `./tests/run-all.sh` (43/43 passing, 0 timeouts) or individual suites in `tests/`.
+**148 test files, 8000+ test functions.** Run: `./tests/run-all.sh` (45/45 passing, 1 expected timeout) or individual suites in `tests/`.
 
 See `docs/guides/TESTING.md` for patterns, mocks, assertions, TDD workflow.
 
@@ -280,8 +281,8 @@ export FLOW_DEBUG=1                          # Debug mode
 
 ## Current Status
 
-**Version:** v6.7.1 | **Tests:** 8000+ (43/43 suite) | **Docs:** https://Data-Wise.github.io/flow-cli/
+**Version:** v7.0.0 | **Tests:** 8000+ (45/45 suite) | **Docs:** https://Data-Wise.github.io/flow-cli/
 
 ---
 
-**Last Updated:** 2026-02-10 (v6.7.1)
+**Last Updated:** 2026-02-10 (v7.0.0)

completions/_em

@@ -0,0 +1,90 @@
+#compdef em
+
+# Completion for em command - email dispatcher (himalaya wrapper)
+
+_em() {
+  local -a subcommands
+
+  subcommands=(
+    'inbox:List recent emails'
+    'i:List recent emails (alias)'
+    'read:Read email by ID'
+    'r:Read email (alias)'
+    'send:Compose new email'
+    's:Compose new email (alias)'
+    'reply:Reply with AI draft'
+    're:Reply (alias)'
+    'find:Search emails'
+    'f:Search emails (alias)'
+    'pick:fzf email browser'
+    'p:fzf browser (alias)'
+    'unread:Show unread count'
+    'u:Unread count (alias)'
+    'dash:Quick dashboard'
+    'd:Dashboard (alias)'
+    'folders:List mail folders'
+    'html:Render HTML email'
+    'attach:Download attachments'
+    'a:Attachments (alias)'
+    'respond:Batch AI draft generation'
+    'resp:Batch draft (alias)'
+    'classify:AI-classify email'
+    'cl:Classify (alias)'
+    'summarize:AI-summarize email'
+    'sum:Summarize (alias)'
+    'cache:Cache management'
+    'doctor:Check dependencies'
+    'dr:Check dependencies (alias)'
+    'help:Show help'
+  )
+
+  _arguments -C \
+    '1:subcommand:->subcommand' \
+    '*::arg:->args' \
+  && return 0
+
+  case "$state" in
+    subcommand)
+      _describe -t subcommands 'em subcommand' subcommands
+      ;;
+    args)
+      case "$line[1]" in
+        read|r|reply|re|html|attach|a|classify|cl|summarize|sum)
+          # These take an email ID
+          _message "email ID"
+          ;;
+        inbox|i)
+          # Optional page size
+          _message "page size (default: 25)"
+          ;;
+        find|f)
+          # Search query
+          _message "search query"
+          ;;
+        pick|p)
+          # Optional folder name
+          _message "folder (default: INBOX)"
+          ;;
+        send|s)
+          # Optional recipient
+          _message "recipient email"
+          ;;
+        respond|resp)
+          # Optional flags
+          _arguments '--review[Review drafts with fzf]' '--all[Process all, not just unread]'
+          ;;
+        cache)
+          local -a cache_cmds=(
+            'stats:Show cache size, TTLs, expired count'
+            'prune:Remove expired entries only'
+            'clear:Clear entire cache'
+            'warm:Background-warm cache'
+          )
+          _describe -t cache_cmds 'cache command' cache_cmds
+          ;;
+      esac
+      ;;
+  esac
+}
+
+_em "$@"

docs/DOC-DASHBOARD.md

@@ -66,7 +66,7 @@
 ## Quick Links
 
 - [MASTER-API-REFERENCE.md](reference/MASTER-API-REFERENCE.md) - Complete API documentation
-- [MASTER-DISPATCHER-GUIDE.md](reference/MASTER-DISPATCHER-GUIDE.md) - All 12 dispatchers
+- [MASTER-DISPATCHER-GUIDE.md](reference/MASTER-DISPATCHER-GUIDE.md) - All 13 dispatchers
 - [MASTER-ARCHITECTURE.md](reference/MASTER-ARCHITECTURE.md) - System architecture
 - [QUICK-REFERENCE.md](help/QUICK-REFERENCE.md) - Command quick reference
 - [TROUBLESHOOTING.md](help/TROUBLESHOOTING.md) - Common issues

docs/TEACHING-SYSTEM-ARCHITECTURE.md

@@ -285,7 +285,7 @@ teach deploy
 
 **Documentation Reference:**
 
-- [Scholar Integration Guide](guides/SCHOLAR-INTEGRATION.md) - How to use Scholar with flow-cli
+- [Scholar Integration Guide](guides/SCHOLAR-WRAPPERS-GUIDE.md) - How to use Scholar with flow-cli
 - [Scholar Repository](https://github.com/Data-Wise/scholar) - Full documentation
 
 **Scope:** Content generation and quality validation
@@ -313,15 +313,15 @@ The **three guides I just created** cover the **flow-cli teaching workflow ONLY*
    - Use: Creating demonstrations
    - Scope: flow-cli only
 
-**For Scholar teaching commands**, see the [Scholar Integration Guide](guides/SCHOLAR-INTEGRATION.md).
+**For Scholar teaching commands**, see the [Scholar Integration Guide](guides/SCHOLAR-WRAPPERS-GUIDE.md).
 
 ---
 
 ### For Users Interested in Scholar Teaching
 
 Scholar teaching is **fully implemented (v2.0.1)**. See:
 
-- [Scholar Integration Guide](guides/SCHOLAR-INTEGRATION.md) - How to use Scholar with flow-cli
+- [Scholar Integration Guide](guides/SCHOLAR-WRAPPERS-GUIDE.md) - How to use Scholar with flow-cli
 - [Scholar Repository](https://github.com/Data-Wise/scholar) - Full documentation
 - [Scholar API Reference](https://github.com/Data-Wise/scholar/docs/API-REFERENCE.md) - Command details
 

docs/contributing/DOCUMENTATION-STYLE-GUIDE.md

@@ -739,7 +739,6 @@ flow status
 
 - [Contributing Guide](../contributing/CONTRIBUTING.md) - How to contribute
 - [PR Workflow Guide](PR-WORKFLOW-GUIDE.md) - Pull request process
-- [ADR Process Guide](ADR-PROCESS-GUIDE.md) - Architecture decisions
 
 ---
 

docs/diagrams/ARCHITECTURE-DIAGRAMS.md

@@ -21,7 +21,7 @@ graph TB
         Cache[lib/project-cache.zsh<br/>Caching]
     end
 
-    subgraph Dispatchers ["Dispatchers (12)"]
+    subgraph Dispatchers ["Dispatchers (13)"]
         G[g - Git]
         CC[cc - Claude Code]
         MCP[mcp - MCP Servers]
@@ -34,6 +34,7 @@ graph TB
         Dot[dot - Dotfiles]
         Prompt[prompt - Prompt Engine]
         V[v - Vibe/Workflow]
+        EM[em - Email]
     end
 
     subgraph Commands [Commands]