dotmd-cli 0.32.1 → 0.34.0

package/README.md

@@ -179,7 +179,7 @@ dotmd query [filters]        Filtered search
 dotmd plans                  List all plans
 dotmd stale                  List stale docs
 dotmd actionable             List docs with next steps
-dotmd index [--write]        Generate/update docs.md index block
+dotmd index [--print]        Generate/update docs.md index block
 dotmd hud                    Actionable triage (silent when clean — ideal SessionStart hook)
 dotmd pickup <file>          Pick up a plan (in-session + print body)
 dotmd release [<file>]       Release in-session lease (alias: unpickup)

package/bin/dotmd.mjs

@@ -58,7 +58,7 @@ Lifecycle:
 
 Create & Export:
   new <type> <name> [body]          Create doc of given type (plan, doc, prompt)
-  index [--write]                   Generate/update docs.md index block
+  index [--print]                   Generate/update docs.md index block
   export [--format md|html|json]    Export docs as markdown, HTML, or JSON
   notion import|export|sync [db-id] Notion database integration
 
@@ -354,12 +354,12 @@ date to match the last git commit date, fixing date drift warnings.
 
 Use --dry-run (-n) to preview changes without writing anything.`,
 
-  index: `dotmd index [--write] — generate/update docs.md index
+  index: `dotmd index [--print] — generate/update docs.md index
 
-Without --write, prints the generated content to stdout.
-With --write, updates the configured index file in place.
+Updates the configured index file in place (writes by default as of 0.34.0).
+Use --print to dump the regenerated content to stdout without writing.
 
-Use --dry-run (-n) with --write to preview without writing.`,
+Use --dry-run (-n) to preview without writing.`,
 
   new: `dotmd new <type> <name> [body] — create a new document
 
