dotmd-cli 0.60.0 → 0.62.0

package/README.md

@@ -33,7 +33,7 @@ dotmd new my-feature        # scaffold a new doc with frontmatter
 dotmd list                  # index all docs grouped by status
 dotmd check                 # validate frontmatter and references
 dotmd context               # compact briefing (great for LLM context)
-dotmd doctor                # auto-fix everything in one pass
+dotmd doctor                # preview fixes for everything (--apply to write)
 ```
 
 ### Shell Completion
@@ -83,7 +83,9 @@ Explicit frontmatter always wins. Body extraction is a cushion for partially-tag
 ## What It Does
 
 - **Index** — group docs by status, with auto-detected progress bars (from `- [ ]` checklists) and next steps
-- **Query** — filter by status, keyword, module, surface, owner, staleness
+- **Query** — filter by status, keyword, module, surface, owner, staleness; `dotmd grep` searches document bodies too
+- **Resume handoff** — `dotmd baton` saves a resume prompt for the next session and releases the in-session plan in one verb
+- **Runlists** — group plans into an ordered sequence on a hub plan; `dotmd runlist next` picks up the next one
 - **Validate** — check for missing fields, broken references, broken body links, stale dates
 - **Stats** — health dashboard with staleness, completeness, audit coverage
 - **Graph** — visualize document relationships as text, Graphviz DOT, or JSON
@@ -129,7 +131,7 @@ Design doc content here...
 - [ ] Add tests
 ```
 
-The only required field is `status`. Everything else is optional but unlocks more features. The `type` field (`plan`, `doc`, or `research`) enables type-specific statuses and smarter context briefings.
+The only required field is `status`. Everything else is optional but unlocks more features. The `type` field (`plan`, `doc`, or `prompt`) enables type-specific statuses and smarter context briefings.
 
 > **Note:** `module:` and `surface:` (singular) are deprecated as of 0.36.3 — use the plural array forms (`modules:`, `surfaces:`). Run `dotmd lint --fix` to migrate existing docs.
 
@@ -177,6 +179,34 @@ Each *quiet* status (`partial`, `queued-after`, `archived`) is exempt from stale
 
 > **Heads-up:** versions before 0.15 included a `done` plan status in the defaults. It saw effectively zero real-world use (plans went `in-session`/`active` → `archived` directly), so it was dropped from the built-in vocabulary. To finish a plan, run `dotmd archive <plan-file>` — or, if you preferred the previous behavior, add `done` back via the `types.plan.statuses` key in your config.
 
