dotmd-cli 0.44.0 → 0.45.1

package/bin/dotmd.mjs

@@ -19,8 +19,9 @@ Common commands:
   briefing              Full briefing with plan counts + next steps
   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
+                        (no file: consume oldest pending prompt)
   archive <file>        Close out a plan (status → archived, move, update refs)
-  prompts [next|use|new]  Manage saved prompts
 
 More help:
   dotmd help all        Full command list
@@ -42,8 +43,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)
-  prompts [list|next|use|archive|new]
-                                    Manage saved prompts (default: list pending)
+  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.
   stale                             Stale docs (preset)
   actionable                        Docs with next steps (preset)
 
@@ -67,7 +68,7 @@ Validate & Fix:
   fix-refs [--dry-run]              Auto-fix broken reference paths + body links
 
 Lifecycle:
-  set <status> [<file>]             Unified transition: archive/release/start/transition in one verb
+  set <status> [<file>]             Unified transition: start work, change status, close out, archive — all via target status
   runlist <hub> [next]              Show or walk an ordered group of plans (see \`dotmd help runlist\`)
   status <file> <status>            Transition document status (deprecated; prefer \`set\`)
   archive <file>                    Archive (status + move + update refs)
@@ -1179,6 +1180,24 @@ async function main() {
     await runPrompts(restArgs, config, { dryRun, verbose });
     return;
   }
+  // Top-level `dotmd use [file]` — the single "start engaging with this doc"
+  // verb. Dispatches by the target doc's type: prompt → consume + archive,
+  // plan → acquire lease + print, doc → print. With no file: consume oldest
+  // pending prompt. See src/use.mjs for the dispatch table.
+  if (command === 'use') {
+    const { runUse } = await import('../src/use.mjs');
+    await runUse(restArgs, config, { dryRun });
+    return;
+  }
+  // `dotmd next` is a top-level alias for `dotmd use` with no arg — consume
+  // the oldest pending prompt. Wired separately so agents who reach for the
+  // literal verb "next" don't bounce off an Unknown-command. Any positional
+  // arg is ignored (a named file goes through `use`).
+  if (command === 'next') {
+    const { runUse } = await import('../src/use.mjs');
+    await runUse(restArgs.filter(a => a.startsWith('-')), config, { dryRun });
+    return;
+  }
 
   // Commands that handle their own index building
   if (command === 'diff') { const { runDiff } = await import('../src/diff.mjs'); runDiff(restArgs, config); return; }

package/package.json

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

package/src/claude-commands.mjs

@@ -19,9 +19,9 @@ function markerFor(version) { return `<!-- dotmd-generated: ${version} -->`; }
 // gets a per-type status vocab appended at generation time so agents arrive
 // with the valid `dotmd status` / `dotmd archive` values already in context.
 const SLASH_DESCRIPTIONS = {
-  plans: "dotmd-managed plan briefing for this repo. Use when the user asks what's on the plate, references a plan slug, queues work, or wants to pick up / release / archive a plan.",
+  plans: "dotmd-managed plan briefing for this repo. Use when the user asks what's on the plate, references a plan slug, queues work, or wants to start / close / archive a plan.",
   docs: "dotmd-managed docs briefing for this repo. Use when the user asks to list, scaffold, query, validate, archive, or rename non-plan docs (reference docs, ADRs, RFCs, design notes), or asks how the dotmd doc lifecycle works here.",
-  baton: "Save a resume prompt for the held plan and release the lease — the minimum handoff. Use when the user says hand off / save a resume / wrap up, or when context is getting tight.",
+  baton: "Save a resume prompt for the active plan and close it out — the minimum handoff. Use when the user says hand off / save a resume / wrap up, or when context is getting tight.",
 };
 
 const VOCAB_TRUNCATE_AT = 12;
@@ -64,15 +64,15 @@ function generatePlansCommand(config, version) {
   lines.push('Plan-specific commands:');
   lines.push('- `dotmd context` — briefing with active/paused/ready plans, age tags, next steps');
   lines.push('- `dotmd set <status> [<file>]` — single status verb. Use this to start, transition, or close any plan:');
-  lines.push('    - `dotmd set in-session <file>` — start work on a plan (acquires the lease + prints body)');
-  lines.push('    - `dotmd set <status> [<file>]` — transition to any other status; if you held the lease it releases automatically');
+  lines.push('    - `dotmd set in-session <file>` — start work on a plan (marks in-session + prints body)');
+  lines.push('    - `dotmd set <status> [<file>]` — transition to any other status; closes out the in-session marker automatically');
   lines.push('    - `dotmd set archived <file>` — close out (same as `dotmd archive`)');
   lines.push('- `dotmd archive <file>` — explicit archive with ref-fixing (equivalent to `set archived`)');
   lines.push('- `dotmd bulk archive <files>` — archive multiple at once');
   lines.push('- `dotmd new plan <name>` — scaffold with full phase structure');
-  lines.push('- `dotmd prompts new <name>` — save a resume-prompt to docs/prompts/ (pipe stdin or @path for body)');
-  lines.push('- `dotmd prompts next` — consume oldest pending prompt (prints body, auto-archives)');
-  lines.push('- `dotmd prompts use <file>` — consume a specific prompt (prints body, auto-archives)');
+  lines.push('- `dotmd new prompt <name>` — save a resume-prompt to docs/prompts/ (pipe stdin or @path for body)');
+  lines.push('- `dotmd use` — consume oldest pending prompt (prints body, auto-archives)');
+  lines.push('- `dotmd use <file>` — open any doc by type: prompt → consume, plan → start work, doc → read');
   lines.push('- `dotmd unblocks <file>` — what depends on / is blocked by a plan');
   lines.push('- `dotmd actionable` — ready plans with next steps (what to promote)');
   lines.push('- `dotmd query --keyword <term>` — find plans by keyword');
@@ -87,7 +87,7 @@ function generatePlansCommand(config, version) {
   lines.push('If the user asks to change a plan\'s status, use `dotmd set <status> <file>`.');
   lines.push('If the user asks to archive a plan, use `dotmd set archived <file>` (or `dotmd archive <file>`).');
   lines.push('');
-  lines.push('**Saved prompts (`docs/prompts/*.md`):** if the user references a file under `docs/prompts/` — e.g. "resume via docs/prompts/foo.md", "use this prompt", "load that one" — consume it with `dotmd prompts use <file>` (atomically prints the body and archives the prompt so it cannot be double-consumed). Do NOT `cat` it, read it with the file-reading tool, or copy its body into chat. To pick the oldest pending prompt without naming a file, use `dotmd prompts next`.');
+  lines.push('**Saved prompts (`docs/prompts/*.md`):** if the user references a file under `docs/prompts/` — e.g. "resume via docs/prompts/foo.md", "use this prompt", "load that one" — consume it with `dotmd use <file>` (atomically prints the body and archives the prompt so it cannot be double-consumed). Do NOT `cat` it, read it with the file-reading tool, or copy its body into chat. To pick the oldest pending prompt without naming a file, run `dotmd use` with no arg.');
   lines.push('');
 
   return lines.join('\n');
@@ -100,12 +100,12 @@ function generateBatonCommand(config, version) {
   lines.push('1. **Save the resume prompt.** `dotmd new prompt resume-<plan-slug>` — pipe stdin or pass `@path`. 10-20 line body: the next concrete decision plus any gotchas. NOT a recap of the plan body. The saved prompt IS the handoff — never print it into chat for copy-paste.');
   lines.push('');
   lines.push('2. **Close out via `dotmd set <status>`.** Pick the status that matches reality:');
-  lines.push('    - `dotmd set active <file>` — work continues, release the lease back to the queue');
+  lines.push('    - `dotmd set active <file>` — work continues, return the plan to the active queue');
   lines.push('    - `dotmd set archived <file>` — fully shipped (also: `dotmd archive <file>`)');
   lines.push('    - `dotmd set paused <file>` / `awaiting <file>` / `partial <file>` / `blocked <file>` — when the status really changed');
-  lines.push('  `set` releases the held lease automatically when transitioning out of `in-session`.');
+  lines.push('  `set` clears the in-session marker automatically when transitioning to any other status.');
   lines.push('');
-  lines.push('If you don\'t already know which plan you hold: `dotmd hud --json` and read `.owned`. Do NOT use `dotmd plans --status in-session` — that lists every session\'s holdings, not just yours.');
+  lines.push('If you don\'t already know which plan you have in-session: `dotmd hud --json` and read `.owned`. Do NOT use `dotmd plans --status in-session` — that lists every session\'s in-session plans, not just yours.');
   lines.push('');
   lines.push('The next session\'s `dotmd hud` (SessionStart hook) surfaces the pending prompt automatically.');
   lines.push('');
@@ -149,10 +149,10 @@ function generateDocsCommand(config, version) {
   lines.push('Lifecycle:');
   lines.push('- `dotmd new plan <name>` — scaffold new plan');
   lines.push('- `dotmd new doc <name>` — scaffold reference doc');
-  lines.push('- `dotmd prompts new <name> "<body>"` — save a resume-prompt');
-  lines.push('- `dotmd prompts next` — consume oldest pending prompt (prints body, auto-archives)');
-  lines.push('- `dotmd prompts use <file>` — consume a specific prompt (prints body, auto-archives)');
-  lines.push('- `dotmd set <status> [<file>]` — unified transition (archive / release / status bump; infers path from held lease)');
+  lines.push('- `dotmd new prompt <name>` — save a resume-prompt (pipe stdin or @path for body)');
+  lines.push('- `dotmd use` — consume oldest pending prompt (prints body, auto-archives)');
+  lines.push('- `dotmd use <file>` — open any doc by type: prompt → consume, plan → start work, doc → read');
+  lines.push('- `dotmd set <status> [<file>]` — unified transition (archive / status bump; infers path from your active in-session plan)');
   lines.push('- `dotmd status <file> <status>` — transition status (legacy; `set` is preferred)');
   lines.push('- `dotmd archive <file>` — archive with auto ref-fixing');
   lines.push('- `dotmd bulk archive <files>` — archive multiple at once');
@@ -161,7 +161,7 @@ function generateDocsCommand(config, version) {
   lines.push('- `dotmd fix-refs` — repair broken references and body links');
   lines.push('- `dotmd rename <old> <new>` — rename doc + update all references');
   lines.push('');
-  lines.push('**Saved prompts (`docs/prompts/*.md`):** if the user references a file under `docs/prompts/` — e.g. "resume via docs/prompts/foo.md", "use this prompt" — consume it with `dotmd prompts use <file>` (prints the body and archives atomically). Do NOT `cat` it or read it with the file-reading tool. To pick the oldest pending prompt without naming a file, use `dotmd prompts next`.');
+  lines.push('**Saved prompts (`docs/prompts/*.md`):** if the user references a file under `docs/prompts/` — e.g. "resume via docs/prompts/foo.md", "use this prompt" — consume it with `dotmd use <file>` (prints the body and archives atomically). Do NOT `cat` it or read it with the file-reading tool. To pick the oldest pending prompt without naming a file, run `dotmd use` with no arg.');
   lines.push('');
 
   return lines.join('\n');

package/src/commands.mjs

@@ -4,7 +4,7 @@
 // templates points at a real command.
 export const KNOWN_COMMANDS = [
   'list', 'json', 'check', 'coverage', 'stats', 'graph', 'deps', 'briefing', 'context', 'hud',
-  'focus', 'query', 'plans', 'prompts', 'stale', 'actionable', 'index', 'pickup', 'release', 'status', 'set', 'archive', 'bulk', 'bulk-tag', 'touch', 'doctor',
+  'focus', 'query', 'plans', 'prompts', 'stale', 'actionable', 'index', 'pickup', 'release', 'status', 'set', 'use', 'next', 'archive', 'bulk', 'bulk-tag', 'touch', 'doctor',
   'unblocks', 'health', 'glossary', 'modules', 'module',
   'fix-refs', 'lint', 'rename', 'migrate', 'notion', 'export', 'summary',
   'watch', 'diff', 'new', 'init', 'completions', 'statuses', 'journal',

package/src/hud.mjs

@@ -122,7 +122,7 @@ export function runHud(argv, config) {
   // 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>  prompts next|use|new  archive <file>'));
+  lines.push(dim('dotmd: plans|briefing  set <status> [<file>]  new <type> <slug>  use [<file>]  archive <file>  (use [no-arg] → oldest pending prompt)'));
 
   if (refreshed.length > 0) {
     const from = refreshed[0].from;

package/src/lifecycle.mjs

@@ -115,7 +115,7 @@ export async function runStatus(argv, config, opts = {}) {
   let newStatus = argv[1];
 
   if (!opts.suppressDeprecation) {
-    process.stderr.write(dim('`dotmd status <file> <status>` is deprecated; prefer `dotmd set <status> [<file>]` (note: <status> first, <file> optional when a lease is held). Removed in a future major.\n'));
+    process.stderr.write(dim('`dotmd status <file> <status>` is deprecated; prefer `dotmd set <status> [<file>]` (note: <status> first; <file> optional when a plan is in-session). Removed in a future major.\n'));
   }
 
   if (!input) { die('Usage: dotmd status <file> <new-status>'); }
@@ -326,11 +326,11 @@ export async function runPickup(argv, config, opts = {}) {
     leaseOutcome = result.outcome;
     if (result.outcome === 'conflict-alive') {
       const c = result.conflict;
-      die(`Held by ${c.host}/${c.session} (pid ${c.pid}) since ${c.pickedUpAt}.\nUse --takeover to override.\n  ${repoPath}`);
+      die(`Plan is in-session with ${c.host}/${c.session} (pid ${c.pid}) since ${c.pickedUpAt}.\nUse --takeover to override.\n  ${repoPath}`);
     }
     if (result.outcome === 'conflict-stale') {
       const c = result.conflict;
-      die(`Stale in-session lease from ${c.host}/${c.session} since ${c.pickedUpAt} (>${STALE_LEASE_AGE_HOURS}h old).\nUse --takeover to claim.\n  ${repoPath}`);
+      die(`Plan flagged in-session by ${c.host}/${c.session} since ${c.pickedUpAt} (>${STALE_LEASE_AGE_HOURS}h ago, looks abandoned).\nUse --takeover to claim.\n  ${repoPath}`);
     }
     if (oldStatus !== 'in-session') {
       updateFrontmatter(filePath, { status: 'in-session', updated: today });
@@ -370,7 +370,7 @@ export async function runPickup(argv, config, opts = {}) {
       process.stderr.write(`${green('▶ Picked up')}: ${repoPath} (${oldStatus ?? 'unset'} → in-session)\n\n`);
     }
     if (fullBody) {
-      const header = `[dotmd] holding ${repoPath} — close with: dotmd set <status> ${repoPath}\n---\n`;
+      const header = `[dotmd] in-session: ${repoPath} — close with: dotmd set <status> ${repoPath}\n---\n`;
       process.stdout.write(header);
       const content = (body ?? '').trim();
       if (content) process.stdout.write(content + '\n');

package/src/pickup-card.mjs

@@ -194,7 +194,7 @@ export function buildCard(filePath, raw, config) {
 // Render the card to human-format string.
 export function renderCard(card) {
   const lines = [];
-  lines.push(`[dotmd] holding ${card.path} — close with: dotmd set <status> ${card.path}`);
+  lines.push(`[dotmd] in-session: ${card.path} — close with: dotmd set <status> ${card.path}`);
   lines.push('---');
   lines.push(`# ${card.title}`);
   const meta = [card.status, card.updated && `updated ${card.updated}`].filter(Boolean).join(' · ');

package/src/prompts.mjs

@@ -118,7 +118,7 @@ function renderPromptsVerbose(index, config, { hasStatusFlag, includeArchived })
   }
 }
 
-function pendingPromptsOldestFirst(config) {
+export function pendingPromptsOldestFirst(config) {
   const index = buildIndex(config);
   const prompts = index.docs.filter(d => d.type === 'prompt' && d.status === 'pending');
 
@@ -192,7 +192,7 @@ function runPromptsUse(argv, config, opts = {}) {
   consumePrompt(filePath, config, { ...opts, noIndex, showFiles });
 }
 
-function consumePrompt(filePath, config, opts) {
+export function consumePrompt(filePath, config, opts) {
   const { dryRun, noIndex, showFiles } = opts;
   const raw = readFileSync(filePath, 'utf8');
   const { frontmatter, body } = extractFrontmatter(raw);

package/src/use.mjs

@@ -0,0 +1,46 @@
+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 { runPickup } from './lifecycle.mjs';
+
+// Top-level `dotmd use [file]` — the single "start engaging with this doc"
+// verb. Dispatches by the target doc's `type:` so agents don't have to know
+// the verb-per-type rule:
+//   - prompt → print body + archive (one-shot consume)
+//   - plan   → acquire lease + print body (same as `set in-session`)
+//   - doc    → print body (read-only)
+// With no argument, consumes the oldest pending prompt.
+export async function runUse(argv, config, opts = {}) {
+  const positional = argv.find(a => !a.startsWith('-'));
+
+  if (!positional) {
+    const queue = pendingPromptsOldestFirst(config);
+    if (queue.length === 0) die('No pending prompts. Pass a file to use a plan or doc.');
+    const head = queue[0];
+    if (!head.abs) die(`Could not resolve path: ${head.doc.path}`);
+    return consumePrompt(head.abs, config, opts);
+  }
+
+  const filePath = resolveDocPath(positional, config);
+  if (!filePath) die(`File not found: ${positional}`);
+
+  const raw = readFileSync(filePath, 'utf8');
+  const { frontmatter } = extractFrontmatter(raw);
+  const parsed = parseSimpleFrontmatter(frontmatter);
+  const type = asString(parsed.type);
+
+  if (type === 'prompt') {
+    return consumePrompt(filePath, config, opts);
+  }
+  if (type === 'plan') {
+    // Delegate to the lease-acquisition path. Same flow as `set in-session`.
+    return runPickup([filePath, ...argv.filter(a => a !== positional)], config, opts);
+  }
+  // Anything else (doc, untyped, custom): print the body. The frontmatter
+  // already names everything an agent needs to know about lifecycle for that
+  // type, so the verb stays a no-op read for non-actionable types.
+  process.stdout.write(raw);
+  if (!raw.endsWith('\n')) process.stdout.write('\n');
+  process.stderr.write(`${toRepoPath(filePath, config.repoRoot)} (${type ?? 'untyped'})\n`);
+}

package/src/validate.mjs

@@ -186,14 +186,14 @@ export function validateDoc(doc, frontmatter, headingTitle, config) {
       doc.warnings.push({
         path: doc.path,
         level: 'warning',
-        message: `\`status: in-session\` but no active lease found (last session may have crashed without releasing). Run \`dotmd set active ${doc.path}\` to clear and re-queue.`,
+        message: `\`status: in-session\` but no session is actually working on this (previous session may have crashed). Run \`dotmd set active ${doc.path}\` to clear and re-queue.`,
       });
     } else if (isLeaseStale(lease)) {
       const ageHours = Math.floor((Date.now() - new Date(lease.pickedUpAt).getTime()) / (1000 * 60 * 60));
       doc.warnings.push({
         path: doc.path,
         level: 'warning',
-        message: `\`status: in-session\` but lease is stale (last touched ${ageHours}h ago, >${STALE_LEASE_AGE_HOURS}h threshold). Run \`dotmd set active ${doc.path}\` to clear and re-queue.`,
+        message: `\`status: in-session\` but last activity was ${ageHours}h ago (>${STALE_LEASE_AGE_HOURS}h, looks abandoned). Run \`dotmd set active ${doc.path}\` to clear and re-queue.`,
       });
     }
   }