dotmd-cli 0.59.0 → 0.60.0

package/bin/dotmd.mjs

@@ -13,7 +13,7 @@ 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',
+  '--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',
@@ -28,6 +28,7 @@ const QUERY_VALUE_FLAGS = new Set([
 const FLAG_SPECS = {
   plans: { flags: QUERY_FLAGS, values: QUERY_VALUE_FLAGS, subcommands: new Set(['status']) },
   query: { flags: QUERY_FLAGS, values: QUERY_VALUE_FLAGS },
+  grep: { 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() },
@@ -131,7 +132,7 @@ Common commands:
   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-or-prompt-slug>] Open a doc by type: prompt → consume, plan → start, doc → read
+  use [<file-or-slug>]  Open a doc by type: prompt → consume, plan → start, doc → read
                         (no file: consume oldest pending prompt)
   archive <file>        Close out a plan (status → archived, move, update refs)
 
@@ -153,10 +154,16 @@ Rules:
   commit-prompt  deny  git add/commit of a (often gitignored) saved prompt
   cat-prompt     warn  cat/less/head of a docs/prompts/*.md (use \`dotmd use\`)
   read-prompt    warn  Read tool on a saved prompt (use \`dotmd use\`)
-  edit-status    warn  hand-edit of a \`status:\` field (use \`dotmd set\`)
+  edit-status    deny  CHANGING a \`status:\` line — via Edit/Write or in-place
+                       stream editors (sed -i, perl -pi, awk -i inplace).
+                       Use \`dotmd set <status> <file>\`. Edits that merely
+                       carry an unchanged status: line as context don't fire.
 
-Every catch is appended to the cross-repo misuse log. Disable with DOTMD_GUARD=0.
-Read the log with \`dotmd misuse\`.`,
+\`guard: { deny: false }\` in dotmd.config.mjs drops edit-status back to
+warn-only. Every catch is appended to the cross-repo misuse log. Disable the
+guard entirely with DOTMD_GUARD=0. Read the log with \`dotmd misuse\`; when one
+rule trips ≥3× in 7 days in a repo, \`dotmd hud\` opens the next session there
+with a one-line recap naming the habit to break.`,
 
   update: `dotmd update — update the dotmd CLI and the Claude Code plugin together
 
@@ -192,9 +199,10 @@ View & Query:
   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.)
+  query [filters] [--json]          Filtered search (--status, --keyword, --body, --stale, etc.)
+  grep <term>                       Keyword search incl. document bodies (query --keyword --body --all)
   plans                             Live plans (excludes archived; --include-archived for all)
-  use [<file-or-prompt-slug>]       Open a doc by type: prompt → consume, plan → start, doc → read
+  use [<file-or-slug>]              Open a doc by type: prompt → consume, plan → start, doc → read
   prompts [list|archive|new|hold] Prompt admin (list / archive / save / hold). Use \`dotmd use\` to consume.
   stale                             Stale docs (preset)
   actionable                        Docs with next steps (preset)
@@ -401,6 +409,7 @@ Filters:
   --type <t1,t2>         Filter by type (plan, doc, research)
   --status <s1,s2>       Filter by status (comma-separated)
   --keyword <term>       Search title, summary, state, path
+  --body                 Extend --keyword into document bodies (lazy scan, shows matching-line excerpts)
   --module <name>        Filter by module
   --surface <name>       Filter by surface
   --domain <name>        Filter by domain
@@ -420,6 +429,22 @@ Filters:
   --summarize-limit <n>  Max docs to summarize (default: 5)
   --model <name>         Model for AI summaries`,
 
+  grep: `dotmd grep <term> — keyword search across frontmatter AND document bodies
+
+Alias for \`dotmd query --keyword <term> --body --all\`. Answers "which doc
+discussed X?" with full doc cards (type, status, updated, path) plus 1-2
+matching-line excerpts per body hit — instead of raw-grep's bare paths.
+
+Bodies are read lazily: frontmatter filters run first, only surviving
+candidates are opened. Archived docs are included but clearly labeled.
+
+Composes with the usual query flags:
+  dotmd grep skipStale                     everything mentioning skipStale
+  dotmd grep retries --type plan           only plans
+  dotmd grep retries --status active       only active docs
+  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
 
 Bundles the release steps into a single command:
@@ -444,21 +469,28 @@ Network failures mid-bump (e.g. \`git push\` fails) leave the local
 commit + tag intact. Inspect with \`git log -1\` and rerun
 \`git push origin main --tags\` to recover.`,
 
-  set: `dotmd set <status> <file> — change a document's status
+  set: `dotmd set <status> <file-or-slug> — change a document's status
 
 Writes the new status into the file's frontmatter. Nothing else — no plan
 checkout, no session locks.
   - target is an archive status → archive the file (move + ref update)
   - everything else             → plain frontmatter status bump
 
+<file-or-slug> resolves like \`dotmd use\`/\`archive\`: exact path first, then
+a unique bare slug / basename across the doc roots (\`set paused auth-revamp\`).
+Ambiguous slugs error with the candidate list instead of guessing.
+
 Options:
+  --note "<text>"        Append the reason to \`## Version History\` in the
+                         same call (creates the section if missing). Saves
+                         the status-change + worklog-edit round-trip.
   --no-index             Skip index regen (see \`dotmd archive --help\`).
   --show-files           Append \`files: …\` footer.
   --dry-run, -n          Preview without writing.
 
 Examples:
   dotmd set in-session docs/plans/x  # mark a plan in-session
-  dotmd set partial docs/plans/x     # mark partial
+  dotmd set partial docs/plans/x --note "tail tracked in y.md"
   dotmd set archived docs/plans/x    # archive a specific plan
 
 To open a plan (mark in-session AND print its body), use \`dotmd use <file>\`.`,
@@ -518,6 +550,8 @@ basename match under the doc roots. An ambiguous basename (the same name in
 two places) errors with the candidate list instead of guessing.
 
 Options:
+  --note "<text>"        Append \`Archived — <text>\` to \`## Version History\`
+                         in the same call (creates the section if missing).
   --no-index             Skip index regen. Use when multiple sessions are
                          working concurrently and you want a path-limited
                          commit that doesn't pull other agents' uncommitted
@@ -1540,6 +1574,23 @@ async function main() {
 
   if (command === 'focus') { runFocus(index, restArgs, config); return; }
   if (command === 'query') { runQuery(index, restArgs, config); 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') {
+    let term = null;
+    const passthrough = [];
+    for (let i = 0; i < restArgs.length; i++) {
+      const arg = restArgs[i];
+      if (QUERY_VALUE_FLAGS.has(arg)) { passthrough.push(arg, restArgs[i + 1]); i += 1; continue; }
+      if (arg.startsWith('-') || term !== null) { passthrough.push(arg); continue; }
+      term = arg;
+    }
+    if (!term) die('Usage: dotmd grep <term> [query flags]\n\nSearches frontmatter fields AND document bodies; alias for `dotmd query --keyword <term> --body --all`.');
+    const defaults = ['--keyword', term, '--body'];
+    if (!passthrough.includes('--limit') && !passthrough.includes('--all')) defaults.push('--all');
+    runQuery(index, [...defaults, ...passthrough], config);
+    return;
+  }
   if (command === 'modules' || command === 'module') {
     // D3: default `--type plan` when the user didn't pass --type explicitly.
     // applyIndexFilters already narrowed by typeArg if it was set; if not, the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.59.0",
+  "version": "0.60.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/commands.mjs

@@ -4,7 +4,7 @@
 // templates points at a real command.
 export const KNOWN_COMMANDS = [
   'list', 'json', 'check', 'coverage', 'stats', 'graph', 'deps', 'briefing', 'context', 'agent-context', 'hud',
-  'focus', 'query', 'plans', 'prompts', 'stale', 'actionable', 'index', 'status', 'set', 'use', 'next', 'archive', 'bulk', 'bulk-tag', 'touch', 'doctor', 'runlist',
+  'focus', 'query', 'grep', 'plans', 'prompts', 'stale', 'actionable', 'index', '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',

package/src/completions.mjs

@@ -1,7 +1,7 @@
 import { die } from './util.mjs';
 
 const COMMANDS = [
-  'list', 'json', 'check', 'coverage', 'stats', 'graph', 'deps', 'unblocks', 'health', 'glossary', 'briefing', 'context', 'focus', 'query',
+  'list', 'json', 'check', 'coverage', 'stats', 'graph', 'deps', 'unblocks', 'health', 'glossary', 'briefing', 'context', 'focus', 'query', 'grep',
   'plans', 'stale', 'actionable', 'index', 'status', 'set', 'archive', 'bulk', 'touch', 'doctor', 'lint', 'rename', 'migrate',
   'fix-refs', 'notion', 'export', 'summary', 'watch', 'diff', 'init', 'new', 'completions', 'journal',
 ];
@@ -9,10 +9,12 @@ const COMMANDS = [
 const GLOBAL_FLAGS = ['--config', '--dry-run', '--verbose', '--root', '--type', '--help', '--version'];
 
 const COMMAND_FLAGS = {
-  query: ['--type', '--status', '--keyword', '--module', '--surface', '--domain', '--owner',
+  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'],
   list: ['--verbose', '--json'],
   coverage: ['--json'],

package/src/config.mjs

@@ -118,6 +118,10 @@ const DEFAULTS = {
   // and users who want usage observability flip this on (or set DOTMD_JOURNAL=1).
   journal: false,
 
+  // PreToolUse guard behavior. `deny: false` drops the status-edit rules from
+  // deny (block the tool call) back to warn-only teaching context.
+  guard: { deny: true },
+
   presets: {
     stale: ['--status', 'active,ready,planned,blocked,scoping', '--stale', '--sort', 'updated', '--all'],
     actionable: ['--status', 'active,ready', '--has-next-step', '--sort', 'updated', '--all'],
@@ -533,6 +537,7 @@ export async function resolveConfig(cwd, explicitConfigPath) {
     referenceFields: config.referenceFields,
     presets: config.presets,
     journal: config.journal === true,
+    guard: { deny: config.guard?.deny !== false },
     hooks,
     configWarnings,
   };

package/src/deps.mjs

@@ -1,7 +1,7 @@
 import path from 'node:path';
 import { buildGraph } from './graph.mjs';
-import { buildIndex } from './index.mjs';
-import { resolveDocPath, toSlug, toRepoPath, die, warn } from './util.mjs';
+import { buildIndex, resolveDocArg } from './index.mjs';
+import { toRepoPath, die } from './util.mjs';
 import { bold, dim, green } from './color.mjs';
 
 export function runDeps(argv, config) {
@@ -38,8 +38,7 @@ export function runDeps(argv, config) {
 
   if (input) {
     // Tree view for a specific doc
-    const filePath = resolveDocPath(input, config);
-    if (!filePath) die(`File not found: ${input}`);
+    const filePath = resolveDocArg(input, config);
     const repoPath = toRepoPath(filePath, config.repoRoot);
     const doc = docByPath.get(repoPath);
     if (!doc) die(`Doc not in index: ${repoPath}`);
@@ -255,8 +254,7 @@ export function runUnblocks(argv, config) {
   const json = argv.includes('--json');
   if (!input) die('Usage: dotmd unblocks <file>');
 
-  const filePath = resolveDocPath(input, config);
-  if (!filePath) die(`File not found: ${input}`);
+  const filePath = resolveDocArg(input, config);
   const repoPath = toRepoPath(filePath, config.repoRoot);
 
   const index = buildIndex(config);

package/src/diff.mjs

@@ -1,10 +1,10 @@
 import { readFileSync } from 'node:fs';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
-import { asString, toRepoPath, resolveDocPath, die, warn } from './util.mjs';
+import { asString, toRepoPath, die, warn } from './util.mjs';
 import { gitDiffSince } from './git.mjs';
-import { buildIndex } from './index.mjs';
+import { buildIndex, resolveDocArg } from './index.mjs';
 import { summarizeDiffText, DEFAULT_MODEL } from './ai.mjs';
-import { bold, dim, green } from './color.mjs';
+import { bold, dim } from './color.mjs';
 
 export function runDiff(argv, config) {
   // Parse flags
@@ -24,10 +24,7 @@ export function runDiff(argv, config) {
 
   if (file) {
     // Single file mode
-    const filePath = resolveDocPath(file, config);
-    if (!filePath) {
-      die(`File not found: ${file}\nSearched: ${toRepoPath(config.repoRoot, config.repoRoot) || '.'}, ${toRepoPath(config.docsRoot, config.repoRoot)}`);
-    }
+    const filePath = resolveDocArg(file, config);
 
     const raw = readFileSync(filePath, 'utf8');
     const { frontmatter } = extractFrontmatter(raw);

package/src/guard.mjs

@@ -16,12 +16,14 @@ const pkg = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'),
 //
 // Two decision levels:
 //   'deny' — block the call and feed the reason back to the model. Reserved for
-//            moves that are guaranteed-wrong (committing a gitignored prompt — it
-//            would fail anyway).
+//            moves that are guaranteed-wrong: committing a gitignored prompt (it
+//            would fail anyway) and hand-editing a `status:` field (`dotmd set`
+//            is a complete substitute; config `guard: { deny: false }` drops the
+//            status rules back to warn).
 //   'warn' — let the call proceed but inject teaching context so the agent learns
 //            the dotmd-native command. Used for soft mistakes (cat/Read of a
-//            prompt, hand-editing a status field) where a human might legitimately
-//            do it; we nudge rather than block.
+//            prompt) where a human might legitimately do it; we nudge rather
+//            than block.
 
 const SHELL_READERS = new Set(['cat', 'less', 'more', 'head', 'tail', 'bat', 'view', 'open']);
 
@@ -56,6 +58,34 @@ function shellTokens(command) {
   return command.split(/\s+/).map(t => t.replace(/^['"]|['"]$/g, '')).filter(Boolean);
 }
 
+// Decision level for the status-edit rules. Hand-editing `status:` has no
+// legitimate variant — `dotmd set` is a complete substitute — so it denies by
+// default. `guard: { deny: false }` in config drops it back to warn-only.
+function editStatusDecision(config) {
+  return config?.guard?.deny === false ? 'warn' : 'deny';
+}
+
+function editStatusResult(target, config, detail) {
+  return {
+    decision: editStatusDecision(config),
+    rule: 'edit-status',
+    detail,
+    reason:
+      `Looks like a hand-edit of the \`status:\` field in ${target}. Use \`dotmd set <status> ${target}\` instead — ` +
+      `it validates the status against this doc's type, runs lifecycle hooks, fixes refs, and keeps the index in sync. Direct edits skip all of that.`,
+  };
+}
+
+// In-place stream editors (`sed -i`, `perl -pi`, `awk -i inplace`) are the
+// shell-side bypass of the Edit-tool status guard. Only the command text
+// before any heredoc marker is scanned — heredoc bodies are document content
+// (often prose *describing* these rules), not commands.
+const STREAM_EDITOR_INPLACE = [
+  /\bsed\b[^|;&<>]*\s-i/,
+  /\bperl\b[^|;&<>]*\s-[a-zA-Z]*i/,
+  /\bg?awk\b[^|;&<>]*\binplace\b/,
+];
+
 function evalBash(command, config, isIgnored) {
   const tokens = shellTokens(command);
   const promptTokens = tokens.filter(isPromptPath);
@@ -94,6 +124,16 @@ function evalBash(command, config, isIgnored) {
     }
   }
 
+  // Rule C — in-place stream-editing `status:` in a managed doc. Same wrong-move
+  // as the Edit-tool rule, reached via the shell.
+  const beforeHeredoc = command.split(/<<-?\s*['"]?\w/)[0];
+  if (/status/.test(beforeHeredoc) && STREAM_EDITOR_INPLACE.some(re => re.test(beforeHeredoc))) {
+    const managed = shellTokens(beforeHeredoc).filter(t => isManagedDoc(t, config));
+    if (managed.length) {
+      return editStatusResult(managed[0], config, command);
+    }
+  }
+
   return null;
 }
 
@@ -108,23 +148,39 @@ function evalRead(filePath) {
   };
 }
 
-const STATUS_LINE = /^\s*status\s*:/m;
+// Every `status:` line in a snippet, normalized for comparison.
+function statusLines(s) {
+  if (typeof s !== 'string') return [];
+  return (s.match(/^[ \t]*status[ \t]*:[^\n]*/gm) ?? []).map(l => l.trim());
+}
 
