dotmd-cli 0.56.0 → 0.57.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.56.0",
+  "version": "0.57.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/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/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/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 === '??');