dotmd-cli 0.48.3 → 0.49.0

package/bin/dotmd.mjs

@@ -4,20 +4,70 @@ import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 import { resolveConfig } from '../src/config.mjs';
-import { die, warn, levenshtein } from '../src/util.mjs';
-import { recordCliInvocation } from '../src/journal.mjs';
+import { die, warn, levenshtein, isArchivedPath } from '../src/util.mjs';
+import { recordCliInvocation, recordGlobalError } from '../src/journal.mjs';
 import { findRepeatFailureHint } from '../src/hints.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const pkg = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
 
+const QUERY_FLAGS = new Set([
+  '--type', '--status', '--keyword', '--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 QUERY_VALUE_FLAGS = new Set([
+  '--type', '--status', '--keyword', '--owner', '--surface', '--module',
+  '--domain', '--audience', '--execution-mode', '--updated-since', '--limit',
+  '--sort', '--group', '--summarize-limit', '--model',
+]);
+
+const FLAG_SPECS = {
+  plans: { flags: QUERY_FLAGS, values: QUERY_VALUE_FLAGS, subcommands: new Set(['status']) },
+  query: { flags: QUERY_FLAGS, values: QUERY_VALUE_FLAGS },
+  stale: { flags: QUERY_FLAGS, values: QUERY_VALUE_FLAGS },
+  actionable: { flags: QUERY_FLAGS, values: QUERY_VALUE_FLAGS },
+  list: { flags: new Set(['--json', '--verbose']), values: new Set() },
+  briefing: { flags: new Set(['--json']), values: new Set() },
+  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']), 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', '--takeover', '--full', '--no-index', '--show-files']), values: new Set(), subcommands: new Set(['next']) },
+  release: { flags: new Set(['--json', '--all', '--stale', '--to', '--force', '--no-index', '--show-files']), values: new Set(['--to']) },
+  unpickup: { flags: new Set(['--json', '--all', '--stale', '--to', '--force', '--no-index', '--show-files']), values: new Set(['--to']) },
+  finish: { flags: new Set(['--json', '--all', '--stale', '--to', '--force', '--no-index', '--show-files']), values: new Set(['--to']) },
+  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', 'shelve', 'unshelve', 'status']),
+  },
+};
+
+function validateKnownFlags(command, argv, config) {
+  const spec = FLAG_SPECS[command] ?? (config?.presets?.[command] ? { flags: QUERY_FLAGS, values: QUERY_VALUE_FLAGS } : null);
+  if (!spec) return;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (spec.subcommands?.has(arg)) continue;
+    if (!arg.startsWith('-')) continue;
+    if (!spec.flags.has(arg)) die(`Unknown flag for \`dotmd ${command}\`: ${arg}`);
+    if (spec.values.has(arg)) i += 1;
+  }
+}
+
 const HELP = {
   _main: `dotmd v${pkg.version} — frontmatter markdown document manager
 
 Common commands:
   plans                 Live plans (excludes archived)
+  prompts               Prompt queue/admin (list, next, archive, new, shelve)
   briefing              Full briefing with plan counts + next steps
+  agent-context         Compact bounded JSON context for agents
   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>]          Open a doc by type: prompt → consume, plan → start, doc → read
@@ -40,7 +90,8 @@ View & Query:
   hud [--json]                      Two-line actionable triage (held / prompts / stuck) — silent when clean
   list [--verbose] [--json]         List docs grouped by status (default command)
   briefing [--json]                 Full briefing with plan status counts + next steps
-  context [--summarize] [--json]    Full briefing (LLM-oriented)
+  context [--summarize] [--json]    Full briefing (LLM-oriented; use --json --compact for bounded JSON)
+  agent-context [--json]            Compact bounded JSON context for agents
   focus [status] [--json]           Detailed view for one status group
   query [filters] [--json]          Filtered search (--status, --keyword, --stale, etc.)
   plans                             Live plans (excludes archived; --include-archived for all)
@@ -65,12 +116,16 @@ Analyze:
 
 Validate & Fix:
   doctor [--apply]                  Auto-fix everything: refs, lint, dates, index (preview by default)
+  self-check                        Project/version skew diagnostic (alias: doctor --project)
   lint [--fix]                      Check and auto-fix frontmatter issues
   fix-refs [--dry-run]              Auto-fix broken reference paths + body links
 
 Lifecycle:
+  pickup <file>                      Acquire an in-session lease and start work
+  release [<file>]                   Release held in-session work (alias: unpickup, finish)
   set <status> [<file>]             Unified transition: start work, change status, close out, archive — all via target status
   runlist <hub> [next]              Show or walk an ordered group of plans (see \`dotmd help runlist\`)
+  unpickup [<file>]                  Release held in-session work
   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
@@ -315,6 +370,11 @@ status. With no file, releases every lease owned by the current session.
 Identical behavior to \`dotmd unpickup\`; both names route to the same
 implementation. See \`dotmd unpickup --help\` for full option list.`,
 
+  finish: `dotmd finish [<file>] [--to <s>] — alias of dotmd release
+
+Compatibility alias for docs and agent loops that use "finish" for releasing
+in-session work. Same behavior as \`dotmd release\` / \`dotmd unpickup\`.`,
+
   ship: `dotmd ship [patch|minor|major] — regen + commit + bump in one step
 
 Bundles the multi-step release dance into a single command:
@@ -479,13 +539,21 @@ Options:
 
   context: `dotmd context — full briefing (LLM-oriented)
 
-Generates a compact status briefing designed for AI/LLM consumption.
+Generates a status briefing designed for AI/LLM consumption. The default
+JSON form is the full index grouped by type/status; use --compact for bounded
+agent-safe JSON.
 
 Options:
   --json                 Output as JSON
+  --compact              With --json, return counts + bounded next-action lists
   --summarize            Add AI summaries for expanded docs
   --model <name>         Model for AI summaries`,
 
+  'agent-context': `dotmd agent-context — compact bounded JSON for agents
+
+Equivalent to \`dotmd context --json --compact\`. Returns counts,
+validation totals, pending prompt next item, and bounded plan action lists.`,
+
   stats: `dotmd stats — doc health dashboard
 
 Shows aggregated metrics: status counts, staleness, errors/warnings,
@@ -615,9 +683,11 @@ Modes:
                          / \`## Next Step\` body section (created above
                          the first H2 if absent, appended otherwise).
                          Plans only; honors --dry-run.
+  --project              Report CLI/project version skew, generated command
+                         drift, and detectable deprecated command mentions.
 
 --apply (or --yes) opts into writes for the default auto-fix pass.
-Sub-modes (--statuses, --migrate-*, --frontmatter-fix) keep their
+Sub-modes (--statuses, --migrate-*, --frontmatter-fix, --project) keep their
 existing contracts: they write by default and honor --dry-run.`,
 
   'fix-refs': `dotmd fix-refs — auto-fix broken reference paths
@@ -1143,6 +1213,8 @@ async function main() {
     process.stderr.write(`Repo root: ${config.repoRoot}\n`);
   }
 
+  validateKnownFlags(command, restArgs, config);
+
   // Preset aliases (user config can override built-in commands below)
   if (config.presets[command]) {
     const { buildIndex } = await import('../src/index.mjs');
@@ -1214,7 +1286,7 @@ async function main() {
   if (command === 'hud') { const { runHud } = await import('../src/hud.mjs'); runHud(restArgs, config); return; }
   if (command === 'journal') { const { runJournal } = await import('../src/journal-read.mjs'); runJournal(restArgs, config); return; }
   if (command === 'pickup') { const { runPickup } = await import('../src/lifecycle.mjs'); await runPickup(restArgs, config, { dryRun }); return; }
-  if (command === 'unpickup' || command === 'release') { const { runUnpickup } = await import('../src/lifecycle.mjs'); await runUnpickup(restArgs, config, { dryRun }); return; }
+  if (command === 'unpickup' || command === 'release' || command === 'finish') { const { runUnpickup } = await import('../src/lifecycle.mjs'); await runUnpickup(restArgs, config, { dryRun }); return; }
   if (command === 'runlist') { const { runRunlist } = await import('../src/runlist.mjs'); await runRunlist(restArgs, config, { dryRun }); return; }
   if (command === 'handoff') { die('`dotmd handoff` was removed in 0.31.0. Use `dotmd prompts new <name>` to create a saved prompt instead. The .dotmd/handoffs/ sidecar mechanism no longer exists; see CHANGELOG.'); }
   if (command === 'status') { const { runStatus } = await import('../src/lifecycle.mjs'); await runStatus(restArgs, config, { dryRun }); return; }
@@ -1230,6 +1302,11 @@ async function main() {
   if (command === 'rename') { const { runRename } = await import('../src/rename.mjs'); await runRename(restArgs, config, { dryRun }); return; }
   if (command === 'migrate') { const { runMigrate } = await import('../src/migrate.mjs'); runMigrate(restArgs, config, { dryRun }); return; }
   if (command === 'fix-refs') { const { runFixRefs } = await import('../src/fix-refs.mjs'); runFixRefs(restArgs, config, { dryRun }); return; }
+  if (command === 'self-check') {
+    const { runDoctor } = await import('../src/doctor.mjs');
+    runDoctor(['--project', ...restArgs], config, { dryRun });
+    return;
+  }
   if (command === 'doctor') {
     // 0.37.0 (F4): the default auto-fix loop previews by default; --apply
     // (alias --yes) writes. Explicit --dry-run still works and wins over
@@ -1237,7 +1314,7 @@ async function main() {
     // auto-fix path — sub-modes (--statuses, --migrate-template,
     // --migrate-prompts) keep their existing "write unless --dry-run"
     // contract because they're explicit one-shots the user opted into.
-    const subMode = args.includes('--statuses') || args.includes('--migrate-template') || args.includes('--migrate-prompts') || args.includes('--frontmatter-fix');
+    const subMode = args.includes('--statuses') || args.includes('--migrate-template') || args.includes('--migrate-prompts') || args.includes('--frontmatter-fix') || args.includes('--project');
     const explicitApply = args.includes('--apply') || args.includes('--yes');
     const explicitDryRun = args.includes('--dry-run') || args.includes('-n');
     const doctorDryRun = subMode ? dryRun : (explicitDryRun || !explicitApply);
@@ -1255,12 +1332,18 @@ async function main() {
   // Opportunistic stale-lease scrub for user-facing "what's actionable now"
   // views. Diagnostic commands (`check`, `coverage`, `stats`, `index`) are
   // intentionally excluded — they should surface drift, not silently fix it.
-  const SCRUB_READ_COMMANDS = new Set(['list', 'briefing', 'context', 'focus', 'query', 'modules', 'module', 'surfaces']);
+  const SCRUB_READ_COMMANDS = new Set(['list', 'briefing', 'context', 'agent-context', 'focus', 'query', 'modules', 'module', 'surfaces']);
   if (SCRUB_READ_COMMANDS.has(command)) {
     const { scrubStaleSilently } = await import('../src/lease-scrub.mjs');
     scrubStaleSilently(config);
   }
-  const index = buildIndex(config);
+  // `dotmd check` is the one shared-buildIndex command that should auto-heal a
+  // drifted index block (frontmatter edits by direct Edit/Write, `lint --fix`,
+  // etc. leave the README out of sync; demanding the user run `dotmd index`
+  // each time was pure noise). Print/dry-run/read-only callers (`json`, `list`,
+  // `query`, `index --print`, ...) stay opt-out so they never mutate disk.
+  const AUTO_HEAL_INDEX_COMMANDS = new Set(['check']);
+  const index = buildIndex(config, { autoHealIndex: AUTO_HEAL_INDEX_COMMANDS.has(command) });
 
   // Apply --root and --type filters
   const rootFilter = rootArg;
@@ -1430,6 +1513,55 @@ async function main() {
     runSurfaces(restArgs, config);
     return;
   }
+
+  function compactDoc(d) {
+    return {
+      path: d.path,
+      title: d.title,
+      status: d.status,
+      type: d.type,
+      nextStep: d.nextStep ?? null,
+      blockers: d.blockers ?? [],
+      daysSinceUpdate: d.daysSinceUpdate ?? null,
+    };
+  }
+
+  function buildCompactAgentContext(idx) {
+    const activeStatuses = new Set(['in-session', 'active', 'ready', 'planned', 'awaiting', 'blocked']);
+    const active = idx.docs.filter(d => d.type === 'plan' && activeStatuses.has(d.status));
+    const stale = idx.docs.filter(d => d.isStale && !config.lifecycle.skipStaleFor.has(d.status));
+    const awaiting = idx.docs.filter(d => d.status === 'awaiting');
+    const blocked = idx.docs.filter(d => d.status === 'blocked' || d.blockers?.length);
+    const pendingPrompts = idx.docs
+      .filter(d => d.type === 'prompt' && d.status === 'pending' && !isArchivedPath(d.path, config))
+      .sort((a, b) => (a.created ?? '').localeCompare(b.created ?? '') || (a.updated ?? '').localeCompare(b.updated ?? ''));
+    return {
+      generatedAt: new Date().toISOString(),
+      countsByStatus: idx.countsByStatus,
+      countsByType: idx.countsByType,
+      errors: {
+        count: idx.errors.length,
+        items: idx.errors.slice(0, 10).map(e => ({ path: e.path, message: e.message })),
+      },
+      warnings: { count: idx.warnings.length },
+      prompts: {
+        pending: pendingPrompts.length,
+        next: pendingPrompts[0] ? compactDoc(pendingPrompts[0]) : null,
+      },
+      plans: {
+        active: active.slice(0, 12).map(compactDoc),
+        awaiting: awaiting.slice(0, 8).map(compactDoc),
+        blocked: blocked.slice(0, 8).map(compactDoc),
+        stale: stale.slice(0, 12).map(compactDoc),
+      },
+    };
+  }
+
+  if (command === 'agent-context') {
+    process.stdout.write(JSON.stringify(buildCompactAgentContext(index), null, 2) + '\n');
+    return;
+  }
+
   if (command === 'briefing') {
     if (args.includes('--json')) {
       const plans = index.docs.filter(d => d.type === 'plan');
@@ -1450,10 +1582,15 @@ async function main() {
 
   if (command === 'context') {
     const summarize = args.includes('--summarize');
+    const compact = args.includes('--compact');
     const modelIdx = args.indexOf('--model');
     const model = modelIdx !== -1 && args[modelIdx + 1] ? args[modelIdx + 1] : undefined;
 
     if (args.includes('--json')) {
+      if (compact) {
+        process.stdout.write(JSON.stringify(buildCompactAgentContext(index), null, 2) + '\n');
+        return;
+      }
       const byStatus = {};
       for (const doc of index.docs) {
         const s = doc.status ?? 'unknown';
@@ -1552,6 +1689,17 @@ function _journalExit(err) {
       version: pkg.version,
     });
   } catch { /* never break exit on journal failure */ }
+  if (err) {
+    try {
+      recordGlobalError({
+        config: _resolvedConfig,
+        startMs: _startMs,
+        args: _invocationArgs,
+        err,
+        version: pkg.version,
+      });
+    } catch { /* never break exit on error-log failure */ }
+  }
 }
 
 main()

package/package.json

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

package/src/claude-commands.mjs

@@ -76,6 +76,8 @@ function generatePlansCommand(config, version) {
   lines.push('- `dotmd unblocks <file>` — what depends on / is blocked by a plan');
   lines.push('- `dotmd actionable` — ready plans with next steps (what to promote)');
   lines.push('- `dotmd query --keyword <term>` — find plans by keyword');
+  lines.push('- `dotmd runlist <hub>` — show ordered children of a runlist hub (→ marks next pickup)');
+  lines.push('- `dotmd runlist next <hub>` — pick up the next non-archived child of a runlist hub');
 
   if (config.raw?.glossary) {
     lines.push('- `dotmd glossary <term>` — domain term lookup with related plans');
@@ -86,6 +88,7 @@ function generatePlansCommand(config, version) {
   lines.push('');
   lines.push('If the user asks to change a plan\'s status, use `dotmd set <status> <file>`.');
   lines.push('If the user asks to archive a plan, use `dotmd set archived <file>` (or `dotmd archive <file>`).');
+  lines.push('If the user references a runlist by name — e.g. "what\'s next on <X> runlist", "<X> runlist status", "pick up the next in <X>" — use `dotmd runlist next <X>` (or `dotmd runlist <X>` first to inspect the ordering). Do NOT fall back to `dotmd context` for runlist-scoped questions.');
   lines.push('');
   lines.push('**Saved prompts (`docs/prompts/*.md`):** if the user references a file under `docs/prompts/` — e.g. "resume via docs/prompts/foo.md", "use this prompt", "load that one" — consume it with `dotmd use <file>` (atomically prints the body and archives the prompt so it cannot be double-consumed). Do NOT `cat` it, read it with the file-reading tool, or copy its body into chat. To pick the oldest pending prompt without naming a file, run `dotmd use` with no arg.');
   lines.push('');

package/src/commands.mjs

@@ -3,10 +3,10 @@
 // that asserts every `dotmd <verb>` reference in generated slash-command
 // templates points at a real command.
 export const KNOWN_COMMANDS = [
-  'list', 'json', 'check', 'coverage', 'stats', 'graph', 'deps', 'briefing', 'context', 'hud',
-  'focus', 'query', 'plans', 'prompts', 'stale', 'actionable', 'index', 'pickup', 'release', 'status', 'set', 'use', 'next', 'archive', 'bulk', 'bulk-tag', 'touch', 'doctor',
+  'list', 'json', 'check', 'coverage', 'stats', 'graph', 'deps', 'briefing', 'context', 'agent-context', 'hud',
+  'focus', 'query', 'plans', 'prompts', 'stale', 'actionable', 'index', 'pickup', 'release', 'finish', 'status', 'set', 'use', 'next', 'archive', 'bulk', 'bulk-tag', 'touch', 'doctor', 'runlist',
   'unblocks', 'health', 'glossary', 'modules', 'module',
   'fix-refs', 'lint', 'rename', 'migrate', 'notion', 'export', 'summary',
   'watch', 'diff', 'new', 'init', 'completions', 'statuses', 'journal',
-  'ship',
+  'ship', 'self-check',
 ];

package/src/completions.mjs

@@ -2,7 +2,7 @@ import { die } from './util.mjs';
 
 const COMMANDS = [
   'list', 'json', 'check', 'coverage', 'stats', 'graph', 'deps', 'unblocks', 'health', 'glossary', 'briefing', 'context', 'focus', 'query',
-  'plans', 'stale', 'actionable', 'index', 'pickup', 'unpickup', 'status', 'set', 'archive', 'bulk', 'touch', 'doctor', 'lint', 'rename', 'migrate',
+  'plans', 'stale', 'actionable', 'index', 'pickup', 'unpickup', 'release', 'finish', 'status', 'set', 'archive', 'bulk', 'touch', 'doctor', 'lint', 'rename', 'migrate',
   'fix-refs', 'notion', 'export', 'summary', 'watch', 'diff', 'init', 'new', 'completions', 'journal',
 ];
 
@@ -34,8 +34,9 @@ const COMMAND_FLAGS = {
   actionable: ['--json', '--sort', '--limit', '--all'],
   briefing: ['--json'],
   pickup: ['--json', '--takeover'],
-  unpickup: ['--json', '--all', '--stale', '--to', '--force'],
-  finish: ['--json'],
+  unpickup: ['--json', '--all', '--stale', '--to', '--force', '--no-index', '--show-files'],
+  release: ['--json', '--all', '--stale', '--to', '--force', '--no-index', '--show-files'],
+  finish: ['--json', '--all', '--stale', '--to', '--force', '--no-index', '--show-files'],
   status: [],
   archive: [],
   doctor: [],

package/src/doctor.mjs

@@ -1,14 +1,17 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
 import { fixBrokenRefs } from './fix-refs.mjs';
 import { runLint } from './lint.mjs';
 import { runTouch } from './lifecycle.mjs';
-import { buildIndex } from './index.mjs';
+import { buildIndex, collectDocFiles } from './index.mjs';
 import { renderIndexFile, writeIndex } from './index-file.mjs';
-import { renderCheck } from './render.mjs';
+import { renderCheck, renderManualFixes } from './render.mjs';
 import { bold, dim, green, yellow } from './color.mjs';
-import { scaffoldClaudeCommands } from './claude-commands.mjs';
+import { checkClaudeCommands, scaffoldClaudeCommands } from './claude-commands.mjs';
 import { runMigrateTemplate } from './migrate-template.mjs';
 import { runMigratePrompts } from './migrate-prompts.mjs';
 import { runFrontmatterFix } from './frontmatter-fix.mjs';
+import { toRepoPath } from './util.mjs';
 
 // Tunable thresholds for `dotmd doctor --statuses` conflation detection.
 // MIN_BUCKET_SIZE: only flag buckets with at least this many docs (small buckets aren't worth nagging).
@@ -40,6 +43,10 @@ const CUE_LABELS = {
 };
 
 export function runDoctor(argv, config, opts = {}) {
+  if (argv.includes('--project')) {
+    runDoctorProject(config, { json: argv.includes('--json') });
+    return;
+  }
   if (argv.includes('--statuses')) {
     runDoctorStatuses(config, { json: argv.includes('--json') });
     return;
@@ -118,6 +125,67 @@ export function runDoctor(argv, config, opts = {}) {
   process.stdout.write('\n' + bold('6. Remaining issues:') + '\n');
   const freshIndex = buildIndex(config);
   process.stdout.write(renderCheck(freshIndex, config));
+  const manual = renderManualFixes(freshIndex);
+  if (manual.trim()) {
+    process.stdout.write('\n' + bold('Closeout guidance') + '\n');
+    process.stdout.write(manual);
+  }
+}
+
+function readJsonIfPresent(filePath) {
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function findDeprecatedCommandMentions(config) {
+  const docs = collectDocFiles(config);
+  const matches = [];
+  for (const filePath of docs) {
+    let raw = '';
+    try { raw = readFileSync(filePath, 'utf8'); } catch { continue; }
+    if (/\bdotmd status\b/.test(raw) || /\bdotmd pickup\b/.test(raw)) {
+      matches.push(toRepoPath(filePath, config.repoRoot));
+    }
+  }
+  return matches;
+}
+
+function runDoctorProject(config, { json = false } = {}) {
+  const cliPackage = readJsonIfPresent(new URL('../package.json', import.meta.url));
+  const repoPackage = readJsonIfPresent(path.join(config.repoRoot, 'package.json'));
+  const depVersion = repoPackage?.dependencies?.['dotmd-cli']
+    ?? repoPackage?.devDependencies?.['dotmd-cli']
+    ?? repoPackage?.dependencies?.dotmd
+    ?? repoPackage?.devDependencies?.dotmd
+    ?? null;
+  const claudeCommandWarnings = checkClaudeCommands(config.repoRoot);
+  const deprecatedCommandMentions = findDeprecatedCommandMentions(config);
+  const result = {
+    cliVersion: cliPackage?.version ?? null,
+    packageDependency: depVersion,
+    claudeCommandWarnings,
+    deprecatedCommandMentions,
+  };
+
+  if (json) {
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    return result;
+  }
+
+  process.stdout.write(bold('dotmd doctor --project') + '\n\n');
+  process.stdout.write(`- running CLI version: ${result.cliVersion ?? 'unknown'}\n`);
+  process.stdout.write(`- package dependency: ${result.packageDependency ?? '(none found)'}\n`);
+  process.stdout.write(`- stale Claude commands: ${claudeCommandWarnings.length}\n`);
+  if (deprecatedCommandMentions.length) {
+    process.stdout.write(`- docs mentioning deprecated commands: ${deprecatedCommandMentions.length}\n`);
+    for (const file of deprecatedCommandMentions.slice(0, 10)) process.stdout.write(`  - ${file}\n`);
+  } else {
+    process.stdout.write('- docs mentioning deprecated commands: 0\n');
+  }
+  return result;
 }
 
 export function analyzeStatusBuckets(docs) {

package/src/glossary-check.mjs

@@ -0,0 +1,35 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { suggestCandidates } from './util.mjs';
+
+function sectionHeadingRegex(sectionHeading) {
+  return new RegExp(`^##\\s+${sectionHeading.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`, 'm');
+}
+
+export function checkGlossaryConfig(config) {
+  const glossaryConfig = config.raw?.glossary;
+  if (!glossaryConfig?.path) return [];
+
+  const filePath = path.resolve(config.repoRoot, glossaryConfig.path);
+  if (!existsSync(filePath)) {
+    return [{
+      path: glossaryConfig.path,
+      level: 'warning',
+      message: `Glossary file configured at \`${glossaryConfig.path}\` but the file does not exist.`,
+    }];
+  }
+
+  const content = readFileSync(filePath, 'utf8');
+  const section = glossaryConfig.section ?? 'Terminology';
+  if (sectionHeadingRegex(section).test(content)) return [];
+
+  const headings = [...content.matchAll(/^##\s+(.+?)\s*$/gm)].map(m => m[1].trim());
+  const suggestions = suggestCandidates(section, headings, 3);
+  const nearby = suggestions.length ? suggestions : headings.slice(0, 3);
+  const hint = nearby.length ? ` Nearby headings: ${nearby.map(s => `\`${s}\``).join(', ')}.` : '';
+  return [{
+    path: glossaryConfig.path,
+    level: 'warning',
+    message: `Glossary config points at section \`## ${section}\`, but that heading is missing in \`${glossaryConfig.path}\`.${hint} Update \`glossary.path\` / \`glossary.section\` or restore the heading.`,
+  }];
+}

package/src/glossary.mjs

@@ -4,8 +4,12 @@ import { buildIndex } from './index.mjs';
 import { die, warn, suggestCandidates } from './util.mjs';
 import { bold, dim, green, yellow } from './color.mjs';
 
+function sectionHeadingRegex(sectionHeading) {
+  return new RegExp(`^##\\s+${sectionHeading.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`, 'm');
+}
+
 function parseGlossaryTable(content, sectionHeading) {
-  const headingRegex = new RegExp(`^##\\s+${sectionHeading.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`, 'm');
+  const headingRegex = sectionHeadingRegex(sectionHeading);
   const match = content.match(headingRegex);
   if (!match) return { found: false, entries: [] };
 

package/src/hud.mjs

@@ -205,7 +205,11 @@ export function buildHud(config) {
   // still run, so the error count matches `dotmd check`'s.
   let errors = 0;
   try {
-    const index = buildIndex(config, { errorsOnly: true });
+    // `autoHealIndex: true` mirrors `dotmd check` — drift from non-regen
+    // mutation paths (`lint --fix`, direct file edits, etc.) heals silently
+    // at SessionStart so the agent doesn't open every session with a
+    // spurious "Run `dotmd index`" error in the hud error count.
+    const index = buildIndex(config, { errorsOnly: true, autoHealIndex: true });
     errors = index.errors.length;
   } catch { /* swallow — bad config shouldn't break the SessionStart hook */ }
 