-function evalEdit(input, config) {
+// Only fire when the edit actually CHANGES a `status:` line. An edit whose
+// old/new strings both carry the same `status:` line is using it as anchor
+// context (e.g. adding a `summary:` field above it) — warning on those taught
+// sessions to ignore the rule (the health-repo repeat offenses were exactly
+// this false positive).
+function evalEdit(input, config, deps = {}) {
   const filePath = input?.file_path;
   if (!isManagedDoc(filePath, config)) return null;
-  // Only fire when the edit actually touches a `status:` frontmatter line.
-  const candidates = [input?.new_string, input?.content, input?.new_str]
-    .filter(s => typeof s === 'string');
-  if (!candidates.some(s => STATUS_LINE.test(s))) return null;
-  return {
-    decision: 'warn',
-    rule: 'edit-status',
-    detail: filePath,
-    reason:
-      `Looks like a hand-edit of the \`status:\` field in ${filePath}. Use \`dotmd set <status> ${filePath}\` instead — ` +
-      `it validates the status against this doc's type, runs lifecycle hooks, fixes refs, and keeps the index in sync. Direct edits skip all of that.`,
-  };
+
+  const pairs = [];
+  const newStr = input?.new_string ?? input?.new_str;
+  if (typeof newStr === 'string') pairs.push([input?.old_string ?? input?.old_str ?? '', newStr]);
+  for (const e of Array.isArray(input?.edits) ? input.edits : []) {
+    if (typeof e?.new_string === 'string') pairs.push([e.old_string ?? '', e.new_string]);
+  }
+  if (typeof input?.content === 'string') {
+    // Write replaces the whole file — diff against what's on disk. An
+    // unreadable/missing target is doc creation, not a status edit.
+    const readFile = deps.readFile ?? ((p) => readFileSync(p, 'utf8'));
+    let existing;
+    try { existing = readFile(filePath); } catch { existing = null; }
+    if (typeof existing === 'string') pairs.push([existing, input.content]);
+  }
+
+  const changed = pairs.some(([oldS, newS]) => statusLines(oldS).join('\n') !== statusLines(newS).join('\n'));
+  if (!changed) return null;
+  return editStatusResult(filePath, config, filePath);
 }
 
 // Pure evaluation — `deps.isIgnored(path) -> bool` is injected so tests don't
@@ -137,7 +193,7 @@ export function evaluateGuard(payload, config, deps = {}) {
 
   if (tool === 'Bash') return evalBash(input.command || '', config, isIgnored);
   if (tool === 'Read') return evalRead(input.file_path || '');
-  if (tool === 'Edit' || tool === 'Write' || tool === 'MultiEdit') return evalEdit(input, config);
+  if (tool === 'Edit' || tool === 'Write' || tool === 'MultiEdit') return evalEdit(input, config, deps);
   return null;
 }
 

package/src/hud.mjs

@@ -6,7 +6,7 @@ import { asString, toRepoPath, currentSessionId } from './util.mjs';
 import { dim, yellow } from './color.mjs';
 import { buildIndex } from './index.mjs';
 import { refreshStaleSlashCommands } from './claude-commands.mjs';
-import { readJournalEntries, journalFilePath } from './journal.mjs';
+import { readJournalEntries, journalFilePath, readMisuseEntries } from './journal.mjs';
 import { compareVersions } from './update.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -191,6 +191,39 @@ export function buildJournalSections(config, now = Date.now()) {
   return { previousSelf, fleet, recentRejections };
 }
 
