dotmd-cli 0.62.0 → 0.64.0

package/README.md

@@ -21,7 +21,9 @@ If you drive dotmd from Claude Code, install the **dotmd plugin**. It teaches ev
 /plugin install dotmd@dotmd
 ```
 
-The plugin bundles the hooks (`SessionStart`/`SubagentStart` priming, a `PreToolUse` guard) and a canonical workflow skill, so guidance travels to **every** repo automatically — no per-repo setup. It calls the `dotmd` CLI, so keep `npm install -g dotmd-cli` installed too. (Source: `plugins/dotmd/` in this repo.)
+The plugin bundles the hooks (`SessionStart`/`SubagentStart` priming, a `PreToolUse` guard) and a canonical workflow skill, so guidance travels to **every** repo automatically — no per-repo setup. (Source: `plugins/dotmd/` in this repo.)
+
+> **The plugin requires a _global_ CLI install.** Its hooks resolve `dotmd` from your `PATH`, so run `npm install -g dotmd-cli`. A project devDependency (`npm install -D dotmd-cli`) lives at `./node_modules/.bin/dotmd` — off `PATH` — so the hooks silently no-op (no errors, just no priming/guarding). Use the devDep for `npm run` scripts; use the global install for the plugin.
 
 > **Upgrading to 0.57.0+:** per-repo `.claude/commands/{plans,docs,baton}.md` scaffolding is retired — that guidance now ships via the plugin's workflow skill and `/plans`, `/docs`, `/prompts`, `/baton` commands. On the next `dotmd hud` (SessionStart), dotmd removes those generated files (only banner-stamped `<!-- dotmd-generated -->` ones — your hand-authored command files are never touched). If you'd committed them, you'll see deletions to commit — that's expected. Run `claude plugin update dotmd@dotmd` to pick up `/baton`.
 
@@ -195,15 +197,34 @@ runlist:
 ---
 ```
 
+Scaffold the whole sprint in one command instead of hand-writing the hub + children:
+
+```bash
+$ dotmd new plan auth-revamp --runlist extract,rewrite,cleanup
+Created: plans/auth-revamp.md (plan (runlist hub))
+Created: plans/auth-revamp-01-extract.md (plan · runlist child, planned)
+Created: plans/auth-revamp-02-rewrite.md (plan · runlist child, planned)
+Created: plans/auth-revamp-03-cleanup.md (plan · runlist child, planned)
+```
+
+That writes the hub above (the `runlist:` array + an `## Order of operations` link list) plus one `planned` child stub per slug, each carrying a `parent_plan: auth-revamp.md` back-ref. Then walk the sequence:
+
 ```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)
+$ dotmd runlist auth-revamp          # the sequence + statuses; → marks the next pickup
+runlist: plans/auth-revamp.md
+  →  1. [planned] plans/auth-revamp-01-extract.md
+     2. [planned] plans/auth-revamp-02-rewrite.md
+     3. [planned] plans/auth-revamp-03-cleanup.md
+
+$ dotmd runlist next auth-revamp     # pick up the → child (planned → in-session) + print its card
+▶ Started: plans/auth-revamp-01-extract.md (planned → in-session)
+
+$ 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.
+In `dotmd plans`, the hub folds its children under one tagged row — `auth-revamp  runlist · 0/3 · next → 01-extract  [RUNLIST]` — 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`.
 

package/bin/dotmd.mjs

