dotmd-cli 0.56.0 → 0.58.0

package/README.md

@@ -23,6 +23,8 @@ If you drive dotmd from Claude Code, install the **dotmd plugin**. It teaches ev
 
 The plugin bundles the hooks (`SessionStart`/`SubagentStart` priming, a `PreToolUse` guard) and a canonical workflow skill, so guidance travels to **every** repo automatically — no per-repo setup. It calls the `dotmd` CLI, so keep `npm install -g dotmd-cli` installed too. (Source: `plugins/dotmd/` in this repo.)
 
+> **Upgrading to 0.57.0+:** per-repo `.claude/commands/{plans,docs,baton}.md` scaffolding is retired — that guidance now ships via the plugin's workflow skill and `/plans`, `/docs`, `/prompts`, `/baton` commands. On the next `dotmd hud` (SessionStart), dotmd removes those generated files (only banner-stamped `<!-- dotmd-generated -->` ones — your hand-authored command files are never touched). If you'd committed them, you'll see deletions to commit — that's expected. Run `claude plugin update dotmd@dotmd` to pick up `/baton`.
+
 ## Quick Start
 
 ```bash
@@ -803,6 +805,11 @@ export const lifecycle = {
   skipStaleFor: ['archived'],
   skipWarningsFor: ['archived'],
   terminalStatuses: ['archived'],
+  // Types that archive into their own <typeDir>/<archiveDir> (e.g.
+  // docs/prompts/archived/) instead of the shared <root>/<archiveDir>.
+  // Defaults to ['prompt'] so session-local prompt churn doesn't bury
+  // plans and docs in the shared archive. Set to [] to disable.
+  archiveNestedTypes: ['prompt'],
 };
 
 export const taxonomy = {

package/dotmd.config.example.mjs

@@ -130,6 +130,9 @@ export const statuses = {
 //   skipStaleFor: ['archived'],         // skip staleness checks
 //   skipWarningsFor: ['archived'],      // skip validation warnings (summary, etc.)
 //   terminalStatuses: ['archived', 'deprecated', 'reference'],  // skip current_state/next_step warnings, exclude from stats scope
+//   archiveNestedTypes: ['prompt'],     // types that archive under <typeDir>/<archiveDir>
+//                                       // (e.g. docs/prompts/archived/) instead of the
+//                                       // shared <root>/<archiveDir>; set [] to disable
 // };
 
 // Taxonomy validation — set fields to null to skip validation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.56.0",
+  "version": "0.58.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

@@ -1,220 +1,71 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, unlinkSync } from 'node:fs';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { green, dim, yellow } from './color.mjs';
 
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const pkg = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
-// Marker is no longer pinned to line 1 — it now lives below the YAML
-// frontmatter that Claude Code surfaces as the slash command's description.
-// The regex is intentionally non-anchored so getInstalledVersion finds it
-// wherever it sits, and the marker string is specific enough that a false
-// positive elsewhere in a user-edited file is not a realistic concern.
-const VERSION_REGEX = /<!-- dotmd-generated: ([\d.]+) -->/;
-function markerFor(version) { return `<!-- dotmd-generated: ${version} -->`; }
-
-// Trigger sentences surfaced by Claude Code's available-skills system reminder.
-// Front-load the "when to reach for it" cue so Claude can route to the right
-// slash command without the user having to type the slash. The plans entry
-// 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 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.",
-};
-
-const VOCAB_TRUNCATE_AT = 12;
-
-// Per-type valid statuses, rendered as one clause per type. Appended to the
-// plans description so it lands in Claude's available-skills listing at
-// SessionStart — no discovery command needed before the first `dotmd status`
-// / `dotmd archive` call. Types with no declared statuses are skipped (the
-// generic global list applies); types with >VOCAB_TRUNCATE_AT statuses are
-// truncated with an ellipsis so the description stays bounded.
-function statusVocabClause(config) {
-  if (!config?.typeStatuses) return '';
-  const parts = [];
-  for (const [type, statusesSet] of config.typeStatuses.entries()) {
-    if (!statusesSet || statusesSet.size === 0) continue;
-    let statuses = [...statusesSet];
-    if (statuses.length > VOCAB_TRUNCATE_AT) {
-      statuses = [...statuses.slice(0, VOCAB_TRUNCATE_AT), '…'];
-    }
-    parts.push(`Valid ${type} statuses: ${statuses.join(', ')}.`);
-  }
-  return parts.join(' ');
-}
-
-function frontmatterFor(name, config) {
-  let description = SLASH_DESCRIPTIONS[name];
-  if (name === 'plans') {
-    const vocab = statusVocabClause(config);
-    if (vocab) description = `${description} ${vocab}`;
-  }
-  return ['---', `description: ${description}`, '---'];
-}
-
-function generatePlansCommand(config, version) {
-  const lines = [...frontmatterFor('plans', config), markerFor(version), ''];
-  lines.push('Run `dotmd context` to get the current plans briefing, then use it to orient yourself.');
-  lines.push('');
-  lines.push(`Plans are managed by **dotmd** (v${version}). Config at \`dotmd.config.mjs\`. Always use \`dotmd\` directly.`);
-  lines.push('');
-  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. Writes the new status to the plan\'s frontmatter. Use it to transition or close any plan:');
-  lines.push('    - `dotmd set in-session <file>` — mark a plan in-session (just a frontmatter status; use `dotmd use <file>` to also print the body)');
-  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 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 → mark in-session + print card, 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');
-  lines.push('- `dotmd runlist <hub>` — show ordered children of a runlist hub (→ marks next)');
-  lines.push('- `dotmd runlist next <hub>` — open the next non-archived child of a runlist hub');
-
-  if (config.raw?.glossary) {
-    lines.push('- `dotmd glossary <term>` — domain term lookup with related plans');
-  }
-
-  lines.push('');
-  lines.push('If the user asks about a specific plan, read its file directly (path is in the briefing or findable via `dotmd query --keyword <term>`).');
-  lines.push('');
-  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('If the user references a runlist by name — e.g. "what\'s next on <X> runlist", "<X> runlist status", "pick up the next in <X>" — use `dotmd runlist next <X>` (or `dotmd runlist <X>` first to inspect the ordering). Do NOT fall back to `dotmd context` for runlist-scoped questions.');
-  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 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');
-}
-
-function generateDocsCommand(config, version) {
-  const roots = Array.isArray(config.raw?.root) ? config.raw.root : [config.raw?.root ?? 'docs'];
-  const rootCount = roots.length;
-
-  const lines = [...frontmatterFor('docs', config), markerFor(version), ''];
-  lines.push(`All documentation in this repo is managed by **dotmd** (v${version}). Docs across ${rootCount} root${rootCount > 1 ? 's' : ''}: ${roots.join(', ')}. Config at \`dotmd.config.mjs\`.`);
-  lines.push('');
-
-  // Document types from config
-  const types = config.raw?.types ? Object.keys(config.raw.types) : [];
-  if (types.length > 0) {
-    lines.push(`Document types: ${types.map(t => '`' + t + '`').join(', ')}.`);
-    lines.push('');
-  }
-
-  lines.push('Commands for working with docs:');
-  lines.push('- `dotmd context` — LLM-oriented briefing across all types');
-  lines.push('- `dotmd doctor --apply` — auto-fix everything in one pass (refs, lint, dates, index; bare `dotmd doctor` previews only)');
-  lines.push('- `dotmd query [filters]` — search by status, keyword, module, surface, type, staleness');
-  lines.push('- `dotmd health` — plan pipeline, velocity, aging');
-  lines.push('- `dotmd stats` — doc health dashboard (completeness, checklists, audit coverage)');
-  lines.push('- `dotmd graph [--dot]` — visualize document relationships');
-  lines.push('- `dotmd deps [file]` — dependency tree');
-  lines.push('- `dotmd unblocks <file>` — impact analysis for a doc');
-  lines.push('- `dotmd diff [file]` — git changes since last updated date');
-  lines.push('- `dotmd list` — all docs grouped by status');
-  lines.push('- `dotmd focus <status>` — detailed view for one status group');
-
-  if (config.raw?.glossary) {
-    lines.push('- `dotmd glossary <term>` — domain term lookup with related docs and plans');
+// dotmd used to scaffold per-repo `.claude/commands/{plans,docs}.md` slash
+// commands — version-stamped, generated from each repo's status vocab, and
+// self-healed by `dotmd hud`. That mechanism is RETIRED. The dotmd Claude Code
+// plugin (plugins/dotmd/skills/dotmd/SKILL.md + bundled hooks) now carries the
+// canonical agent-facing workflow into every repo and every subagent, and
+// `dotmd hud` injects the dynamic per-project status vocab at runtime. A static
+// skill + a runtime hook covers the full picture with no per-repo file to drift.
+//
+// The only job left in this module is teardown: delete the stale generated
+// command files dotmd left behind so retired scaffolding stops shadowing the
+// plugin skill. Removal is banner-gated — files WITHOUT the dotmd marker are
+// hand-authored (e.g. a repo's own module-*.md / domain-*.md briefings) and are
+// NEVER touched. Every dotmd-stamped file is fair game, including legacy ones
+// dotmd no longer generates (e.g. the old baton.md).
+
+const GENERATED_MARKER = '<!-- dotmd-generated:';
+
+// The marker sits just below the YAML frontmatter Claude Code surfaces as the
+// command description. That description can be long (the retired plans.md baked
+// the full per-type status vocab into it), pushing the banner well past the
+// first kilobyte — so classify against the whole file, not a head slice. These
+// are tiny command files, so reading them in full is cheap.
+function isGeneratedCommandFile(filePath) {
+  try {
+    return readFileSync(filePath, 'utf8').includes(GENERATED_MARKER);
+  } catch {
+    return false;
   }
-
-  lines.push('');
-  lines.push('Lifecycle:');
-  lines.push('- `dotmd new plan <name>` — scaffold new plan');
-  lines.push('- `dotmd new doc <name>` — scaffold reference doc');
-  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');
-  lines.push('- `dotmd touch --git` — bulk-sync updated dates from git history');
-  lines.push('- `dotmd lint --fix` — auto-fix frontmatter issues');
-  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 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');
 }
 
-function getInstalledVersion(filePath) {
-  if (!existsSync(filePath)) return null;
-  const content = readFileSync(filePath, 'utf8');
-  const match = content.match(VERSION_REGEX);
-  return match ? match[1] : null;
-}
-
-export function scaffoldClaudeCommands(cwd, config, opts = {}) {
-  const { dryRun = false, version = pkg.version } = opts;
-  const claudeDir = path.join(cwd, '.claude');
-  if (!existsSync(claudeDir)) return [];
-
-  const commandsDir = path.join(claudeDir, 'commands');
-  const results = [];
-
-  const files = [
-    { name: 'plans.md', generate: () => generatePlansCommand(config, version) },
-    { name: 'docs.md', generate: () => generateDocsCommand(config, version) },
-  ];
-
-  for (const { name, generate } of files) {
+// Remove every dotmd-generated slash-command file under .claude/commands.
+// Returns [{ name, action: 'removed' }] for each file cleaned (or that would be
+// cleaned, in dry-run). Never throws — teardown must not break a hook or a
+// command. User-authored command files (no dotmd banner) survive untouched.
+export function removeGeneratedSlashCommands(cwd, opts = {}) {
+  const { dryRun = false } = opts;
+  const commandsDir = path.join(cwd, '.claude', 'commands');
+  if (!existsSync(commandsDir)) return [];
+  let entries;
+  try { entries = readdirSync(commandsDir); } catch { return []; }
+  const removed = [];
+  for (const name of entries) {
+    if (!name.endsWith('.md')) continue;
     const filePath = path.join(commandsDir, name);
-    const installedVersion = getInstalledVersion(filePath);
-
-    if (installedVersion === version) {
-      results.push({ name, action: 'current' });
-    } else if (installedVersion) {
-      // Outdated — regenerate
-      if (!dryRun) {
-        mkdirSync(commandsDir, { recursive: true });
-        writeFileSync(filePath, generate(), 'utf8');
-      }
-      results.push({ name, action: 'updated', from: installedVersion, to: version });
-    } else if (!existsSync(filePath)) {
-      // New — create
-      if (!dryRun) {
-        mkdirSync(commandsDir, { recursive: true });
-        writeFileSync(filePath, generate(), 'utf8');
-      }
-      results.push({ name, action: 'created' });
-    } else {
-      // File exists but no version marker — user-managed, don't touch
-      results.push({ name, action: 'skipped' });
+    if (!isGeneratedCommandFile(filePath)) continue;
+    if (!dryRun) {
+      try { unlinkSync(filePath); } catch { continue; }
     }
+    removed.push({ name, action: 'removed' });
   }
-
-  return results;
+  return removed;
 }
 
-// Self-heal: regen any slash-command file whose banner is older than pkg.version.
-// Designed for runHud to call at SessionStart — closes the gap between "user
-// upgraded dotmd" and "slash-command body reflects the new version" without
-// requiring a manual `dotmd doctor`. Returns only the entries that actually
-// changed so the caller can surface a one-line note; an empty array means the
-// hud silent-clean contract is preserved. `skipped` (user-managed, no banner)
-// and `current` entries are filtered out — callers don't care about them.
+// Self-heal entrypoint for `dotmd hud` (SessionStart hook). Was: regenerate
+// stale slash commands. Now: delete the retired generated files so the plugin
+// skill is the single source of truth. Returns only the removed entries; an
+// empty array preserves hud's silent-clean contract. Kept under the old name so
+// hud's call site (and its swallow-all-errors wrapper) is unchanged.
 export function refreshStaleSlashCommands(config) {
-  const results = scaffoldClaudeCommands(config.repoRoot, config);
-  return results.filter(r => r.action === 'updated');
+  return removeGeneratedSlashCommands(config.repoRoot);
 }
 
-// Intentionally returns []. Slash-command stamp drift is auto-healed every
-// time `dotmd hud` runs (SessionStart hook), and `dotmd doctor` regens them
-// on demand. Surfacing a warning at `dotmd check` time was pure noise — it
-// fired on every release until the next session, despite the user having no
-// action to take (the heal is automatic). Kept the function for API stability
-// in case downstream callers import it.
+// Retained as a no-op for API stability. `dotmd check` never warned on slash
+// commands (the old auto-heal made it pure noise), and now there is nothing to
+// generate at all. See git history for the retired scaffolder.
 export function checkClaudeCommands(_cwd, _opts = {}) {
   return [];
 }

package/src/config.mjs

@@ -63,6 +63,12 @@ const DEFAULTS = {
     // statuses file under the owning type folder; archive remains a separate
     // primitive untouched.
     filedStatuses: { held: 'held', shelved: 'held', paused: 'held' },
+    // Types whose archive nests under their own type dir (<typeDir>/<archiveDir>,
+    // e.g. docs/prompts/archived/) instead of the shared <root>/<archiveDir>.
+    // Prompts are session-local churn — keeping their archive out of the shared
+    // docs/archived/ stops them from burying plans/docs there. Set to [] to send
+    // every type to the shared archive.
+    archiveNestedTypes: ['prompt'],
   },
 
   taxonomy: {
@@ -476,6 +482,9 @@ export async function resolveConfig(cwd, explicitConfigPath) {
   // F15: filedStatuses keyed by status name, value = directory name. Empty
   // object when no status opts in via `filed: true` (or `filed: '<dirname>'`).
   const filedStatuses = new Map(Object.entries(lifecycle.filedStatuses ?? {}));
+  // Types that archive into their own <typeDir>/<archiveDir> rather than the
+  // shared <root>/<archiveDir> (default: prompt).
+  const archiveNestedTypes = new Set(lifecycle.archiveNestedTypes ?? []);
 
   // Warn if rootStatuses keys don't match any configured root
   for (const rootKey of Object.keys(rootStatusesRaw)) {
@@ -507,7 +516,7 @@ export async function resolveConfig(cwd, explicitConfigPath) {
     rootValidStatuses,
     staleDaysByStatus,
 
-    lifecycle: { archiveStatuses, skipStaleFor, skipWarningsFor, terminalStatuses, filedStatuses },
+    lifecycle: { archiveStatuses, skipStaleFor, skipWarningsFor, terminalStatuses, filedStatuses, archiveNestedTypes },
 
     validSurfaces,
     validModules,

package/src/doctor.mjs

@@ -7,7 +7,7 @@ import { buildIndex, collectDocFiles } from './index.mjs';
 import { renderIndexFile, writeIndex } from './index-file.mjs';
 import { renderCheck, renderManualFixes } from './render.mjs';
 import { bold, dim, green, yellow } from './color.mjs';
-import { checkClaudeCommands, scaffoldClaudeCommands } from './claude-commands.mjs';
+import { checkClaudeCommands, removeGeneratedSlashCommands } from './claude-commands.mjs';
 import { runMigrateTemplate } from './migrate-template.mjs';
 import { runMigratePrompts } from './migrate-prompts.mjs';
 import { runFrontmatterFix } from './frontmatter-fix.mjs';
@@ -98,25 +98,27 @@ export function runDoctor(argv, config, opts = {}) {
     process.stdout.write('Index updated.\n');
   }
 
-  // Step 5: Refresh Claude Code commands. Always print the heading so the
-  // numbering stays `1,2,3,4,5,6` — pre-fix it was conditional, so a doctor
-  // run where everything was already current printed `1,2,3,4,6` with `5.`
-  // silently missing.
+  // Step 5: Clean up retired Claude Code command scaffolding. The per-repo
+  // `.claude/commands/{plans,docs}.md` files are superseded by the dotmd plugin
+  // skill; doctor sweeps any leftover banner-stamped (dotmd-generated) files.
+  // Always print the heading so the numbering stays `1,2,3,4,5,6`.
   process.stdout.write('\n' + bold('5. Claude Code commands:') + '\n');
   if (dryRun) {
-    process.stdout.write('[dry-run] Would refresh .claude/commands/ if outdated.\n');
+    const wouldRemove = removeGeneratedSlashCommands(config.repoRoot, { dryRun: true });
+    if (wouldRemove.length === 0) {
+      process.stdout.write('[dry-run] No retired slash-command files to remove.\n');
+    } else {
+      for (const r of wouldRemove) {
+        process.stdout.write(`[dry-run] Would remove retired .claude/commands/${r.name} (guidance now ships via the dotmd plugin).\n`);
+      }
+    }
   } else {
-    const claudeResults = scaffoldClaudeCommands(config.repoRoot, config);
-    const changes = claudeResults.filter(r => r.action === 'updated' || r.action === 'created');
-    if (changes.length === 0) {
-      process.stdout.write('Nothing to refresh.\n');
+    const removed = removeGeneratedSlashCommands(config.repoRoot);
+    if (removed.length === 0) {
+      process.stdout.write('Nothing to clean up.\n');
     } else {
-      for (const r of changes) {
-        if (r.action === 'updated') {
-          process.stdout.write(`${green('Updated')} .claude/commands/${r.name} (v${r.from} → v${r.to})\n`);
-        } else if (r.action === 'created') {
-          process.stdout.write(`${green('Created')} .claude/commands/${r.name}\n`);
-        }
+      for (const r of removed) {
+        process.stdout.write(`${green('Removed')} retired .claude/commands/${r.name} (guidance now ships via the dotmd plugin)\n`);
       }
     }
   }

package/src/guard.mjs

@@ -25,11 +25,17 @@ const pkg = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'),
 
 const SHELL_READERS = new Set(['cat', 'less', 'more', 'head', 'tail', 'bat', 'view', 'open']);
 
-// A path that ends in .md and sits under a `prompts/` directory is a saved
-// prompt regardless of which doc root it belongs to — robust across repos
-// without needing the resolved config.
+// A path that ends in .md and sits under a `prompts/` directory is a
+// session-local saved prompt regardless of which doc root it belongs to —
+// robust across repos without needing the resolved config. Archived prompts
+// (`…/prompts/archived/…`, the default nested archive for the prompt type) are
+// committable history, NOT session-local, so they're explicitly excluded — the
+// guard must not block committing or reading them.
 function isPromptPath(p) {
-  return typeof p === 'string' && p.endsWith('.md') && /(^|\/)prompts\//.test(p);
+  if (typeof p !== 'string' || !p.endsWith('.md')) return false;
+  if (!/(^|\/)prompts\//.test(p)) return false;
+  if (/(^|\/)archived\//.test(p)) return false;
+  return true;
 }
 
 // Loose "is this a dotmd-managed doc" test: a .md file under one of the

package/src/hud.mjs

@@ -261,11 +261,12 @@ export function runHud(argv, config) {
 
   const hud = buildHud(config);
 
-  // Self-heal stale slash-command files. Wrapped: a broken scaffolder must
-  // never kill the SessionStart hook (would block every session). Runs for its
-  // side effect only — the refresh is no longer announced in stdout (see the
-  // primer-only contract below). Skipped in --json mode to keep the structured
-  // shape stable for programmatic callers.
+  // Clean up retired generated slash-command files (the plugin skill replaces
+  // them). Banner-gated, so hand-authored commands survive. Wrapped: teardown
+  // must never kill the SessionStart hook (would block every session). Runs for
+  // its side effect only — nothing is announced in stdout (see the primer-only
+  // contract below). Skipped in --json mode to keep the structured shape stable
+  // for programmatic callers.
   if (!json) {
     try { refreshStaleSlashCommands(config); }
     catch { /* swallow — see comment above */ }

package/src/init.mjs

@@ -5,8 +5,7 @@ import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { green, dim, yellow } from './color.mjs';
 import { warn } from './util.mjs';
-import { scaffoldClaudeCommands } from './claude-commands.mjs';
-import { resolveConfig } from './config.mjs';
+import { removeGeneratedSlashCommands } from './claude-commands.mjs';
 
 // Subdirectories scaffolded under docsRoot and tracked separately during scans.
 // Each maps to a builtin type (plan, prompt). New types added here should also
@@ -331,53 +330,32 @@ export async function runInit(cwd, config, opts = {}) {
     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
-  // resolveConfig was called before init wrote the starter, so the `if (config)`
-  // gate below silently skipped slash-command scaffolding entirely on first init.
-  // Re-resolving picks up STARTER_CONFIG (or any pre-existing config) in the
-  // real-run path; in dry-run with no on-disk config, it returns the merged
-  // DEFAULTS, which is enough for the preview line (`would create…`).
-  //
-  // Reports all four scaffold outcomes so the user can't be surprised by
-  // either a silent regenerate (pre-fix: `updated` was unreported) or by
-  // dotmd skipping a user-managed file (pre-fix: `skipped` was unreported).
-  const scaffoldConfig = await resolveConfig(cwd);
-  if (scaffoldConfig) {
-    const results = scaffoldClaudeCommands(cwd, scaffoldConfig, { dryRun });
-    for (const r of results) {
-      const filename = `.claude/commands/${r.name}`;
-      if (r.action === 'created') {
-        process.stdout.write(`  ${dryTag}${green('create')}  ${filename}\n`);
-      } else if (r.action === 'updated') {
-        process.stdout.write(`  ${dryTag}${green('update')}  ${filename} (v${r.from} → v${r.to})\n`);
-      } else if (r.action === 'current') {
-        process.stdout.write(`  ${dryTag}${dim('exists')}  ${filename}\n`);
-      } else if (r.action === 'skipped') {
-        process.stdout.write(`  ${dryTag}${yellow('skip')}    ${filename} (no version marker — user-managed)\n`);
-      }
+  // Claude Code integration. dotmd no longer scaffolds per-repo
+  // `.claude/commands/*.md` slash commands — the dotmd plugin's SKILL.md is the
+  // canonical agent-facing workflow now, and `dotmd hud` injects this repo's
+  // status vocab at runtime. If a `.claude/` exists, sweep any retired
+  // generated command files (banner-gated, so hand-authored ones survive) and
+  // point the user at the plugin instead.
+  if (existsSync(path.join(cwd, '.claude'))) {
+    const removed = removeGeneratedSlashCommands(cwd, { dryRun });
+    for (const r of removed) {
+      const verb = dryRun ? 'would remove' : 'removed';
+      process.stdout.write(`  ${dryTag}${yellow('clean')}   .claude/commands/${r.name} (retired — ${verb}; guidance ships via the dotmd plugin)\n`);
     }
-  }
 
-  // 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(`\n  ${yellow('hint')}    install the dotmd Claude Code plugin so its hooks + workflow skill\n`);
+      process.stdout.write(`            travel to every session and subagent automatically:\n\n`);
+      process.stdout.write(`              /plugin marketplace add reowens/dotmd\n`);
+      process.stdout.write(`              /plugin install dotmd@dotmd\n\n`);
+      process.stdout.write(`            Or, without the plugin, wire \`dotmd hud\` at SessionStart by hand —\n`);
+      process.stdout.write(`            add to .claude/settings.json (merge into any existing hooks):\n\n`);
+      process.stdout.write(`              "hooks": { "SessionStart": [\n`);
+      process.stdout.write(`                { "hooks": [{ "type": "command", "command": "dotmd hud" }] }\n`);
+      process.stdout.write(`              ] }\n`);
     }
   }
 

package/src/lifecycle.mjs

@@ -32,6 +32,17 @@ function findFilingRoot(filePath, fileRoot, docType, config) {
   return fileRoot;
 }
 
+// Base directory a doc archives under. Types in lifecycle.archiveNestedTypes
+// (default: prompt) archive into their own <typeDir>/ — yielding
+// <typeDir>/<archiveDir> (e.g. docs/prompts/archived/) — so session-local
+// prompt churn doesn't bury plans/docs in the shared <root>/<archiveDir>.
+// Everything else archives under fileRoot. Used by both runStatus (set
+// archived) and runArchive so the two paths stay in lockstep.
+function archiveBaseFor(filePath, fileRoot, docType, config) {
+  const nest = config.lifecycle?.archiveNestedTypes?.has(docType) ?? false;
+  return nest ? findFilingRoot(filePath, fileRoot, docType, config) : fileRoot;
+}
+
 // Best-effort index regen for any doc-set or doc-status mutation. The
 // generated block groups by status and embeds per-doc snapshots, so any
 // change that affects what would render leaves the index stale. Wrapped
@@ -172,8 +183,11 @@ export async function runStatus(argv, config, opts = {}) {
   }
 
   const today = nowIso();
-  const archiveDir = path.join(fileRoot, config.archiveDir);
   const filingRoot = findFilingRoot(filePath, fileRoot, docType, config);
+  // Type-aware archive base (prompts nest under their type dir by default);
+  // unarchive reuses archiveBase so a prompt restores to its type dir.
+  const archiveBase = archiveBaseFor(filePath, fileRoot, docType, config);
+  const archiveDir = path.join(archiveBase, config.archiveDir);
   const relFromFilingRoot = path.relative(filingRoot, filePath);
   const relSegments = relFromFilingRoot.split(path.sep);
   const inArchive = isArchivedPath(toRepoPath(filePath, config.repoRoot), config);
@@ -202,7 +216,7 @@ export async function runStatus(argv, config, opts = {}) {
       finalPath = targetPath;
     }
     if (isUnarchiving) {
-      const targetPath = path.join(fileRoot, path.basename(filePath));
+      const targetPath = path.join(archiveBase, path.basename(filePath));
       process.stdout.write(`${prefix} Would move: ${toRepoPath(filePath, config.repoRoot)} → ${toRepoPath(targetPath, config.repoRoot)}\n`);
       finalPath = targetPath;
     }
@@ -235,7 +249,7 @@ export async function runStatus(argv, config, opts = {}) {
   }
 
   if (isUnarchiving) {
-    const targetPath = path.join(fileRoot, path.basename(filePath));
+    const targetPath = path.join(archiveBase, path.basename(filePath));
     if (existsSync(targetPath)) { die(`Target already exists: ${toRepoPath(targetPath, config.repoRoot)}`); }
     const result = gitMv(filePath, targetPath, config.repoRoot);
     if (result.status !== 0) { die(result.stderr || 'git mv failed.'); }
@@ -436,7 +450,9 @@ export function runArchive(argv, config, opts = {}) {
   const closeoutAction = closeoutTemplate ? planCloseoutInjection(body) : null;
 
   const today = nowIso();
-  const targetDir = path.join(archiveFileRoot, config.archiveDir);
+  // Type-aware: prompts archive under docs/prompts/archived/ by default (see
+  // archiveBaseFor); plans/docs keep the shared <root>/archived/.
+  const targetDir = path.join(archiveBaseFor(filePath, archiveFileRoot, asString(parsed.type), config), config.archiveDir);
   const targetPath = uniqueArchiveTarget(targetDir, path.basename(filePath));
   const oldRepoPath = toRepoPath(filePath, config.repoRoot);
   const newRepoPath = toRepoPath(targetPath, config.repoRoot);

package/src/ship.mjs

@@ -3,7 +3,6 @@ import { spawnSync } from 'node:child_process';
 import path from 'node:path';
 import { die, warn, toRepoPath } from './util.mjs';
 import { green, dim, yellow } from './color.mjs';
-import { scaffoldClaudeCommands } from './claude-commands.mjs';
 
 // Files dotmd ship will auto-stage when they're dirty. Anything outside this
 // allowlist stays in the working tree — user has to `git add` it explicitly,
@@ -77,16 +76,11 @@ export async function runShip(argv, config, opts = {}) {
 
   process.stdout.write(`${green('→')} Shipping ${current} → ${target} (${bump})\n`);
 
-  // 1. Regen slash commands at the *target* version so the resulting commit
-  //    matches the post-bump state and no dirty tree lingers after release.
-  const regenResults = scaffoldClaudeCommands(config.repoRoot, config, { version: target, dryRun });
-  const refreshed = regenResults.filter(r => r.action === 'updated' || r.action === 'created');
-  if (refreshed.length > 0) {
-    const verb = dryRun ? 'Would regenerate' : 'Regenerated';
-    process.stdout.write(`${green('→')} ${verb} slash commands @ ${target}: ${refreshed.map(r => r.name).join(', ')}\n`);
-  }
+  // Per-repo slash-command scaffolding is retired (the dotmd plugin's SKILL.md
+  // is canonical now), so there is nothing to regenerate at ship time. Any
+  // stale generated files are swept by `dotmd hud` / `dotmd doctor`.
 
-  // 2. Identify dirty tracked files. Anything matching the allowlist gets
+  // Identify dirty tracked files. Anything matching the allowlist gets
   //    staged; everything else is left dirty so the user can handle it.
   const dirty = listDirtyFiles(config.repoRoot);
   const untracked = dirty.filter(d => d.status === '??');