dotmd-cli 0.4.0 → 0.6.0

package/bin/dotmd.mjs

@@ -17,6 +17,7 @@ import { runDiff } from '../src/diff.mjs';
 import { runLint } from '../src/lint.mjs';
 import { runRename } from '../src/rename.mjs';
 import { runMigrate } from '../src/migrate.mjs';
+import { runFixRefs, fixBrokenRefs } from '../src/fix-refs.mjs';
 import { die, warn } from '../src/util.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -29,15 +30,16 @@ const HELP = {
 Commands:
   list [--verbose]       List docs grouped by status (default)
   json                   Full index as JSON
-  check                  Validate frontmatter and references
+  check [flags]          Validate frontmatter and references
   coverage [--json]      Metadata coverage report
   context                Compact briefing (LLM-oriented)
   focus [status]         Detailed view for one status group
   query [filters]        Filtered search
   index [--write]        Generate/update docs.md index block
   status <file> <status> Transition document status
-  archive <file>         Archive (status + move + index regen)
+  archive <file>         Archive (status + move + update refs)
   touch <file>           Bump updated date
+  fix-refs               Auto-fix broken reference paths
   lint [--fix]           Check and auto-fix frontmatter issues
   rename <old> <new>     Rename doc and update references
   migrate <f> <old> <new>  Batch update a frontmatter field
@@ -82,10 +84,33 @@ regenerates the index (if configured).
 
 Use --dry-run (-n) to preview changes without writing anything.`,
 
+  check: `dotmd check — validate frontmatter and references
+
+Options:
+  --errors-only          Show only errors, suppress warnings
+  --fix                  Auto-fix broken references and regenerate index`,
+
   archive: `dotmd archive <file> — archive a document
 
