dotmd-cli 0.10.6 → 0.11.1

package/bin/dotmd.mjs

@@ -8,7 +8,7 @@ import { buildIndex } from '../src/index.mjs';
 import { renderCompactList, renderVerboseList, renderContext, renderCheck, renderCoverage, buildCoverage } from '../src/render.mjs';
 import { renderIndexFile, writeIndex } from '../src/index-file.mjs';
 import { runFocus, runQuery } from '../src/query.mjs';
-import { runStatus, runArchive, runTouch } from '../src/lifecycle.mjs';
+import { runStatus, runArchive, runTouch, runBulkArchive } from '../src/lifecycle.mjs';
 import { runInit } from '../src/init.mjs';
 import { runNew } from '../src/new.mjs';
 import { runCompletions } from '../src/completions.mjs';
@@ -22,7 +22,9 @@ import { buildGraph, renderGraphText, renderGraphDot, renderGraphJson } from '..
 import { runDoctor } from '../src/doctor.mjs';
 import { buildStats, renderStats, renderStatsJson } from '../src/stats.mjs';
 import { runSummary } from '../src/summary.mjs';
-import { runDeps } from '../src/deps.mjs';
+import { runDeps, runUnblocks } from '../src/deps.mjs';
+import { runHealth } from '../src/health.mjs';
+import { runGlossary } from '../src/glossary.mjs';
 import { runExport } from '../src/export.mjs';
 import { runNotion } from '../src/notion.mjs';
 import { die, warn, levenshtein } from '../src/util.mjs';
@@ -44,6 +46,9 @@ View & Query:
   stats [--json]                    Doc health dashboard
   graph [--dot] [--json]            Visualize document relationships
   deps [file] [--json]              Dependency tree or overview
+  unblocks <file> [--json]          Show what completes when this doc ships
+  health [--json]                   Plan velocity, aging, and pipeline health
+  glossary <term> [--list] [--json] Look up domain terms + related docs
   diff [file] [--summarize]         Show changes since last updated date
   plans                             List all plans (shortcut for query --type plan)
   stale                             List stale docs across all statuses
@@ -59,6 +64,7 @@ Validate & Fix:
 Lifecycle:
   status <file> <status>            Transition document status
   archive <file>                    Archive (status + move + update refs)
+  bulk archive <f1> <f2> ...        Archive multiple files at once
   touch <file>                      Bump updated date
   touch --git                       Bulk-sync dates from git history
   rename <old> <new>                Rename doc and update all references
@@ -387,12 +393,6 @@ async function main() {
     return;
   }
 
