dotmd-cli 0.59.0 → 0.61.0

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
@@ -901,7 +928,10 @@ export function appendVersionHistory(filePath, entry) {
 
 export function updateFrontmatter(filePath, updates) {
   const raw = readFileSync(filePath, 'utf8');
-  if (!raw.startsWith('---\n')) throw new Error(`${filePath} has no frontmatter block.`);
+  // Name the remedy in the error: this is where every status verb lands when a
+  // doc was created outside dotmd, and "no frontmatter block" alone left
+  // sessions retrying other verbs instead of fixing the doc.
+  if (!raw.startsWith('---\n')) throw new Error(`${filePath} has no frontmatter block. Retrofit it first: dotmd bulk-tag ${filePath} --type <type> --status <status>`);
 
   const endMarker = raw.indexOf('\n---\n', 4);
   if (endMarker === -1) throw new Error(`${filePath} has unclosed frontmatter block.`);

package/src/new.mjs

@@ -256,7 +256,7 @@ function mergeBodyFrontmatter(scaffoldFm, overrides, cliType) {
   return fm;
 }
 
-function readBodyInput(source) {
+export function readBodyInput(source) {
   if (source === '-') {
     try { return readFileSync(0, 'utf8'); } catch (err) { die(`Could not read body from stdin: ${err.message}`); }
   }
@@ -548,6 +548,12 @@ export async function runNew(argv, config, opts = {}) {
   if (typeName === 'prompt') {
     process.stdout.write(dim('Session-local — no need to commit. The next session runs `dotmd use` (or `dotmd use ' + repoPath + '`) to consume it.\n'));
   }
+  // Teach the field-length contract at the moment the fields get written —
+  // learning it from a cap warning later sends sessions into hand-trim /
+  // re-check loops.
+  if (typeName === 'plan') {
+    process.stdout.write(dim('current_state = 2-4 sentence summary (cap 1500 chars); next_step = 1-2 sentence pointer (cap 800). Detail goes in the body, not frontmatter.\n'));
+  }
   try {
     const { isGitIgnored } = await import('./git.mjs');
     if (isGitIgnored(filePath, config.repoRoot)) {

package/src/prompts.mjs

@@ -11,7 +11,7 @@ import { green, dim } from './color.mjs';
 // `resume` is an alias for `use` — agents reach for "resume" when continuing a
 // session; `use` reads as internal mechanics. Both names stay valid; the
 // canonical output ("Consumed: …") is unchanged.
-const SUBCOMMANDS = new Set(['list', 'next', 'use', 'resume', 'archive', 'new', 'hold', 'unhold', 'shelve', 'unshelve']);
+const SUBCOMMANDS = new Set(['list', 'next', 'use', 'resume', 'show', 'peek', 'archive', 'new', 'hold', 'unhold', 'shelve', 'unshelve']);
 
 export async function runPrompts(argv, config, opts = {}) {
   const sub = argv[0];
@@ -26,6 +26,8 @@ export async function runPrompts(argv, config, opts = {}) {
     case 'next':     return runPromptsNext(rest, config, opts);
     case 'use':      return runPromptsUse(rest, config, opts);
     case 'resume':   return runPromptsUse(rest, config, opts);
+    case 'show':     return runPromptsShow(rest, config);
+    case 'peek':     return runPromptsShow(rest, config);
     case 'archive':  return runPromptsArchive(rest, config, opts);
     case 'new':      return runPromptsNew(rest, config, opts);
     case 'hold':     return runPromptsHold(rest, config, opts);
@@ -283,6 +285,28 @@ export function consumePrompt(filePath, config, opts) {
   process.stderr.write(`${green('✓ Consumed')}: ${consumedPath}\n`);
 }
 
+// Read-only peek: print the body WITHOUT consuming. The sanctioned triage path
+// — surveying pending prompts must not archive them (that's `use`'s job), and
+// it must not require raw cat/Read (which the guard warns about).
+function runPromptsShow(argv, config) {
+  const input = argv.find(a => !a.startsWith('-'));
+  if (!input) die('Usage: dotmd prompts show <file-or-slug>');
+  const filePath = resolvePromptInput(input, config);
+
+  const raw = readFileSync(filePath, 'utf8');
+  const { frontmatter, body } = extractFrontmatter(raw);
+  const parsed = parseSimpleFrontmatter(frontmatter);
+  const repoPath = toRepoPath(filePath, config.repoRoot);
+  if (asString(parsed.type) !== 'prompt') {
+    die(`Not a prompt (type: ${asString(parsed.type) ?? 'unknown'}): ${repoPath}`);
+  }
+
+  const status = asString(parsed.status) ?? 'unknown';
+  process.stderr.write(dim(`${repoPath} [${status}] — read-only peek; \`dotmd use ${repoPath}\` to consume\n`));
+  process.stdout.write(body);
+  if (!body.endsWith('\n')) process.stdout.write('\n');
+}
+
 function runPromptsArchive(argv, config, opts = {}) {
   const input = argv.find(a => !a.startsWith('-'));
   if (!input) die('Usage: dotmd prompts archive <file-or-slug>');

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);

package/src/validate.mjs

@@ -475,7 +475,7 @@ export function validatePlanShape(doc, body, frontmatter, config) {
     doc.warnings.push({
       path: doc.path,
       level: 'warning',
-      message: `\`next_step\` is ${nextStep.length} chars (cap: 800). Long prose belongs in the body — keep next_step as a 1-2 sentence pointer.`,
+      message: `\`next_step\` is ${nextStep.length} chars (cap: 800). One mechanical fix: \`dotmd doctor --frontmatter-fix\` (moves the overflow into the body) — do NOT hand-trim or re-run check in a loop. Going forward, write next_step as a 1-2 sentence pointer; detail goes in the body.`,
     });
   }
 
@@ -488,7 +488,7 @@ export function validatePlanShape(doc, body, frontmatter, config) {
     doc.warnings.push({
       path: doc.path,
       level: 'warning',
-      message: `\`current_state\` is ${currentState.length} chars (cap: 1500). Long prose belongs in the body.`,
+      message: `\`current_state\` is ${currentState.length} chars (cap: 1500). One mechanical fix: \`dotmd doctor --frontmatter-fix\` (moves the overflow into the body) — do NOT hand-trim or re-run check in a loop. Going forward, write current_state as a 2-4 sentence summary; detail goes in the body.`,
     });
   }