dotmd-cli 0.76.8 → 0.77.1

package/README.md

@@ -20,6 +20,10 @@ npm install -D dotmd-cli    # project scripts via node_modules/.bin
 npx dotmd-cli init          # try it without installing
 ```
 
+`runlist` is the canonical executable, `rl` is its short convenience alias, and
+`dotmd` remains supported during the compatibility window. All three invoke the
+same CLI; examples below retain `dotmd` while the public package identity does.
+
 Maintainer release automation is POSIX-only because it uses Bash and POSIX
 command-line tools. The published Node.js CLI remains cross-platform.
 

package/assets/opencode/plugin.js

@@ -28,25 +28,30 @@ import { execFile } from 'node:child_process';
 const PRIMER_TTL_MS = 60_000;
 const PRIMER_TIMEOUT_MS = 5_000;
 
-function dotmdExecutable() {
-  return process.platform === 'win32' ? 'dotmd.cmd' : 'dotmd';
+function cliExecutables() {
+  return process.platform === 'win32' ? ['runlist.cmd', 'dotmd.cmd'] : ['runlist', 'dotmd'];
 }
 
 function runHud(directory) {
   return new Promise(resolve => {
     let settled = false;
     const done = value => { if (!settled) { settled = true; resolve(value); } };
-    try {
-      execFile(dotmdExecutable(), ['hud'], {
-        cwd: directory,
-        timeout: PRIMER_TIMEOUT_MS,
-        windowsHide: true,
-        env: { ...process.env, NO_COLOR: '1' },
-      }, (error, stdout) => done(error ? '' : (stdout ?? '').trim()));
-    } catch {
-      // `dotmd` not on PATH, spawn refused — no primer, no noise.
-      done('');
-    }
+    const candidates = cliExecutables();
+    const attempt = index => {
+      if (index >= candidates.length) { done(''); return; }
+      try {
+        execFile(candidates[index], ['hud'], {
+          cwd: directory,
+          timeout: PRIMER_TIMEOUT_MS,
+          windowsHide: true,
+          env: { ...process.env, NO_COLOR: '1' },
+        }, (error, stdout) => {
+          if (error?.code === 'ENOENT') attempt(index + 1);
+          else done(error ? '' : (stdout ?? '').trim());
+        });
+      } catch { attempt(index + 1); }
+    };
+    attempt(0);
   });
 }
 
@@ -76,10 +81,14 @@ export default async function dotmdOpencodePlugin({ directory }) {
     // available to a tool shell.
     'shell.env': async (input, output) => {
       try {
-        if (input?.sessionID) output.env.DOTMD_SESSION_ID = `opencode:${input.sessionID}`;
+        if (input?.sessionID) {
+          output.env.RUNLIST_SESSION_ID = `opencode:${input.sessionID}`;
+          output.env.DOTMD_SESSION_ID = `opencode:${input.sessionID}`;
+        }
         // The OpenCode server process hosts the session and outlives every tool
         // shell, so it is the process whose liveness answers "is this claim's
         // owner still there?" — `dotmd doctor --claims` probes exactly this.
+        output.env.RUNLIST_SESSION_PID = String(process.pid);
         output.env.DOTMD_SESSION_PID = String(process.pid);
       } catch { /* never break a shell over this */ }
     },

package/bin/dotmd.mjs

@@ -138,7 +138,7 @@ Rules:
 
 \`guard: { deny: false }\` in dotmd.config.mjs drops edit-status back to
 warn-only. Every catch is appended to the cross-repo misuse log. Disable the
-guard entirely with DOTMD_GUARD=0. Read the log with \`dotmd misuse\`; when one
+guard entirely with RUNLIST_GUARD=0. Read the log with \`dotmd misuse\`; when one
 rule trips ≥3× in 7 days in a repo, \`dotmd hud\` opens the next session there
 with a one-line recap naming the habit to break.`,
 
@@ -278,7 +278,7 @@ Setup:
   watch [command]                   Re-run a command on file changes
   completions <shell>               Shell completion script (bash, zsh)
   journal [--tail N|--errors|--by-command|--session id|--since iso|--json]
-                                    View opt-in JSONL command journal (enable: DOTMD_JOURNAL=1 or journal: true)
+                                    View opt-in JSONL command journal (enable: RUNLIST_JOURNAL=1 or journal: true)
 
 Global Options:
   --config <path>        Explicit config file path
@@ -400,10 +400,10 @@ invocation appends one JSONL line to .dotmd/journal.jsonl with argv, exit
 code, elapsed ms, session id, and (on error) a single-line err message.
 
 Enable:
-  - env:    DOTMD_JOURNAL=1
+  - env:    RUNLIST_JOURNAL=1
   - config: \`export const journal = true;\` in dotmd.config.mjs
 
-The env var beats config (DOTMD_JOURNAL=0 forces off). The journal is
+The env var beats config (RUNLIST_JOURNAL=0 forces off). The journal is
 default-off so non-agent users don't pay the size/PII cost.
 
 Reader options:
@@ -421,7 +421,7 @@ Storage:
   rotation or pruned after the retention window.
 
 Examples:
-  DOTMD_JOURNAL=1 dotmd plans
+  RUNLIST_JOURNAL=1 dotmd plans
   dotmd journal --tail 5
   dotmd journal --errors
   dotmd journal --by-command
@@ -506,7 +506,7 @@ Ambiguous slugs error with the candidate list instead of guessing.
 When the path is omitted, exactly one plan must be owned by this session.
 Claude Code session IDs are recognized automatically, as is OpenCode (via
 OPENCODE_PID — per OpenCode process, not per session). Other hosts must set
-DOTMD_SESSION_ID; anonymous ownership mutations fail closed.
+RUNLIST_SESSION_ID; anonymous ownership mutations fail closed.
 Pickup hooks use at-least-once delivery with a stable operationId; hook side
 effects must deduplicate that ID.
 
@@ -1442,6 +1442,20 @@ Pass file paths as positional args to scope to those files only; otherwise
 the whole docs tree is scanned.`,
 };
 
+// Help presents the new product name while the compatibility package and
+// plugin still use their old registry identities. Protect those identifiers
+// from the display-only command-name rewrite until the package cutover.
+function canonicalHelp(text) {
+  return String(text)
+    .replaceAll('dotmd-cli', '\u0000PACKAGE\u0000')
+    .replaceAll('dotmd@dotmd', '\u0000PLUGIN\u0000')
+    .replaceAll('reowens/dotmd', '\u0000REPOSITORY\u0000')
+    .replace(/\bdotmd\b/g, 'runlist')
+    .replaceAll('\u0000PACKAGE\u0000', 'dotmd-cli')
+    .replaceAll('\u0000PLUGIN\u0000', 'dotmd@dotmd')
+    .replaceAll('\u0000REPOSITORY\u0000', 'reowens/dotmd');
+}
+
 const GLOBAL_VALUE_OPTIONS = new Set(['--config', '--root', '--type']);
 const GLOBAL_BOOLEAN_OPTIONS = new Set(['--dry-run', '-n', '--verbose']);
 
