dotmd-cli 0.6.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

@@ -18,6 +18,8 @@ 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);
@@ -32,6 +34,7 @@ Commands:
   json                   Full index as JSON
   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
@@ -39,6 +42,7 @@ Commands:
   status <file> <status> Transition document status
   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
@@ -97,6 +101,25 @@ 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,
@@ -126,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.`,
@@ -269,6 +294,7 @@ async function main() {
   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);
 
@@ -348,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.6.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,8 +1,8 @@
 import { die } from './util.mjs';
 
 const COMMANDS = [
-  'list', 'json', 'check', 'coverage', 'context', 'focus', 'query',
-  'index', 'status', 'archive', 'touch', 'lint', 'rename', 'migrate',
+  'list', 'json', 'check', 'coverage', 'graph', 'context', 'focus', 'query',
+  'index', 'status', 'archive', 'touch', 'doctor', 'lint', 'rename', 'migrate',
   'fix-refs', 'watch', 'diff', 'init', 'new', 'completions',
 ];
 
@@ -15,9 +15,10 @@ 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: [],

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/graph.mjs

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

package/src/index.mjs

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

package/src/new.mjs

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

package/src/validate.mjs

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