dotmd-cli 0.7.6 → 0.8.1

package/src/fix-refs.mjs

@@ -1,14 +1,14 @@
 import { readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { extractFrontmatter, replaceFrontmatter } from './frontmatter.mjs';
-import { toRepoPath, warn } from './util.mjs';
+import { toRepoPath, escapeRegex, 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) {
+  if (result.totalFixed === 0 && result.bodyLinksFixed === 0 && result.unfixableCount === 0) {
     process.stdout.write(green('No broken references found.') + '\n');
   }
 }
@@ -34,80 +34,130 @@ export function fixBrokenRefs(config, opts = {}) {
     }
   }
 
-  // Find broken ref errors
+  const prefix = dryRun ? dim('[dry-run] ') : '';
+  let totalFixed = 0;
+  let unfixableCount = 0;
+  let bodyLinksFixed = 0;
+
+  // ── Fix broken frontmatter references ────────────────────────────────
+
   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 };
-  }
+  if (brokenRefErrors.length > 0) {
+    const fixesByDoc = new Map();
 
-  // 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; }
 
-  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);
 
-    const brokenRef = match[1];
-    const brokenBasename = path.basename(brokenRef);
+      if (duplicateBasenames.has(brokenBasename)) { unfixableCount++; continue; }
 
-    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 resolved = basenameMap.get(brokenBasename);
-    if (!resolved) { unfixableCount++; continue; }
+    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;
 
-    const docAbsPath = path.join(config.repoRoot, err.path);
-    const docDir = path.dirname(docAbsPath);
-    const correctRelPath = path.relative(docDir, resolved).split(path.sep).join('/');
+      let newFm = fm;
+      for (const { brokenRef, correctRelPath } of fixes) {
+        newFm = newFm.split(brokenRef).join(correctRelPath);
+      }
 
-    if (correctRelPath === brokenRef) { unfixableCount++; continue; }
+      if (newFm !== fm && !dryRun) {
+        raw = replaceFrontmatter(raw, newFm);
+        writeFileSync(absPath, raw, 'utf8');
+      }
 
-    if (!fixesByDoc.has(err.path)) {
-      fixesByDoc.set(err.path, []);
+      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;
     }
-    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;
+  // ── Fix broken body links ────────────────────────────────────────────
 