+// Misuse recap: when sessions in THIS repo keep tripping the same guard rule,
+// say so once at SessionStart — the shipped self-correcting-hints pattern
+// pointed at repeat offenses. One line, only for the top rule, only past the
+// threshold; silent otherwise.
+const MISUSE_RECAP_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+const MISUSE_RECAP_THRESHOLD = 3;
+
+const MISUSE_CORRECTIONS = {
+  'edit-status': 'never hand-edit `status:`; use `dotmd set <status> <file>`',
+  'cat-prompt': 'read saved prompts with `dotmd use <file>`',
+  'read-prompt': 'read saved prompts with `dotmd use <file>`',
+  'commit-prompt': 'saved prompts are session-local; never git add/commit them',
+};
+
+export function buildMisuseRecap(config, now = Date.now()) {
+  let entries;
+  try { entries = readMisuseEntries(); } catch { return null; }
+  if (!entries.length) return null;
+  const cutoff = now - MISUSE_RECAP_WINDOW_MS;
+  const counts = new Map();
+  for (const e of entries) {
+    if (!e?.rule || (e.repo || '') !== config.repoRoot) continue;
+    const t = new Date(e.ts).getTime();
+    if (!Number.isFinite(t) || t < cutoff) continue;
+    counts.set(e.rule, (counts.get(e.rule) ?? 0) + 1);
+  }
+  const top = [...counts.entries()].sort((a, b) => b[1] - a[1])[0];
+  if (!top || top[1] < MISUSE_RECAP_THRESHOLD) return null;
+  const [rule, count] = top;
+  const fix = MISUSE_CORRECTIONS[rule] ?? 'see `dotmd misuse`';
+  return `sessions here tripped ${rule} ${count}× this week — ${fix}`;
+}
+
 export function buildHud(config) {
   const prompts = findActionablePrompts(config);
 
@@ -212,8 +245,9 @@ export function buildHud(config) {
   } catch { /* swallow — bad config shouldn't break the SessionStart hook */ }
 
   const { previousSelf, fleet, recentRejections } = buildJournalSections(config);
+  const misuseRecap = buildMisuseRecap(config);
 
-  return { prompts, errors, previousSelf, fleet, recentRejections };
+  return { prompts, errors, previousSelf, fleet, recentRejections, misuseRecap };
 }
 
 // Subagent primer: a spawned subagent (Explore, Plan, general-purpose) starts
