dotmd-cli 0.3.0 → 0.4.0

package/README.md

@@ -83,6 +83,9 @@ dotmd index [--write]        Generate/update docs.md index block
 dotmd status <file> <status> Transition document status
 dotmd archive <file>         Archive (status + move + index regen)
 dotmd touch <file>           Bump updated date
+dotmd lint [--fix]           Check and auto-fix frontmatter issues
+dotmd rename <old> <new>     Rename doc and update references
+dotmd migrate <f> <old> <new>  Batch update a frontmatter field
 dotmd watch [command]        Re-run a command on file changes
 dotmd diff [file]            Show changes since last updated date
 dotmd new <name>             Create a new document with frontmatter
@@ -133,6 +136,44 @@ export const presets = {
 
 Then run `dotmd stale` or `dotmd mine` as shorthand.
 
+### Lint
+
+Check docs for fixable frontmatter issues and optionally auto-fix them:
+
+```bash
+dotmd lint                   # report issues
+dotmd lint --fix             # fix all issues
+dotmd lint --fix --dry-run   # preview fixes without writing
+```
+
+Detected issues:
+- Missing `updated` date on non-archived docs
+- Status casing mismatch (e.g., `Active` → `active`)
+- camelCase frontmatter keys (e.g., `nextStep` → `next_step`)
+- Trailing whitespace in frontmatter values
+- Missing newline at end of file
+
+### Rename
+
+Rename a document and update all frontmatter references across your docs:
+
+```bash
+dotmd rename old-name.md new-name        # renames + updates refs
+dotmd rename old-name.md new-name -n     # preview without writing
+```
+
+Uses `git mv` for the rename and scans all reference fields for the old filename. Body markdown links are warned about but not auto-fixed.
+
+### Migrate
+
+Batch update a frontmatter field value across all docs:
+
+```bash
+dotmd migrate status research exploration   # rename a status
+dotmd migrate module auth identity          # rename a module
+dotmd migrate module auth identity -n       # preview
+```
+
 ### Watch Mode
 
 ```bash
@@ -231,7 +272,18 @@ export function onStatusChange(doc, { oldStatus, newStatus }) {
 }
 ```
 
-Available: `onArchive`, `onStatusChange`, `onTouch`.
+Available: `onArchive`, `onStatusChange`, `onTouch`, `onNew`, `onRename`, `onLint`.
+
+### Summarize Hook
+
+Override the diff summarizer (replaces the default MLX model call):
+
+```js
+export function summarizeDiff(diffOutput, filePath) {
+  // call your preferred LLM, return a string summary
+  return `Changes in ${filePath}: ...`;
+}
+```
 
 ## Features
 

package/bin/dotmd.mjs

@@ -14,6 +14,9 @@ import { runNew } from '../src/new.mjs';
 import { runCompletions } from '../src/completions.mjs';
 import { runWatch } from '../src/watch.mjs';
 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 { die, warn } from '../src/util.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -35,6 +38,9 @@ Commands:
   status <file> <status> Transition document status
   archive <file>         Archive (status + move + index regen)
   touch <file>           Bump updated date
+  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
   watch [command]       Re-run a command on file changes
   diff [file]           Show changes since last updated date
   new <name>             Create a new document with frontmatter
@@ -122,6 +128,33 @@ Options:
   --summarize            Generate AI summary using local MLX model
   --model <name>         MLX model to use (default: mlx-community/Llama-3.2-3B-Instruct-4bit)`,
 
+  lint: `dotmd lint [--fix] — check and auto-fix frontmatter issues
+
+Scans all docs for fixable problems: missing updated dates, status casing,
+camelCase key names, trailing whitespace in values, missing EOF newline.
+
+Without --fix, reports all issues. With --fix, applies fixes in place.
+Use --dry-run (-n) with --fix to preview without writing anything.`,
+
+  rename: `dotmd rename <old> <new> — rename doc and update references
+
+Renames a document using git mv and updates all frontmatter references
+in other docs that point to the old filename.
+
+Body markdown links are warned about but not auto-fixed.
+Use --dry-run (-n) to preview changes without writing anything.`,
+
+  migrate: `dotmd migrate <field> <old-value> <new-value> — batch update a frontmatter field
+
+Finds all docs where the given field equals old-value and updates it
+to new-value.
+
+Examples:
+  dotmd migrate status research exploration
+  dotmd migrate module auth identity
+
+Use --dry-run (-n) to preview changes without writing anything.`,
+
   init: `dotmd init — create starter config and docs directory
 
 Creates dotmd.config.mjs, docs/, and docs/docs.md in the current
@@ -179,6 +212,12 @@ async function main() {
     warn('No dotmd config found — using defaults. Run `dotmd init` to create one.');
   }
 
+  if (config.configWarnings && config.configWarnings.length > 0) {
+    for (const w of config.configWarnings) {
+      warn(w);
+    }
+  }
+
   if (verbose) {
     process.stderr.write(`Config: ${config.configPath ?? 'none'}\n`);
     process.stderr.write(`Docs root: ${config.docsRoot}\n`);
@@ -201,6 +240,9 @@ async function main() {
   if (command === 'archive') { runArchive(restArgs, config, { dryRun }); return; }
   if (command === 'touch') { runTouch(restArgs, config, { dryRun }); return; }
   if (command === 'new') { runNew(restArgs, config, { dryRun }); return; }
+  if (command === 'lint') { runLint(restArgs, config, { dryRun }); return; }
+  if (command === 'rename') { runRename(restArgs, config, { dryRun }); return; }
+  if (command === 'migrate') { runMigrate(restArgs, config, { dryRun }); return; }
 
   const index = buildIndex(config);
 

package/package.json

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

package/src/completions.mjs

@@ -2,7 +2,8 @@ import { die } from './util.mjs';
 
 const COMMANDS = [
   'list', 'json', 'check', 'coverage', 'context', 'focus', 'query',
-  'index', 'status', 'archive', 'touch', 'watch', 'diff', 'init', 'new', 'completions',
+  'index', 'status', 'archive', 'touch', 'lint', 'rename', 'migrate',
+  'watch', 'diff', 'init', 'new', 'completions',
 ];
 
 const GLOBAL_FLAGS = ['--config', '--dry-run', '--verbose', '--help', '--version'];
@@ -16,6 +17,9 @@ const COMMAND_FLAGS = {
   coverage: ['--json'],
   new: ['--status', '--title'],
   diff: ['--stat', '--since', '--summarize', '--model'],
+  lint: ['--fix'],
+  rename: [],
+  migrate: [],
 };
 
 function bashCompletion() {

package/src/config.mjs

@@ -76,6 +76,50 @@ function findConfigFile(startDir) {
   return null;
 }
 
+const VALID_CONFIG_KEYS = new Set(Object.keys(DEFAULTS));
+
+function validateConfig(userConfig, config, validStatuses, indexPath) {
+  const warnings = [];
+
+  // statuses.order must be array
+  if (config.statuses && config.statuses.order !== undefined && !Array.isArray(config.statuses.order)) {
+    warnings.push('Config: statuses.order must be an array.');
+  }
+
+  // archiveDir must be string
+  if (config.archiveDir !== undefined && typeof config.archiveDir !== 'string') {
+    warnings.push('Config: archiveDir must be a string.');
+  }
+
+  // lifecycle.archiveStatuses values must exist in validStatuses
+  if (config.lifecycle?.archiveStatuses) {
+    for (const s of config.lifecycle.archiveStatuses) {
+      if (!validStatuses.has(s)) {
+        warnings.push(`Config: lifecycle.archiveStatuses contains unknown status '${s}'.`);
+      }
+    }
+  }
+
+  // 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.');
+  }
+
+  // index path file exists (if configured)
+  if (indexPath && !existsSync(indexPath)) {
+    warnings.push(`Config: index path does not exist: ${indexPath}`);
+  }
+
+  // Unknown top-level user config keys
+  for (const key of Object.keys(userConfig)) {
+    if (!VALID_CONFIG_KEYS.has(key)) {
+      warnings.push(`Config: unknown key '${key}'.`);
+    }
+  }
+
+  return warnings;
+}
+
 function deepMerge(defaults, overrides) {
   const result = { ...defaults };
   for (const [key, value] of Object.entries(overrides)) {
@@ -119,6 +163,7 @@ export async function resolveConfig(cwd, explicitConfigPath) {
         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: [],
       };
     }
 
@@ -188,6 +233,8 @@ 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);
+
   return {
     raw: config,
 
@@ -219,5 +266,6 @@ export async function resolveConfig(cwd, explicitConfigPath) {
     referenceFields: config.referenceFields,
     presets: config.presets,
     hooks,
+    configWarnings,
   };
 }

package/src/diff.mjs

@@ -80,7 +80,9 @@ function printFileDiff(relPath, since, diffOutput, opts) {
   process.stdout.write(bold(relPath) + dim(` (updated: ${since})`) + '\n');
 
   if (opts.summarize) {
-    const summary = summarizeWithMLX(diffOutput, relPath, opts.model);
+    const summary = opts.config?.hooks?.summarizeDiff
+      ? opts.config.hooks.summarizeDiff(diffOutput, relPath)
+      : summarizeWithMLX(diffOutput, relPath, opts.model);
     if (summary) {
       process.stdout.write(dim(`  Summary: ${summary}`) + '\n');
     } else {

package/src/lint.mjs

@@ -0,0 +1,186 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
+import { asString, toRepoPath } from './util.mjs';
+import { buildIndex, collectDocFiles } from './index.mjs';
+import { updateFrontmatter } from './lifecycle.mjs';
+import { bold, green, yellow, dim } from './color.mjs';
+
+const KEY_RENAMES = {
+  nextStep: 'next_step',
+  currentState: 'current_state',
+  auditLevel: 'audit_level',
+  sourceOfTruth: 'source_of_truth',
+  relatedPlans: 'related_plans',
+  supportsPlans: 'supports_plans',
+};
+
+export function runLint(argv, config, opts = {}) {
+  const { dryRun } = opts;
+  const fix = argv.includes('--fix');
+  const allFiles = collectDocFiles(config);
+  const fixable = [];
+
+  for (const filePath of allFiles) {
+    const raw = readFileSync(filePath, 'utf8');
+    const { frontmatter } = extractFrontmatter(raw);
+    if (!frontmatter) continue;
+    const parsed = parseSimpleFrontmatter(frontmatter);
+    const repoPath = toRepoPath(filePath, config.repoRoot);
+    const fixes = [];
+
+    // Missing updated
+    if (!asString(parsed.updated) && asString(parsed.status) && !config.lifecycle.skipWarningsFor.has(asString(parsed.status))) {
+      const today = new Date().toISOString().slice(0, 10);
+      fixes.push({ field: 'updated', oldValue: null, newValue: today, type: 'add' });
+    }
+
+    // Status casing
+    const status = asString(parsed.status);
+    if (status && status !== status.toLowerCase() && config.validStatuses.has(status.toLowerCase())) {
+      fixes.push({ field: 'status', oldValue: status, newValue: status.toLowerCase(), type: 'update' });
+    }
+
+    // Key renames
+    for (const [oldKey, newKey] of Object.entries(KEY_RENAMES)) {
+      if (parsed[oldKey] !== undefined && parsed[newKey] === undefined) {
+        fixes.push({ field: oldKey, oldValue: oldKey, newValue: newKey, type: 'rename-key' });
+      }
+    }
+
+    // Trailing whitespace in values
+    for (const line of frontmatter.split('\n')) {
+      const m = line.match(/^([A-Za-z0-9_-]+):(.+\S)\s+$/);
+      if (m) {
+        fixes.push({ field: m[1], oldValue: m[2] + line.slice(line.indexOf(m[2]) + m[2].length), newValue: m[2], type: 'trim' });
+      }
+    }
+
+    // Missing newline at EOF
+    if (!raw.endsWith('\n')) {
+      fixes.push({ field: '(eof)', oldValue: 'missing', newValue: 'newline', type: 'eof' });
+    }
+
+    if (fixes.length > 0) {
+      fixable.push({ filePath, repoPath, fixes });
+    }
+  }
+
+  // Also get non-fixable issues from index
+  const index = buildIndex(config);
+  const nonFixable = [...index.errors, ...index.warnings];
+
+  if (!fix) {
+    // Report mode
+    if (fixable.length > 0) {
+      process.stdout.write(bold(`${fixable.length} file(s) with fixable issues:\n\n`));
+      for (const { repoPath, fixes } of fixable) {
+        process.stdout.write(`  ${repoPath}\n`);
+        for (const f of fixes) {
+          if (f.type === 'rename-key') {
+            process.stdout.write(dim(`    ${f.oldValue} → ${f.newValue}\n`));
+          } else if (f.type === 'eof') {
+            process.stdout.write(dim(`    missing newline at end of file\n`));
+          } else if (f.type === 'add') {
+            process.stdout.write(dim(`    add ${f.field}: ${f.newValue}\n`));
+          } else {
+            process.stdout.write(dim(`    ${f.field}: ${f.oldValue} → ${f.newValue}\n`));
+          }
+        }
+      }
+      process.stdout.write(`\nRun ${bold('dotmd lint --fix')} to auto-fix.\n`);
+    }
+
+    if (nonFixable.length > 0) {
+      process.stdout.write(`\n${yellow(`${nonFixable.length} non-fixable issue(s)`)} (manual attention needed):\n`);
+      for (const issue of nonFixable) {
+        process.stdout.write(`  ${issue.path}: ${issue.message}\n`);
+      }
+    }
+
+    if (fixable.length === 0 && nonFixable.length === 0) {
+      process.stdout.write(green('No issues found.') + '\n');
+    }
+    return;
+  }
+
+  // Fix mode
+  const prefix = dryRun ? dim('[dry-run] ') : '';
+  let totalFixes = 0;
+
+  for (const { filePath, repoPath, fixes } of fixable) {
+    const updates = {};
+    const keyRenames = [];
+    let needsEofFix = false;
+    const trimFixes = [];
+
+    for (const f of fixes) {
+      if (f.type === 'rename-key') {
+        keyRenames.push(f);
+      } else if (f.type === 'eof') {
+        needsEofFix = true;
+      } else if (f.type === 'trim') {
+        trimFixes.push(f);
+      } else {
+        updates[f.field] = f.newValue;
+      }
+    }
+
+    if (!dryRun) {
+      // Apply key renames and trim fixes via raw string manipulation
+      if (keyRenames.length > 0 || trimFixes.length > 0) {
+        let raw = readFileSync(filePath, 'utf8');
+        const { frontmatter: fm } = extractFrontmatter(raw);
+        let newFm = fm;
+        for (const kr of keyRenames) {
+          const regex = new RegExp(`^${kr.oldValue}:`, 'm');
+          newFm = newFm.replace(regex, `${kr.newValue}:`);
+        }
+        for (const tf of trimFixes) {
+          const regex = new RegExp(`^(${escapeRegex(tf.field)}:)${escapeRegex(tf.oldValue)}$`, 'm');
+          newFm = newFm.replace(regex, `$1${tf.newValue}`);
+        }
+        if (newFm !== fm) {
+          raw = raw.replace(`---\n${fm}\n---`, `---\n${newFm}\n---`);
+          writeFileSync(filePath, raw, 'utf8');
+        }
+      }
+
+      // Apply value updates via updateFrontmatter
+      if (Object.keys(updates).length > 0) {
+        updateFrontmatter(filePath, updates);
+      }
+
+      // EOF fix
+      if (needsEofFix) {
+        const current = readFileSync(filePath, 'utf8');
+        if (!current.endsWith('\n')) {
+          writeFileSync(filePath, current + '\n', 'utf8');
+        }
+      }
+    }
+
+    process.stdout.write(`${prefix}${green('Fixed')}: ${repoPath} (${fixes.length} issue${fixes.length > 1 ? 's' : ''})\n`);
+    for (const f of fixes) {
+      if (f.type === 'rename-key') {
+        process.stdout.write(`${prefix}  ${dim(`${f.oldValue} → ${f.newValue}`)}\n`);
+      } else if (f.type === 'eof') {
+        process.stdout.write(`${prefix}  ${dim('added newline at EOF')}\n`);
+      } else if (f.type === 'add') {
+        process.stdout.write(`${prefix}  ${dim(`add ${f.field}: ${f.newValue}`)}\n`);
+      } else {
+        process.stdout.write(`${prefix}  ${dim(`${f.field}: ${f.oldValue} → ${f.newValue}`)}\n`);
+      }
+    }
+    totalFixes += fixes.length;
+
+    if (!dryRun) {
+      config.hooks.onLint?.({ path: repoPath, fixes });
+    }
+  }
+
+  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

@@ -0,0 +1,56 @@
+import { readFileSync } from 'node:fs';
+import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
+import { asString, toRepoPath, die } from './util.mjs';
+import { collectDocFiles } from './index.mjs';
+import { updateFrontmatter } from './lifecycle.mjs';
+import { bold, green, dim } from './color.mjs';
+
+export function runMigrate(argv, config, opts = {}) {
+  const { dryRun } = opts;
+
+  // Parse positional args (skip flags)
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i].startsWith('-')) continue;
+    positional.push(argv[i]);
+  }
+
+  const field = positional[0];
+  const oldValue = positional[1];
+  const newValue = positional[2];
+
+  if (!field || !oldValue || !newValue) {
+    die('Usage: dotmd migrate <field> <old-value> <new-value>');
+    return;
+  }
+
+  const allFiles = collectDocFiles(config);
+  const matches = [];
+
+  for (const filePath of allFiles) {
+    const raw = readFileSync(filePath, 'utf8');
+    const { frontmatter } = extractFrontmatter(raw);
+    if (!frontmatter) continue;
+    const parsed = parseSimpleFrontmatter(frontmatter);
+    const current = asString(parsed[field]);
+    if (current === oldValue) {
+      matches.push({ filePath, repoPath: toRepoPath(filePath, config.repoRoot) });
+    }
+  }
+
+  if (matches.length === 0) {
+    process.stdout.write(`No docs found with ${bold(field)}: ${oldValue}\n`);
+    return;
+  }
+
+  const prefix = dryRun ? dim('[dry-run] ') : '';
+
+  for (const { filePath, repoPath } of matches) {
+    if (!dryRun) {
+      updateFrontmatter(filePath, { [field]: newValue });
+    }
+    process.stdout.write(`${prefix}${green('Updated')}: ${repoPath} (${field}: ${oldValue} → ${newValue})\n`);
+  }
+
+  process.stdout.write(`\n${prefix}${matches.length} file(s) ${dryRun ? 'would be ' : ''}updated.\n`);
+}

package/src/new.mjs

@@ -51,4 +51,6 @@ 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 });
 }

package/src/rename.mjs

@@ -0,0 +1,149 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
+import { toRepoPath, resolveDocPath, die, warn } from './util.mjs';
+import { collectDocFiles } from './index.mjs';
+import { gitMv } from './git.mjs';
+import { green, dim, yellow } from './color.mjs';
+
+export function runRename(argv, config, opts = {}) {
+  const { dryRun } = opts;
+
+  // Parse positional args (skip flags)
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i].startsWith('-')) continue;
+    positional.push(argv[i]);
+  }
+
+  const oldInput = positional[0];
+  const newInput = positional[1];
+
+  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
+  const oldDir = path.dirname(oldPath);
+  let newBasename = newInput;
+  // If newInput contains a path separator, use just the basename
+  if (newInput.includes('/') || newInput.includes(path.sep)) {
+    newBasename = path.basename(newInput);
+  }
+  // Add .md if not present
+  if (!newBasename.endsWith('.md')) {
+    newBasename += '.md';
+  }
+  const newPath = path.join(oldDir, newBasename);
+
+  if (existsSync(newPath)) {
+    die(`Target already exists: ${toRepoPath(newPath, config.repoRoot)}`);
+    return;
+  }
+
+  const oldRepoPath = toRepoPath(oldPath, config.repoRoot);
+  const newRepoPath = toRepoPath(newPath, config.repoRoot);
+  const oldBasename = path.basename(oldPath);
+
+  // Scan for references in other docs
+  const allFiles = collectDocFiles(config);
+  const allRefFields = [
+    ...(config.referenceFields.bidirectional || []),
+    ...(config.referenceFields.unidirectional || []),
+  ];
+  const refUpdates = [];
+  const bodyWarnings = [];
+
+  for (const filePath of allFiles) {
+    if (filePath === oldPath) continue;
+    const raw = readFileSync(filePath, 'utf8');
+    const { frontmatter, body } = extractFrontmatter(raw);
+    if (!frontmatter) continue;
+
+    // Check frontmatter reference fields for old basename
+    let hasRef = false;
+    for (const line of frontmatter.split('\n')) {
+      if (line.includes(oldBasename)) {
+        hasRef = true;
+        break;
+      }
+    }
+
+    if (hasRef) {
+      refUpdates.push(filePath);
+    }
+
+    // Check body for markdown links containing old basename
+    if (body && body.includes(oldBasename)) {
+      bodyWarnings.push(toRepoPath(filePath, config.repoRoot));
+    }
+  }
+
+  if (dryRun) {
+    const prefix = dim('[dry-run]');
+    process.stdout.write(`${prefix} Would rename: ${oldRepoPath} → ${newRepoPath}\n`);
+    if (refUpdates.length > 0) {
+      process.stdout.write(`${prefix} Would update references in ${refUpdates.length} file(s):\n`);
+      for (const f of refUpdates) {
+        process.stdout.write(`${prefix}   ${toRepoPath(f, config.repoRoot)}\n`);
+      }
+    }
+    if (bodyWarnings.length > 0) {
+      process.stdout.write(`\n${yellow('Body links referencing old name')} (manual update needed):\n`);
+      for (const p of bodyWarnings) {
+        process.stdout.write(`  ${p}\n`);
+      }
+    }
+    return;
+  }
+
+  // Perform git mv
+  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
+  let updatedCount = 0;
+  for (const filePath of refUpdates) {
+    let raw = readFileSync(filePath, 'utf8');
+    const { frontmatter: fm } = extractFrontmatter(raw);
+    if (!fm) continue;
+
+    const newFm = fm.split('\n').map(line => {
+      if (line.includes(oldBasename)) {
+        return line.split(oldBasename).join(newBasename);
+      }
+      return line;
+    }).join('\n');
+
+    if (newFm !== fm) {
+      raw = raw.replace(`---\n${fm}\n---`, `---\n${newFm}\n---`);
+      writeFileSync(filePath, raw, 'utf8');
+      updatedCount++;
+    }
+  }
+
+  process.stdout.write(`${green('Renamed')}: ${oldRepoPath} → ${newRepoPath}\n`);
+  if (updatedCount > 0) {
+    process.stdout.write(`Updated references in ${updatedCount} file(s).\n`);
+  }
+
+  if (bodyWarnings.length > 0) {
+    process.stdout.write(`\n${yellow('Body links referencing old name')} (manual update needed):\n`);
+    for (const p of bodyWarnings) {
+      process.stdout.write(`  ${p}\n`);
+    }
+  }
+
+  config.hooks.onRename?.({ oldPath: oldRepoPath, newPath: newRepoPath, referencesUpdated: updatedCount });
+}