dotmd-cli 0.31.3 → 0.32.0

package/README.md

@@ -33,9 +33,43 @@ eval "$(dotmd completions bash)"    # add to ~/.bashrc
 eval "$(dotmd completions zsh)"     # add to ~/.zshrc
 ```
 
+## Auto-Detected From Your Markdown
+
+dotmd reads what's already in your `.md` files — you don't have to migrate everything into frontmatter to get useful output.
+
+Add `- [ ]` checkboxes anywhere in the body:
+
+```markdown
+## Polish
+
+- [x] Index regen on every mutation
+- [x] Auto-checklist progress bars
+- [x] Untagged docs surfaced in `list`
+- [ ] SessionStart hook auto-wired by init
+- [ ] Bulk-tag prompt for brownfield repos
+```
+
+`dotmd list` picks them up — zero config, no extra field:
+
+```
+Polish-Pass                   2d  ██████░░░░ 3/5
+```
+
+Same story for these signals, each picked up from body text when the matching frontmatter field is missing:
+
+| Field | Falls back to | Example body |
+|-------|---------------|--------------|
+| `title` | first `# H1` heading | `# Auth Token Refresh` |
+| `summary` | first `> blockquote` line (skipping `Status note` lines) | `> One-line summary of what this doc covers.` |
+| `current_state` | `**Status:** ...`, `- Status: ...`, or `> Status note (...): ...` lines (skipped on terminal docs to avoid stale claims) | `**Status:** Phase 2 underway` |
+| `next_step` | first bullet under a `## Next Step` (or `## Suggested Next Step`) H2 section | `## Next Step`<br>`- wire token refresh into middleware` |
+| Body links | inline `[text](path.md)` references | validated as ref edges by `check` |
+
+Explicit frontmatter always wins. Body extraction is a cushion for partially-tagged docs, not a replacement for it.
+
 ## What It Does
 
-- **Index** — group docs by status, show progress bars, next steps
+- **Index** — group docs by status, with auto-detected progress bars (from `- [ ]` checklists) and next steps
 - **Query** — filter by status, keyword, module, surface, owner, staleness
 - **Validate** — check for missing fields, broken references, broken body links, stale dates
 - **Stats** — health dashboard with staleness, completeness, audit coverage

package/bin/dotmd.mjs

@@ -50,6 +50,7 @@ Lifecycle:
   status <file> <status>            Transition document status
   archive <file>                    Archive (status + move + update refs)
   bulk archive <f1> <f2> ...        Archive multiple files at once
+  bulk-tag [files...]               Tag pre-existing untagged .md files
   touch <file>                      Bump updated date
   touch --git                       Bulk-sync dates from git history
   rename <old> <new>                Rename doc and update all references