@@ -286,7 +320,10 @@ export function runHud(argv, config) {
   // for state that belongs inside its own command. Each of those signals lives
   // in its proper command (`plans`, `prompts`, `check`) and stays available via
   // `dotmd hud --json` for programmatic callers. The hook's job is purely to
-  // teach the verbs, never to report status.
+  // teach the verbs, never to report status. The misuse recap below is the one
+  // exception because it IS teaching: a repeat-offense rule means the primer
+  // alone isn't landing, so name the specific habit to break.
   process.stdout.write(dim('dotmd: plans|briefing  set <status> [<file>]  new <type> <slug>  use [<file>]  archive <file>  (use [no-arg] → oldest pending prompt)') + '\n');
+  if (hud.misuseRecap) process.stdout.write(yellow(`[dotmd] ${hud.misuseRecap}`) + '\n');
   if (drift) process.stdout.write(yellow(drift) + '\n');
 }

package/src/index.mjs

@@ -2,7 +2,7 @@ import { readdirSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { extractFirstHeading, extractSummary, extractStatusSnapshot, extractNextStep, extractChecklistCounts, extractBodyLinks } from './extractors.mjs';
-import { asString, normalizeStringList, normalizeBlockers, mergeUniqueStrings, toRepoPath, warn } from './util.mjs';
+import { asString, normalizeStringList, normalizeBlockers, mergeUniqueStrings, toRepoPath, warn, die, resolveDocPath, suggestCandidates } from './util.mjs';
 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';
@@ -152,6 +152,54 @@ export function collectDocFiles(config) {
   return files.sort((a, b) => a.localeCompare(b));
 }
 
+// Shared resolver for CLI file arguments — the single path every file-taking
+// verb (`use`, `set`, `archive`, `touch`, `rename`, …) funnels through so
+// bare slugs behave identically everywhere. Tries, in order: exact path
+// (the resolveDocPath fast path), `<input>.md`, then a unique basename match
+// across all doc roots. An ambiguous basename dies listing the candidates
+// rather than guessing — a wrong auto-resolved mutation is worse than a
+// retry. A full miss dies with did-you-mean suggestions drawn from the doc
+// corpus; pass { dieOnMiss: false } to get null instead and keep a custom
+// fallback at the call site.
+export function resolveDocArg(input, config, { dieOnMiss = true } = {}) {
+  if (!input) return null;
+  const direct = resolveDocPath(input, config);
+  if (direct) return direct;
+  if (!input.endsWith('.md')) {
+    const withExt = resolveDocPath(input + '.md', config);
+    if (withExt) return withExt;
+  }
+
+  const slug = input.replace(/\.md$/, '');
+  const files = collectDocFiles(config);
+  const byBasename = files.filter(f => path.basename(f, '.md') === slug);
+  if (byBasename.length === 1) return byBasename[0];
+  if (byBasename.length > 1) {
+    die(`Multiple docs match "${input}" by basename:\n${byBasename.map(f => '  ' + toRepoPath(f, config.repoRoot)).join('\n')}`);
+  }
+
+  if (!dieOnMiss) return null;
+  die(docArgMissMessage(input, config, files));
+}
+
+// `File not found` + the searched roots + up-to-3 did-you-mean candidates
+// matched on basename and printed as repo-relative paths. Exported so verbs
+// with their own resolution (e.g. interactive pickers) can reuse the message.
+export function docArgMissMessage(input, config, files = collectDocFiles(config)) {
+  const roots = config.docsRoots || [config.docsRoot];
+  const searched = [toRepoPath(config.repoRoot, config.repoRoot) || '.', ...roots.map(r => toRepoPath(r, config.repoRoot))].join(', ');
+  const slug = String(input).split('/').pop().replace(/\.md$/, '');
+  const pathsByBase = new Map();
+  for (const f of files) {
+    const base = path.basename(f, '.md');
+    if (!pathsByBase.has(base)) pathsByBase.set(base, toRepoPath(f, config.repoRoot));
+  }
+  const hits = suggestCandidates(slug, [...pathsByBase.keys()]);
+  let msg = `File not found: ${input}\nSearched: ${searched}`;
+  if (hits.length) msg += `\nDid you mean: ${hits.map(b => pathsByBase.get(b)).join(', ')}?`;
+  return msg;
+}
+
 function walkMarkdownFiles(directory, files, excludedDirs, skipPaths, seen = new Set()) {
   let entries;
   try {

package/src/lifecycle.mjs

@@ -2,8 +2,8 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { asString, toRepoPath, die, warn, resolveDocPath, resolveRefPath, escapeRegex, nowIso, suggestCandidates, emitFilesFooter, isArchivedPath } from './util.mjs';
-import { gitMv, getGitLastModified, getGitLastModifiedBatch } from './git.mjs';
-import { buildIndex, collectDocFiles } from './index.mjs';
+import { gitMv, getGitLastModifiedBatch } from './git.mjs';
+import { buildIndex, collectDocFiles, resolveDocArg } from './index.mjs';
 import { renderIndexFile, writeIndex } from './index-file.mjs';
 import { green, dim } from './color.mjs';
 import { isInteractive, promptChoice } from './prompt.mjs';
@@ -15,29 +15,6 @@ function findFileRoot(filePath, config) {
   return roots.find(r => filePath.startsWith(r + '/')) ?? config.docsRoot;
 }
 
-// Resolve an archive target like `dotmd use` resolves a pickup target: an exact
-// path wins (the resolveDocPath fast path), but a bare slug / basename falls
-// back to a recursive basename match under the doc roots. Mirrors
-// resolvePromptInput's basename pass so the closure verb is as forgiving about
-// naming as `use`/`prompts archive`. A basename shared by two files errors with
-// the candidate list rather than guessing which one to move.
-function resolveArchiveTarget(input, config) {
-  const direct = resolveDocPath(input, config);
-  if (direct) return direct;
-  if (!input.endsWith('.md')) {
-    const withExt = resolveDocPath(input + '.md', config);
-    if (withExt) return withExt;
-  }
-
-  const slug = input.replace(/\.md$/, '');
-  const byBasename = collectDocFiles(config).filter(f => path.basename(f, '.md') === slug);
-  if (byBasename.length === 1) return byBasename[0];
-  if (byBasename.length > 1) {
-    die(`Multiple docs match "${input}" by basename:\n${byBasename.map(f => '  ' + toRepoPath(f, config.repoRoot)).join('\n')}`);
-  }
-  return null;
-}
-
 function defaultTypeDir(docType, config) {
   if (docType === 'plan') return 'plans';
   if (docType === 'prompt') return 'prompts';
@@ -151,6 +128,13 @@ export async function runStatus(argv, config, opts = {}) {
   const noIndex = argv.includes('--no-index') || opts.noIndex;
   const showFiles = argv.includes('--show-files') || opts.showFiles;
   argv = argv.filter(a => a !== '--no-index' && a !== '--show-files');
+  let note = opts.note ?? null;
+  const noteIdx = argv.indexOf('--note');
+  if (noteIdx !== -1) {
+    note = note ?? argv[noteIdx + 1] ?? null;
+    if (!note || note.startsWith('--')) die('--note requires a value: --note "what changed and why"');
+    argv = argv.filter((_, i) => i !== noteIdx && i !== noteIdx + 1);
+  }
   const input = argv[0];
   let newStatus = argv[1];
 
@@ -160,8 +144,7 @@ export async function runStatus(argv, config, opts = {}) {
 
   if (!input) { die('Usage: dotmd status <file> <new-status>'); }
 
-  const filePath = resolveDocPath(input, config);
-  if (!filePath) { die(`File not found: ${input}\nSearched: ${toRepoPath(config.repoRoot, config.repoRoot) || '.'}, ${toRepoPath(config.docsRoot, config.repoRoot)}`); }
+  const filePath = resolveDocArg(input, config);
 
   // Determine type-specific or root-specific valid statuses
   const raw = readFileSync(filePath, 'utf8');
@@ -256,12 +239,18 @@ export async function runStatus(argv, config, opts = {}) {
     if ((isArchiving || isUnarchiving || isFiling || isUnfiling) && config.indexPath) {
       process.stdout.write(`${prefix} Would regenerate index\n`);
     }
+    if (note) {
+      process.stdout.write(`${prefix} Would append Version History: - **${today}** Status: ${oldStatus ?? 'unknown'} → ${newStatus} — ${note}\n`);
+    }
     process.stdout.write(`${prefix} ${toRepoPath(finalPath, config.repoRoot)}: ${oldStatus ?? 'unknown'} → ${newStatus}\n`);
     return;
   }
 
   updateFrontmatter(filePath, { status: newStatus, updated: today });
-  appendVersionHistory(filePath, `Status: ${oldStatus ?? 'unknown'} → ${newStatus}.`);
+  const transition = `Status: ${oldStatus ?? 'unknown'} → ${newStatus}`;
+  // A --note must land even when the doc has no Version History section yet;
+  // the plain transition entry stays best-effort (bare docs skip it).
+  appendVersionHistory(filePath, note ? `${transition} — ${note}` : `${transition}.`, { createSection: Boolean(note) });
 
   if (isArchiving) {
     mkdirSync(archiveDir, { recursive: true });
@@ -350,8 +339,7 @@ export async function startPlan(argv, config, opts = {}) {
     input = candidates[idx].path;
   }
 
-  const filePath = resolveDocPath(input, config);
-  if (!filePath) die(`File not found: ${input}`);
+  const filePath = resolveDocArg(input, config);
 
   const raw = readFileSync(filePath, 'utf8');
   const { frontmatter: fmRaw, body } = extractFrontmatter(raw);
@@ -420,12 +408,18 @@ export function runArchive(argv, config, opts = {}) {
   const showFiles = argv.includes('--show-files') || opts.showFiles;
   const closeoutTemplate = argv.includes('--closeout-template');
   argv = argv.filter(a => a !== '--no-index' && a !== '--show-files' && a !== '--closeout-template');
+  let note = opts.note ?? null;
+  const noteIdx = argv.indexOf('--note');
+  if (noteIdx !== -1) {
+    note = note ?? argv[noteIdx + 1] ?? null;
+    if (!note || note.startsWith('--')) die('--note requires a value: --note "what shipped / why closed"');
+    argv = argv.filter((_, i) => i !== noteIdx && i !== noteIdx + 1);
+  }
   const input = argv[0];
 
   if (!input) { die('Usage: dotmd archive <file>'); }
 
-  const filePath = resolveArchiveTarget(input, config);
-  if (!filePath) { die(`File not found: ${input}\nSearched: ${toRepoPath(config.repoRoot, config.repoRoot) || '.'}, ${toRepoPath(config.docsRoot, config.repoRoot)}`); }
+  const filePath = resolveDocArg(input, config);
 
   const archiveFileRoot = findFileRoot(filePath, config);
   const relFromRoot = path.relative(archiveFileRoot, filePath);
@@ -456,7 +450,8 @@ export function runArchive(argv, config, opts = {}) {
       return;
     }
     updateFrontmatter(filePath, { status: 'archived', updated: today });
-    appendVersionHistory(filePath, `Archived (frontmatter healed in place from \`${oldStatus}\`).`);
+    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`);
     const touched = [repoPathHeal];
@@ -488,6 +483,9 @@ export function runArchive(argv, config, opts = {}) {
       out.write(`${prefix} \`## Closeout\` section already present — no injection\n`);
     }
     out.write(`${prefix} Would update frontmatter: status: ${oldStatus} → archived, updated: ${today}\n`);
+    if (note) {
+      out.write(`${prefix} Would append Version History: - **${today}** Archived — ${note}\n`);
+    }
     out.write(`${prefix} Would move: ${oldRepoPath} → ${newRepoPath}\n`);
     if (config.indexPath && !noIndex) out.write(`${prefix} Would regenerate index\n`);
     if (config.indexPath && noIndex) out.write(`${prefix} Would skip index regen (--no-index)\n`);
@@ -510,7 +508,7 @@ export function runArchive(argv, config, opts = {}) {
   }
 
   updateFrontmatter(filePath, { status: 'archived', updated: today });
-  appendVersionHistory(filePath, 'Archived.');
+  appendVersionHistory(filePath, note ? `Archived — ${note}` : 'Archived.', { createSection: Boolean(note) });
 
   mkdirSync(targetDir, { recursive: true });
 
@@ -571,6 +569,13 @@ export async function runSet(argv, config, opts = {}) {
   const noIndex = argv.includes('--no-index');
   const showFiles = argv.includes('--show-files');
   argv = argv.filter(a => a !== '--no-index' && a !== '--show-files');
+  let note = opts.note ?? null;
+  const noteIdx = argv.indexOf('--note');
+  if (noteIdx !== -1) {
+    note = note ?? argv[noteIdx + 1] ?? null;
+    if (!note || note.startsWith('--')) die('--note requires a value: --note "what changed and why"');
+    argv = argv.filter((_, i) => i !== noteIdx && i !== noteIdx + 1);
+  }
 
   const newStatus = argv[0];
   const input = argv[1];
@@ -578,8 +583,7 @@ export async function runSet(argv, config, opts = {}) {
   if (!newStatus) die('Usage: dotmd set <status> <path>');
   if (!input) die('Usage: dotmd set <status> <path>');
 
-  const filePath = resolveDocPath(input, config);
-  if (!filePath) die(`File not found: ${input}\nSearched: ${toRepoPath(config.repoRoot, config.repoRoot) || '.'}, ${toRepoPath(config.docsRoot, config.repoRoot)}`);
+  const filePath = resolveDocArg(input, config);
 
   const inArchive = isArchivedPath(toRepoPath(filePath, config.repoRoot), config);
 
@@ -587,13 +591,30 @@ 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 });
+    return runArchive(archiveArgs, config, { dryRun, note });
+  }
+
+  // `partial` promises a successor tracking the deferred tail. When neither a
+  // --note nor any doc reference exists to point at it, remind — advisory
+  // only, computed before the transition (filing may move the file).
+  let partialReminder = false;
+  if (newStatus === 'partial' && !note) {
+    try {
+      const { frontmatter: fmRaw, body } = extractFrontmatter(readFileSync(filePath, 'utf8'));
+      const related = parseSimpleFrontmatter(fmRaw).related_plans;
+      const hasRelated = Array.isArray(related) ? related.length > 0 : Boolean(asString(related)?.trim());
+      partialReminder = !hasRelated && !/[\w./-]+\.md\b/.test(body);
+    } catch { /* advisory only */ }
   }
 
   const statusArgs = [filePath, newStatus];
   if (noIndex) statusArgs.push('--no-index');
   if (showFiles) statusArgs.push('--show-files');
-  await runStatus(statusArgs, config, { dryRun, suppressDeprecation: true });
+  await runStatus(statusArgs, config, { dryRun, suppressDeprecation: true, note });
+
+  if (partialReminder && !dryRun) {
+    warn('partial usually references the successor plan tracking the tail — add a link to the body, or rerun with --note "tail tracked in <plan>".');
+  }
 }
 
 export function runBulkArchive(argv, config, opts = {}) {
@@ -670,8 +691,7 @@ export function runTouch(argv, config, opts = {}) {
 
   // --git mode: bulk-sync frontmatter dates from git history
   if (useGit) {
-    const allFiles = input ? [resolveDocPath(input, config)].filter(Boolean) : collectDocFiles(config);
-    if (input && allFiles.length === 0) { die(`File not found: ${input}`); }
+    const allFiles = input ? [resolveDocArg(input, config)] : collectDocFiles(config);
 
     const prefix = dryRun ? dim('[dry-run] ') : '';
     let synced = 0;
@@ -714,8 +734,7 @@ export function runTouch(argv, config, opts = {}) {
 
   if (!input) { die('Usage: dotmd touch <file>\n       dotmd touch --git          Bulk-sync dates from git history'); }
 
-  const filePath = resolveDocPath(input, config);
-  if (!filePath) { die(`File not found: ${input}\nSearched: ${toRepoPath(config.repoRoot, config.repoRoot) || '.'}, ${toRepoPath(config.docsRoot, config.repoRoot)}`); }
+  const filePath = resolveDocArg(input, config);
 
   const today = nowIso();
 
@@ -862,7 +881,7 @@ function countRefsToUpdate(oldPath, newPath, config) {
 // Newest-first ordering: inserted at the top of the section, right after the
 // heading + blank-line gap. If the section is missing, this is a silent no-op
 // — never auto-creates the section (don't surprise users on old plans/docs).
-export function appendVersionHistory(filePath, entry) {
+export function appendVersionHistory(filePath, entry, { createSection = false } = {}) {
   let raw;
   try { raw = readFileSync(filePath, 'utf8'); } catch { return false; }
   if (!raw.startsWith('---\n')) return false;
@@ -872,10 +891,18 @@ export function appendVersionHistory(filePath, entry) {
   const frontmatter = raw.slice(4, endMarker);
   const body = raw.slice(endMarker + 5);
 
-  const vh = findSection(walkSections(body), 'Version History');
-  if (!vh) return false;
-
   const bullet = `- **${nowIso()}** ${entry}`;
+
+  const vh = findSection(walkSections(body), 'Version History');
+  if (!vh) {
+    // Bare docs (no scaffold) have no Version History; transitions silently
+    // skip the worklog. But an explicit `--note` must not be dropped — the
+    // caller opts into creating the section at the end of the body.
+    if (!createSection) return false;
+    const trimmed = body.replace(/\n+$/, '');
+    writeFileSync(filePath, `---\n${frontmatter}\n---\n${trimmed}\n\n## Version History\n\n${bullet}\n`, 'utf8');
+    return true;
+  }
   const lines = body.split('\n');
 
   // vh.lineStart is 1-indexed for the heading line. The line immediately

package/src/query.mjs

@@ -1,6 +1,6 @@
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
-import { capitalize, toSlug, truncate, warn, suggestCandidates, isArchivedPath } from './util.mjs';
+import { capitalize, toSlug, truncate, warn, die, suggestCandidates, isArchivedPath } from './util.mjs';
 import { renderProgressBar, formatCurrentState } from './render.mjs';
 import { computeDaysSinceUpdate, computeIsStale } from './validate.mjs';
 import { getGitLastModifiedBatch } from './git.mjs';
@@ -76,6 +76,9 @@ export function runFocus(index, argv, config) {
 
 export function runQuery(index, argv, config, opts = {}) {
   const filters = parseQueryArgs(argv);
+  if (filters.body && !filters.keyword) {
+    die('`--body` extends a keyword search into document bodies — pass `--keyword <term>` (or use `dotmd grep <term>`).');
+  }
   const docs = filterDocs(index.docs, filters, config);
 
   if (filters.json) {
@@ -119,7 +122,7 @@ function writeUnknownFilterValueHint(filters, index) {
 
 export function parseQueryArgs(argv) {
   const filters = {
-    types: null, statuses: null, keyword: null, owner: null, surface: null,
+    types: null, statuses: null, keyword: null, body: false, owner: null, surface: null,
     module: null, domain: null, audience: null, executionMode: null,
     updatedSince: null, limit: 20, all: false, sort: 'updated',
     group: null,
@@ -136,6 +139,7 @@ export function parseQueryArgs(argv) {
     if (arg === '--type' && next) { filters.types = next.split(',').map(v => v.trim()).filter(Boolean); i += 1; continue; }
     if (arg === '--status' && next) { filters.statuses = next.split(',').map(v => v.trim()).filter(Boolean); i += 1; continue; }
     if (arg === '--keyword' && next) { filters.keyword = next; i += 1; continue; }
+    if (arg === '--body') { filters.body = true; continue; }
     if (arg === '--owner' && next) { filters.owner = next; i += 1; continue; }
     if (arg === '--surface' && next) { filters.surface = next; i += 1; continue; }
     if (arg === '--module' && next) { filters.module = next; i += 1; continue; }
@@ -187,9 +191,12 @@ export function filterDocs(docs, filters, config) {
     result = result.filter(d => !archived.has(d.status) && !isArchivedPath(d.path, config));
   }
 
-  if (filters.keyword) {
-    const needle = filters.keyword.toLowerCase();
-    result = result.filter(d => [d.title, d.summary, d.currentState, d.nextStep, d.path, ...(d.blockers ?? [])].filter(Boolean).join(' ').toLowerCase().includes(needle));
+  const keywordNeedle = filters.keyword ? filters.keyword.toLowerCase() : null;
+  const matchesFrontmatter = d => [d.title, d.summary, d.currentState, d.nextStep, d.path, ...(d.blockers ?? [])].filter(Boolean).join(' ').toLowerCase().includes(keywordNeedle);
+  // With --body the keyword filter is deferred to after the cheap frontmatter
+  // filters (below) so body files are only read for surviving candidates.
+  if (keywordNeedle && !filters.body) {
+    result = result.filter(matchesFrontmatter);
   }
 
   // Positional substring filter: AND match against slug + title.
@@ -224,6 +231,19 @@ export function filterDocs(docs, filters, config) {
   if (filters.hasBlockers) result = result.filter(d => d.hasBlockers);
   if (filters.checklistOpen) result = result.filter(d => (d.checklist?.open ?? 0) > 0);
 
+  // Lazy body scan: docs already matching on frontmatter fields keep their spot
+  // without a file read; only the rest get their bodies scanned. Hits carry
+  // 1-2 matching-line excerpts so the caller can rank without opening files.
+  if (keywordNeedle && filters.body) {
+    result = result.filter(d => {
+      if (matchesFrontmatter(d)) return true;
+      const matches = scanBodyForKeyword(d, keywordNeedle, config);
+      if (!matches.length) return false;
+      d.bodyMatches = matches;
+      return true;
+    });
+  }
+
   result.sort(buildSorter(filters.sort, config));
   // Stash pre-limit count and per-status breakdown on filters so renderers
   // can show "N more" footers and accurate pipeline summaries even when the
@@ -237,6 +257,45 @@ export function filterDocs(docs, filters, config) {
   return filters.all ? result : result.slice(0, filters.limit);
 }
 
+// Read one doc's body and return up to MAX_BODY_MATCHES matching-line
+// excerpts: { line: <1-based file line>, text: <trimmed, windowed around the
+// match> }. Line numbers are file-absolute (frontmatter included) so they can
+// feed straight into a Read offset.
+const MAX_BODY_MATCHES = 2;
+const EXCERPT_WIDTH = 120;
+
+function scanBodyForKeyword(doc, needle, config) {
+  let raw;
+  try {
+    raw = readFileSync(path.resolve(config.repoRoot, doc.path), 'utf8');
+  } catch (err) {
+    warn(`Could not read ${doc.path}: ${err.message}`);
+    return [];
+  }
+  const { body } = extractFrontmatter(raw);
+  if (!body || !body.toLowerCase().includes(needle)) return [];
+
+  // body is a suffix of raw — the slice before it is the frontmatter block.
+  const bodyStartLine = raw.slice(0, raw.length - body.length).split('\n').length;
+  const lines = body.split('\n');
+  const matches = [];
+  for (let i = 0; i < lines.length && matches.length < MAX_BODY_MATCHES; i++) {
+    const text = lines[i].trim();
+    const at = text.toLowerCase().indexOf(needle);
+    if (at === -1) continue;
+    matches.push({ line: bodyStartLine + i, text: excerptAround(text, at, needle.length) });
+  }
+  return matches;
+}
+
+// Window a long line around the match so the needle is always visible.
+function excerptAround(text, at, needleLen) {
+  if (text.length <= EXCERPT_WIDTH) return text;
+  const start = Math.max(0, Math.min(at - Math.floor((EXCERPT_WIDTH - needleLen) / 2), text.length - EXCERPT_WIDTH));
+  const slice = text.slice(start, start + EXCERPT_WIDTH);
+  return `${start > 0 ? '…' : ''}${slice}${start + EXCERPT_WIDTH < text.length ? '…' : ''}`;
+}
+
 function getDocSummary(doc, config) {
   try {
     const absPath = path.resolve(config.repoRoot, doc.path);
@@ -261,7 +320,7 @@ function renderQueryResults(docs, filters, config) {
   }
   if (filters.types?.length) process.stdout.write(`- type: ${filters.types.join(', ')}\n`);
   if (filters.statuses?.length) process.stdout.write(`- status: ${filters.statuses.join(', ')}\n`);
-  if (filters.keyword) process.stdout.write(`- keyword: ${filters.keyword}\n`);
+  if (filters.keyword) process.stdout.write(`- keyword: ${filters.keyword}${filters.body ? ' (bodies scanned)' : ''}\n`);
   if (filters.owner) process.stdout.write(`- owner: ${filters.owner}\n`);
   if (filters.surface) process.stdout.write(`- surface: ${filters.surface}\n`);
   if (filters.module) process.stdout.write(`- module: ${filters.module}\n`);
@@ -299,6 +358,9 @@ function renderQueryResults(docs, filters, config) {
     if (doc.executionMode) process.stdout.write(`  execution-mode: ${doc.executionMode}\n`);
     if (doc.blockers?.length) process.stdout.write(`  blockers: ${doc.blockers.join('; ')}\n`);
     if (doc.checklist?.total) process.stdout.write(`  checklist: ${doc.checklist.completed}/${doc.checklist.total} complete\n`);
+    for (const m of doc.bodyMatches ?? []) {
+      process.stdout.write(`  match: ${dim(`L${m.line}:`)} ${m.text}\n`);
+    }
     if (filters.summarize && idx < filters.summarizeLimit) {
       const summary = getDocSummary(doc, config);
       if (summary) process.stdout.write(`  ${dim('ai-summary:')} ${summary}\n`);

package/src/rename.mjs

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
-import { toRepoPath, resolveDocPath, die, warn } from './util.mjs';
-import { collectDocFiles } from './index.mjs';
+import { toRepoPath, die, warn } from './util.mjs';
+import { collectDocFiles, resolveDocArg } from './index.mjs';
 import { regenIndex } from './lifecycle.mjs';
 import { gitMv } from './git.mjs';
 import { green, dim } from './color.mjs';
@@ -31,10 +31,7 @@ export async function runRename(argv, config, opts = {}) {
   }
 
   // Resolve old path
-  const oldPath = resolveDocPath(oldInput, config);
-  if (!oldPath) {
-    die(`File not found: ${oldInput}\nSearched: ${toRepoPath(config.repoRoot, config.repoRoot) || '.'}, ${toRepoPath(config.docsRoot, config.repoRoot)}`);
-  }
+  const oldPath = resolveDocArg(oldInput, config);
 
   // Compute new path — cross-directory if input has slashes, same directory otherwise
   let newPath;

package/src/render.mjs

@@ -1,6 +1,6 @@
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
-import { capitalize, toSlug, truncate, warn } from './util.mjs';
+import { capitalize, toSlug, truncate, warn, isArchivedPath } from './util.mjs';
 import { extractFrontmatter } from './frontmatter.mjs';
 import { summarizeDocBody } from './ai.mjs';
 import { bold, red, yellow, green, dim } from './color.mjs';
@@ -323,10 +323,20 @@ export function renderBriefing(index, config) {
   const untyped = index.docs.filter(d => !d.type);
 
   if (plans.length) {
+    // Headline counts LIVE plans first — "30 plans: 25 archived, …" skims as
+    // 30 open work items when zero are. "Live" mirrors the `dotmd plans`
+    // filter: not in an archive/terminal status and not filed under archived/.
+    const closed = new Set([
+      ...(config.lifecycle?.archiveStatuses ?? []),
+      ...(config.lifecycle?.terminalStatuses ?? []),
+    ]);
+    const live = plans.filter(p => !closed.has(p.status) && !isArchivedPath(p.path, config));
     const bySt = {};
-    for (const p of plans) { bySt[p.status] = (bySt[p.status] ?? 0) + 1; }
+    for (const p of live) { bySt[p.status] = (bySt[p.status] ?? 0) + 1; }
     const counts = Object.entries(bySt).map(([s, n]) => `${n} ${s}`).join(', ');
-    lines.push(`${plans.length} plans: ${counts}`);
+    const closedCount = plans.length - live.length;
+    const closedPart = closedCount ? ` (${closedCount} archived)` : '';
+    lines.push(live.length ? `${live.length} live plans${closedPart}: ${counts}` : `0 live plans${closedPart}`);
     const show = plans.filter(p => p.status === 'in-session' || p.status === 'active');
     for (const p of show) {
       const next = p.nextStep ? `next: ${p.nextStep}` : '(no next step)';

package/src/runlist.mjs

@@ -1,45 +1,22 @@
-import { existsSync, readFileSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import {
   asString,
   die,
   normalizeStringList,
-  resolveDocPath,
   resolveRefPath,
   toRepoPath,
-  toSlug,
 } from './util.mjs';
+import { resolveDocArg } from './index.mjs';
 import { bold, cyan, dim, green, red, yellow } from './color.mjs';
 
 const PICKUPABLE_STATUSES = new Set(['active', 'planned', 'in-session']);
 
-// resolveDocPath only tries cwd / repo-root / docs-root joins, so bare plan
-// slugs like `clear-the-deck` don't resolve when plans live under
-// `<docsRoot>/plans/`. The other commands (`dotmd set <slug>`, `dotmd plans`)
-// take slugs — runlist should too. Try the direct resolve first, then
-// fall back to `<root>/plans/<slug>.md` under each configured doc root.
+// Bare hub slugs resolve through the shared resolver; the caller keeps its
+// runlist-specific miss message, so no die-on-miss here.
 function resolveHubInput(input, config) {
-  const direct = resolveDocPath(input, config);
-  if (direct) return direct;
-
-  if (!input.endsWith('.md')) {
-    const withExt = resolveDocPath(input + '.md', config);
-    if (withExt) return withExt;
-  }
-
-  const slugFile = input.endsWith('.md') ? input : `${input}.md`;
-  const roots = config.docsRoots || (config.docsRoot ? [config.docsRoot] : []);
-  for (const root of roots) {
-    const candidate = path.join(root, 'plans', slugFile);
-    if (existsSync(candidate)) return candidate;
-    // Multi-root layouts may already have a `plans` root, so also try the
-    // root itself.
-    const rootCandidate = path.join(root, slugFile);
-    if (existsSync(rootCandidate)) return rootCandidate;
-  }
-
-  return null;
+  return resolveDocArg(input, config, { dieOnMiss: false });
 }
 
 // Read a hub plan's `runlist:` and resolve each entry to a repo-relative path

package/src/summary.mjs

@@ -1,7 +1,8 @@
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
-import { asString, toRepoPath, resolveDocPath, die, warn } from './util.mjs';
+import { asString, toRepoPath, die, warn } from './util.mjs';
+import { resolveDocArg } from './index.mjs';
 import { summarizeDocBody } from './ai.mjs';
 import { bold, dim } from './color.mjs';
 
@@ -23,8 +24,7 @@ export function runSummary(argv, config) {
   const input = positional[0];
   if (!input) { die('Usage: dotmd summary <file> [--model <name>] [--json]'); }
 
-  const filePath = resolveDocPath(input, config);
-  if (!filePath) { die(`File not found: ${input}`); }
+  const filePath = resolveDocArg(input, config);
 
   const raw = readFileSync(filePath, 'utf8');
   const { frontmatter, body } = extractFrontmatter(raw);

package/src/use.mjs

@@ -3,6 +3,7 @@ import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { asString, die, resolveDocPath, toRepoPath } from './util.mjs';
 import { consumePrompt, pendingPromptsOldestFirst, resolvePromptInput } from './prompts.mjs';
 import { startPlan } from './lifecycle.mjs';
+import { resolveDocArg } from './index.mjs';
 
 // Top-level `dotmd use [file]` — the single "start engaging with this doc"
 // verb. Dispatches by the target doc's `type:` so agents don't have to know
@@ -22,8 +23,12 @@ export async function runUse(argv, config, opts = {}) {
     return consumePrompt(head.abs, config, opts);
   }
 
-  const filePath = resolveDocPath(positional, config) ?? resolvePromptInput(positional, config, { dieOnMiss: false });
-  if (!filePath) die(`File not found: ${positional}`);
+  // Exact path first, then prompt slugs (they keep precedence on a slug
+  // collision — consuming a prompt is the more common intent), then the
+  // shared resolver for plan/doc slugs, which dies with did-you-mean on miss.
+  const filePath = resolveDocPath(positional, config)
+    ?? resolvePromptInput(positional, config, { dieOnMiss: false })
+    ?? resolveDocArg(positional, config);
 
   const raw = readFileSync(filePath, 'utf8');
   const { frontmatter } = extractFrontmatter(raw);