+### Runlists: ordered groups of plans
+
+When several plans must ship in a known order (an "auth revamp" sprint with extract → rewrite → cleanup phases), declare a `runlist:` array on a hub plan instead of chaining `queued-after` per pair or keeping the order in prose:
+
+```yaml
+---
+type: plan
+status: active
+title: Auth Revamp
+runlist:
+  - auth-revamp-01-extract.md
+  - auth-revamp-02-rewrite.md
+  - auth-revamp-03-cleanup.md
+---
+```
+
+```bash
+dotmd runlist <hub>          # children + statuses in order; first non-archived child marked →
+dotmd runlist next <hub>     # pick up the next child (marks in-session + prints it)
+dotmd runlists               # dashboard of coordination-hub runlists (--json, --limit N)
+```
+
+`runlist next` stops with a runlist-aware error if the next child isn't in a workable status (`active` / `planned` / `in-session`), so you resolve the blocker before continuing. Each child should set `parent_plan:` pointing back at the hub — `dotmd check` warns when it doesn't. There's no separate doc type: a runlist hub is just a plan with the array.
+
+In `dotmd plans`, hubs are tagged `[RUNLIST]` (not `[ACTIVE]`) with their children folded underneath — the hub row shows `done/total` progress and the next-pickup `→`, so a multi-plan sprint reads as one runlist instead of cluttering the triage list. A child whose hub is filtered out of the view (e.g. `--status active` when the hub is `planned`) still renders on its own.
+
+**Coordination runlists.** A `runlist:` array fits a small ordered *sprint*. For a large, prose-first *coordination map* (a domain hub pointing at many plans, with gating/sequence rationale, sometimes unordered), set `execution_mode: coordination` instead — or just name it `*-runlist`. These aren't folded: `dotmd plans` lifts them into a pinned `Runlists` section and out of the active count, and `dotmd runlists` shows that dashboard standalone. `dotmd briefing` and `dotmd health` do the same — coordination hubs are pulled out of the live/active counts into a `runlists` bucket (briefing) and a held-out `Runlists:` tally (health), so they don't inflate the actionable-plan or aging numbers. The per-hub "N related" count comes from `related_plans:`. `dotmd check` nudges a `*-runlist` hub missing `execution_mode: coordination`.
+
 ## Commands
 
 ```
@@ -191,27 +221,36 @@ dotmd unblocks <file>        Show what depends on this doc
 dotmd health [--json]        Plan velocity, aging, and pipeline
 dotmd briefing               Compact summary for session start
 dotmd context [--summarize]  Full briefing (LLM-oriented)
+dotmd agent-context          Compact bounded JSON context for agents
 dotmd focus [status]         Detailed view for one status group
-dotmd query [filters]        Filtered search
-dotmd plans                  List all plans
+dotmd query [filters]        Filtered search (--body scans document bodies)
+dotmd grep <term>            Keyword search incl. bodies — "which doc discussed X?"
+dotmd plans                  List live plans (excludes archived)
 dotmd modules                Module dashboard (plans grouped by module)
 dotmd module <name>          Plans for one module, grouped by status
+dotmd surfaces               List configured surface taxonomy
 dotmd stale                  List stale docs
 dotmd actionable             List docs with next steps
 dotmd index [--print]        Generate/update docs.md index block
 dotmd hud                    Actionable triage (silent when clean — ideal SessionStart hook)
-dotmd use <file>             Open a plan (in-session + print it) or consume a prompt
-dotmd set <status> <file>    Change a document's status (frontmatter write)
+dotmd use [<file-or-slug>]   Open by type: prompt → consume, plan → start, doc → read
+                             (no arg: consume the oldest pending prompt)
+dotmd set <status> <file>    Change a document's status (--note appends why to Version History)
+dotmd baton [<plan>|<slug>] <@draft|->  Save a resume prompt; releases the in-session plan
+dotmd runlist <hub> [next]   Show or walk an ordered group of plans
 dotmd status <file> <status> Transition document status (deprecated; prefer set)
 dotmd archive <file>         Archive (status + move + update refs)
 dotmd bulk archive <files>   Archive multiple files at once
+dotmd bulk-tag [files]       Tag pre-existing untagged .md files
 dotmd touch <file>           Bump updated date
 dotmd touch --git            Bulk-sync dates from git history
-dotmd doctor                 Auto-fix everything in one pass
+dotmd doctor [--apply]       Fix refs, lint, dates, index (previews by default)
+dotmd self-check             Project/version skew diagnostic
 dotmd fix-refs               Auto-fix broken reference paths
 dotmd lint [--fix]           Check and auto-fix frontmatter issues
 dotmd rename <old> <new>     Rename doc and update references
 dotmd migrate <f> <old> <new>  Batch update a frontmatter field
+dotmd ship [patch|minor|major] Regen + commit + bump in one step
 dotmd notion <sub> [db-id]   Notion import/export/sync
 dotmd export [file]          Export docs as md, html, or json
 dotmd summary <file>         AI summary of a document
@@ -219,19 +258,22 @@ dotmd glossary <term>        Look up domain terms + related docs
 dotmd watch [command]        Re-run a command on file changes
 dotmd diff [file]            Show changes since last updated date
 dotmd new <type> <name>      Create a new doc (type: doc, plan, or prompt)
-dotmd prompts [sub]          Manage saved prompts (list, next, use, hold, archive, new)
+dotmd prompts [sub]          Manage saved prompts (list, show, hold, archive, new)
+dotmd statuses [sub]         Manage per-project status taxonomy
 dotmd journal [flags]        View opt-in command-usage journal (DOTMD_JOURNAL=1)
 dotmd init                   Create starter config + docs directory
 dotmd completions <shell>    Output shell completion script (bash, zsh)
 ```
 