-Sets status to 'archived', moves to the archive directory, regenerates
-the index, and scans for stale references.
+Sets status to 'archived', moves to the archive directory, auto-updates
+references in other docs, and regenerates the index.
+
+Use --dry-run (-n) to preview changes without writing anything.`,
+
+  'fix-refs': `dotmd fix-refs — auto-fix broken reference paths
+
+Scans all docs for reference fields that point to non-existent files,
+then attempts to resolve them by matching the basename against all known
+docs. Fixes are applied by rewriting the frontmatter path.
+
+Use --dry-run (-n) to preview changes without writing anything.`,
+
+  touch: `dotmd touch <file> — bump updated date
+       dotmd touch --git  — bulk-sync dates from git history
+
+Without --git, updates a single file's frontmatter updated date to today.
+With --git, scans all docs (or a specific file) and syncs their updated
+date to match the last git commit date, fixing date drift warnings.
 
 Use --dry-run (-n) to preview changes without writing anything.`,
 
@@ -243,6 +268,7 @@ async function main() {
   if (command === 'lint') { runLint(restArgs, config, { dryRun }); return; }
   if (command === 'rename') { runRename(restArgs, config, { dryRun }); return; }
   if (command === 'migrate') { runMigrate(restArgs, config, { dryRun }); return; }
+  if (command === 'fix-refs') { runFixRefs(restArgs, config, { dryRun }); return; }
 
   const index = buildIndex(config);
 
@@ -265,7 +291,29 @@ async function main() {
   }
 
   if (command === 'check') {
-    process.stdout.write(renderCheck(index, config));
+    const fix = args.includes('--fix');
+    const errorsOnly = args.includes('--errors-only');
+
+    if (fix) {
+      // Auto-fix: broken refs, then lint, then rebuild index
+      const refResult = fixBrokenRefs(config, { dryRun, quiet: false });
+      if (!dryRun) {
+        runLint(['--fix'], config, { dryRun });
+      }
+      if (!dryRun && config.indexPath) {
+        const { renderIndexFile: rif, writeIndex: wi } = await import('../src/index-file.mjs');
+        const freshIndex = buildIndex(config);
+        wi(rif(freshIndex, config), config);
+        process.stdout.write('Index regenerated.\n');
+      }
+      // Show remaining issues
+      const freshIndex = buildIndex(config);
+      process.stdout.write('\n' + renderCheck(freshIndex, config, { errorsOnly }));
+      if (freshIndex.errors.length > 0) process.exitCode = 1;
+      return;
+    }
+
+    process.stdout.write(renderCheck(index, config, { errorsOnly }));
     if (index.errors.length > 0) process.exitCode = 1;
     return;
   }
@@ -282,7 +330,6 @@ async function main() {
   if (command === 'index') {
     if (!config.indexPath) {
       die('Index generation is not configured. Add an `index` section to your dotmd.config.mjs.');
-      return;
     }
     const write = args.includes('--write');
     const rendered = renderIndexFile(index, config);
@@ -306,5 +353,6 @@ async function main() {
 }
 
 main().catch(err => {
-  die(err.message);
+  process.stderr.write(`${err.message}\n`);
+  process.exitCode = 1;
 });

package/dotmd.config.example.mjs

@@ -35,7 +35,7 @@ export const lifecycle = {
 
 // Taxonomy validation — set fields to null to skip validation
 export const taxonomy = {
-  surfaces: ['frontend', 'backend', 'mobile', 'docs', 'ops', 'platform'],
+  surfaces: ['web', 'ios', 'android', 'mobile', 'full-stack', 'frontend', 'backend', 'api', 'docs', 'ops', 'platform', 'infra', 'design'],
   moduleRequiredFor: ['active', 'ready', 'planned', 'blocked'],
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Zero-dependency CLI for managing markdown documents with YAML frontmatter — index, query, validate, lifecycle.",
   "type": "module",
   "license": "MIT",

package/src/completions.mjs

@@ -3,7 +3,7 @@ import { die } from './util.mjs';
 const COMMANDS = [
   'list', 'json', 'check', 'coverage', 'context', 'focus', 'query',
   'index', 'status', 'archive', 'touch', 'lint', 'rename', 'migrate',
-  'watch', 'diff', 'init', 'new', 'completions',
+  'fix-refs', 'watch', 'diff', 'init', 'new', 'completions',
 ];
 
 const GLOBAL_FLAGS = ['--config', '--dry-run', '--verbose', '--help', '--version'];
@@ -17,9 +17,12 @@ const COMMAND_FLAGS = {
   coverage: ['--json'],
   new: ['--status', '--title'],
   diff: ['--stat', '--since', '--summarize', '--model'],
+  check: ['--errors-only', '--fix'],
   lint: ['--fix'],
   rename: [],
   migrate: [],
+  'fix-refs': [],
+  touch: ['--git'],
 };
 
 function bashCompletion() {
@@ -90,7 +93,6 @@ export function runCompletions(argv) {
   const shell = argv[0];
   if (!shell) {
     die('Usage: dotmd completions <bash|zsh>');
-    return;
   }
   if (shell === 'bash') {
     process.stdout.write(bashCompletion() + '\n');

package/src/config.mjs

@@ -100,6 +100,15 @@ function validateConfig(userConfig, config, validStatuses, indexPath) {
     }
   }
 
+  // staleDays keys must exist in validStatuses
+  if (config.statuses?.staleDays) {
+    for (const key of Object.keys(config.statuses.staleDays)) {
+      if (!validStatuses.has(key)) {
+        warnings.push(`Config: statuses.staleDays contains unknown status '${key}'.`);
+      }
+    }
+  }
+
   // taxonomy.surfaces must be null or array
   if (config.taxonomy?.surfaces !== undefined && config.taxonomy.surfaces !== null && !Array.isArray(config.taxonomy.surfaces)) {
     warnings.push('Config: taxonomy.surfaces must be null or an array.');
@@ -149,22 +158,6 @@ export async function resolveConfig(cwd, explicitConfigPath) {
       mod = await import(configUrl);
     } catch (err) {
       die('Failed to load config: ' + configPath + '\n' + err.message + '\nRun `dotmd init` to create a starter config.');
-      // Return defaults so caller can still function
-      const defaults = deepMerge(DEFAULTS, {});
-      const defaultStatusOrder = defaults.statuses.order;
-      return {
-        raw: defaults, docsRoot: cwd, repoRoot: cwd, configDir: cwd,
-        configPath: configPath ?? null, configFound: Boolean(configPath),
-        archiveDir: defaults.archiveDir, excludeDirs: new Set(defaults.excludeDirs),
-        docsRootPrefix: '', statusOrder: defaultStatusOrder,
-        validStatuses: new Set(defaultStatusOrder), staleDaysByStatus: {},
-        lifecycle: { archiveStatuses: new Set(defaults.lifecycle.archiveStatuses), skipStaleFor: new Set(defaults.lifecycle.skipStaleFor), skipWarningsFor: new Set(defaults.lifecycle.skipWarningsFor) },
-        validSurfaces: null, moduleRequiredStatuses: new Set(),
-        indexPath: null, indexStartMarker: '<!-- GENERATED:dotmd:start -->', indexEndMarker: '<!-- GENERATED:dotmd:end -->', archivedHighlightLimit: 8,
-        context: defaults.context, display: defaults.display,
-        referenceFields: defaults.referenceFields, presets: defaults.presets, hooks: {},
-        configWarnings: [],
-      };
     }
 
     configDir = path.dirname(configPath);
@@ -189,8 +182,9 @@ export async function resolveConfig(cwd, explicitConfigPath) {
 
   const docsRoot = path.resolve(configDir, config.root);
 
+  const earlyWarnings = [];
   if (!existsSync(docsRoot)) {
-    warn('Docs root does not exist: ' + docsRoot);
+    earlyWarnings.push('Config: docs root does not exist: ' + docsRoot);
   }
 
   // Find repo root by walking up looking for .git
@@ -233,7 +227,7 @@ export async function resolveConfig(cwd, explicitConfigPath) {
   const skipStaleFor = new Set(lifecycle.skipStaleFor);
   const skipWarningsFor = new Set(lifecycle.skipWarningsFor);
 
-  const configWarnings = validateConfig(userConfig, config, validStatuses, indexPath);
+  const configWarnings = [...earlyWarnings, ...validateConfig(userConfig, config, validStatuses, indexPath)];
 
   return {
     raw: config,

package/src/diff.mjs

@@ -27,7 +27,6 @@ export function runDiff(argv, config) {
     const filePath = resolveDocPath(file, config);
     if (!filePath) {
       die(`File not found: ${file}\nSearched: ${toRepoPath(config.repoRoot, config.repoRoot) || '.'}, ${toRepoPath(config.docsRoot, config.repoRoot)}`);
-      return;
     }
 
     const raw = readFileSync(filePath, 'utf8');
@@ -37,7 +36,6 @@ export function runDiff(argv, config) {
 
     if (!since) {
       die(`No updated date found in ${file} and no --since provided.`);
-      return;
     }
 
     const relPath = toRepoPath(filePath, config.repoRoot);
@@ -80,9 +78,15 @@ function printFileDiff(relPath, since, diffOutput, opts) {
   process.stdout.write(bold(relPath) + dim(` (updated: ${since})`) + '\n');
 
   if (opts.summarize) {
-    const summary = opts.config?.hooks?.summarizeDiff
-      ? opts.config.hooks.summarizeDiff(diffOutput, relPath)
-      : summarizeWithMLX(diffOutput, relPath, opts.model);
+    let summary;
+    try {
+      summary = opts.config?.hooks?.summarizeDiff
+        ? opts.config.hooks.summarizeDiff(diffOutput, relPath)
+        : summarizeWithMLX(diffOutput, relPath, opts.model);
+    } catch (err) {
+      warn(`Hook 'summarizeDiff' threw: ${err.message}`);
+      summary = null;
+    }
     if (summary) {
       process.stdout.write(dim(`  Summary: ${summary}`) + '\n');
     } else {
@@ -95,6 +99,12 @@ function printFileDiff(relPath, since, diffOutput, opts) {
 }
 
 function summarizeWithMLX(diffText, filePath, model) {
+  const uvCheck = spawnSync('uv', ['--version'], { encoding: 'utf8' });
+  if (uvCheck.error) {
+    warn('uv is not installed. Install it to enable --summarize: https://docs.astral.sh/uv/');
+    return null;
+  }
+
   const prompt = `Summarize this git diff in 1-2 sentences. Focus on what changed semantically, not line counts.\n\nFile: ${filePath}\n\n${diffText.slice(0, 4000)}`;
 
   const result = spawnSync('uv', [

package/src/fix-refs.mjs

@@ -0,0 +1,113 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { extractFrontmatter, replaceFrontmatter } from './frontmatter.mjs';
+import { toRepoPath, warn } from './util.mjs';
+import { buildIndex, collectDocFiles } from './index.mjs';
+import { green, dim, yellow } from './color.mjs';
+
+export function runFixRefs(argv, config, opts = {}) {
+  const { dryRun } = opts;
+  const result = fixBrokenRefs(config, { dryRun });
+  if (result.totalFixed === 0 && result.unfixableCount === 0) {
+    process.stdout.write(green('No broken references found.') + '\n');
+  }
+}
+
+/**
+ * Core logic for fixing broken references. Returns { totalFixed, unfixableCount }.
+ * Shared by `dotmd fix-refs` and `dotmd check --fix`.
+ */
+export function fixBrokenRefs(config, opts = {}) {
+  const { dryRun, quiet } = opts;
+  const index = buildIndex(config);
+  const allFiles = collectDocFiles(config);
+
+  // Build a map of basename → absolute path for all docs
+  const basenameMap = new Map();
+  const duplicateBasenames = new Set();
+  for (const filePath of allFiles) {
+    const basename = path.basename(filePath);
+    if (basenameMap.has(basename)) {
+      duplicateBasenames.add(basename);
+    } else {
+      basenameMap.set(basename, filePath);
+    }
+  }
+
+  // Find broken ref errors
+  const brokenRefErrors = index.errors.filter(e =>
+    e.message.includes('does not resolve to an existing file')
+  );
+
+  if (brokenRefErrors.length === 0) {
+    return { totalFixed: 0, unfixableCount: 0 };
+  }
+
+  // Group fixes by doc path
+  const fixesByDoc = new Map();
+  let unfixableCount = 0;
+
+  for (const err of brokenRefErrors) {
+    const match = err.message.match(/entry `([^`]+)` does not resolve/);
+    if (!match) { unfixableCount++; continue; }
+
+    const brokenRef = match[1];
+    const brokenBasename = path.basename(brokenRef);
+
+    if (duplicateBasenames.has(brokenBasename)) {
+      unfixableCount++;
+      continue;
+    }
+
+    const resolved = basenameMap.get(brokenBasename);
+    if (!resolved) { unfixableCount++; continue; }
+
+    const docAbsPath = path.join(config.repoRoot, err.path);
+    const docDir = path.dirname(docAbsPath);
+    const correctRelPath = path.relative(docDir, resolved).split(path.sep).join('/');
+
+    if (correctRelPath === brokenRef) { unfixableCount++; continue; }
+
+    if (!fixesByDoc.has(err.path)) {
+      fixesByDoc.set(err.path, []);
+    }
+    fixesByDoc.get(err.path).push({ brokenRef, correctRelPath });
+  }
+
+  const prefix = dryRun ? dim('[dry-run] ') : '';
+  let totalFixed = 0;
+
+  for (const [docPath, fixes] of fixesByDoc) {
+    const absPath = path.join(config.repoRoot, docPath);
+    let raw = readFileSync(absPath, 'utf8');
+    const { frontmatter: fm } = extractFrontmatter(raw);
+    if (!fm) continue;
+
+    let newFm = fm;
+    for (const { brokenRef, correctRelPath } of fixes) {
+      newFm = newFm.split(brokenRef).join(correctRelPath);
+    }
+
+    if (newFm !== fm && !dryRun) {
+      raw = replaceFrontmatter(raw, newFm);
+      writeFileSync(absPath, raw, 'utf8');
+    }
+
+    if (!quiet) {
+      process.stdout.write(`${prefix}${green('Fixed')}: ${docPath} (${fixes.length} ref${fixes.length > 1 ? 's' : ''})\n`);
+      for (const { brokenRef, correctRelPath } of fixes) {
+        process.stdout.write(`${prefix}  ${dim(`${brokenRef} → ${correctRelPath}`)}\n`);
+      }
+    }
+    totalFixed += fixes.length;
+  }
+
+  if (!quiet) {
+    process.stdout.write(`\n${prefix}${totalFixed} reference${totalFixed !== 1 ? 's' : ''} fixed across ${fixesByDoc.size} file(s).\n`);
+    if (unfixableCount > 0) {
+      process.stdout.write(`${yellow(`${unfixableCount} broken reference(s) could not be auto-resolved`)} (file not found by basename).\n`);
+    }
+  }
+
+  return { totalFixed, unfixableCount };
+}

