dotmd-cli 0.49.4 → 0.50.0

package/README.md

@@ -128,7 +128,7 @@ Every document can have a `type` field in its frontmatter. Types determine which
 |------|---------|----------------|
 | `plan` | Execution plans | `in-session`, `active`, `planned`, `blocked`, `partial`, `paused`, `awaiting`, `queued-after`, `archived` |
 | `doc` | Design docs, specs, ADRs, RFCs, reference material | `draft`, `active`, `review`, `reference`, `deprecated`, `archived` |
-| `prompt` | Saved prompts that seed future Claude sessions | `pending`, `shelved`, `claimed`, `archived` |
+| `prompt` | Saved prompts that seed future Claude sessions | `pending`, `held`, `shelved`, `claimed`, `archived` |
 
 Documents without a `type` field use the global `statuses.order` from config.
 
@@ -206,7 +206,7 @@ dotmd glossary <term>        Look up domain terms + related docs
 dotmd watch [command]        Re-run a command on file changes
 dotmd diff [file]            Show changes since last updated date
 dotmd new <type> <name>      Create a new doc (type: doc, plan, or prompt)
-dotmd prompts [sub]          Manage saved prompts (list, next, use, shelve, archive, new)
+dotmd prompts [sub]          Manage saved prompts (list, next, use, hold, archive, new)
 dotmd journal [flags]        View opt-in command-usage journal (DOTMD_JOURNAL=1)
 dotmd init                   Create starter config + docs directory
 dotmd completions <shell>    Output shell completion script (bash, zsh)
@@ -303,16 +303,17 @@ dotmd prompts                     # list pending prompts (default)
 dotmd prompts list --all          # all statuses
 dotmd prompts next                # print body of oldest pending + auto-archive (one-shot)
 dotmd prompts use <file>          # print body of a specific prompt + auto-archive
-dotmd prompts shelve <file>       # park a prompt (status → shelved): kept in list,
-                                  # hidden from hud/briefing, skipped by `next`
-dotmd prompts unshelve <file>     # move a shelved prompt back to pending
+dotmd prompts hold <file>         # park a prompt (status → held) under prompts/held/:
+                                  # kept in list, hidden from hud/briefing, skipped by `next`
+dotmd prompts unhold <file>       # move a held prompt back to pending
+dotmd prompts shelve <file>       # legacy alias for `hold`
 dotmd prompts archive <file>      # archive without printing the body
 dotmd prompts new <name> [body]   # alias for `dotmd new prompt`
 ```
 
-`dotmd hud` surfaces pending prompts on session start (alongside held leases), so a saved prompt acts as a self-addressed reminder: write it now, the next session sees it. Shelved prompts are kept out of the SessionStart surface — use them for "saved but not next."
+`dotmd hud` surfaces pending prompts on session start (alongside held leases), so a saved prompt acts as a self-addressed reminder: write it now, the next session sees it. Held prompts are kept out of the SessionStart surface — use them for "saved but not next."
 
-Statuses: `pending` (drafted, awaiting a session), `shelved` (saved but parked — visible in `prompts list`, hidden from `hud`/`briefing`, skipped by `prompts next`), `archived` (consumed or filed away). `claimed` is reserved for a future "in-flight" state but is currently a synonym for archived in practice.
+Statuses: `pending` (drafted, awaiting a session), `held` (saved but parked under `prompts/held/` — visible in `prompts list`, hidden from `hud`/`briefing`, skipped by `prompts next`), `archived` (consumed or filed away). `shelved` is a legacy spelling accepted for older files; `claimed` is reserved for a future "in-flight" state but is currently a synonym for archived in practice.
 
 ### Command Journal (opt-in)
 
@@ -878,9 +879,15 @@ export const index = {
   path: 'docs/docs.md',
   startMarker: '<!-- GENERATED:dotmd:start -->',
   endMarker: '<!-- GENERATED:dotmd:end -->',
+  snapshot: 'status', // default; use 'state' to include live current_state text
 };
 ```
 
