dotmd-cli 0.33.0 → 0.35.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)
@@ -757,6 +757,12 @@ export const referenceFields = {
   bidirectional: ['related_plans'],       // warn if A→B but B↛A
   unidirectional: ['supports_plans'],     // one-way, no symmetry check
 };
+// Per-ref opt-out: prefix any value with `>` to mark that specific ref one-way
+// without changing the field's default. Useful for leaf→upstream-parent refs
+// (audits, hub docs) where a back-ref would force editing a stable parent.
+//   related_docs:
+//     - docs/sibling-design.md            # bidirectional (default for the field)
+//     - "> docs/audit-beyond-platform.md" # one-way upstream — no back-ref expected
 
 export const index = {
   path: 'docs/docs.md',

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.33.0",
+  "version": "0.35.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/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/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 = [];
 
@@ -169,10 +175,30 @@ export function parseDocFile(filePath, config) {
   const bodyLinks = extractBodyLinks(body);
   const hasCloseout = /^##\s+Closeout/m.test(body);
 
-  // Dynamic reference field extraction
+  // Dynamic reference field extraction. A leading `>` on a value (e.g.
+  // `"> docs/audit-beyond-platform.md"`) marks that single ref as one-way —
+  // the prefix is stripped so path resolution still works, and the direction
+  // is recorded on a parallel `refFieldDirections[field]` array indexed the
+  // same as `refFields[field]`. Bidirectional reciprocity checks consume the
+  // directions to skip outbound entries that opted out of expecting a back-ref.
   const refFields = {};
+  const refFieldDirections = {};
   for (const field of [...(config.referenceFields.bidirectional || []), ...(config.referenceFields.unidirectional || [])]) {
-    refFields[field] = normalizeStringList(parsedFrontmatter[field]);
+    const raw = normalizeStringList(parsedFrontmatter[field]);
+    const paths = [];
+    const directions = [];
+    for (const entry of raw) {
+      const oneWay = entry.match(/^>\s*(.+)$/);
+      if (oneWay) {
+        paths.push(oneWay[1].trim());
+        directions.push('one-way');
+      } else {
+        paths.push(entry);
+        directions.push('two-way');
+      }
+    }
+    refFields[field] = paths;
+    refFieldDirections[field] = directions;
   }
 
   // Tag doc with its root
@@ -209,6 +235,7 @@ export function parseDocFile(filePath, config) {
     checklist,
     bodyLinks,
     refFields,
+    refFieldDirections,
     checklistCompletionRate: computeChecklistCompletionRate(checklist),
     hasCloseout,
     hasNextStep: Boolean(nextStep),

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,37 +189,111 @@ 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 || [];
   if (!biFields.length) return { warnings, errors: [] };
 
+  // refMap stores `Set<targetPath>` keyed by the source doc path — used to
+  // answer "does B reference A?" via .has(). oneWayMap stores the subset of A's
+  // outbound refs that opted out of expecting a back-ref (via the `>` prefix in
+  // frontmatter, parsed in src/index.mjs:parseDocFile). We split these so the
+  // membership check stays cheap (Set.has) while the per-ref directionality
+  // filter only consults oneWayMap when iterating outbound edges.
   const refMap = new Map();
+  const oneWayMap = new Map();
   for (const doc of docs) {
     const docDir = path.dirname(path.join(config.repoRoot, doc.path));
     const refs = new Set();
+    const oneWay = new Set();
     for (const field of biFields) {
-      for (const relPath of (doc.refFields[field] || [])) {
+      const entries = doc.refFields[field] || [];
+      const dirs = doc.refFieldDirections?.[field] || [];
+      for (let i = 0; i < entries.length; i++) {
+        const relPath = entries[i];
         // Use the same doc-relative-then-repo-root fallback as validateDoc so
         // both styles produce identical refMap keys; otherwise an entry like
         // `docs/foo.md` (repo-root style) gets keyed as
         // `<doc-parent>/docs/foo.md` and never matches the target's repo path.
         const resolved = resolveRefPath(relPath, docDir, config.repoRoot)
           ?? path.resolve(docDir, relPath);
-        refs.add(toRepoPath(resolved, config.repoRoot));
+        const targetPath = toRepoPath(resolved, config.repoRoot);
+        refs.add(targetPath);
+        if (dirs[i] === 'one-way') oneWay.add(targetPath);
       }
     }
     refMap.set(doc.path, refs);
+    oneWayMap.set(doc.path, oneWay);
   }
 
   for (const [docPath, refs] of refMap) {
+    const oneWay = oneWayMap.get(docPath);
     for (const targetPath of refs) {
+      if (oneWay.has(targetPath)) continue;
       const targetRefs = refMap.get(targetPath);
       if (targetRefs && !targetRefs.has(docPath)) {
         warnings.push({ path: docPath, level: 'warning',