dotmd-cli 0.5.0 → 0.7.0

package/README.md

@@ -19,6 +19,7 @@ dotmd new my-feature        # scaffold a new doc with frontmatter
 dotmd list                  # index all docs grouped by status
 dotmd check                 # validate frontmatter and references
 dotmd context               # compact briefing (great for LLM context)
+dotmd doctor                # auto-fix everything in one pass
 ```
 
 ### Shell Completion
@@ -37,9 +38,11 @@ dotmd scans a directory of markdown files, parses their YAML frontmatter, and gi
 
 - **Index** — group docs by status, show progress bars, next steps
 - **Query** — filter by status, keyword, module, surface, owner, staleness
-- **Validate** — check for missing fields, broken references, stale dates
-- **Lifecycle** — transition statuses, auto-archive with `git mv`, bump dates
-- **Scaffold** — create new docs with frontmatter from the command line
+- **Validate** — check for missing fields, broken references, stale dates, broken body links
+- **Graph** — visualize document relationships as text, Graphviz DOT, or JSON
+- **Lifecycle** — transition statuses, auto-archive with `git mv` and reference updates
+- **Doctor** — auto-fix broken refs, lint issues, date drift, and stale indexes in one pass
+- **Scaffold** — create new docs from templates (plan, ADR, RFC, audit, design)
 - **Index generation** — auto-generate a `docs.md` index block
 - **Context briefing** — compact summary designed for AI/LLM consumption
 - **Dry-run** — preview any mutation with `--dry-run` before committing
@@ -56,6 +59,8 @@ module: auth
 surface: backend
 next_step: implement token refresh
 current_state: initial scaffolding complete
+related_plans:
+  - ./design-doc.md
 ---
 
 # Auth Token Refresh
@@ -67,28 +72,32 @@ Design doc content here...
 - [ ] Add tests
 ```
 
-The only required field is `status`. Everything else is optional but unlocks more features (staleness detection, filtering, coverage reports).
+The only required field is `status`. Everything else is optional but unlocks more features (staleness detection, filtering, coverage reports, graph visualization).
 
 ## Commands
 
 ```
 dotmd list [--verbose]       List docs grouped by status (default)
 dotmd json                   Full index as JSON
-dotmd check                  Validate frontmatter and references
+dotmd check [--errors-only] [--fix]  Validate frontmatter and references
 dotmd coverage [--json]      Metadata coverage report
+dotmd graph [--dot|--json]   Visualize document relationships
 dotmd context                Compact briefing (LLM-oriented)
 dotmd focus [status]         Detailed view for one status group
 dotmd query [filters]        Filtered search
 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 archive <file>         Archive (status + move + update refs)
 dotmd touch <file>           Bump updated date
+dotmd touch --git            Bulk-sync dates from git history
+dotmd doctor                 Auto-fix everything in one pass
+dotmd fix-refs               Auto-fix broken reference paths
 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
+dotmd new <name>             Create a new document from template
 dotmd init                   Create starter config + docs directory
 dotmd completions <shell>    Output shell completion script (bash, zsh)
 ```
@@ -114,31 +123,91 @@ dotmd query --surface backend --checklist-open
 
 Flags: `--status`, `--keyword`, `--module`, `--surface`, `--domain`, `--owner`, `--updated-since`, `--stale`, `--has-next-step`, `--has-blockers`, `--checklist-open`, `--sort`, `--limit`, `--all`, `--git`, `--json`.
 
-### Scaffold a Document
+### Scaffold with Templates
 
 ```bash
-dotmd new my-feature                          # creates docs/my-feature.md (status: active)
-dotmd new "API Redesign" --status planned     # custom status
-dotmd new auth-refresh --title "Auth Refresh" # custom title
-dotmd new something --dry-run                 # preview without creating
+dotmd new my-feature                                  # default (status + title)
+dotmd new my-plan --template plan                     # plan with module, surface, refs
+dotmd new my-decision --template adr                  # ADR: Context, Decision, Consequences
+dotmd new my-proposal --template rfc                  # RFC: Summary, Motivation, Design
+dotmd new my-audit --template audit                   # Audit: Scope, Findings, Recommendations
+dotmd new my-design --template design                 # Design: Goals, Non-Goals, Design
+dotmd new my-feature --status planned --title "Title" # custom status and title
+dotmd new --list-templates                            # show all available templates
 ```
 
