dotmd-cli 0.5.0 → 0.7.0

package/src/graph.mjs

@@ -0,0 +1,268 @@
+import path from 'node:path';
+import { toSlug, toRepoPath, warn } from './util.mjs';
+import { bold, red, green, dim } from './color.mjs';
+
+const STATUS_COLORS = {
+  active:    '#b3e6b3',
+  ready:     '#b3d9ff',
+  planned:   '#ffffb3',
+  research:  '#e6ccff',
+  blocked:   '#ffb3b3',
+  reference: '#d9d9d9',
+  archived:  '#e6e6e6',
+};
+const DEFAULT_COLOR = '#f2f2f2';
+
+export function buildGraph(index, config, filters = {}) {
+  const biFields = new Set(config.referenceFields.bidirectional || []);
+  const uniFields = new Set(config.referenceFields.unidirectional || []);
+  const allRefFields = [...biFields, ...uniFields];
+
+  // Filter docs
+  let docs = index.docs;
+  if (filters.statuses?.length) {
+    docs = docs.filter(d => filters.statuses.includes(d.status));
+  }
+  if (filters.module) {
+    const m = filters.module.toLowerCase();
+    docs = docs.filter(d => (d.modules ?? []).some(mod => mod.toLowerCase() === m) || (d.module ?? '').toLowerCase() === m);
+  }
+  if (filters.surface) {
+    const s = filters.surface.toLowerCase();
+    docs = docs.filter(d => (d.surfaces ?? []).some(sf => sf.toLowerCase() === s) || (d.surface ?? '').toLowerCase() === s);
+  }
+
+  const docPathSet = new Set(docs.map(d => d.path));
+  const allDocPaths = new Set(index.docs.map(d => d.path));
+  const docByPath = new Map(index.docs.map(d => [d.path, d]));
+
+  // Build nodes
+  const nodes = docs.map(d => ({
+    id: d.path,
+    slug: toSlug(d),
+    title: d.title,
+    status: d.status,
+    module: d.module,
+    surface: d.surface,
+    edgeCount: 0,
+  }));
+  const nodeMap = new Map(nodes.map(n => [n.id, n]));
+
+  // Build edges
+  const edges = [];
+  const edgeKeys = new Set();
+  const referencedPaths = new Set();
+
+  for (const doc of docs) {
+    const docDir = path.dirname(path.join(config.repoRoot, doc.path));
+
+    for (const field of allRefFields) {
+      for (const relPath of (doc.refFields[field] || [])) {
+        const resolved = path.resolve(docDir, relPath);
+        const targetPath = toRepoPath(resolved, config.repoRoot);
+        const edgeKey = `${doc.path}|${targetPath}|${field}`;
+        if (edgeKeys.has(edgeKey)) continue;
+        edgeKeys.add(edgeKey);
+
+        const broken = !allDocPaths.has(targetPath);
+        const external = !broken && !docPathSet.has(targetPath);
+
+        edges.push({
+          source: doc.path,
+          target: targetPath,
+          field,
+          type: biFields.has(field) ? 'bidirectional' : 'unidirectional',
+          broken,
+          external,
+        });
+
+        referencedPaths.add(targetPath);
+        referencedPaths.add(doc.path);
+      }
+    }
+  }
+
+  // Count edges per node
+  for (const edge of edges) {
+    if (nodeMap.has(edge.source)) nodeMap.get(edge.source).edgeCount++;
+  }
+
+  // Find orphans (no outgoing or incoming edges among filtered docs)
+  const connectedPaths = new Set();
+  for (const edge of edges) {
+    connectedPaths.add(edge.source);
+    if (!edge.broken && !edge.external) connectedPaths.add(edge.target);
+  }
+  const orphans = docs.filter(d => !connectedPaths.has(d.path)).map(d => d.path);
+
+  const brokenEdges = edges.filter(e => e.broken);
+
+  return {
+    nodes,
+    edges,
+    orphans,
+    brokenEdges,
+    stats: {
+      nodeCount: nodes.length,
+      edgeCount: edges.length,
+      orphanCount: orphans.length,
+      brokenEdgeCount: brokenEdges.length,
+    },
+  };
+}
+
+// ── Text renderer ──────────────────────────────────────────────────────
+
+export function renderGraphText(graph, config) {
+  const defaultRenderer = (g) => _renderGraphText(g, config);
+  if (config.hooks.renderGraph) {
+    try { return config.hooks.renderGraph(graph, defaultRenderer); }
+    catch (err) { warn(`Hook 'renderGraph' threw: ${err.message}`); }
+  }
+  return defaultRenderer(graph);
+}
+
+function _renderGraphText(graph, config) {
+  const { nodes, edges, orphans, stats } = graph;
+
+  if (stats.nodeCount === 0) return 'No documents found.\n';
+
+  const allRefFields = [
+    ...(config.referenceFields.bidirectional || []),
+    ...(config.referenceFields.unidirectional || []),
+  ];
+  if (allRefFields.length === 0) {
+    return `Graph — ${stats.nodeCount} docs, no reference fields configured\n\nAdd \`referenceFields\` to your config to enable relationship tracking.\n`;
+  }
+
+  const lines = [];
+  const parts = [`${stats.nodeCount} docs`, `${stats.edgeCount} edges`];
+  if (stats.orphanCount > 0) parts.push(`${stats.orphanCount} orphans`);
+  if (stats.brokenEdgeCount > 0) parts.push(`${stats.brokenEdgeCount} broken`);
+  lines.push(bold(`Graph`) + dim(` — ${parts.join(', ')}`));
+  lines.push('');
+
+  // Compute max field name length for alignment
+  const fieldNames = [...new Set(edges.map(e => e.field))];
+  const maxFieldLen = fieldNames.length > 0 ? Math.max(...fieldNames.map(f => f.length)) : 0;
+
+  // Group edges by source
+  const edgesBySource = new Map();
+  for (const edge of edges) {
+    if (!edgesBySource.has(edge.source)) edgesBySource.set(edge.source, []);
+    edgesBySource.get(edge.source).push(edge);
+  }
+
+  // Build a slug lookup for targets
+  const allDocByPath = new Map();
+  for (const n of nodes) allDocByPath.set(n.id, n.slug);
+
+  // Render each node with edges
+  const nodesWithEdges = nodes.filter(n => edgesBySource.has(n.id));
+  const nodesWithoutEdges = nodes.filter(n => !edgesBySource.has(n.id) && !orphans.includes(n.id));
+
+  for (const node of nodesWithEdges) {
+    lines.push(`${node.slug} ${dim(`(${node.status})`)}`);
+    for (const edge of edgesBySource.get(node.id)) {
+      const targetSlug = allDocByPath.get(edge.target) ?? path.basename(edge.target, '.md');
+      const fieldPad = edge.field.padEnd(maxFieldLen);
+      let line = `  ${'──'} ${fieldPad} ${'──'} ${targetSlug}`;
+      if (edge.broken) line += '  ' + red('[broken]');
+      if (edge.external) line += '  ' + dim('[external]');
+      lines.push(line);
+    }
+    lines.push('');
+  }
+
+  if (orphans.length > 0) {
+    const orphanSlugs = orphans.map(p => path.basename(p, '.md'));
+    lines.push(`${dim('Orphans')}: ${orphanSlugs.join(', ')}`);
+    lines.push('');
+  }
+
+  return `${lines.join('\n').trimEnd()}\n`;
+}
+
+// ── DOT renderer ───────────────────────────────────────────────────────
+
+export function renderGraphDot(graph, config) {
+  const { nodes, edges } = graph;
+  const lines = [];
+  lines.push('digraph dotmd {');
+  lines.push('  rankdir=LR;');
+  lines.push('  node [shape=box, style="rounded,filled", fontname="Helvetica"];');
+  lines.push('');
+
+  // Nodes
+  const nodeSet = new Set(nodes.map(n => n.slug));
+  for (const node of nodes) {
+    const color = STATUS_COLORS[node.status] ?? DEFAULT_COLOR;
+    lines.push(`  "${node.slug}" [label="${node.slug}\\n(${node.status ?? 'unknown'})", fillcolor="${color}"];`);
+  }
+
+  // Synthesize broken/external target nodes
+  const syntheticNodes = new Set();
+  for (const edge of edges) {
+    const targetSlug = path.basename(edge.target, '.md');
+    if (!nodeSet.has(targetSlug) && !syntheticNodes.has(targetSlug)) {
+      syntheticNodes.add(targetSlug);
+      if (edge.broken) {
+        lines.push(`  "${targetSlug}" [label="${targetSlug}\\n(unknown)", style="rounded,dashed,filled", fillcolor="#ffb3b3"];`);
+      } else if (edge.external) {
+        lines.push(`  "${targetSlug}" [label="${targetSlug}\\n(filtered)", style="rounded,dashed,filled", fillcolor="#e6e6e6"];`);
+      }
+    }
+  }
+
+  lines.push('');
+
+  // Detect mutual bidirectional edges for dir=both rendering
+  const biEdgeIndex = new Map();
+  for (const edge of edges) {
+    if (edge.type !== 'bidirectional') continue;
+    const key = `${edge.source}|${edge.target}|${edge.field}`;
+    biEdgeIndex.set(key, edge);
+  }
+
+  const rendered = new Set();
+  for (const edge of edges) {
+    const sourceSlug = path.basename(edge.source, '.md');
+    const targetSlug = path.basename(edge.target, '.md');
+    const edgeKey = [edge.source, edge.target, edge.field].sort().join('|');
+
+    if (rendered.has(edgeKey)) continue;
+    rendered.add(edgeKey);
+
+    if (edge.broken) {
+      lines.push(`  "${sourceSlug}" -> "${targetSlug}" [style=dashed, color=red, label="${edge.field}"];`);
+    } else if (edge.type === 'bidirectional') {
+      // Check if reverse edge exists
+      const reverseKey = `${edge.target}|${edge.source}|${edge.field}`;
+      if (biEdgeIndex.has(reverseKey)) {
+        lines.push(`  "${sourceSlug}" -> "${targetSlug}" [dir=both, label="${edge.field}", color="#666666"];`);
+      } else {
+        lines.push(`  "${sourceSlug}" -> "${targetSlug}" [label="${edge.field}", color="#666666"];`);
+      }
+    } else {
+      const style = edge.external ? ', style=dashed' : '';
+      lines.push(`  "${sourceSlug}" -> "${targetSlug}" [label="${edge.field}", color="#999999"${style}];`);
+    }
+  }
+
+  lines.push('}');
+  return lines.join('\n') + '\n';
+}
+
+// ── JSON renderer ──────────────────────────────────────────────────────
+
+export function renderGraphJson(graph) {
+  return JSON.stringify({
+    generatedAt: new Date().toISOString(),
+    stats: graph.stats,
+    nodes: graph.nodes,
+    edges: graph.edges.map(({ source, target, field, type, broken }) => ({
+      source, target, field, type, broken,
+    })),
+    orphans: graph.orphans,
+  }, null, 2) + '\n';
+}