@@ -954,16 +954,16 @@ async function main() {
     if (!config.indexPath) {
       die('Index generation is not configured. Add an `index` section to your dotmd.config.mjs.');
     }
-    const write = args.includes('--write');
+    const print = args.includes('--print');
     const { renderIndexFile, writeIndex } = await import('../src/index-file.mjs');
     const rendered = renderIndexFile(index, config);
-    if (write && !dryRun) {
-      writeIndex(rendered, config);
-      process.stdout.write(`Updated ${config.indexPath}\n`);
-    } else if (write && dryRun) {
+    if (print) {
+      process.stdout.write(rendered);
+    } else if (dryRun) {
       process.stdout.write(`[dry-run] Would update ${config.indexPath}\n`);
     } else {
-      process.stdout.write(rendered);
+      writeIndex(rendered, config);
+      process.stdout.write(`Updated ${config.indexPath}\n`);
     }
     return;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.32.1",
+  "version": "0.34.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

@@ -46,6 +46,22 @@ function generatePlansCommand(config) {
   return lines.join('\n');
 }
 
+function generateBatonCommand() {
+  const lines = [VERSION_MARKER, ''];
+  lines.push('You are wrapping this session. Hand the baton cleanly to the next one.');
+  lines.push('');
+  lines.push('1. **Update the in-flight plan.** Find it via `dotmd plans --status in-session`. Edit its `current_state:` / `next_step:` frontmatter so they reflect where things actually stand. If status should change (shipped → archive, stuck on a human decision → awaiting, etc.), transition with `dotmd status <file> <status>` — or `dotmd archive <file>` if work is done.');
+  lines.push('');
+  lines.push('2. **Save ONE lean handoff prompt.** Run `dotmd new prompt resume-<plan-slug>` with a body of ~10-20 lines: point at the plan file, name the next concrete decision, flag any gotchas. Do NOT recap the plan body (the plan is for that). Do NOT print the handoff into chat for the user to copy-paste — the saved prompt is the handoff.');
+  lines.push('');
+  lines.push('3. **Release the lease.** `dotmd release` (skip if `dotmd archive` already closed out — archive auto-releases).');
+  lines.push('');
+  lines.push('The next session\'s `dotmd hud` (SessionStart hook) surfaces the pending prompt automatically.');
+  lines.push('');
+
+  return lines.join('\n');
+}
+
 function generateDocsCommand(config) {
   const roots = Array.isArray(config.raw?.root) ? config.raw.root : [config.raw?.root ?? 'docs'];
   const rootCount = roots.length;
@@ -118,6 +134,7 @@ export function scaffoldClaudeCommands(cwd, config, opts = {}) {
   const files = [
     { name: 'plans.md', generate: () => generatePlansCommand(config) },
     { name: 'docs.md', generate: () => generateDocsCommand(config) },
+    { name: 'baton.md', generate: () => generateBatonCommand() },
   ];
 
   for (const { name, generate } of files) {
@@ -149,12 +166,24 @@ export function scaffoldClaudeCommands(cwd, config, opts = {}) {
   return results;
 }
 
+// Self-heal: regen any slash-command file whose banner is older than pkg.version.
+// Designed for runHud to call at SessionStart — closes the gap between "user
+// upgraded dotmd" and "slash-command body reflects the new version" without
+// requiring a manual `dotmd doctor`. Returns only the entries that actually
+// changed so the caller can surface a one-line note; an empty array means the
+// hud silent-clean contract is preserved. `skipped` (user-managed, no banner)
+// and `current` entries are filtered out — callers don't care about them.
+export function refreshStaleSlashCommands(config) {
+  const results = scaffoldClaudeCommands(config.repoRoot, config);
+  return results.filter(r => r.action === 'updated');
+}
+
 export function checkClaudeCommands(cwd) {
   const commandsDir = path.join(cwd, '.claude', 'commands');
   if (!existsSync(commandsDir)) return [];
 
   const warnings = [];
-  for (const name of ['plans.md', 'docs.md']) {
+  for (const name of ['plans.md', 'docs.md', 'baton.md']) {
     const filePath = path.join(commandsDir, name);
     const installedVersion = getInstalledVersion(filePath);
     if (installedVersion && installedVersion !== pkg.version) {

package/src/glossary.mjs

@@ -1,7 +1,7 @@
 import { readFileSync, existsSync } from 'node:fs';
 import path from 'node:path';
 import { buildIndex } from './index.mjs';
-import { die, warn } from './util.mjs';
+import { die, warn, suggestCandidates } from './util.mjs';
 import { bold, dim, green, yellow } from './color.mjs';
 
 function parseGlossaryTable(content, sectionHeading) {
@@ -217,7 +217,9 @@ export function runGlossary(argv, config) {
   }
 
   if (matches.length === 0) {
-    process.stdout.write(dim(`No glossary match for "${term}".`) + '\n');
+    const suggestions = suggestCandidates(term, entries.map(e => e.term));
+    const hint = suggestions.length ? ` Did you mean: ${suggestions.join(', ')}?` : '';
+    process.stdout.write(dim(`No glossary match for "${term}".${hint}`) + '\n');
     return;
   }
 

package/src/hud.mjs

@@ -5,6 +5,7 @@ import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { asString, toRepoPath } from './util.mjs';
 import { green, yellow, red, dim } from './color.mjs';
 import { buildIndex } from './index.mjs';
+import { refreshStaleSlashCommands } from './claude-commands.mjs';
 
 const MAX_PREVIEW = 5;
 
@@ -89,6 +90,15 @@ export function runHud(argv, config) {
   const json = argv.includes('--json');
   const hud = buildHud(config);
 
+  // Self-heal stale slash-command files. Wrapped: a broken scaffolder must
+  // never kill the SessionStart hook (would block every session). Skipped in
+  // --json mode to keep the structured shape stable for programmatic callers.
+  let refreshed = [];
+  if (!json) {
+    try { refreshed = refreshStaleSlashCommands(config); }
+    catch { /* swallow — see comment above */ }
+  }
+
   if (json) {
     process.stdout.write(JSON.stringify(hud, null, 2) + '\n');
     return;
@@ -107,6 +117,12 @@ export function runHud(argv, config) {
   if (hud.errors > 0) {
     lines.push(red(`✗ ${hud.errors} validation error${hud.errors === 1 ? '' : 's'}  ${dim('(run: dotmd check)')}`));
   }
+  if (refreshed.length > 0) {
+    const from = refreshed[0].from;
+    const to = refreshed[0].to;
+    const names = refreshed.map(r => r.name).join(', ');
+    lines.push(dim(`↻ slash commands refreshed (v${from} → v${to}): ${names}`));
+  }
 
   if (lines.length === 0) return; // silent when clean
   process.stdout.write(lines.join('\n') + '\n');

package/src/index.mjs

@@ -3,12 +3,18 @@ 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 { validateDoc, validatePlanShape, validateDocShape, checkBidirectionalReferences, checkGitStaleness, computeDaysSinceUpdate, computeIsStale, computeChecklistCompletionRate } from './validate.mjs';
+import { validateDoc, validatePlanShape, validateDocShape, checkBidirectionalReferences, checkGitStaleness, computeDaysSinceUpdate, computeIsStale, computeChecklistCompletionRate, enrichRefErrorSuggestions } from './validate.mjs';
 import { checkIndex } from './index-file.mjs';
 import { checkClaudeCommands } from './claude-commands.mjs';
 
 export function buildIndex(config) {
   const docs = collectDocFiles(config).map(f => parseDocFile(f, config));
+  // Per-file validation (validateDoc) ran during parse without sibling
+  // visibility. Now that the full index is materialized, enrich
+  // unresolved-ref entries with "Did you mean..." candidates drawn from the
+  // index — mutates doc.errors/doc.warnings in place so the aggregations
+  // below pick up the enriched messages.
+  enrichRefErrorSuggestions(docs, config);
   const warnings = [];
   const errors = [];
 

package/src/lifecycle.mjs

@@ -35,7 +35,7 @@ export function regenIndex(config) {
     const index = buildIndex(config);
     writeIndex(renderIndexFile(index, config), config);
   } catch (err) {
-    warn(`Could not regenerate index (run \`dotmd index --write\`): ${err.message}`);
+    warn(`Could not regenerate index (run \`dotmd index\`): ${err.message}`);
   }
 }
 

package/src/new.mjs

@@ -51,6 +51,9 @@ ${ctx?.bodyInput?.trim() ?? ''}
     dir: 'plans',
     targetRoot: 'plans',
     defaultStatus: 'active',
+    // Body input lands in the Problem section. Plans don't have an Overview;
+    // Problem is the established opening section in the build-up shape.
+    acceptsBody: true,
     frontmatter: (s, d) => [
       'type: plan',
       `status: ${s}`,
@@ -73,7 +76,7 @@ ${ctx?.bodyInput?.trim() ?? ''}
 
 ## Problem
 
-
+${ctx?.bodyInput?.trim() ?? ''}
 
 ## Goals
 
@@ -242,8 +245,9 @@ export async function runNew(argv, config, opts = {}) {
 
   // Fail-fast when the user passes body input to a template that doesn't
   // consume it — silently discarding heredoc content is the worst UX.
-  // Templates opt in via `acceptsBody: true` or `requiresBody: true`. Built-in
-  // `prompt` is the only template that consumes body by default.
+  // Templates opt in via `acceptsBody: true` or `requiresBody: true`. All
+  // built-in templates (doc, plan, prompt) accept body; this guard fires
+  // only for custom templates that opt out.
   if (bodyInput !== null && !template.acceptsBody && !template.requiresBody) {
     const accepting = Object.entries(BUILTIN_TEMPLATES)
       .filter(([, t]) => t.acceptsBody || t.requiresBody)

package/src/query.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, suggestCandidates } from './util.mjs';
 import { renderProgressBar, formatCurrentState } from './render.mjs';
 import { computeDaysSinceUpdate, computeIsStale } from './validate.mjs';
 import { getGitLastModifiedBatch } from './git.mjs';
@@ -90,10 +90,31 @@ export function runQuery(index, argv, config, opts = {}) {
 
   if (opts.preset === 'plans' || opts.preset === 'prompts') {
     renderPlansOutput(docs, filters, config, { noun: opts.preset });
+    if (docs.length === 0) writeUnknownFilterValueHint(filters, index);
     return;
   }
 
   renderQueryResults(docs, filters, config);
+  if (docs.length === 0) writeUnknownFilterValueHint(filters, index);
+}
+
+// When a query returns nothing AND a value-shaped filter (currently --module)
+// names a value that doesn't exist anywhere in the index, the empty result is
+// almost certainly a typo rather than a combination miss. Surface a hint so
+// the agent doesn't have to grep modules to discover the right spelling.
+function writeUnknownFilterValueHint(filters, index) {
+  if (filters.module) {
+    const allModules = new Set();
+    for (const d of index.docs) {
+      for (const m of (d.modules ?? [])) allModules.add(m);
+    }
+    const exists = [...allModules].some(m => m.toLowerCase() === filters.module.toLowerCase());
+    if (!exists) {
+      const suggestions = suggestCandidates(filters.module, [...allModules]);
+      const hint = suggestions.length ? ` Did you mean: ${suggestions.join(', ')}?` : '';
+      process.stdout.write(dim(`No module \`${filters.module}\` in index.${hint}`) + '\n');
+    }
+  }
 }
 
 export function parseQueryArgs(argv) {

package/src/util.mjs

@@ -89,6 +89,42 @@ export function levenshtein(a, b) {
   return matrix[b.length][a.length];
 }
 
+// Top-N candidates from a list, ranked for "did you mean" hints. Substring
+// match wins (cheap and intent-revealing for typos that share a prefix or
+// stem); Levenshtein distance ≤3 catches transpositions and small edits.
+// Results are deduped and capped. Empty input or empty candidate list returns
+// an empty array — callers should suppress the hint line in that case.
+export function suggestCandidates(query, candidates, max = 3) {
+  if (!query || !candidates?.length) return [];
+  const lower = String(query).toLowerCase();
+  const scored = new Map();
+
+  for (const cand of candidates) {
+    if (!cand) continue;
+    const candLower = String(cand).toLowerCase();
+    if (candLower === lower) continue;
+    if (candLower.includes(lower) || lower.includes(candLower)) {
+      // Substring hits sort first; shorter candidates rank higher within that bucket.
+      scored.set(cand, Math.min(scored.get(cand) ?? Infinity, candLower.length));
+    }
+  }
+
+  if (scored.size < max) {
+    for (const cand of candidates) {
+      if (!cand || scored.has(cand)) continue;
+      const candLower = String(cand).toLowerCase();
+      if (candLower === lower) continue;
+      const dist = levenshtein(lower, candLower);
+      if (dist <= 3) scored.set(cand, 1000 + dist);
+    }
+  }
+
+  return [...scored.entries()]
+    .sort((a, b) => a[1] - b[1])
+    .slice(0, max)
+    .map(([cand]) => cand);
+}
+
 export function resolveDocPath(input, config) {
   if (!input) return null;
   if (path.isAbsolute(input)) return existsSync(input) ? input : null;

package/src/validate.mjs

@@ -1,5 +1,5 @@
 import path from 'node:path';
-import { asString, resolveRefPath } from './util.mjs';
+import { asString, resolveRefPath, suggestCandidates } from './util.mjs';
 import { getGitLastModified, getGitLastModifiedBatch } from './git.mjs';
 import { toRepoPath } from './util.mjs';
 
@@ -176,7 +176,12 @@ export function validateDoc(doc, frontmatter, headingTitle, config) {
     for (const field of allRefFields) {
       for (const relPath of (doc.refFields[field] || [])) {
         if (!resolveRefPath(relPath, docDir, config.repoRoot)) {
-          doc.errors.push({ path: doc.path, level: 'error', message: `${field} entry \`${relPath}\` does not resolve to an existing file.` });
+          doc.errors.push({
+            path: doc.path,
+            level: 'error',
+            message: `${field} entry \`${relPath}\` does not resolve to an existing file.`,
+            meta: { kind: 'ref-resolution', field, relPath },
+          });
         }
       }
     }
@@ -184,12 +189,70 @@ export function validateDoc(doc, frontmatter, headingTitle, config) {
     // Validate body links resolve to existing files
     for (const link of (doc.bodyLinks || [])) {
       if (!resolveRefPath(link.href, docDir, config.repoRoot)) {
-        doc.warnings.push({ path: doc.path, level: 'warning', message: `body link \`${link.href}\` does not resolve to an existing file.` });
+        doc.warnings.push({
+          path: doc.path,
+          level: 'warning',
+          message: `body link \`${link.href}\` does not resolve to an existing file.`,
+          meta: { kind: 'ref-resolution', field: 'body-link', relPath: link.href },
+        });
       }
     }
   }
 }
 
+// Guess which doc type a ref field expects so suggestions don't propose
+// nonsense (a `related_plans` ref shouldn't suggest doc filenames). Heuristic:
+// match common substrings in the field name. When ambiguous, return null so
+// the caller suggests across all types.
+function inferRefFieldType(field) {
+  if (!field) return null;
+  const f = field.toLowerCase();
+  if (f.includes('plan')) return 'plan';
+  if (f.includes('doc')) return 'doc';
+  if (f.includes('prompt')) return 'prompt';
+  if (f.includes('research')) return 'research';
+  return null;
+}
+
+function candidatePathsForType(docs, type) {
+  // When the field implies a type, exclude docs that explicitly declare a
+  // different type. Untyped docs (no frontmatter `type:`) are kept — we
+  // don't know they aren't the target, so suggesting them is still useful.
+  const matches = type ? docs.filter(d => !d.type || d.type === type) : docs;
+  // Suggest by basename (the friendly handle agents/humans actually type) and
+  // by repo-relative path (covers cases where multiple files share a basename
+  // and the disambiguator is the directory).
+  const out = new Set();
+  for (const d of matches) {
+    out.add(path.basename(d.path));
+    out.add(d.path);
+  }
+  return [...out];
+}
+
+// Post-pass enrichment: walk every doc's errors/warnings for unresolved-ref
+// entries and append `Did you mean: a, b, c?` using the full index. Runs
+// after parsing so it has the global doc list (validateDoc runs per-file and
+// can't see siblings). Filters candidates by ref-field type when the field
+// name implies one (e.g. `related_plans` → plans only).
+export function enrichRefErrorSuggestions(docs, config) {
+  const enrich = (entry) => {
+    if (!entry?.meta || entry.meta.kind !== 'ref-resolution') return;
+    if (entry._suggested) return;
+    const inferred = inferRefFieldType(entry.meta.field);
+    const candidates = candidatePathsForType(docs, inferred);
+    const suggestions = suggestCandidates(path.basename(entry.meta.relPath), candidates);
+    entry._suggested = true;
+    if (suggestions.length === 0) return;
+    entry.message = `${entry.message} Did you mean: ${suggestions.join(', ')}?`;
+  };
+
+  for (const doc of docs) {
+    for (const e of (doc.errors || [])) enrich(e);
+    for (const w of (doc.warnings || [])) enrich(w);
+  }
+}
+
 export function checkBidirectionalReferences(docs, config) {
   const warnings = [];
   const biFields = config.referenceFields.bidirectional || [];