@@ -1512,7 +1526,7 @@ async function main() {
   // Tolerate accidentally pasting the command prefix twice, while leaving all
   // remaining arguments to the normal `use` grammar and path validation.
   if (command === 'use') {
-    while (restArgs[0] === 'dotmd' && restArgs[1] === 'use') restArgs = restArgs.slice(2);
+    while ((restArgs[0] === 'runlist' || restArgs[0] === 'dotmd') && restArgs[1] === 'use') restArgs = restArgs.slice(2);
   }
 
   // Reconstruct the active global flags for proxy commands (e.g. `watch`) that
@@ -1559,12 +1573,12 @@ async function main() {
     const topic = restArgs[0];
     if (topic) {
       const key = `help:${topic}`;
-      if (HELP[key]) { process.stdout.write(`${HELP[key]}\n`); return; }
-      if (HELP[topic]) { process.stdout.write(`${HELP[topic]}\n`); return; }
+      if (HELP[key]) { process.stdout.write(`${canonicalHelp(HELP[key])}\n`); return; }
+      if (HELP[topic]) { process.stdout.write(`${canonicalHelp(HELP[topic])}\n`); return; }
       process.stderr.write(`Unknown help topic: ${topic}\n\nAvailable topics: all, statuses\nPer-command help: dotmd <cmd> --help\n`);
       process.exit(1);
     }
-    process.stdout.write(`${HELP._main}\n`);
+    process.stdout.write(`${canonicalHelp(HELP._main)}\n`);
     return;
   }
 
@@ -1588,7 +1602,7 @@ async function main() {
   // Per-command help
   if (args.includes('--help') || args.includes('-h')) {
     requireCommandPolicy(command, dispatchPolicy);
-    process.stdout.write(`${HELP[command] ?? commandUsage(command)}\n`);
+    process.stdout.write(`${canonicalHelp(HELP[command] ?? commandUsage(command))}\n`);
     return;
   }
 
@@ -1623,11 +1637,21 @@ async function main() {
     if (notice) process.stderr.write(`${notice}\n`);
   }
 
-  const suppressSideEffects = effectiveDryRun || command === 'hud' || passiveMachineContext;
+  const suppressSideEffects = effectiveDryRun || command === 'hud' || command === 'guard' || passiveMachineContext;
   Object.defineProperty(config, '_execution', {
     value: { dryRun, passive: command === 'hud' || passiveMachineContext, suppressSideEffects, gitStaleness },
     enumerable: false,
   });
+  if (!suppressSideEffects) {
+    const { migrateStateDirectory } = await import('../src/state-migration.mjs');
+    const { LEGACY_STATE_DIR, STATE_DIR } = await import('../src/naming.mjs');
+    const migration = migrateStateDirectory(config.repoRoot);
+    if (migration.status === 'migrated') {
+      process.stderr.write(`[runlist] migrated ${LEGACY_STATE_DIR}/ → ${STATE_DIR}/ (session state moved; repository files unchanged)\n`);
+    } else if (migration.status === 'refused') {
+      warn(migration.message);
+    }
+  }
   // Unknown names may still be user-defined query presets. Every built-in
   // dispatcher branch, including mutators above the shared index path, must be
   // present in the centralized command policy registry.
@@ -2240,7 +2264,7 @@ main()
     let out = err.message;
     // F17c: append a repeat-failure tip when the journal shows this same shape
     // has already failed in this session within the lookup window. Lookup is
-    // a no-op when the journal is disabled or DOTMD_NO_HINTS=1.
+    // a no-op when the journal is disabled or RUNLIST_NO_HINTS=1.
     try {
       const hint = findRepeatFailureHint(sanitizeTelemetryArgv(_invocationArgs), _resolvedConfig);
       if (hint) out = `${out}\n\nTip: ${hint}`;

package/bin/runlist.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+// Canonical executable. The implementation remains shared with the retired
+// `dotmd` alias during the compatibility window so both commands behave
+// identically and cannot drift.
+await import('./dotmd.mjs');

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "dotmd-cli",
-  "version": "0.76.8",
+  "version": "0.77.1",
   "description": "CLI for managing markdown documents with YAML frontmatter — index, query, validate, graph, export, lifecycle, and AI summaries.",
   "type": "module",
   "license": "MIT",
   "bin": {
+    "runlist": "bin/runlist.mjs",
+    "rl": "bin/runlist.mjs",
     "dotmd": "bin/dotmd.mjs"
   },
   "exports": {
@@ -15,7 +17,7 @@
     "src/",
     "assets/",
     "scripts/postinstall.mjs",
-    "dotmd.config.example.mjs"
+    "runlist.config.example.mjs"
   ],
   "keywords": [
     "markdown",

package/{dotmd.config.example.mjs → runlist.config.example.mjs}

@@ -1,4 +1,4 @@
-// dotmd.config.mjs — document management configuration
+// runlist.config.mjs — document management configuration
 // All exports are optional. Omitted values use built-in defaults.
 // Place this file at the root of your project.
 
@@ -7,17 +7,17 @@
 // Directory containing your markdown docs (relative to this config file)
 export const root = 'docs';
 
-// Subdirectory for archived docs (used by `dotmd archive` and `dotmd status`)
+// Subdirectory for archived docs (used by `runlist archive` and `runlist status`)
 export const archiveDir = 'archived';
 
 // Directories to skip when scanning
 export const excludeDirs = ['evidence'];
 
-// Floor under the scan surface. `dotmd check` fails when it scans fewer docs than
+// Floor under the scan surface. `runlist check` fails when it scans fewer docs than
 // this, so a broken root or an over-eager exclude can't read as a clean estate —
 // zero errors and zero docs look identical otherwise. Off when unset. Set it well
 // below your real count (round down hard); raise it as the corpus grows.
-// Override for one run with `dotmd check --min-docs <n>`; skipped for path-scoped
+// Override for one run with `runlist check --min-docs <n>`; skipped for path-scoped
 // checks, which are deliberate subsets.
 // export const minDocs = 500;
 
@@ -44,7 +44,7 @@ export const excludeDirs = ['evidence'];
 // `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.
 //
-// Contradiction check (since 0.36.2): dotmd `warn()`s at config-load when a status combines
+// Contradiction check (since 0.36.2): runlist `warn()`s at config-load when a status combines
 // `skipStale: true` with a `staleDays` value (the number is silently ignored) or
 // `skipWarnings: true` with `requiresModule: true` (the module requirement can never fire).
 // The same check applies via the `quiet: true` sugar. Drop one of the conflicting fields to silence.
@@ -80,8 +80,8 @@ export const excludeDirs = ['evidence'];
 //     },
 //   },
 //   prompt: {
-//     // Saved prompts that seed future Claude sessions. `dotmd hud` surfaces
-//     // pending prompts on session start; `dotmd prompts next` claims the oldest.
+//     // Saved prompts that seed future Claude sessions. `runlist hud` surfaces
+//     // pending prompts on session start; `runlist prompts next` claims the oldest.
 //     statuses: {
 //       'pending':  { context: 'expanded', staleDays: 30 },
 //       'held':     { context: 'counted', quiet: true },   // saved but not next: hidden from hud/briefing, skipped by no-arg `use`
@@ -132,7 +132,7 @@ export const statuses = {
 // no `types` definition. With rich-form types, the runtime derives these from
 // per-status `terminal` / `archive` / `skipStale` / `skipWarnings` / `quiet`
 // flags. An explicit `lifecycle` export sitting alongside rich-form types will
-// SILENTLY OVERRIDE the per-status flags — `dotmd statuses` will warn you
+// SILENTLY OVERRIDE the per-status flags — `runlist statuses` will warn you
 // before writing into a config in that state.
 //
 // export const lifecycle = {
@@ -155,13 +155,13 @@ export const taxonomy = {
 // Index file generation — remove this section to disable
 export const index = {
   path: 'docs/docs.md',
-  startMarker: '<!-- GENERATED:dotmd:start -->',
-  endMarker: '<!-- GENERATED:dotmd:end -->',
+  startMarker: '<!-- GENERATED:runlist:start -->',
+  endMarker: '<!-- GENERATED:runlist:end -->',
   snapshot: 'status', // default; use 'state' to include live current_state text
   archivedLimit: 8,
 };
 
-// Context briefing layout (`dotmd context`)
+// Context briefing layout (`runlist context`)
 export const context = {
   expanded: ['active'],
   listed: ['ready', 'planned'],
@@ -170,7 +170,7 @@ export const context = {
   recentStatuses: ['active', 'ready', 'planned'],
   recentLimit: 10,
   truncateNextStep: 80,
-  // Cap on slugs shown in the "Stale: …" tail before "…and N more (run `dotmd stale`)"
+  // Cap on slugs shown in the "Stale: …" tail before "…and N more (run `runlist stale`)"
   // takes over (since 0.36.2). Raise on wide terminals; lower for tighter briefings.
   staleTailLimit: 8,
 };
@@ -198,13 +198,13 @@ export const presets = {
 };
 
 // ─── Templates ───────────────────────────────────────────────────────────────
-// Define new types or override builtins. `dotmd new <type> <name>` looks here first.
+// Define new types or override builtins. `runlist new <type> <name>` looks here first.
 //
 // Properties:
-//   description:    string — shown in `dotmd new --list-types`
+//   description:    string — shown in `runlist new --list-types`
 //   defaultStatus:  string — initial status if `--status` not passed
 //   acceptsBody:    boolean — allow body input (inline / --body / @file / piped stdin).
-//                   REQUIRED if you want `cat draft.md | dotmd new <type> <slug>` (or @path,
+//                   REQUIRED if you want `cat draft.md | runlist new <type> <slug>` (or @path,
 //                   --body, heredoc) to work. Your `body` fn must also interpolate the input,
 //                   e.g. `${ctx?.bodyInput?.trim() ?? ''}`. See the body-acceptance guard below.
 //   requiresBody:   boolean — error if no body input (implies acceptsBody; see `prompt` builtin)
@@ -221,13 +221,13 @@ export const presets = {
 //
 // Body-acceptance guard (the #1 custom-template gotcha):
 //   When you override a builtin and supply your OWN `body` fn that NEVER references
-//   `bodyInput`, dotmd assumes the fn would silently discard piped input — so it strips
+//   `bodyInput`, runlist assumes the fn would silently discard piped input — so it strips
 //   the inherited `acceptsBody`/`requiresBody` and rejects body input with a fail-fast
 //   error. Two ways to keep piped/@path/heredoc bodies working in a custom template:
 //     1. interpolate `${ctx?.bodyInput?.trim() ?? ''}` somewhere in your `body` fn, OR
 //     2. set `acceptsBody: true` explicitly (do BOTH if you want the input to actually land).
 //   A `body: (t) =>` that ignores `ctx` is the classic trap — it scaffolds fine but
-//   `dotmd new <type> <slug> < draft.md` errors until you wire in `bodyInput`.
+//   `runlist new <type> <slug> < draft.md` errors until you wire in `bodyInput`.
 //
 // Custom type example — adds a `spike` type that lives in the `spikes` root (or
 // under `docs/spikes/` in single-root layouts):

package/scripts/postinstall.mjs

@@ -6,7 +6,7 @@
 //   - Only on GLOBAL installs (`npm i -g`). A project devDep / CI / Docker
 //     install must never touch a user's Claude Code state.
 //   - Default: just print a one-line nudge. A CLI install silently mutating the
-//     agent's plugin cache is surprising; opt in with DOTMD_AUTO_PLUGIN_UPDATE=1
+//     agent's plugin cache is surprising; opt in with RUNLIST_AUTO_PLUGIN_UPDATE=1
 //     to actually run the refresh.
 //   - NEVER fail the install: everything is swallowed and we always exit 0. A
 //     nonzero postinstall would break `npm i -g dotmd-cli`.
@@ -34,7 +34,7 @@ try {
     } catch { return false; }
   })();
 
-  if (process.env.DOTMD_AUTO_PLUGIN_UPDATE === '1' && hasClaude) {
+  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');
   } else {

package/src/atomic-mutation.mjs

@@ -23,6 +23,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { captureGitIndexGeneration, gitIndexProvablyUnpublished, gitIndexPublicationRaced, reclaimPreparedGitIndex, restoreGitIndexCas, sameGitIndexGeneration, stageMovePathsCas } from './git.mjs';
 import { authorizeManagedDestination, authorizeManagedSource, authorizeRepoGeneratedPath } from './managed-path.mjs';
+import { ARTIFACT_PREFIX, LEGACY_ARTIFACT_PREFIX, LEGACY_STATE_DIR, STATE_DIR, isOwnedArtifact, stateDir } from './naming.mjs';
 import { commitRename } from './durable-rename.mjs';
 
 const sleepBuffer = new Int32Array(new SharedArrayBuffer(4));
@@ -85,7 +86,7 @@ export class MutationConflictError extends Error {
   constructor(message) {
     super(message);
     this.name = 'MutationConflictError';
-    this.code = 'DOTMD_MUTATION_CONFLICT';
+    this.code = 'RUNLIST_MUTATION_CONFLICT';
   }
 }
 
@@ -93,7 +94,7 @@ export class MutationLockError extends Error {
   constructor(message) {
     super(message);
     this.name = 'MutationLockError';
-    this.code = 'DOTMD_MUTATION_LOCK_TIMEOUT';
+    this.code = 'RUNLIST_MUTATION_LOCK_TIMEOUT';
   }
 }
 
@@ -117,7 +118,7 @@ function safeGeneratedPath(filePath, repoRoot, options, kind) {
 }
 
 function transactionRoot(repoRoot, options = {}) {
-  return safeGeneratedPath(path.join(path.resolve(repoRoot), '.dotmd', 'transactions'), repoRoot, options, 'Transaction root');
+  return safeGeneratedPath(path.join(stateDir(repoRoot), 'transactions'), repoRoot, options, 'Transaction root');
 }
 
 function durableJson(filePath, value, options = {}) {
@@ -237,7 +238,7 @@ function validatePreparedGitIndex(prepared, label, directory) {
   }
   validateGitSnapshot(prepared.generation, `${label}.generation`);
   validateTransactionArtifact(prepared.path, directory, label);
-  if (path.dirname(prepared.tempPath) !== path.dirname(prepared.generation.indexPath) || !path.basename(prepared.tempPath).startsWith('.dotmd-index-')) {
+  if (path.dirname(prepared.tempPath) !== path.dirname(prepared.generation.indexPath) || !isOwnedArtifact(path.basename(prepared.tempPath), 'index')) {
     throw new MutationConflictError(`Unsafe prepared Git index path in ${label}.`);
   }
   if ((prepared.generation.exists && (prepared.hash !== prepared.generation.hash || prepared.size !== prepared.generation.size))
@@ -289,7 +290,7 @@ function validateParticipantPath(participant, repoRoot, options, label) {
     throw new MutationConflictError(`Invalid transaction participant ${label}.`);
   }
   const txRoot = transactionRoot(repoRoot, options);
-  const lockRoot = safeGeneratedPath(path.join(repoRoot, '.dotmd', 'locks'), repoRoot, options, 'Lock root');
+  const lockRoot = safeGeneratedPath(path.join(stateDir(repoRoot), 'locks'), repoRoot, options, 'Lock root');
   if (contained(txRoot, participant.path) || contained(lockRoot, participant.path)) {
     throw new MutationConflictError(`Transaction participant targets transaction/lock state: ${participant.path}`);
   }
@@ -299,7 +300,7 @@ function validateParticipantPath(participant, repoRoot, options, label) {
   } else {
     const authorized = safeGeneratedPath(participant.path, repoRoot, options, 'Transaction generated participant');
     if (options.config) {
-      const ownershipRoot = path.join(path.resolve(repoRoot), '.dotmd', 'ownership');
+      const ownershipRoot = path.join(stateDir(repoRoot), 'ownership');
       if (!contained(ownershipRoot, authorized)) throw new MutationConflictError(`Generated transaction participant is outside session ownership state: ${participant.path}`);
       if (participant.label !== 'ownership') throw new MutationConflictError(`Session-generated participant must be classified as ownership: ${participant.path}`);
     }
@@ -349,8 +350,9 @@ function validateManifest(manifest, manifestPath, directory, repoRoot, options)
     if (!participant || !contained(createdDirectory.path, participant.path) || createdDirectory.path === participant.path) {
       throw new MutationConflictError(`Transaction-created directory is not bound to a destination participant: ${createdDirectory.path}`);
     }
-    const expectedMarker = path.join(createdDirectory.path, `.dotmd-transaction-${manifest.id}`);
-    if (createdDirectory.marker !== expectedMarker || createdDirectory.token !== manifest.directoryToken) {
+    const expectedMarkers = [ARTIFACT_PREFIX, LEGACY_ARTIFACT_PREFIX]
+      .map(prefix => path.join(createdDirectory.path, `${prefix}transaction-${manifest.id}`));
+    if (!expectedMarkers.includes(createdDirectory.marker) || createdDirectory.token !== manifest.directoryToken) {
       throw new MutationConflictError(`Transaction-created directory marker binding mismatch: ${createdDirectory.path}`);
     }
     if (!['intended', 'created', 'removing', 'removed'].includes(createdDirectory.markerState)) throw new MutationConflictError(`Invalid transaction directory marker state: ${createdDirectory.path}`);
@@ -358,7 +360,7 @@ function validateManifest(manifest, manifestPath, directory, repoRoot, options)
       throw new MutationConflictError(`Invalid transaction-created directory identity: ${createdDirectory.path}`);
     }
     if (createdDirectory.markerState !== 'intended' && createdDirectory.identity === null) throw new MutationConflictError(`Transaction-created directory state lacks an identity: ${createdDirectory.path}`);
-    if (participant.policy === 'managed' && options.config) authorizeManagedDestination(path.join(createdDirectory.path, '.dotmd-directory-check.md'), options.config, { kind: 'Transaction-created directory' });
+    if (participant.policy === 'managed' && options.config) authorizeManagedDestination(path.join(createdDirectory.path, `${ARTIFACT_PREFIX}directory-check.md`), options.config, { kind: 'Transaction-created directory' });
     else safeGeneratedPath(createdDirectory.path, repoRoot, options, 'Transaction-created directory');
   }
   const createdPaths = new Set(manifest.createdDirectories.map(item => item.path));
@@ -752,7 +754,7 @@ function ensureTransactionDirectory(directory, transaction, options, participant
     const intent = {
       path: item,
       participantPath: path.resolve(participantPath),
-      marker: path.join(item, `.dotmd-transaction-${transaction.manifest.id}`),
+      marker: path.join(item, `${ARTIFACT_PREFIX}transaction-${transaction.manifest.id}`),
       token: transaction.manifest.directoryToken,
       markerState: 'intended',
       identity: null,
@@ -850,9 +852,9 @@ function setMoveManifestPhase(transaction, phase, options, detail = null) {
 }
 
 function companionPhase(item, fallback) {
-  return item.label === 'ownership' || item.path.includes(`${path.sep}.dotmd${path.sep}ownership${path.sep}`)
-    ? 'ownership-publication'
-    : fallback;
+  const ownershipPath = [STATE_DIR, LEGACY_STATE_DIR]
+    .some(dir => item.path.includes(`${path.sep}${dir}${path.sep}ownership${path.sep}`));
+  return item.label === 'ownership' || ownershipPath ? 'ownership-publication' : fallback;
 }
 
 function statIdentity(stat) {
@@ -919,7 +921,7 @@ function canonicalPath(filePath) {
 
 function lockPathFor(canonical, repoRoot) {
   const key = createHash('sha256').update(canonical).digest('hex');
-  return path.join(path.resolve(repoRoot), '.dotmd', 'locks', `${key}.lock`);
+  return path.join(stateDir(repoRoot), 'locks', `${key}.lock`);
 }
 
 function ownerDescription(lockPath) {
@@ -978,7 +980,7 @@ export function withPathLocks(filePaths, options, callback) {
   const { repoRoot, timeoutMs = MUTATION_LOCK_TIMEOUT_MS, retryMs = 20 } = options;
   if (!repoRoot) throw new Error('withPathLocks requires repoRoot.');
   const canonicals = [...new Set(filePaths.map(canonicalPath))].sort();
-  const lockRoot = safeGeneratedPath(path.join(path.resolve(repoRoot), '.dotmd', 'locks'), repoRoot, options, 'Lock root');
+  const lockRoot = safeGeneratedPath(path.join(stateDir(repoRoot), 'locks'), repoRoot, options, 'Lock root');
   ensureDirectoryDurable(lockRoot, options, 'lock-root-create');
   const acquired = [];
   const deadline = Date.now() + timeoutMs;
@@ -1059,7 +1061,7 @@ export function withPathLocks(filePaths, options, callback) {
 
 function tempPathFor(filePath) {
   const base = path.basename(filePath);
-  return path.join(path.dirname(filePath), `.${base}.dotmd-tmp-${process.pid}-${Date.now()}-${tempSequence++}`);
+  return path.join(path.dirname(filePath), `.${base}${ARTIFACT_PREFIX}tmp-${process.pid}-${Date.now()}-${tempSequence++}`);
 }
 
 function fsyncDirectory(dirPath, options = {}, phase = 'directory') {
@@ -1110,7 +1112,7 @@ function committedGeneration(prepared, finalPath) {
 }
 
 function recoveryArtifact(filePath, content, mode, label) {
-  const artifact = path.join(path.dirname(filePath), `.${path.basename(filePath)}.dotmd-recovery-${label}-${randomUUID()}`);
+  const artifact = path.join(path.dirname(filePath), `.${path.basename(filePath)}${ARTIFACT_PREFIX}recovery-${label}-${randomUUID()}`);
   const temp = writeCompleteTemp(artifact, content, mode);
   renameSync(temp.path, artifact);
   fsyncDirectory(path.dirname(artifact));

package/src/commands.mjs

@@ -1,4 +1,4 @@
-// Canonical command grammar. Execution stays in bin/dotmd.mjs; this schema owns
+// Canonical command grammar. Execution starts at bin/runlist.mjs; this schema owns
 // names, aliases, visibility, options, positional arity, help groups, and policy.
 const none = Object.freeze({ mutation: 'none', pathPolicy: 'read-only' });
 const mutates = (pathPolicy) => Object.freeze({ mutation: 'conditional', pathPolicy });

package/src/completions.mjs

@@ -7,9 +7,9 @@ const COMMAND_WORDS = Object.freeze(Object.fromEntries(
 ));
 
 function bashCompletion() {
-  return `# dotmd bash completion
-# Add to ~/.bashrc: eval "$(dotmd completions bash)"
-_dotmd() {
+  return `# runlist bash completion
+# Add to ~/.bashrc: eval "$(runlist completions bash)"
+_runlist() {
   local cur cmd expect_value
   cur="\${COMP_WORDS[COMP_CWORD]}"
   cmd=""
@@ -39,13 +39,13 @@ ${Object.entries(COMMAND_WORDS).map(([command, words]) =>
     *) COMPREPLY=( $(compgen -W "${GLOBAL_FLAGS.join(' ')}" -- "$cur") ) ;;
   esac
 }
-complete -F _dotmd dotmd`;
+complete -F _runlist runlist rl dotmd`;
 }
 
 function zshCompletion() {
-  return `# dotmd zsh completion
-# Add to ~/.zshrc: eval "$(dotmd completions zsh)"
-_dotmd() {
+  return `# runlist zsh completion
+# Add to ~/.zshrc: eval "$(runlist completions zsh)"
+_runlist() {
   local -a commands global_flags
   commands=(
 ${COMPLETION_COMMANDS.map(command => `    '${command}'`).join('\n')}
@@ -81,12 +81,12 @@ ${Object.entries(COMMAND_WORDS).map(([command, words]) =>
 
   _describe 'flag' global_flags
 }
-compdef _dotmd dotmd`;
+compdef _runlist runlist rl dotmd`;
 }
 
 export function runCompletions(argv) {
   const shell = argv[0];
-  if (!shell) die('Usage: dotmd completions <bash|zsh>');
+  if (!shell) die('Usage: runlist completions <bash|zsh>');
   if (shell === 'bash') process.stdout.write(bashCompletion() + '\n');
   else if (shell === 'zsh') process.stdout.write(zshCompletion() + '\n');
   else die(`Unsupported shell: ${shell}\nSupported: bash, zsh`);

package/src/config-edit.mjs

@@ -1,5 +1,5 @@
 // Line-based, brace-aware editor for the `types.<typename>.statuses` block in
-// dotmd.config.mjs. Edits are scoped to single-line status entries; we refuse
+// runlist config. Edits are scoped to single-line status entries; we refuse
 // (with an actionable error) on multi-line entries, array form, or anything
 // outside our supported shape. Atomic write contract:
 //
@@ -17,6 +17,7 @@
 
 import { existsSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs';
 import { pathToFileURL } from 'node:url';
+import { ARTIFACT_PREFIX } from './naming.mjs';
 import { resolveConfig } from './config.mjs';
 import { commitRename } from './durable-rename.mjs';
 
@@ -230,7 +231,7 @@ function skipToNextProperty(content, start, end) {
 export function parseStatusesBlock(content, typeName) {
   const types = locateTypesBlock(content);
   if (!types) {
-    throw new ConfigEditError('Your dotmd.config.mjs does not define a `types` block — there is nothing for `dotmd statuses` to edit. Add a `types: {...}` export to opt in to per-project status taxonomy. See dotmd.config.example.mjs for the rich-form template.');
+    throw new ConfigEditError('Your runlist config does not define a `types` block — there is nothing for `runlist statuses` to edit. Add a `types: {...}` export to opt in to per-project status taxonomy. See runlist.config.example.mjs for the rich-form template.');
   }
   const typeProp = findChildProperty(content, types.start, types.end, typeName);
   if (!typeProp) {
@@ -530,7 +531,7 @@ export function replaceEntry(content, parsed, name, newLine) {
     throw new ConfigEditError(`Status '${name}' is not defined for this type.`);
   }
   if (target.multiLine) {
-    throw new ConfigEditError(`Status '${name}' spans multiple lines; this CLI only edits single-line entries. Edit dotmd.config.mjs by hand.`);
+    throw new ConfigEditError(`Status '${name}' spans multiple lines; this CLI only edits single-line entries. Edit the runlist config by hand.`);
   }
   return content.slice(0, target.lineStart) + newLine + content.slice(target.lineEnd);
 }
@@ -542,7 +543,7 @@ export function deleteEntry(content, parsed, name) {
     throw new ConfigEditError(`Status '${name}' is not defined for this type.`);
   }
   if (target.multiLine) {
-    throw new ConfigEditError(`Status '${name}' spans multiple lines; delete it by hand in dotmd.config.mjs.`);
+    throw new ConfigEditError(`Status '${name}' spans multiple lines; delete it by hand in the runlist config.`);
   }
   return content.slice(0, target.lineStart) + content.slice(target.lineEnd);
 }
@@ -566,7 +567,7 @@ export function inferIndent(content, parsed) {
 export async function writeConfigAtomic(configPath, newContent, cwd) {
   // Node only imports .mjs/.js/.cjs, so the temp must keep a JS extension.
   // Sibling file in the same dir → atomic renameSync within one filesystem.
-  const tmpPath = configPath.replace(/(\.[^.]+)$/, `.dotmd-edit-${process.pid}-${Date.now()}$1`);
+  const tmpPath = configPath.replace(/(\.[^.]+)$/, `${ARTIFACT_PREFIX}edit-${process.pid}-${Date.now()}$1`);
   writeFileSync(tmpPath, newContent, 'utf8');
 
   try {

package/src/config.mjs

@@ -2,8 +2,7 @@ import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { die, warn } from './util.mjs';
-
-const CONFIG_FILENAMES = ['dotmd.config.mjs', '.dotmd.config.mjs', 'dotmd.config.js'];
+import { CONFIG_FILENAMES } from './naming.mjs';
 
 // Keys where user config replaces defaults entirely (not deep-merged).
 // These are flat maps or config sections where the user's version is authoritative —
@@ -116,7 +115,7 @@ const DEFAULTS = {
   glossary: null,
 
   // Opt-in JSONL command journal at .dotmd/journal.jsonl. Default off — agents
-  // and users who want usage observability flip this on (or set DOTMD_JOURNAL=1).
+  // and users who want usage observability flip this on (or set RUNLIST_JOURNAL=1).
   journal: false,
 
   // PreToolUse guard behavior. `deny: false` drops the status-edit rules from

package/src/git.mjs

@@ -3,6 +3,7 @@ import { chmodSync, closeSync, existsSync, fsyncSync, linkSync, lstatSync, openS
 import path from 'node:path';
 import { createHash, randomUUID } from 'node:crypto';
 import { commitRename } from './durable-rename.mjs';
+import { ARTIFACT_PREFIX, isOwnedArtifact } from './naming.mjs';
 
 // Best-effort `git check-ignore` for a path. Returns true only when git
 // definitively reports the path is ignored; any failure (not a repo, git
@@ -579,7 +580,7 @@ function prepareMoveIndex(source, target, repoRoot, before, options = {}) {
   const paths = [source, target].map(candidate => path.isAbsolute(candidate) ? path.relative(repoRoot, candidate) : candidate);
   assertSafeGitPaths(paths);
   const { indexDir } = gitIndexLocations(repoRoot);
-  const preparedPath = path.join(indexDir, `.dotmd-index-${process.pid}-${randomUUID()}`);
+  const preparedPath = path.join(indexDir, `${ARTIFACT_PREFIX}index-${process.pid}-${randomUUID()}`);
   const artifactPath = options.artifactPath ?? preparedPath;
   writeGeneration(artifactPath, before);
   let seed = { ...describePrepared(artifactPath, before), state: 'preparing', tempPath: preparedPath, work: null };
@@ -690,7 +691,7 @@ function publishIndexGeneration(repoRoot, expected, desired, prepared, testHooks
 function publishIndexGenerationLocked(repoRoot, expected, desired, prepared, testHooks, notePublished) {
   const { indexPath, indexDir, lockPath } = gitIndexLocations(repoRoot);
   if (expected.indexPath !== indexPath || desired.indexPath !== indexPath) throw new Error('Selected Git index changed since the transaction snapshot; recovery refused to target a different index.');
-  if (!prepared || prepared.state !== 'prepared' || path.dirname(prepared.tempPath) !== indexDir || !path.basename(prepared.tempPath).startsWith('.dotmd-index-') || !preparedMatches(prepared)) throw new Error('Prepared Git index ownership could not be verified.');
+  if (!prepared || prepared.state !== 'prepared' || path.dirname(prepared.tempPath) !== indexDir || !isOwnedArtifact(path.basename(prepared.tempPath), 'index') || !preparedMatches(prepared)) throw new Error('Prepared Git index ownership could not be verified.');
   if ((desired.exists && (prepared.hash !== desired.hash || prepared.size !== desired.size || prepared.mode !== desired.mode)) || (!desired.exists && prepared.size !== 0)) throw new Error('Prepared Git index artifact does not match the desired generation.');
   const publication = prepared.work ?? prepared;
   if (!preparedMatches(publication) || (desired.exists && (publication.hash !== desired.hash || publication.size !== desired.size || publication.mode !== desired.mode)) || (!desired.exists && publication.size !== 0)) throw new Error('Selected-directory Git working index does not match the desired generation.');
@@ -766,12 +767,12 @@ export function stageMovePathsCas(source, target, repoRoot, before, options = {}
 
 export function restoreGitIndexCas(before, ownedAfter, repoRoot, options = {}) {
   const { indexDir } = gitIndexLocations(repoRoot);
-  const preparedPath = options.artifactPath ?? path.join(indexDir, `.dotmd-index-restore-${process.pid}-${randomUUID()}`);
+  const preparedPath = options.artifactPath ?? path.join(indexDir, `${ARTIFACT_PREFIX}index-restore-${process.pid}-${randomUUID()}`);
   let artifact = null;
   try {
     writeGeneration(preparedPath, before);
     const prepared = before;
-    const tempPath = path.join(indexDir, `.dotmd-index-restore-${process.pid}-${randomUUID()}`);
+    const tempPath = path.join(indexDir, `${ARTIFACT_PREFIX}index-restore-${process.pid}-${randomUUID()}`);
     artifact = { ...describePrepared(preparedPath, prepared), state: 'preparing', tempPath, work: null };
     options.testHooks?.afterGitRestoreArtifact?.({ before, ownedAfter, prepared: artifact });
     writeGeneration(tempPath, before);
@@ -802,7 +803,7 @@ export function reclaimPreparedGitIndex(manifestGitIndex, repoRoot, options = {}
   const retainedPaths = [];
   const { indexPath, indexDir, lockPath } = gitIndexLocations(repoRoot);
   if (manifestGitIndex.before?.indexPath !== indexPath || prepared.generation?.indexPath !== indexPath) throw new Error('Recovery environment selects a different Git index than the abandoned transaction.');
-  if (path.dirname(prepared.tempPath) !== indexDir || !path.basename(prepared.tempPath).startsWith('.dotmd-index-')) throw new Error('Abandoned prepared Git index path is unsafe.');
+  if (path.dirname(prepared.tempPath) !== indexDir || !isOwnedArtifact(path.basename(prepared.tempPath), 'index')) throw new Error('Abandoned prepared Git index path is unsafe.');
   if (!existsSync(prepared.path)) {
     // The lock is only ever ours as a hard link to the publication inode, so a
     // lock that does not carry that inode cannot be ours — it belongs to a live

package/src/guard.mjs

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { inspectGitCommandPaths } from './git.mjs';
 import { recordGuardEvent } from './journal.mjs';
+import { readEnv } from './naming.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
@@ -348,7 +349,7 @@ function evalEdit(input, config, deps = {}) {
 // Pure evaluation — `deps.isIgnored(path) -> bool` is injected so tests don't
 // need a real git tree. Returns null (no opinion) or a result object.
 export function evaluateGuard(payload, config, deps = {}) {
-  if (process.env.DOTMD_GUARD === '0') return null;
+  if (readEnv('GUARD') === '0') return null;
   if (!config?.configFound) return null;
   const tool = payload?.tool_name;
   const input = payload?.tool_input || {};

package/src/hints.mjs

@@ -1,13 +1,14 @@
 import { existsSync } from 'node:fs';
 import { readJournalEntries, isJournalEnabled, journalFilePath } from './journal.mjs';
 import { currentSessionId } from './util.mjs';
+import { readEnv } from './naming.mjs';
 
 // F17c: repeat-failure hints. When an agent runs the same broken invocation
 // twice in the same session within HINT_WINDOW_MS, the second die() output is
 // suffixed with a Tip: paragraph informed by the prior failure's recorded
 // stderr. First failures stay terse — don't punish humans typing a command
 // for the first time. The lookup is skipped cleanly when the journal is
-// disabled or DOTMD_NO_HINTS=1, so this costs nothing for non-opt-in users.
+// disabled or RUNLIST_NO_HINTS=1, so this costs nothing for non-opt-in users.
 
 const HINT_WINDOW_MS = 10 * 60 * 1000;
 const OVERLAP_THRESHOLD = 0.75;
@@ -83,7 +84,7 @@ function jaccard(a, b) {
 // journal must never break the error-reporting path.
 export function findRepeatFailureHint(failingArgv, config) {
   try {
-    if (process.env.DOTMD_NO_HINTS === '1') return null;
+    if (readEnv('NO_HINTS') === '1') return null;
     if (!config) return null;
     if (!isJournalEnabled(config)) return null;
     if (!existsSync(journalFilePath(config))) return null;

package/src/host-integration.mjs

@@ -22,6 +22,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { hostSessionSource } from './util.mjs';
+import { readEnv, stateDir } from './naming.mjs';
 
 export const GENERATED_MARKER = 'dotmd-generated:';
 const PLUGIN_FILENAME = 'dotmd.js';
@@ -137,8 +138,8 @@ export function describeSessionIdentity(opts = {}) {
       id: null, scope: 'none', source: null, host: null,
       summary: 'no session identity — `use`, `set`, `baton` and `archive` fail closed',
       advice: underOpencode
-        ? ['dotmd install opencode', 'or set DOTMD_SESSION_ID for this shell']
-        : ['set DOTMD_SESSION_ID for this shell or host session', 'known hosts: dotmd install'],
+        ? ['runlist install opencode', 'or set RUNLIST_SESSION_ID for this shell']
+        : ['set RUNLIST_SESSION_ID for this shell or host session', 'known hosts: runlist install'],
     };
   }
 
@@ -153,7 +154,7 @@ export function describeSessionIdentity(opts = {}) {
       ? 'restart OpenCode — this session predates the installed integration'
       : 'dotmd install opencode  — for a per-session identity');
   } else if (source.scope === 'terminal') {
-    advice.push('every agent session in this terminal shares this id — set DOTMD_SESSION_ID per session');
+    advice.push('every agent session in this terminal shares this id — set RUNLIST_SESSION_ID per session');
   }
   return {
     id: source.id,
@@ -179,19 +180,19 @@ export function describeSessionIdentity(opts = {}) {
 // OpenCode in the first place, and punish a setup that is working.
 //
 // Once per session per repo, via a marker under the gitignored .dotmd/. Silent
-// under DOTMD_NO_HINTS=1, the switch the repeat-failure hints already use.
+// under RUNLIST_NO_HINTS=1, the switch the repeat-failure hints already use.
 const NOTICE_DIR = 'notices';
 
 function noticeMarkerPath(repoRoot, key) {
   const digest = createHash('sha256').update(key).digest('hex').slice(0, 32);
-  return path.join(path.resolve(repoRoot), '.dotmd', NOTICE_DIR, `${digest}`);
+  return path.join(stateDir(repoRoot), NOTICE_DIR, `${digest}`);
 }
 
 // Returns the notice text the first time it applies in a session, then null.
 // `record: false` answers without consuming the once-per-session budget.
 export function degradedIdentityNotice(repoRoot, opts = {}) {
   const { env = process.env, homedir = os.homedir(), version, record = true } = opts;
-  if (env.DOTMD_NO_HINTS === '1') return null;
+  if (readEnv('NO_HINTS', env) === '1') return null;
   // Cheap env check first: a user on any other host pays nothing for this.
   if (!env.OPENCODE && !env.OPENCODE_PID) return null;
 

package/src/init.mjs

@@ -36,7 +36,7 @@ function detectSessionStartHook(cwd) {
     for (const entry of sessionStart) {
       const inner = Array.isArray(entry?.hooks) ? entry.hooks : [];
       for (const hook of inner) {
-        if (typeof hook?.command === 'string' && /\bdotmd\s+hud\b/.test(hook.command)) {
+        if (typeof hook?.command === 'string' && /\b(?:runlist|dotmd)\s+hud\b/.test(hook.command)) {
           const rel = file.startsWith(cwd) ? path.relative(cwd, file) : file;
           return { wired: true, file: rel };
         }
@@ -46,8 +46,8 @@ function detectSessionStartHook(cwd) {
   return { wired: false };
 }
 
-const STARTER_CONFIG = `// dotmd.config.mjs — document management configuration
-// All exports are optional. See dotmd.config.example.mjs for full reference.
+const STARTER_CONFIG = `// runlist.config.mjs — document management configuration
+// All exports are optional. See runlist.config.example.mjs for full reference.
 
 export const root = 'docs';
 
@@ -212,7 +212,7 @@ const KNOWN_STALE_DAYS = {
 };
 
 function generateDetectedConfig(scan, rootPath) {
-  const lines = [`// dotmd.config.mjs — auto-detected from ${scan.docCount} existing docs`, ''];
+  const lines = [`// runlist.config.mjs — auto-detected from ${scan.docCount} existing docs`, ''];
   lines.push(`export const root = '${rootPath}';`);
   lines.push('');
 
@@ -274,7 +274,7 @@ function generateDetectedConfig(scan, rootPath) {
 
 export async function runInit(cwd, config, opts = {}) {
   const { dryRun = false } = opts;
-  const configPath = path.join(cwd, 'dotmd.config.mjs');
+  const configPath = path.join(cwd, 'runlist.config.mjs');
   const docsDir = path.join(cwd, 'docs');
   const indexPath = path.join(docsDir, 'docs.md');
 
@@ -288,14 +288,14 @@ export async function runInit(cwd, config, opts = {}) {
   const scan = existsSync(docsDir) ? scanExistingDocs(docsDir) : null;
 
   if (existsSync(configPath)) {
-    process.stdout.write(`  ${dryTag}${dim('exists')}  dotmd.config.mjs\n`);
+    process.stdout.write(`  ${dryTag}${dim('exists')}  ${path.basename(config.configPath)}\n`);
   } else {
     if (scan && scan.docCount > 0) {
       if (!dryRun) writeFileSync(configPath, generateDetectedConfig(scan, 'docs'), 'utf8');
-      process.stdout.write(`  ${dryTag}${green('create')}  dotmd.config.mjs (detected ${scan.docCount} docs)\n`);
+      process.stdout.write(`  ${dryTag}${green('create')}  runlist.config.mjs (detected ${scan.docCount} docs)\n`);
     } else {
       if (!dryRun) writeFileSync(configPath, STARTER_CONFIG, 'utf8');
-      process.stdout.write(`  ${dryTag}${green('create')}  dotmd.config.mjs\n`);
+      process.stdout.write(`  ${dryTag}${green('create')}  runlist.config.mjs\n`);
     }
   }
 
@@ -377,9 +377,10 @@ export async function runInit(cwd, config, opts = {}) {
     process.stdout.write(`                 export const root = [${subs.map(s => `'${s}'`).join(', ')}];\n`);
   }
 
-  // .gitignore: two rules.
+  // .gitignore: three rules.
   //
-  //   .dotmd/                 — session ownership records
+  //   .runlist/               — session ownership records
+  //   .dotmd/                 — legacy state during the compatibility window
   //   <docs>/prompts/*.md     — the LIVE saved-prompt queue
   //
   // The second one is load-bearing. Saved prompts are session-local by design and
@@ -392,6 +393,7 @@ export async function runInit(cwd, config, opts = {}) {
   const docsRel = path.relative(cwd, docsDir).split(path.sep).join('/');
   const promptsIgnore = `/${docsRel ? `${docsRel}/` : ''}prompts/*.md`;
   const ignoreRules = [
+    { line: '.runlist/', accepts: (l) => l === '.runlist/' || l === '.runlist' },
     { line: '.dotmd/', accepts: (l) => l === '.dotmd/' || l === '.dotmd' },
     { line: promptsIgnore, accepts: (l) => l === promptsIgnore || l === promptsIgnore.slice(1) },
   ];

package/src/journal-read.mjs

@@ -32,7 +32,7 @@ export function runJournal(argv, config) {
   if (!existsSync(file)) {
     if (!isJournalEnabled(config)) {
       process.stderr.write(
-        'Journal is opt-in. Enable with `DOTMD_JOURNAL=1` (env) or `journal: true` (in dotmd.config.mjs).\n',
+        'Journal is opt-in. Enable with `RUNLIST_JOURNAL=1` (env) or `journal: true` (in runlist.config.mjs).\n',
       );
       return;
     }

package/src/journal.mjs

@@ -2,8 +2,8 @@ import { existsSync, mkdirSync, appendFileSync, statSync, renameSync, readFileSy
 import path from 'node:path';
 import os from 'node:os';
 import { currentSessionId } from './util.mjs';
+import { readEnv, stateDir } from './naming.mjs';
 
-const JOURNAL_DIR = '.dotmd';
 const JOURNAL_FILE = 'journal.jsonl';
 const JOURNAL_BACKUP = 'journal.jsonl.1';
 const ROTATE_SIZE_BYTES = 5 * 1024 * 1024;
@@ -118,17 +118,17 @@ export function sanitizeTelemetryText(value, secrets = []) {
 }
 
 export function isJournalEnabled(config) {
-  if (process.env.DOTMD_JOURNAL === '1') return true;
-  if (process.env.DOTMD_JOURNAL === '0') return false;
+  if (readEnv('JOURNAL') === '1') return true;
+  if (readEnv('JOURNAL') === '0') return false;
   return config?.journal === true;
 }
 
 export function journalFilePath(config) {
-  return path.join(config.repoRoot, JOURNAL_DIR, JOURNAL_FILE);
+  return path.join(stateDir(config.repoRoot), JOURNAL_FILE);
 }
 
 export function journalBackupPath(config) {
-  return path.join(config.repoRoot, JOURNAL_DIR, JOURNAL_BACKUP);
+  return path.join(stateDir(config.repoRoot), JOURNAL_BACKUP);
 }
 
 function firstEntry(file) {
@@ -206,7 +206,7 @@ export function appendJournalEntry(config, entry) {
       ...(Array.isArray(entry?.argv) ? { argv: sanitized.argv } : {}),
       ...(entry?.err ? { err: sanitizeTelemetryText(entry.err, sanitized.secrets) } : {}),
     };
-    const dir = path.join(config.repoRoot, JOURNAL_DIR);
+    const dir = stateDir(config.repoRoot);
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
     const file = journalFilePath(config);
     maybeRotate(file, journalBackupPath(config), safeEntry);
@@ -267,11 +267,11 @@ export function recordCliInvocation({ config, startMs, args, err, version }) {
 
 // Global error log: always-on, cross-repo, captured per failed invocation.
 // Independent of `isJournalEnabled` so silent failures stop disappearing.
-// DOTMD_ERROR_LOG_DIR overrides the default location (for tests, or for
+// RUNLIST_ERROR_LOG_DIR overrides the default location (for tests, or for
 // users who want the log somewhere other than ~/.claude/logs).
 
 export function globalErrorLogDir() {
-  return process.env.DOTMD_ERROR_LOG_DIR || path.join(os.homedir(), '.claude', 'logs');
+  return readEnv('ERROR_LOG_DIR') || path.join(os.homedir(), '.claude', 'logs');
 }
 
 export function globalErrorLogPath() {

package/src/naming.mjs

@@ -0,0 +1,55 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+// Canonical product-owned names and the spellings accepted during migration.
+// Writers use the current names. Readers accept both so a new build can safely
+// recover work left by an older build. Migration is intentionally one-way.
+export const PRODUCT_NAME = 'runlist';
+export const LEGACY_PRODUCT_NAME = 'dotmd';
+
+export const STATE_DIR = '.runlist';
+export const LEGACY_STATE_DIR = '.dotmd';
+
+export const ARTIFACT_PREFIX = '.runlist-';
+export const LEGACY_ARTIFACT_PREFIX = '.dotmd-';
+
+export const CONFIG_FILENAMES = [
+  'runlist.config.mjs',
+  '.runlist.config.mjs',
+  'runlist.config.js',
+  'dotmd.config.mjs',
+  '.dotmd.config.mjs',
+  'dotmd.config.js',
+];
+
+export const ENV_PREFIX = 'RUNLIST_';
+export const LEGACY_ENV_PREFIX = 'DOTMD_';
+
+// Prefer current state, but let an explicitly refused migration keep operating
+// against the untouched legacy directory.
+export function stateDir(repoRoot) {
+  const root = path.resolve(repoRoot);
+  const current = path.join(root, STATE_DIR);
+  if (existsSync(current)) return current;
+  const legacy = path.join(root, LEGACY_STATE_DIR);
+  if (existsSync(legacy)) return legacy;
+  return current;
+}
+
+export function isOwnedArtifact(basename, kind = '') {
+  const suffix = kind ? `${kind}-` : '';
+  return basename.startsWith(`${ARTIFACT_PREFIX}${suffix}`)
+    || basename.startsWith(`${LEGACY_ARTIFACT_PREFIX}${suffix}`);
+}
+
+export function isSidecarArtifact(basename, kind = '') {
+  const suffix = kind ? `${kind}-` : '';
+  return basename.includes(`${ARTIFACT_PREFIX}${suffix}`)
+    || basename.includes(`${LEGACY_ARTIFACT_PREFIX}${suffix}`);
+}
+
+export function readEnv(name, env = process.env) {
+  const current = env[`${ENV_PREFIX}${name}`];
+  if (current !== undefined) return current;
+  return env[`${LEGACY_ENV_PREFIX}${name}`];
+}

package/src/pickup.mjs

@@ -6,6 +6,7 @@ import os from 'node:os';
 import { currentProcessOwner, mutateFileSet, processOwnerLiveness, processStartIdentity, replaceSnapshot, snapshotFile, withPathLocks } from './atomic-mutation.mjs';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { asString, hostSessionId, relTime } from './util.mjs';
+import { readEnv, stateDir } from './naming.mjs';
 
 export const OWNERSHIP_SCHEMA = 2;
 export const HOOK_DELIVERY_LEASE_MS = 30_000;
@@ -13,14 +14,14 @@ export const HOOK_DELIVERY_LEASE_MS = 30_000;
 export function authoritativeSessionId(env = process.env) {
   const id = hostSessionId(env);
   if (id) return id;
-  // Name the host when we can recognize it. The generic "set DOTMD_SESSION_ID"
+  // Name the host when we can recognize it. The generic "set RUNLIST_SESSION_ID"
   // is the fallback of last resort, and a poor one to reach for first: exported
   // from a shell profile it gives every session in that shell ONE id, which is
   // the collision the ownership record exists to prevent.
   const host = env.OPENCODE || env.OPENCODE_PID ? 'opencode' : null;
   throw new Error(host
-    ? `No authoritative session identity. Run \`dotmd install ${host}\` to give each ${host} session its own, or set DOTMD_SESSION_ID for this shell.`
-    : 'No authoritative session identity. Set DOTMD_SESSION_ID for this shell or host session, or see `dotmd install` for supported hosts.');
+    ? `No authoritative session identity. Run \`runlist install ${host}\` to give each ${host} session its own, or set RUNLIST_SESSION_ID for this shell.`
+    : 'No authoritative session identity. Set RUNLIST_SESSION_ID for this shell or host session, or see `runlist install` for supported hosts.');
 }
 
 export function availableSessionId(env = process.env) {
@@ -38,7 +39,7 @@ export function availableSessionId(env = process.env) {
 // `OPENCODE_PID` is the OpenCode server process, which is exactly that harness:
 // it hosts the session and outlives every tool shell it spawns.
 export function sessionProcessOwner(env = process.env) {
-  const raw = (env.DOTMD_SESSION_PID ?? env.CLAUDE_PID ?? env.OPENCODE_PID)?.trim();
+  const raw = (readEnv('SESSION_PID', env) ?? env.CLAUDE_PID ?? env.OPENCODE_PID)?.trim();
   const pid = Number(raw);
   if (!raw || !Number.isInteger(pid) || pid <= 0) return null;
   return {
@@ -116,7 +117,7 @@ export function classifyPlanPickup(facts) {
 }
 
 function ownershipRoot(config) {
-  return path.join(config.repoRoot, '.dotmd', 'ownership');
+  return path.join(stateDir(config.repoRoot), 'ownership');
 }
 
 export function canonicalPlanIdentity(filePath, config) {

package/src/prompts.mjs

@@ -16,6 +16,7 @@ import {
   readPlanOwnership,
 } from './pickup.mjs';
 import { actionablePromptStatuses, comparePromptDocs } from './status-metadata.mjs';
+import { LEGACY_STATE_DIR, STATE_DIR } from './naming.mjs';
 
 // `resume` is an alias for `use` — agents reach for "resume" when continuing a
 // session; `use` reads as internal mechanics. Both names stay valid; the
@@ -330,8 +331,10 @@ export async function consumePrompt(filePath, config, opts) {
     ...(linkedClaim?.planChanged ? [linkedClaim.repoPath] : []),
     ...(archiveResult?.referencePaths ?? []),
   ].filter(Boolean).map(normalize);
-  const ownershipResultPaths = resultPaths.filter(candidate => candidate.startsWith('.dotmd/ownership/'));
-  const repositoryFiles = [...new Set(resultPaths.filter(candidate => !candidate.startsWith('.dotmd/ownership/')))];
+  const isOwnershipPath = candidate => [STATE_DIR, LEGACY_STATE_DIR]
+    .some(dir => candidate.startsWith(`${dir}/ownership/`));
+  const ownershipResultPaths = resultPaths.filter(isOwnershipPath);
+  const repositoryFiles = [...new Set(resultPaths.filter(candidate => !isOwnershipPath(candidate)))];
   const sessionFiles = [...new Set([
     repoPath,
     consumedPath,

package/src/reference-planner.mjs

@@ -37,7 +37,7 @@ export class AmbiguousReferenceError extends Error {
   constructor(token, sourcePath, local, repository) {
     super(`Ambiguous reference '${token}' in ${sourcePath}: document-relative resolves to ${local}, repository-relative resolves to ${repository}. Use an explicit unambiguous path.`);
     this.name = 'AmbiguousReferenceError';
-    this.code = 'DOTMD_AMBIGUOUS_REFERENCE';
+    this.code = 'RUNLIST_AMBIGUOUS_REFERENCE';
   }
 }
 

package/src/ship.mjs

@@ -20,6 +20,8 @@ const ALLOWLIST_PATTERNS = [
   /^plugins\//,
   /^\.claude-plugin\//,
   /^\.claude\/commands\//,
+  /^runlist\.config\.example\.mjs$/,
+  /^runlist\.config\.mjs$/,
   /^dotmd\.config\.example\.mjs$/,
   /^dotmd\.config\.mjs$/,
   /^package(?:-lock)?\.json$/,

package/src/state-migration.mjs

@@ -0,0 +1,123 @@
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  rmdirSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import path from 'node:path';
+import { processOwnerLiveness } from './atomic-mutation.mjs';
+import { LEGACY_STATE_DIR, STATE_DIR } from './naming.mjs';
+
+export { stateDir } from './naming.mjs';
+
+const MIGRATION_MARKER = 'migrated-from-dotmd.json';
+const DROP_ENTRIES = new Set(['handoffs']);
+const TERMINAL_TRANSACTION_STATUSES = new Set(['committed', 'rolled-back', 'failed-manual']);
+
+function heldLocks(lockRoot) {
+  if (!existsSync(lockRoot)) return [];
+  let entries;
+  try { entries = readdirSync(lockRoot); }
+  catch { return [{ lock: path.basename(lockRoot), status: 'unreadable-directory' }]; }
+  const held = [];
+  for (const entry of entries) {
+    const ownerPath = path.join(lockRoot, entry, 'owner.json');
+    if (!existsSync(ownerPath)) {
+      held.push({ lock: entry, status: 'owner-missing' });
+      continue;
+    }
+    let owner;
+    try { owner = JSON.parse(readFileSync(ownerPath, 'utf8')); }
+    catch {
+      held.push({ lock: entry, status: 'owner-unreadable' });
+      continue;
+    }
+    if (processOwnerLiveness(owner) !== 'dead') {
+      held.push({ lock: entry, status: 'held-or-unverifiable', pid: owner.pid, hostname: owner.hostname });
+    }
+  }
+  return held;
+}
+
+function unresolvedTransactions(transactionRoot) {
+  if (!existsSync(transactionRoot)) return [];
+  let entries;
+  try { entries = readdirSync(transactionRoot); }
+  catch { return [{ id: path.basename(transactionRoot), status: 'unreadable-directory' }]; }
+  const open = [];
+  for (const entry of entries) {
+    const manifestPath = path.join(transactionRoot, entry, 'manifest.json');
+    if (!existsSync(manifestPath)) {
+      open.push({ id: entry, status: 'manifest-missing' });
+      continue;
+    }
+    let manifest;
+    try { manifest = JSON.parse(readFileSync(manifestPath, 'utf8')); }
+    catch { open.push({ id: entry, status: 'unreadable' }); continue; }
+    if (!TERMINAL_TRANSACTION_STATUSES.has(manifest.status)) {
+      open.push({ id: entry, status: manifest.status ?? 'unknown' });
+    }
+  }
+  return open;
+}
+
+function moveEntry(from, to) {
+  if (existsSync(to)) {
+    if (statSync(to).isDirectory() && statSync(from).isDirectory()) {
+      for (const child of readdirSync(from)) moveEntry(path.join(from, child), path.join(to, child));
+      rmSync(from, { recursive: true, force: true });
+      return;
+    }
+    // Current state wins an exact-name collision. The legacy copy is stale by
+    // definition and retaining both would make the next migration ambiguous.
+    rmSync(from, { recursive: true, force: true });
+    return;
+  }
+  renameSync(from, to);
+}
+
+export function migrateStateDirectory(repoRoot, options = {}) {
+  const root = path.resolve(repoRoot);
+  const from = path.join(root, LEGACY_STATE_DIR);
+  const to = path.join(root, STATE_DIR);
+  if (!existsSync(from)) return { status: 'noop', reason: 'nothing-to-migrate', from, to };
+
+  const held = heldLocks(path.join(from, 'locks'));
+  if (held.length) {
+    return {
+      status: 'refused', reason: 'locks-held', detail: held, from, to,
+      message: `Legacy state has ${held.length} lock${held.length === 1 ? '' : 's'} that ${held.length === 1 ? 'is' : 'are'} not provably abandoned. State migration refused; retry after active work finishes or inspect with \`runlist doctor --transactions\`.`,
+    };
+  }
+
+  const open = unresolvedTransactions(path.join(from, 'transactions'));
+  if (open.length) {
+    return {
+      status: 'refused', reason: 'transactions-unresolved', detail: open, from, to,
+      message: `${open.length} transaction${open.length === 1 ? ' is' : 's are'} not terminal (${open.map(item => `${item.id}: ${item.status}`).join(', ')}). State migration refused. Resolve with \`runlist doctor --transactions --apply\`, then retry.`,
+    };
+  }
+
+  if (options.dryRun) return { status: 'noop', reason: 'dry-run', from, to };
+
+  mkdirSync(to, { recursive: true });
+  for (const entry of readdirSync(from)) {
+    if (DROP_ENTRIES.has(entry)) {
+      rmSync(path.join(from, entry), { recursive: true, force: true });
+      continue;
+    }
+    moveEntry(path.join(from, entry), path.join(to, entry));
+  }
+  try { if (readdirSync(from).length === 0) rmdirSync(from); } catch {}
+
+  writeFileSync(
+    path.join(to, MIGRATION_MARKER),
+    JSON.stringify({ from: LEGACY_STATE_DIR, to: STATE_DIR, migratedAt: new Date().toISOString() }, null, 2) + '\n',
+  );
+  return { status: 'migrated', from, to };
+}

package/src/util.mjs

@@ -22,6 +22,7 @@ import { dim } from './color.mjs';
 // tell two of them apart. `dotmd doctor --session` reports that distinction, and
 // it is the whole reason `dotmd install opencode` exists.
 const SESSION_ID_SOURCES = [
+  { variable: 'RUNLIST_SESSION_ID', prefix: null, scope: 'session', host: 'explicit override' },
   { variable: 'DOTMD_SESSION_ID', prefix: null, scope: 'session', host: 'explicit override' },
   { variable: 'CLAUDE_CODE_SESSION_ID', prefix: null, scope: 'session', host: 'Claude Code' },
   { variable: 'CLAUDE_SESSION_ID', prefix: null, scope: 'session', host: 'Claude Code' },

package/src/watch.mjs

@@ -5,7 +5,7 @@ import { fileURLToPath } from 'node:url';
 import { dim } from './color.mjs';
 
 export function watchCliPath(moduleUrl = import.meta.url) {
-  return path.resolve(path.dirname(fileURLToPath(moduleUrl)), '..', 'bin', 'dotmd.mjs');
+  return path.resolve(path.dirname(fileURLToPath(moduleUrl)), '..', 'bin', 'runlist.mjs');
 }
 
 export function runWatch(argv, config) {