+Generated indexes default to status-only rows for live sections so README files
+do not become stale mirrors of volatile `current_state` text. Set
+`snapshot: 'state'` if you want the older `Status Snapshot` table for live
+sections too. Archived highlights still include their historical snapshots.
+
 All exports are optional. Additional options: `context`, `display`, `presets`, `templates`, `excludeDirs`, `notion`. See [`dotmd.config.example.mjs`](dotmd.config.example.mjs) for the full reference.
 
 Config discovery walks up from cwd looking for `dotmd.config.mjs` or `.dotmd.config.mjs`.

package/bin/dotmd.mjs

@@ -44,7 +44,7 @@ const FLAG_SPECS = {
   prompts: {
     flags: new Set(['--json', '--status', '--include-archived', '--sort', '--limit', '--all', '--no-index', '--show-files', '--body', '--message', '--title']),
     values: new Set(['--status', '--sort', '--limit', '--body', '--message', '--title']),
-    subcommands: new Set(['list', 'next', 'use', 'resume', 'archive', 'new', 'shelve', 'unshelve', 'status']),
+    subcommands: new Set(['list', 'next', 'use', 'resume', 'archive', 'new', 'hold', 'unhold', 'shelve', 'unshelve', 'status']),
   },
 };
 
@@ -65,12 +65,12 @@ const HELP = {
 
 Common commands:
   plans                 Live plans (excludes archived)
-  prompts               Prompt queue/admin (list, next, archive, new, shelve)
+  prompts               Prompt queue/admin (list, next, archive, new, hold)
   briefing              Full briefing with plan counts + next steps
   agent-context         Compact bounded JSON context for agents
   set <status> [file]   Transition status (start work, finish, archive — all via target status)
   new <type> <name>     Create plan/doc/prompt (pipe stdin or @path for body)
-  use [<file>]          Open a doc by type: prompt → consume, plan → start, doc → read
+  use [<file-or-prompt-slug>] Open a doc by type: prompt → consume, plan → start, doc → read
                         (no file: consume oldest pending prompt)
   archive <file>        Close out a plan (status → archived, move, update refs)
 
@@ -95,8 +95,8 @@ View & Query:
   focus [status] [--json]           Detailed view for one status group
   query [filters] [--json]          Filtered search (--status, --keyword, --stale, etc.)
   plans                             Live plans (excludes archived; --include-archived for all)
-  use [<file>]                      Open a doc by type: prompt → consume, plan → start, doc → read
-  prompts [list|archive|new|shelve] Prompt admin (list / archive / save / shelve). Use \`dotmd use\` to consume.
+  use [<file-or-prompt-slug>]       Open a doc by type: prompt → consume, plan → start, doc → read
+  prompts [list|archive|new|hold] Prompt admin (list / archive / save / hold). Use \`dotmd use\` to consume.
   stale                             Stale docs (preset)
   actionable                        Docs with next steps (preset)
 
@@ -235,9 +235,13 @@ prompt statuses
                  \`dotmd prompts use <file>\` prints body + archives atomically.
                  \`dotmd prompts next\` does the same for the oldest pending.
 
-  shelved        Saved but hidden from \`hud\` / \`briefing\` / \`prompts next\`.
+  held           Saved under prompts/held/ and hidden from \`hud\` /
+                 \`briefing\` / \`prompts next\`.
                  Still listed by \`dotmd prompts list\`.
-                 \`dotmd prompts unshelve <file>\` → pending.
+                 \`dotmd prompts unhold <file>\` → pending.
+
+  shelved        Legacy spelling for held prompts. \`dotmd prompts shelve\`
+                 now writes \`status: held\`.
 
   claimed        Legacy intermediate state (atomic use → archived now).
 
@@ -920,10 +924,11 @@ Subcommands:
   resume <file-or-slug>      Alias for \`use\` — same behavior, easier name
                              when continuing a session
   archive <file-or-slug>     Archive a prompt without printing its body
-  shelve <file-or-slug>      Park a prompt (status → shelved): kept in list,
-                             hidden from hud/briefing pending surfaces, skipped
-                             by \`prompts next\`. Use for "saved but not next."
-  unshelve <file-or-slug>    Move a shelved prompt back to pending.
+  hold <file-or-slug>        Park a prompt (status → held) under prompts/held/:
+                             kept in list, hidden from hud/briefing pending
+                             surfaces, skipped by \`prompts next\`.
+  unhold <file-or-slug>      Move a held prompt back to pending.
+  shelve / unshelve          Legacy aliases for hold / unhold.
   new <slug> [body]          Create a new prompt (alias for
                              \`dotmd new prompt <slug> [body]\`)
 
@@ -931,7 +936,7 @@ Subcommands:
 slug matching a prompt basename, or a unique substring of a prompt
 path. Ambiguous substrings error with the candidate list.
 
-Default prompt statuses: pending, shelved, claimed, archived.
+Default prompt statuses: pending, held, shelved, claimed, archived.
 
 Examples:
   dotmd prompts                        # pending prompts (default)

package/dotmd.config.example.mjs

@@ -144,6 +144,7 @@ export const index = {
   path: 'docs/docs.md',
   startMarker: '<!-- GENERATED:dotmd:start -->',
   endMarker: '<!-- GENERATED:dotmd:end -->',
+  snapshot: 'status', // default; use 'state' to include live current_state text
   archivedLimit: 8,
 };
 

package/package.json

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

package/src/config.mjs

@@ -11,6 +11,7 @@ const CONFIG_FILENAMES = ['dotmd.config.mjs', '.dotmd.config.mjs', 'dotmd.config
 const REPLACE_KEYS = new Set([
   'statuses.staleDays',
   'statuses.rootStatuses',
+  'lifecycle.filedStatuses',
   'presets',
   'context',
 ]);
@@ -36,8 +37,8 @@ const DEFAULTS = {
       staleDays: { draft: 30, active: 14, review: 14 },
     },
     prompt: {
-      statuses: ['pending', 'shelved', 'claimed', 'archived'],
-      context: { expanded: ['pending'], listed: ['shelved'], counted: ['claimed', 'archived'] },
+      statuses: ['pending', 'held', 'shelved', 'claimed', 'archived'],
+      context: { expanded: ['pending'], listed: ['held', 'shelved'], counted: ['claimed', 'archived'] },
       staleDays: { pending: 30 },
     },
   },
@@ -58,10 +59,10 @@ const DEFAULTS = {
     skipStaleFor: ['archived', 'reference', 'partial', 'queued-after'],
     skipWarningsFor: ['archived', 'partial', 'queued-after'],
     terminalStatuses: ['archived', 'deprecated', 'reference'],
-    // F15: opt-in per-status `{ filed: true }` in `types.<type>.statuses`
-    // populates this map (status → dirName). Empty by default — archive: true
-    // remains a separate primitive untouched.
-    filedStatuses: {},
+    // F15: per-status filing buckets (status → dirName). Built-in held/paused
+    // statuses file under the owning type folder; archive remains a separate
+    // primitive untouched.
+    filedStatuses: { held: 'held', shelved: 'held', paused: 'held' },
   },
 
   taxonomy: {
@@ -315,6 +316,10 @@ function validateConfig(userConfig, config, validStatuses, indexPath) {
     warnings.push(`Config: index path does not exist: ${indexPath}`);
   }
 
+  if (config.index?.snapshot !== undefined && !['status', 'state'].includes(config.index.snapshot)) {
+    warnings.push("Config: index.snapshot must be 'status' or 'state'.");
+  }
+
   // Unknown top-level user config keys
   for (const key of Object.keys(userConfig)) {
     if (!VALID_CONFIG_KEYS.has(key)) {
@@ -511,6 +516,7 @@ export async function resolveConfig(cwd, explicitConfigPath) {
     indexPath,
     indexStartMarker: config.index?.startMarker ?? '<!-- GENERATED:dotmd:start -->',
     indexEndMarker: config.index?.endMarker ?? '<!-- GENERATED:dotmd:end -->',
+    indexSnapshot: config.index?.snapshot ?? 'status',
     archivedHighlightLimit: config.index?.archivedLimit ?? 8,
 
     context: config.context,

package/src/hud.mjs

@@ -4,21 +4,11 @@ import { readLeases, findStaleLeases, currentSessionId, isLeaseStale, STALE_LEAS
 import { scrubStaleSilently } from './lease-scrub.mjs';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { asString, toRepoPath } from './util.mjs';
-import { dim, yellow } from './color.mjs';
+import { dim } from './color.mjs';
 import { buildIndex } from './index.mjs';
 import { refreshStaleSlashCommands } from './claude-commands.mjs';
 import { readJournalEntries, journalFilePath } from './journal.mjs';
 
-const MAX_PREVIEW = 5;
-
-function slug(repoPath) { return path.basename(repoPath, '.md'); }
-
-function previewList(items, max = MAX_PREVIEW) {
-  const slugs = items.slice(0, max).map(slug);
-  const more = items.length > max ? `, +${items.length - max} more` : '';
-  return slugs.join(', ') + more;
-}
-
 // Statuses that count as "actionable" for a prompt are derived from config:
 // types.prompt.context.expanded (the statuses the user wants prominently shown).
 // Falls back to ['pending'] when no prompt type is configured (defensive default
@@ -223,11 +213,12 @@ export function runHud(argv, config) {
   const hud = buildHud(config);
 
   // Self-heal stale slash-command files. Wrapped: a broken scaffolder must
-  // never kill the SessionStart hook (would block every session). Skipped in
-  // --json mode to keep the structured shape stable for programmatic callers.
-  let refreshed = [];
+  // never kill the SessionStart hook (would block every session). Runs for its
+  // side effect only — the refresh is no longer announced in stdout (see the
+  // primer-only contract below). Skipped in --json mode to keep the structured
+  // shape stable for programmatic callers.
   if (!json) {
-    try { refreshed = refreshStaleSlashCommands(config); }
+    try { refreshStaleSlashCommands(config); }
     catch { /* swallow — see comment above */ }
   }
 
@@ -236,58 +227,15 @@ export function runHud(argv, config) {
     return;
   }
 
-  const lines = [];
-
-  // Always-on command primer. Replaces the prior plan-state / prompts /
-  // stuck-leases / validation-errors lines — those signals belong inside
-  // their own commands (`plans`, `prompts`), not in the SessionStart hook.
-  // hud's job is purely to remind the agent which verbs exist, since that's
-  // the one thing the agent reaches for `--help` to recover. Keep it tight:
-  // one line, the minimum verb set.
-  lines.push(dim('dotmd: plans|briefing  set <status> [<file>]  new <type> <slug>  use [<file>]  archive <file>  (use [no-arg] → oldest pending prompt)'));
-
-  const state = [];
-  if (hud.owned?.length) state.push(`held: ${hud.owned.length} (${previewList(hud.owned)})`);
-  if (hud.prompts?.length) state.push(`prompts: ${hud.prompts.length} (${previewList(hud.prompts)})`);
-  if (hud.stale?.length) state.push(`stuck: ${hud.stale.length} (${previewList(hud.stale)})`);
-  if (hud.errors > 0) state.push(`errors: ${hud.errors} (run dotmd check)`);
-  if (state.length) lines.push(yellow(state.join(' · ')));
-
-  if (refreshed.length > 0) {
-    const from = refreshed[0].from;
-    const to = refreshed[0].to;
-    const names = refreshed.map(r => r.name).join(', ');
-    lines.push(dim(`↻ slash commands refreshed (v${from} → v${to}): ${names}`));
-  }
-
-  // F17b: three journal-aware sections. Silent-when-clean: each block emits
-  // only when it has entries.
-  if (hud.previousSelf?.length) {
-    lines.push(dim('— previous self —'));
-    for (const e of hud.previousSelf) {
-      const cmd = (e.argv ?? []).join(' ');
-      const exitTag = e.exit === 0 ? '' : `, exit ${e.exit}`;
-      lines.push(dim(`  ${cmd} (${e.ago}${exitTag})`));
-    }
-  }
-
-  if (hud.fleet?.length) {
-    lines.push(dim('— fleet (last 24h) —'));
-    for (const f of hud.fleet) {
-      const heldTag = f.holding?.length
-        ? ` · holding ${f.holding.map(p => path.basename(p, '.md')).join(', ')}`
-        : '';
-      const staleTag = f.stale ? yellow(' [stale]') : '';
-      lines.push(dim(`  session ${f.sid} · ${f.cmds} cmds · last ${f.lastAgo}${heldTag}`) + staleTag);
-    }
-  }
-
-  if (hud.recentRejections?.length) {
-    lines.push(dim('— recent rejections (last 1h) —'));
-    for (const r of hud.recentRejections) {
-      lines.push(dim(`  ${r.count}× "${r.cls}" on \`${r.cmd}\``));
-    }
-  }
-
-  process.stdout.write(lines.join('\n') + '\n');
+  // SessionStart contract: emit ONLY the command primer — the verb cheat-sheet
+  // that tells the agent which dotmd verbs exist. Everything else hud used to
+  // print (held/prompts/stuck/errors state, slash-command refresh notices, and
+  // the journal-aware previous-self / fleet / recent-rejections sections) is
+  // deliberately suppressed here: those signals nudged agents into phantom
+  // follow-up work — e.g. "errors: 1 (run dotmd check)" prompting a check run
+  // for state that belongs inside its own command. Each of those signals lives
+  // in its proper command (`plans`, `prompts`, `check`) and stays available via
+  // `dotmd hud --json` for programmatic callers. The hook's job is purely to
+  // teach the verbs, never to report status.
+  process.stdout.write(dim('dotmd: plans|briefing  set <status> [<file>]  new <type> <slug>  use [<file>]  archive <file>  (use [no-arg] → oldest pending prompt)') + '\n');
 }

