dotmd-cli 0.22.1 → 0.24.0

package/bin/dotmd.mjs

@@ -20,7 +20,8 @@ View & Query:
   context [--summarize] [--json]    Full briefing (LLM-oriented)
   focus [status] [--json]           Detailed view for one status group
   query [filters] [--json]          Filtered search (--status, --keyword, --stale, etc.)
-  plans                             All plans (preset)
+  plans                             Live plans (excludes archived; --include-archived for all)
+  prompts                           Pending prompts in docs/prompts/
   stale                             Stale docs (preset)
   actionable                        Docs with next steps (preset)
 
@@ -55,7 +56,7 @@ Lifecycle:
   migrate <field> <old> <new> [f...]Batch update a frontmatter field value (optional file filter)
 
 Create & Export:
-  new <name> [--template <t>]       Create doc from template (plan, adr, rfc, audit, design)
+  new <type> <name> [body]          Create doc of given type (plan, doc, prompt, research)
   index [--write]                   Generate/update docs.md index block
   export [--format md|html|json]    Export docs as markdown, HTML, or JSON
   notion import|export|sync [db-id] Notion database integration
@@ -352,6 +353,11 @@ Modes:
                          Skips non-plans. Per-file diff. Doesn't touch
                          long next_step/current_state or unmarked phase
                          headings (those need human input).
+  --migrate-prompts      Retrofit pre-existing markdown files under any docs
+                         root's prompts/ subdirectory with proper prompt
+                         frontmatter (type, status, created from git
+                         history, dotmd_version, context, related_plans).
+                         Skips files that already have frontmatter.
   --migrate-template <file>  Migrate just one plan.
   --migrate-template --include-archived
                          Also touch plans in the archive directory.
@@ -386,22 +392,42 @@ With --write, updates the configured index file in place.
 
 Use --dry-run (-n) with --write to preview without writing.`,
 
-  new: `dotmd new <name> — create a new document
+  new: `dotmd new <type> <name> [body] — create a new document
 
-Creates a new markdown document with frontmatter in the docs root.
+Types and their default destinations:
+  plan        docs/plans/<slug>.md     (build-up template: Problem → Phases → Closeout)
+  doc         docs/<slug>.md           (minimal reference doc)
+  prompt      docs/prompts/<slug>.md   (saved prompt to seed a future session — body required)
+  research    docs/<slug>.md           (audit / investigation)
 
-Options:
-  --template <name>    Use a template (default, plan, adr, rfc, audit, design)
-  --status <s>         Set initial status (default: active)
-  --title <t>          Override the document title
+\`<type>\` can be omitted; defaults to \`doc\`.
+\`<name>\` is slugified for the filename.
+
+Body input (prompt type only):
+  <text>                 Inline body as 3rd positional
+  --message "<text>"     Explicit inline body
+  -                      Read body from stdin (heredoc-friendly for agents)
+  @path                  Read body from a file
+
+Examples:
+  dotmd new plan auth-revamp
+  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
+
+Other options:
+  --status <s>         Set initial status (defaults to first valid status for the type)
+  --title <t>          Override the auto-derived title
   --root <name>        Create in a specific docs root
-  --list-templates     Show available templates
+  --list-types         Show registered types (alias: --list-templates)
 
 For plans, the default status vocabulary is: in-session, active, planned,
-blocked, partial, paused, awaiting, queued-after, archived. Run
-\`dotmd status --help\` for what each one means.
+blocked, partial, paused, awaiting, queued-after, archived.
+For prompts: pending (default), claimed, archived.
 
-The filename is derived from <name> by slugifying it.
 Use --dry-run (-n) to preview without creating the file.`,
 
   watch: `dotmd watch [command] — re-run a command on file changes
@@ -510,24 +536,40 @@ directory. Skips any files that already exist.
 If docs/ already contains .md files, auto-detects statuses, surfaces,
 modules, and reference fields to pre-populate the config.`,
 
-  plans: `dotmd plans — list all plans
+  plans: `dotmd plans — list live plans (excludes archived by default)
 
-Shows all documents with type: plan, sorted by status.
-Supports all query flags (--status, --module, --json, --sort, --group, etc.)
+Shows documents with type: plan, excluding terminal/archive statuses,
+sorted by status. Supports all query flags (--status, --module, --json,
+--sort, --group, etc.).
 
 Default plan statuses: in-session, active, planned, blocked, partial,
 paused, awaiting, queued-after, archived. Run \`dotmd status --help\` for
 the unstuck-action behind each one.
 
 Examples:
-  dotmd plans                          # all plans
+  dotmd plans                          # live plans (default)
+  dotmd plans --include-archived       # all plans including archived
   dotmd plans --status active          # active plans only
   dotmd plans --status awaiting        # plans waiting on a human decision
   dotmd plans --status partial,paused  # shipped-tail and parked plans
   dotmd plans --module auth            # plans for the auth module
-  dotmd plans --group module           # all plans grouped by module
+  dotmd plans --group module           # plans grouped by module
   dotmd plans --json                   # JSON output`,
 
