dotmd-cli 0.39.7 → 0.39.9

package/bin/dotmd.mjs

@@ -581,10 +581,16 @@ Types and their default destinations:
 \`<name>\` is slugified for the filename.
 
 Body input (all built-in types — required for prompt, optional for plan/doc):
-  <text>                 Inline body as 3rd positional
-  --message "<text>"     Explicit inline body
+  @path                  Read body from a file (preferred for multi-line bodies)
   -                      Read body from stdin (heredoc-friendly for agents)
-  @path                  Read body from a file
+  --message "<text>"     Explicit inline body
+  <text>                 Inline body as 3rd positional
+
+Tip for agents: prefer \`@path\` or \`-\` for multi-line bodies. Inline bodies
+put the entire content on the bash command line, which (a) breaks under shell
+quoting for backticks/dollar-signs and (b) trips PreToolUse hooks that scan
+command strings for forbidden literals (destructive-git patterns, etc.).
+\`@/tmp/foo.md\` sidesteps both.
 
 For plan/doc, a single-section body lands under the type's first scaffolded
 section (e.g. \`## Problem\` for plans). If the body already authors
@@ -594,19 +600,19 @@ the title + your body is emitted — no duplicated empty outline below
 
 Examples:
   dotmd new plan auth-revamp
-  dotmd new plan auth-revamp "Investigation findings before scoping…"
+  dotmd new prompt resume-foo @/tmp/draft.md
+  dotmd new prompt resume-foo - <<'EOF'
+  multi-line
+  prompt body
+  EOF
+  dotmd new prompt cleanup-tomorrow "look at remaining lint warnings"
   dotmd new plan full-spec - <<'EOF'
   ## Problem
   …
   ## Phases
   …
   EOF
-  dotmd new prompt cleanup-tomorrow "look at remaining lint warnings"
-  dotmd new prompt resume-foo - <<'EOF'
-  multi-line
-  prompt body
-  EOF
-  dotmd new prompt from-file @/tmp/draft.md
+  dotmd new plan auth-revamp "Investigation findings before scoping…"
 
 Other options:
   --status <s>         Set initial status (defaults to first valid status for the type)
@@ -754,12 +760,17 @@ Prompts are documents with \`type: prompt\`, typically saved under
 docs/prompts/. They seed future Claude sessions; consuming a prompt
 prints its body to stdout and atomically archives it (one-shot).
 
+\`dotmd prompt\` (singular) is an alias for \`dotmd prompts\` — every
+subcommand below works under either spelling.
+
 Subcommands:
   list                       List pending prompts (default)
   next                       Consume the oldest pending prompt:
                              print body to stdout, flip status to archived
   use <file-or-slug>         Consume a specific prompt (same as next, but
                              targets the named prompt instead of picking oldest)
+  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
@@ -786,6 +797,8 @@ Examples:
   claude "$(dotmd prompts next)"       # consume oldest pending + run claude
   claude "$(dotmd prompts use resume-foo)"           # by slug
   claude "$(dotmd prompts use docs/prompts/foo.md)"  # by path
+  claude "$(dotmd prompts resume resume-foo)"        # \`resume\` is an alias for \`use\`
+  dotmd prompt list                    # singular alias for \`dotmd prompts list\`
 
   dotmd prompts next --dry-run         # preview without consuming
   dotmd prompts archive old-thing
@@ -958,7 +971,7 @@ the whole docs tree is scanned.`,
 
 async function main() {
   const args = process.argv.slice(2);
-  const command = args[0] ?? 'list';
+  let command = args[0] ?? 'list';
 
   // Pre-config flags
   if (args.includes('--version') || args.includes('-v')) {
@@ -979,6 +992,14 @@ async function main() {
     return;
   }
 
+  // Singular-form alias for the prompts subcommand namespace. Trivial
+  // no-collision collapse — `prompt` was previously "unknown command", now
+  // routes everywhere `prompts` does (incl. per-command --help below, and the
+  // subcommand dispatch at the `prompts` branch in the chain). The other
+  // singular/plural pairs (`plan`/`plans`, `module`/`modules`,
+  // `status`/`statuses`) are deliberately kept distinct — see F20 plan.
+  if (command === 'prompt') command = 'prompts';
+
   // Per-command help
   if (args.includes('--help') || args.includes('-h')) {
     process.stdout.write(`${HELP[command] ?? HELP._main}\n`);

package/package.json

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

package/src/hud.mjs

@@ -76,10 +76,13 @@ export function buildHud(config) {
   // Validation error count — hud's "silent when clean" contract should treat
   // `check` errors as not-clean. Without this, a SessionStart hook firing hud
   // can leave the agent with no visible signal that a check is failing.
-  // buildIndex wraps the same scan every other read command does; cost is fine.
+  // `errorsOnly: true` skips warning-only cross-doc passes (git staleness,
+  // bidirectional refs, claude-commands) that hud never reads — ~6× faster on
+  // SessionStart for platform-scale corpora. Per-file validation + checkIndex
+  // still run, so the error count matches `dotmd check`'s.
   let errors = 0;
   try {
-    const index = buildIndex(config);
+    const index = buildIndex(config, { errorsOnly: true });
     errors = index.errors.length;
   } catch { /* swallow — bad config shouldn't break the SessionStart hook */ }
 

package/src/index.mjs

@@ -7,14 +7,22 @@ import { validateDoc, validatePlanShape, validateDocShape, checkBidirectionalRef
 import { checkIndex } from './index-file.mjs';
 import { checkClaudeCommands } from './claude-commands.mjs';
 
-// `fast: true` skips every pass that only produces warnings/errors — the
-// rendered index file consumes only status/title/snapshot/etc., not the
-// validation output. Use it from `regenIndex` (post-mutation index refresh)
-// where validation has already run elsewhere (or will, next time the user
-// runs `dotmd check`). Saves the full-repo `git log` scan in
-// `checkGitStaleness` plus the bidirectional ref walk + claude-commands check.
+// `fast: true` skips every pass that produces warnings/errors — the rendered
+// index file consumes only status/title/snapshot/etc., not the validation
+// output. Use it from `regenIndex` (post-mutation index refresh) where
+// validation has already run elsewhere (or will, next time the user runs
+// `dotmd check`). Saves the full-repo `git log` scan in `checkGitStaleness`
+// plus the bidirectional ref walk + claude-commands check.
+//
+// `errorsOnly: true` runs every error-producing pass (per-file `validateDoc`,
+// `checkIndex`, the `validate` hook) but skips the warning-only cross-doc
+// passes (bidirectional refs, runlist back-pointers, git staleness, claude
+// commands). Use it from `dotmd hud` — the SessionStart hook only renders the
+// error COUNT, so the warning-only passes are pure overhead there. Preserves
+// the invariant that hud's "✗ N validation errors" line matches `dotmd check`.
 export function buildIndex(config, opts = {}) {
-  const { fast = false } = opts;
+  const { fast = false, errorsOnly = false } = opts;
+  const skipWarningOnlyChecks = fast || errorsOnly;
   const docs = collectDocFiles(config).map(f => parseDocFile(f, config, { fast }));
   if (!fast) {
     // Per-file validation (validateDoc) ran during parse without sibling
@@ -86,13 +94,13 @@ export function buildIndex(config, opts = {}) {
     countsByType[type][doc.status] = (countsByType[type][doc.status] ?? 0) + 1;
   }
 
-  if (!fast) {
-    if (config.indexPath) {
-      const indexCheck = checkIndex(transformedDocs, config);
-      warnings.push(...indexCheck.warnings);
-      errors.push(...indexCheck.errors);
-    }
+  if (!fast && config.indexPath) {
+    const indexCheck = checkIndex(transformedDocs, config);
+    warnings.push(...indexCheck.warnings);
+    errors.push(...indexCheck.errors);
+  }
 
+  if (!skipWarningOnlyChecks) {
     const refCheck = checkBidirectionalReferences(transformedDocs, config);
     warnings.push(...refCheck.warnings);
 

package/src/prompts.mjs

@@ -8,7 +8,10 @@ import { runArchive, runStatus } from './lifecycle.mjs';
 import { runNew } from './new.mjs';
 import { green, dim } from './color.mjs';
 
-const SUBCOMMANDS = new Set(['list', 'next', 'use', 'archive', 'new', 'shelve', 'unshelve']);
+// `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']);
 
 export async function runPrompts(argv, config, opts = {}) {
   const sub = argv[0];
@@ -22,6 +25,7 @@ export async function runPrompts(argv, config, opts = {}) {
     case 'list':     return runPromptsList(rest, config, opts);
     case 'next':     return runPromptsNext(rest, config, opts);
     case 'use':      return runPromptsUse(rest, 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);