-### Preset Aliases
-
-Define custom query presets in your config:
+Built-in templates: `default`, `plan`, `adr`, `rfc`, `audit`, `design`. Add custom templates in your config:
 
 ```js
-export const presets = {
-  stale: ['--status', 'active,ready', '--stale', '--sort', 'updated', '--all'],
-  mine: ['--owner', 'robert', '--status', 'active', '--all'],
+export const templates = {
+  spike: {
+    description: 'Timeboxed investigation',
+    frontmatter: (status, today) => `status: ${status}\nupdated: ${today}\ntimebox: 2d`,
+    body: (title) => `\n# ${title}\n\n## Hypothesis\n\n\n\n## Findings\n\n\n`,
+  },
 };
 ```
 
-Then run `dotmd stale` or `dotmd mine` as shorthand.
+### Check & Fix
 
-### Lint
+```bash
+dotmd check                  # validate everything
+dotmd check --errors-only    # suppress warnings, show only errors
+dotmd check --fix            # auto-fix broken refs + lint + regen index
+```
+
+Validates: required fields, status values, broken reference paths, broken body links (`[text](path.md)`), bidirectional reference symmetry, git date drift, taxonomy mismatches.
+
+### Doctor
+
+One command to fix everything fixable:
+
+```bash
+dotmd doctor                 # fix refs → lint → sync git dates → regen index
+dotmd doctor --dry-run       # preview all changes
+```
+
+Runs in sequence: `fix-refs` → `lint --fix` → `touch --git` → `index --write` → shows remaining issues.
+
+### Graph
+
+Visualize how documents reference each other:
+
+```bash
+dotmd graph                              # text adjacency list
+dotmd graph --dot | dot -Tpng -o g.png   # Graphviz PNG
+dotmd graph --json                       # machine-readable
+dotmd graph --status active,ready        # filter by status
+dotmd graph --module auth                # filter by module
+```
 
-Check docs for fixable frontmatter issues and optionally auto-fix them:
+### Archive
+
+```bash
+dotmd archive docs/old-plan.md           # move + update refs + regen index
+dotmd archive docs/old-plan.md -n        # preview
+```
+
+Archives a document: sets status to `archived`, moves to archive directory via `git mv`, auto-updates references in other docs, and regenerates the index.
+
+### Touch
+
+```bash
+dotmd touch docs/my-doc.md              # set updated to today
+dotmd touch --git                        # bulk-sync all docs from git history
+dotmd touch --git docs/my-doc.md         # sync one file from git
+```
+
+### Fix References
+
+```bash
+dotmd fix-refs                           # find and fix broken ref paths
+dotmd fix-refs --dry-run                 # preview fixes
+```
+
+Scans all reference fields for broken paths, resolves by basename matching, and rewrites frontmatter.
+
+### Lint
 
 ```bash
 dotmd lint                   # report issues
@@ -146,34 +215,35 @@ 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
+Detected issues: missing `updated`, status casing, camelCase keys, trailing whitespace, missing EOF newline.
 
 ### 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.
+Uses `git mv` and updates all frontmatter references. 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
 ```
 
+### Preset Aliases
+
+```js
+export const presets = {
+  stale: ['--status', 'active,ready', '--stale', '--sort', 'updated', '--all'],
+  mine: ['--owner', 'robert', '--status', 'active', '--all'],
+};
+```
+
+Then run `dotmd stale` or `dotmd mine` as shorthand.
+
 ### Watch Mode
 
 ```bash
@@ -184,19 +254,13 @@ dotmd watch context      # live briefing
 
 ### Diff & Summarize
 
-Show git changes since each document's `updated` frontmatter date:
-
 ```bash
 dotmd diff                           # all drifted docs
 dotmd diff docs/plans/auth.md        # single file
 dotmd diff --stat                    # summary stats only
-dotmd diff --since 2026-01-01        # override date
 dotmd diff --summarize               # AI summary via local MLX model
-dotmd diff --summarize --model mlx-community/Mistral-7B-Instruct-v0.3-4bit
 ```
 
-The `--summarize` flag requires `uv` and a local MLX-compatible model. No JS dependencies are added.
-
 ## Configuration
 
 Create `dotmd.config.mjs` at your project root (or run `dotmd init`):
@@ -216,6 +280,16 @@ export const lifecycle = {
   skipWarningsFor: ['archived'],
 };
 
