dotmd-cli 0.14.11 → 0.15.0

package/README.md

@@ -88,7 +88,7 @@ Every document can have a `type` field in its frontmatter. Types determine which
 
 | Type | Purpose | Valid Statuses |
 |------|---------|----------------|
-| `plan` | Execution plans | `in-session`, `active`, `planned`, `blocked`, `done`, `archived` |
+| `plan` | Execution plans | `in-session`, `active`, `planned`, `blocked`, `partial`, `paused`, `awaiting`, `queued-after`, `archived` |
 | `doc` | Design docs, specs, ADRs, RFCs | `draft`, `active`, `review`, `reference`, `deprecated`, `archived` |
 | `research` | Investigations, audits, analysis | `active`, `reference`, `archived` |
 
@@ -106,6 +106,26 @@ dotmd export --type research              # export research only
 
 Customize types and their statuses in config with the `types` key. See [`dotmd.config.example.mjs`](dotmd.config.example.mjs).
 
+### What each plan status means
+
+The default plan vocabulary is shaped around the **unstuck-action test**: every stop-status should map to a distinct next move. If two statuses have the same unstuck-action, one is dead weight; if a single status covers several different actions, it's overloaded.
+
+| Status | Unstuck-action | When to use |
+|--------|----------------|-------------|
+| `in-session` | — | A Claude session is working on it right now. Don't pick up. |
+| `active` | Pick up | Ready to be worked on. |
+| `planned` | Wait for trigger | Queued; not yet ready to execute. |
+| `blocked` | **Monitor** | External arrival on its own schedule (hardware, vendor, third-party rollout). You can't speed it up. |
+| `partial` | **Spawn successors** | Shipped most of the plan; tail deferred. Body should reference successor plans tracking the tail. Visible but quiet (no nagging). |
+| `paused` | **Re-evaluate** | Intentionally set aside, no external dependency. Resume by deciding the work is still worth doing. Quiet. |
+| `awaiting` | **Ask** | Needs a human decision or input. NOT quiet — pings get forgotten, so this status generates stale pressure to chase the answer. |
+| `queued-after` | **Check predecessor** | Sequenced behind another plan; can start once that one ships. Quiet. |
+| `archived` | — | No longer relevant; auto-moved to the archive directory on transition. |
+
+Each *quiet* status (`partial`, `paused`, `queued-after`, `archived`) is exempt from stale-warning pressure but still appears in active scope and metrics — quietness is a presentation flag, not a closure flag. `awaiting` deliberately stays loud so unanswered questions don't decay into invisible backlog.
+
+> **Heads-up:** versions before 0.15 included a `done` plan status in the defaults. It saw effectively zero real-world use (plans went `in-session`/`active` → `archived` directly), so it was dropped from the built-in vocabulary. To finish a plan, run `dotmd archive <plan-file>` — or, if you preferred the previous behavior, add `done` back via the `types.plan.statuses` key in your config.
+
 ## Commands
 
 ```
@@ -390,8 +410,8 @@ dotmd rename old-name.md new-name        # renames + updates refs
 ### Migrate
 
 ```bash
-dotmd migrate status research exploration   # rename a status
-dotmd migrate module auth identity          # rename a module
+dotmd migrate status research scoping       # rename a status (e.g. for the 0.15 default-vocab change)
+dotmd migrate module auth identity           # rename a module
 ```
 
 ### Preset Aliases

package/bin/dotmd.mjs

@@ -140,6 +140,17 @@ Moves the document to the new status. If transitioning to an archive
 status, automatically moves the file to the archive directory and
 regenerates the index (if configured).
 
+Default plan statuses (each maps to a distinct unstuck-action):
+  in-session     A Claude session is working on it now
+  active         Ready to be picked up
+  planned        Queued for future work
+  blocked        External arrival wait — monitor (hardware, vendor, rollout)
+  partial        Shipped + deferred tail — spawn successor plans
+  paused         Intentionally set aside — re-evaluate to resume
+  awaiting       Needs human input/decision — chase the answer
+  queued-after   Sequenced behind another plan — check predecessor
+  archived       No longer relevant; auto-moved to archive directory
+
 Use --dry-run (-n) to preview changes without writing anything.`,
 
   check: `dotmd check — validate frontmatter and references
@@ -262,6 +273,10 @@ Options:
   --root <name>        Create in a specific docs root
   --list-templates     Show available templates
 
+For plans, the default status vocabulary is: in-session, active, planned,
+blocked, partial, paused, awaiting, queued-after, archived. Run
+\`dotmd status --help\` for what each one means.
+
 The filename is derived from <name> by slugifying it.
 Use --dry-run (-n) to preview without creating the file.`,
 