package/src/index.mjs

@@ -1,7 +1,7 @@
 import { readdirSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
-import { extractFirstHeading, extractSummary, extractStatusSnapshot, extractNextStep, extractChecklistCounts } from './extractors.mjs';
+import { extractFirstHeading, extractSummary, extractStatusSnapshot, extractNextStep, extractChecklistCounts, extractBodyLinks } from './extractors.mjs';
 import { asString, normalizeStringList, normalizeBlockers, mergeUniqueStrings, toRepoPath, warn } from './util.mjs';
 import { validateDoc, checkBidirectionalReferences, checkGitStaleness, computeDaysSinceUpdate, computeIsStale, computeChecklistCompletionRate } from './validate.mjs';
 import { checkIndex } from './index-file.mjs';
@@ -119,6 +119,7 @@ export function parseDocFile(filePath, config) {
   const audience = asString(parsedFrontmatter.audience) ?? null;
   const executionMode = asString(parsedFrontmatter.execution_mode) ?? null;
   const checklist = extractChecklistCounts(body);
+  const bodyLinks = extractBodyLinks(body);
 
   // Dynamic reference field extraction
   const refFields = {};
@@ -148,6 +149,7 @@ export function parseDocFile(filePath, config) {
     auditLevel: asString(parsedFrontmatter.audit_level) ?? null,
     sourceOfTruth: asString(parsedFrontmatter.source_of_truth) ?? null,
     checklist,
+    bodyLinks,
     refFields,
     checklistCompletionRate: computeChecklistCompletionRate(checklist),
     hasNextStep: Boolean(nextStep),

package/src/lifecycle.mjs

@@ -1,11 +1,11 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
-import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
+import { extractFrontmatter, parseSimpleFrontmatter, replaceFrontmatter } from './frontmatter.mjs';
 import { asString, toRepoPath, die, warn, resolveDocPath, escapeRegex } from './util.mjs';
-import { gitMv } from './git.mjs';
+import { gitMv, getGitLastModified } from './git.mjs';
 import { buildIndex, collectDocFiles } from './index.mjs';
 import { renderIndexFile, writeIndex } from './index-file.mjs';
-import { green, dim } from './color.mjs';
+import { green, dim, yellow } from './color.mjs';
 
 export function runStatus(argv, config, opts = {}) {
   const { dryRun } = opts;
@@ -114,20 +114,10 @@ export function runArchive(argv, config, opts = {}) {
     process.stdout.write(`${prefix} Would move: ${oldRepoPath} → ${newRepoPath}\n`);
     if (config.indexPath) process.stdout.write(`${prefix} Would regenerate index\n`);
 
-    // Reference scan is read-only, still useful in dry-run
-    const basename = path.basename(filePath);
-    const references = [];
-    for (const docFile of collectDocFiles(config)) {
-      if (docFile === targetPath) continue;
-      const docRaw = readFileSync(docFile, 'utf8');
-      const { frontmatter: docFm } = extractFrontmatter(docRaw);
-      if (docFm.includes(basename)) {
-        references.push(toRepoPath(docFile, config.repoRoot));
-      }
-    }
-    if (references.length > 0) {
-      process.stdout.write('\nThese docs reference the old path — would need updating:\n');
-      for (const ref of references) process.stdout.write(`- ${ref}\n`);
+    // Preview reference updates
+    const refCount = countRefsToUpdate(filePath, targetPath, config);
+    if (refCount > 0) {
+      process.stdout.write(`${prefix} Would update references in ${refCount} file(s)\n`);
     }
     return;
   }
@@ -140,39 +130,78 @@ export function runArchive(argv, config, opts = {}) {
   const result = gitMv(filePath, targetPath, config.repoRoot);
   if (result.status !== 0) { die(result.stderr || 'git mv failed.'); }
 
+  // Auto-update references in other docs
+  const updatedRefCount = updateRefsAfterMove(filePath, targetPath, config);
+
   if (config.indexPath) {
     const index = buildIndex(config);
     writeIndex(renderIndexFile(index, config), config);
   }
 
   process.stdout.write(`${green('Archived')}: ${oldRepoPath} → ${newRepoPath}\n`);
+  if (updatedRefCount > 0) process.stdout.write(`Updated references in ${updatedRefCount} file(s).\n`);
   if (config.indexPath) process.stdout.write('Index regenerated.\n');
 
-  const basename = path.basename(filePath);
-  const references = [];
-  for (const docFile of collectDocFiles(config)) {
-    if (docFile === targetPath) continue;
-    const docRaw = readFileSync(docFile, 'utf8');
-    const { frontmatter: docFm } = extractFrontmatter(docRaw);
-    if (docFm.includes(basename)) {
-      references.push(toRepoPath(docFile, config.repoRoot));
-    }
-  }
-
-  if (references.length > 0) {
-    process.stdout.write('\nThese docs reference the old path — update reference entries:\n');
-    for (const ref of references) process.stdout.write(`- ${ref}\n`);
-  }
-
-  process.stdout.write('\nNext: commit, then update references if needed.\n');
   try { config.hooks.onArchive?.({ path: newRepoPath, oldStatus }, { oldPath: oldRepoPath, newPath: newRepoPath }); } catch (err) { warn(`Hook 'onArchive' threw: ${err.message}`); }
 }
 
 export function runTouch(argv, config, opts = {}) {
   const { dryRun } = opts;
-  const input = argv[0];
+  const useGit = argv.includes('--git');
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--config') { i++; continue; }
+    if (argv[i].startsWith('-')) continue;
+    positional.push(argv[i]);
+  }
+  const input = positional[0];
 
-  if (!input) { die('Usage: dotmd touch <file>'); }
+  // --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 prefix = dryRun ? dim('[dry-run] ') : '';
+    let synced = 0;
+
+    for (const filePath of allFiles) {
+      const repoPath = toRepoPath(filePath, config.repoRoot);
+      const raw = readFileSync(filePath, 'utf8');
+      const { frontmatter } = extractFrontmatter(raw);
+      if (!frontmatter) continue;
+
+      const parsed = parseSimpleFrontmatter(frontmatter);
+      const status = asString(parsed.status);
+      if (config.lifecycle.skipStaleFor.has(status)) continue;
+
+      const fmUpdated = asString(parsed.updated);
+      const gitDate = getGitLastModified(repoPath, config.repoRoot);
+      if (!gitDate) continue;
+
+      const gitDay = gitDate.slice(0, 10);
+      if (fmUpdated === gitDay) continue;
+
+      // Only sync if git is newer than frontmatter
+      const gitMs = new Date(gitDate).getTime();
+      const fmMs = fmUpdated ? new Date(fmUpdated).getTime() : 0;
+      if (fmMs >= gitMs) continue;
+
+      if (!dryRun) {
+        updateFrontmatter(filePath, { updated: gitDay });
+      }
+      process.stdout.write(`${prefix}${green('Synced')}: ${repoPath} (updated → ${gitDay})\n`);
+      synced++;
+    }
+
+    if (synced === 0) {
+      process.stdout.write(green('All frontmatter dates are in sync with git.') + '\n');
+    } else {
+      process.stdout.write(`\n${prefix}${synced} file(s) synced.\n`);
+    }
+    return;
+  }
+
+  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)}`); }
@@ -190,6 +219,69 @@ export function runTouch(argv, config, opts = {}) {
   try { config.hooks.onTouch?.({ path: toRepoPath(filePath, config.repoRoot) }, { path: toRepoPath(filePath, config.repoRoot), date: today }); } catch (err) { warn(`Hook 'onTouch' threw: ${err.message}`); }
 }
 
+/**
+ * After a file moves (archive/unarchive), update frontmatter references in all
+ * docs that pointed to the old location so they point to the new one.
+ */
+function updateRefsAfterMove(oldPath, newPath, config) {
+  const basename = path.basename(oldPath);
+  const allFiles = collectDocFiles(config);
+  let updatedCount = 0;
+
+  for (const docFile of allFiles) {
+    if (docFile === newPath) continue;
+    let raw = readFileSync(docFile, 'utf8');
+    const { frontmatter: fm } = extractFrontmatter(raw);
+    if (!fm || !fm.includes(basename)) continue;
+
+    const docDir = path.dirname(docFile);
+    const oldRelPath = path.relative(docDir, oldPath).split(path.sep).join('/');
+    const newRelPath = path.relative(docDir, newPath).split(path.sep).join('/');
+
+    let newFm = fm;
+
+    // Replace exact relative path
+    if (newFm.includes(oldRelPath)) {
+      newFm = newFm.split(oldRelPath).join(newRelPath);
+    }
+
+    // Also handle ./ prefix variant
+    const dotSlashOld = './' + oldRelPath;
+    if (newFm.includes(dotSlashOld)) {
+      newFm = newFm.split(dotSlashOld).join(newRelPath);
+    }
+
+    if (newFm !== fm) {
+      raw = replaceFrontmatter(raw, newFm);
+      writeFileSync(docFile, raw, 'utf8');
+      updatedCount++;
+    }
+  }
+
+  return updatedCount;
+}
+
+function countRefsToUpdate(oldPath, newPath, config) {
+  const basename = path.basename(oldPath);
+  const allFiles = collectDocFiles(config);
+  let count = 0;
+
+  for (const docFile of allFiles) {
+    if (docFile === newPath) continue;
+    const raw = readFileSync(docFile, 'utf8');
+    const { frontmatter: fm } = extractFrontmatter(raw);
+    if (!fm || !fm.includes(basename)) continue;
+
+    const docDir = path.dirname(docFile);
+    const oldRelPath = path.relative(docDir, oldPath).split(path.sep).join('/');
+    if (fm.includes(oldRelPath) || fm.includes('./' + oldRelPath)) {
+      count++;
+    }
+  }
+
+  return count;
+}
+
 export function updateFrontmatter(filePath, updates) {
   const raw = readFileSync(filePath, 'utf8');
   if (!raw.startsWith('---\n')) throw new Error(`${filePath} has no frontmatter block.`);

package/src/new.mjs

@@ -1,7 +1,40 @@
 import { existsSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { toRepoPath, die, warn } from './util.mjs';
-import { green, dim } from './color.mjs';
+import { green, dim, bold } from './color.mjs';
+
+const BUILTIN_TEMPLATES = {
+  default: {
+    description: 'Minimal document with status and updated date',
+    frontmatter: (s, d) => `status: ${s}\nupdated: ${d}`,
+    body: (t) => `\n# ${t}\n`,
+  },
+  plan: {
+    description: 'Execution plan with module, surface, and cross-references',
+    frontmatter: (s, d) => `status: ${s}\nupdated: ${d}\nsurface:\nmodule:\ncurrent_state:\nrelated_plans:`,
+    body: (t) => `\n# ${t}\n\n## Overview\n\n\n\n## Implementation Plan\n\n- [ ] \n\n## Open Questions\n\n\n`,
+  },
+  adr: {
+    description: 'Architecture Decision Record',
+    frontmatter: (s, d) => `status: ${s}\nupdated: ${d}\ndecision_date:\ndeciders:`,
+    body: (t) => `\n# ${t}\n\n## Context\n\n\n\n## Decision\n\n\n\n## Consequences\n\n\n`,
+  },
+  rfc: {
+    description: 'Request for Comments',
+    frontmatter: (s, d) => `status: ${s}\nupdated: ${d}\nowner:\nreviewers:`,
+    body: (t) => `\n# ${t}\n\n## Summary\n\n\n\n## Motivation\n\n\n\n## Detailed Design\n\n\n\n## Alternatives\n\n\n\n## Open Questions\n\n\n`,
+  },
+  audit: {
+    description: 'Codebase audit or research investigation',
+    frontmatter: (s, d) => `status: research\nupdated: ${d}\naudited: ${d}\naudit_level: pass1\nmodule:\nsource_of_truth: code\nsupports_plans:`,
+    body: (t) => `\n# ${t}\n\n## Scope\n\n\n\n## Findings\n\n\n\n## Recommendations\n\n\n`,
+  },
+  design: {
+    description: 'Design document with goals, non-goals, and implementation plan',
+    frontmatter: (s, d) => `status: ${s}\nupdated: ${d}\nowner:\nsurface:\nmodule:\nrelated_plans:`,
+    body: (t) => `\n# ${t}\n\n## Overview\n\n\n\n## Goals\n\n\n\n## Non-Goals\n\n\n\n## Design\n\n\n\n## Implementation Plan\n\n- [ ] \n`,
+  },
+};
 
 export function runNew(argv, config, opts = {}) {
   const { dryRun } = opts;
@@ -10,20 +43,29 @@ export function runNew(argv, config, opts = {}) {
   const positional = [];
   let status = 'active';
   let title = null;
+  let templateName = null;
   for (let i = 0; i < argv.length; i++) {
     if (argv[i] === '--status' && argv[i + 1]) { status = argv[++i]; continue; }
     if (argv[i] === '--title' && argv[i + 1]) { title = argv[++i]; continue; }
+    if (argv[i] === '--template' && argv[i + 1]) { templateName = argv[++i]; continue; }
+    if (argv[i] === '--list-templates') {
+      listTemplates(config);
+      return;
+    }
     if (!argv[i].startsWith('-')) positional.push(argv[i]);
   }
 
   const name = positional[0];
-  if (!name) { die('Usage: dotmd new <name> [--status <s>] [--title <t>]'); }
+  if (!name) { die('Usage: dotmd new <name> [--template <t>] [--status <s>] [--title <t>]\n       dotmd new --list-templates'); }
 
   // Validate status
   if (!config.validStatuses.has(status)) {
     die(`Invalid status: ${status}\nValid: ${[...config.validStatuses].join(', ')}`);
   }
 
+  // Resolve template
+  const template = resolveTemplate(templateName ?? 'default', config);
+
   // Slugify
   const slug = name.toLowerCase().replace(/[\s_]+/g, '-').replace(/[^a-z0-9-]/g, '').replace(/-+/g, '-').replace(/^-|-$/g, '');
   if (!slug) { die('Name resolves to empty slug: ' + name); }
@@ -39,16 +81,57 @@ export function runNew(argv, config, opts = {}) {
     die(`File already exists: ${repoPath}`);
   }
 
+  const today = new Date().toISOString().slice(0, 10);
+
+  // Generate content
+  let content;
+  if (typeof template === 'function') {
+    content = template(name, { status, title: docTitle, today });
+  } else {
+    const fm = template.frontmatter(status, today);
+    const body = template.body(docTitle);
+    content = `---\n${fm}\n---\n${body}`;
+  }
+
   if (dryRun) {
     process.stdout.write(`${dim('[dry-run]')} Would create: ${repoPath}\n`);
+    if (templateName) process.stdout.write(`${dim('[dry-run]')} Template: ${templateName}\n`);
     return;
   }
 
-  const today = new Date().toISOString().slice(0, 10);
-  const content = `---\nstatus: ${status}\nupdated: ${today}\n---\n\n# ${docTitle}\n`;
-
   writeFileSync(filePath, content, 'utf8');
-  process.stdout.write(`${green('Created')}: ${repoPath}\n`);
+  process.stdout.write(`${green('Created')}: ${repoPath}`);
+  if (templateName) process.stdout.write(` ${dim(`(template: ${templateName})`)}`);
+  process.stdout.write('\n');
 
-  try { config.hooks.onNew?.({ path: repoPath, status, title: docTitle }); } catch (err) { warn(`Hook 'onNew' threw: ${err.message}`); }
+  try { config.hooks.onNew?.({ path: repoPath, status, title: docTitle, template: templateName }); } catch (err) { warn(`Hook 'onNew' threw: ${err.message}`); }
+}
+
+function resolveTemplate(name, config) {
+  // Config templates take priority
+  const configTemplates = config.raw?.templates ?? {};
+  if (configTemplates[name]) return configTemplates[name];
+  if (BUILTIN_TEMPLATES[name]) return BUILTIN_TEMPLATES[name];
+
+  const available = [...new Set([...Object.keys(BUILTIN_TEMPLATES), ...Object.keys(configTemplates)])];
+  die(`Unknown template: ${name}\nAvailable: ${available.join(', ')}`);
+}
+
+function listTemplates(config) {
+  const configTemplates = config.raw?.templates ?? {};
+  const all = { ...BUILTIN_TEMPLATES };
+  for (const [k, v] of Object.entries(configTemplates)) {
+    all[k] = v;
+  }
+
+  process.stdout.write(bold('Available templates') + '\n\n');
+  for (const [name, tmpl] of Object.entries(all)) {
+    const desc = typeof tmpl === 'function'
+      ? '(custom function)'
+      : (tmpl.description ?? '');
+    const source = configTemplates[name] ? dim(' (config)') : '';
+    process.stdout.write(`  ${name}${source}\n`);
+    if (desc) process.stdout.write(`  ${dim(desc)}\n`);
+    process.stdout.write('\n');
+  }
 }

package/src/render.mjs

@@ -143,8 +143,8 @@ function _renderContext(index, config) {
   return `${lines.join('\n').trimEnd()}\n`;
 }
 
-export function renderCheck(index, config) {
-  const defaultRenderer = (idx) => _renderCheck(idx);
+export function renderCheck(index, config, opts = {}) {
+  const defaultRenderer = (idx) => _renderCheck(idx, opts);
   if (config.hooks.renderCheck) {
     try { return config.hooks.renderCheck(index, defaultRenderer); }
     catch (err) { warn(`Hook 'renderCheck' threw: ${err.message}`); }
@@ -152,7 +152,8 @@ export function renderCheck(index, config) {
   return defaultRenderer(index);
 }
 
-function _renderCheck(index) {
+function _renderCheck(index, opts = {}) {
+  const { errorsOnly } = opts;
   const lines = ['Check', ''];
   lines.push(`- docs scanned: ${index.docs.length}`);
   lines.push(`- errors: ${index.errors.length}`);
@@ -167,7 +168,7 @@ function _renderCheck(index) {
     lines.push('');
   }
 
-  if (index.warnings.length > 0) {
+  if (!errorsOnly && index.warnings.length > 0) {
     lines.push(yellow('Warnings'));
     for (const issue of index.warnings) {
       lines.push(`- ${issue.path}: ${issue.message}`);

package/src/validate.mjs

@@ -76,6 +76,14 @@ export function validateDoc(doc, frontmatter, headingTitle, config) {
       }
     }
   }
+
+  // Validate body links resolve to existing files
+  for (const link of (doc.bodyLinks || [])) {
+    const resolved = path.resolve(docDir, link.href);
+    if (!existsSync(resolved)) {
+      doc.warnings.push({ path: doc.path, level: 'warning', message: `body link \`${link.href}\` does not resolve to an existing file.` });
+    }
+  }
 }
 
 export function checkBidirectionalReferences(docs, config) {