+export const taxonomy = {
+  surfaces: ['web', 'ios', 'backend', 'api', 'platform'],
+  moduleRequiredFor: ['active', 'ready', 'planned', 'blocked'],
+};
+
+export const referenceFields = {
+  bidirectional: ['related_plans'],       // warn if A→B but B↛A
+  unidirectional: ['supports_plans'],     // one-way, no symmetry check
+};
+
 export const index = {
   path: 'docs/docs.md',
   startMarker: '<!-- GENERATED:dotmd:start -->',
@@ -258,7 +332,7 @@ export function renderContext(index, defaultRenderer) {
 }
 ```
 
-Available: `renderContext`, `renderCompactList`, `renderCheck`, `formatSnapshot`.
+Available: `renderContext`, `renderCompactList`, `renderCheck`, `renderGraph`, `formatSnapshot`.
 
 ### Lifecycle Hooks
 
@@ -291,7 +365,7 @@ export function summarizeDiff(diffOutput, filePath) {
 - **No build step** — ships as plain ESM, runs directly
 - **Git-aware** — detects frontmatter date drift vs git history, uses `git mv` for archives
 - **Dry-run everything** — preview any mutation with `--dry-run` / `-n`
-- **Configurable everything** — statuses, taxonomy, lifecycle, validation rules, display
+- **Configurable everything** — statuses, taxonomy, lifecycle, validation rules, display, templates
 - **Hook system** — extend with JS functions, no plugin framework to learn
 - **LLM-friendly** — `dotmd context` generates compact briefings for AI assistants
 - **Shell completion** — bash and zsh via `dotmd completions`

package/bin/dotmd.mjs

@@ -17,6 +17,9 @@ 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 { buildGraph, renderGraphText, renderGraphDot, renderGraphJson } from '../src/graph.mjs';
+import { runDoctor } from '../src/doctor.mjs';
 import { die, warn } from '../src/util.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -29,15 +32,18 @@ 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
+  graph [--dot|--json]   Visualize document relationships
   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
+  doctor                 Auto-fix everything: refs, lint, dates, index
+  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 +88,52 @@ 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.`,
+
+  graph: `dotmd graph — visualize document relationships
+
+Output formats:
+  (default)              Text adjacency list
+  --dot                  Graphviz DOT format (pipe to dot -Tpng)
+  --json                 Machine-readable JSON
+
+Filters:
+  --status <s1,s2>       Show only docs with these statuses
+  --module <name>        Show only docs with this module
+  --surface <name>       Show only docs with this surface`,
+
+  doctor: `dotmd doctor — auto-fix everything in one pass
+
+Runs in sequence: fix broken references, lint --fix, sync dates from
+git, regenerate index, then show remaining issues.
+
+Use --dry-run (-n) to preview all 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.`,
 
@@ -101,8 +149,10 @@ Use --dry-run (-n) with --write to preview without writing.`,
 Creates a new markdown document with frontmatter in the docs root.
 
 Options:
+  --template <name>    Use a template (default, plan, adr, rfc, audit, design)
   --status <s>         Set initial status (default: active)
   --title <t>          Override the document title
+  --list-templates     Show available templates
 
 The filename is derived from <name> by slugifying it.
 Use --dry-run (-n) to preview without creating the file.`,
@@ -243,6 +293,8 @@ 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; }
+  if (command === 'doctor') { runDoctor(restArgs, config, { dryRun }); return; }
 
   const index = buildIndex(config);
 
@@ -265,7 +317,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;
   }
@@ -300,6 +374,25 @@ async function main() {
   if (command === 'query') { runQuery(index, restArgs, config); return; }
   if (command === 'context') { process.stdout.write(renderContext(index, config)); return; }
 
+  if (command === 'graph') {
+    const statusFilter = (() => { const i = args.indexOf('--status'); return i !== -1 && args[i + 1] ? args[i + 1] : null; })();
+    const moduleFilter = (() => { const i = args.indexOf('--module'); return i !== -1 && args[i + 1] ? args[i + 1] : null; })();
+    const surfaceFilter = (() => { const i = args.indexOf('--surface'); return i !== -1 && args[i + 1] ? args[i + 1] : null; })();
+    const graph = buildGraph(index, config, {
+      statuses: statusFilter?.split(',') ?? null,
+      module: moduleFilter,
+      surface: surfaceFilter,
+    });
+    if (args.includes('--dot')) {
+      process.stdout.write(renderGraphDot(graph, config));
+    } else if (args.includes('--json')) {
+      process.stdout.write(renderGraphJson(graph));
+    } else {
+      process.stdout.write(renderGraphText(graph, config));
+    }
+    return;
+  }
+
   // Unknown command — show help
   die(`Unknown command: ${command}\n\n${HELP._main}`);
 }

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.5.0",
+  "version": "0.7.0",
   "description": "Zero-dependency CLI for managing markdown documents with YAML frontmatter — index, query, validate, lifecycle.",
   "type": "module",
   "license": "MIT",