package/src/index-file.mjs

@@ -21,6 +21,7 @@ export function renderIndexFile(index, config) {
 function renderGeneratedBlock(index, config) {
   const lines = [];
   const indexDir = config.indexPath ? path.dirname(path.relative(config.repoRoot, config.indexPath)).split(path.sep).join('/') : '';
+  const snapshotMode = config.indexSnapshot ?? 'status';
 
   for (const status of config.statusOrder) {
     const docs = index.docs.filter(doc => doc.status === status);
@@ -34,10 +35,9 @@ function renderGeneratedBlock(index, config) {
 
     lines.push(`## ${capitalize(status)}`);
     lines.push('');
-    lines.push('| Doc | Status Snapshot |');
-    lines.push('|-----|-----------------|');
+    lines.push(...snapshotHeader(snapshotMode));
     for (const doc of docs) {
-      const snapshot = formatSnapshot(doc, config);
+      const snapshot = renderIndexSnapshot(doc, config, snapshotMode);
       const linkPath = indexDir ? path.relative(indexDir, doc.path).split(path.sep).join('/') : doc.path;
       lines.push(`| [${escapeTable(doc.title)}](${linkPath}) | ${escapeTable(snapshot)} |`);
     }
@@ -76,6 +76,16 @@ function renderArchivedSection(docs, config, status) {
   return lines;
 }
 
+function snapshotHeader(snapshotMode) {
+  if (snapshotMode === 'state') return ['| Doc | Status Snapshot |', '|-----|-----------------|'];
+  return ['| Doc | Status |', '|-----|--------|'];
+}
+
+function renderIndexSnapshot(doc, config, snapshotMode) {
+  if (snapshotMode === 'state') return formatSnapshot(doc, config);
+  return capitalize(doc.status ?? 'unknown');
+}
+
 export function writeIndex(content, config) {
   writeFileSync(config.indexPath, content, 'utf8');
 }

package/src/init.mjs

@@ -189,6 +189,7 @@ function generateDetectedConfig(scan, rootPath) {
   lines.push(`  path: '${rootPath}/docs.md',`);
   lines.push(`  startMarker: '<!-- GENERATED:dotmd:start -->',`);
   lines.push(`  endMarker: '<!-- GENERATED:dotmd:end -->',`);
+  lines.push(`  snapshot: 'status',`);
   lines.push('};');
   lines.push('');
 

package/src/lifecycle.mjs

@@ -26,6 +26,23 @@ function findFileRoot(filePath, config) {
   return roots.find(r => filePath.startsWith(r + '/')) ?? config.docsRoot;
 }
 
+function defaultTypeDir(docType, config) {
+  if (docType === 'plan') return 'plans';
+  if (docType === 'prompt') return 'prompts';
+  const templateDir = config.raw?.templates?.[docType]?.dir;
+  return typeof templateDir === 'string' && templateDir ? templateDir : null;
+}
+
+function findFilingRoot(filePath, fileRoot, docType, config) {
+  const dirName = defaultTypeDir(docType, config);
+  if (!dirName) return fileRoot;
+  if (path.basename(fileRoot) === dirName) return fileRoot;
+
+  const relSegments = path.relative(fileRoot, filePath).split(path.sep);
+  if (relSegments[0] === dirName) return path.join(fileRoot, dirName);
+  return fileRoot;
+}
+
 // Best-effort index regen for any doc-set or doc-status mutation. The
 // generated block groups by status and embeds per-doc snapshots, so any
 // change that affects what would render leaves the index stale. Wrapped
@@ -167,8 +184,9 @@ export async function runStatus(argv, config, opts = {}) {
 
   const today = nowIso();
   const archiveDir = path.join(fileRoot, config.archiveDir);
-  const relFromRoot = path.relative(fileRoot, filePath);
-  const relSegments = relFromRoot.split(path.sep);
+  const filingRoot = findFilingRoot(filePath, fileRoot, docType, config);
+  const relFromFilingRoot = path.relative(filingRoot, filePath);
+  const relSegments = relFromFilingRoot.split(path.sep);
   const inArchive = isArchivedPath(toRepoPath(filePath, config.repoRoot), config);
   const isArchiving = config.lifecycle.archiveStatuses.has(newStatus) && !inArchive;
   const isUnarchiving = !config.lifecycle.archiveStatuses.has(newStatus) && inArchive;
@@ -200,12 +218,12 @@ export async function runStatus(argv, config, opts = {}) {
       finalPath = targetPath;
     }
     if (isFiling) {
-      const targetPath = path.join(fileRoot, newFiledDir, path.basename(filePath));
+      const targetPath = path.join(filingRoot, newFiledDir, path.basename(filePath));
       process.stdout.write(`${prefix} Would file: ${toRepoPath(filePath, config.repoRoot)} → ${toRepoPath(targetPath, config.repoRoot)}\n`);
       finalPath = targetPath;
     }
     if (isUnfiling) {
-      const targetPath = path.join(fileRoot, path.basename(filePath));
+      const targetPath = path.join(filingRoot, path.basename(filePath));
       process.stdout.write(`${prefix} Would unfile: ${toRepoPath(filePath, config.repoRoot)} → ${toRepoPath(targetPath, config.repoRoot)}\n`);
       finalPath = targetPath;
     }
@@ -236,7 +254,7 @@ export async function runStatus(argv, config, opts = {}) {
   }
 
   if (isFiling) {
-    const targetDir = path.join(fileRoot, newFiledDir);
+    const targetDir = path.join(filingRoot, newFiledDir);
     mkdirSync(targetDir, { recursive: true });
     const targetPath = path.join(targetDir, path.basename(filePath));
     if (existsSync(targetPath)) { die(`Target already exists: ${toRepoPath(targetPath, config.repoRoot)}`); }
@@ -246,7 +264,7 @@ export async function runStatus(argv, config, opts = {}) {
   }
 
   if (isUnfiling) {
-    const targetPath = path.join(fileRoot, path.basename(filePath));
+    const targetPath = path.join(filingRoot, path.basename(filePath));
     if (existsSync(targetPath)) { die(`Target already exists: ${toRepoPath(targetPath, config.repoRoot)}`); }
     const result = gitMv(filePath, targetPath, config.repoRoot);
     if (result.status !== 0) { die(result.stderr || 'git mv failed.'); }

package/src/prompts.mjs

@@ -11,7 +11,7 @@ import { green, dim } from './color.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
 // canonical output ("Consumed: …") is unchanged.
-const SUBCOMMANDS = new Set(['list', 'next', 'use', 'resume', 'archive', 'new', 'shelve', 'unshelve']);
+const SUBCOMMANDS = new Set(['list', 'next', 'use', 'resume', 'archive', 'new', 'hold', 'unhold', 'shelve', 'unshelve']);
 
 export async function runPrompts(argv, config, opts = {}) {
   const sub = argv[0];
@@ -28,8 +28,10 @@ export async function runPrompts(argv, config, opts = {}) {
     case 'resume':   return runPromptsUse(rest, config, opts);
     case 'archive':  return runPromptsArchive(rest, config, opts);
     case 'new':      return runPromptsNew(rest, config, opts);
-    case 'shelve':   return runPromptsShelve(rest, config, opts);
-    case 'unshelve': return runPromptsUnshelve(rest, config, opts);
+    case 'hold':     return runPromptsHold(rest, config, opts);
+    case 'unhold':   return runPromptsUnhold(rest, config, opts);
+    case 'shelve':   return runPromptsHold(rest, config, opts);
+    case 'unshelve': return runPromptsUnhold(rest, config, opts);
   }
 }
 
@@ -190,7 +192,8 @@ function runPromptsNext(argv, config, opts = {}) {
 // path + '.md', exact basename match across type: prompt docs, substring
 // match across type: prompt docs. Returns the absolute path or dies with a
 // helpful message (no match / ambiguous match).
-function resolvePromptInput(input, config) {
+export function resolvePromptInput(input, config, options = {}) {
+  const dieOnMiss = options.dieOnMiss !== false;
   const direct = resolveDocPath(input, config);
   if (direct) return direct;
 
@@ -201,7 +204,10 @@ function resolvePromptInput(input, config) {
 
   const index = buildIndex(config);
   const prompts = index.docs.filter(d => d.type === 'prompt');
-  if (prompts.length === 0) die(`No prompts in the index.`);
+  if (prompts.length === 0) {
+    if (dieOnMiss) die(`No prompts in the index.`);
+    return null;
+  }
 
   const slug = input.replace(/\.md$/, '');
 
@@ -219,7 +225,8 @@ function resolvePromptInput(input, config) {
     die(`Multiple prompts match "${input}":\n${bySubstring.map(d => '  ' + d.path).join('\n')}`);
   }
 
-  die(`No prompt found matching: ${input}`);
+  if (dieOnMiss) die(`No prompt found matching: ${input}`);
+  return null;
 }
 
 function runPromptsUse(argv, config, opts = {}) {
@@ -300,16 +307,16 @@ async function runPromptsNew(argv, config, opts = {}) {
   return runNew(['prompt', ...argv], config, opts);
 }
 
-async function runPromptsShelve(argv, config, opts = {}) {
+async function runPromptsHold(argv, config, opts = {}) {
   const input = argv.find(a => !a.startsWith('-'));
-  if (!input) die('Usage: dotmd prompts shelve <file-or-slug>');
+  if (!input) die('Usage: dotmd prompts hold <file-or-slug>');
   const filePath = resolvePromptInput(input, config);
-  return runStatus([filePath, 'shelved'], config, opts);
+  return runStatus([filePath, 'held'], config, opts);
 }
 
-async function runPromptsUnshelve(argv, config, opts = {}) {
+async function runPromptsUnhold(argv, config, opts = {}) {
   const input = argv.find(a => !a.startsWith('-'));
-  if (!input) die('Usage: dotmd prompts unshelve <file-or-slug>');
+  if (!input) die('Usage: dotmd prompts unhold <file-or-slug>');
   const filePath = resolvePromptInput(input, config);
   return runStatus([filePath, 'pending'], config, opts);
 }

package/src/use.mjs

@@ -1,7 +1,7 @@
 import { readFileSync } from 'node:fs';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { asString, die, resolveDocPath, toRepoPath } from './util.mjs';
-import { consumePrompt, pendingPromptsOldestFirst } from './prompts.mjs';
+import { consumePrompt, pendingPromptsOldestFirst, resolvePromptInput } from './prompts.mjs';
 import { runPickup } from './lifecycle.mjs';
 
 // Top-level `dotmd use [file]` — the single "start engaging with this doc"
@@ -22,7 +22,7 @@ export async function runUse(argv, config, opts = {}) {
     return consumePrompt(head.abs, config, opts);
   }
 
-  const filePath = resolveDocPath(positional, config);
+  const filePath = resolveDocPath(positional, config) ?? resolvePromptInput(positional, config, { dieOnMiss: false });
   if (!filePath) die(`File not found: ${positional}`);
 
   const raw = readFileSync(filePath, 'utf8');

package/src/validate.mjs

@@ -49,6 +49,11 @@ function liveTypeDirsForRoots(config) {
     for (const dirName of filedDirs) {
       if (path.basename(rootRel) === dirName) continue;
       set.add(rootRel ? `${rootRel}/${dirName}` : dirName);
+      for (const typeDir of BUILTIN_TYPE_DIR_NAMES) {
+        if (path.basename(rootRel) === typeDir) continue;
+        const typeRoot = rootRel ? `${rootRel}/${typeDir}` : typeDir;
+        set.add(`${typeRoot}/${dirName}`);
+      }
     }
   }
   return set;