package/src/frontmatter.mjs

@@ -14,6 +14,14 @@ export function extractFrontmatter(raw) {
   };
 }
 
+export function replaceFrontmatter(raw, newFrontmatter) {
+  if (!raw.startsWith('---\n')) return raw;
+  const endMarker = raw.indexOf('\n---\n', 4);
+  if (endMarker === -1) return raw;
+  const body = raw.slice(endMarker + 5);
+  return `---\n${newFrontmatter}\n---\n${body}`;
+}
+
 export function parseSimpleFrontmatter(text) {
   const data = {};
   let currentArrayKey = null;
@@ -25,6 +33,10 @@ export function parseSimpleFrontmatter(text) {
     const keyMatch = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
     if (keyMatch) {
       const [, key, rawValue] = keyMatch;
+      if (Object.prototype.hasOwnProperty.call(data, key)) {
+        currentArrayKey = null;
+        continue;
+      }
       if (!rawValue.trim()) {
         data[key] = [];
         currentArrayKey = key;
@@ -48,7 +60,12 @@ export function parseSimpleFrontmatter(text) {
 }
 
 function parseScalar(value) {
-  const unquoted = value.replace(/^['"]|['"]$/g, '');
+  let unquoted = value;
+  if (value.length > 1 &&
+      ((value.startsWith("'") && value.endsWith("'")) ||
+       (value.startsWith('"') && value.endsWith('"')))) {
+    unquoted = value.slice(1, -1);
+  }
   if (unquoted === 'true') return true;
   if (unquoted === 'false') return false;
   return unquoted;

package/src/git.mjs

@@ -1,15 +1,26 @@
 import { spawnSync } from 'node:child_process';
 
+let gitChecked = false;
+function ensureGit() {
+  if (gitChecked) return;
+  const result = spawnSync('git', ['--version'], { encoding: 'utf8' });
+  if (result.error) {
+    throw new Error('git is not installed or not found in PATH. dotmd requires git for this operation.');
+  }
+  gitChecked = true;
+}
+
 export function getGitLastModified(relPath, repoRoot) {
   const result = spawnSync('git', ['log', '-1', '--format=%aI', '--', relPath], {
     cwd: repoRoot,
     encoding: 'utf8',
   });
-  if (result.status !== 0 || !result.stdout.trim()) return null;
+  if (result.error || result.status !== 0 || !result.stdout.trim()) return null;
   return result.stdout.trim();
 }
 
 export function gitMv(source, target, repoRoot) {
+  ensureGit();
   const result = spawnSync('git', ['mv', source, target], {
     cwd: repoRoot,
     encoding: 'utf8',
@@ -18,6 +29,7 @@ export function gitMv(source, target, repoRoot) {
 }
 
 export function gitDiffSince(relPath, sinceDate, repoRoot, opts = {}) {
+  ensureGit();
   // Find the last commit at or before sinceDate
   const baseline = spawnSync('git', [
     'log', '-1', '--before=' + sinceDate + 'T23:59:59', '--format=%H', '--', relPath

package/src/index.mjs

@@ -2,7 +2,7 @@ import { readdirSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { extractFirstHeading, extractSummary, extractStatusSnapshot, extractNextStep, extractChecklistCounts } from './extractors.mjs';
-import { asString, normalizeStringList, normalizeBlockers, mergeUniqueStrings, toRepoPath } from './util.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';
 
@@ -19,20 +19,32 @@ export function buildIndex(config) {
   if (config.hooks.validate) {
     const ctx = { config, allDocs: docs, repoRoot: config.repoRoot };
     for (const doc of docs) {
-      const result = config.hooks.validate(doc, ctx);
-      if (result?.errors) {
-        doc.errors.push(...result.errors);
-        errors.push(...result.errors);
-      }
-      if (result?.warnings) {
-        doc.warnings.push(...result.warnings);
-        warnings.push(...result.warnings);
+      try {
+        const result = config.hooks.validate(doc, ctx);
+        if (result?.errors) {
+          doc.errors.push(...result.errors);
+          errors.push(...result.errors);
+        }
+        if (result?.warnings) {
+          doc.warnings.push(...result.warnings);
+          warnings.push(...result.warnings);
+        }
+      } catch (err) {
+        const hookError = { path: doc.path, level: 'error', message: `Hook 'validate' threw: ${err.message}` };
+        doc.errors.push(hookError);
+        errors.push(hookError);
       }
     }
   }
 
   const transformedDocs = config.hooks.transformDoc
-    ? docs.map(d => config.hooks.transformDoc(d) ?? d)
+    ? docs.map(d => {
+        try { return config.hooks.transformDoc(d) ?? d; }
+        catch (err) {
+          warnings.push({ path: d.path, level: 'warning', message: `Hook 'transformDoc' threw: ${err.message}` });
+          return d;
+        }
+      })
     : docs;
 
   const countsByStatus = Object.fromEntries(config.statusOrder.map(status => [

package/src/lifecycle.mjs

@@ -1,22 +1,22 @@
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
-import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
-import { asString, toRepoPath, die, resolveDocPath } from './util.mjs';
-import { gitMv } from './git.mjs';
+import { extractFrontmatter, parseSimpleFrontmatter, replaceFrontmatter } from './frontmatter.mjs';
+import { asString, toRepoPath, die, warn, resolveDocPath, escapeRegex } from './util.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;
   const input = argv[0];
   const newStatus = argv[1];
 
-  if (!input || !newStatus) { die('Usage: dotmd status <file> <new-status>'); return; }
-  if (!config.validStatuses.has(newStatus)) { die(`Invalid status: ${newStatus}\nValid: ${[...config.validStatuses].join(', ')}`); return; }
+  if (!input || !newStatus) { die('Usage: dotmd status <file> <new-status>'); }
+  if (!config.validStatuses.has(newStatus)) { die(`Invalid status: ${newStatus}\nValid: ${[...config.validStatuses].join(', ')}`); }
 
   const filePath = resolveDocPath(input, config);
-  if (!filePath) { die(`File not found: ${input}\nSearched: ${toRepoPath(config.repoRoot, config.repoRoot) || '.'}, ${toRepoPath(config.docsRoot, config.repoRoot)}`); return; }
+  if (!filePath) { die(`File not found: ${input}\nSearched: ${toRepoPath(config.repoRoot, config.repoRoot) || '.'}, ${toRepoPath(config.docsRoot, config.repoRoot)}`); }
 
   const raw = readFileSync(filePath, 'utf8');
   const { frontmatter } = extractFrontmatter(raw);
@@ -57,18 +57,19 @@ export function runStatus(argv, config, opts = {}) {
   updateFrontmatter(filePath, { status: newStatus, updated: today });
 
   if (isArchiving) {
+    mkdirSync(archiveDir, { recursive: true });
     const targetPath = path.join(archiveDir, path.basename(filePath));
-    if (existsSync(targetPath)) { die(`Target already exists: ${toRepoPath(targetPath, config.repoRoot)}`); return; }
+    if (existsSync(targetPath)) { die(`Target already exists: ${toRepoPath(targetPath, config.repoRoot)}`); }
     const result = gitMv(filePath, targetPath, config.repoRoot);
-    if (result.status !== 0) { die(result.stderr || 'git mv failed.'); return; }
+    if (result.status !== 0) { die(result.stderr || 'git mv failed.'); }
     finalPath = targetPath;
   }
 
   if (isUnarchiving) {
     const targetPath = path.join(config.docsRoot, path.basename(filePath));
-    if (existsSync(targetPath)) { die(`Target already exists: ${toRepoPath(targetPath, config.repoRoot)}`); return; }
+    if (existsSync(targetPath)) { die(`Target already exists: ${toRepoPath(targetPath, config.repoRoot)}`); }
     const result = gitMv(filePath, targetPath, config.repoRoot);
-    if (result.status !== 0) { die(result.stderr || 'git mv failed.'); return; }
+    if (result.status !== 0) { die(result.stderr || 'git mv failed.'); }
     finalPath = targetPath;
   }
 
@@ -79,21 +80,21 @@ export function runStatus(argv, config, opts = {}) {
 
   process.stdout.write(`${green(toRepoPath(finalPath, config.repoRoot))}: ${oldStatus ?? 'unknown'} → ${newStatus}\n`);
 
-  config.hooks.onStatusChange?.({ path: toRepoPath(finalPath, config.repoRoot), oldStatus, newStatus }, {
+  try { config.hooks.onStatusChange?.({ path: toRepoPath(finalPath, config.repoRoot), oldStatus, newStatus }, {
     oldPath: toRepoPath(filePath, config.repoRoot),
     newPath: toRepoPath(finalPath, config.repoRoot),
-  });
+  }); } catch (err) { warn(`Hook 'onStatusChange' threw: ${err.message}`); }
 }
 
 export function runArchive(argv, config, opts = {}) {
   const { dryRun } = opts;
   const input = argv[0];
 
-  if (!input) { die('Usage: dotmd archive <file>'); return; }
+  if (!input) { die('Usage: dotmd archive <file>'); }
 
   const filePath = resolveDocPath(input, config);
-  if (!filePath) { die(`File not found: ${input}\nSearched: ${toRepoPath(config.repoRoot, config.repoRoot) || '.'}, ${toRepoPath(config.docsRoot, config.repoRoot)}`); return; }
-  if (filePath.includes(`/${config.archiveDir}/`)) { die(`Already archived: ${toRepoPath(filePath, config.repoRoot)}`); return; }
+  if (!filePath) { die(`File not found: ${input}\nSearched: ${toRepoPath(config.repoRoot, config.repoRoot) || '.'}, ${toRepoPath(config.docsRoot, config.repoRoot)}`); }
+  if (filePath.includes(`/${config.archiveDir}/`)) { die(`Already archived: ${toRepoPath(filePath, config.repoRoot)}`); }
 
   const raw = readFileSync(filePath, 'utf8');
   const { frontmatter } = extractFrontmatter(raw);
@@ -109,34 +110,28 @@ export function runArchive(argv, config, opts = {}) {
   if (dryRun) {
     const prefix = dim('[dry-run]');
     process.stdout.write(`${prefix} Would update frontmatter: status: ${oldStatus} → archived, updated: ${today}\n`);
-    if (existsSync(targetPath)) { die(`Target already exists: ${toRepoPath(targetPath, config.repoRoot)}`); return; }
+    if (existsSync(targetPath)) { die(`Target already exists: ${toRepoPath(targetPath, config.repoRoot)}`); }
     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;
   }
 
   updateFrontmatter(filePath, { status: 'archived', updated: today });
 
-  if (existsSync(targetPath)) { die(`Target already exists: ${toRepoPath(targetPath, config.repoRoot)}`); return; }
+  mkdirSync(targetDir, { recursive: true });
+  if (existsSync(targetPath)) { die(`Target already exists: ${toRepoPath(targetPath, config.repoRoot)}`); }
 
   const result = gitMv(filePath, targetPath, config.repoRoot);
-  if (result.status !== 0) { die(result.stderr || 'git mv failed.'); return; }
+  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);
@@ -144,36 +139,72 @@ export function runArchive(argv, config, opts = {}) {
   }
 
   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');
-  config.hooks.onArchive?.({ path: newRepoPath, oldStatus }, { oldPath: oldRepoPath, newPath: newRepoPath });
+  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>'); return; }
+  // --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)}`); return; }
+  if (!filePath) { die(`File not found: ${input}\nSearched: ${toRepoPath(config.repoRoot, config.repoRoot) || '.'}, ${toRepoPath(config.docsRoot, config.repoRoot)}`); }
 
   const today = new Date().toISOString().slice(0, 10);
 
@@ -185,7 +216,70 @@ export function runTouch(argv, config, opts = {}) {
   updateFrontmatter(filePath, { updated: today });
   process.stdout.write(`${green('Touched')}: ${toRepoPath(filePath, config.repoRoot)} (updated → ${today})\n`);
 
-  config.hooks.onTouch?.({ path: toRepoPath(filePath, config.repoRoot) }, { path: toRepoPath(filePath, config.repoRoot), date: today });
+  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) {
@@ -199,7 +293,7 @@ export function updateFrontmatter(filePath, updates) {
   const body = raw.slice(endMarker + 5);
 
   for (const [key, value] of Object.entries(updates)) {
-    const regex = new RegExp(`^${key}:.*$`, 'm');
+    const regex = new RegExp(`^${escapeRegex(key)}:.*$`, 'm');
     if (regex.test(frontmatter)) {
       frontmatter = frontmatter.replace(regex, `${key}: ${value}`);
     } else {

package/src/lint.mjs

@@ -1,6 +1,6 @@
 import { readFileSync, writeFileSync } from 'node:fs';
-import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
-import { asString, toRepoPath } from './util.mjs';
+import { extractFrontmatter, parseSimpleFrontmatter, replaceFrontmatter } from './frontmatter.mjs';
+import { asString, toRepoPath, escapeRegex, warn } from './util.mjs';
 import { buildIndex, collectDocFiles } from './index.mjs';
 import { updateFrontmatter } from './lifecycle.mjs';
 import { bold, green, yellow, dim } from './color.mjs';
@@ -132,7 +132,7 @@ export function runLint(argv, config, opts = {}) {
         const { frontmatter: fm } = extractFrontmatter(raw);
         let newFm = fm;
         for (const kr of keyRenames) {
-          const regex = new RegExp(`^${kr.oldValue}:`, 'm');
+          const regex = new RegExp(`^${escapeRegex(kr.oldValue)}:`, 'm');
           newFm = newFm.replace(regex, `${kr.newValue}:`);
         }
         for (const tf of trimFixes) {
@@ -140,7 +140,7 @@ export function runLint(argv, config, opts = {}) {
           newFm = newFm.replace(regex, `$1${tf.newValue}`);
         }
         if (newFm !== fm) {
-          raw = raw.replace(`---\n${fm}\n---`, `---\n${newFm}\n---`);
+          raw = replaceFrontmatter(raw, newFm);
           writeFileSync(filePath, raw, 'utf8');
         }
       }
@@ -174,13 +174,10 @@ export function runLint(argv, config, opts = {}) {
     totalFixes += fixes.length;
 
     if (!dryRun) {
-      config.hooks.onLint?.({ path: repoPath, fixes });
+      try { config.hooks.onLint?.({ path: repoPath, fixes }); } catch (err) { warn(`Hook 'onLint' threw: ${err.message}`); }
     }
   }
 
   process.stdout.write(`\n${prefix}${totalFixes} fix${totalFixes !== 1 ? 'es' : ''} applied across ${fixable.length} file(s).\n`);
 }
 
-function escapeRegex(str) {
-  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}

package/src/migrate.mjs

@@ -21,7 +21,6 @@ export function runMigrate(argv, config, opts = {}) {
 
   if (!field || !oldValue || !newValue) {
     die('Usage: dotmd migrate <field> <old-value> <new-value>');
-    return;
   }
 
   const allFiles = collectDocFiles(config);

package/src/new.mjs

@@ -1,6 +1,6 @@
 import { existsSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
-import { toRepoPath, die } from './util.mjs';
+import { toRepoPath, die, warn } from './util.mjs';
 import { green, dim } from './color.mjs';
 
 export function runNew(argv, config, opts = {}) {
@@ -17,17 +17,16 @@ export function runNew(argv, config, opts = {}) {
   }
 
   const name = positional[0];
-  if (!name) { die('Usage: dotmd new <name> [--status <s>] [--title <t>]'); return; }
+  if (!name) { die('Usage: dotmd new <name> [--status <s>] [--title <t>]'); }
 
   // Validate status
   if (!config.validStatuses.has(status)) {
     die(`Invalid status: ${status}\nValid: ${[...config.validStatuses].join(', ')}`);
-    return;
   }
 
   // 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); return; }
+  if (!slug) { die('Name resolves to empty slug: ' + name); }
 
   // Title
   const docTitle = title ?? name.replace(/[-_]/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
@@ -38,7 +37,6 @@ export function runNew(argv, config, opts = {}) {
 
   if (existsSync(filePath)) {
     die(`File already exists: ${repoPath}`);
-    return;
   }
 
   if (dryRun) {
@@ -52,5 +50,5 @@ export function runNew(argv, config, opts = {}) {
   writeFileSync(filePath, content, 'utf8');
   process.stdout.write(`${green('Created')}: ${repoPath}\n`);
 
-  config.hooks.onNew?.({ path: repoPath, status, title: docTitle });
+  try { config.hooks.onNew?.({ path: repoPath, status, title: docTitle }); } catch (err) { warn(`Hook 'onNew' threw: ${err.message}`); }
 }

package/src/rename.mjs

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
-import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
+import { extractFrontmatter, parseSimpleFrontmatter, replaceFrontmatter } from './frontmatter.mjs';
 import { toRepoPath, resolveDocPath, die, warn } from './util.mjs';
 import { collectDocFiles } from './index.mjs';
 import { gitMv } from './git.mjs';
@@ -21,14 +21,12 @@ export function runRename(argv, config, opts = {}) {
 
   if (!oldInput || !newInput) {
     die('Usage: dotmd rename <old> <new>');
-    return;
   }
 
   // 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)}`);
-    return;
   }
 
   // Compute new path in same directory as old
@@ -109,7 +107,6 @@ export function runRename(argv, config, opts = {}) {
   const result = gitMv(oldPath, newPath, config.repoRoot);
   if (result.status !== 0) {
     die(result.stderr || 'git mv failed.');
-    return;
   }
 
   // Update references in frontmatter of other docs
@@ -127,7 +124,7 @@ export function runRename(argv, config, opts = {}) {
     }).join('\n');
 
     if (newFm !== fm) {
-      raw = raw.replace(`---\n${fm}\n---`, `---\n${newFm}\n---`);
+      raw = replaceFrontmatter(raw, newFm);
       writeFileSync(filePath, raw, 'utf8');
       updatedCount++;
     }
@@ -145,5 +142,5 @@ export function runRename(argv, config, opts = {}) {
     }
   }
 
-  config.hooks.onRename?.({ oldPath: oldRepoPath, newPath: newRepoPath, referencesUpdated: updatedCount });
+  try { config.hooks.onRename?.({ oldPath: oldRepoPath, newPath: newRepoPath, referencesUpdated: updatedCount }); } catch (err) { warn(`Hook 'onRename' threw: ${err.message}`); }
 }

package/src/render.mjs

@@ -1,10 +1,11 @@
-import { capitalize, toSlug, truncate } from './util.mjs';
+import { capitalize, toSlug, truncate, warn } from './util.mjs';
 import { bold, red, yellow, green } from './color.mjs';
 
 export function renderCompactList(index, config) {
   const defaultRenderer = (idx) => _renderCompactList(idx, config);
   if (config.hooks.renderCompactList) {
-    return config.hooks.renderCompactList(index, defaultRenderer);
+    try { return config.hooks.renderCompactList(index, defaultRenderer); }
+    catch (err) { warn(`Hook 'renderCompactList' threw: ${err.message}`); }
   }
   return defaultRenderer(index);
 }
@@ -63,7 +64,8 @@ export function renderVerboseList(index, config) {
 export function renderContext(index, config) {
   const defaultRenderer = (idx) => _renderContext(idx, config);
   if (config.hooks.renderContext) {
-    return config.hooks.renderContext(index, defaultRenderer);
+    try { return config.hooks.renderContext(index, defaultRenderer); }
+    catch (err) { warn(`Hook 'renderContext' threw: ${err.message}`); }
   }
   return defaultRenderer(index);
 }
@@ -141,15 +143,17 @@ 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) {
-    return config.hooks.renderCheck(index, defaultRenderer);
+    try { return config.hooks.renderCheck(index, defaultRenderer); }
+    catch (err) { warn(`Hook 'renderCheck' threw: ${err.message}`); }
   }
   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}`);
@@ -164,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}`);
@@ -234,7 +238,8 @@ export function renderProgressBar(checklist) {
 export function formatSnapshot(doc, config) {
   const defaultFormatter = (d) => _formatSnapshot(d);
   if (config.hooks.formatSnapshot) {
-    return config.hooks.formatSnapshot(doc, defaultFormatter);
+    try { return config.hooks.formatSnapshot(doc, defaultFormatter); }
+    catch (err) { warn(`Hook 'formatSnapshot' threw: ${err.message}`); }
   }
   return defaultFormatter(doc);
 }

package/src/util.mjs

@@ -47,6 +47,10 @@ export function mergeUniqueStrings(...lists) {
   return [...new Set(lists.flat().filter(Boolean))];
 }
 
+export function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
 export function toRepoPath(absolutePath, repoRoot) {
   return path.relative(repoRoot, absolutePath).split(path.sep).join('/');
 }
@@ -55,9 +59,15 @@ export function warn(message) {
   process.stderr.write(`${dim(message)}\n`);
 }
 
+export class DotmdError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'DotmdError';
+  }
+}
+
 export function die(message) {
-  process.stderr.write(`${message}\n`);
-  process.exitCode = 1;
+  throw new DotmdError(message);
 }
 
 export function resolveDocPath(input, config) {