dotmd-cli 0.77.3 → 0.79.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.77.3",
+  "version": "0.79.0",
   "description": "CLI for managing markdown documents with YAML frontmatter — index, query, validate, graph, export, lifecycle, and AI summaries.",
   "type": "module",
   "license": "MIT",
@@ -41,7 +41,7 @@
   },
   "homepage": "https://github.com/reowens/dotmd#readme",
   "scripts": {
-    "test": "node --test test/*.test.mjs",
+    "test": "node --import ./test/setup-env.mjs --test test/*.test.mjs",
     "postinstall": "node scripts/postinstall.mjs",
     "preversion": "node scripts/release-preflight.mjs && npm test",
     "version": "node scripts/prepare-version-commit.mjs",

package/scripts/postinstall.mjs

@@ -36,17 +36,17 @@ try {
 
   if ((process.env.RUNLIST_AUTO_PLUGIN_UPDATE ?? process.env.DOTMD_AUTO_PLUGIN_UPDATE) === '1' && hasClaude) {
     spawnSync('claude', ['plugin', 'update', 'dotmd@dotmd'], { stdio: 'ignore', timeout: 60000 });
-    process.stdout.write('dotmd: refreshed the Claude Code plugin — restart your session (or /reload-plugins) to apply.\n');
+    process.stdout.write('runlist: refreshed the Claude Code plugin — restart your session (or /reload-plugins) to apply.\n');
   } else {
     // The CLI just installed fresh, so only the plugin can be stale — point at
     // the targeted refresh rather than the full `dotmd update` (CLI + plugin).
     const nudge = hasClaude
-      ? 'dotmd CLI installed. Using the Claude Code plugin? Run `dotmd update --plugin-only` to refresh it, then restart.'
-      : 'dotmd CLI installed.';
+      ? 'runlist CLI installed. Using the Claude Code plugin? Run `runlist update --plugin-only` to refresh it, then restart.'
+      : 'runlist CLI installed.';
     process.stdout.write(`${nudge}\n`);
   }
   if (hasOpencode) {
-    process.stdout.write('dotmd: OpenCode detected — run `dotmd install opencode` for per-session plan ownership and a session-start briefing.\n');
+    process.stdout.write('runlist: OpenCode detected — run `runlist install opencode` for per-session plan ownership and a session-start briefing.\n');
   }
 } catch {
   // Best effort only — never break the install.

package/src/atomic-mutation.mjs

@@ -203,7 +203,7 @@ function transactionRepairMessage(manifestPath, manifest, reason) {
     ...(manifest.gitIndex?.retainedPaths ?? []),
   ].filter(Boolean);
   return `${reason}\nTransaction recovery refused to guess. Manifest: ${manifestPath}\n` +
-    `Start with \`dotmd doctor --transactions\` — it reports this transaction's state and resolves it when the canonical files agree on one generation.\n` +
+    `Start with \`runlist doctor --transactions\` — it reports this transaction's state and resolves it when the canonical files agree on one generation.\n` +
     `If it reports the generations as ambiguous, inspect the canonical files and recovery artifacts, then restore one complete generation and remove the manifest:\n` +
     `${artifacts.map(item => `  ${item}`).join('\n') || '  (no content artifacts)'}`;
 }

package/src/baton.mjs

@@ -1,7 +1,7 @@
-import { readFileSync, existsSync, writeFileSync } from 'node:fs';
+import { readFileSync, existsSync, writeFileSync, realpathSync } from 'node:fs';
 import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
-import { asString, toRepoPath, die, warn } from './util.mjs';
+import { asString, toRepoPath, die, warn, isArchivedPath, resolveRefPath } from './util.mjs';
 import { buildIndex, resolveDocArg } from './index.mjs';
 import { preparePromptDocument, runNew, readBodyInput, readPipedBodyInput } from './new.mjs';
 import { ensurePlanCompletionBeforeRelease, planHasPendingCompletion, runSet } from './lifecycle.mjs';
@@ -26,11 +26,42 @@ export function findOwnedPlan(config, index = null) {
   return { plan: clean && owned.length === 1 ? owned[0] : null, via: clean && owned.length === 1 ? 'ownership' : null, inSession, owned, diagnostics: records.diagnostics ?? [] };
 }
 
-const BODY_USAGE = `dotmd baton needs the resume draft as its body. Write 10–20 lines first — the next concrete decision plus any gotchas, NOT a recap of the plan — then:
-  dotmd baton @/tmp/draft.md             # body from file (preferred)
-  cat /tmp/draft.md | dotmd baton        # body from stdin
-  dotmd baton --message "..."            # one-liner
-No plan in-session? Name the handoff instead: dotmd baton <slug> @/tmp/draft.md`;
+// One line that says what is missing, then one example. Baton never drafts the
+// resume itself: the session that did the work is the only one that knows the
+// next decision, and a prompt assembled from frontmatter reads like a handoff
+// while carrying nothing the plan doesn't already say.
+const BODY_USAGE = `Nothing saved: baton needs the resume you wrote, passed as @<file> or - (stdin).
+  runlist baton [<plan-or-slug>] @/tmp/draft.md`;
+
+// A handoff that lands beside a pending one leaves two prompts for the same
+// work, and the next session picks whichever sorts first. Baton used to step to
+// `resume-<x>-2` silently; it now refuses and names what is waiting, so the
+// older prompt is consumed or archived on purpose. Plan mode also catches a
+// pending prompt under a different name that links the same plan.
+function pendingHandoffs(promptPath, planPath, config) {
+  const found = new Set();
+  if (existsSync(promptPath)) found.add(toRepoPath(promptPath, config.repoRoot));
+  if (planPath) {
+    const planReal = realpathSync(planPath);
+    const index = buildIndex(config, { fast: true, invokeHooks: false });
+    for (const doc of index.docs) {
+      if (doc.type !== 'prompt' || doc.status === 'archived' || isArchivedPath(doc.path, config)) continue;
+      const abs = path.resolve(config.repoRoot, doc.path);
+      let planRef;
+      try { planRef = asString(parseSimpleFrontmatter(extractFrontmatter(readFileSync(abs, 'utf8')).frontmatter).plan); }
+      catch { continue; }
+      const linked = planRef ? resolveRefPath(planRef, path.dirname(abs), config.repoRoot) : null;
+      if (linked && realpathSync(linked) === planReal) found.add(doc.path);
+    }
+  }
+  return [...found];
+}
+
+function refusePendingHandoff(pending) {
+  const lines = pending.map(p => `  ${p}`).join('\n');
+  const slug = path.basename(pending[0], '.md');
+  die(`Nothing saved: a handoff for this is already pending:\n${lines}\nUse it (\`runlist use ${slug}\`) or archive it (\`runlist prompts archive ${pending[0]}\`), then run baton again.`);
+}
 
 // Is this positional a filesystem reference (must resolve, typos die) or a
 // bare word (may be a plan slug, may be a brand-new handoff name)?
@@ -56,7 +87,7 @@ export async function runBaton(argv, config, opts = {}) {
     if (a === '--force') { force = true; continue; }
     if (a === '--json') continue;
     if (!a.startsWith('-') || a === '-' || a.startsWith('@')) { positionals.push(a); continue; }
-    die(`Unknown flag for \`dotmd baton\`: ${a}`);
+    die(`Unknown flag for \`runlist baton\`: ${a}`);
   }
 
   let planArg = null;
@@ -107,13 +138,21 @@ export async function runBaton(argv, config, opts = {}) {
     if (owned.plan) {
       planPath = path.resolve(config.repoRoot, owned.plan.path);
     } else if (owned.owned?.length > 1) {
-      die(`Multiple plans are owned by this session; pass one explicitly:\n${owned.owned.map(d => '  dotmd baton ' + d.path + ' @/tmp/draft.md').join('\n')}`);
+      die(`Multiple plans are owned by this session; pass one explicitly:\n${owned.owned.map(d => '  runlist baton ' + d.path + ' @/tmp/draft.md').join('\n')}`);
     } else {
       const diagnostics = owned.diagnostics?.length ? `\nIgnored ownership records:\n${owned.diagnostics.map(d => `  ${d}`).join('\n')}` : '';
-      die(`No valid in-session plan is owned by this session, so baton needs a name for the resume prompt:\n  dotmd baton <slug> @/tmp/draft.md      # saves resume-<slug>, touches nothing else\nHanding off a specific plan? dotmd baton <plan-file> @/tmp/draft.md${diagnostics}`);
+      die(`No valid in-session plan is owned by this session, so baton needs a name for the resume prompt:\n  runlist baton <slug> @/tmp/draft.md      # saves resume-<slug>, touches nothing else\nHanding off a specific plan? runlist baton <plan-file> @/tmp/draft.md${diagnostics}`);
     }
   }
 
+  const nameBase = planPath ? path.basename(planPath, '.md') : promptSlug;
+  const slugBase = nameBase.startsWith('resume-') ? nameBase : `resume-${nameBase}`;
+  const refuseIfPending = () => {
+    const target = preparePromptDocument(slugBase, body, config, { dryRun: true });
+    const pending = pendingHandoffs(target.filePath, planPath, config);
+    if (pending.length) refusePendingHandoff(pending);
+  };
+
   let repoPath = null;
   let oldStatus = null;
   let ownershipPath = null;
@@ -123,7 +162,7 @@ export async function runBaton(argv, config, opts = {}) {
     const raw = readFileSync(planPath, 'utf8');
     const { frontmatter: fmRaw } = extractFrontmatter(raw);
     if (!fmRaw) {
-      die(`${repoPath} has no frontmatter block — baton can't flip its status.\nFix the doc first (\`dotmd bulk-tag ${repoPath} --type plan --status in-session\`), or save the prompt without a status flip: dotmd baton ${path.basename(planPath, '.md')} @/tmp/draft.md`);
+      die(`${repoPath} has no frontmatter block — baton can't flip its status.\nFix the doc first (\`runlist bulk-tag ${repoPath} --type plan --status in-session\`), or save the prompt without a status flip: runlist baton ${path.basename(planPath, '.md')} @/tmp/draft.md`);
     }
     const fm = parseSimpleFrontmatter(fmRaw);
     const docType = asString(fm.type);
@@ -137,21 +176,22 @@ export async function runBaton(argv, config, opts = {}) {
       die(`Invalid status \`${status}\` for type \`${docType ?? 'plan'}\`\nValid: ${[...validStatuses].join(', ')}`);
     }
     if (status === 'in-session') {
-      die('`dotmd baton --status in-session` contradicts baton release semantics. Choose active/paused/awaiting/partial/blocked.');
+      die('`runlist baton --status in-session` contradicts baton release semantics. Choose active/paused/awaiting/partial/blocked.');
     }
     assertPlanMutationAuthorized(repoPath, config, { sessionId: authoritativeSessionId(), force });
+    // Before the plan-completion step: a refusal must leave nothing changed.
+    refuseIfPending();
     ownershipPath = readPlanOwnership(repoPath, config)?.recordPath ?? null;
     if (!dryRun) ensurePlanCompletionBeforeRelease(repoPath, config, { testHooks: opts.testHooks });
     else if (planHasPendingCompletion(repoPath, config)) process.stderr.write(`${dim('[dry-run]')} Pending claim completion would block this release.\n`);
   } else {
+    refuseIfPending();
     if (statusFlag) warn(`--status ignored — no plan involved in this handoff (saving the prompt only).`);
     if (note) warn(`--note ignored — no plan involved in this handoff (notes land in a plan's Version History).`);
   }
 
   // Plan mode publishes the already-stamped prompt, status/history update, and
   // ownership release in one transaction. Slug mode has no plan transaction.
-  const nameBase = planPath ? path.basename(planPath, '.md') : promptSlug;
-  const slugBase = nameBase.startsWith('resume-') ? nameBase : `resume-${nameBase}`;
   let createdSlug = null;
   let archiveResult = null;
   let statusChanged = false;
@@ -162,49 +202,45 @@ export async function runBaton(argv, config, opts = {}) {
   if (json) process.stdout.write = chunk => { muted.push(String(chunk)); return true; };
   try {
   if (!planPath) {
-    for (let n = 1; n <= 9 && !createdSlug; n++) {
-      const slug = n === 1 ? slugBase : `${slugBase}-${n}`;
-      try {
-        const prepared = preparePromptDocument(slug, body, config, { dryRun });
-        newResult = await runNew(['prompt', slug, '--body', body], config, { dryRun, deferIndex: true });
-        createdSlug = slug;
-        promptRepoPath = prepared.repoPath;
-      }
-      catch (err) { if (!/File already exists/.test(String(err?.message))) throw err; }
+    const prepared = preparePromptDocument(slugBase, body, config, { dryRun });
+    try {
+      newResult = await runNew(['prompt', slugBase, '--body', body], config, { dryRun, deferIndex: true });
+    } catch (err) {
+      // Lost a race with another baton between the pending check and the write.
+      if (/File already exists/.test(String(err?.message))) refusePendingHandoff([prepared.repoPath]);
+      throw err;
     }
+    createdSlug = slugBase;
+    promptRepoPath = prepared.repoPath;
   } else {
-    for (let n = 1; n <= 9 && !createdSlug; n++) {
-      const candidate = n === 1 ? slugBase : `${slugBase}-${n}`;
-      const prepared = preparePromptDocument(candidate, body, config, { plan: repoPath, dryRun });
-      if (existsSync(prepared.filePath)) continue;
-      const setArgs = [status, planPath];
-      if (force) setArgs.push('--force');
-      if (note) setArgs.push('--note', note);
-      try {
-        if (dryRun) process.stdout.write(`${dim('[dry-run]')} Would create: ${prepared.repoPath}\n`);
-        archiveResult = await runSet(setArgs, config, {
-          dryRun,
-          viaBaton: true,
-          testHooks: opts.testHooks,
-          creations: dryRun ? [] : [{ path: prepared.filePath, content: prepared.content }],
-          deferIndex: true,
-        });
-        createdSlug = prepared.slug;
-        promptRepoPath = prepared.repoPath;
-        statusChanged = oldStatus !== status;
-        if (!dryRun) {
-          try { config.hooks.onNew?.({ path: prepared.repoPath, status: 'pending', title: prepared.slug, type: 'prompt' }); }
-          catch (err) { warn(`Hook 'onNew' threw: ${err.message}`); }
-        }
-      } catch (err) {
-        if (!/Destination already exists|File already exists/.test(String(err?.message))) throw err;
-      }
+    const prepared = preparePromptDocument(slugBase, body, config, { plan: repoPath, dryRun });
+    const setArgs = [status, planPath];
+    if (force) setArgs.push('--force');
+    if (note) setArgs.push('--note', note);
+    try {
+      if (dryRun) process.stdout.write(`${dim('[dry-run]')} Would create: ${prepared.repoPath}\n`);
+      archiveResult = await runSet(setArgs, config, {
+        dryRun,
+        viaBaton: true,
+        testHooks: opts.testHooks,
+        creations: dryRun ? [] : [{ path: prepared.filePath, content: prepared.content }],
+        deferIndex: true,
+      });
+    } catch (err) {
+      if (/Destination already exists|File already exists/.test(String(err?.message))) refusePendingHandoff([prepared.repoPath]);
+      throw err;
+    }
+    createdSlug = prepared.slug;
+    promptRepoPath = prepared.repoPath;
+    statusChanged = oldStatus !== status;
+    if (!dryRun) {
+      try { config.hooks.onNew?.({ path: prepared.repoPath, status: 'pending', title: prepared.slug, type: 'prompt' }); }
+      catch (err) { warn(`Hook 'onNew' threw: ${err.message}`); }
     }
   }
   } finally {
     if (json) process.stdout.write = originalStdoutWrite;
   }
-  if (!createdSlug) die(`Could not find a free prompt slug for ${slugBase} (tried ${slugBase}-2 … ${slugBase}-9).`);
 
   // A release status can FILE the plan into a bucket (`lifecycle.filedStatuses`,
   // e.g. paused → docs/plans/held/). The prompt is created inside the same

package/src/check-collapse.mjs

@@ -14,19 +14,19 @@ const CATEGORIES = [
     key: 'updated-behind-git',
     match: /^frontmatter `updated:.*` is behind git history/,
     label: 'docs have `updated` behind git history',
-    fix: 'dotmd touch --git',
+    fix: 'runlist touch --git',
   },
   {
     key: 'singular-module',
-    match: /^`module:` \(singular\) is deprecated.*Run `dotmd lint --fix`/,
+    match: /^`module:` \(singular\) is deprecated.*Run `runlist lint --fix`/,
     label: 'docs use deprecated singular `module:`',
-    fix: 'dotmd lint --fix',
+    fix: 'runlist lint --fix',
   },
   {
     key: 'singular-surface',
-    match: /^`surface:` \(singular\) is deprecated.*Run `dotmd lint --fix`/,
+    match: /^`surface:` \(singular\) is deprecated.*Run `runlist lint --fix`/,
     label: 'docs use deprecated singular `surface:`',
-    fix: 'dotmd lint --fix',
+    fix: 'runlist lint --fix',
   },
 ];
 

package/src/claude-commands.mjs

@@ -16,7 +16,10 @@ import path from 'node:path';
 // NEVER touched. Every dotmd-stamped file is fair game, including legacy ones
 // dotmd no longer generates (e.g. the old baton.md).
 
-const GENERATED_MARKER = '<!-- dotmd-generated:';
+// Nothing writes these files any more, so only the legacy banner can exist in
+// the wild; the current spelling is accepted too so a banner-gated teardown
+// never depends on which name stamped the file.
+const GENERATED_MARKERS = ['<!-- runlist-generated:', '<!-- dotmd-generated:'];
 
 // The marker sits just below the YAML frontmatter Claude Code surfaces as the
 // command description. That description can be long (the retired plans.md baked
@@ -25,7 +28,8 @@ const GENERATED_MARKER = '<!-- dotmd-generated:';
 // are tiny command files, so reading them in full is cheap.
 function isGeneratedCommandFile(filePath) {
   try {
-    return readFileSync(filePath, 'utf8').includes(GENERATED_MARKER);
+    const contents = readFileSync(filePath, 'utf8');
+    return GENERATED_MARKERS.some(marker => contents.includes(marker));
   } catch {
     return false;
   }

package/src/commands.mjs

@@ -92,16 +92,16 @@ const definitions = [
   command('prompts', mutates('managed sources/destinations by subcommand'), 'workflow', [
     form('', { options: [flag('--json'), value('--status'), flag('--include-archived'), value('--sort'), value('--limit'), flag('--all')] }),
     form('list', { subcommands: ['list', 'status'], options: [flag('--json'), value('--status'), flag('--include-archived'), value('--sort'), value('--limit'), flag('--all')] }),
-    form('next', { subcommands: ['next'] }),
-    form('use [file]', { subcommands: ['use', 'resume'], args: positionals(0, 1), options: [flag('--no-index'), flag('--show-files'), flag('--force')] }),
+    form('next', { subcommands: ['next'], options: [flag('--no-claim')] }),
+    form('use [file]', { subcommands: ['use', 'resume'], args: positionals(0, 1), options: [flag('--no-index'), flag('--show-files'), flag('--force'), flag('--no-claim')] }),
     form('show [file...]', { subcommands: ['show', 'peek'], args: positionals(0, Infinity), options: [flag('--json'), flag('--all'), value('--limit')] }),
     form('archive <file>', { subcommands: ['archive'], args: positionals(1, 1), options: [flag('--no-index'), flag('--show-files')] }),
     form('new <slug> [body...]', { subcommands: ['new'], args: positionals(1, Infinity), options: [value('--body', '--message'), value('--title'), value('--status')] }),
     form('hold <file>', { subcommands: ['hold', 'shelve'], args: positionals(1, 1) }),
     form('unhold <file>', { subcommands: ['unhold', 'unshelve'], args: positionals(1, 1) }),
   ], { aliases: ['prompt'] }),
-  command('use', mutates('managed source when starting/consuming; docs remain read-only'), 'workflow', [form('[file]', { args: positionals(0, 1), options: [flag('--json'), flag('--full'), flag('--no-index'), flag('--show-files'), flag('--force')] })]),
-  command('next', mutates('managed prompt source and same-root archive destination'), 'workflow', [form('', { options: [flag('--json'), flag('--no-index'), flag('--show-files'), flag('--force')] })]),
+  command('use', mutates('managed source when starting/consuming; docs remain read-only'), 'workflow', [form('[file]', { args: positionals(0, 1), options: [flag('--json'), flag('--full'), flag('--no-index'), flag('--show-files'), flag('--force'), flag('--no-claim')] })]),
+  command('next', mutates('managed prompt source and same-root archive destination'), 'workflow', [form('', { options: [flag('--json'), flag('--no-index'), flag('--show-files'), flag('--force'), flag('--no-claim')] })]),
   command('baton', mutates('managed plan/prompt sources and managed prompt destination'), 'workflow', [form('[plan|slug] <@<file>|->', { args: positionals(0, 2), options: [value('--status'), value('--note'), value('--body', '--message'), flag('--force'), flag('--json')] })]),
   command('runlist', mutates('managed hubs/children and managed scaffold destinations'), 'workflow', [
     form('<hub>', { args: positionals(1, 1), options: [flag('--json')] }),
@@ -244,7 +244,7 @@ export function commandCompletionWords(name) {
 export function commandUsage(name) {
   const definition = commandDefinition(name);
   if (!definition) return null;
-  return definition.forms.map(commandForm => `dotmd ${definition.name}${commandForm.syntax ? ` ${commandForm.syntax}` : ''}`).join('\n');
+  return definition.forms.map(commandForm => `runlist ${definition.name}${commandForm.syntax ? ` ${commandForm.syntax}` : ''}`).join('\n');
 }
 
 function optionMap(forms) {
@@ -267,12 +267,12 @@ function scanArgs(name, argv, options, passthrough = false, dashPositionalsAfter
     if (!option) {
       if (passthrough) continue;
       if (positional.length >= dashPositionalsAfter) { positional.push(arg); continue; }
-      throw new Error(`Unknown flag for \`dotmd ${name}\`: ${arg}`);
+      throw new Error(`Unknown flag for \`runlist ${name}\`: ${arg}`);
     }
     if (option.arity === 1) {
       const next = argv[i + 1];
       if (next === undefined || options.has(next)) {
-        throw new Error(`Missing value for \`${arg}\` in \`dotmd ${name}\`.`);
+        throw new Error(`Missing value for \`${arg}\` in \`runlist ${name}\`.`);
       }
       i += 1;
     } else if (option.arity === 'optional' && argv[i + 1] !== undefined && !argv[i + 1].startsWith('-')) {
@@ -317,7 +317,7 @@ export function validateCommandArgs(name, argv, { preset = false } = {}) {
   const preliminary = scanArgs(canonical, normalized, allOptions, allPassthrough, dashPositionalsAfter);
   const selected = definition.forms.find(commandForm => commandForm.subcommands.includes(preliminary[0]))
     ?? definition.forms.find(commandForm => commandForm.subcommands.length === 0);
-  if (!selected) throw new Error(`Unknown subcommand for \`dotmd ${canonical}\`: ${preliminary[0] ?? '(missing)'}`);
+  if (!selected) throw new Error(`Unknown subcommand for \`runlist ${canonical}\`: ${preliminary[0] ?? '(missing)'}`);
   const selectedOptions = optionMap([selected]);
   const positional = scanArgs(canonical, normalized, selectedOptions, selected.passthrough, selected.dashPositionalsAfter);
   const args = selected.subcommands.includes(positional[0]) ? positional.slice(1) : positional;

package/src/config.mjs

@@ -218,10 +218,10 @@ function normalizeRichStatuses(config, userConfig) {
       const skipStaleEffective = p.skipStale === true || quietImpliesSkipStale;
       const skipWarningsEffective = p.skipWarnings === true || quietImpliesSkipWarnings;
       if (skipStaleEffective && p.staleDays != null) {
-        warn(`dotmd config: status "${typeName}.${name}" has skipStale: true and staleDays: ${p.staleDays} — staleDays is ignored. Drop one to silence this warning.`);
+        warn(`runlist config: status "${typeName}.${name}" has skipStale: true and staleDays: ${p.staleDays} — staleDays is ignored. Drop one to silence this warning.`);
       }
       if (skipWarningsEffective && p.requiresModule) {
-        warn(`dotmd config: status "${typeName}.${name}" has skipWarnings: true and requiresModule: true — the module requirement can never fire. Drop one to silence this warning.`);
+        warn(`runlist config: status "${typeName}.${name}" has skipWarnings: true and requiresModule: true — the module requirement can never fire. Drop one to silence this warning.`);
       }
 
       if (p.archive && !derived.archiveStatuses.includes(name)) derived.archiveStatuses.push(name);

package/src/deps.mjs

@@ -252,7 +252,7 @@ function renderFlatJson(graph, forwardMap, reverseMap, docByPath) {
 export function runUnblocks(argv, config) {
   const input = argv.find(a => !a.startsWith('-'));
   const json = argv.includes('--json');
-  if (!input) die('Usage: dotmd unblocks <file>');
+  if (!input) die('Usage: runlist unblocks <file>');
 
   const filePath = resolveDocArg(input, config);
   const repoPath = toRepoPath(filePath, config.repoRoot);

package/src/doctor.mjs

@@ -99,7 +99,7 @@ function runDoctorTransactions(argv, config, opts = {}) {
   }
   if (resolvable.length) {
     process.stdout.write(`\n${resolvable.length} resolvable — the canonical files already agree on one generation.\n`);
-    process.stdout.write(dim('Run `dotmd doctor --transactions --apply` to clear them (no document content is touched).\n'));
+    process.stdout.write(dim('Run `runlist doctor --transactions --apply` to clear them (no document content is touched).\n'));
   }
   const stuck = report.filter(item => !item.resolvable && !clearedIds.has(item.id) && (item.status === 'failed-manual' || !item.readable));
   if (stuck.length) {
@@ -152,7 +152,7 @@ async function runDoctorClaims(argv, config, opts = {}) {
         // status into. Deciding by existence here rather than by catching
         // runSet's "File not found" keeps the bypass narrow and explicit.
         if (existsSync(path.resolve(config.repoRoot, claim.plan))) {
-          await runSet(['active', claim.plan], config, { force: true, sessionId: operator, note: 'Claim released by `dotmd doctor --claims` — the owning session was gone.' });
+          await runSet(['active', claim.plan], config, { force: true, sessionId: operator, note: 'Claim released by `runlist doctor --claims` — the owning session was gone.' });
         } else {
           releaseVanishedPlanClaim(claim, config);
           claim.vanished = true;
@@ -201,13 +201,13 @@ async function runDoctorClaims(argv, config, opts = {}) {
   const pendingDead = dead.filter(claim => !releasedSet.has(claim.plan));
   if (pendingDead.length) {
     process.stdout.write(yellow(`\n${pendingDead.length} held by a session whose process is gone.\n`));
-    process.stdout.write(dim('Run `dotmd doctor --claims --apply` to release them.\n'));
+    process.stdout.write(dim('Run `runlist doctor --claims --apply` to release them.\n'));
   }
   const unjudgeable = claims.filter(claim =>
     !claim.corrupt && claim.liveness !== 'dead' && !releasedSet.has(claim.plan));
   if (unjudgeable.length && olderThanMs === null) {
     process.stdout.write(dim(`\n${unjudgeable.length} cannot be judged from here — no owning process was recorded, or it is on another machine.\n`));
-    process.stdout.write(dim('If you know those sessions are over: `dotmd doctor --claims --apply --older-than 24h`.\n'));
+    process.stdout.write(dim('If you know those sessions are over: `runlist doctor --claims --apply --older-than 24h`.\n'));
   }
 }
 
@@ -228,10 +228,10 @@ function runDoctorSession(argv) {
   for (const line of identity.advice) process.stdout.write(`    → ${line}\n`);
 
   process.stdout.write('\n' + bold('Host integration\n'));
-  if (oc.foreign) process.stdout.write(`  ${yellow('!')} opencode: a dotmd.js dotmd did not write — ${oc.path}\n`);
+  if (oc.foreign) process.stdout.write(`  ${yellow('!')} opencode: a dotmd.js runlist did not write — ${oc.path}\n`);
   else if (!oc.exists) process.stdout.write(`  ${dim('·')} opencode: not installed — ${dim(oc.path)}\n`);
-  else process.stdout.write(`  ${oc.stale ? yellow('!') : green('✓')} opencode: ${oc.version}${oc.stale ? ` (CLI is ${dotmdVersion()} — run \`dotmd update\`)` : ''}\n`);
-  process.stdout.write(dim('  Claude Code ships as a plugin — `dotmd install` reports both hosts.\n'));
+  else process.stdout.write(`  ${oc.stale ? yellow('!') : green('✓')} opencode: ${oc.version}${oc.stale ? ` (CLI is ${dotmdVersion()} — run \`runlist update\`)` : ''}\n`);
+  process.stdout.write(dim('  Claude Code ships as a plugin — `runlist install` reports both hosts.\n'));
 }
 
 export function runDoctor(argv, config, opts = {}) {
@@ -273,7 +273,7 @@ export function runDoctor(argv, config, opts = {}) {
   const modeNote = dryRun
     ? dim('[preview — run with --apply to write]')
     : dim('[applying changes]');
-  process.stdout.write(bold('dotmd doctor') + ' ' + modeNote + '\n\n');
+  process.stdout.write(bold('runlist doctor') + ' ' + modeNote + '\n\n');
   if (dryRun) {
     const skippedHooks = ['validate', 'transformDoc', 'formatSnapshot', 'renderCheck']
       .filter(name => typeof config.hooks?.[name] === 'function');
@@ -335,7 +335,7 @@ export function runDoctor(argv, config, opts = {}) {
       process.stdout.write('[dry-run] No retired slash-command files to remove.\n');
     } else {
       for (const r of wouldRemove) {
-        process.stdout.write(`[dry-run] Would remove retired .claude/commands/${r.name} (guidance now ships via the dotmd plugin).\n`);
+        process.stdout.write(`[dry-run] Would remove retired .claude/commands/${r.name} (guidance now ships via the runlist plugin).\n`);
       }
     }
   } else {
@@ -344,7 +344,7 @@ export function runDoctor(argv, config, opts = {}) {
       process.stdout.write('Nothing to clean up.\n');
     } else {
       for (const r of removed) {
-        process.stdout.write(`${green('Removed')} retired .claude/commands/${r.name} (guidance now ships via the dotmd plugin)\n`);
+        process.stdout.write(`${green('Removed')} retired .claude/commands/${r.name} (guidance now ships via the runlist plugin)\n`);
       }
     }
   }
@@ -369,7 +369,7 @@ export function runDoctor(argv, config, opts = {}) {
     process.stdout.write('\n' + bold('Session identity') + '\n');
     process.stdout.write(`${yellow('!')} ${identity.summary}\n`);
     for (const line of identity.advice) process.stdout.write(dim(`  → ${line}\n`));
-    process.stdout.write(dim('  `dotmd doctor --session` for the full picture.\n'));
+    process.stdout.write(dim('  `runlist doctor --session` for the full picture.\n'));
   }
 }
 
@@ -387,7 +387,7 @@ function findDeprecatedCommandMentions(config) {
   for (const filePath of docs) {
     let raw = '';
     try { raw = readFileSync(filePath, 'utf8'); } catch { continue; }
-    if (/\bdotmd status\b/.test(raw) || /\bdotmd (pickup|unpickup|release|finish)\b/.test(raw)) {
+    if (/\b(?:dotmd|runlist|rl) status\b/.test(raw) || /\b(?:dotmd|runlist|rl) (pickup|unpickup|release|finish)\b/.test(raw)) {
       matches.push(toRepoPath(filePath, config.repoRoot));
     }
   }
@@ -445,7 +445,7 @@ function runDoctorProject(config, { json = false } = {}) {
     return result;
   }
 
-  process.stdout.write(bold('dotmd doctor --project') + '\n\n');
+  process.stdout.write(bold('runlist doctor --project') + '\n\n');
   process.stdout.write(`- running CLI version: ${result.cliVersion ?? 'unknown'}\n`);
   process.stdout.write(`- package dependency: ${result.packageDependency ?? '(none found)'}\n`);
   process.stdout.write(`- stale Claude commands: ${claudeCommandWarnings.length}\n`);
@@ -456,18 +456,18 @@ function runDoctorProject(config, { json = false } = {}) {
     process.stdout.write('- docs mentioning deprecated commands: 0\n');
   }
   if (docsWithoutFrontmatter.length) {
-    process.stdout.write(yellow(`- docs without a frontmatter block: ${docsWithoutFrontmatter.length} — every status verb (\`set\`, \`archive\`, \`baton\`) dies on these. Fix: dotmd bulk-tag <file> --type <type> --status <status>`) + '\n');
+    process.stdout.write(yellow(`- docs without a frontmatter block: ${docsWithoutFrontmatter.length} — every status verb (\`set\`, \`archive\`, \`baton\`) dies on these. Fix: runlist bulk-tag <file> --type <type> --status <status>`) + '\n');
     for (const file of docsWithoutFrontmatter.slice(0, 10)) process.stdout.write(`  - ${file}\n`);
   } else {
     process.stdout.write('- docs without a frontmatter block: 0\n');
   }
   if (planStatusGaps.length) {
-    process.stdout.write(yellow(`- plan status vocab missing: ${planStatusGaps.join(', ')} — \`dotmd use\` and \`dotmd baton\` depend on these; add them to types.plan.statuses in dotmd.config.mjs`) + '\n');
+    process.stdout.write(yellow(`- plan status vocab missing: ${planStatusGaps.join(', ')} — \`runlist use\` and \`runlist baton\` depend on these; add them to types.plan.statuses in runlist.config.mjs`) + '\n');
   } else {
     process.stdout.write('- plan status vocab: ok\n');
   }
   if (skillDriftWarnings.length) {
-    process.stdout.write(yellow(`- canonical workflow block: drifted — CLAUDE.md and the plugin SKILL.md teach different workflows. Reconcile the block between the \`dotmd:canonical-workflow\` markers in both files.`) + '\n');
+    process.stdout.write(yellow(`- canonical workflow block: drifted — CLAUDE.md and the plugin SKILL.md teach different workflows. Reconcile the block between the \`runlist:canonical-workflow\` markers in both files.`) + '\n');
   } else {
     process.stdout.write('- canonical workflow block: in sync\n');
   }
@@ -559,7 +559,7 @@ function runDoctorStatuses(config, { json = false } = {}) {
     return;
   }
 
-  process.stdout.write(bold('dotmd doctor --statuses') + '\n\n');
+  process.stdout.write(bold('runlist doctor --statuses') + '\n\n');
 
   if (suggestions.length === 0) {
     process.stdout.write(`No overloaded status buckets detected (min bucket size: ${MIN_BUCKET_SIZE}).\n`);

package/src/fix-membership.mjs

@@ -21,7 +21,7 @@ function resolveHubArgs(args, docs) {
     const [match] = matches;
     if (!isHubDoc(match)) {
       die(`${match.path} is not a hub — it has no \`runlist:\` and no \`execution_mode: coordination|roadmap\`. `
-        + 'Run `dotmd fix-membership` with no argument to sweep every hub.');
+        + 'Run `runlist fix-membership` with no argument to sweep every hub.');
     }
     paths.add(match.path);
   }

package/src/frontmatter-fix.mjs

@@ -61,7 +61,7 @@ export function runFrontmatterFix(config, opts = {}) {
 
   const prefix = dryRun ? dim('[dry-run] ') : '';
   const banner = dryRun ? dim(' [preview — run without --dry-run to write]') : '';
-  out.write(bold('dotmd doctor --frontmatter-fix') + banner + '\n\n');
+  out.write(bold('runlist doctor --frontmatter-fix') + banner + '\n\n');
 
   if (results.length === 0) {
     out.write(green('No over-cap fields found.') + '\n');

package/src/git.mjs

@@ -36,7 +36,7 @@ function ensureGit() {
   if (gitChecked) return;
   const result = spawnSync('git', ['--version'], { encoding: 'utf8' });
   if (result.error) {
-    throw new Error('git is not installed or not found in PATH. dotmd requires git for this operation.');
+    throw new Error('git is not installed or not found in PATH. runlist requires git for this operation.');
   }
   gitChecked = true;
 }

package/src/glossary.mjs

@@ -183,9 +183,9 @@ export function runGlossary(argv, config) {
   const term = argv.find(a => !a.startsWith('-'));
 
   const result = loadGlossary(config);
-  if (!result) die('No glossary configured. Add glossary: { path, section } to your dotmd config.');
+  if (!result) die('No glossary configured. Add glossary: { path, section } to your runlist config.');
   if (!result.found) {
-    die(`Glossary section "## ${result.section}" not found in ${result.path}. Add the section, or update glossary.section in dotmd.config.mjs.`);
+    die(`Glossary section "## ${result.section}" not found in ${result.path}. Add the section, or update glossary.section in runlist.config.mjs.`);
   }
   if (result.entries.length === 0) {
     die(`Glossary section "## ${result.section}" found in ${result.path} but contains no recognizable entries (expected markdown table or schema→UI bullets).`);
@@ -212,7 +212,7 @@ export function runGlossary(argv, config) {
     return;
   }
 
-  if (!term) die('Usage: dotmd glossary <term> | --list | --json');
+  if (!term) die('Usage: runlist glossary <term> | --list | --json');
 
   const matches = matchTerm(term, entries);
 

package/src/graph.mjs

@@ -208,7 +208,7 @@ function _renderGraphText(graph, config) {
 export function renderGraphDot(graph, config) {
   const { nodes, edges } = graph;
   const lines = [];
-  lines.push('digraph dotmd {');
+  lines.push('digraph runlist {');
   lines.push('  rankdir=LR;');
   lines.push('  node [shape=box, style="rounded,filled", fontname="Helvetica"];');
   lines.push('');