@@ -242,6 +246,13 @@ export function runHud(argv, config) {
   // one line, the minimum verb set.
   lines.push(dim('dotmd: plans|briefing  set <status> [<file>]  new <type> <slug>  use [<file>]  archive <file>  (use [no-arg] → oldest pending prompt)'));
 
+  const state = [];
+  if (hud.owned?.length) state.push(`held: ${hud.owned.length} (${previewList(hud.owned)})`);
+  if (hud.prompts?.length) state.push(`prompts: ${hud.prompts.length} (${previewList(hud.prompts)})`);
+  if (hud.stale?.length) state.push(`stuck: ${hud.stale.length} (${previewList(hud.stale)})`);
+  if (hud.errors > 0) state.push(`errors: ${hud.errors} (run dotmd check)`);
+  if (state.length) lines.push(yellow(state.join(' · ')));
+
   if (refreshed.length > 0) {
     const from = refreshed[0].from;
     const to = refreshed[0].to;

package/src/index-file.mjs

@@ -80,7 +80,19 @@ export function writeIndex(content, config) {
   writeFileSync(config.indexPath, content, 'utf8');
 }
 
-export function checkIndex(docs, config) {
+// `autoHeal: true` rewrites the index in place when drift is detected and
+// downgrades the result to a warning ("Auto-regenerated stale index block").
+// Drift happens when frontmatter changes (status/title/current_state/module)
+// arrive via paths that don't call `regenIndex` — direct file edits, `lint
+// --fix`, `frontmatter-fix`, `bulk-tag`, etc. The README block is fully
+// generated content; treating drift as an error forced the user to run
+// `dotmd index` themselves every session. Callers inside `buildIndex` pass
+// `autoHeal: true` because the docs there are always the canonical full set
+// (filtering happens later in the CLI dispatcher). Direct callers with a
+// filtered/synthetic docs list omit it to keep the old error semantics —
+// auto-overwriting from a partial doc list would clobber valid content.
+export function checkIndex(docs, config, opts = {}) {
+  const { autoHeal = false } = opts;
   const warnings = [];
   const errors = [];
 
@@ -98,7 +110,16 @@ export function checkIndex(docs, config) {
   const index = { docs };
   const expected = renderIndexFile(index, config);
   if (expected !== current) {
-    errors.push({ path: config.indexPath, level: 'error', message: 'Generated index block is stale. Run `dotmd index`.' });
+    if (autoHeal) {
+      try {
+        writeFileSync(config.indexPath, expected, 'utf8');
+        warnings.push({ path: config.indexPath, level: 'warning', message: 'Auto-regenerated stale index block.' });
+      } catch (err) {
+        errors.push({ path: config.indexPath, level: 'error', message: `Could not auto-regenerate stale index block: ${err.message}` });
+      }
+    } else {
+      errors.push({ path: config.indexPath, level: 'error', message: 'Generated index block is stale. Run `dotmd index`.' });
+    }
   }
 
   return { warnings, errors };

package/src/index.mjs

@@ -6,6 +6,7 @@ import { asString, normalizeStringList, normalizeBlockers, mergeUniqueStrings, t
 import { validateDoc, validatePlanShape, validateDocShape, checkBidirectionalReferences, checkGitStaleness, checkRunlistBackPointers, computeDaysSinceUpdate, computeIsStale, computeChecklistCompletionRate, enrichRefErrorSuggestions } from './validate.mjs';
 import { checkIndex } from './index-file.mjs';
 import { checkClaudeCommands } from './claude-commands.mjs';
+import { checkGlossaryConfig } from './glossary-check.mjs';
 
 // `fast: true` skips every pass that produces warnings/errors — the rendered
 // index file consumes only status/title/snapshot/etc., not the validation
@@ -21,7 +22,7 @@ import { checkClaudeCommands } from './claude-commands.mjs';
 // error COUNT, so the warning-only passes are pure overhead there. Preserves
 // the invariant that hud's "✗ N validation errors" line matches `dotmd check`.
 export function buildIndex(config, opts = {}) {
-  const { fast = false, errorsOnly = false } = opts;
+  const { fast = false, errorsOnly = false, autoHealIndex = false } = opts;
   const skipWarningOnlyChecks = fast || errorsOnly;
   const docs = collectDocFiles(config).map(f => parseDocFile(f, config, { fast }));
   if (!fast) {
@@ -95,7 +96,15 @@ export function buildIndex(config, opts = {}) {
   }
 
   if (!fast && config.indexPath) {
-    const indexCheck = checkIndex(transformedDocs, config);
+    // `autoHealIndex` is opt-in from the caller (currently `dotmd check` and
+    // `dotmd hud`). When true, drift triggers an in-place rewrite and a
+    // warning instead of the old "Run `dotmd index`" error — closing the
+    // class of nags produced by mutation paths that skip `regenIndex`
+    // (`lint --fix`, direct file edits, etc). `transformedDocs` here is
+    // always the canonical full set; CLI-level `--root`/`--type` filtering
+    // runs after `buildIndex` returns, so a rewrite is safe. Off by default
+    // so dry-run / print modes never mutate disk as a side effect.
+    const indexCheck = checkIndex(transformedDocs, config, { autoHeal: autoHealIndex });
     warnings.push(...indexCheck.warnings);
     errors.push(...indexCheck.errors);
   }
@@ -116,6 +125,9 @@ export function buildIndex(config, opts = {}) {
 
     const claudeWarnings = checkClaudeCommands(config.repoRoot);
     warnings.push(...claudeWarnings);
+
+    const glossaryWarnings = checkGlossaryConfig(config);
+    warnings.push(...glossaryWarnings);
   }
 
   return {

package/src/journal.mjs

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync, appendFileSync, statSync, renameSync, readFileSync } from 'node:fs';
 import path from 'node:path';
+import os from 'node:os';
 import { currentSessionId } from './lease.mjs';
 
 const JOURNAL_DIR = '.dotmd';
@@ -8,6 +9,9 @@ const JOURNAL_BACKUP = 'journal.jsonl.1';
 const ROTATE_SIZE_BYTES = 5 * 1024 * 1024;
 const ROTATE_AGE_MS = 30 * 24 * 60 * 60 * 1000;
 
+const ERROR_LOG_FILE = 'dotmd-errors.log';
+const ERROR_LOG_BACKUP = 'dotmd-errors.log.1';
+
 export function isJournalEnabled(config) {
   if (process.env.DOTMD_JOURNAL === '1') return true;
   if (process.env.DOTMD_JOURNAL === '0') return false;
@@ -22,12 +26,12 @@ export function journalBackupPath(config) {
   return path.join(config.repoRoot, JOURNAL_DIR, JOURNAL_BACKUP);
 }
 
-function maybeRotate(file, config) {
+function maybeRotate(file, backup) {
   if (!existsSync(file)) return;
   let st;
   try { st = statSync(file); } catch { return; }
   if (st.size > ROTATE_SIZE_BYTES) {
-    try { renameSync(file, journalBackupPath(config)); } catch {}
+    try { renameSync(file, backup); } catch {}
     return;
   }
   if (st.size === 0) return;
@@ -41,7 +45,7 @@ function maybeRotate(file, config) {
     const obj = JSON.parse(first);
     const t = new Date(obj.ts).getTime();
     if (!Number.isNaN(t) && (Date.now() - t) > ROTATE_AGE_MS) {
-      try { renameSync(file, journalBackupPath(config)); } catch {}
+      try { renameSync(file, backup); } catch {}
     }
   } catch {}
 }
@@ -53,7 +57,7 @@ export function appendJournalEntry(config, entry) {
     const dir = path.join(config.repoRoot, JOURNAL_DIR);
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
     const file = journalFilePath(config);
-    maybeRotate(file, config);
+    maybeRotate(file, journalBackupPath(config));
     // O_APPEND is atomic for writes under PIPE_BUF (4KB on Linux, 512B on
     // macOS). Entries are well under either threshold, so concurrent CLI
     // invocations interleave cleanly without locking.
@@ -96,3 +100,52 @@ export function recordCliInvocation({ config, startMs, args, err, version }) {
   }
   appendJournalEntry(config, entry);
 }
+
+// Global error log: always-on, cross-repo, captured per failed invocation.
+// Independent of `isJournalEnabled` so silent failures stop disappearing.
+// DOTMD_ERROR_LOG_DIR overrides the default location (for tests, or for
+// users who want the log somewhere other than ~/.claude/logs).
+
+export function globalErrorLogDir() {
+  return process.env.DOTMD_ERROR_LOG_DIR || path.join(os.homedir(), '.claude', 'logs');
+}
+
+export function globalErrorLogPath() {
+  return path.join(globalErrorLogDir(), ERROR_LOG_FILE);
+}
+
+export function globalErrorLogBackupPath() {
+  return path.join(globalErrorLogDir(), ERROR_LOG_BACKUP);
+}
+
+export function recordGlobalError({ config, startMs, args, err, version }) {
+  if (!err) return;
+  const flatMsg = String(err.message ?? err).replace(/\s+/g, ' ').trim();
+  const entry = {
+    ts: new Date().toISOString(),
+    repo: config?.repoRoot || process.cwd(),
+    sid: currentSessionId(),
+    pid: process.pid,
+    argv: args,
+    exit: process.exitCode ?? 1,
+    ms: typeof startMs === 'number' ? Date.now() - startMs : null,
+    v: version,
+    err: flatMsg.length > 500 ? flatMsg.slice(0, 497) + '...' : flatMsg,
+  };
+  if (err && err.name) entry.errName = err.name;
+  if (err && err.stack) {
+    // Keep the first few frames; stacks for DotmdError are short anyway and
+    // for unexpected exceptions five frames is usually enough to localize.
+    const stack = String(err.stack).split('\n').slice(0, 6).join('\n');
+    entry.stack = stack.length > 1000 ? stack.slice(0, 997) + '...' : stack;
+  }
+  try {
+    const dir = globalErrorLogDir();
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    const file = globalErrorLogPath();
+    maybeRotate(file, globalErrorLogBackupPath());
+    appendFileSync(file, JSON.stringify(entry) + '\n', { flag: 'a' });
+  } catch {
+    // Logging must never break exit.
+  }
+}

package/src/lease.mjs

@@ -100,18 +100,28 @@ export function isPidAlive(pid, host) {
   }
 }
 
+export function isLeasePidDead(lease) {
+  if (!lease || lease.host !== os.hostname()) return false;
+  if (!Number.isInteger(lease.pid) || lease.pid <= 0) return false;
+  return !isPidAlive(lease.pid, lease.host);
+}
+
 export function isLeaseStale(lease) {
   const t = new Date(lease.pickedUpAt).getTime();
   if (Number.isNaN(t)) return true;
   return Date.now() - t > STALE_LEASE_AGE_MS;
-  // Note: pid liveness is intentionally NOT used here. dotmd's own CLI pid is
-  // dead the moment the process exits, so it's not a useful signal for "is the
-  // session that wrote this lease still active." Use age and explicit takeover.
 }
 
-export function findStaleLeases(config) {
+export function isLeaseReclaimable(lease, opts = {}) {
+  if (isLeaseStale(lease)) return true;
+  const currentSession = opts.currentSession ?? currentSessionId();
+  if (lease?.session === currentSession) return false;
+  return isLeasePidDead(lease);
+}
+
+export function findStaleLeases(config, opts = {}) {
   const leases = readLeases(config);
-  return Object.values(leases).filter(isLeaseStale);
+  return Object.values(leases).filter(l => isLeaseReclaimable(l, opts));
 }
 
 export function acquireLease(config, repoPath, oldStatus, opts = {}) {
@@ -129,8 +139,7 @@ export function acquireLease(config, repoPath, oldStatus, opts = {}) {
     }
 
     if (existing && !opts.takeover) {
-      const ageMs = Date.now() - new Date(existing.pickedUpAt).getTime();
-      const stale = Number.isNaN(ageMs) || ageMs > STALE_LEASE_AGE_MS;
+      const stale = isLeaseReclaimable(existing, { currentSession: session });
       return {
         outcome: stale ? 'conflict-stale' : 'conflict-alive',
         conflict: existing,
@@ -189,12 +198,13 @@ export function releaseAllForSession(config, sessionId, opts = {}) {
   });
 }
 
-export function releaseStale(config) {
+export function releaseStale(config, opts = {}) {
   return withLeaseLock(config, () => {
     const leases = readLeases(config);
     const released = [];
+    const currentSession = opts.currentSession ?? currentSessionId();
     for (const [key, lease] of Object.entries(leases)) {
-      if (isLeaseStale(lease)) {
+      if (isLeaseReclaimable(lease, { currentSession })) {
         released.push(lease);
         delete leases[key];
       }

package/src/lifecycle.mjs

@@ -15,7 +15,7 @@ import {
   readLeases,
   currentSessionId,
   migrateLease,
-  STALE_LEASE_AGE_MS,
+  isLeaseReclaimable,
   STALE_LEASE_AGE_HOURS,
 } from './lease.mjs';
 import { buildCard, renderCard } from './pickup-card.mjs';
@@ -292,7 +292,7 @@ export async function runPickup(argv, config, opts = {}) {
   // Without this, a stale lease from a crashed prior session would still
   // produce 'conflict-stale' and force the agent to pass --takeover even
   // though we already know the holder is gone.
-  if (!dryRun) {
+  if (!dryRun && !takeover) {
     try {
       const { scrubStaleSilently } = await import('./lease-scrub.mjs');
       scrubStaleSilently(config);
@@ -511,10 +511,7 @@ export async function runUnpickup(argv, config, opts = {}) {
   if (targets === null) {
     // --stale path
     if (dryRun) {
-      const staleLeases = Object.values(leases).filter(l => {
-        const age = Date.now() - new Date(l.pickedUpAt).getTime();
-        return Number.isNaN(age) || age > STALE_LEASE_AGE_MS;
-      });
+      const staleLeases = Object.values(leases).filter(l => isLeaseReclaimable(l, { currentSession: session }));
       for (const l of staleLeases) {
         process.stderr.write(`${dim('[dry-run]')} Would release stale: ${l.path} (${l.session})\n`);
       }

package/src/prompts.mjs

@@ -38,12 +38,19 @@ function runPromptsList(argv, config, opts = {}) {
   const hasStatusFlag = argv.includes('--status');
   const includeArchived = argv.includes('--include-archived');
   const sub = argv[0];
+  const json = argv.includes('--json');
 
-  if (opts.verbose && !argv.includes('--json')) {
+  if (opts.verbose && !json) {
     renderPromptsVerbose(index, config, { hasStatusFlag, includeArchived });
     return;
   }
 
+  const hasPositionalFilter = argv.some(a => !a.startsWith('-') && a !== 'list');
+  if (!json && !hasStatusFlag && !includeArchived && !hasPositionalFilter && sub !== 'status' && !argv.some(a => a.startsWith('--sort') || a.startsWith('--limit') || a === '--all')) {
+    renderPromptQueueList(index, config);
+    return;
+  }
+
   let defaults;
   let extras = argv;
   if (sub === 'status') {
@@ -57,6 +64,34 @@ function runPromptsList(argv, config, opts = {}) {
   runQuery(index, [...defaults, ...extras], config, { preset: 'prompts' });
 }
 
+function renderPromptQueueList(index, config) {
+  const queue = pendingPromptsOldestFirst(config);
+  const queuedPaths = new Set(queue.map(q => q.doc.path));
+  const others = index.docs
+    .filter(d => d.type === 'prompt' && !queuedPaths.has(d.path) && !isArchivedPath(d.path, config) && d.status !== 'archived')
+    .sort((a, b) => (b.updated ?? '').localeCompare(a.updated ?? '') || (a.title ?? a.path).localeCompare(b.title ?? b.path));
+  const prompts = [...queue.map(q => q.doc), ...others];
+
+  if (prompts.length === 0) {
+    process.stdout.write('No prompts.\n');
+    return;
+  }
+
+  const counts = {};
+  for (const p of prompts) counts[p.status ?? 'unknown'] = (counts[p.status ?? 'unknown'] ?? 0) + 1;
+  const summary = Object.entries(counts).map(([s, n]) => `${n} ${s}`).join(' · ');
+  process.stdout.write(dim(`${prompts.length} prompts · ${summary}`) + '\n\n');
+
+  const maxSlug = Math.min(36, Math.max(...prompts.map(p => path.basename(p.path, '.md').length)));
+  for (let i = 0; i < prompts.length; i++) {
+    const p = prompts[i];
+    const slug = path.basename(p.path, '.md').padEnd(maxSlug);
+    const marker = i === 0 && p.status === 'pending' ? green('[NEXT]') : '      ';
+    const status = `[${(p.status ?? 'unknown').toUpperCase()}]`;
+    process.stdout.write(`  ${marker} ${slug} ${status}\n`);
+  }
+}
+
 // Resolve a prompt's "target plan" for `prompts list --verbose`. Order:
 //   1. frontmatter `related_plans:` (first entry — assumed plan slug)
 //   2. frontmatter `parent_plan:`
@@ -226,10 +261,17 @@ export function consumePrompt(filePath, config, opts) {
     return;
   }
 
+  // Archive BEFORE emitting the body. If runArchive throws (git mv failure,
+  // hook crash, anything), the body must not have already gone to stdout —
+  // otherwise `claude "$(dotmd prompts next)"` consumes the prompt without it
+  // ever being archived, and the next session sees the same prompt as pending.
+  // Body is already in memory from extractFrontmatter, so the source file
+  // can move out from under us safely.
+  runArchive([filePath], config, { noIndex, showFiles, out: process.stderr });
+
   process.stdout.write(body);
   if (!body.endsWith('\n')) process.stdout.write('\n');
 
-  runArchive([filePath], config, { noIndex, showFiles, out: process.stderr });
   process.stderr.write(`${green('✓ Consumed')}: ${repoPath}\n`);
 }
 

package/src/render.mjs

@@ -360,7 +360,7 @@ export function renderBriefing(index, config) {
   try {
     const staleLeases = findStaleLeases(config);
     if (staleLeases.length > 0) {
-      lines.push(yellow(`Stuck in-session: ${staleLeases.length} (>1d or dead pid, run \`dotmd release --stale\`)`));
+      lines.push(yellow(`Stuck in-session: ${staleLeases.length} (>4h or dead same-host pid, run \`dotmd release --stale\`)`));
     }
   } catch {}
 
@@ -376,6 +376,80 @@ export function renderCheck(index, config, opts = {}) {
   return defaultRenderer(index);
 }
 
+export function classifyIssueAction(issue) {
+  const message = issue?.message ?? '';
+  const file = issue?.path ?? '<file>';
+
+  if (/Missing frontmatter `status`/.test(message)) {
+    return { action: `dotmd bulk-tag ${file}`, fixable: false, label: 'missing status' };
+  }
+  if (/Missing frontmatter `updated`/.test(message) || /frontmatter `updated: .*` is behind git history/.test(message)) {
+    return { action: 'dotmd touch --git', fixable: true, label: 'dates' };
+  }
+  if (/`(?:module|surface):` \(singular\) is deprecated/.test(message) || /camelCase|nextStep|currentState|auditLevel/.test(message)) {
+    return { action: 'dotmd lint --fix', fixable: true, label: 'frontmatter migrations' };
+  }
+  if (/Unknown surface/.test(message)) {
+    return { action: 'dotmd surfaces', fixable: false, label: 'taxonomy' };
+  }
+  if (/Glossary config points at section|Glossary file configured/.test(message)) {
+    return { action: 'edit dotmd.config.mjs glossary.path/glossary.section', fixable: false, label: 'glossary config' };
+  }
+  if (/under `.*\/` but `status: .*` is not an archive status/.test(message)) {
+    return { action: message.match(/Run `([^`]+)`/)?.[1] ?? `dotmd set archived ${file}`, fixable: true, label: 'archive drift' };
+  }
+  if (/`status: .*` but file is a direct child/.test(message)) {
+    return { action: `dotmd archive ${file}`, fixable: true, label: 'archive drift' };
+  }
+  if (/`current_state` is \d+ chars|`next_step` is \d+ chars/.test(message)) {
+    return { action: 'dotmd doctor --frontmatter-fix', fixable: true, label: 'long frontmatter' };
+  }
+  if (/`modules` is required/.test(message)) {
+    return { action: `edit ${file} modules: or run dotmd lint --fix if scaffolded empty`, fixable: false, label: 'module metadata' };
+  }
+  if (/entry `.*` does not resolve|body link `.*` does not resolve/.test(message)) {
+    return { action: 'dotmd fix-refs --dry-run', fixable: true, label: 'references' };
+  }
+
+  return { action: `edit ${file}`, fixable: false, label: 'manual review' };
+}
+
+export function renderManualFixes(index) {
+  const issues = [...(index.errors ?? []), ...(index.warnings ?? [])];
+  const groups = new Map();
+  for (const issue of issues) {
+    const item = classifyIssueAction(issue);
+    const key = `${item.fixable ? 'fixable' : 'manual'}:${item.action}`;
+    if (!groups.has(key)) groups.set(key, { ...item, paths: new Set() });
+    groups.get(key).paths.add(issue.path);
+  }
+  if (groups.size === 0) return '';
+
+  const manual = [...groups.values()].filter(g => !g.fixable);
+  const fixable = [...groups.values()].filter(g => g.fixable);
+  const lines = [];
+
+  if (fixable.length > 0) {
+    lines.push('Fixable actions');
+    for (const group of fixable) {
+      const count = group.paths.size;
+      lines.push(`- ${group.action} (${count} ${count === 1 ? 'file' : 'files'}: ${[...group.paths].slice(0, 3).join(', ')}${count > 3 ? ', ...' : ''})`);
+    }
+    lines.push('');
+  }
+
+  if (manual.length > 0) {
+    lines.push('Manual fixes remaining');
+    for (const group of manual) {
+      const count = group.paths.size;
+      lines.push(`- ${group.action} (${count} ${count === 1 ? 'file' : 'files'}: ${[...group.paths].slice(0, 3).join(', ')}${count > 3 ? ', ...' : ''})`);
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
 function _renderCheck(index, opts = {}) {
   const { errorsOnly, noCollapse, verbose } = opts;
   const lines = ['Check', ''];
@@ -390,6 +464,10 @@ function _renderCheck(index, opts = {}) {
       lines.push(`- ${issue.path}: ${issue.message}`);
     }
     lines.push('');
+    const actions = renderManualFixes({ errors: index.errors, warnings: [] }).trimEnd();
+    if (actions) {
+      lines.push(actions);
+    }
   }
 
   // Warnings: terse by default — print count + pointer. The full per-doc list
@@ -415,7 +493,7 @@ function _renderCheck(index, opts = {}) {
       }
       lines.push('');
     } else {
-      lines.push(dim(`Run \`dotmd check --verbose\` for per-doc detail, or \`dotmd doctor\` to auto-fix where possible.`));
+      lines.push(dim(`Run \`dotmd check --verbose\` for per-doc detail. \`dotmd doctor\` auto-fixes supported issues; remaining issues need the suggested manual command.`));
       lines.push('');
     }
   }

package/src/runlist.mjs

@@ -45,12 +45,7 @@ function resolveHubInput(input, config) {
 // Read a hub plan's `runlist:` and resolve each entry to a repo-relative path
 // plus its current status. Missing files are reported with `missing: true`;
 // callers decide how to render them. Pure: no IO beyond file reads.
-function readRunlistChildren(hubAbsPath, config) {
-  const raw = readFileSync(hubAbsPath, 'utf8');
-  const { frontmatter: fmRaw } = extractFrontmatter(raw);
-  const fm = parseSimpleFrontmatter(fmRaw);
-  const refs = normalizeStringList(fm.runlist);
-
+function resolveRunlistRefs(refs, hubAbsPath, config) {
   const hubDir = path.dirname(hubAbsPath);
   const out = [];
   for (const ref of refs) {
@@ -79,6 +74,45 @@ function readRunlistChildren(hubAbsPath, config) {
   return out;
 }
 
+function detectBodyRunlistRefs(body) {
+  if (!body) return [];
+  const sectionRe = /^##\s+(Order of operations|Runlist|Execution order|Implementation order|Plan order)\s*$/gim;
+  const refs = [];
+  let match;
+  while ((match = sectionRe.exec(body)) !== null) {
+    const start = match.index + match[0].length;
+    const rest = body.slice(start);
+    const next = rest.search(/^##\s+/m);
+    const section = next >= 0 ? rest.slice(0, next) : rest;
+
+    const linkRe = /\[[^\]]+\]\(([^)]+\.md(?:#[^)]+)?)\)/g;
+    let link;
+    while ((link = linkRe.exec(section)) !== null) refs.push(link[1]);
+
+    const checklistRe = /^\s*[-*]\s+\[[ xX]\]\s+([^\s)]+\.md(?:#[^\s)]+)?)/gm;
+    let item;
+    while ((item = checklistRe.exec(section)) !== null) refs.push(item[1]);
+  }
+  return [...new Set(refs)];
+}
+
+function readRunlistChildren(hubAbsPath, config) {
+  const raw = readFileSync(hubAbsPath, 'utf8');
+  const { frontmatter: fmRaw, body } = extractFrontmatter(raw);
+  const fm = parseSimpleFrontmatter(fmRaw);
+  const refs = normalizeStringList(fm.runlist);
+
+  if (refs.length > 0) {
+    return { children: resolveRunlistRefs(refs, hubAbsPath, config), source: 'frontmatter' };
+  }
+
+  const bodyRefs = detectBodyRunlistRefs(body);
+  return {
+    children: resolveRunlistRefs(bodyRefs, hubAbsPath, config),
+    source: bodyRefs.length > 0 ? 'body' : 'empty',
+  };
+}
+
 const STATUS_TAG_COLORS = {
   'in-session': (s) => bold(red(s)),
   'active': green,
@@ -100,9 +134,12 @@ function renderRunlist(hubRepoPath, children, opts = {}) {
   const lines = [];
   lines.push(bold(`runlist: ${hubRepoPath}`));
   if (children.length === 0) {
-    lines.push(dim('  (empty — add child plan paths to the hub plan\'s `runlist:` field)'));
+    lines.push(dim('  (empty — add child plan paths to the hub plan\'s `runlist:` field, or add markdown links under `## Order of operations`)'));
     return lines.join('\n') + '\n';
   }
+  if (opts.source === 'body') {
+    lines.push(dim('  (from body links — add these paths to frontmatter `runlist:` to make the order canonical)'));
+  }
 
   const archiveStatuses = opts.archiveStatuses ?? new Set(['archived']);
   let nextPicked = false;
@@ -144,18 +181,20 @@ export async function runRunlist(argv, config, opts = {}) {
   if (!hubAbs) die(`Hub plan not found: ${hubInput}`);
   const hubRepoPath = toRepoPath(hubAbs, config.repoRoot);
 
-  const children = readRunlistChildren(hubAbs, config);
+  const runlist = readRunlistChildren(hubAbs, config);
+  const { children, source } = runlist;
   const archiveStatuses = config.lifecycle?.archiveStatuses ?? new Set(['archived']);
 
   if (sub === 'show') {
     if (json) {
       process.stdout.write(JSON.stringify({
         hub: hubRepoPath,
+        source,
         children,
       }, null, 2) + '\n');
       return;
     }
-    process.stdout.write(renderRunlist(hubRepoPath, children, { archiveStatuses }));
+    process.stdout.write(renderRunlist(hubRepoPath, children, { archiveStatuses, source }));
     return;
   }