-  // Init and completions don't need config
-  if (command === 'init') {
-    runInit(process.cwd());
-    return;
-  }
-
   if (command === 'completions') {
     runCompletions(args.slice(1));
     return;
@@ -412,6 +412,12 @@ async function main() {
 
   const config = await resolveConfig(process.cwd(), explicitConfig);
 
+  // Init — now has access to config for Claude command generation
+  if (command === 'init') {
+    runInit(process.cwd(), config.configFound ? config : null);
+    return;
+  }
+
   // Watch is a pure proxy — pass raw args so the child process gets all flags
   if (command === 'watch') { runWatch(args.slice(1), config); return; }
 
@@ -455,12 +461,16 @@ async function main() {
   if (command === 'diff') { runDiff(restArgs, config); return; }
   if (command === 'summary') { runSummary(restArgs, config); return; }
   if (command === 'deps') { runDeps(restArgs, config); return; }
+  if (command === 'unblocks') { runUnblocks(restArgs, config); return; }
+  if (command === 'health') { runHealth(restArgs, config); return; }
+  if (command === 'glossary') { runGlossary(restArgs, config); return; }
   if (command === 'export') { runExport(restArgs, config, { dryRun, root: rootArg, type: typeArg }); return; }
   if (command === 'notion') { await runNotion(restArgs, config, { dryRun }); return; }
 
   // Lifecycle commands
   if (command === 'status') { await runStatus(restArgs, config, { dryRun }); return; }
   if (command === 'archive') { runArchive(restArgs, config, { dryRun }); return; }
+  if (command === 'bulk' && restArgs[0] === 'archive') { runBulkArchive(restArgs.slice(1), config, { dryRun }); return; }
   if (command === 'touch') { runTouch(restArgs, config, { dryRun }); return; }
   if (command === 'new') { await runNew(restArgs, config, { dryRun, root: rootArg }); return; }
   if (command === 'lint') { runLint(restArgs, config, { dryRun }); return; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.10.6",
+  "version": "0.11.1",
   "description": "CLI for managing markdown documents with YAML frontmatter — index, query, validate, graph, export, Notion sync, AI summaries.",
   "type": "module",
   "license": "MIT",

package/src/claude-commands.mjs

@@ -0,0 +1,151 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { green, dim, yellow } from './color.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
+const VERSION_MARKER = `<!-- dotmd-generated: ${pkg.version} -->`;
+const VERSION_REGEX = /^<!-- dotmd-generated: ([\d.]+) -->/;
+
+function generatePlansCommand(config) {
+  const lines = [VERSION_MARKER, ''];
+  lines.push('Run `dotmd context` to get the current plans briefing, then use it to orient yourself.');
+  lines.push('');
+  lines.push(`Plans are managed by **dotmd** (v${pkg.version}). Config at \`dotmd.config.mjs\`. Always use \`dotmd\` directly.`);
+  lines.push('');
+  lines.push('Plan-specific commands:');
+  lines.push('- `dotmd context` — briefing with active/paused/ready plans, age tags, next steps');
+  lines.push('- `dotmd health` — plan velocity, aging, checklist progress, pipeline view');
+  lines.push('- `dotmd unblocks <file>` — what depends on / is blocked by a plan');
+  lines.push('- `dotmd next` — ready plans with next steps (what to promote)');
+  lines.push('- `dotmd new <name> --template plan` — scaffold with full phase structure');
+  lines.push('- `dotmd archive <file>` — archive with auto ref-fixing (both directions)');
+  lines.push('- `dotmd bulk archive <files>` — archive multiple at once');
+  lines.push('- `dotmd status <file> <status>` — transition status');
+  lines.push('- `dotmd query --keyword <term>` — find plans by keyword');
+
+  if (config.raw?.glossary) {
+    lines.push('- `dotmd glossary <term>` — domain term lookup with related plans');
+  }
+
+  lines.push('');
+  lines.push('If the user asks about a specific plan, read its file directly (path is in the briefing or findable via `dotmd query --keyword <term>`).');
+  lines.push('');
+  lines.push('If the user asks to change a plan\'s status, use `dotmd status <file> <status>`.');
+  lines.push('If the user asks to archive a plan, use `dotmd archive <file>`.');
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+function generateDocsCommand(config) {
+  const roots = Array.isArray(config.raw?.root) ? config.raw.root : [config.raw?.root ?? 'docs'];
+  const rootCount = roots.length;
+
+  const lines = [VERSION_MARKER, ''];
+  lines.push(`All documentation in this repo is managed by **dotmd** (v${pkg.version}). Docs across ${rootCount} root${rootCount > 1 ? 's' : ''}: ${roots.join(', ')}. Config at \`dotmd.config.mjs\`.`);
+  lines.push('');
+
+  // Document types from config
+  const types = config.raw?.types ? Object.keys(config.raw.types) : [];
+  if (types.length > 0) {
+    lines.push(`Document types: ${types.map(t => '`' + t + '`').join(', ')}.`);
+    lines.push('');
+  }
+
+  lines.push('Commands for working with docs:');
+  lines.push('- `dotmd context` — LLM-oriented briefing across all types');
+  lines.push('- `dotmd check` — validate frontmatter, refs, body links (target: 0 errors)');
+  lines.push('- `dotmd doctor` — auto-fix everything in one pass (refs, lint, dates, index)');
+  lines.push('- `dotmd query [filters]` — search by status, keyword, module, surface, type, staleness');
+  lines.push('- `dotmd health` — plan pipeline, velocity, aging');
+  lines.push('- `dotmd stats` — doc health dashboard (completeness, checklists, audit coverage)');
+  lines.push('- `dotmd graph [--dot]` — visualize document relationships');
+  lines.push('- `dotmd deps [file]` — dependency tree');
+  lines.push('- `dotmd unblocks <file>` — impact analysis for a doc');
+  lines.push('- `dotmd diff [file]` — git changes since last updated date');
+  lines.push('- `dotmd list` — all docs grouped by status');
+  lines.push('- `dotmd focus <status>` — detailed view for one status group');
+
+  if (config.raw?.glossary) {
+    lines.push('- `dotmd glossary <term>` — domain term lookup with related docs and plans');
+  }
+
+  lines.push('');
+  lines.push('Lifecycle:');
+  lines.push('- `dotmd new <name> --template plan` — scaffold new plan');
+  lines.push('- `dotmd status <file> <status>` — transition status');
+  lines.push('- `dotmd archive <file>` — archive with auto ref-fixing');
+  lines.push('- `dotmd bulk archive <files>` — archive multiple at once');
+  lines.push('- `dotmd touch --git` — bulk-sync updated dates from git history');
+  lines.push('- `dotmd lint --fix` — auto-fix frontmatter issues');
+  lines.push('- `dotmd fix-refs` — repair broken references and body links');
+  lines.push('- `dotmd rename <old> <new>` — rename doc + update all references');
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+function getInstalledVersion(filePath) {
+  if (!existsSync(filePath)) return null;
+  const content = readFileSync(filePath, 'utf8');
+  const match = content.match(VERSION_REGEX);
+  return match ? match[1] : null;
+}
+
+export function scaffoldClaudeCommands(cwd, config) {
+  const claudeDir = path.join(cwd, '.claude');
+  if (!existsSync(claudeDir)) return [];
+
+  const commandsDir = path.join(claudeDir, 'commands');
+  const results = [];
+
+  const files = [
+    { name: 'plans.md', generate: () => generatePlansCommand(config) },
+    { name: 'docs.md', generate: () => generateDocsCommand(config) },
+  ];
+
+  for (const { name, generate } of files) {
+    const filePath = path.join(commandsDir, name);
+    const installedVersion = getInstalledVersion(filePath);
+
+    if (installedVersion === pkg.version) {
+      results.push({ name, action: 'current' });
+    } else if (installedVersion) {
+      // Outdated — regenerate
+      mkdirSync(commandsDir, { recursive: true });
+      writeFileSync(filePath, generate(), 'utf8');
+      results.push({ name, action: 'updated', from: installedVersion, to: pkg.version });
+    } else if (!existsSync(filePath)) {
+      // New — create
+      mkdirSync(commandsDir, { recursive: true });
+      writeFileSync(filePath, generate(), 'utf8');
+      results.push({ name, action: 'created' });
+    } else {
+      // File exists but no version marker — user-managed, don't touch
+      results.push({ name, action: 'skipped' });
+    }
+  }
+
+  return results;
+}
+
+export function checkClaudeCommands(cwd) {
+  const commandsDir = path.join(cwd, '.claude', 'commands');
+  if (!existsSync(commandsDir)) return [];
+
+  const warnings = [];
+  for (const name of ['plans.md', 'docs.md']) {
+    const filePath = path.join(commandsDir, name);
+    const installedVersion = getInstalledVersion(filePath);
+    if (installedVersion && installedVersion !== pkg.version) {
+      warnings.push({
+        path: `.claude/commands/${name}`,
+        level: 'warning',
+        message: `Claude command outdated (v${installedVersion} → v${pkg.version}). Run \`dotmd doctor\` to update.`,
+      });
+    }
+  }
+  return warnings;
+}

package/src/completions.mjs

@@ -1,8 +1,8 @@
 import { die } from './util.mjs';
 
 const COMMANDS = [
-  'list', 'json', 'check', 'coverage', 'stats', 'graph', 'deps', 'context', 'focus', 'query',
-  'plans', 'stale', 'actionable', 'index', 'status', 'archive', 'touch', 'doctor', 'lint', 'rename', 'migrate',
+  'list', 'json', 'check', 'coverage', 'stats', 'graph', 'deps', 'unblocks', 'health', 'glossary', 'context', 'focus', 'query',
+  'plans', 'stale', 'actionable', 'index', 'status', 'archive', 'bulk', 'touch', 'doctor', 'lint', 'rename', 'migrate',
   'fix-refs', 'notion', 'export', 'summary', 'watch', 'diff', 'init', 'new', 'completions',
 ];
 
@@ -22,6 +22,10 @@ const COMMAND_FLAGS = {
   stats: ['--json'],
   graph: ['--dot', '--json', '--status', '--module', '--surface'],
   deps: ['--json', '--depth'],
+  unblocks: ['--json'],
+  health: ['--json'],
+  glossary: ['--list', '--json'],
+  bulk: ['archive'],
   notion: ['import', 'export', 'sync', '--force', '--dry-run'],
   export: ['--format', '--output', '--status', '--module', '--root', '--type'],
   focus: ['--json'],

package/src/config.mjs

@@ -76,6 +76,8 @@ const DEFAULTS = {
 
   templates: {},
 
+  glossary: null,
+
   notion: null,
 
   presets: {

package/src/deps.mjs

@@ -2,7 +2,7 @@ import path from 'node:path';
 import { buildGraph } from './graph.mjs';
 import { buildIndex } from './index.mjs';
 import { resolveDocPath, toSlug, toRepoPath, die, warn } from './util.mjs';
-import { bold, dim } from './color.mjs';
+import { bold, dim, green } from './color.mjs';
 
 export function runDeps(argv, config) {
   const positional = [];
@@ -247,3 +247,73 @@ function renderFlatJson(graph, forwardMap, reverseMap, docByPath) {
     orphans: graph.orphans,
   }, null, 2) + '\n');
 }
+
+// ── Unblocks ─────────────────────────────────────────────────────────
+
+export function runUnblocks(argv, config) {
+  const input = argv.find(a => !a.startsWith('-'));
+  const json = argv.includes('--json');
+  if (!input) die('Usage: dotmd unblocks <file>');
+
+  const filePath = resolveDocPath(input, config);
+  if (!filePath) die(`File not found: ${input}`);
+  const repoPath = toRepoPath(filePath, config.repoRoot);
+
+  const index = buildIndex(config);
+  const graph = buildGraph(index, config);
+  const docByPath = new Map(index.docs.map(d => [d.path, d]));
+  const doc = docByPath.get(repoPath);
+  if (!doc) die(`Doc not in index: ${repoPath}`);
+
+  // Find docs that reference this one (reverse edges)
+  const reverseMap = new Map();
+  for (const edge of graph.edges) {
+    if (!edge.broken) {
+      if (!reverseMap.has(edge.target)) reverseMap.set(edge.target, []);
+      reverseMap.get(edge.target).push({ source: edge.source, field: edge.field });
+    }
+  }
+
+  // Also find docs with blockers mentioning this file's basename
+  const basename = path.basename(repoPath, '.md');
+  const blockerRefs = index.docs.filter(d =>
+    d.blockers?.some(b => b.includes(basename) || b.includes(path.basename(repoPath)))
+  );
+
+  const directDeps = (reverseMap.get(repoPath) || []).map(e => {
+    const d = docByPath.get(e.source);
+    return { path: e.source, slug: path.basename(e.source, '.md'), status: d?.status, field: e.field };
+  });
+
+  const blockerDeps = blockerRefs
+    .filter(d => d.path !== repoPath)
+    .map(d => ({ path: d.path, slug: path.basename(d.path, '.md'), status: d.status, blockers: d.blockers }));
+
+  if (json) {
+    process.stdout.write(JSON.stringify({ doc: repoPath, directDeps, blockerDeps }, null, 2) + '\n');
+    return;
+  }
+
+  const slug = path.basename(repoPath, '.md');
+  process.stdout.write(`${bold('Unblocks')} — what happens when ${green(slug)} completes:\n\n`);
+
+  if (directDeps.length > 0) {
+    process.stdout.write(bold('Referenced by:') + '\n');
+    for (const d of directDeps) {
+      process.stdout.write(`  ${d.slug.padEnd(24)} ${dim(`(${d.status})`)}  via ${dim(d.field)}\n`);
+    }
+    process.stdout.write('\n');
+  }
+
+  if (blockerDeps.length > 0) {
+    process.stdout.write(bold('Listed as blocker in:') + '\n');
+    for (const d of blockerDeps) {
+      process.stdout.write(`  ${d.slug.padEnd(24)} ${dim(`(${d.status})`)}\n`);
+    }
+    process.stdout.write('\n');
+  }
+
+  if (directDeps.length === 0 && blockerDeps.length === 0) {
+    process.stdout.write(dim('No docs depend on or are blocked by this file.') + '\n');
+  }
+}

package/src/doctor.mjs

@@ -4,7 +4,8 @@ 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';
+import { bold, dim, green, yellow } from './color.mjs';
+import { scaffoldClaudeCommands } from './claude-commands.mjs';
 
 export function runDoctor(argv, config, opts = {}) {
   const { dryRun } = opts;
@@ -34,8 +35,21 @@ export function runDoctor(argv, config, opts = {}) {
     }
   }
 
-  // Step 5: Show remaining check
-  process.stdout.write('\n' + bold('5. Remaining issues:') + '\n');
+  // Step 5: Refresh Claude Code commands
+  const claudeResults = dryRun ? [] : scaffoldClaudeCommands(config.repoRoot, config);
+  if (claudeResults.some(r => r.action !== 'current' && r.action !== 'skipped')) {
+    process.stdout.write('\n' + bold('5. Claude Code commands:') + '\n');
+    for (const r of claudeResults) {
+      if (r.action === 'updated') {
+        process.stdout.write(`${green('Updated')} .claude/commands/${r.name} (v${r.from} → v${r.to})\n`);
+      } else if (r.action === 'created') {
+        process.stdout.write(`${green('Created')} .claude/commands/${r.name}\n`);
+      }
+    }
+  }
+
+  // Step 6: Show remaining check
+  process.stdout.write('\n' + bold('6. Remaining issues:') + '\n');
   const freshIndex = buildIndex(config);
   process.stdout.write(renderCheck(freshIndex, config));
 }

package/src/glossary.mjs

@@ -0,0 +1,230 @@
+import { readFileSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import { buildIndex } from './index.mjs';
+import { die, warn } from './util.mjs';
+import { bold, dim, green, yellow } from './color.mjs';
+
+function parseGlossaryTable(content, sectionHeading) {
+  const headingRegex = new RegExp(`^##\\s+${sectionHeading.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`, 'm');
+  const match = content.match(headingRegex);
+  if (!match) return [];
+
+  const sectionStart = match.index + match[0].length;
+  const nextHeading = content.indexOf('\n## ', sectionStart);
+  const section = nextHeading > -1 ? content.slice(sectionStart, nextHeading) : content.slice(sectionStart);
+
+  const entries = [];
+  const lines = section.split('\n');
+  let headerParsed = false;
+  let columns = [];
+
+  for (const line of lines) {
+    if (!line.startsWith('|')) continue;
+    const cells = line.split('|').slice(1, -1).map(c => c.trim());
+
+    if (!headerParsed) {
+      columns = cells.map(c => c.toLowerCase().replace(/\*\*/g, ''));
+      headerParsed = true;
+      continue;
+    }
+
+    if (cells.every(c => /^[-:]+$/.test(c))) continue;
+
+    const term = cells[0]?.replace(/\*\*/g, '').trim();
+    if (!term) continue;
+
+    const entry = { term };
+    for (let i = 1; i < columns.length; i++) {
+      entry[columns[i]] = cells[i] || '';
+    }
+    entries.push(entry);
+  }
+
+  // Schema→UI mappings
+  const mappingRegex = /^-\s+`([^`]+)`\s+→\s+"([^"]+)"\s*(?:\(([^)]+)\))?/gm;
+  let m;
+  while ((m = mappingRegex.exec(section)) !== null) {
+    entries.push({ term: m[1], meaning: `UI label: "${m[2]}"${m[3] ? ` (${m[3]})` : ''}`, tiers: 'schema→UI' });
+  }
+
+  return entries;
+}
+
+function loadGlossary(config) {
+  const glossaryConfig = config.raw?.glossary;
+  if (!glossaryConfig?.path) return null;
+
+  const filePath = path.resolve(config.repoRoot, glossaryConfig.path);
+  if (!existsSync(filePath)) {
+    warn(`Glossary file not found: ${glossaryConfig.path}`);
+    return null;
+  }
+
+  const content = readFileSync(filePath, 'utf8');
+  const section = glossaryConfig.section ?? 'Terminology';
+  return parseGlossaryTable(content, section);
+}
+
+function matchTerm(query, entries) {
+  const lower = query.toLowerCase();
+
+  // Exact match first
+  const exact = entries.filter(e => e.term.toLowerCase() === lower);
+  if (exact.length > 0) return exact;
+
+  // Term starts with query
+  const startsWith = entries.filter(e => e.term.toLowerCase().startsWith(lower));
+  if (startsWith.length > 0) return startsWith;
+
+  // Substring in term
+  const termMatch = entries.filter(e => e.term.toLowerCase().includes(lower));
+  if (termMatch.length > 0) return termMatch;
+
+  // Substring in meaning (broadest)
+  return entries.filter(e => e.meaning?.toLowerCase().includes(lower));
+}
+
+function findRelatedDocs(entry, index) {
+  const termLower = entry.term.toLowerCase();
+  // Split compound terms like "Trail / Summit / Expedition"
+  const termParts = entry.term.split(/\s*\/\s*/).map(t => t.trim().toLowerCase());
+
+  return index.docs.filter(d => {
+    // Module match (exact)
+    if (d.module?.toLowerCase() === termLower) return true;
+    if (d.modules?.some(m => m.toLowerCase() === termLower)) return true;
+    // Module match on term parts
+    if (termParts.some(p => d.module?.toLowerCase() === p || d.modules?.some(m => m.toLowerCase() === p))) return true;
+    // Path contains term (for terms like "hetchy" that aren't modules)
+    if (termParts.some(p => p.length >= 4 && d.path.toLowerCase().includes(p))) return true;
+    // Title match
+    if (termParts.some(p => p.length >= 4 && d.title?.toLowerCase().includes(p))) return true;
+    return false;
+  });
+}
+
+function findSeeAlso(entry, allEntries) {
+  const termLower = entry.term.toLowerCase();
+  const parts = entry.term.split(/\s*\/\s*/).map(t => t.trim().toLowerCase());
+
+  return allEntries.filter(other => {
+    if (other.term === entry.term) return false;
+    const otherLower = other.term.toLowerCase();
+    // Other term contains this term or vice versa
+    if (otherLower.includes(termLower) || termLower.includes(otherLower)) return true;
+    // Other meaning references this term
+    if (other.meaning?.toLowerCase().includes(termLower)) return true;
+    // Part match
+    if (parts.some(p => p.length >= 4 && (otherLower.includes(p) || other.meaning?.toLowerCase().includes(p)))) return true;
+    return false;
+  });
+}
+
+function renderEntry(entry, index, allEntries) {
+  const lines = [];
+  lines.push(`${green(bold(entry.term))}`);
+  if (entry.meaning) lines.push(`  ${entry.meaning}`);
+  if (entry.tiers) lines.push(`  ${dim(`Tiers: ${entry.tiers}`)}`);
+
+  const relatedDocs = findRelatedDocs(entry, index);
+
+  if (relatedDocs.length > 0) {
+    lines.push('');
+
+    // Module entry point (the main module doc, e.g. situ.md)
+    const entryPoint = relatedDocs.find(d =>
+      d.root?.includes('modules') && path.basename(d.path, '.md') === entry.term.toLowerCase()
+    );
+    if (entryPoint) {
+      lines.push(`  ${bold('Entry point:')} ${entryPoint.path}`);
+    }
+
+    // Other module docs (count, not list)
+    const moduleDocs = relatedDocs.filter(d => d.root?.includes('modules') && d !== entryPoint);
+    if (moduleDocs.length > 0) {
+      lines.push(`  ${bold('Module docs:')} ${moduleDocs.length} files in ${dim(path.dirname(moduleDocs[0].path))}`);
+    }
+
+    // Plans grouped by status
+    const planGroups = [
+      ['Active', 'active'],
+      ['Paused', 'paused'],
+      ['Ready', 'ready'],
+      ['Planned', 'planned'],
+      ['Blocked', 'blocked'],
+      ['Research', 'research'],
+    ];
+
+    for (const [label, status] of planGroups) {
+      const plans = relatedDocs.filter(d => d.type === 'plan' && d.status === status);
+      if (plans.length === 0) continue;
+      lines.push(`  ${bold(`${label}:`)} ${plans.map(d => path.basename(d.path, '.md')).join(', ')}`);
+    }
+  }
+
+  // See also: related glossary terms
+  const seeAlso = findSeeAlso(entry, allEntries);
+  if (seeAlso.length > 0) {
+    lines.push(`  ${dim('See also:')} ${seeAlso.map(e => e.term).join(', ')}`);
+  }
+
+  lines.push('');
+  return lines.join('\n');
+}
+
+export function runGlossary(argv, config) {
+  const json = argv.includes('--json');
+  const listAll = argv.includes('--list');
+  const term = argv.find(a => !a.startsWith('-'));
+
+  const entries = loadGlossary(config);
+  if (!entries) die('No glossary configured. Add glossary: { path, section } to your dotmd config.');
+  if (entries.length === 0) die('Glossary section found but no entries parsed.');
+
+  if (json && listAll) {
+    const index = buildIndex(config);
+    const enriched = entries.map(entry => ({
+      ...entry,
+      relatedDocs: findRelatedDocs(entry, index).map(d => ({ path: d.path, status: d.status, type: d.type, title: d.title })),
+      seeAlso: findSeeAlso(entry, entries).map(e => e.term),
+    }));
+    process.stdout.write(JSON.stringify(enriched, null, 2) + '\n');
+    return;
+  }
+
+  if (listAll) {
+    process.stdout.write(bold('Glossary') + dim(` (${entries.length} terms)`) + '\n\n');
+    const maxTerm = Math.max(...entries.map(e => e.term.length));
+    for (const entry of entries) {
+      process.stdout.write(`  ${green(entry.term.padEnd(maxTerm + 2))} ${entry.meaning || ''}\n`);
+    }
+    return;
+  }
+
+  if (!term) die('Usage: dotmd glossary <term> | --list | --json');
+
+  const matches = matchTerm(term, entries);
+
+  if (json) {
+    const index = buildIndex(config);
+    const enriched = matches.map(entry => ({
+      ...entry,
+      relatedDocs: findRelatedDocs(entry, index).map(d => ({ path: d.path, status: d.status, type: d.type, title: d.title })),
+      seeAlso: findSeeAlso(entry, entries).map(e => e.term),
+    }));
+    process.stdout.write(JSON.stringify(enriched, null, 2) + '\n');
+    return;
+  }
+
+  if (matches.length === 0) {
+    process.stdout.write(dim(`No glossary match for "${term}".`) + '\n');
+    return;
+  }
+
+  const index = buildIndex(config);
+  for (const entry of matches) {
+    process.stdout.write(renderEntry(entry, index, entries));
+  }
+}
+
+export { loadGlossary };

package/src/health.mjs

@@ -0,0 +1,141 @@
+import path from 'node:path';
+import { buildIndex } from './index.mjs';
+import { bold, dim, green, yellow, red } from './color.mjs';
+
+export function runHealth(argv, config) {
+  const json = argv.includes('--json');
+  const index = buildIndex(config);
+
+  // Only plans (type: plan or untyped docs in plans root)
+  const plans = index.docs.filter(d => d.type === 'plan' || (!d.type && d.root?.includes('plan')));
+  const now = Date.now();
+
+  // Status distribution
+  const byStatus = {};
+  for (const doc of plans) {
+    const s = doc.status ?? 'unknown';
+    byStatus[s] = (byStatus[s] || 0) + 1;
+  }
+
+  // Active plan aging (days since created)
+  const activePlans = plans.filter(d => d.status === 'active');
+  const activeAges = activePlans.map(d => {
+    const created = d.created ? new Date(d.created).getTime() : null;
+    return created ? Math.floor((now - created) / 86400000) : null;
+  }).filter(a => a !== null);
+
+  // Recently archived (last 30 days by updated date)
+  const recentlyArchived = plans
+    .filter(d => d.status === 'archived' && d.updated)
+    .filter(d => {
+      const updated = new Date(d.updated).getTime();
+      return (now - updated) < 30 * 86400000;
+    });
+
+  // Paused plan aging
+  const pausedPlans = plans.filter(d => d.status === 'paused');
+  const pausedAges = pausedPlans.map(d => {
+    const updated = d.updated ? new Date(d.updated).getTime() : null;
+    return updated ? Math.floor((now - updated) / 86400000) : null;
+  }).filter(a => a !== null);
+
+  // Blocked plan count + aging
+  const blockedPlans = plans.filter(d => d.status === 'blocked');
+
+  // Checklist progress on active plans
+  const activeWithChecklists = activePlans.filter(d => d.checklist?.total > 0);
+  const avgCompletion = activeWithChecklists.length > 0
+    ? activeWithChecklists.reduce((sum, d) => sum + (d.checklist.completed / d.checklist.total), 0) / activeWithChecklists.length
+    : null;
+
+  // Plans with deferred items (search body — not available here, use checklist proxy)
+  const readyPlans = plans.filter(d => d.status === 'ready');
+  const plannedPlans = plans.filter(d => d.status === 'planned');
+
+  if (json) {
+    process.stdout.write(JSON.stringify({
+      totalPlans: plans.length,
+      byStatus,
+      active: {
+        count: activePlans.length,
+        ages: activeAges,
+        avgAge: activeAges.length > 0 ? Math.round(activeAges.reduce((a, b) => a + b, 0) / activeAges.length) : null,
+        maxAge: activeAges.length > 0 ? Math.max(...activeAges) : null,
+        avgChecklistCompletion: avgCompletion ? Math.round(avgCompletion * 100) : null,
+      },
+      paused: { count: pausedPlans.length, ages: pausedAges },
+      blocked: { count: blockedPlans.length },
+      ready: { count: readyPlans.length },
+      planned: { count: plannedPlans.length },
+      recentlyArchived: { count: recentlyArchived.length, last30d: recentlyArchived.map(d => path.basename(d.path, '.md')) },
+    }, null, 2) + '\n');
+    return;
+  }
+
+  process.stdout.write(bold('Plan Health') + '\n\n');
+
+  // Pipeline
+  process.stdout.write(bold('Pipeline:') + '\n');
+  const pipeline = ['active', 'paused', 'ready', 'planned', 'blocked', 'research', 'archived'];
+  for (const s of pipeline) {
+    const count = byStatus[s] || 0;
+    if (count > 0) {
+      const bar = '█'.repeat(Math.min(count, 40));
+      process.stdout.write(`  ${s.padEnd(10)} ${String(count).padStart(4)}  ${dim(bar)}\n`);
+    }
+  }
+  process.stdout.write('\n');
+
+  // Active plan health
+  if (activePlans.length > 0) {
+    process.stdout.write(bold('Active plans:') + '\n');
+    const avgAge = activeAges.length > 0 ? Math.round(activeAges.reduce((a, b) => a + b, 0) / activeAges.length) : 0;
+    const maxAge = activeAges.length > 0 ? Math.max(...activeAges) : 0;
+    process.stdout.write(`  Count: ${activePlans.length}  Avg age: ${avgAge}d  Max age: ${maxAge}d\n`);
+    if (avgCompletion !== null) {
+      process.stdout.write(`  Avg checklist: ${Math.round(avgCompletion * 100)}%\n`);
+    }
+    for (const doc of activePlans) {
+      const age = doc.created ? Math.floor((now - new Date(doc.created).getTime()) / 86400000) : '?';
+      const slug = path.basename(doc.path, '.md').padEnd(28);
+      const pct = doc.checklist?.total > 0 ? `${Math.round(doc.checklist.completed / doc.checklist.total * 100)}%` : '-';
+      const ageColor = age > 30 ? red(age + 'd') : age > 14 ? yellow(age + 'd') : dim(age + 'd');
+      process.stdout.write(`  ${slug} ${ageColor}  checklist: ${pct}\n`);
+    }
+    process.stdout.write('\n');
+  }
+
+  // Paused
+  if (pausedPlans.length > 0) {
+    process.stdout.write(bold('Paused:') + '\n');
+    for (const doc of pausedPlans) {
+      const slug = path.basename(doc.path, '.md').padEnd(28);
+      const age = doc.updated ? Math.floor((now - new Date(doc.updated).getTime()) / 86400000) + 'd paused' : '';
+      process.stdout.write(`  ${slug} ${dim(age)}\n`);
+    }
+    process.stdout.write('\n');
+  }
+
+  // Velocity
+  process.stdout.write(bold('Velocity (last 30d):') + '\n');
+  process.stdout.write(`  Archived: ${green(String(recentlyArchived.length))} plans\n`);
+  if (recentlyArchived.length > 0) {
+    for (const doc of recentlyArchived.slice(0, 8)) {
+      process.stdout.write(`    ${dim(path.basename(doc.path, '.md'))}\n`);
+    }
+    if (recentlyArchived.length > 8) {
+      process.stdout.write(`    ${dim(`...and ${recentlyArchived.length - 8} more`)}\n`);
+    }
+  }
+  process.stdout.write('\n');
+
+  // Blocked summary
+  if (blockedPlans.length > 0) {
+    process.stdout.write(`${bold('Blocked:')} ${blockedPlans.length} plans\n\n`);
+  }
+
+  // Ready to promote
+  if (readyPlans.length > 0) {
+    process.stdout.write(`${bold('Ready to promote:')} ${readyPlans.length} plans\n\n`);
+  }
+}

package/src/index.mjs

@@ -5,6 +5,7 @@ import { extractFirstHeading, extractSummary, extractStatusSnapshot, extractNext
 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';
+import { checkClaudeCommands } from './claude-commands.mjs';
 
 export function buildIndex(config) {
   const docs = collectDocFiles(config).map(f => parseDocFile(f, config));
@@ -70,6 +71,9 @@ export function buildIndex(config) {
   const gitWarnings = checkGitStaleness(transformedDocs, config);
   warnings.push(...gitWarnings);
 
+  const claudeWarnings = checkClaudeCommands(config.repoRoot);
+  warnings.push(...claudeWarnings);
+
   return {
     generatedAt: new Date().toISOString(),
     docs: transformedDocs,

package/src/init.mjs

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from
 import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { green, dim } from './color.mjs';
+import { scaffoldClaudeCommands } from './claude-commands.mjs';
 
 const STARTER_CONFIG = `// dotmd.config.mjs — document management configuration
 // All exports are optional. See dotmd.config.example.mjs for full reference.
@@ -103,7 +104,7 @@ function generateDetectedConfig(scan, rootPath) {
   return lines.join('\n');
 }
 
-export function runInit(cwd) {
+export function runInit(cwd, config) {
   const configPath = path.join(cwd, 'dotmd.config.mjs');
   const docsDir = path.join(cwd, 'docs');
   const indexPath = path.join(docsDir, 'docs.md');
@@ -137,6 +138,18 @@ export function runInit(cwd) {
     process.stdout.write(`  ${green('create')}  docs/docs.md\n`);
   }
 
+  // Claude Code integration — auto-detect .claude/ directory
+  if (config) {
+    const results = scaffoldClaudeCommands(cwd, config);
+    for (const r of results) {
+      if (r.action === 'created') {
+        process.stdout.write(`  ${green('create')}  .claude/commands/${r.name}\n`);
+      } else if (r.action === 'current') {
+        process.stdout.write(`  ${dim('current')} .claude/commands/${r.name}\n`);
+      }
+    }
+  }
+
   process.stdout.write(`\nReady. Create your first doc:\n`);
   process.stdout.write(`  dotmd new my-doc\n`);
   process.stdout.write(`  dotmd list\n\n`);

package/src/lifecycle.mjs

@@ -164,6 +164,9 @@ export function runArchive(argv, config, opts = {}) {
   const result = gitMv(filePath, targetPath, config.repoRoot);
   if (result.status !== 0) { die(result.stderr || 'git mv failed.'); }
 
+  // Fix refs FROM the archived file (relative paths shifted by move)
+  const selfRefsFixed = updateRefsFromMovedFile(filePath, targetPath, config);
+
   // Auto-update references in other docs
   const updatedRefCount = updateRefsAfterMove(filePath, targetPath, config);
 
@@ -173,12 +176,56 @@ export function runArchive(argv, config, opts = {}) {
   }
 
   process.stdout.write(`${green('Archived')}: ${oldRepoPath} → ${newRepoPath}\n`);
+  if (selfRefsFixed) process.stdout.write('Updated references in archived file.\n');
   if (updatedRefCount > 0) process.stdout.write(`Updated references in ${updatedRefCount} file(s).\n`);
   if (config.indexPath) process.stdout.write('Index regenerated.\n');
 
   try { config.hooks.onArchive?.({ path: newRepoPath, oldStatus }, { oldPath: oldRepoPath, newPath: newRepoPath }); } catch (err) { warn(`Hook 'onArchive' threw: ${err.message}`); }
 }
 
+export function runBulkArchive(argv, config, opts = {}) {
+  const { dryRun } = opts;
+  const inputs = argv.filter(a => !a.startsWith('-'));
+  if (inputs.length === 0) die('Usage: dotmd bulk archive <file1> <file2> ... or <glob>');
+
+  const allFiles = collectDocFiles(config);
+  const matched = [];
+
+  for (const input of inputs) {
+    const filePath = resolveDocPath(input, config);
+    if (filePath) {
+      matched.push(filePath);
+    } else {
+      // Try as glob-style substring match
+      const hits = allFiles.filter(f => f.includes(input) || path.basename(f).includes(input));
+      matched.push(...hits);
+    }
+  }
+
+  const unique = [...new Set(matched)].filter(f => !f.includes(`/${config.archiveDir}/`));
+  if (unique.length === 0) die('No matching files found (already-archived files are excluded).');
+
+  process.stdout.write(`${unique.length} file(s) to archive:\n`);
+  for (const f of unique) {
+    process.stdout.write(`  ${toRepoPath(f, config.repoRoot)}\n`);
+  }
+
+  if (dryRun) {
+    process.stdout.write(dim('\n[dry-run] No changes made.\n'));
+    return;
+  }
+
+  process.stdout.write('\n');
+  for (const f of unique) {
+    const relPath = toRepoPath(f, config.repoRoot);
+    try {
+      runArchive([relPath], config, opts);
+    } catch (err) {
+      warn(`Failed to archive ${relPath}: ${err.message}`);
+    }
+  }
+}
+
 export function runTouch(argv, config, opts = {}) {
   const { dryRun } = opts;
   const useGit = argv.includes('--git');
@@ -293,6 +340,46 @@ function updateRefsAfterMove(oldPath, newPath, config) {
   return updatedCount;
 }
 
+function updateRefsFromMovedFile(oldPath, newPath, config) {
+  const oldDir = path.dirname(oldPath);
+  const newDir = path.dirname(newPath);
+  if (oldDir === newDir) return 0;
+
+  let raw = readFileSync(newPath, 'utf8');
+  const { frontmatter, body } = extractFrontmatter(raw);
+
+  // Fix frontmatter ref fields (YAML list items like  - ./path.md)
+  let newFm = frontmatter;
+  const refRegex = /^(\s+-\s+)(\S+\.md)$/gm;
+  newFm = newFm.replace(refRegex, (match, prefix, refPath) => {
+    const absTarget = path.resolve(oldDir, refPath);
+    if (!existsSync(absTarget)) return match;
+    const newRelPath = path.relative(newDir, absTarget).split(path.sep).join('/');
+    return `${prefix}${newRelPath}`;
+  });
+
+  // Fix body markdown links [text](path.md)
+  let newBody = body;
+  const linkRegex = /(\[[^\]]*\]\()([^)]+\.md)(\))/g;
+  newBody = newBody.replace(linkRegex, (match, pre, href, post) => {
+    if (href.startsWith('http')) return match;
+    const absTarget = path.resolve(oldDir, href);
+    if (!existsSync(absTarget)) return match;
+    const newHref = path.relative(newDir, absTarget).split(path.sep).join('/');
+    return `${pre}${newHref}${post}`;
+  });
+
+  if (newFm !== frontmatter || newBody !== body) {
+    const rebuilt = replaceFrontmatter(raw, newFm);
+    // Replace body: rebuilt has updated frontmatter but old body
+    const { frontmatter: updatedFm } = extractFrontmatter(rebuilt);
+    writeFileSync(newPath, `---\n${updatedFm}\n---${newBody}`, 'utf8');
+    return 1;
+  }
+
+  return 0;
+}
+
 function countRefsToUpdate(oldPath, newPath, config) {
   const basename = path.basename(oldPath);
   const allFiles = collectDocFiles(config);

package/src/render.mjs

@@ -133,10 +133,12 @@ function _renderContextSection(docs, ctx, opts, config, lines) {
     const maxSlug = Math.min(24, Math.max(...sdocs.map(d => toSlug(d).length)));
     for (const doc of sdocs) {
       const slug = toSlug(doc).padEnd(maxSlug);
+      const age = doc.created ? Math.floor((Date.now() - new Date(doc.created).getTime()) / 86400000) : null;
+      const ageTag = age !== null ? dim(` (${age}d)`) : '';
       const next = doc.nextStep
         ? truncate(doc.nextStep, ctx.truncateNextStep || 80)
         : '(no next step)';
-      lines.push(`  ${slug}  next: ${next}`);
+      lines.push(`  ${slug}${ageTag}  next: ${next}`);
       if (opts.summarize) {
         try {
           const absPath = path.resolve(config.repoRoot, doc.path);