+Run `dotmd help all` for the always-current version of this list, `dotmd help statuses` for the status vocabulary, and `dotmd <cmd> --help` for per-command details.
+
 ### Global Flags
 
 ```
 --config <path>        Explicit config file path
 --dry-run, -n          Preview changes without writing anything
 --root <name>          Filter to a specific docs root
---type <t1,t2>         Filter by document type (plan, doc, research)
+--type <t1,t2>         Filter by document type (plan, doc, prompt, or custom)
 --verbose              Show resolved config details
 --help, -h             Show help (per-command with: dotmd <cmd> --help)
 --version, -v          Show version
@@ -246,9 +288,12 @@ dotmd query --stale --sort updated --all
 dotmd query --surface backend --checklist-open
 dotmd query --status active --summarize             # AI summaries
 dotmd query --status active --summarize --summarize-limit 3
+dotmd query --keyword "retries" --body              # scan document bodies too
 ```
 
-Flags: `--type`, `--status`, `--keyword`, `--module`, `--surface`, `--domain`, `--owner`, `--updated-since`, `--stale`, `--has-next-step`, `--has-blockers`, `--checklist-open`, `--sort`, `--limit`, `--all`, `--git`, `--json`, `--summarize`, `--summarize-limit`, `--model`.
+Flags: `--type`, `--status`, `--keyword`, `--body`, `--module`, `--surface`, `--domain`, `--owner`, `--updated-since`, `--stale`, `--has-next-step`, `--has-blockers`, `--checklist-open`, `--sort`, `--limit`, `--all`, `--git`, `--json`, `--summarize`, `--summarize-limit`, `--model`.
+
+`dotmd grep <term>` is the "which doc discussed X?" shorthand — an alias for `dotmd query --keyword <term> --body --all` that prints doc cards plus line-numbered excerpts per body hit. Bodies are read lazily (frontmatter filters run first), and it composes with the usual query flags.
 
 ### Create Documents
 
@@ -311,9 +356,19 @@ dotmd new prompt from-file @/tmp/draft.md
 
 Manage them with the `prompts` command family:
 
+Consume one with `dotmd use` — it atomically prints the body and archives the prompt so it can't be double-consumed:
+
+```bash
+dotmd use                         # consume the oldest pending prompt
+dotmd use <file-or-slug>          # consume a specific prompt
+```
+
+Admin verbs live under the `prompts` namespace:
+
 ```bash
 dotmd prompts                     # list pending prompts (default)
 dotmd prompts list --all          # all statuses
+dotmd prompts show <file>         # read-only peek: print the body WITHOUT consuming
 dotmd prompts next                # print body of oldest pending + auto-archive (one-shot)
 dotmd prompts use <file>          # print body of a specific prompt + auto-archive
 dotmd prompts hold <file>         # park a prompt (status → held) under prompts/held/:
@@ -328,6 +383,31 @@ dotmd prompts new <name> [body]   # alias for `dotmd new prompt`
 
 Statuses: `pending` (drafted, awaiting a session), `held` (saved but parked under `prompts/held/` — visible in `prompts list`, hidden from `hud`/`briefing`, skipped by `prompts next`), `archived` (consumed or filed away). `shelved` is a legacy spelling accepted for older files; `claimed` is reserved for a future "in-flight" state but is currently a synonym for archived in practice.
 
+### Baton: resume prompts & session handoff
+
+`dotmd baton` is the "save a resume prompt" verb — the way one session hands work to the next without pasting resume text into chat. Write a short draft (the next concrete decision plus any gotchas, not a recap), then:
+
+```bash
+dotmd baton @/tmp/draft.md        # plan mode: a plan is in-session
+```
+
+In plan mode, baton does the whole closeout in one call:
+
+1. Saves a resume prompt named `resume-<plan-slug>` (collision-safe: `-2`, `-3`, …) under `docs/prompts/` with `status: pending`.
+2. Releases the plan: one status flip, `in-session` → `active` by default (`--status paused|awaiting|partial|blocked` to override, `--note "why"` to record the reason in `## Version History`).
+3. Prints the exact `git commit` command for the plan's frontmatter change — the prompt stays out of the pathspec, because saved prompts are session-local.
+
+Baton resolves *your* plan via the command journal (or takes it explicitly: `dotmd baton <plan-file> @draft`), falling back to the only in-session plan.
+
+No plan involved? Slug mode saves the prompt and touches nothing else:
+
+```bash
+dotmd baton checkout-fixes @/tmp/draft.md    # saves resume-checkout-fixes; no status changes
+cat /tmp/draft.md | dotmd baton              # body from stdin
+```
+
+Either way, the next session's `dotmd hud` surfaces the pending prompt, and `dotmd use` consumes it.
+
 ### Command Journal (opt-in)
 
 dotmd's primary user is an agent. Every CLI invocation can be journaled
