dotmd-cli 0.63.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.`,
 
@@ -1273,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')) {
@@ -1281,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; }
@@ -1310,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;
 
@@ -1337,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
@@ -1381,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;
   }
 
@@ -1393,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;
@@ -1402,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`
@@ -1412,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;
   }
@@ -1517,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`);
   }
@@ -1671,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.63.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/init.mjs

@@ -152,6 +152,16 @@ function countMarkdownFiles(dir) {
   return { withFrontmatter, withoutFrontmatter };
 }
 
+// Sensible default stale thresholds (days) for statuses dotmd recognizes, used
+// only to scope the generated config's staleDays to detected statuses. Mirrors
+// the global + per-type defaults in config.mjs DEFAULTS; the repo's own custom
+// statuses are intentionally absent so we don't invent a threshold for vocab we
+// don't understand.
+const KNOWN_STALE_DAYS = {
+  'in-session': 1, active: 14, ready: 14, planned: 30, blocked: 30,
+  scoping: 30, paused: 3, awaiting: 14, draft: 30, review: 14, pending: 30,
+};
+
 function generateDetectedConfig(scan, rootPath) {
   const lines = [`// dotmd.config.mjs — auto-detected from ${scan.docCount} existing docs`, ''];
   lines.push(`export const root = '${rootPath}';`);