+  prompts: `dotmd prompts — list saved prompts (excludes archived by default)
+
+Shows documents with type: prompt, typically saved under docs/prompts/.
+Prompts are created with \`dotmd new prompt <name> "<body>"\` and seed
+future Claude sessions via \`claude "$(cat docs/prompts/<name>.md)"\`.
+
+Default prompt statuses: pending, claimed, archived.
+
+Examples:
+  dotmd prompts                        # pending prompts (default)
+  dotmd prompts --include-archived     # all prompts including archived
+  dotmd prompts --status claimed       # already-consumed prompts
+  dotmd prompts --json                 # JSON output`,
+
   stale: `dotmd stale — list stale documents
 
 Shows docs that haven't been updated within their staleness threshold.
@@ -698,7 +740,7 @@ async function main() {
     process.stderr.write(`Repo root: ${config.repoRoot}\n`);
   }
 
-  // Preset aliases
+  // Preset aliases (user config can override built-in commands below)
   if (config.presets[command]) {
     const { buildIndex } = await import('../src/index.mjs');
     const { runQuery } = await import('../src/query.mjs');
@@ -707,6 +749,43 @@ async function main() {
     return;
   }
 
+  // Built-in list commands — stable across projects regardless of preset config.
+  // Two views per type:
+  //   `dotmd plans`         triage — top 10 by recency, flat with right-aligned [TAG]
+  //   `dotmd plans status`  pipeline — grouped by status, no per-row tag, all plans
+  if (command === 'plans') {
+    const { buildIndex } = await import('../src/index.mjs');
+    const { runQuery } = await import('../src/query.mjs');
+    const index = buildIndex(config);
+    const sub = restArgs[0];
+    let defaults;
+    let extras = restArgs;
+    if (sub === 'status') {
+      defaults = ['--type', 'plan', '--exclude-archived', '--sort', 'status', '--all'];
+      extras = restArgs.slice(1);
+    } else {
+      defaults = ['--type', 'plan', '--exclude-archived', '--sort', 'updated', '--limit', '10'];
+    }
+    runQuery(index, [...defaults, ...extras], config, { preset: 'plans' });
+    return;
+  }
+  if (command === 'prompts') {
+    const { buildIndex } = await import('../src/index.mjs');
+    const { runQuery } = await import('../src/query.mjs');
+    const index = buildIndex(config);
+    const sub = restArgs[0];
+    let defaults;
+    let extras = restArgs;
+    if (sub === 'status') {
+      defaults = ['--type', 'prompt', '--exclude-archived', '--sort', 'status', '--all'];
+      extras = restArgs.slice(1);
+    } else {
+      defaults = ['--type', 'prompt', '--exclude-archived', '--sort', 'updated', '--limit', '10'];
+    }
+    runQuery(index, [...defaults, ...extras], config, { preset: 'prompts' });
+    return;
+  }
+
   // Commands that handle their own index building
   if (command === 'diff') { const { runDiff } = await import('../src/diff.mjs'); runDiff(restArgs, config); return; }
   if (command === 'summary') { const { runSummary } = await import('../src/summary.mjs'); runSummary(restArgs, config); return; }
@@ -981,7 +1060,7 @@ async function main() {
   // Unknown command — suggest closest match
   const allCommands = [
     'list', 'json', 'check', 'coverage', 'stats', 'graph', 'deps', 'briefing', 'context', 'hud',
-    'focus', 'query', 'plans', 'stale', 'actionable', 'index', 'pickup', 'release', 'handoff', 'finish', 'status', 'archive', 'bulk', 'touch', 'doctor',
+    'focus', 'query', 'plans', 'prompts', 'stale', 'actionable', 'index', 'pickup', 'release', 'handoff', 'finish', 'status', 'archive', 'bulk', 'touch', 'doctor',
     'unblocks', 'health', 'glossary',
     'fix-refs', 'lint', 'rename', 'migrate', 'notion', 'export', 'summary',
     'watch', 'diff', 'new', 'init', 'completions', 'statuses',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.22.1",
+  "version": "0.24.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/claude-commands.mjs

@@ -22,7 +22,8 @@ function generatePlansCommand(config) {
   lines.push('- `dotmd health` — plan velocity, aging, checklist progress, pipeline view');
   lines.push('- `dotmd unblocks <file>` — what depends on / is blocked by a plan');
   lines.push('- `dotmd next` — ready plans with next steps (what to promote)');
-  lines.push('- `dotmd new <name> --template plan` — scaffold with full phase structure');
+  lines.push('- `dotmd new plan <name>` — scaffold with full phase structure');
+  lines.push('- `dotmd new prompt <name> "<body>"` — save a resume-prompt to docs/prompts/');
   lines.push('- `dotmd archive <file>` — archive with auto ref-fixing (both directions)');
   lines.push('- `dotmd bulk archive <files>` — archive multiple at once');
   lines.push('- `dotmd status <file> <status>` — transition status');
@@ -115,7 +116,10 @@ function generateDocsCommand(config) {
 
   lines.push('');
   lines.push('Lifecycle:');
-  lines.push('- `dotmd new <name> --template plan` — scaffold new plan');
+  lines.push('- `dotmd new plan <name>` — scaffold new plan');
+  lines.push('- `dotmd new doc <name>` — scaffold reference doc');
+  lines.push('- `dotmd new prompt <name> "<body>"` — save a resume-prompt');
+  lines.push('- `dotmd new research <name>` — scaffold an audit/investigation');
   lines.push('- `dotmd status <file> <status>` — transition status');
   lines.push('- `dotmd archive <file>` — archive with auto ref-fixing');
   lines.push('- `dotmd bulk archive <files>` — archive multiple at once');

package/src/color.mjs

@@ -6,5 +6,9 @@ const wrap = (code) => enabled ? (s) => `\x1b[${code}m${s}\x1b[0m` : (s) => s;
 export const bold = wrap('1');
 export const dim = wrap('2');
 export const red = wrap('31');
-export const yellow = wrap('33');
 export const green = wrap('32');
+export const yellow = wrap('33');
+export const blue = wrap('34');
+export const magenta = wrap('35');
+export const cyan = wrap('36');
+export const brightYellow = wrap('93');

package/src/config.mjs

@@ -40,6 +40,11 @@ const DEFAULTS = {
       context: { expanded: ['active'], listed: [], counted: ['reference', 'archived'] },
       staleDays: { active: 30 },
     },
+    prompt: {
+      statuses: ['pending', 'claimed', 'archived'],
+      context: { expanded: ['pending'], listed: [], counted: ['claimed', 'archived'] },
+      staleDays: { pending: 30 },
+    },
   },
 
   statuses: {
@@ -95,7 +100,6 @@ const DEFAULTS = {
   notion: null,
 
   presets: {
-    plans: ['--type', 'plan', '--sort', 'status', '--all'],
     stale: ['--status', 'active,ready,planned,blocked,scoping', '--stale', '--sort', 'updated', '--all'],
     actionable: ['--status', 'active,ready', '--has-next-step', '--sort', 'updated', '--all'],
   },

package/src/doctor.mjs

@@ -7,6 +7,7 @@ import { renderCheck } from './render.mjs';
 import { bold, dim, green, yellow } from './color.mjs';
 import { scaffoldClaudeCommands } from './claude-commands.mjs';
 import { runMigrateTemplate } from './migrate-template.mjs';
+import { runMigratePrompts } from './migrate-prompts.mjs';
 
 // Tunable thresholds for `dotmd doctor --statuses` conflation detection.
 // MIN_BUCKET_SIZE: only flag buckets with at least this many docs (small buckets aren't worth nagging).
@@ -46,6 +47,10 @@ export function runDoctor(argv, config, opts = {}) {
     runMigrateTemplate(argv, config, opts);
     return;
   }
+  if (argv.includes('--migrate-prompts')) {
+    runMigratePrompts(argv, config, opts);
+    return;
+  }
 
   const { dryRun } = opts;
   process.stdout.write(bold('dotmd doctor') + '\n\n');

package/src/git.mjs

@@ -19,6 +19,16 @@ export function getGitLastModified(relPath, repoRoot) {
   return result.stdout.trim();
 }
 
+export function getGitFirstAdded(relPath, repoRoot) {
+  const result = spawnSync('git', ['log', '--diff-filter=A', '--follow', '--format=%aI', '--', relPath], {
+    cwd: repoRoot, encoding: 'utf8',
+  });
+  if (result.error || result.status !== 0 || !result.stdout.trim()) return null;
+  // `git log` returns newest-first; the file's add commit is the LAST entry.
+  const lines = result.stdout.trim().split('\n').filter(Boolean);
+  return lines[lines.length - 1] ?? null;
+}
+
 export function getGitLastModifiedBatch(repoRoot) {
   const result = spawnSync('git', [
     'log', '--format=commit %aI', '--name-only', '--diff-filter=ACDMR', 'HEAD',

package/src/migrate-prompts.mjs

@@ -0,0 +1,169 @@
+import { readFileSync, writeFileSync, readdirSync, statSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
+import { toRepoPath, nowIso } from './util.mjs';
+import { getGitFirstAdded } from './git.mjs';
+import { bold, green, dim } from './color.mjs';
+import { readFileSync as rfs } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(rfs(path.join(__dirname, '..', 'package.json'), 'utf8'));
+
+function findPromptCandidates(config) {
+  const roots = config.docsRoots || [config.docsRoot];
+  // Build the set of directories to search: each root, plus each root's parent
+  // (catches `docs/prompts/` when roots are like `docs/plans/`, `docs/modules/`),
+  // plus the repo root itself.
+  const candidates = new Set();
+  for (const root of roots) {
+    candidates.add(path.join(root, 'prompts'));
+    candidates.add(path.join(path.dirname(root), 'prompts'));
+  }
+  candidates.add(path.join(config.repoRoot, 'prompts'));
+
+  const out = [];
+  const seen = new Set();
+  for (const dir of candidates) {
+    if (!existsSync(dir) || seen.has(dir)) continue;
+    seen.add(dir);
+    walkDir(dir, out);
+  }
+  return out;
+}
+
+function walkDir(dir, out) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name.startsWith('.')) continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) { walkDir(full, out); continue; }
+    if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+    out.push(full);
+  }
+}
+
+function deriveContext(body, filePath) {
+  // Use first heading or filename as the context label.
+  const firstH1 = body.match(/^#\s+(.+?)\s*$/m);
+  if (firstH1) return firstH1[1].slice(0, 100);
+  // Fall back to slug, title-cased.
+  const slug = path.basename(filePath, '.md');
+  return slug.replace(/[-_]/g, ' ').replace(/\b\w/g, c => c.toUpperCase()).slice(0, 100);
+}
+
+export function migrateOnePrompt(raw, opts = {}) {
+  const { frontmatter, body: rawBody } = extractFrontmatter(raw);
+  const created = opts.created || nowIso();
+
+  // Case 1: no frontmatter at all → wrap with full fresh frontmatter.
+  if (!frontmatter || frontmatter.length === 0) {
+    const body = raw.trimStart();
+    const context = deriveContext(body, opts.filePath || 'unknown');
+    const fm = [
+      'type: prompt',
+      'status: pending',
+      `created: ${created}`,
+      `dotmd_version: ${pkg.version}`,
+      `context: "${context.replace(/"/g, '\\"')}"`,
+      'related_plans: []',
+    ].join('\n');
+    return {
+      changes: [{ kind: 'add-frontmatter', detail: `type=prompt, created=${created}, context="${context}"` }],
+      newRaw: `---\n${fm}\n---\n\n${body.trim()}\n`,
+    };
+  }
+
+  // Case 2: frontmatter exists. If it already has `type: prompt`, leave alone.
+  const parsed = parseSimpleFrontmatter(frontmatter);
+  if (parsed.type === 'prompt') {
+    return { changes: [], newRaw: raw, skipped: 'already-prompt' };
+  }
+
+  // Case 3: partial/ad-hoc frontmatter (e.g., `title:` + `purpose:` only).
+  // Add missing required fields while preserving existing keys.
+  const needed = [];
+  if (!parsed.type) needed.push(['type', 'prompt']);
+  if (!parsed.status) needed.push(['status', 'pending']);
+  if (!parsed.created) needed.push(['created', created]);
+  if (!parsed.dotmd_version) needed.push(['dotmd_version', pkg.version]);
+  if (!parsed.context) {
+    // Prefer existing `title:` if present, else derive from body/filename.
+    const ctx = typeof parsed.title === 'string' ? parsed.title : deriveContext(rawBody || raw, opts.filePath || 'unknown');
+    needed.push(['context', `"${ctx.replace(/"/g, '\\"')}"`]);
+  }
+  if (!parsed.related_plans) needed.push(['related_plans', '[]']);
+
+  if (needed.length === 0) {
+    return { changes: [], newRaw: raw, skipped: 'frontmatter-complete' };
+  }
+
+  // Prepend the missing fields (so `type` ends up at the top for grep-friendliness).
+  const addedLines = needed.map(([k, v]) => `${k}: ${v}`).join('\n');
+  const newFrontmatter = `${addedLines}\n${frontmatter}`;
+  const newRaw = `---\n${newFrontmatter}\n---\n${rawBody}`;
+  return {
+    changes: [{ kind: 'merge-frontmatter', detail: `added: ${needed.map(([k]) => k).join(', ')}` }],
+    newRaw,
+  };
+}
+
+export function runMigratePrompts(argv, config, opts = {}) {
+  const { dryRun } = opts;
+  const json = argv.includes('--json');
+  const fileArg = argv.find(a => !a.startsWith('-') && a !== 'doctor');
+
+  let files;
+  if (fileArg) {
+    const target = fileArg.endsWith('.md') ? fileArg : `${fileArg}.md`;
+    files = findPromptCandidates(config).filter(f => f.endsWith(target) || f === target);
+    if (files.length === 0) {
+      process.stderr.write(`File not found in any prompts/ subdir: ${fileArg}\n`);
+      process.exitCode = 1;
+      return;
+    }
+  } else {
+    files = findPromptCandidates(config);
+  }
+
+  const results = [];
+  let touched = 0;
+
+  for (const filePath of files) {
+    const raw = readFileSync(filePath, 'utf8');
+    const created = getGitFirstAdded(toRepoPath(filePath, config.repoRoot), config.repoRoot)
+      || new Date(statSync(filePath).birthtimeMs).toISOString().replace(/\.\d{3}Z$/, 'Z');
+    const result = migrateOnePrompt(raw, { created, filePath });
+    if (result.changes.length === 0) continue;
+
+    const repoPath = toRepoPath(filePath, config.repoRoot);
+    results.push({ path: repoPath, changes: result.changes });
+    touched++;
+
+    if (!dryRun) writeFileSync(filePath, result.newRaw, 'utf8');
+  }
+
+  if (json) {
+    process.stdout.write(JSON.stringify({
+      dryRun: Boolean(dryRun),
+      filesScanned: files.length,
+      filesTouched: touched,
+      results,
+    }, null, 2) + '\n');
+    return;
+  }
+
+  if (results.length === 0) {
+    process.stdout.write(green('No prompts need migration.') + dim(` (${files.length} scanned)`) + '\n');
+    return;
+  }
+
+  const prefix = dryRun ? dim('[dry-run] ') : '';
+  process.stdout.write(bold(`${prefix}${touched} prompt${touched === 1 ? '' : 's'} ${dryRun ? 'would be' : 'were'} migrated:\n\n`));
+  for (const r of results) {
+    process.stdout.write(`  ${r.path}\n`);
+    for (const c of r.changes) {
+      process.stdout.write(dim(`    [${c.kind}] ${c.detail}\n`));
+    }
+  }
+  if (dryRun) process.stdout.write(`\nRun ${bold('dotmd doctor --migrate-prompts')} without --dry-run to apply.\n`);
+}