-    let newFm = fm;
-    for (const { brokenRef, correctRelPath } of fixes) {
-      newFm = newFm.split(brokenRef).join(correctRelPath);
-    }
+  for (const doc of index.docs) {
+    const brokenBodyWarnings = doc.warnings.filter(w =>
+      w.message.startsWith('body link') && w.message.includes('does not resolve')
+    );
+    if (!brokenBodyWarnings.length) continue;
 
-    if (newFm !== fm && !dryRun) {
-      raw = replaceFrontmatter(raw, newFm);
-      writeFileSync(absPath, raw, 'utf8');
+    const absPath = path.join(config.repoRoot, doc.path);
+    let raw = readFileSync(absPath, 'utf8');
+    const { frontmatter: fm, body } = extractFrontmatter(raw);
+    let newBody = body;
+    const docDir = path.dirname(absPath);
+    const bodyFixes = [];
+
+    for (const warn of brokenBodyWarnings) {
+      const match = warn.message.match(/body link `([^`]+)` does not resolve/);
+      if (!match) continue;
+
+      const brokenHref = match[1];
+      const brokenBasename = path.basename(brokenHref);
+
+      if (duplicateBasenames.has(brokenBasename)) continue;
+      const resolved = basenameMap.get(brokenBasename);
+      if (!resolved) continue;
+
+      const correctHref = path.relative(docDir, resolved).split(path.sep).join('/');
+      if (correctHref === brokenHref) continue;
+
+      const linkRegex = new RegExp(
+        '(?<!!)\\[([^\\]]+)\\]\\(' + escapeRegex(brokenHref) + '(#[^)]*)?\\)',
+        'g'
+      );
+      newBody = newBody.replace(linkRegex, (_, text, anchor) =>
+        `[${text}](${correctHref}${anchor ?? ''})`
+      );
+      bodyFixes.push({ brokenHref, correctHref });
     }
 
-    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`);
+    if (bodyFixes.length > 0 && newBody !== body) {
+      if (!dryRun) {
+        writeFileSync(absPath, `---\n${fm}\n---\n${newBody}`, 'utf8');
+      }
+      if (!quiet) {
+        process.stdout.write(`${prefix}${green('Fixed')}: ${doc.path} (${bodyFixes.length} body link${bodyFixes.length > 1 ? 's' : ''})\n`);
+        for (const { brokenHref, correctHref } of bodyFixes) {
+          process.stdout.write(`${prefix}  ${dim(`${brokenHref} → ${correctHref}`)}\n`);
+        }
       }
+      bodyLinksFixed += bodyFixes.length;
     }
-    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`);
-    }
+  // ── Summary ──────────────────────────────────────────────────────────
+
+  const allFixed = totalFixed + bodyLinksFixed;
+  if (!quiet && allFixed > 0) {
+    process.stdout.write(`\n${prefix}${allFixed} fix${allFixed !== 1 ? 'es' : ''} applied.\n`);
+  }
+  if (!quiet && unfixableCount > 0) {
+    process.stdout.write(`${yellow(`${unfixableCount} broken reference(s) could not be auto-resolved`)} (file not found by basename).\n`);
   }
 
-  return { totalFixed, unfixableCount };
+  return { totalFixed, unfixableCount, bodyLinksFixed };
 }

package/src/index.mjs

@@ -77,11 +77,15 @@ export function collectDocFiles(config) {
   const files = [];
   const skipPaths = new Set();
   if (config.indexPath) skipPaths.add(config.indexPath);
-  walkMarkdownFiles(config.docsRoot, files, config.excludeDirs, skipPaths);
+  const roots = config.docsRoots || [config.docsRoot];
+  const seen = new Set();
+  for (const root of roots) {
+    walkMarkdownFiles(root, files, config.excludeDirs, skipPaths, seen);
+  }
   return files.sort((a, b) => a.localeCompare(b));
 }
 
-function walkMarkdownFiles(directory, files, excludedDirs, skipPaths) {
+function walkMarkdownFiles(directory, files, excludedDirs, skipPaths, seen = new Set()) {
   let entries;
   try {
     entries = readdirSync(directory, { withFileTypes: true });
@@ -91,11 +95,12 @@ function walkMarkdownFiles(directory, files, excludedDirs, skipPaths) {
   for (const entry of entries) {
     if (entry.isDirectory()) {
       if (excludedDirs && excludedDirs.has(entry.name)) continue;
-      walkMarkdownFiles(path.join(directory, entry.name), files, excludedDirs, skipPaths);
+      walkMarkdownFiles(path.join(directory, entry.name), files, excludedDirs, skipPaths, seen);
       continue;
     }
     const fullPath = path.join(directory, entry.name);
-    if (!entry.isFile() || !entry.name.endsWith('.md') || skipPaths.has(fullPath)) continue;
+    if (!entry.isFile() || !entry.name.endsWith('.md') || skipPaths.has(fullPath) || seen.has(fullPath)) continue;
+    seen.add(fullPath);
     files.push(fullPath);
   }
 }
@@ -127,8 +132,14 @@ export function parseDocFile(filePath, config) {
     refFields[field] = normalizeStringList(parsedFrontmatter[field]);
   }
 
+  // Tag doc with its root
+  const roots = config.docsRoots || [config.docsRoot];
+  const docRoot = roots.find(r => filePath.startsWith(r)) ?? config.docsRoot;
+  const rootLabel = path.relative(config.repoRoot, docRoot).split(path.sep).join('/');
+
   const doc = {
     path: relativePath,
+    root: rootLabel,
     status: asString(parsedFrontmatter.status) ?? null,
     owner: asString(parsedFrontmatter.owner) ?? null,
     surface,

package/src/init.mjs

@@ -1,5 +1,6 @@
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
+import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { green, dim } from './color.mjs';
 
 const STARTER_CONFIG = `// dotmd.config.mjs — document management configuration
@@ -24,6 +25,84 @@ _No docs yet. Run \`dotmd list\` after creating your first document._
 <!-- GENERATED:dotmd:end -->
 `;
 
+function scanExistingDocs(dir) {
+  const statuses = new Set();
+  const surfaces = new Set();
+  const modules = new Set();
+  const refFieldNames = new Set();
+  let docCount = 0;
+
+  function walk(d) {
+    let entries;
+    try { entries = readdirSync(d, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      if (entry.isDirectory()) { walk(path.join(d, entry.name)); continue; }
+      if (!entry.name.endsWith('.md')) continue;
+      let raw;
+      try { raw = readFileSync(path.join(d, entry.name), 'utf8'); } catch { continue; }
+      const { frontmatter } = extractFrontmatter(raw);
+      if (!frontmatter) continue;
+      const parsed = parseSimpleFrontmatter(frontmatter);
+      docCount++;
+      if (parsed.status) statuses.add(String(parsed.status).toLowerCase());
+      if (parsed.surface) surfaces.add(String(parsed.surface));
+      if (Array.isArray(parsed.surfaces)) parsed.surfaces.forEach(s => surfaces.add(String(s)));
+      if (parsed.module) modules.add(String(parsed.module));
+      if (Array.isArray(parsed.modules)) parsed.modules.forEach(m => modules.add(String(m)));
+      for (const [key, val] of Object.entries(parsed)) {
+        if (Array.isArray(val) && val.some(v => String(v).endsWith('.md'))) {
+          refFieldNames.add(key);
+        }
+      }
+    }
+  }
+
+  walk(dir);
+  return { docCount, statuses, surfaces, modules, refFieldNames };
+}
+
+function generateDetectedConfig(scan, rootPath) {
+  const lines = [`// dotmd.config.mjs — auto-detected from ${scan.docCount} existing docs`, ''];
+  lines.push(`export const root = '${rootPath}';`);
+  lines.push('');
+
+  const defaultOrder = ['active', 'ready', 'planned', 'research', 'blocked', 'reference', 'archived'];
+  const ordered = defaultOrder.filter(s => scan.statuses.has(s));
+  const extra = [...scan.statuses].filter(s => !defaultOrder.includes(s)).sort();
+  const allStatuses = [...ordered, ...extra];
+  if (allStatuses.length > 0) {
+    lines.push('export const statuses = {');
+    lines.push(`  order: [${allStatuses.map(s => `'${s}'`).join(', ')}],`);
+    lines.push('};');
+    lines.push('');
+  }
+
+  if (scan.surfaces.size > 0) {
+    lines.push('export const taxonomy = {');
+    lines.push(`  surfaces: [${[...scan.surfaces].sort().map(s => `'${s}'`).join(', ')}],`);
+    lines.push('};');
+    lines.push('');
+  }
+
+  if (scan.refFieldNames.size > 0) {
+    const names = [...scan.refFieldNames].sort();
+    lines.push('export const referenceFields = {');
+    lines.push(`  bidirectional: [${names.map(n => `'${n}'`).join(', ')}],`);
+    lines.push('  unidirectional: [],');
+    lines.push('};');
+    lines.push('');
+  }
+
+  lines.push('export const index = {');
+  lines.push(`  path: '${rootPath}/docs.md',`);
+  lines.push(`  startMarker: '<!-- GENERATED:dotmd:start -->',`);
+  lines.push(`  endMarker: '<!-- GENERATED:dotmd:end -->',`);
+  lines.push('};');
+  lines.push('');
+
+  return lines.join('\n');
+}
+
 export function runInit(cwd) {
   const configPath = path.join(cwd, 'dotmd.config.mjs');
   const docsDir = path.join(cwd, 'docs');
@@ -34,8 +113,14 @@ export function runInit(cwd) {
   if (existsSync(configPath)) {
     process.stdout.write(`  ${dim('exists')}  dotmd.config.mjs\n`);
   } else {
-    writeFileSync(configPath, STARTER_CONFIG, 'utf8');
-    process.stdout.write(`  ${green('create')}  dotmd.config.mjs\n`);
+    const scan = existsSync(docsDir) ? scanExistingDocs(docsDir) : null;
+    if (scan && scan.docCount > 0) {
+      writeFileSync(configPath, generateDetectedConfig(scan, 'docs'), 'utf8');
+      process.stdout.write(`  ${green('create')}  dotmd.config.mjs (detected ${scan.docCount} docs)\n`);
+    } else {
+      writeFileSync(configPath, STARTER_CONFIG, 'utf8');
+      process.stdout.write(`  ${green('create')}  dotmd.config.mjs\n`);
+    }
   }
 
   if (existsSync(docsDir)) {
@@ -57,4 +142,3 @@ export function runInit(cwd) {
   process.stdout.write(`  printf '---\\nstatus: active\\nupdated: ${today}\\n---\\n\\n# My Doc\\n' > docs/my-doc.md\n`);
   process.stdout.write(`  dotmd list\n\n`);
 }
-

package/src/lifecycle.mjs

@@ -7,6 +7,11 @@ import { buildIndex, collectDocFiles } from './index.mjs';
 import { renderIndexFile, writeIndex } from './index-file.mjs';
 import { green, dim, yellow } from './color.mjs';
 
+function findFileRoot(filePath, config) {
+  const roots = config.docsRoots || [config.docsRoot];
+  return roots.find(r => filePath.startsWith(r)) ?? config.docsRoot;
+}
+
 export function runStatus(argv, config, opts = {}) {
   const { dryRun } = opts;
   const input = argv[0];
@@ -29,7 +34,8 @@ export function runStatus(argv, config, opts = {}) {
   }
 
   const today = new Date().toISOString().slice(0, 10);
-  const archiveDir = path.join(config.docsRoot, config.archiveDir);
+  const fileRoot = findFileRoot(filePath, config);
+  const archiveDir = path.join(fileRoot, config.archiveDir);
   const isArchiving = config.lifecycle.archiveStatuses.has(newStatus) && !filePath.includes(`/${config.archiveDir}/`);
   const isUnarchiving = !config.lifecycle.archiveStatuses.has(newStatus) && filePath.includes(`/${config.archiveDir}/`);
   let finalPath = filePath;
@@ -43,7 +49,7 @@ export function runStatus(argv, config, opts = {}) {
       finalPath = targetPath;
     }
     if (isUnarchiving) {
-      const targetPath = path.join(config.docsRoot, path.basename(filePath));
+      const targetPath = path.join(fileRoot, path.basename(filePath));
       process.stdout.write(`${prefix} Would move: ${toRepoPath(filePath, config.repoRoot)} → ${toRepoPath(targetPath, config.repoRoot)}\n`);
       finalPath = targetPath;
     }
@@ -66,7 +72,7 @@ export function runStatus(argv, config, opts = {}) {
   }
 
   if (isUnarchiving) {
-    const targetPath = path.join(config.docsRoot, path.basename(filePath));
+    const targetPath = path.join(fileRoot, path.basename(filePath));
     if (existsSync(targetPath)) { die(`Target already exists: ${toRepoPath(targetPath, config.repoRoot)}`); }
     const result = gitMv(filePath, targetPath, config.repoRoot);
     if (result.status !== 0) { die(result.stderr || 'git mv failed.'); }
@@ -102,7 +108,8 @@ export function runArchive(argv, config, opts = {}) {
   const oldStatus = asString(parsed.status) ?? 'unknown';
 
   const today = new Date().toISOString().slice(0, 10);
-  const targetDir = path.join(config.docsRoot, config.archiveDir);
+  const archiveFileRoot = findFileRoot(filePath, config);
+  const targetDir = path.join(archiveFileRoot, config.archiveDir);
   const targetPath = path.join(targetDir, path.basename(filePath));
   const oldRepoPath = toRepoPath(filePath, config.repoRoot);
   const newRepoPath = toRepoPath(targetPath, config.repoRoot);
@@ -181,10 +188,8 @@ export function runTouch(argv, config, opts = {}) {
       const gitDay = gitDate.slice(0, 10);
       if (fmUpdated === gitDay) continue;
 
-      // Only sync if git is newer than frontmatter
-      const gitMs = new Date(gitDate).getTime();
-      const fmMs = fmUpdated ? new Date(fmUpdated).getTime() : 0;
-      if (fmMs >= gitMs) continue;
+      // Only sync if git is newer than frontmatter (compare date strings)
+      if (fmUpdated && fmUpdated >= gitDay) continue;
 
       if (!dryRun) {
         updateFrontmatter(filePath, { updated: gitDay });

package/src/lint.mjs

@@ -47,6 +47,13 @@ export function runLint(argv, config, opts = {}) {
       }
     }
 
+    // Comma-separated surface → surfaces array
+    const surfaceVal = asString(parsed.surface);
+    if (surfaceVal && surfaceVal.includes(',')) {
+      const values = surfaceVal.split(',').map(s => s.trim()).filter(Boolean);
+      fixes.push({ field: 'surface', oldValue: surfaceVal, newValue: values, type: 'split-to-array' });
+    }
+
     // Trailing whitespace in values
     for (const line of frontmatter.split('\n')) {
       const m = line.match(/^([A-Za-z0-9_-]+):(.+\S)\s+$/);
@@ -78,6 +85,8 @@ export function runLint(argv, config, opts = {}) {
         for (const f of fixes) {
           if (f.type === 'rename-key') {
             process.stdout.write(dim(`    ${f.oldValue} → ${f.newValue}\n`));
+          } else if (f.type === 'split-to-array') {
+            process.stdout.write(dim(`    ${f.field}: "${f.oldValue}" → surfaces: [${f.newValue.join(', ')}]\n`));
           } else if (f.type === 'eof') {
             process.stdout.write(dim(`    missing newline at end of file\n`));
           } else if (f.type === 'add') {
@@ -112,6 +121,7 @@ export function runLint(argv, config, opts = {}) {
     const keyRenames = [];
     let needsEofFix = false;
     const trimFixes = [];
+    const splitToArray = [];
 
     for (const f of fixes) {
       if (f.type === 'rename-key') {
@@ -120,12 +130,36 @@ export function runLint(argv, config, opts = {}) {
         needsEofFix = true;
       } else if (f.type === 'trim') {
         trimFixes.push(f);
+      } else if (f.type === 'split-to-array') {
+        splitToArray.push(f);
       } else {
         updates[f.field] = f.newValue;
       }
     }
 
     if (!dryRun) {
+      // Apply split-to-array fixes (surface: a, b → surfaces: array)
+      for (const sa of splitToArray) {
+        let raw = readFileSync(filePath, 'utf8');
+        const { frontmatter: fm } = extractFrontmatter(raw);
+        // Remove the scalar surface line
+        let newFm = fm.replace(new RegExp(`^${escapeRegex(sa.field)}:.*$`, 'm'), '').replace(/\n{2,}/g, '\n');
+        // Check if surfaces: array already exists
+        if (newFm.includes('surfaces:')) {
+          // Append new values to existing array
+          for (const val of sa.newValue) {
+            if (!newFm.includes(`- ${val}`)) {
+              newFm = newFm.replace(/^(surfaces:)$/m, `$1\n  - ${val}`);
+            }
+          }
+        } else {
+          // Create new surfaces: array
+          newFm += `\nsurfaces:\n${sa.newValue.map(v => `  - ${v}`).join('\n')}`;
+        }
+        raw = replaceFrontmatter(raw, newFm.trim());
+        writeFileSync(filePath, raw, 'utf8');
+      }
+
       // Apply key renames and trim fixes via raw string manipulation
       if (keyRenames.length > 0 || trimFixes.length > 0) {
         let raw = readFileSync(filePath, 'utf8');
@@ -165,6 +199,8 @@ export function runLint(argv, config, opts = {}) {
         process.stdout.write(`${prefix}  ${dim(`${f.oldValue} → ${f.newValue}`)}\n`);
       } else if (f.type === 'eof') {
         process.stdout.write(`${prefix}  ${dim('added newline at EOF')}\n`);
+      } else if (f.type === 'split-to-array') {
+        process.stdout.write(`${prefix}  ${dim(`${f.field}: "${f.oldValue}" → surfaces: [${f.newValue.join(', ')}]`)}\n`);
       } else if (f.type === 'add') {
         process.stdout.write(`${prefix}  ${dim(`add ${f.field}: ${f.newValue}`)}\n`);
       } else {

package/src/new.mjs

@@ -44,10 +44,12 @@ export function runNew(argv, config, opts = {}) {
   let status = 'active';
   let title = null;
   let templateName = null;
+  let rootName = 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] === '--root' && argv[i + 1]) { rootName = argv[++i]; continue; }
     if (argv[i] === '--list-templates') {
       listTemplates(config);
       return;
@@ -73,8 +75,20 @@ export function runNew(argv, config, opts = {}) {
   // Title
   const docTitle = title ?? name.replace(/[-_]/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
 
+  // Resolve target root
+  let targetRoot = config.docsRoot;
+  if (rootName) {
+    const roots = config.docsRoots || [config.docsRoot];
+    const match = roots.find(r => r.endsWith(rootName) || path.basename(r) === rootName);
+    if (!match) {
+      const available = roots.map(r => path.basename(r)).join(', ');
+      die(`Unknown root: ${rootName}\nAvailable: ${available}`);
+    }
+    targetRoot = match;
+  }
+
   // Path
-  const filePath = path.join(config.docsRoot, slug + '.md');
+  const filePath = path.join(targetRoot, slug + '.md');
   const repoPath = toRepoPath(filePath, config.repoRoot);
 
   if (existsSync(filePath)) {