@@ -164,6 +174,18 @@ function generateDetectedConfig(scan, rootPath) {
   if (allStatuses.length > 0) {
     lines.push('export const statuses = {');
     lines.push(`  order: [${allStatuses.map(s => `'${s}'`).join(', ')}],`);
+    // Scope staleDays to the detected statuses. `statuses.staleDays` is a
+    // replace-key, so emitting it here stops the resolver from inheriting the
+    // default map (keyed by `ready`/`scoping`/… that this repo may not use) —
+    // which otherwise makes every command warn about statuses the user never
+    // wrote. Only statuses with a sensible known threshold get an entry;
+    // unrecognized ones (the repo's own vocab) are left for the user to tune.
+    const staleEntries = allStatuses.filter(s => s in KNOWN_STALE_DAYS);
+    if (staleEntries.length > 0) {
+      lines.push('  staleDays: {');
+      for (const s of staleEntries) lines.push(`    '${s}': ${KNOWN_STALE_DAYS[s]},`);
+      lines.push('  },');
+    }
     lines.push('};');
     lines.push('');
   }
@@ -333,16 +355,24 @@ export async function runInit(cwd, config, opts = {}) {
   // Claude Code integration. dotmd no longer scaffolds per-repo
   // `.claude/commands/*.md` slash commands — the dotmd plugin's SKILL.md is the
   // canonical agent-facing workflow now, and `dotmd hud` injects this repo's
-  // status vocab at runtime. If a `.claude/` exists, sweep any retired
-  // generated command files (banner-gated, so hand-authored ones survive) and
-  // point the user at the plugin instead.
-  if (existsSync(path.join(cwd, '.claude'))) {
+  // status vocab at runtime.
+  const hasProjectClaude = existsSync(path.join(cwd, '.claude'));
+  // A project `.claude/` proves it; a user-global `~/.claude/` means they run
+  // Claude Code elsewhere, so the plugin nudge is still relevant before this
+  // repo has any `.claude/` of its own (the common greenfield case).
+  const likelyClaudeUser = hasProjectClaude || existsSync(path.join(os.homedir(), '.claude'));
+
+  // If a `.claude/` exists, sweep any retired generated command files
+  // (banner-gated, so hand-authored ones survive).
+  if (hasProjectClaude) {
     const removed = removeGeneratedSlashCommands(cwd, { dryRun });
     for (const r of removed) {
       const verb = dryRun ? 'would remove' : 'removed';
       process.stdout.write(`  ${dryTag}${yellow('clean')}   .claude/commands/${r.name} (retired — ${verb}; guidance ships via the dotmd plugin)\n`);
     }
+  }
 
+  if (likelyClaudeUser) {
     const sessionStart = detectSessionStartHook(cwd);
     if (sessionStart.wired) {
       process.stdout.write(`  ${dim('exists')}  ${sessionStart.file} (SessionStart hook for \`dotmd hud\` already wired)\n`);
@@ -351,6 +381,8 @@ export async function runInit(cwd, config, opts = {}) {
       process.stdout.write(`            travel to every session and subagent automatically:\n\n`);
       process.stdout.write(`              /plugin marketplace add reowens/dotmd\n`);
       process.stdout.write(`              /plugin install dotmd@dotmd\n\n`);
+      process.stdout.write(`            The plugin's hooks call \`dotmd\` on your PATH, so install the CLI\n`);
+      process.stdout.write(`            globally too — ${green('npm i -g dotmd-cli')} (a project devDependency won't power them).\n\n`);
       process.stdout.write(`            Or, without the plugin, wire \`dotmd hud\` at SessionStart by hand —\n`);
       process.stdout.write(`            add to .claude/settings.json (merge into any existing hooks):\n\n`);
       process.stdout.write(`              "hooks": { "SessionStart": [\n`);

package/src/lifecycle.mjs

@@ -457,26 +457,37 @@ export function runArchive(argv, config, opts = {}) {
   const parsed = parseSimpleFrontmatter(frontmatter);
   const oldStatus = asString(parsed.status) ?? 'unknown';
 
+  // Preserve a configured custom archive status (e.g. `done` with archive:true)
+  // when one is threaded through from `dotmd set <archive-status>`. Fall back to
+  // the canonical `archived`, or — if the config has no `archived` at all — its
+  // first declared archive status, so we never write a status the config can't
+  // validate.
+  const archiveStatuses = config.lifecycle.archiveStatuses;
+  const defaultArchiveStatus = archiveStatuses.has('archived')
+    ? 'archived'
+    : (archiveStatuses.values().next().value ?? 'archived');
+  const targetStatus = opts.archiveStatus ?? defaultArchiveStatus;
+
   // Heal stuck frontmatter (issue #13): file is under archiveDir/ but its
   // status hasn't been flipped. Flip in place; don't try to move (it's already
   // archived on disk) and don't refuse — refusal leaves the drift permanent.
   if (inArchiveDir) {
-    if (oldStatus === 'archived') {
+    if (oldStatus === targetStatus) {
       die(`Already archived: ${toRepoPath(filePath, config.repoRoot)}`);
     }
     const today = nowIso();
     const repoPathHeal = toRepoPath(filePath, config.repoRoot);
     if (dryRun) {
       const prefix = dim('[dry-run]');
-      out.write(`${prefix} Would heal frontmatter in place: status: ${oldStatus} → archived, updated: ${today}\n`);
+      out.write(`${prefix} Would heal frontmatter in place: status: ${oldStatus} → ${targetStatus}, updated: ${today}\n`);
       out.write(`${prefix} Would skip git mv (file already under \`${config.archiveDir}/\`)\n`);
       return;
     }
-    updateFrontmatter(filePath, { status: 'archived', updated: today });
+    updateFrontmatter(filePath, { status: targetStatus, updated: today });
     const healEntry = `Archived (frontmatter healed in place from \`${oldStatus}\`)${note ? ` — ${note}` : '.'}`;
     appendVersionHistory(filePath, healEntry, { createSection: Boolean(note) });
     if (!noIndex) regenIndex(config);
-    out.write(`${green('✓ Healed')}: ${repoPathHeal} (${oldStatus} → archived; file already under \`${config.archiveDir}/\`)\n`);
+    out.write(`${green('✓ Healed')}: ${repoPathHeal} (${oldStatus} → ${targetStatus}; file already under \`${config.archiveDir}/\`)\n`);
     const touched = [repoPathHeal];
     if (config.indexPath && !noIndex) touched.push(config.indexPath);
     if (showFiles) emitFilesFooter(touched, config);
@@ -505,7 +516,7 @@ export function runArchive(argv, config, opts = {}) {
     } else if (closeoutAction?.action === 'skip') {
       out.write(`${prefix} \`## Closeout\` section already present — no injection\n`);
     }
-    out.write(`${prefix} Would update frontmatter: status: ${oldStatus} → archived, updated: ${today}\n`);
+    out.write(`${prefix} Would update frontmatter: status: ${oldStatus} → ${targetStatus}, updated: ${today}\n`);
     if (note) {
       out.write(`${prefix} Would append Version History: - **${today}** Archived — ${note}\n`);
     }
@@ -530,7 +541,7 @@ export function runArchive(argv, config, opts = {}) {
     writeFileSync(filePath, `---\n${frontmatter}\n---\n${closeoutAction.newBody}`, 'utf8');
   }
 
-  updateFrontmatter(filePath, { status: 'archived', updated: today });
+  updateFrontmatter(filePath, { status: targetStatus, updated: today });
   appendVersionHistory(filePath, note ? `Archived — ${note}` : 'Archived.', { createSection: Boolean(note) });
 
   mkdirSync(targetDir, { recursive: true });
@@ -614,7 +625,10 @@ export async function runSet(argv, config, opts = {}) {
     const archiveArgs = [filePath];
     if (noIndex) archiveArgs.push('--no-index');
     if (showFiles) archiveArgs.push('--show-files');
-    return runArchive(archiveArgs, config, { dryRun, note });
+    // Preserve the exact target status — a config may name its archive status
+    // `done` (with archive:true) rather than `archived`. Without this, runArchive
+    // would silently rewrite it to `archived`.
+    return runArchive(archiveArgs, config, { dryRun, note, archiveStatus: newStatus });
   }
 
   // `partial` promises a successor tracking the deferred tail. When neither a
@@ -784,7 +798,9 @@ export function runTouch(argv, config, opts = {}) {
 // when archiving `child.md` (suffix match). oldPath no longer exists on disk
 // post-`git mv`, so existsSync-based resolveRefPath can't be used here.
 function rewriteFrontmatterRefs(fm, docDir, oldPath, newPath, repoRoot) {
-  return fm.replace(/[^\s"'<>:]+\.md\b/g, (token) => {
+  // Exclude [ ] , from the token so flow-array elements (`refs: [a.md, b.md]`)
+  // match individually rather than swallowing the bracket and failing to resolve.
+  return fm.replace(/[^\s"'<>:[\],]+\.md\b/g, (token) => {
     const docRelAbs = path.resolve(docDir, token);
     const repoRelAbs = path.resolve(repoRoot, token);
     if (docRelAbs !== oldPath && repoRelAbs !== oldPath) return token;
@@ -848,24 +864,28 @@ function updateRefsFromMovedFile(oldPath, newPath, config) {
   // when the source moves. Without the repo-root fallback, repo-relative refs
   // silently skipped rewriting (existsSync on the doubled doc-relative path
   // returned false).
+  // Token-based: rewrite every `*.md` path that resolved to a real file from
+  // the old location, regardless of YAML shape — block-sequence list items
+  // (`  - ./path.md`), inline scalars (`parent_plan: hub.md`), and flow arrays
+  // (`related_plans: [a.md, b.md]`). Quotes sit outside the matched token, so
+  // `"./path.md"` rewrites in place. Mirrors rewriteFrontmatterRefs (inbound).
   let newFm = frontmatter;
-  const refRegex = /^(\s+-\s+)(\S+\.md)$/gm;
-  newFm = newFm.replace(refRegex, (match, prefix, refPath) => {
-    const absTarget = resolveRefPath(refPath, oldDir, config.repoRoot);
-    if (!absTarget) return match;
-    const newRelPath = path.relative(newDir, absTarget).split(path.sep).join('/');
-    return `${prefix}${newRelPath}`;
+  newFm = newFm.replace(/[^\s"'<>:[\],]+\.md\b/g, (token) => {
+    const absTarget = resolveRefPath(token, oldDir, config.repoRoot);
+    if (!absTarget) return token;
+    return path.relative(newDir, absTarget).split(path.sep).join('/');
   });
 
-  // Fix body markdown links [text](path.md)
+  // Fix body markdown links [text](path.md) and [text](path.md#anchor) — the
+  // trailing fragment is preserved across the rewrite.
   let newBody = body;
-  const linkRegex = /(\[[^\]]*\]\()([^)]+\.md)(\))/g;
-  newBody = newBody.replace(linkRegex, (match, pre, href, post) => {
-    if (href.startsWith('http')) return match;
+  const linkRegex = /(\[[^\]]*\]\()([^)#]+\.md)(#[^)]*)?(\))/g;
+  newBody = newBody.replace(linkRegex, (match, pre, href, frag, post) => {
+    if (/^https?:/i.test(href)) return match;
     const absTarget = resolveRefPath(href, oldDir, config.repoRoot);
     if (!absTarget) return match;
     const newHref = path.relative(newDir, absTarget).split(path.sep).join('/');
-    return `${pre}${newHref}${post}`;
+    return `${pre}${newHref}${frag ?? ''}${post}`;
   });
 
   if (newFm !== frontmatter || newBody !== body) {

package/src/new.mjs

@@ -268,6 +268,117 @@ export function readBodyInput(source) {
   return source;
 }
 
+// Slug/title helpers shared by name resolution and runlist child generation.
+function slugify(s) {
+  return s.toLowerCase().replace(/[\s_]+/g, '-').replace(/[^a-z0-9-]/g, '').replace(/-+/g, '-').replace(/^-|-$/g, '');
+}
+function titleize(s) {
+  return s.replace(/[-_]/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+}
+
+// Resolve one `--runlist` token to a scaffolded child plan: a bare slug becomes
+// `<hub>-NN-<slug>.md` (the documented runlist naming convention). `pos` is the
+// 1-based position used for the zero-padded NN prefix. Tokens must be bare slugs
+// — a path is rejected (wiring an ordered hub to a plan that already lives
+// elsewhere needs a hub-relative ref, so it's a hand-edit, not a scaffold).
+function planChildFromToken(hubSlug, token, pos) {
+  const t = token.trim();
+  if (t.includes('/') || t.includes(path.sep)) {
+    die(`Runlist child "${token}" must be a bare slug, not a path. To put an existing plan in the runlist, add it to the hub's runlist: by hand.`);
+  }
+  const childSlug = slugify(t.replace(/\.md$/, ''));
+  if (!childSlug) die(`Runlist child token resolves to an empty slug: "${token}"`);
+  const nn = String(pos).padStart(2, '0');
+  return { file: `${hubSlug}-${nn}-${childSlug}.md`, title: titleize(t.replace(/\.md$/, '')) };
+}
+
+// Body for a sprint runlist hub: the children ARE the phases, so the heavy
+// generic plan scaffold (Goals/Phases/Deferred/…) is replaced by an ordered
+// `## Order of operations` list that mirrors the `runlist:` frontmatter.
+function runlistHubBody(title, hubSlug, children, bodyInput, today) {
+  const steps = children
+    .map((c, i) => `${i + 1}. [${c.title}](${c.file}) ⬜`)
+    .join('\n');
+  const n = children.length;
+  return `
+# ${title}
+
+> One-paragraph problem statement: what this runlist sprints toward, why now.
+
+## Problem
+
+${bodyInput?.trim() ?? ''}
+
+## Order of operations
+
+${steps}
+
+Pick up the next child with \`dotmd runlist next ${hubSlug}\` — it targets the
+first non-archived child. \`dotmd runlist ${hubSlug}\` shows the sequence + status.
+
+## Version History
+
+- **${today}** Created (runlist hub, ${n} ${n === 1 ? 'child' : 'children'}).
+`;
+}
+
+// Body for a coordination hub: prose-first domain map with a ranked-queue table.
+// Mirrors the `execution_mode: coordination` shape `dotmd runlists` reads.
+function coordinationHubBody(title, bodyInput, today) {
+  return `
+# ${title}
+
+> One-paragraph: the domain this hub coordinates and how to read the queue below.
+
+## Scope
+
+${bodyInput?.trim() ?? ''}
+
+## Ranked queue
+
+<!-- One row per coordinated plan, in pickup order; the gating column explains
+dependencies. Wire each plan into related_plans: so the "N related" count and
+graph pick it up. -->
+
+| # | Plan | Why / gating | Status |
+|---|------|--------------|--------|
+| 1 | \`<plan>.md\` | | |
+
+## Version History
+
+- **${today}** Created (coordination hub).
+`;
+}
+
+// Minimal child plan stub for a scaffolded runlist child. parent_plan points
+// back at the hub (same dir) so \`dotmd doctor\` is satisfied and the reverse
+// link/graph work; status starts `planned` (queued behind the hub).
+function runlistChildContent(childTitle, hubSlug, hubTitle, childStatus, today) {
+  return `---
+type: plan
+status: ${childStatus}
+created: ${today}
+updated: ${today}
+parent_plan: ${hubSlug}.md
+related_plans:
+current_state:
+next_step:
+---
+
+# ${childTitle}
+
+> Runlist child of [${hubTitle}](${hubSlug}.md).
+
+## Problem
+
+
+
+## Version History
+
+- **${today}** Created (runlist child of ${hubSlug}).
+`;
+}
+
 export async function runNew(argv, config, opts = {}) {
   const { dryRun } = opts;
 
@@ -289,9 +400,13 @@ export async function runNew(argv, config, opts = {}) {
   let bodyFlag = null;
   let bodyFlagName = null; // tracks which spelling the caller used, for error attribution
   let showFiles = opts.showFiles ?? false;
+  let runlistArg = null;     // --runlist a,b,c  → sprint hub + child stubs
+  let coordination = false;  // --coordination   → coordination hub skeleton
   for (let i = 0; i < argv.length; i++) {
     if (argv[i] === '--status' && argv[i + 1]) { status = argv[++i]; continue; }
     if (argv[i] === '--title' && argv[i + 1]) { title = argv[++i]; continue; }
+    if (argv[i] === '--runlist' && argv[i + 1]) { runlistArg = argv[++i]; continue; }
+    if (argv[i] === '--coordination') { coordination = true; continue; }
     // --body is the canonical flag; --message is a back-compat alias.
     if ((argv[i] === '--body' || argv[i] === '--message') && argv[i + 1]) {
       bodyFlagName = argv[i];
@@ -359,6 +474,24 @@ export async function runNew(argv, config, opts = {}) {
     die(`Invalid status \`${status}\` for type \`${typeName}\`\nValid: ${[...effective].join(', ')}`);
   }
 
+  // Runlist/coordination hubs are a plan shape, not a separate type. Guard the
+  // flags to type plan and reject the contradictory combination (a sprint
+  // `runlist:` array vs a prose-first coordination map are different shapes).
+  const isRunlistHub = runlistArg !== null;
+  const isCoordinationHub = coordination;
+  if ((isRunlistHub || isCoordinationHub) && typeName !== 'plan') {
+    die(`--${isRunlistHub ? 'runlist' : 'coordination'} only applies to plans. Use: dotmd new plan <name> --${isRunlistHub ? 'runlist a,b,c' : 'coordination'}`);
+  }
+  if (isRunlistHub && isCoordinationHub) {
+    die('--runlist and --coordination are mutually exclusive: a sprint runlist hub carries an ordered `runlist:` array; a coordination hub is a prose-first map (`execution_mode: coordination`). Pick one.');
+  }
+  const runlistTokens = isRunlistHub
+    ? runlistArg.split(',').map(s => s.trim()).filter(Boolean)
+    : [];
+  if (isRunlistHub && runlistTokens.length === 0) {
+    die('--runlist needs at least one child, e.g. --runlist extract,rewrite,cleanup');
+  }
+
   // Body input resolution: --body flag > positional bodyArg > auto-piped-stdin > nothing
   let bodyInput = null;
   let bodyInputSource = null;
@@ -498,6 +631,10 @@ export async function runNew(argv, config, opts = {}) {
 
   const today = nowIso();
 
+  // Resolve runlist children from the hub slug (e.g. `extract` → hub-01-extract.md).
+  const runlistChildren = runlistTokens.map((tok, i) => planChildFromToken(slug, tok, i + 1));
+  const childStatus = effective.has('planned') ? 'planned' : status;
+
   // Generate content
   let content;
   const validSurfaces = config.raw?.taxonomy?.surfaces ?? (config.validSurfaces ? [...config.validSurfaces] : null);
@@ -508,7 +645,14 @@ export async function runNew(argv, config, opts = {}) {
   } else {
     let fm = template.frontmatter(status, today, tmplCtx);
     if (bodyFrontmatter) fm = mergeBodyFrontmatter(fm, bodyFrontmatter, typeName);
-    const body = template.body(docTitle, tmplCtx);
+    // Inject the hub-shape frontmatter (runlist array / coordination marker)
+    // on top of the standard plan scaffold, then swap in a purpose-built body.
+    if (isRunlistHub) fm = mergeBodyFrontmatter(fm, { runlist: runlistChildren.map(c => c.file) }, typeName);
+    if (isCoordinationHub) fm = mergeBodyFrontmatter(fm, { execution_mode: 'coordination' }, typeName);
+    let body;
+    if (isRunlistHub) body = runlistHubBody(docTitle, slug, runlistChildren, bodyInput, today);
+    else if (isCoordinationHub) body = coordinationHubBody(docTitle, bodyInput, today);
+    else body = template.body(docTitle, tmplCtx);
     content = `---\n${fm}\n---\n${body}`;
   }
 
@@ -525,9 +669,14 @@ export async function runNew(argv, config, opts = {}) {
     rootHint = `Root: ${chosenLabel} (others: ${others.join(', ')} — pass --root <name> to change)\n`;
   }
 
+  const hubKind = isRunlistHub ? ' (runlist hub)' : isCoordinationHub ? ' (coordination hub)' : '';
+
   if (dryRun) {
     process.stdout.write(`${dim('[dry-run]')} Would create: ${repoPath}\n`);
-    process.stdout.write(`${dim('[dry-run]')} Type: ${typeName}\n`);
+    process.stdout.write(`${dim('[dry-run]')} Type: ${typeName}${hubKind}\n`);
+    for (const c of runlistChildren) {
+      process.stdout.write(`${dim('[dry-run]')} Would create child: ${toRepoPath(path.join(baseDir, c.file), config.repoRoot)}\n`);
+    }
     if (rootHint) process.stdout.write(`${dim('[dry-run]')} ${rootHint}`);
     return;
   }
@@ -536,9 +685,22 @@ export async function runNew(argv, config, opts = {}) {
   mkdirSync(path.dirname(filePath), { recursive: true });
 
   writeFileSync(filePath, content, 'utf8');
-  process.stdout.write(`${green('Created')}: ${repoPath} ${dim(`(${typeName})`)}\n`);
+  process.stdout.write(`${green('Created')}: ${repoPath} ${dim(`(${typeName}${hubKind})`)}\n`);
   if (rootHint) process.stdout.write(dim(rootHint));
 
+  // Scaffold runlist child stubs. An existing child file is never clobbered.
+  const childPaths = [];
+  for (const c of runlistChildren) {
+    const childPath = path.join(baseDir, c.file);
+    if (existsSync(childPath)) {
+      warn(`Runlist child already exists, left as-is: ${toRepoPath(childPath, config.repoRoot)}`);
+      continue;
+    }
+    writeFileSync(childPath, runlistChildContent(c.title, slug, docTitle, childStatus, today), 'utf8');
+    childPaths.push(childPath);
+    process.stdout.write(`${green('Created')}: ${toRepoPath(childPath, config.repoRoot)} ${dim(`(plan · runlist child, ${childStatus})`)}\n`);
+  }
+
   // Post-create guidance. Prompts are the classic confusion point: agents
   // reflexively `git add && commit` a freshly-created file, but saved prompts
   // are session-local handoff artifacts — the next session consumes them via
@@ -564,7 +726,7 @@ export async function runNew(argv, config, opts = {}) {
   regenIndex(config);
 
   if (showFiles) {
-    const touched = [filePath];
+    const touched = [filePath, ...childPaths];
     if (config.indexPath) touched.push(config.indexPath);
     emitFilesFooter(touched, config);
   }

package/src/query.mjs

@@ -77,6 +77,11 @@ export function runFocus(index, argv, config) {
 
 export function runQuery(index, argv, config, opts = {}) {
   const filters = parseQueryArgs(argv);
+  // Global --type/--root are stripped by the dispatcher and applied to the
+  // index before it reaches here; reflect them in the filter echo so JSON
+  // metadata isn't reported as unfiltered when the result set is narrowed.
+  if (opts.type && !filters.types) filters.types = opts.type.split(',').map(v => v.trim()).filter(Boolean);
+  if (opts.root && !filters.root) filters.root = opts.root;
   if (filters.body && !filters.keyword) {
     die('`--body` extends a keyword search into document bodies — pass `--keyword <term>` (or use `dotmd grep <term>`).');
   }

package/src/ship.mjs

@@ -12,6 +12,12 @@ const ALLOWLIST_PATTERNS = [
   /^test\//,
   /^bin\//,
   /^docs\//,
+  // Plugin artifacts ship in lockstep with the CLI (the plugin-based workflow
+  // is canonical), so a dirty SKILL.md / command / hook / manifest is a release
+  // change. `.claude/commands/` stays for repos that still hand-author slash
+  // commands — harmless, and dropping it would un-stage their edits.
+  /^plugins\//,
+  /^\.claude-plugin\//,
   /^\.claude\/commands\//,
   /^dotmd\.config\.example\.mjs$/,
   /^dotmd\.config\.mjs$/,