@@ -403,8 +483,8 @@ Shows: status counts, staleness, errors/warnings, freshness (today/week/month),
 ### Doctor
 
 ```bash
-dotmd doctor                 # fix refs → lint → sync git dates → regen index
-dotmd doctor --dry-run       # preview all changes
+dotmd doctor                 # preview: fix refs → lint → sync git dates → regen index
+dotmd doctor --apply         # actually write the fixes (previews by default since 0.37.0)
 dotmd doctor --statuses      # detect overloaded status buckets (read-only)
 dotmd doctor --statuses --json  # machine-readable suggestions
 ```
@@ -607,6 +687,15 @@ dotmd archive docs/plans/my-plan.md --closeout-template   # also inject ## Close
 `in-session` is a status like any other — `dotmd set <status> <file>` writes it
 to the file's frontmatter and does nothing else.
 
+Add `--note "why"` to any `set` or `archive` to append the reason to the doc's
+`## Version History` section in the same call (creates the section if missing) —
+it saves the status-change + worklog-edit round-trip. `set partial` without a
+note or successor link prints a reminder.
+
+To stop mid-work and hand off to a future session, use `dotmd baton` (see
+[Baton](#baton-resume-prompts--session-handoff)) — it saves the resume prompt
+and releases the plan in one verb.
+
 **Recommended Claude Code hook** — add to `~/.claude/settings.json`
 (or your project's `.claude/settings.json`):
 

package/bin/dotmd.mjs

@@ -36,16 +36,19 @@ const FLAG_SPECS = {
   context: { flags: new Set(['--json', '--compact', '--summarize', '--model']), values: new Set(['--model']) },
   'agent-context': { flags: new Set(['--json']), values: new Set() },
   hud: { flags: new Set(['--json', '--subagent']), values: new Set() },
+  // '-' is the stdin marker (a positional, not a flag) — listed so validation lets it through.
+  baton: { flags: new Set(['--status', '--note', '--body', '--message', '--dry-run', '-n', '-']), values: new Set(['--status', '--note', '--body', '--message']) },
   guard: { flags: new Set(), values: new Set() },
   misuse: { flags: new Set(['--json', '--tail', '--by-rule', '--repo']), values: new Set(['--tail', '--repo']) },
   update: { flags: new Set(['--check', '--cli-only', '--plugin-only']), values: new Set() },
   check: { flags: new Set(['--fix', '--errors-only', '--no-collapse', '--json', '--verbose']), values: new Set() },
   doctor: { flags: new Set(['--apply', '--yes', '--dry-run', '-n', '--statuses', '--migrate-template', '--migrate-prompts', '--frontmatter-fix', '--project', '--json', '--include-archived']), values: new Set() },
   runlist: { flags: new Set(['--json', '--full', '--no-index', '--show-files']), values: new Set(), subcommands: new Set(['next']) },
+  runlists: { flags: new Set(['--json', '--limit', '--sort']), values: new Set(['--limit', '--sort']) },
   prompts: {
     flags: new Set(['--json', '--status', '--include-archived', '--sort', '--limit', '--all', '--no-index', '--show-files', '--body', '--message', '--title']),
     values: new Set(['--status', '--sort', '--limit', '--body', '--message', '--title']),
-    subcommands: new Set(['list', 'next', 'use', 'resume', 'archive', 'new', 'hold', 'unhold', 'shelve', 'unshelve', 'status']),
+    subcommands: new Set(['list', 'next', 'use', 'resume', 'show', 'peek', 'archive', 'new', 'hold', 'unhold', 'shelve', 'unshelve', 'status']),
   },
 };
 
@@ -133,6 +136,7 @@ Common commands:
   set <status> [file]   Transition status (start work, finish, archive — all via target status)
   new <type> <name>     Create plan/doc/prompt (pipe stdin or @path for body)
   use [<file-or-slug>]  Open a doc by type: prompt → consume, plan → start, doc → read
+  baton [<plan>|<slug>] <@draft|-> Save a resume prompt (+ release the plan, if one is in-session)
                         (no file: consume oldest pending prompt)
   archive <file>        Close out a plan (status → archived, move, update refs)
 
@@ -203,7 +207,8 @@ View & Query:
   grep <term>                       Keyword search incl. document bodies (query --keyword --body --all)
   plans                             Live plans (excludes archived; --include-archived for all)
   use [<file-or-slug>]              Open a doc by type: prompt → consume, plan → start, doc → read
-  prompts [list|archive|new|hold] Prompt admin (list / archive / save / hold). Use \`dotmd use\` to consume.
+  baton [<plan>|<slug>] <@draft|->  Save a resume prompt; releases the plan + prints the commit when one is in-session
+  prompts [list|show|archive|new|hold] Prompt admin (list / peek / archive / save / hold). Use \`dotmd use\` to consume.
   stale                             Stale docs (preset)
   actionable                        Docs with next steps (preset)
 
@@ -231,6 +236,7 @@ Lifecycle:
   use <file>                        Open a plan (mark in-session + print it) or consume a prompt
   set <status> <file>               Change a document's status (frontmatter write; archive also moves the file)
   runlist <hub> [next]              Show or walk an ordered group of plans (see \`dotmd help runlist\`)
+  runlists                          List coordination-hub runlists (the Runlists dashboard)
   status <file> <status>            Transition document status (deprecated; prefer \`set\`)
   archive <file>                    Archive (status + move + update refs)
   bulk archive <f1> <f2> ...        Archive multiple files at once
@@ -259,7 +265,7 @@ Setup:
 Global Options:
   --config <path>        Explicit config file path
   --root <name>          Filter to a specific docs root
-  --type <t1,t2>         Filter by document type (plan, doc, research)
+  --type <t1,t2>         Filter by document type (plan, doc, prompt)
   --dry-run, -n          Preview changes without writing anything
   --verbose              Show config details and doc count
   --help, -h             Show help (per-command: dotmd <cmd> --help)
@@ -406,7 +412,7 @@ Examples:
   query: `dotmd query — filtered document search
 
 Filters:
-  --type <t1,t2>         Filter by type (plan, doc, research)
+  --type <t1,t2>         Filter by type (plan, doc, prompt)
   --status <s1,s2>       Filter by status (comma-separated)
   --keyword <term>       Search title, summary, state, path
   --body                 Extend --keyword into document bodies (lazy scan, shows matching-line excerpts)
@@ -603,7 +609,8 @@ Recommended SessionStart hook (in ~/.claude/settings.json):
   "SessionStart": [{ "hooks": [{ "type": "command", "command": "dotmd hud", "timeout": 5 }] }]
 
 Options:
-  --json                 Output as JSON ({ owned, queued, prompts, stale })`,
+  --json                 Output as JSON ({ owned, prompts, errors, previousSelf,
+                         fleet, recentRejections, misuseRecap, drift })`,
 
   briefing: `dotmd briefing — compact summary for session start
 
@@ -882,7 +889,7 @@ Options:
   --format <md|html|json>  Output format (default: md)
   --output <path>          Write to file/directory (default: stdout for md/json)
   --status <s1,s2>         Filter by status
-  --type <t1,t2>           Filter by type (plan, doc, research)
+  --type <t1,t2>           Filter by type (plan, doc, prompt)
   --module <name>          Filter by module
   --root <name>            Filter by root
   --dry-run, -n            Preview without writing`,
@@ -993,6 +1000,8 @@ Subcommands:
                              targets the named prompt instead of picking oldest)
   resume <file-or-slug>      Alias for \`use\` — same behavior, easier name
                              when continuing a session
+  show <file-or-slug>        Read-only peek: print the body WITHOUT consuming
+                             (triage). \`peek\` is an alias.
   archive <file-or-slug>     Archive a prompt without printing its body
   hold <file-or-slug>        Park a prompt (status → held) under prompts/held/:
                              kept in list, hidden from hud/briefing pending
@@ -1023,10 +1032,50 @@ Examples:
   claude "$(dotmd prompts resume resume-foo)"        # \`resume\` is an alias for \`use\`
   dotmd prompt list                    # singular alias for \`dotmd prompts list\`
 
+  dotmd prompts show resume-foo        # peek without consuming (triage)
   dotmd prompts next --dry-run         # preview without consuming
   dotmd prompts archive old-thing
   dotmd prompts new my-prompt "Body text here"`,
 
+  baton: `dotmd baton — save a resume prompt for whatever you're doing (and release the plan, if there is one)
+
+The "save a resume prompt" verb. Works mid-anything:
+
+Plan mode (a plan is in-session, or you pass one):
+  1. Saves a resume prompt named resume-<plan-slug> (collision-safe: -2, -3, …).
+     The prompt is session-local — the next session's hud surfaces it; never
+     paste resume text into chat.
+  2. Releases the plan: one status flip, in-session → active by default
+     (--status to override, --note to record why in ## Version History).
+  3. Prints the exact \`git commit\` for the plan's frontmatter change — the
+     prompt stays OUT of the pathspec (it's session-local, often gitignored).
+  Which plan? Pass it explicitly, or baton resolves the one THIS session marked
+  in-session (via the journal), falling back to the only in-session plan.
+
+Slug mode (no plan involved — "save a resume prompt for this"):
+  dotmd baton <slug> @/tmp/draft.md   →  saves resume-<slug>, touches NOTHING
+  else: no status changes, no commit, no plan required. Reference any relevant
+  plans/docs inside the draft body.
+
+Usage:
+  dotmd baton [<plan-file> | <slug>] [@draft.md | - | --message "..."]
+
+Options:
+  --status <s>           Target status for the plan (default: active; plan mode only)
+  --note "why"           Append the reason to ## Version History (plan mode only)
+  --message / --body     Inline body (one-liners; prefer @path or stdin)
+  --dry-run, -n          Preview without writing
+
+Examples:
+  dotmd baton @/tmp/draft.md                       # owned plan, body from file
+  dotmd baton checkout-fixes @/tmp/draft.md        # no plan: just save resume-checkout-fixes
+  cat /tmp/draft.md | dotmd baton                  # body from stdin
+  dotmd baton docs/plans/auth.md @/tmp/draft.md    # explicit plan
+  dotmd baton --status paused --note "blocked on review" @/tmp/d.md
+
+Write the draft FIRST (10–20 lines): the next concrete decision plus any
+gotchas — not a recap of the plan body.`,
+
   stale: `dotmd stale — list stale documents
 
 Shows docs that haven't been updated within their staleness threshold.
@@ -1165,7 +1214,33 @@ Common shape:
   ---
 
 Child plans should set \`parent_plan:\` back at the hub — \`dotmd check\` warns
-when they don't.`,
+when they don't.
+
+In \`dotmd plans\`, a hub is tagged \`[RUNLIST]\` (not \`[ACTIVE]\`) and its
+children fold underneath it — progress (\`done/total\`) and the next pickup
+\`→\` show on the hub row, so a sprint reads as one runlist instead of N loose
+plans. Children whose hub is filtered out of the view (e.g. \`--status active\`
+when the hub is \`planned\`) still render on their own.
+
+Larger, prose-first "coordination" runlists (a domain map pointing at many
+plans, marked \`execution_mode: coordination\` or named \`*-runlist\`) aren't
+folded — they're lifted into a separate \`Runlists\` section in \`dotmd plans\`
+and out of the active count. \`dotmd runlists\` shows that dashboard on its own.`,
+
+  runlists: `dotmd runlists — the coordination-hub dashboard
+
+Lists every *coordination runlist*: a prose-first plan that sits above a
+cluster of others (a domain map), detected by \`execution_mode: coordination\`
+or a \`*-runlist\` / \`runlist\` slug. Each row shows the hub, its age, the rough
+size of its \`related_plans:\` cluster, and a one-line descriptor.
+
+This is the standalone form of the \`Runlists\` section that \`dotmd plans\`
+pins beneath the leaf-plan triage list.
+
+  dotmd runlists               All runlists (a small bounded set), most stale first.
+  dotmd runlists --sort recent Order by recency instead (age|recent|related|title|status).
+  dotmd runlists --limit N     Cap the list at N.
+  dotmd runlists --json        Structured rows (path, status, childCount, …).`,
 
   'bulk-tag': `dotmd bulk-tag [files...] — fill in type/status frontmatter on pre-existing markdown
 
@@ -1325,6 +1400,16 @@ async function main() {
     runQuery(index, [...defaults, ...extras], config, { preset: 'plans' });
     return;
   }
+  // `dotmd runlists` (plural) — the coordination-hub dashboard (the `Runlists`
+  // section of `dotmd plans`, standalone). Distinct from `dotmd runlist <hub>`
+  // (singular), which walks one hub's children.
+  if (command === 'runlists') {
+    const { buildIndex } = await import('../src/index.mjs');
+    const { runRunlists } = await import('../src/query.mjs');
+    const index = buildIndex(config);
+    runRunlists(index, restArgs, config);
+    return;
+  }
   if (command === 'prompts') {
     const { runPrompts } = await import('../src/prompts.mjs');
     await runPrompts(restArgs, config, { dryRun, verbose });
@@ -1339,6 +1424,14 @@ async function main() {
     await runUse(restArgs, config, { dryRun });
     return;
   }
+  // `dotmd baton [plan] <@draft|->` — the one-command handoff: save the resume
+  // prompt, release the plan (one status flip), print the exact commit. See
+  // src/baton.mjs for why this is a single verb and not a skill choreography.
+  if (command === 'baton') {
+    const { runBaton } = await import('../src/baton.mjs');
+    await runBaton(restArgs, config, { dryRun });
+    return;
+  }
   // `dotmd next` is a top-level alias for `dotmd use` with no arg — consume
   // the oldest pending prompt. Wired separately so agents who reach for the
   // literal verb "next" don't bounce off an Unknown-command. Any positional
@@ -1667,8 +1760,16 @@ async function main() {
       const docs = index.docs.filter(d => d.type === 'doc');
       const research = index.docs.filter(d => d.type === 'research');
       const stale = index.docs.filter(d => d.isStale && !config.lifecycle.skipStaleFor.has(d.status)).length;
+      // Coordination hubs are runlists, not actionable plans — split them out of
+      // inSession/active into their own `runlists` array so the JSON mirrors the
+      // rendered briefing. Empty on repos with no coordination hubs.
+      const { buildCoordinationIndex } = await import('../src/runlist.mjs');
+      const coordination = buildCoordinationIndex(index, config);
+      const isHub = (d) => coordination.has(d.path);
+      const closedStatuses = new Set([...config.lifecycle.archiveStatuses, ...config.lifecycle.terminalStatuses]);
+      const isLiveHub = (d) => isHub(d) && !closedStatuses.has(d.status) && !isArchivedPath(d.path, config);
       process.stdout.write(JSON.stringify({
-        plans: { total: plans.length, inSession: plans.filter(d => d.status === 'in-session').map(d => ({ path: d.path, title: d.title, nextStep: d.nextStep })), active: plans.filter(d => d.status === 'active').map(d => ({ path: d.path, title: d.title, nextStep: d.nextStep })) },
+        plans: { total: plans.length, inSession: plans.filter(d => d.status === 'in-session' && !isHub(d)).map(d => ({ path: d.path, title: d.title, nextStep: d.nextStep })), active: plans.filter(d => d.status === 'active' && !isHub(d)).map(d => ({ path: d.path, title: d.title, nextStep: d.nextStep })), runlists: plans.filter(isLiveHub).map(d => ({ path: d.path, title: d.title, status: d.status, childCount: coordination.get(d.path)?.childCount ?? 0 })) },
         docs: { total: docs.length, active: docs.filter(d => !config.lifecycle.terminalStatuses.has(d.status)).length },
         research: { total: research.length, active: research.filter(d => d.status === 'active').length },
         stale, errorCount: index.errors.length, warningCount: index.warnings.length,

package/dotmd.config.example.mjs

@@ -193,7 +193,11 @@ export const presets = {
 // Properties:
 //   description:    string — shown in `dotmd new --list-types`
 //   defaultStatus:  string — initial status if `--status` not passed
-//   requiresBody:   boolean — error if no body input (see `prompt` builtin)
+//   acceptsBody:    boolean — allow body input (inline / --body / @file / piped stdin).
+//                   REQUIRED if you want `cat draft.md | dotmd new <type> <slug>` (or @path,
+//                   --body, heredoc) to work. Your `body` fn must also interpolate the input,
+//                   e.g. `${ctx?.bodyInput?.trim() ?? ''}`. See the body-acceptance guard below.
+//   requiresBody:   boolean — error if no body input (implies acceptsBody; see `prompt` builtin)
 //   targetRoot:     string — name (basename or suffix) of the root this type lives in.
 //                   In flat-array `root` configs (e.g. ['docs/plans', 'docs/prompts']),
 //                   the new doc lands in the matching root. Falls back to `config.docsRoot`
@@ -203,7 +207,17 @@ export const presets = {
 //                   under `docsRoot='docs'`, `dir` puts files in `docs/plans/` and `docs/prompts/`;
 //                   under flat-array roots, `targetRoot` routes directly to the type-specific root.
 //   frontmatter:    (status, isoTime, ctx) => string
-//   body:           (title, ctx) => string
+//   body:           (title, ctx) => string — slot user-supplied body via `ctx.bodyInput`
+//
+// Body-acceptance guard (the #1 custom-template gotcha):
+//   When you override a builtin and supply your OWN `body` fn that NEVER references
+//   `bodyInput`, dotmd assumes the fn would silently discard piped input — so it strips
+//   the inherited `acceptsBody`/`requiresBody` and rejects body input with a fail-fast
+//   error. Two ways to keep piped/@path/heredoc bodies working in a custom template:
+//     1. interpolate `${ctx?.bodyInput?.trim() ?? ''}` somewhere in your `body` fn, OR
+//     2. set `acceptsBody: true` explicitly (do BOTH if you want the input to actually land).
+//   A `body: (t) =>` that ignores `ctx` is the classic trap — it scaffolds fine but
+//   `dotmd new <type> <slug> < draft.md` errors until you wire in `bodyInput`.
 //
 // Custom type example — adds a `spike` type that lives in the `spikes` root (or
 // under `docs/spikes/` in single-root layouts):
@@ -218,8 +232,11 @@ export const presets = {
 //   },
 //
 //   // Override a builtin (e.g. project-specific prompt frontmatter shape).
-//   // IMPORTANT: builtin properties are NOT inherited — re-declare `targetRoot`, `dir`,
-//   // `defaultStatus`, `requiresBody`, etc. that you want preserved.
+//   // Overrides shallow-merge OVER the builtin: any property you omit is inherited
+//   // (`targetRoot`, `dir`, `defaultStatus`, `requiresBody`, …), and anything you declare
+//   // wins. EXCEPTION: if you supply your own `body` fn that doesn't reference `bodyInput`,
+//   // the inherited `acceptsBody`/`requiresBody` are dropped (see the guard above) — so
+//   // re-declare `acceptsBody: true` and wire in `ctx.bodyInput` if you want piped bodies.
 //   // prompt: {
 //   //   description: 'Project resume prompt',
 //   //   defaultStatus: 'pending',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.60.0",
+  "version": "0.62.0",
   "description": "CLI for managing markdown documents with YAML frontmatter — index, query, validate, graph, export, Notion sync, AI summaries.",
   "type": "module",
   "license": "MIT",