@@ -451,21 +451,21 @@ Composes with the usual query flags:
   dotmd grep retries --limit 5             cap results (default: unlimited)
   dotmd grep retries --json                machine-readable (bodyMatches per doc)`,
 
-  ship: `dotmd ship [patch|minor|major] — regen + commit + bump in one step
+  ship: `dotmd ship [patch|minor|major] — commit + bump in one step
 
 Bundles the release steps into a single command:
-  1. Regenerate \`.claude/commands/*.md\` with the TARGET version stamp
-     (the post-bump version, so the slash-command files match the new
-     release and no dirty tree lingers after).
-  2. Auto-stage every dirty file matching the release allowlist
-     (src/, test/, bin/, docs/, .claude/commands/, package*.json,
-     dotmd.config*.mjs, README.md, CLAUDE.md, .gitignore). Anything
-     outside the allowlist is left dirty — secrets, WIP, etc. never get
-     bundled in.
-  3. Commit with an auto-generated \`chore: release <version>\` message.
-  4. Run \`npm version <bump>\` to bump package.json, tag, push, run
+  1. Auto-stage every dirty file matching the release allowlist
+     (src/, test/, bin/, docs/, plugins/, .claude-plugin/,
+     .claude/commands/, package*.json, dotmd.config*.mjs, README.md,
+     CLAUDE.md, .gitignore). Anything outside the allowlist is left
+     dirty — secrets, WIP, etc. never get bundled in.
+  2. Commit with an auto-generated \`chore: release <version>\` message.
+  3. Run \`npm version <bump>\` to bump package.json, tag, push, run
      the publish workflow, and reinstall locally.
 
+(Per-repo \`.claude/commands\` scaffolding is retired — the dotmd plugin's
+SKILL.md is canonical now — so ship no longer regenerates anything.)
+
 Options:
   --dry-run, -n          Show what would happen without staging or bumping.
 
@@ -758,10 +758,10 @@ Modes:
                          in their Version History would be misleading).
   --migrate-template --json  Machine-readable result.
   --frontmatter-fix      Auto-fix the long-frontmatter warnings that
-                         \`dotmd check\` flags: \`current_state\` >500 chars
-                         or \`next_step\` >300 chars. Truncates the
+                         \`dotmd check\` flags: \`current_state\` >1500 chars
+                         or \`next_step\` >800 chars. Truncates the
                          frontmatter field at the nearest sentence
-                         boundary under the target (300 / 200) and
+                         boundary under the target (1200 / 600) and
                          appends the remainder to a \`## Current State\`
                          / \`## Next Step\` body section (created above
                          the first H2 if absent, appended otherwise).
@@ -843,6 +843,20 @@ Examples:
   EOF
   dotmd new plan auth-revamp "Investigation findings before scoping…"
 
+Scaffolding runlists (plans only):
+  --runlist <a,b,c>    Create a sprint runlist hub plus one child plan per slug.
+                       The hub carries \`runlist: [<hub>-01-a.md, <hub>-02-b.md, …]\`
+                       and an \`## Order of operations\` list; each child is a
+                       \`planned\` stub with a \`parent_plan:\` back-ref. Children
+                       are named by the documented \`<hub>-NN-<slug>\` convention.
+  --coordination       Create a prose-first coordination hub: \`execution_mode:
+                       coordination\` + a \`## Ranked queue\` skeleton (no children).
+                       Surfaces in \`dotmd runlists\`, held out of the active count.
+  (\`--runlist\` and \`--coordination\` are mutually exclusive.)
+
+  dotmd new plan auth-revamp --runlist extract,rewrite,cleanup
+  dotmd new plan platform --coordination
+
 Other options:
   --status <s>         Set initial status (defaults to first valid status for the type)
   --title <t>          Override the auto-derived title
@@ -853,7 +867,7 @@ Other options:
 
 For plans, the default status vocabulary is: in-session, active, planned,
 blocked, partial, paused, awaiting, queued-after, archived.
-For prompts: pending (default), claimed, archived.
+For prompts: pending (default), held, shelved, claimed, archived.
 
 Use --dry-run (-n) to preview without creating the file.`,
 
@@ -1225,14 +1239,19 @@ 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.`,
+and out of the active count. \`dotmd runlists\` shows that dashboard on its own.
+For these, \`runlist\`/\`runlist next\` also read order from the body when there's
+no \`runlist:\` array — a \`## Ranked queue\` table or \`## Order of operations\`
+list of markdown links (the first \`.md\` link per row/item, in order).`,
 
   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.
+size of its \`related_plans:\` cluster, a \`next → <child>\` when the hub's body
+encodes order as markdown links (\`## Ranked queue\` table / \`## Order of
+operations\` list), and a one-line descriptor.
 
 This is the standalone form of the \`Runlists\` section that \`dotmd plans\`
 pins beneath the leaf-plan triage list.
@@ -1240,7 +1259,7 @@ 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, …).`,
+  dotmd runlists --json        Structured rows (path, status, childCount, nextPickup, …).`,
 
   'bulk-tag': `dotmd bulk-tag [files...] — fill in type/status frontmatter on pre-existing markdown
 