package/src/new.mjs

@@ -1,17 +1,24 @@
-import { existsSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { toRepoPath, die, warn, nowIso } from './util.mjs';
 import { green, dim, bold } from './color.mjs';
 import { isInteractive, promptText } from './prompt.mjs';
 
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
+
 const BUILTIN_TEMPLATES = {
-  default: {
-    description: 'Minimal document with status and updated date',
-    frontmatter: (s, d) => `type: doc\nstatus: ${s}\nupdated: ${d}`,
+  doc: {
+    description: 'Reference doc, design note, glossary entry, etc.',
+    defaultStatus: 'active',
+    frontmatter: (s, d) => `type: doc\nstatus: ${s}\ncreated: ${d}\nupdated: ${d}`,
     body: (t) => `\n# ${t}\n`,
   },
   plan: {
     description: 'Execution plan — build-up shape (Problem → Phases → Closeout) with phase status markers and Version History',
+    dir: 'plans',
+    defaultStatus: 'active',
     frontmatter: (s, d) => [
       'type: plan',
       `status: ${s}`,
@@ -88,67 +95,127 @@ Status markers (put in heading text):
 <!-- Filled on archive: what shipped, key commits, deferrals dispositioned. -->
 `,
   },
-  adr: {
-    description: 'Architecture Decision Record',
-    frontmatter: (s, d) => `type: doc\nstatus: ${s}\nupdated: ${d}\ndecision_date:\ndeciders:`,
-    body: (t) => `\n# ${t}\n\n## Context\n\n\n\n## Decision\n\n\n\n## Consequences\n\n\n`,
-  },
-  rfc: {
-    description: 'Request for Comments',
-    frontmatter: (s, d) => `type: doc\nstatus: ${s}\nupdated: ${d}\nowner:\nreviewers:`,
-    body: (t) => `\n# ${t}\n\n## Summary\n\n\n\n## Motivation\n\n\n\n## Detailed Design\n\n\n\n## Alternatives\n\n\n\n## Open Questions\n\n\n`,
-  },
-  audit: {
+  research: {
     description: 'Codebase audit or research investigation',
-    frontmatter: (s, d) => `type: research\nstatus: ${s}\nupdated: ${d}\naudited: ${d}\naudit_level: pass1\nmodule:\nsource_of_truth: code\nsupports_plans:`,
+    defaultStatus: 'active',
+    frontmatter: (s, d) => [
+      'type: research',
+      `status: ${s}`,
+      `created: ${d}`,
+      `updated: ${d}`,
+      `audited: ${d}`,
+      'audit_level: pass1',
+      'module:',
+      'source_of_truth: code',
+      'supports_plans: []',
+    ].join('\n'),
     body: (t) => `\n# ${t}\n\n## Scope\n\n\n\n## Findings\n\n\n\n## Recommendations\n\n\n`,
   },
-  design: {
-    description: 'Design document with goals, non-goals, and implementation plan',
-    frontmatter: (s, d) => `type: doc\nstatus: ${s}\nupdated: ${d}\nowner:\nsurface:\nmodule:\nrelated_plans:`,
-    body: (t) => `\n# ${t}\n\n## Overview\n\n\n\n## Goals\n\n\n\n## Non-Goals\n\n\n\n## Design\n\n\n\n## Implementation Plan\n\n- [ ] \n`,
+  prompt: {
+    description: 'Saved prompt to seed a future Claude session — body is required',
+    dir: 'prompts',
+    defaultStatus: 'pending',
+    requiresBody: true,
+    frontmatter: (s, d, ctx) => [
+      'type: prompt',
+      `status: ${s}`,
+      `created: ${d}`,
+      `dotmd_version: ${pkg.version}`,
+      `context: ${ctx?.title ? `"${ctx.title.replace(/"/g, '\\"')}"` : ''}`,
+      'related_plans: []',
+    ].join('\n'),
+    body: (t, ctx) => `\n${ctx?.bodyInput ?? '<!-- prompt body -->'}\n`,
   },
 };
 
+function readBodyInput(source) {
+  if (source === '-') {
+    try { return readFileSync(0, 'utf8'); } catch (err) { die(`Could not read body from stdin: ${err.message}`); }
+  }
+  if (typeof source === 'string' && source.startsWith('@')) {
+    const file = source.slice(1);
+    if (!existsSync(file)) die(`Body file not found: ${file}`);
+    return readFileSync(file, 'utf8');
+  }
+  return source;
+}
+
 export async function runNew(argv, config, opts = {}) {
   const { dryRun } = opts;
 
-  // Parse args
+  // Parse args. Pull out flags first.
   const positional = [];
-  let status = 'active';
+  let status = null;
   let title = null;
-  let templateName = null;
   let rootName = opts.root ?? null;
+  let messageFlag = null;
   for (let i = 0; i < argv.length; i++) {
     if (argv[i] === '--status' && argv[i + 1]) { status = argv[++i]; continue; }
     if (argv[i] === '--title' && argv[i + 1]) { title = argv[++i]; continue; }
-    if (argv[i] === '--template' && argv[i + 1]) { templateName = argv[++i]; continue; }
+    if (argv[i] === '--message' && argv[i + 1]) { messageFlag = argv[++i]; continue; }
     if (argv[i] === '--root' && argv[i + 1]) { rootName = argv[++i]; continue; }
     if (argv[i] === '--config') { i++; continue; }
-    if (argv[i] === '--list-templates') {
+    if (argv[i] === '--list-templates' || argv[i] === '--list-types') {
       listTemplates(config);
       return;
     }
-    if (!argv[i].startsWith('-')) positional.push(argv[i]);
+    // Treat `-` alone (stdin marker) as a positional, not a flag.
+    if (!argv[i].startsWith('-') || argv[i] === '-') positional.push(argv[i]);
+  }
+
+  // Resolve type vs name:
+  //   `dotmd new plan auth-revamp`     → type=plan, name=auth-revamp
+  //   `dotmd new auth-revamp`          → type=doc (default), name=auth-revamp
+  //   `dotmd new prompt foo "body"`    → type=prompt, name=foo, bodyArg="body"
+  const knownTypes = new Set(Object.keys(BUILTIN_TEMPLATES));
+  // Also include any custom templates from config
+  for (const k of Object.keys(config.raw?.templates ?? {})) knownTypes.add(k);
+
+  let typeName, name, bodyArg = null;
+  if (positional.length >= 1 && knownTypes.has(positional[0])) {
+    typeName = positional[0];
+    name = positional[1];
+    if (positional.length > 2) bodyArg = positional.slice(2).join(' ');
+  } else {
+    typeName = 'doc';
+    name = positional[0];
+    if (positional.length > 1) bodyArg = positional.slice(1).join(' ');
   }
 
-  let name = positional[0];
   if (!name) {
     if (isInteractive()) {
-      name = await promptText('Document name: ');
+      name = await promptText(`${typeName} name: `);
       if (!name) die('No name provided.');
     } else {
-      die('Usage: dotmd new <name> [--template <t>] [--status <s>] [--title <t>]\n       dotmd new --list-templates');
+      die(`Usage: dotmd new <type> <name> [body]\n       types: ${[...knownTypes].join(', ')}\n       body: inline text | "-" (stdin) | "@path" (file) | --message "..."`);
     }
   }
 
-  // Validate status
-  if (!config.validStatuses.has(status)) {
-    die(`Invalid status: ${status}\nValid: ${[...config.validStatuses].join(', ')}`);
+  // Resolve template (by type name, falls back to lookup)
+  const template = resolveTemplate(typeName, config);
+
+  // Validate status (template default first, then per-type list, then 'active')
+  if (!status) {
+    if (typeof template === 'object' && template.defaultStatus) {
+      status = template.defaultStatus;
+    } else {
+      const typeStatuses = config.typeStatuses?.get(typeName);
+      status = typeStatuses && typeStatuses.size > 0 ? [...typeStatuses][0] : 'active';
+    }
+  }
+  const effective = config.typeStatuses?.get(typeName) ?? config.validStatuses;
+  if (!effective.has(status)) {
+    die(`Invalid status \`${status}\` for type \`${typeName}\`\nValid: ${[...effective].join(', ')}`);
   }
 
-  // Resolve template
-  const template = resolveTemplate(templateName ?? 'default', config);
+  // Body input resolution: messageFlag > bodyArg > nothing
+  let bodyInput = null;
+  if (messageFlag !== null) bodyInput = readBodyInput(messageFlag);
+  else if (bodyArg !== null) bodyInput = readBodyInput(bodyArg);
+
+  if (template.requiresBody && (!bodyInput || !bodyInput.trim())) {
+    die(`\`${typeName}\` template requires a body. Pass inline, --message "...", - for stdin, or @path for a file.`);
+  }
 
   // If name contains path separators, split into directory prefix and basename
   let nameDir = null;
@@ -179,7 +246,12 @@ export async function runNew(argv, config, opts = {}) {
     targetRoot = match;
   }
 
-  // Path — if user provided a directory prefix, resolve relative to repoRoot
+  // Template-declared subdirectory (e.g., prompt → 'prompts')
+  if (typeof template === 'object' && template.dir && !nameDir) {
+    nameDir = path.join(path.relative(config.repoRoot, targetRoot), template.dir);
+  }
+
+  // Path — if user provided a directory prefix OR template declared one, resolve relative to repoRoot
   const baseDir = nameDir ? path.resolve(config.repoRoot, nameDir) : targetRoot;
   const filePath = path.join(baseDir, slug + '.md');
   const repoPath = toRepoPath(filePath, config.repoRoot);
@@ -192,26 +264,28 @@ export async function runNew(argv, config, opts = {}) {
 
   // Generate content
   let content;
+  const tmplCtx = { status, title: docTitle, today, bodyInput };
   if (typeof template === 'function') {
-    content = template(name, { status, title: docTitle, today });
+    content = template(name, tmplCtx);
   } else {
-    const fm = template.frontmatter(status, today);
-    const body = template.body(docTitle, { today, status });
+    const fm = template.frontmatter(status, today, tmplCtx);
+    const body = template.body(docTitle, tmplCtx);
     content = `---\n${fm}\n---\n${body}`;
   }
 
   if (dryRun) {
     process.stdout.write(`${dim('[dry-run]')} Would create: ${repoPath}\n`);
-    if (templateName) process.stdout.write(`${dim('[dry-run]')} Template: ${templateName}\n`);
+    process.stdout.write(`${dim('[dry-run]')} Type: ${typeName}\n`);
     return;
   }
 
+  // Ensure parent dir exists (templates with `dir:` may target a new subdirectory)
+  mkdirSync(path.dirname(filePath), { recursive: true });
+
   writeFileSync(filePath, content, 'utf8');
-  process.stdout.write(`${green('Created')}: ${repoPath}`);
-  if (templateName) process.stdout.write(` ${dim(`(template: ${templateName})`)}`);
-  process.stdout.write('\n');
+  process.stdout.write(`${green('Created')}: ${repoPath} ${dim(`(${typeName})`)}\n`);
 
-  try { config.hooks.onNew?.({ path: repoPath, status, title: docTitle, template: templateName }); } catch (err) { warn(`Hook 'onNew' threw: ${err.message}`); }
+  try { config.hooks.onNew?.({ path: repoPath, status, title: docTitle, type: typeName }); } catch (err) { warn(`Hook 'onNew' threw: ${err.message}`); }
 }
 
 function resolveTemplate(name, config) {
@@ -221,7 +295,7 @@ function resolveTemplate(name, config) {
   if (BUILTIN_TEMPLATES[name]) return BUILTIN_TEMPLATES[name];
 
   const available = [...new Set([...Object.keys(BUILTIN_TEMPLATES), ...Object.keys(configTemplates)])];
-  die(`Unknown template: ${name}\nAvailable: ${available.join(', ')}`);
+  die(`Unknown type: ${name}\nAvailable: ${available.join(', ')}`);
 }
 
 function listTemplates(config) {
@@ -231,7 +305,7 @@ function listTemplates(config) {
     all[k] = v;
   }
 
-  process.stdout.write(bold('Available templates') + '\n\n');
+  process.stdout.write(bold('Available types') + '\n\n');
   for (const [name, tmpl] of Object.entries(all)) {
     const desc = typeof tmpl === 'function'
       ? '(custom function)'

package/src/query.mjs

@@ -6,7 +6,30 @@ import { computeDaysSinceUpdate, computeIsStale } from './validate.mjs';
 import { getGitLastModifiedBatch } from './git.mjs';
 import { extractFrontmatter } from './frontmatter.mjs';
 import { summarizeDocBody } from './ai.mjs';
-import { bold, dim, yellow, red } from './color.mjs';
+import { bold, dim, yellow, red, green, blue, magenta, cyan, brightYellow } from './color.mjs';
+
+const STATUS_COLORS = {
+  'in-session': (s) => bold(red(s)),
+  'active': green,
+  'planned': blue,
+  'blocked': yellow,
+  'partial': (s) => dim(green(s)),
+  'paused': magenta,
+  'awaiting': brightYellow,
+  'queued-after': (s) => dim(cyan(s)),
+  'archived': dim,
+  'pending': bold,
+  'claimed': dim,
+};
+
+function colorTag(status) {
+  const tag = `[${(status ?? 'unknown').toUpperCase()}]`;
+  const fn = STATUS_COLORS[status] ?? dim;
+  return fn(tag);
+}
+
+// Strip ANSI for length math
+function visibleLen(s) { return s.replace(/\x1b\[[0-9;]*m/g, '').length; }
 
 export function runFocus(index, argv, config) {
   // Find first positional arg, skipping flag-value pairs like --root <name>
@@ -64,8 +87,8 @@ export function runQuery(index, argv, config, opts = {}) {
     return;
   }
 
-  if (opts.preset === 'plans') {
-    renderPlansOutput(docs, filters, config);
+  if (opts.preset === 'plans' || opts.preset === 'prompts') {
+    renderPlansOutput(docs, filters, config, { noun: opts.preset });
     return;
   }
 
@@ -101,6 +124,8 @@ export function parseQueryArgs(argv) {
     if (arg === '--sort' && next) { filters.sort = next; i += 1; continue; }
     if (arg === '--group' && next) { filters.group = next; i += 1; continue; }
     if (arg === '--all') { filters.all = true; continue; }
+    if (arg === '--include-archived') { filters.includeArchived = true; continue; }
+    if (arg === '--exclude-archived') { filters.excludeArchived = true; continue; }
     if (arg === '--stale') { filters.stale = true; continue; }
     if (arg === '--has-next-step') { filters.hasNextStep = true; continue; }
     if (arg === '--has-blockers') { filters.hasBlockers = true; continue; }
@@ -120,6 +145,15 @@ export function filterDocs(docs, filters, config) {
 
   if (filters.types?.length) result = result.filter(d => filters.types.includes(d.type));
   if (filters.statuses?.length) result = result.filter(d => filters.statuses.includes(d.status));
+  // --exclude-archived strips terminal/archive statuses unless the caller
+  // explicitly opted back in with --include-archived.
+  if (filters.excludeArchived && !filters.includeArchived) {
+    const archived = new Set([
+      ...(config.lifecycle?.archiveStatuses ?? []),
+      ...(config.lifecycle?.terminalStatuses ?? []),
+    ]);
+    result = result.filter(d => !archived.has(d.status));
+  }
 
   if (filters.keyword) {
     const needle = filters.keyword.toLowerCase();
@@ -151,6 +185,15 @@ export function filterDocs(docs, filters, config) {
   if (filters.checklistOpen) result = result.filter(d => (d.checklist?.open ?? 0) > 0);
 
   result.sort(buildSorter(filters.sort, config));
+  // Stash pre-limit count and per-status breakdown on filters so renderers
+  // can show "N more" footers and accurate pipeline summaries even when the
+  // returned slice is limited.
+  filters._totalBeforeLimit = result.length;
+  filters._statusCounts = {};
+  for (const d of result) {
+    const s = d.status ?? 'unknown';
+    filters._statusCounts[s] = (filters._statusCounts[s] ?? 0) + 1;
+  }
   return filters.all ? result : result.slice(0, filters.limit);
 }
 
@@ -235,19 +278,28 @@ function compareUpdatedDesc(a, b) {
   return au !== bu ? bu.localeCompare(au) : 0;
 }
 
-function renderPlansOutput(docs, filters, config) {
+function renderPlansOutput(docs, filters, config, opts = {}) {
+  const noun = opts.noun ?? 'plans';
   if (docs.length === 0) {
-    process.stdout.write('No plans found.\n');
+    process.stdout.write(`No ${noun} found.\n`);
     return;
   }
 
-  // Summary line
-  const bySt = {};
-  for (const d of docs) { bySt[d.status] = (bySt[d.status] ?? 0) + 1; }
-  const counts = Object.entries(bySt).map(([s, n]) => `${n} ${s}`).join(', ');
-  process.stdout.write(`${bold('Plans')} ${dim(`(${docs.length})`)}  ${counts}\n`);
-
-  // Active filter note (only if user applied extra filters beyond the preset defaults)
+  // Summary line: middle-dot separator, ALWAYS based on the full pre-limit
+  // pipeline so the top-of-page numbers stay honest when --limit is applied.
+  const totalShown = docs.length;
+  const totalAll = filters._totalBeforeLimit ?? totalShown;
+  const bySt = filters._statusCounts ?? (() => {
+    const counts = {};
+    for (const d of docs) { counts[d.status] = (counts[d.status] ?? 0) + 1; }
+    return counts;
+  })();
+  // Sort statuses by count desc for a stable visual.
+  const counts = Object.entries(bySt).sort((a, b) => b[1] - a[1]).map(([s, n]) => `${n} ${s}`).join(' · ');
+  const header = `${totalAll} ${noun}${counts ? ' · ' + counts : ''}`;
+  process.stdout.write(dim(header) + '\n');
+
+  // Active filter note
   const activeFilters = [];
   if (filters.statuses?.length) activeFilters.push(`status: ${filters.statuses.join(', ')}`);
   if (filters.module) activeFilters.push(`module: ${filters.module}`);
@@ -260,29 +312,40 @@ function renderPlansOutput(docs, filters, config) {
   if (activeFilters.length) process.stdout.write(dim(`  filtered: ${activeFilters.join(' | ')}`) + '\n');
 
   const maxWidth = process.stdout.columns || 100;
+  const grouped = filters.sort === 'status' || filters.group;
 
-  // Group by module or status
   if (filters.group === 'module') {
+    process.stdout.write('\n');
     renderPlansByGroup(docs, d => d.modules?.length ? d.modules : ['(none)'], filters, maxWidth);
   } else if (filters.group === 'surface') {
+    process.stdout.write('\n');
     renderPlansByGroup(docs, d => d.surfaces?.length ? d.surfaces : ['(none)'], filters, maxWidth);
   } else if (filters.group === 'owner') {
+    process.stdout.write('\n');
     renderPlansByGroup(docs, d => [d.owner ?? '(none)'], filters, maxWidth);
-  } else {
-    // Default: group by status, ordered by config.statusOrder
+  } else if (grouped) {
+    // Pipeline view: group by status, ordered by config.statusOrder. Tag is implicit.
     const statusGroups = new Map();
     for (const d of docs) {
       const s = d.status ?? 'unknown';
       if (!statusGroups.has(s)) statusGroups.set(s, []);
       statusGroups.get(s).push(d);
     }
-
     const orderedStatuses = [...config.statusOrder.filter(s => statusGroups.has(s)), ...([...statusGroups.keys()].filter(s => !config.statusOrder.includes(s)))];
-
     for (const status of orderedStatuses) {
       const group = statusGroups.get(status);
       process.stdout.write(`\n${bold(`${capitalize(status)} (${group.length})`)}\n`);
-      renderPlanRows(group, filters, maxWidth);
+      renderPlanRows(group, filters, maxWidth, { showTag: false });
+    }
+  } else {
+    // Triage view: flat, sorted by recency, tag on right.
+    process.stdout.write('\n');
+    renderPlanRows(docs, filters, maxWidth, { showTag: true });
+    // Footer when the result was capped.
+    const hidden = totalAll - totalShown;
+    if (hidden > 0) {
+      process.stdout.write('\n');
+      process.stdout.write(dim(`  ${hidden} more ${noun}  ·  dotmd ${noun} --all  ·  dotmd ${noun} status\n`));
     }
   }
 
@@ -306,29 +369,53 @@ function renderPlansByGroup(docs, keyFn, filters, maxWidth) {
   }
 }
 
-function renderPlanRows(group, filters, maxWidth) {
+// Widest tag we render (status name in CAPS + brackets). Used to budget the
+// next-step column when right-aligning tags.
+const MAX_TAG_WIDTH = '[QUEUED-AFTER]'.length;
+
+function renderPlanRows(group, filters, maxWidth, opts = {}) {
+  const { showTag = false } = opts;
   const maxSlug = Math.min(30, Math.max(...group.map(d => toSlug(d).length)));
-  const showModule = !filters.module && filters.group !== 'module';
 
   for (const doc of group) {
     const slug = toSlug(doc).padEnd(maxSlug);
-    const age = doc.daysSinceUpdate != null ? `${doc.daysSinceUpdate}d` : ' —';
+    const age = doc.daysSinceUpdate != null ? `${doc.daysSinceUpdate}d` : '—';
     const ageStr = doc.daysSinceUpdate != null && doc.isStale ? red(age.padStart(4)) : dim(age.padStart(4));
-    const progress = renderProgressBar(doc.checklist);
 
-    const parts = [`  ${slug}  ${ageStr}`];
-    if (progress) parts.push(progress);
-    if (showModule && doc.modules?.length) parts.push(dim(`[${doc.modules.join(',')}]`));
+    // Compact percentage cell (always 5 chars: "100% " / " 99% " / "  5% " / "     ")
+    let pctCell = '     ';
+    if (doc.checklist?.total) {
+      const pct = Math.round((doc.checklist.completed / doc.checklist.total) * 100);
+      pctCell = `${pct.toString().padStart(3)}% `;
+    }
 
-    if (doc.blockers?.length && (doc.status === 'blocked')) {
-      parts.push(yellow(`blockers: ${doc.blockers.join('; ')}`));
+    const leftBlock = `  ${slug}  ${ageStr}  ${dim(pctCell)}`;
+    const leftLen = visibleLen(leftBlock);
+
+    // Next-step / blocker text. Budget = maxWidth - leftLen - separator - (tag column if shown).
+    let nextText = '';
+    if (doc.blockers?.length && doc.status === 'blocked') {
+      nextText = `blocked by ${doc.blockers.join('; ')}`;
     } else if (doc.nextStep) {
-      parts.push(`next: ${doc.nextStep}`);
-    } else {
-      parts.push(dim('(no next step)'));
+      nextText = doc.nextStep;
     }
 
-    const line = parts.join('  ');
-    process.stdout.write((line.length > maxWidth ? line.slice(0, maxWidth - 3) + '...' : line) + '\n');
+    const tagBudget = showTag ? MAX_TAG_WIDTH + 2 : 0; // 2 = gap before tag
+    const nextBudget = Math.max(10, maxWidth - leftLen - 2 - tagBudget); // -2 for `  ` separator
+    let nextRendered = nextText;
+    if (nextText.length > nextBudget) nextRendered = nextText.slice(0, nextBudget - 3) + '...';
+
+    // Coloring for "blocked by" stays yellow.
+    if (doc.blockers?.length && doc.status === 'blocked') nextRendered = yellow(nextRendered);
+
+    let line = `${leftBlock}  ${nextRendered}`;
+    if (showTag) {
+      // Pad next column to push tag to the right column boundary.
+      const consumed = visibleLen(line);
+      const targetCol = maxWidth - MAX_TAG_WIDTH;
+      const padCount = Math.max(2, targetCol - consumed);
+      line = `${line}${' '.repeat(padCount)}${colorTag(doc.status)}`;
+    }
+    process.stdout.write(line + '\n');
   }
 }