package/src/completions.mjs

@@ -1,9 +1,9 @@
 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',
+  'list', 'json', 'check', 'coverage', 'graph', 'context', 'focus', 'query',
+  'index', 'status', 'archive', 'touch', 'doctor', 'lint', 'rename', 'migrate',
+  'fix-refs', 'watch', 'diff', 'init', 'new', 'completions',
 ];
 
 const GLOBAL_FLAGS = ['--config', '--dry-run', '--verbose', '--help', '--version'];
@@ -15,11 +15,15 @@ const COMMAND_FLAGS = {
   index: ['--write'],
   list: ['--verbose'],
   coverage: ['--json'],
-  new: ['--status', '--title'],
+  new: ['--status', '--title', '--template', '--list-templates'],
   diff: ['--stat', '--since', '--summarize', '--model'],
+  check: ['--errors-only', '--fix'],
+  graph: ['--dot', '--json', '--status', '--module', '--surface'],
   lint: ['--fix'],
   rename: [],
   migrate: [],
+  'fix-refs': [],
+  touch: ['--git'],
 };
 
 function bashCompletion() {

package/src/config.mjs

@@ -55,6 +55,8 @@ const DEFAULTS = {
     unidirectional: [],
   },
 
+  templates: {},
+
   presets: {
     stale: ['--status', 'active,ready,planned,blocked,research', '--stale', '--sort', 'updated', '--all'],
     actionable: ['--status', 'active,ready', '--has-next-step', '--sort', 'updated', '--all'],

package/src/doctor.mjs

@@ -0,0 +1,41 @@
+import { fixBrokenRefs } from './fix-refs.mjs';
+import { runLint } from './lint.mjs';
+import { runTouch } from './lifecycle.mjs';
+import { buildIndex } from './index.mjs';
+import { renderIndexFile, writeIndex } from './index-file.mjs';
+import { renderCheck } from './render.mjs';
+import { bold } from './color.mjs';
+
+export function runDoctor(argv, config, opts = {}) {
+  const { dryRun } = opts;
+  process.stdout.write(bold('dotmd doctor') + '\n\n');
+
+  // Step 1: Fix broken references
+  process.stdout.write(bold('1. Fixing broken references...') + '\n');
+  fixBrokenRefs(config, { dryRun });
+
+  // Step 2: Lint --fix
+  process.stdout.write('\n' + bold('2. Fixing frontmatter issues...') + '\n');
+  runLint(['--fix'], config, { dryRun });
+
+  // Step 3: Sync dates from git
+  process.stdout.write('\n' + bold('3. Syncing dates from git...') + '\n');
+  runTouch(['--git'], config, { dryRun });
+
+  // Step 4: Regenerate index
+  if (config.indexPath) {
+    process.stdout.write('\n' + bold('4. Regenerating index...') + '\n');
+    if (!dryRun) {
+      const index = buildIndex(config);
+      writeIndex(renderIndexFile(index, config), config);
+      process.stdout.write('Index updated.\n');
+    } else {
+      process.stdout.write('[dry-run] Would regenerate index.\n');
+    }
+  }
+
+  // Step 5: Show remaining check
+  process.stdout.write('\n' + bold('5. Remaining issues:') + '\n');
+  const freshIndex = buildIndex(config);
+  process.stdout.write(renderCheck(freshIndex, config));
+}

package/src/extractors.mjs

@@ -39,6 +39,25 @@ export function extractNextStep(body) {
   return lines[0] ?? null;
 }
 
+export function extractBodyLinks(body) {
+  if (!body) return [];
+  // Strip fenced code blocks to avoid false positives
+  const stripped = body.replace(/^```[\s\S]*?^```/gm, '');
+  const links = [];
+  // Match [text](path.md) or [text](path.md#anchor), skip images (preceded by !)
+  const regex = /(?<!!)\[([^\]]+)\]\(([^)]+\.md(?:#[^)]*)?)\)/g;
+  let match;
+  while ((match = regex.exec(stripped)) !== null) {
+    const href = match[2];
+    // Skip external URLs
+    if (/^https?:\/\//i.test(href)) continue;
+    // Strip anchor fragment for path resolution
+    const cleanHref = href.replace(/#.*$/, '');
+    links.push({ text: match[1], href: cleanHref });
+  }
+  return links;
+}
+
 export function extractChecklistCounts(body) {
   const matches = [...body.matchAll(/^\s*[-*]\s+\[([ xX])\]\s+/gm)];
   let completed = 0;

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 };
+}