@@ -1268,7 +1287,6 @@ the whole docs tree is scanned.`,
 
 async function main() {
   const args = process.argv.slice(2);
-  let command = args[0] ?? 'list';
 
   // Pre-config flags
   if (args.includes('--version') || args.includes('-v')) {
@@ -1276,8 +1294,70 @@ async function main() {
     return;
   }
 
+  // Normalize global flags from ANYWHERE in argv (before OR after the command)
+  // so `dotmd --config x list` resolves `list` as the command, not `--config`.
+  // Value flags (--config/--root/--type) consume the next token; the booleans
+  // (--dry-run/-n/--verbose) are read positionally below. --help/-h stay in the
+  // leftover stream and are handled by the blocks just below.
+  let explicitConfig = null;
+  let rootArg = null;
+  let typeArg = null;
+  const normalized = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--config' && args[i + 1]) { explicitConfig = args[++i]; continue; }
+    if (a === '--type' && args[i + 1]) { typeArg = args[++i]; continue; }
+    if (a === '--root' && args[i + 1]) { rootArg = args[++i]; continue; }
+    if (a === '--dry-run' || a === '-n' || a === '--verbose') continue;
+    normalized.push(a);
+  }
+  const dryRun = args.includes('--dry-run') || args.includes('-n');
+  const verbose = args.includes('--verbose');
+  let command = normalized[0] ?? 'list';
+  const restArgs = normalized.slice(1);
+
+  // Reconstruct the active global flags for proxy commands (e.g. `watch`) that
+  // re-invoke the CLI in a child process and must propagate them through.
+  const globalFlagArgs = () => {
+    const out = [];
+    if (explicitConfig) out.push('--config', explicitConfig);
+    if (rootArg) out.push('--root', rootArg);
+    if (typeArg) out.push('--type', typeArg);
+    if (dryRun) out.push('--dry-run');
+    if (verbose) out.push('--verbose');
+    return out;
+  };
+
+  // Apply global --root / --type filters to an index in place. Shared by the
+  // common index path below AND the early-dispatched commands (plans, runlists,
+  // presets) that build their own index, so filtering is consistent everywhere.
+  // Recomputes BOTH countsByStatus and countsByType so filtered JSON never
+  // reports corpus-wide tallies.
+  function applyIndexFilters(idx) {
+    if (rootArg) {
+      idx.docs = idx.docs.filter(d => d.root === rootArg || d.root.endsWith('/' + rootArg) || d.root.split('/').pop() === rootArg);
+    }
+    if (typeArg) {
+      const types = typeArg.split(',').map(t => t.trim()).filter(Boolean);
+      idx.docs = idx.docs.filter(d => types.includes(d.type));
+    }
+    if (rootArg || typeArg) {
+      idx.errors = idx.errors.filter(e => idx.docs.some(d => d.path === e.path));
+      idx.warnings = idx.warnings.filter(w => idx.docs.some(d => d.path === w.path));
+      idx.countsByStatus = {};
+      idx.countsByType = {};
+      for (const doc of idx.docs) {
+        const status = doc.status ?? 'unknown';
+        idx.countsByStatus[status] = (idx.countsByStatus[status] ?? 0) + 1;
+        const type = doc.type || 'unknown';
+        if (!idx.countsByType[type]) idx.countsByType[type] = {};
+        idx.countsByType[type][status] = (idx.countsByType[type][status] ?? 0) + 1;
+      }
+    }
+  }
+
   if (command === 'help' || command === '--help' || command === '-h') {
-    const topic = args[1];
+    const topic = restArgs[0];
     if (topic) {
       const key = `help:${topic}`;
       if (HELP[key]) { process.stdout.write(`${HELP[key]}\n`); return; }
@@ -1305,22 +1385,10 @@ async function main() {
 
   if (command === 'completions') {
     const { runCompletions } = await import('../src/completions.mjs');
-    runCompletions(args.slice(1));
+    runCompletions(restArgs);
     return;
   }
 
-  // Extract --config flag
-  let explicitConfig = null;
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === '--config' && args[i + 1]) {
-      explicitConfig = args[i + 1];
-      break;
-    }
-  }
-
-  const dryRun = args.includes('--dry-run') || args.includes('-n');
-  const verbose = args.includes('--verbose');
-
   const config = await resolveConfig(process.cwd(), explicitConfig);
   _resolvedConfig = config;
 
@@ -1332,20 +1400,9 @@ async function main() {
     return;
   }
 
-  // Watch is a pure proxy — pass raw args so the child process gets all flags
-  if (command === 'watch') { const { runWatch } = await import('../src/watch.mjs'); runWatch(args.slice(1), config); return; }
-
-  // Strip global flags from restArgs so commands don't have to filter them
-  const restArgs = [];
-  let rootArg = null;
-  let typeArg = null;
-  for (let i = 1; i < args.length; i++) {
-    if (args[i] === '--config') { i++; continue; }
-    if (args[i] === '--type' && args[i + 1]) { typeArg = args[++i]; continue; }
-    if (args[i] === '--root' && args[i + 1]) { rootArg = args[++i]; continue; }
-    if (args[i] === '--dry-run' || args[i] === '-n' || args[i] === '--verbose') continue;
-    restArgs.push(args[i]);
-  }
+  // Watch is a proxy — re-inject the active globals so the child re-resolves
+  // the same config/filters.
+  if (command === 'watch') { const { runWatch } = await import('../src/watch.mjs'); runWatch([...globalFlagArgs(), ...restArgs], config); return; }
 
   // Hook commands (`hud`, `guard`) fire in EVERY repo via the globally-enabled
   // plugin — `guard` runs on every Bash/Read/Edit. They must stay silent where
@@ -1376,7 +1433,8 @@ async function main() {
     const { buildIndex } = await import('../src/index.mjs');
     const { runQuery } = await import('../src/query.mjs');
     const index = buildIndex(config);
-    runQuery(index, [...config.presets[command], ...restArgs], config, { preset: command });
+    applyIndexFilters(index);
+    runQuery(index, [...config.presets[command], ...restArgs], config, { preset: command, type: typeArg, root: rootArg });
     return;
   }
 
@@ -1388,6 +1446,7 @@ async function main() {
     const { buildIndex } = await import('../src/index.mjs');
     const { runQuery } = await import('../src/query.mjs');
     const index = buildIndex(config);
+    applyIndexFilters(index);
     const sub = restArgs[0];
     let defaults;
     let extras = restArgs;
@@ -1397,7 +1456,7 @@ async function main() {
     } else {
       defaults = ['--type', 'plan', '--exclude-archived', '--sort', 'updated', '--limit', '10'];
     }
-    runQuery(index, [...defaults, ...extras], config, { preset: 'plans' });
+    runQuery(index, [...defaults, ...extras], config, { preset: 'plans', type: typeArg, root: rootArg });
     return;
   }
   // `dotmd runlists` (plural) — the coordination-hub dashboard (the `Runlists`
@@ -1407,6 +1466,7 @@ async function main() {
     const { buildIndex } = await import('../src/index.mjs');
     const { runRunlists } = await import('../src/query.mjs');
     const index = buildIndex(config);
+    applyIndexFilters(index);
     runRunlists(index, restArgs, config);
     return;
   }
@@ -1512,34 +1572,8 @@ async function main() {
   const AUTO_HEAL_INDEX_COMMANDS = new Set(['check']);
   const index = buildIndex(config, { autoHealIndex: AUTO_HEAL_INDEX_COMMANDS.has(command) && !checkHasPathScope });
 
-  // Apply --root and --type filters
-  const rootFilter = rootArg;
-  const typeFilter = typeArg;
-
-  function applyIndexFilters(idx) {
-    if (rootFilter) {
-      idx.docs = idx.docs.filter(d => d.root === rootFilter || d.root.endsWith('/' + rootFilter) || d.root.split('/').pop() === rootFilter);
-    }
-    if (typeFilter) {
-      const types = typeFilter.split(',').map(t => t.trim()).filter(Boolean);
-      idx.docs = idx.docs.filter(d => types.includes(d.type));
-    }
-    if (rootFilter || typeFilter) {
-      idx.errors = idx.errors.filter(e => idx.docs.some(d => d.path === e.path));
-      idx.warnings = idx.warnings.filter(w => idx.docs.some(d => d.path === w.path));
-      idx.countsByStatus = {};
-      for (const doc of idx.docs) {
-        const s = doc.status ?? 'unknown';
-        idx.countsByStatus[s] = (idx.countsByStatus[s] ?? 0) + 1;
-      }
-    }
-  }
-
   applyIndexFilters(index);
 
-  if (rootFilter || typeFilter) {
-  }
-
   if (verbose) {
     process.stderr.write(`Docs found: ${index.docs.length}\n`);
   }
@@ -1666,7 +1700,7 @@ async function main() {
   }
 
   if (command === 'focus') { runFocus(index, restArgs, config); return; }
-  if (command === 'query') { runQuery(index, restArgs, config); return; }
+  if (command === 'query') { runQuery(index, restArgs, config, { type: typeArg, root: rootArg }); return; }
   // `dotmd grep <term>` — ergonomic alias for `query --keyword <term> --body`.
   // Unlimited by default (grep semantics) unless the caller bounds it themselves.
   if (command === 'grep') {

package/dotmd.config.example.mjs

@@ -76,6 +76,8 @@ export const excludeDirs = ['evidence'];
 //     // pending prompts on session start; `dotmd prompts next` claims the oldest.
 //     statuses: {
 //       'pending':  { context: 'expanded', staleDays: 30 },
+//       'held':     { context: 'counted', quiet: true },   // saved but not next: hidden from hud/briefing, skipped by no-arg `use`
+//       'shelved':  { context: 'counted', quiet: true },   // legacy alias for held
 //       'claimed':  { context: 'counted', quiet: true },
 //       'archived': { context: 'counted', archive: true, terminal: true, quiet: true },
 //     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.62.0",
+  "version": "0.64.0",
   "description": "CLI for managing markdown documents with YAML frontmatter — index, query, validate, graph, export, Notion sync, AI summaries.",
   "type": "module",
   "license": "MIT",
@@ -42,7 +42,7 @@
     "test": "node --test test/*.test.mjs",
     "postinstall": "node scripts/postinstall.mjs",
     "preversion": "npm test",
-    "version": "node bin/dotmd.mjs hud >/dev/null 2>&1; node scripts/sync-plugin-version.mjs; git add .claude/commands docs/docs.md plugins/dotmd/.claude-plugin/plugin.json .claude-plugin/marketplace.json 2>/dev/null; true",
+    "version": "node bin/dotmd.mjs hud >/dev/null 2>&1; node scripts/sync-plugin-version.mjs; git add .claude/commands docs/docs.md plugins .claude-plugin 2>/dev/null; true",
     "postversion": "bash scripts/postversion.sh"
   },
   "engines": {

package/scripts/postinstall.mjs

@@ -28,7 +28,12 @@ try {
     spawnSync('claude', ['plugin', 'update', 'dotmd@dotmd'], { stdio: 'ignore', timeout: 60000 });
     process.stdout.write('dotmd: refreshed the Claude Code plugin — restart your session (or /reload-plugins) to apply.\n');
   } else {
-    process.stdout.write('dotmd CLI installed. Using the Claude Code plugin? Run `dotmd update` to refresh it too, then restart.\n');
+    // The CLI just installed fresh, so only the plugin can be stale — point at
+    // the targeted refresh rather than the full `dotmd update` (CLI + plugin).
+    const nudge = hasClaude
+      ? 'dotmd CLI installed. Using the Claude Code plugin? Run `dotmd update --plugin-only` to refresh it, then restart.'
+      : 'dotmd CLI installed.';
+    process.stdout.write(`${nudge}\n`);
   }
 } catch {
   // Best effort only — never break the install.

package/src/commands.mjs

@@ -5,7 +5,7 @@
 export const KNOWN_COMMANDS = [
   'list', 'json', 'check', 'coverage', 'stats', 'graph', 'deps', 'briefing', 'context', 'agent-context', 'hud',
   'focus', 'query', 'grep', 'plans', 'prompts', 'stale', 'actionable', 'index', 'status', 'set', 'use', 'next', 'archive', 'bulk', 'bulk-tag', 'touch', 'doctor', 'runlist', 'runlists',
-  'unblocks', 'health', 'glossary', 'modules', 'module',
+  'unblocks', 'health', 'glossary', 'modules', 'module', 'surfaces',
   'fix-refs', 'lint', 'rename', 'migrate', 'notion', 'export', 'summary',
   'watch', 'diff', 'new', 'init', 'completions', 'statuses', 'journal',
   'guard', 'misuse', 'update',

package/src/completions.mjs

@@ -1,52 +1,77 @@
 import { die } from './util.mjs';
+import { KNOWN_COMMANDS } from './commands.mjs';
 
-const COMMANDS = [
-  'list', 'json', 'check', 'coverage', 'stats', 'graph', 'deps', 'unblocks', 'health', 'glossary', 'briefing', 'context', 'focus', 'query', 'grep',
-  'plans', 'runlist', 'runlists', 'stale', 'actionable', 'index', 'status', 'set', 'archive', 'bulk', 'touch', 'doctor', 'lint', 'rename', 'migrate',
-  'fix-refs', 'notion', 'export', 'summary', 'watch', 'diff', 'init', 'new', 'completions', 'journal',
-];
+// Derive the completable command list from the dispatcher's canonical verb list
+// so completions never drift behind new commands. A tiny denylist drops verbs
+// that exist but shouldn't be tab-completed (internal self-test).
+const COMPLETION_DENYLIST = new Set(['self-check']);
+const COMMANDS = KNOWN_COMMANDS.filter(c => !COMPLETION_DENYLIST.has(c));
 
 const GLOBAL_FLAGS = ['--config', '--dry-run', '--verbose', '--root', '--type', '--help', '--version'];
 
+// Shared filter flags for the query-style commands (mirrors QUERY_FLAGS in
+// bin/dotmd.mjs). Kept as one array so query/grep/stale/actionable/plans stay
+// in lockstep.
+const QUERY_FLAGS = [
+  '--type', '--status', '--keyword', '--body', '--owner', '--surface', '--module',
+  '--domain', '--audience', '--execution-mode', '--updated-since', '--limit', '--sort',
+  '--group', '--all', '--include-archived', '--exclude-archived', '--stale',
+  '--has-next-step', '--has-blockers', '--checklist-open', '--json', '--git',
+  '--summarize', '--summarize-limit', '--model',
+];
+
 const COMMAND_FLAGS = {
-  query: ['--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'],
-  grep: ['--type', '--status', '--limit', '--all', '--json', '--sort',
-         '--module', '--surface', '--domain', '--owner'],
-  index: ['--write'],
+  query: QUERY_FLAGS,
+  grep: QUERY_FLAGS,
+  stale: QUERY_FLAGS,
+  actionable: QUERY_FLAGS,
+  plans: ['status', ...QUERY_FLAGS],
   list: ['--verbose', '--json'],
+  briefing: ['--json'],
+  context: ['--json', '--compact', '--summarize', '--model'],
+  'agent-context': ['--json'],
+  hud: ['--json', '--subagent'],
+  index: ['--write'],
   coverage: ['--json'],
-  new: ['--status', '--title', '--template', '--list-templates', '--root'],
-  diff: ['--stat', '--since', '--summarize', '--model'],
-  check: ['--errors-only', '--fix', '--json'],
   stats: ['--json'],
   graph: ['--dot', '--json', '--status', '--module', '--surface'],
   deps: ['--json', '--depth'],
   unblocks: ['--json'],
   health: ['--json'],
   glossary: ['--list', '--json'],
-  bulk: ['archive'],
+  modules: ['--sort', '--json'],
+  module: ['--json'],
+  surfaces: ['--json'],
+  runlists: ['--json', '--limit', '--sort'],
+  runlist: ['next', '--json', '--full', '--no-index', '--show-files'],
+  prompts: ['list', 'next', 'use', 'show', 'archive', 'new', 'hold', 'unhold',
+            '--json', '--status', '--include-archived', '--sort', '--limit', '--all'],
+  use: [],
+  next: [],
+  baton: ['--status', '--note', '--body', '--message', '--dry-run'],
+  set: [],
+  status: [],
+  archive: ['--note', '--no-index', '--show-files', '--closeout-template'],
+  bulk: ['archive', 'tag'],
+  statuses: ['list', 'add', '--type', '--like', '--json'],
+  update: ['--check', '--cli-only', '--plugin-only'],
+  misuse: ['--json', '--tail', '--by-rule', '--repo'],
+  journal: ['--tail', '--errors', '--session', '--since', '--by-command', '--json'],
+  new: ['--status', '--title', '--template', '--list-templates', '--root', '--message', '--body'],
   notion: ['import', 'export', 'sync', '--force', '--dry-run'],
   export: ['--format', '--output', '--status', '--module', '--root', '--type'],
   focus: ['--json'],
-  plans: ['--status', '--json', '--sort', '--limit', '--all', '--stale', '--has-next-step'],
-  stale: ['--json', '--sort', '--limit', '--all'],
-  actionable: ['--json', '--sort', '--limit', '--all'],
-  briefing: ['--json'],
-  status: [],
-  archive: [],
-  doctor: [],
-  watch: [],
+  summary: ['--model', '--max-tokens', '--json'],
+  diff: ['--stat', '--since', '--summarize', '--model'],
+  touch: ['--git'],
+  check: ['--fix', '--errors-only', '--no-collapse', '--json', '--verbose'],
+  doctor: ['--apply', '--yes', '--dry-run', '--statuses', '--migrate-template',
+           '--migrate-prompts', '--frontmatter-fix', '--project', '--json', '--include-archived'],
   lint: ['--fix'],
+  ship: [],
   rename: [],
   migrate: [],
   'fix-refs': [],
-  summary: ['--model', '--max-tokens', '--json'],
-  context: ['--summarize', '--model', '--json'],
-  touch: ['--git'],
-  journal: ['--tail', '--errors', '--session', '--since', '--by-command', '--json'],
 };
 
 function bashCompletion() {

package/src/config.mjs

@@ -307,8 +307,14 @@ function validateConfig(userConfig, config, validStatuses, indexPath) {
     }
   }
 
-  // staleDays keys must exist in validStatuses
-  if (config.statuses?.staleDays) {
+  // staleDays keys must exist in validStatuses — but only validate the map when
+  // the user actually wrote `statuses.staleDays`. When it's inherited from
+  // defaults (user overrode `statuses.order` but left staleDays unset), the
+  // default map is keyed by default statuses (`ready`, `scoping`, …) that the
+  // user's order may not include — warning there blames the user for keys they
+  // never authored and makes brownfield repos noisy on every command, hook
+  // included. Real typos in a user-provided map are still caught.
+  if (userConfig.statuses?.staleDays && config.statuses?.staleDays) {
     for (const key of Object.keys(config.statuses.staleDays)) {
       if (!validStatuses.has(key)) {
         warnings.push(`Config: statuses.staleDays contains unknown status '${key}'.`);

package/src/health.mjs

@@ -87,7 +87,7 @@ export function runHealth(argv, config) {
       ready: { count: readyPlans.length },
       planned: { count: plannedPlans.length },
       recentlyArchived: { count: recentlyArchived.length, last30d: recentlyArchived.map(d => path.basename(d.path, '.md')) },
-      runlists: { count: runlistHubs.length, hubs: runlistHubs.map(d => ({ path: d.path, title: d.title, status: d.status, childCount: coordination.get(d.path)?.childCount ?? 0 })) },
+      runlists: { count: runlistHubs.length, hubs: runlistHubs.map(d => ({ path: d.path, title: d.title, status: d.status, childCount: coordination.get(d.path)?.childCount ?? 0, nextPickup: coordination.get(d.path)?.nextPickup ?? null })) },
     }, null, 2) + '\n');
     return;
   }
@@ -122,9 +122,10 @@ export function runHealth(argv, config) {
     for (const doc of runlistHubs.slice(0, 8)) {
       const slug = hubLabel(doc).padEnd(28);
       const age = doc.daysSinceUpdate != null ? `${doc.daysSinceUpdate}d` : '?d';
-      const rel = coordination.get(doc.path)?.childCount;
-      const relStr = rel ? `  ${dim(`${rel} related`)}` : '';
-      process.stdout.write(`  ${slug} ${dim(age.padStart(4))}${relStr}\n`);
+      const info = coordination.get(doc.path);
+      const relStr = info?.childCount ? `  ${dim(`${info.childCount} related`)}` : '';
+      const nextStr = info?.nextPickup ? `  ${green('→')} ${info.nextPickup.label}` : '';
+      process.stdout.write(`  ${slug} ${dim(age.padStart(4))}${relStr}${nextStr}\n`);
     }
     if (runlistHubs.length > 8) {
       process.stdout.write(`  ${dim(`...and ${runlistHubs.length - 8} more`)}\n`);