@@ -350,7 +365,7 @@ Finds all docs where the given field equals old-value and updates it
 to new-value.
 
 Examples:
-  dotmd migrate status research exploration
+  dotmd migrate status research scoping
   dotmd migrate module auth identity
 
 Use --dry-run (-n) to preview changes without writing anything.`,
@@ -368,12 +383,18 @@ modules, and reference fields to pre-populate the config.`,
 Shows all documents with type: plan, sorted by status.
 Supports all query flags (--status, --module, --json, --sort, --group, etc.)
 
+Default plan statuses: in-session, active, planned, blocked, partial,
+paused, awaiting, queued-after, archived. Run \`dotmd status --help\` for
+the unstuck-action behind each one.
+
 Examples:
-  dotmd plans                       # all plans
-  dotmd plans --status active       # active plans only
-  dotmd plans --module auth         # plans for the auth module
-  dotmd plans --group module        # all plans grouped by module
-  dotmd plans --json                # JSON output`,
+  dotmd plans                          # all plans
+  dotmd plans --status active          # active plans only
+  dotmd plans --status awaiting        # plans waiting on a human decision
+  dotmd plans --status partial,paused  # shipped-tail and parked plans
+  dotmd plans --module auth            # plans for the auth module
+  dotmd plans --group module           # all plans grouped by module
+  dotmd plans --json                   # JSON output`,
 
   stale: `dotmd stale — list stale documents
 

package/dotmd.config.example.mjs

@@ -25,20 +25,35 @@ export const excludeDirs = ['evidence'];
 //   context:        'expanded' | 'listed' | 'counted' (default: 'counted')
 //   staleDays:      number | null — stale threshold (default: null = never stale)
 //   requiresModule: boolean — require `module` frontmatter (default: false)
-//   terminal:       boolean — skip current_state/next_step warnings (default: false)
 //   archive:        boolean — auto-move to archiveDir on transition (default: false)
+//   terminal:       boolean — closed state; excluded from active-work stats/coverage scope (default: false)
 //   skipStale:      boolean — exempt from stale checks (default: false)
 //   skipWarnings:   boolean — exempt from validation warnings (default: false)
+//   quiet:          boolean — sugar for `skipStale: true, skipWarnings: true`. Use for visible-but-quiet
+//                   statuses (e.g. `partial`) where you want no nagging but DO want them in scope.
+//                   Setting `skipStale: false` or `skipWarnings: false` explicitly overrides the sugar.
+//
+// `terminal` and `quiet` are orthogonal. Mark a status `terminal` only when it represents closure
+// (excluded from active-work scope). Use `quiet` for noise suppression without closure semantics.
+//
+// Each plan stop-status maps to a distinct unstuck-action — the test for whether
+// the vocabulary earns its weight. blocked = monitor (external arrival on its own
+// schedule), awaiting = ask (chase the human/decision), queued-after = check the
+// predecessor, paused = re-evaluate, partial = spawn successor plans for the
+// deferred tail.
 //
 // export const types = {
 //   plan: {
 //     statuses: {
-//       'in-session': { context: 'expanded', staleDays: 1, requiresModule: true },
-//       'active':     { context: 'expanded', staleDays: 14, requiresModule: true },
-//       'planned':    { context: 'listed', staleDays: 30, requiresModule: true },
-//       'blocked':    { context: 'listed', staleDays: 30, requiresModule: true, skipStale: true },
-//       'done':       { context: 'counted', terminal: true, skipStale: true, skipWarnings: true },
-//       'archived':   { context: 'counted', archive: true, terminal: true, skipStale: true, skipWarnings: true },
+//       'in-session':   { context: 'expanded', staleDays: 1, requiresModule: true },
+//       'active':       { context: 'expanded', staleDays: 14, requiresModule: true },
+//       'planned':      { context: 'listed', staleDays: 30, requiresModule: true },
+//       'blocked':      { context: 'listed', staleDays: 30, requiresModule: true },
+//       'partial':      { context: 'expanded', requiresModule: true, quiet: true },     // shipped + deferred tail; visible, no nagging
+//       'paused':       { context: 'listed', requiresModule: true, quiet: true },       // intentionally set aside, no external dep
+//       'awaiting':     { context: 'listed', staleDays: 14, requiresModule: true },     // human input/decision wait — NOT quiet (pings get forgotten)
+//       'queued-after': { context: 'counted', requiresModule: true, quiet: true },      // sequenced behind another plan
+//       'archived':     { context: 'counted', archive: true, terminal: true, quiet: true },
 //     },
 //   },
 //   doc: {
@@ -48,7 +63,7 @@ export const excludeDirs = ['evidence'];
 //       'review':     { context: 'listed', staleDays: 14 },
 //       'reference':  { context: 'counted', skipStale: true },
 //       'deprecated': { context: 'counted', terminal: true, skipStale: true },
-//       'archived':   { context: 'counted', archive: true, terminal: true, skipStale: true, skipWarnings: true },
+//       'archived':   { context: 'counted', archive: true, terminal: true, quiet: true },
 //     },
 //   },
 // };
@@ -57,16 +72,20 @@ export const excludeDirs = ['evidence'];
 // When using array form, define behavior in separate statuses/lifecycle/taxonomy sections.
 // export const types = {
 //   plan: {
-//     statuses: ['in-session', 'active', 'planned', 'blocked', 'done', 'archived'],
-//     context: { expanded: ['in-session', 'active'], listed: ['planned', 'blocked'], counted: ['done', 'archived'] },
-//     staleDays: { 'in-session': 1, active: 14, planned: 30, blocked: 30 },
+//     statuses: ['in-session', 'active', 'planned', 'blocked', 'partial', 'paused', 'awaiting', 'queued-after', 'archived'],
+//     context: {
+//       expanded: ['in-session', 'active', 'partial'],
+//       listed: ['planned', 'blocked', 'paused', 'awaiting'],
+//       counted: ['queued-after', 'archived'],
+//     },
+//     staleDays: { 'in-session': 1, active: 14, planned: 30, blocked: 30, awaiting: 14 },
 //   },
 // };
 
 // Status workflow — fallback for docs without a type field. Order determines display grouping.
 // When using rich status definitions, statuses.order and staleDays are derived automatically.
 export const statuses = {
-  order: ['active', 'ready', 'planned', 'research', 'blocked', 'reference', 'archived'],
+  order: ['active', 'ready', 'planned', 'scoping', 'blocked', 'reference', 'archived'],
   // Additional statuses valid only in specific roots (merged with order)
   // Useful when different doc areas track different things (e.g. plans vs module docs)
   // rootStatuses: {
@@ -79,7 +98,7 @@ export const statuses = {
     ready: 14,
     planned: 30,
     blocked: 30,
-    research: 30,
+    scoping: 30,
   },
 };
 
@@ -111,7 +130,7 @@ export const index = {
 export const context = {
   expanded: ['active'],
   listed: ['ready', 'planned'],
-  counted: ['blocked', 'research', 'reference', 'archived'],
+  counted: ['blocked', 'scoping', 'reference', 'archived'],
   recentDays: 3,
   recentStatuses: ['active', 'ready', 'planned'],
   recentLimit: 10,

package/package.json

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

package/src/config.mjs

@@ -22,9 +22,13 @@ const DEFAULTS = {
 
   types: {
     plan: {
-      statuses: ['in-session', 'active', 'planned', 'blocked', 'done', 'archived'],
-      context: { expanded: ['in-session', 'active'], listed: ['planned', 'blocked'], counted: ['done', 'archived'] },
-      staleDays: { 'in-session': 1, active: 14, planned: 30, blocked: 30 },
+      statuses: ['in-session', 'active', 'planned', 'blocked', 'partial', 'paused', 'awaiting', 'queued-after', 'archived'],
+      context: {
+        expanded: ['in-session', 'active', 'partial'],
+        listed: ['planned', 'blocked', 'paused', 'awaiting'],
+        counted: ['queued-after', 'archived'],
+      },
+      staleDays: { 'in-session': 1, active: 14, planned: 30, blocked: 30, awaiting: 14 },
     },
     doc: {
       statuses: ['draft', 'active', 'review', 'reference', 'deprecated', 'archived'],
@@ -39,26 +43,26 @@ const DEFAULTS = {
   },
 
   statuses: {
-    order: ['active', 'ready', 'planned', 'research', 'blocked', 'reference', 'archived'],
+    order: ['active', 'ready', 'planned', 'scoping', 'blocked', 'reference', 'archived'],
     staleDays: {
       active: 14,
       ready: 14,
       planned: 30,
       blocked: 30,
-      research: 30,
+      scoping: 30,
     },
   },
 
   lifecycle: {
     archiveStatuses: ['archived'],
-    skipStaleFor: ['archived', 'reference'],
-    skipWarningsFor: ['archived'],
-    terminalStatuses: ['archived', 'deprecated', 'reference', 'done'],
+    skipStaleFor: ['archived', 'reference', 'partial', 'paused', 'queued-after'],
+    skipWarningsFor: ['archived', 'partial', 'paused', 'queued-after'],
+    terminalStatuses: ['archived', 'deprecated', 'reference'],
   },
 
   taxonomy: {
     surfaces: null,
-    moduleRequiredFor: [],
+    moduleRequiredFor: ['partial', 'paused', 'awaiting', 'queued-after'],
   },
 
   index: null,
@@ -66,7 +70,7 @@ const DEFAULTS = {
   context: {
     expanded: ['active'],
     listed: ['ready', 'planned'],
-    counted: ['blocked', 'research', 'reference', 'archived'],
+    counted: ['blocked', 'scoping', 'reference', 'archived'],
     recentDays: 3,
     recentStatuses: ['active', 'ready', 'planned'],
     recentLimit: 10,
@@ -92,7 +96,7 @@ const DEFAULTS = {
 
   presets: {
     plans: ['--type', 'plan', '--sort', 'status', '--all'],
-    stale: ['--status', 'active,ready,planned,blocked,research', '--stale', '--sort', 'updated', '--all'],
+    stale: ['--status', 'active,ready,planned,blocked,scoping', '--stale', '--sort', 'updated', '--all'],
     actionable: ['--status', 'active,ready', '--has-next-step', '--sort', 'updated', '--all'],
   },
 };
@@ -147,9 +151,13 @@ function normalizeRichStatuses(config, userConfig) {
         derived.staleDays[name] = p.staleDays;
       }
 
+      // `quiet: true` is sugar for skipStale + skipWarnings unless those are explicitly false.
+      const quietImpliesSkipStale = p.quiet && p.skipStale !== false;
+      const quietImpliesSkipWarnings = p.quiet && p.skipWarnings !== false;
+
       if (p.archive && !derived.archiveStatuses.includes(name)) derived.archiveStatuses.push(name);
-      if (p.skipStale && !derived.skipStaleFor.includes(name)) derived.skipStaleFor.push(name);
-      if (p.skipWarnings && !derived.skipWarningsFor.includes(name)) derived.skipWarningsFor.push(name);
+      if ((p.skipStale || quietImpliesSkipStale) && !derived.skipStaleFor.includes(name)) derived.skipStaleFor.push(name);
+      if ((p.skipWarnings || quietImpliesSkipWarnings) && !derived.skipWarningsFor.includes(name)) derived.skipWarningsFor.push(name);
       if (p.terminal && !derived.terminalStatuses.includes(name)) derived.terminalStatuses.push(name);
       if (p.requiresModule && !derived.moduleRequiredFor.includes(name)) derived.moduleRequiredFor.push(name);
 

package/src/frontmatter.mjs

@@ -22,11 +22,18 @@ export function replaceFrontmatter(raw, newFrontmatter) {
   return `---\n${newFrontmatter}\n---\n${body}`;
 }
 
-export function parseSimpleFrontmatter(text) {
+// Parses our YAML subset. Optional `warnings` array receives non-fatal
+// structural issues (e.g. duplicate keys) — caller decides whether to surface
+// them. Default behavior is unchanged: keep first occurrence of a duplicate
+// key, ignore subsequent ones.
+export function parseSimpleFrontmatter(text, warnings) {
   const data = {};
+  const seenDupKeys = new Set();
   let currentArrayKey = null;
+  let lineNum = 0;
 
   for (const rawLine of text.split('\n')) {
+    lineNum++;
     const line = rawLine.replace(/\r$/, '');
     if (!line.trim()) continue;
 
@@ -35,6 +42,11 @@ export function parseSimpleFrontmatter(text) {
       const [, key, rawValue] = keyMatch;
       if (Object.prototype.hasOwnProperty.call(data, key)) {
         currentArrayKey = null;
+        if (warnings && !seenDupKeys.has(key)) {
+          seenDupKeys.add(key);
+          warnings.push({ key, line: lineNum,
+            message: `Duplicate frontmatter key \`${key}\` at line ${lineNum}; keeping first occurrence, ignoring later values.` });
+        }
         continue;
       }
       if (!rawValue.trim()) {

package/src/health.mjs

@@ -76,7 +76,7 @@ export function runHealth(argv, config) {
 
   // Pipeline
   process.stdout.write(bold('Pipeline:') + '\n');
-  const pipeline = ['active', 'paused', 'ready', 'planned', 'blocked', 'research', 'archived'];
+  const pipeline = ['active', 'paused', 'ready', 'planned', 'blocked', 'scoping', 'archived'];
   for (const s of pipeline) {
     const count = byStatus[s] || 0;
     if (count > 0) {

package/src/index.mjs

@@ -120,7 +120,8 @@ export function parseDocFile(filePath, config) {
   const relativePath = toRepoPath(filePath, config.repoRoot);
   const raw = readFileSync(filePath, 'utf8');
   const { frontmatter, body } = extractFrontmatter(raw);
-  const parsedFrontmatter = parseSimpleFrontmatter(frontmatter);
+  const fmWarnings = [];
+  const parsedFrontmatter = parseSimpleFrontmatter(frontmatter, fmWarnings);
   const headingTitle = extractFirstHeading(body);
   const title = asString(parsedFrontmatter.title) ?? headingTitle ?? path.basename(filePath, '.md');
   const summary = asString(parsedFrontmatter.summary) ?? extractSummary(body) ?? null;
@@ -187,6 +188,10 @@ export function parseDocFile(filePath, config) {
     errors: [],
   };
 
+  for (const w of fmWarnings) {
+    doc.warnings.push({ path: relativePath, level: 'warning', message: w.message });
+  }
+
   validateDoc(doc, parsedFrontmatter, headingTitle, config);
   return doc;
 }

package/src/init.mjs

@@ -68,7 +68,7 @@ function generateDetectedConfig(scan, rootPath) {
   lines.push(`export const root = '${rootPath}';`);
   lines.push('');
 
-  const defaultOrder = ['active', 'ready', 'planned', 'research', 'blocked', 'reference', 'archived'];
+  const defaultOrder = ['active', 'ready', 'planned', 'scoping', '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];

package/src/render.mjs

@@ -368,8 +368,8 @@ export function renderCoverage(index, config) {
 }
 
 export function buildCoverage(index, config) {
-  const scope = [...new Set(index.docs.map(d => d.status).filter(s => s && !config.lifecycle.terminalStatuses.has(s) && !config.lifecycle.skipWarningsFor.has(s)))];
-  const scoped = index.docs.filter(doc => doc.status && !config.lifecycle.terminalStatuses.has(doc.status) && !config.lifecycle.skipWarningsFor.has(doc.status));
+  const scope = [...new Set(index.docs.map(d => d.status).filter(s => s && !config.lifecycle.terminalStatuses.has(s)))];
+  const scoped = index.docs.filter(doc => doc.status && !config.lifecycle.terminalStatuses.has(doc.status));
   const missingSurface = scoped.filter(doc => !doc.surface);
   const missingModule = scoped.filter(doc => !doc.module);
   const modulePlatform = scoped.filter(doc => doc.module === 'platform');
@@ -403,7 +403,7 @@ export function formatSnapshot(doc, config) {
 
 function _formatSnapshot(doc) {
   const state = doc.currentState ?? 'No current_state set';
-  if (/^active:|^ready:|^planned:|^research:|^blocked:|^archived:/i.test(state)) {
+  if (/^active:|^ready:|^planned:|^scoping:|^blocked:|^archived:/i.test(state)) {
     return state;
   }
   return `${capitalize(doc.status ?? 'unknown')}: ${state}`;

package/src/stats.mjs

@@ -8,10 +8,10 @@ function pct(n, total) {
 
 export function buildStats(index, config) {
   const docs = index.docs;
-  const scope = config.statusOrder.filter(s => !config.lifecycle.terminalStatuses.has(s) && !config.lifecycle.skipWarningsFor.has(s));
+  const scope = config.statusOrder.filter(s => !config.lifecycle.terminalStatuses.has(s));
   for (const typeSet of (config.typeStatuses?.values() ?? [])) {
     for (const s of typeSet) {
-      if (!config.lifecycle.terminalStatuses.has(s) && !config.lifecycle.skipWarningsFor.has(s) && !scope.includes(s)) scope.push(s);
+      if (!config.lifecycle.terminalStatuses.has(s) && !scope.includes(s)) scope.push(s);
     }
   }
   const scoped = docs.filter(d => scope.includes(d.status));

package/src/util.mjs

@@ -100,3 +100,17 @@ export function resolveDocPath(input, config) {
 
   return null;
 }
+
+// Resolve a reference path written in frontmatter or a body link.
+// Tries doc-relative first (the historical convention), then falls back to
+// repo-root-relative — so paths like `docs/foo/bar.md` written from any nesting
+// level resolve correctly. Returns the absolute path if either form exists,
+// else null.
+export function resolveRefPath(relPath, docDir, repoRoot) {
+  if (!relPath) return null;
+  const docRelative = path.resolve(docDir, relPath);
+  if (existsSync(docRelative)) return docRelative;
+  const repoRelative = path.resolve(repoRoot, relPath);
+  if (existsSync(repoRelative)) return repoRelative;
+  return null;
+}

package/src/validate.mjs

@@ -1,6 +1,5 @@
-import { existsSync } from 'node:fs';
 import path from 'node:path';
-import { asString } from './util.mjs';
+import { asString, resolveRefPath } from './util.mjs';
 import { getGitLastModified, getGitLastModifiedBatch } from './git.mjs';
 import { toRepoPath } from './util.mjs';
 
@@ -101,8 +100,7 @@ export function validateDoc(doc, frontmatter, headingTitle, config) {
   const allRefFields = [...(config.referenceFields.bidirectional || []), ...(config.referenceFields.unidirectional || [])];
   for (const field of allRefFields) {
     for (const relPath of (doc.refFields[field] || [])) {
-      const resolved = path.resolve(docDir, relPath);
-      if (!existsSync(resolved)) {
+      if (!resolveRefPath(relPath, docDir, config.repoRoot)) {
         doc.errors.push({ path: doc.path, level: 'error', message: `${field} entry \`${relPath}\` does not resolve to an existing file.` });
       }
     }
@@ -110,8 +108,7 @@ 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)) {
+    if (!resolveRefPath(link.href, docDir, config.repoRoot)) {
       doc.warnings.push({ path: doc.path, level: 'warning', message: `body link \`${link.href}\` does not resolve to an existing file.` });
     }
   }
@@ -128,7 +125,12 @@ export function checkBidirectionalReferences(docs, config) {
     const refs = new Set();
     for (const field of biFields) {
       for (const relPath of (doc.refFields[field] || [])) {
-        const resolved = path.resolve(docDir, relPath);
+        // Use the same doc-relative-then-repo-root fallback as validateDoc so
+        // both styles produce identical refMap keys; otherwise an entry like
+        // `docs/foo.md` (repo-root style) gets keyed as
+        // `<doc-parent>/docs/foo.md` and never matches the target's repo path.
+        const resolved = resolveRefPath(relPath, docDir, config.repoRoot)
+          ?? path.resolve(docDir, relPath);
         refs.add(toRepoPath(resolved, config.repoRoot));
       }
     }