@@ -647,6 +648,29 @@ Archives each file: sets status to archived, moves to archive
 directory, updates references, and regenerates the index.
 
 Use --dry-run (-n) to preview changes without writing anything.`,
+
+  'bulk-tag': `dotmd bulk-tag [files...] — fill in type/status frontmatter on pre-existing markdown
+
+Scans the docs tree for files that are missing either \`type:\` or \`status:\`
+(or have no frontmatter block at all) and writes minimal frontmatter so they
+appear in \`dotmd list\`, \`query\`, and \`briefing\`.
+
+Type is inferred from the file's subdir under docsRoot:
+  docs/plans/foo.md    → type: plan,   status: planned
+  docs/prompts/bar.md  → type: prompt, status: pending
+  docs/baz.md          → type: doc,    status: draft
+
+Already-tagged files (both \`type:\` and \`status:\` set) are skipped. Files
+under the archive directory are excluded.
+
+Flags:
+  --type <t>       Override inferred type for every candidate.
+  --status <s>     Override the per-type default status.
+  --json           Emit a structured candidate list.
+  --dry-run (-n)   Preview without writing.
+
+Pass file paths as positional args to scope to those files only; otherwise
+the whole docs tree is scanned.`,
 };
 
 async function main() {
@@ -784,6 +808,8 @@ async function main() {
   if (command === 'status') { const { runStatus } = await import('../src/lifecycle.mjs'); await runStatus(restArgs, config, { dryRun }); return; }
   if (command === 'archive') { const { runArchive } = await import('../src/lifecycle.mjs'); runArchive(restArgs, config, { dryRun }); return; }
   if (command === 'bulk' && restArgs[0] === 'archive') { const { runBulkArchive } = await import('../src/lifecycle.mjs'); runBulkArchive(restArgs.slice(1), config, { dryRun }); return; }
+  if (command === 'bulk' && restArgs[0] === 'tag') { const { runBulkTag } = await import('../src/bulk-tag.mjs'); runBulkTag(restArgs.slice(1), config, { dryRun }); return; }
+  if (command === 'bulk-tag') { const { runBulkTag } = await import('../src/bulk-tag.mjs'); runBulkTag(restArgs, config, { dryRun }); return; }
   if (command === 'touch') { const { runTouch } = await import('../src/lifecycle.mjs'); runTouch(restArgs, config, { dryRun }); return; }
   if (command === 'new') { const { runNew } = await import('../src/new.mjs'); await runNew(restArgs, config, { dryRun, root: rootArg }); return; }
   if (command === 'lint') { const { runLint } = await import('../src/lint.mjs'); runLint(restArgs, config, { dryRun }); return; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.31.3",
+  "version": "0.32.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/bulk-tag.mjs

@@ -0,0 +1,174 @@
+import path from 'node:path';
+import { readFileSync } from 'node:fs';
+import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
+import { collectDocFiles } from './index.mjs';
+import { toRepoPath, die, warn, resolveDocPath } from './util.mjs';
+import { writeFrontmatter } from './lifecycle.mjs';
+import { green, dim, yellow } from './color.mjs';
+
+// Per-type default status for bulk-tagging pre-existing untagged markdown.
+// These intentionally lean conservative (draft / planned) rather than active —
+// the user is triaging files they didn't create through `dotmd new`, so
+// dropping them into the active list would clutter it without consent. The
+// audit handoff endorsed this conservative default.
+const DEFAULT_STATUS_BY_TYPE = {
+  plan: 'planned',
+  doc: 'draft',
+  prompt: 'pending',
+};
+
+// Derive a doc type from the file's first subdir under its docsRoot:
+//   docs/plans/foo.md   → 'plan'
+//   docs/prompts/bar.md → 'prompt'
+//   docs/baz.md         → 'doc'  (root-level under docsRoot)
+//   docs/notes/qux.md   → 'doc'  (unrecognized subdir falls through)
+// Centralizes the inline `rootLabel.includes('plan')` heuristic from lint.mjs
+// and extends it for prompts.
+export function inferTypeFromPath(filePath, docsRoot) {
+  const rel = path.relative(docsRoot, filePath);
+  const segments = rel.split(path.sep);
+  if (segments.length >= 2) {
+    const sub = segments[0];
+    if (sub === 'plans') return 'plan';
+    if (sub === 'prompts') return 'prompt';
+  }
+  return 'doc';
+}
+
+function parseArgs(argv) {
+  const opts = { typeOverride: null, statusOverride: null, json: false, positional: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--type') { opts.typeOverride = argv[++i]; continue; }
+    if (a === '--status') { opts.statusOverride = argv[++i]; continue; }
+    if (a === '--json') { opts.json = true; continue; }
+    if (a.startsWith('-')) die(`Unknown flag: ${a}`);
+    opts.positional.push(a);
+  }
+  return opts;
+}
+
+function findFileRoot(filePath, config) {
+  const roots = config.docsRoots || [config.docsRoot];
+  return roots.find(r => filePath.startsWith(r + '/')) ?? config.docsRoot;
+}
+
+export function runBulkTag(argv, config, opts = {}) {
+  const { dryRun } = opts;
+  const args = parseArgs(argv);
+
+  // Determine candidate set: explicit positional args take precedence; otherwise
+  // scan all collected doc files (which already excludes config.indexPath).
+  const allFiles = collectDocFiles(config);
+  let pool;
+  if (args.positional.length > 0) {
+    pool = args.positional
+      .map(p => resolveDocPath(p, config))
+      .filter(Boolean);
+    if (pool.length === 0) die('No matching files found for the given paths.');
+  } else {
+    pool = allFiles;
+  }
+
+  // Skip already-archived files (mirrors bulk archive's policy at
+  // lifecycle.mjs:569–573) — settled docs shouldn't be retroactively tagged.
+  const archiveDir = config.archiveDir;
+  const inArchive = (f) => {
+    const root = findFileRoot(f, config);
+    const rel = path.relative(root, f);
+    return rel.startsWith(archiveDir + '/') || rel.startsWith(archiveDir + path.sep);
+  };
+
+  const candidates = [];
+  for (const filePath of pool) {
+    if (inArchive(filePath)) continue;
+    let raw;
+    try { raw = readFileSync(filePath, 'utf8'); } catch (err) { warn(`Could not read ${filePath}: ${err.message}`); continue; }
+    const { frontmatter } = extractFrontmatter(raw);
+    const parsed = frontmatter ? parseSimpleFrontmatter(frontmatter) : {};
+    const hasType = typeof parsed.type === 'string' && parsed.type.length > 0;
+    const hasStatus = typeof parsed.status === 'string' && parsed.status.length > 0;
+    // Only files missing type OR status are candidates; fully tagged files are
+    // skipped silently (bulk-tag's job is to fill gaps, not nag).
+    if (hasType && hasStatus) continue;
+
+    const root = findFileRoot(filePath, config);
+    const inferredType = args.typeOverride ?? (hasType ? parsed.type : inferTypeFromPath(filePath, root));
+    const defaultStatus = DEFAULT_STATUS_BY_TYPE[inferredType] ?? 'draft';
+    const inferredStatus = args.statusOverride ?? (hasStatus ? parsed.status : defaultStatus);
+
+    const updates = {};
+    if (!hasType) updates.type = inferredType;
+    if (!hasStatus) updates.status = inferredStatus;
+
+    candidates.push({
+      filePath,
+      relPath: toRepoPath(filePath, config.repoRoot),
+      hadFrontmatter: Boolean(frontmatter),
+      hadType: hasType,
+      hadStatus: hasStatus,
+      currentType: hasType ? parsed.type : null,
+      currentStatus: hasStatus ? parsed.status : null,
+      newType: inferredType,
+      newStatus: inferredStatus,
+      updates,
+    });
+  }
+
+  if (args.json) {
+    process.stdout.write(JSON.stringify({
+      dryRun: Boolean(dryRun),
+      count: candidates.length,
+      candidates: candidates.map(c => ({
+        path: c.relPath,
+        hadFrontmatter: c.hadFrontmatter,
+        currentType: c.currentType,
+        currentStatus: c.currentStatus,
+        newType: c.newType,
+        newStatus: c.newStatus,
+        updates: c.updates,
+      })),
+    }, null, 2) + '\n');
+    if (!dryRun) {
+      for (const c of candidates) {
+        try { writeFrontmatter(c.filePath, c.updates); }
+        catch (err) { warn(`Failed to tag ${c.relPath}: ${err.message}`); }
+      }
+    }
+    return;
+  }
+
+  if (candidates.length === 0) {
+    process.stdout.write(green('No untagged files found.') + '\n');
+    return;
+  }
+
+  process.stdout.write(`${candidates.length} untagged file(s) — will tag:\n`);
+  const pathWidth = Math.min(60, Math.max(...candidates.map(c => c.relPath.length)));
+  for (const c of candidates) {
+    const fields = [];
+    if (c.updates.type) fields.push(`type: ${c.updates.type}`);
+    if (c.updates.status) fields.push(`status: ${c.updates.status}`);
+    const note = c.hadFrontmatter
+      ? `(added ${Object.keys(c.updates).join(', ')})`
+      : '(no frontmatter)';
+    process.stdout.write(`  ${c.relPath.padEnd(pathWidth)}  ${fields.join('  ')}  ${dim(note)}\n`);
+  }
+
+  if (dryRun) {
+    process.stdout.write(dim('\n[dry-run] No changes made.\n'));
+    return;
+  }
+
+  process.stdout.write('\n');
+  let tagged = 0;
+  for (const c of candidates) {
+    try {
+      writeFrontmatter(c.filePath, c.updates);
+      tagged++;
+    } catch (err) {
+      warn(`Failed to tag ${c.relPath}: ${err.message}`);
+    }
+  }
+  process.stdout.write(green(`Tagged ${tagged} file(s).`) + '\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', 'finish', 'status', 'archive', 'bulk', 'touch', 'doctor',
+  'focus', 'query', 'plans', 'prompts', 'stale', 'actionable', 'index', 'pickup', 'release', 'finish', 'status', 'archive', 'bulk', 'bulk-tag', 'touch', 'doctor',
   'unblocks', 'health', 'glossary',
   'fix-refs', 'lint', 'rename', 'migrate', 'notion', 'export', 'summary',
   'watch', 'diff', 'new', 'init', 'completions', 'statuses',

package/src/hud.mjs

@@ -3,7 +3,8 @@ import path from 'node:path';
 import { readLeases, findStaleLeases, currentSessionId } from './lease.mjs';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { asString, toRepoPath } from './util.mjs';
-import { green, yellow, dim } from './color.mjs';
+import { green, yellow, red, dim } from './color.mjs';
+import { buildIndex } from './index.mjs';
 
 const MAX_PREVIEW = 5;
 
@@ -71,7 +72,17 @@ export function buildHud(config) {
   const stale = findStaleLeases(config).map(l => l.path);
   const prompts = findActionablePrompts(config);
 
-  return { owned, stale, prompts };
+  // 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.
+  let errors = 0;
+  try {
+    const index = buildIndex(config);
+    errors = index.errors.length;
+  } catch { /* swallow — bad config shouldn't break the SessionStart hook */ }
+
+  return { owned, stale, prompts, errors };
 }
 
 export function runHud(argv, config) {
@@ -93,6 +104,9 @@ export function runHud(argv, config) {
   if (hud.stale.length > 0) {
     lines.push(yellow(`⚠ ${hud.stale.length} stuck lease${hud.stale.length === 1 ? '' : 's'} >24h  ${dim('(run: dotmd release --stale)')}`));
   }
+  if (hud.errors > 0) {
+    lines.push(red(`✗ ${hud.errors} validation error${hud.errors === 1 ? '' : 's'}  ${dim('(run: dotmd check)')}`));
+  }
 
   if (lines.length === 0) return; // silent when clean
   process.stdout.write(lines.join('\n') + '\n');

package/src/index.mjs

@@ -125,7 +125,37 @@ export function parseDocFile(filePath, config) {
   const headingTitle = extractFirstHeading(body);
   const title = asString(parsedFrontmatter.title) ?? headingTitle ?? path.basename(filePath, '.md');
   const summary = asString(parsedFrontmatter.summary) ?? extractSummary(body) ?? null;
-  const currentState = asString(parsedFrontmatter.current_state) ?? extractStatusSnapshot(body) ?? 'No current_state set';
+  // For terminal-status docs (archived / reference / deprecated by default),
+  // skip the body-scrape and the "No current_state set" fallback when the user
+  // didn't set `current_state:` in frontmatter explicitly. Body text on a
+  // settled doc often contains stale "in progress" / "FIXED (uncommitted)"
+  // snapshots from when the doc was live; surfacing those in the index lies
+  // about current state. Frontmatter still wins if explicit — the audit's
+  // criterion: "should defer to frontmatter when status is terminal."
+  const fmCurrentState = asString(parsedFrontmatter.current_state);
+  const docStatus = asString(parsedFrontmatter.status);
+  const isTerminalDoc = docStatus && config.lifecycle?.terminalStatuses?.has?.(docStatus);
+  // Track where currentState came from so renderers can prefix `(auto)` on
+  // body-scraped values. Frontmatter wins silently; body-scraped values flag
+  // their origin so the user knows the string was inferred (and that adding
+  // `current_state:` to frontmatter would override). The placeholder
+  // `'No current_state set'` is neither — origin stays null.
+  let currentState;
+  let currentStateOrigin = null;
+  if (fmCurrentState) {
+    currentState = fmCurrentState;
+    currentStateOrigin = 'frontmatter';
+  } else if (isTerminalDoc) {
+    currentState = null;
+  } else {
+    const scraped = extractStatusSnapshot(body);
+    if (scraped) {
+      currentState = scraped;
+      currentStateOrigin = 'body';
+    } else {
+      currentState = 'No current_state set';
+    }
+  }
   const nextStep = asString(parsedFrontmatter.next_step) ?? extractNextStep(body) ?? null;
   const blockers = normalizeBlockers(parsedFrontmatter.blockers);
   const surface = asString(parsedFrontmatter.surface) ?? null;
@@ -168,6 +198,7 @@ export function parseDocFile(filePath, config) {
     title,
     summary,
     currentState,
+    currentStateOrigin,
     nextStep,
     blockers,
     updated: asString(parsedFrontmatter.updated) ?? null,

package/src/init.mjs

@@ -1,4 +1,6 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import os from 'node:os';
 import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { green, dim, yellow } from './color.mjs';
@@ -11,6 +13,40 @@ import { resolveConfig } from './config.mjs';
 // have a matching builtin template so `dotmd new <type>` lands files correctly.
 const TYPE_SUBDIRS = ['plans', 'prompts'];
 
+// Look for a `dotmd hud` SessionStart hook already wired in either the project
+// (.claude/settings{,.local}.json) or the user-global config (~/.claude/
+// settings.json). User-global counts because Claude Code merges global hooks
+// into every project — if the user has it wired globally, this project gets it
+// for free and the init snippet would be noise. We only inspect — we do NOT
+// mutate any file. Settings-merge logic is hostile to do silently (clobbering
+// an existing SessionStart entry would surprise the user), so init just prints
+// a paste-ready snippet when the hook isn't found.
+function detectSessionStartHook(cwd) {
+  const candidates = [
+    path.join(cwd, '.claude', 'settings.json'),
+    path.join(cwd, '.claude', 'settings.local.json'),
+    path.join(os.homedir(), '.claude', 'settings.json'),
+  ];
+  for (const file of candidates) {
+    if (!existsSync(file)) continue;
+    let parsed;
+    try { parsed = JSON.parse(readFileSync(file, 'utf8')); }
+    catch { continue; }
+    const sessionStart = parsed?.hooks?.SessionStart;
+    if (!Array.isArray(sessionStart)) continue;
+    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)) {
+          const rel = file.startsWith(cwd) ? path.relative(cwd, file) : file;
+          return { wired: true, file: rel };
+        }
+      }
+    }
+  }
+  return { wired: false };
+}
+
 const STARTER_CONFIG = `// dotmd.config.mjs — document management configuration
 // All exports are optional. See dotmd.config.example.mjs for full reference.
 
@@ -47,6 +83,10 @@ function scanExistingDocs(dir) {
   const modules = new Set();
   const refFieldNames = new Set();
   let docCount = 0;
+  // Files without a frontmatter block, OR with a block that's missing `type:`
+  // or `status:`. Surfaced by the init "bulk-tag hint" to point users at the
+  // command that can fix them all in one shot.
+  let untaggedCount = 0;
   // Track files per top-level subdir under `dir` (e.g. plans/, prompts/, "")
   // so callers can report what's already there — including files without frontmatter,
   // which are otherwise invisible to detection.
@@ -72,10 +112,13 @@ function scanExistingDocs(dir) {
       try { raw = readFileSync(path.join(d, entry.name), 'utf8'); } catch (err) { warn(`Could not read ${entry.name}: ${err.message}`); continue; }
       const { frontmatter } = extractFrontmatter(raw);
       const subdir = topSubdir ?? '';
-      if (!frontmatter) { bump(subdir, false); continue; }
+      if (!frontmatter) { bump(subdir, false); untaggedCount++; continue; }
       bump(subdir, true);
       const parsed = parseSimpleFrontmatter(frontmatter);
       docCount++;
+      const hasType = typeof parsed.type === 'string' && parsed.type.length > 0;
+      const hasStatus = typeof parsed.status === 'string' && parsed.status.length > 0;
+      if (!hasType || !hasStatus) untaggedCount++;
       if (parsed.status) statuses.add(String(parsed.status).toLowerCase());
       if (parsed.surface) surfaces.add(String(parsed.surface));
       if (Array.isArray(parsed.surfaces)) parsed.surfaces.forEach(s => surfaces.add(String(s)));
@@ -90,7 +133,7 @@ function scanExistingDocs(dir) {
   }
 
   walk(dir, null);
-  return { docCount, statuses, surfaces, modules, refFieldNames, subdirCounts };
+  return { docCount, statuses, surfaces, modules, refFieldNames, subdirCounts, untaggedCount };
 }
 
 // Count .md files (regardless of frontmatter) directly inside a single directory.
@@ -260,6 +303,33 @@ export async function runInit(cwd, config, opts = {}) {
     process.stdout.write(`  ${dryTag}${green('create')}  .gitignore\n`);
   }
 
+  // Warn when docs/ is gitignored — silently scaffolding into an ignored dir
+  // means every doc we manage falls outside git, which a doc-management tool
+  // should not leave the user guessing about. Three of gmax's six docs were
+  // force-added; the other three were untracked and the user had no way to
+  // know without `git ls-files docs/`.
+  if (existsSync(path.join(cwd, '.git'))) {
+    const probe = spawnSync('git', ['check-ignore', '-q', 'docs/'], {
+      cwd, encoding: 'utf8',
+    });
+    // Exit 0 → ignored. Exit 1 → not ignored. Exit 128 → not in repo / git error.
+    if (probe.status === 0) {
+      process.stdout.write(`\n  ${yellow('notice')}  docs/ is gitignored — files dotmd manages will NOT be tracked.\n`);
+      process.stdout.write(`           Add an exception to .gitignore so docs/ is tracked:\n`);
+      process.stdout.write(`             !docs/\n`);
+      process.stdout.write(`           Or run: echo '!docs/' >> .gitignore\n`);
+    }
+  }
+
+  // Bulk-tag hint — when init found pre-existing .md files without
+  // type/status, point at the command that can tag them in one shot. Init's
+  // job here is discovery; the per-file detail lives in `bulk-tag --dry-run`.
+  if (scan?.untaggedCount > 0) {
+    const n = scan.untaggedCount;
+    const noun = n === 1 ? 'file' : 'files';
+    process.stdout.write(`\n  ${yellow('hint')}    ${n} untagged .md ${noun} found — run \`dotmd bulk-tag --dry-run\` to preview tagging.\n`);
+  }
+
   // Claude Code integration — auto-detect .claude/ directory.
   // Re-resolve config so the scaffold sees whatever we (may have) just written.
   // Pre-fix: the dispatcher passed `null` to runInit on a fresh repo because
@@ -289,9 +359,30 @@ export async function runInit(cwd, config, opts = {}) {
     }
   }
 
+  // SessionStart hook hint — only when .claude/ exists. Print-only; users with
+  // existing settings.json need to merge by hand because auto-merging hook
+  // arrays would silently mutate user-managed files.
+  if (existsSync(path.join(cwd, '.claude'))) {
+    const sessionStart = detectSessionStartHook(cwd);
+    if (sessionStart.wired) {
+      process.stdout.write(`  ${dim('exists')}  ${sessionStart.file} (SessionStart hook for \`dotmd hud\` already wired)\n`);
+    } else {
+      process.stdout.write(`\n  ${yellow('hint')}    wire \`dotmd hud\` to run at SessionStart — add to .claude/settings.json:\n\n`);
+      process.stdout.write(`            {\n`);
+      process.stdout.write(`              "hooks": {\n`);
+      process.stdout.write(`                "SessionStart": [\n`);
+      process.stdout.write(`                  { "hooks": [{ "type": "command", "command": "dotmd hud" }] }\n`);
+      process.stdout.write(`                ]\n`);
+      process.stdout.write(`              }\n`);
+      process.stdout.write(`            }\n\n`);
+      process.stdout.write(`            If .claude/settings.json already exists, merge into the existing\n`);
+      process.stdout.write(`            \`hooks.SessionStart\` array rather than replacing the file.\n`);
+    }
+  }
+
   process.stdout.write(`\nReady. A few starting points:\n`);
   process.stdout.write(`  dotmd new doc my-doc            # scaffold a reference doc\n`);
   process.stdout.write(`  dotmd new plan my-plan          # scaffold an execution plan\n`);
   process.stdout.write(`  dotmd list                      # see what you've got\n`);
-  process.stdout.write(`  dotmd hud                       # session-start triage (ideal SessionStart hook)\n\n`);
+  process.stdout.write(`  dotmd hud                       # session-start triage\n\n`);
 }

package/src/lifecycle.mjs

@@ -832,3 +832,18 @@ export function updateFrontmatter(filePath, updates) {
 
   writeFileSync(filePath, `---\n${frontmatter}\n---\n${body}`, 'utf8');
 }
+
+// Prepend a fresh `---\n…\n---\n` block to a file that has no frontmatter yet.
+// Sibling to updateFrontmatter() for the bulk-tag flow, which needs to tag
+// pre-existing markdown files that never had a frontmatter block. Delegates
+// to updateFrontmatter when a block already exists so callers can hand it any
+// file without pre-checking — the result is the same shape either way.
+export function writeFrontmatter(filePath, fields) {
+  const raw = readFileSync(filePath, 'utf8');
+  if (raw.startsWith('---\n')) {
+    updateFrontmatter(filePath, fields);
+    return;
+  }
+  const lines = Object.entries(fields).map(([k, v]) => `${k}: ${v}`).join('\n');
+  writeFileSync(filePath, `---\n${lines}\n---\n${raw}`, 'utf8');
+}

package/src/new.mjs

@@ -13,6 +13,10 @@ const BUILTIN_TEMPLATES = {
   doc: {
     description: 'Reference doc, design note, module overview — build-up shape lite',
     defaultStatus: 'active',
+    // Body input optional. When passed (inline / --message / @file / stdin),
+    // it lands in the Overview section. Without it, Overview is left blank
+    // and the user fills it in.
+    acceptsBody: true,
     frontmatter: (s, d) => [
       'type: doc',
       `status: ${s}`,
@@ -32,7 +36,7 @@ const BUILTIN_TEMPLATES = {
 
 ## Overview
 
-
+${ctx?.bodyInput?.trim() ?? ''}
 
 ## Version History
 

package/src/query.mjs

@@ -1,7 +1,7 @@
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import { capitalize, toSlug, truncate, warn } from './util.mjs';
-import { renderProgressBar } from './render.mjs';
+import { renderProgressBar, formatCurrentState } from './render.mjs';
 import { computeDaysSinceUpdate, computeIsStale } from './validate.mjs';
 import { getGitLastModifiedBatch } from './git.mjs';
 import { extractFrontmatter } from './frontmatter.mjs';
@@ -59,7 +59,8 @@ export function runFocus(index, argv, config) {
   for (const doc of docs) {
     process.stdout.write(`- ${doc.title}\n`);
     process.stdout.write(`  path: ${doc.path}\n`);
-    process.stdout.write(`  state: ${doc.currentState}\n`);
+    const stateValue = formatCurrentState(doc);
+    if (stateValue) process.stdout.write(`  state: ${stateValue}\n`);
     if (doc.nextStep) {
       process.stdout.write(`  next: ${doc.nextStep}\n`);
     }
@@ -259,7 +260,8 @@ function renderQueryResults(docs, filters, config) {
     if (doc.daysSinceUpdate != null) process.stdout.write(`  days-since-update: ${doc.daysSinceUpdate}\n`);
     process.stdout.write(`  stale: ${doc.isStale ? 'yes' : 'no'}\n`);
     process.stdout.write(`  path: ${doc.path}\n`);
-    process.stdout.write(`  state: ${doc.currentState}\n`);
+    const stateValue = formatCurrentState(doc);
+    if (stateValue) process.stdout.write(`  state: ${stateValue}\n`);
     if (doc.nextStep) process.stdout.write(`  next: ${doc.nextStep}\n`);
     if (doc.owner) process.stdout.write(`  owner: ${doc.owner}\n`);
     if (doc.surfaces?.length) process.stdout.write(`  surfaces: ${doc.surfaces.join(', ')}\n`);

package/src/render.mjs

@@ -6,6 +6,17 @@ import { summarizeDocBody } from './ai.mjs';
 import { bold, red, yellow, green, dim } from './color.mjs';
 import { findStaleLeases } from './lease.mjs';
 
+// Render `currentState` with an `(auto)` prefix when the value was body-scraped
+// rather than read from frontmatter. Lets a reader see at a glance which docs
+// have an explicit `current_state:` line versus a string inferred from the body
+// — and that overriding it is as simple as adding the field to frontmatter.
+export function formatCurrentState(doc) {
+  if (!doc.currentState) return null;
+  return doc.currentStateOrigin === 'body'
+    ? `(auto) ${doc.currentState}`
+    : doc.currentState;
+}
+
 export function renderCompactList(index, config) {
   const defaultRenderer = (idx) => _renderCompactList(idx, config);
   if (config.hooks.renderCompactList) {
@@ -70,6 +81,21 @@ function _renderCompactList(index, config) {
     lines.push('');
   }
 
+  // Surface docs without a status (untagged — either no frontmatter at all,
+  // or frontmatter present but no `status:` key). Pre-fix these were silently
+  // dropped because every section filtered by status, so `dotmd list` on a
+  // freshly-init'd brownfield repo with N existing .md files showed just
+  // "Index" and looked like the tool didn't see them. Now they get their own
+  // section with the path so the user can find them and add frontmatter.
+  const untagged = index.docs.filter(d => !d.status);
+  if (untagged.length > 0) {
+    lines.push(bold(`Untagged (${untagged.length})  ${dim('— missing `status:` in frontmatter')}`));
+    for (const doc of untagged) {
+      lines.push(`  ${doc.path}`);
+    }
+    lines.push('');
+  }
+
   return `${lines.join('\n').trimEnd()}\n`;
 }
 
@@ -84,7 +110,11 @@ export function renderVerboseList(index, config) {
 
     lines.push(`${capitalize(status)} (${docs.length})`);
     for (const doc of docs) {
-      const parts = [`- ${doc.title}`, `${capitalize(status)}: ${doc.currentState}`, `(${doc.path})`];
+      const stateValue = formatCurrentState(doc);
+      const stateLabel = stateValue
+        ? `${capitalize(status)}: ${stateValue}`
+        : capitalize(status);
+      const parts = [`- ${doc.title}`, stateLabel, `(${doc.path})`];
       if (doc.nextStep) {
         parts.push(`next: ${doc.nextStep}`);
       }
@@ -102,7 +132,11 @@ export function renderVerboseList(index, config) {
 
     lines.push(`${capitalize(status)} (${docs.length})`);
     for (const doc of docs) {
-      const parts = [`- ${doc.title}`, `${capitalize(status)}: ${doc.currentState}`, `(${doc.path})`];
+      const stateValue = formatCurrentState(doc);
+      const stateLabel = stateValue
+        ? `${capitalize(status)}: ${stateValue}`
+        : capitalize(status);
+      const parts = [`- ${doc.title}`, stateLabel, `(${doc.path})`];
       if (doc.nextStep) {
         parts.push(`next: ${doc.nextStep}`);
       }
@@ -111,6 +145,17 @@ export function renderVerboseList(index, config) {
     lines.push('');
   }
 
+  // Surface untagged docs (no `status:` in frontmatter, or no frontmatter at
+  // all) — see _renderCompactList for the why.
+  const untagged = index.docs.filter(d => !d.status);
+  if (untagged.length > 0) {
+    lines.push(`Untagged (${untagged.length}) — missing \`status:\` in frontmatter`);
+    for (const doc of untagged) {
+      lines.push(`- ${doc.title} — (${doc.path})`);
+    }
+    lines.push('');
+  }
+
   return `${lines.join('\n').trimEnd()}\n`;
 }
 
@@ -408,7 +453,7 @@ export function renderProgressBar(checklist) {
 }
 
 export function formatSnapshot(doc, config) {
-  const defaultFormatter = (d) => _formatSnapshot(d);
+  const defaultFormatter = (d) => _formatSnapshot(d, config);
   if (config.hooks.formatSnapshot) {
     try { return config.hooks.formatSnapshot(doc, defaultFormatter); }
     catch (err) { warn(`Hook 'formatSnapshot' threw: ${err.message}`); }
@@ -416,8 +461,21 @@ export function formatSnapshot(doc, config) {
   return defaultFormatter(doc);
 }
 
-function _formatSnapshot(doc) {
-  const state = doc.currentState ?? 'No current_state set';
+function _formatSnapshot(doc, config) {
+  // For terminal statuses (archived, reference, deprecated, etc.) a missing
+  // `current_state` is fine — these are settled docs, no one's expected to be
+  // tracking what they're "currently doing." Pre-fix, the bare-status fallback
+  // rendered as `Reference: No current_state set` everywhere, which looked
+  // like a noisy hint to add a field that the templates never scaffolded.
+  // Now: bare-status line when terminal AND no current_state.
+  // Paired with src/index.mjs's body-scrape suppression for terminal docs —
+  // both layers drop body-derived state when frontmatter is silent.
+  const terminal = config?.lifecycle?.terminalStatuses;
+  const isTerminal = doc.status && terminal && terminal.has(doc.status);
+  if (isTerminal && !doc.currentState) {
+    return capitalize(doc.status);
+  }
+  const state = formatCurrentState(doc) ?? 'No current_state set';
   if (/^active:|^ready:|^planned:|^scoping:|^blocked:|^archived:/i.test(state)) {
     return state;
   }