dotmd-cli 0.38.1 → 0.39.1

package/package.json

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

@@ -6,10 +6,29 @@ 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'));
 const VERSION_MARKER = `<!-- dotmd-generated: ${pkg.version} -->`;
-const VERSION_REGEX = /^<!-- dotmd-generated: ([\d.]+) -->/;
+// 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.]+) -->/;
+
+// Trigger sentences surfaced by Claude Code's available-skills system reminder.
+// Keep each ≤200 chars (well under the 1,536-char auto-load truncation limit)
+// and 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.
+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 pick up / release / 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.",
+  baton: "Save a resume prompt for the held plan and release the lease — the minimum handoff. Use when the user says hand off / save a resume / wrap up, or when context is getting tight.",
+};
+
+function frontmatterFor(name) {
+  return ['---', `description: ${SLASH_DESCRIPTIONS[name]}`, '---'];
+}
 
 function generatePlansCommand(config) {
-  const lines = [VERSION_MARKER, ''];
+  const lines = [...frontmatterFor('plans'), VERSION_MARKER, ''];
   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${pkg.version}). Config at \`dotmd.config.mjs\`. Always use \`dotmd\` directly.`);
@@ -47,14 +66,18 @@ function generatePlansCommand(config) {
 }
 
 function generateBatonCommand() {
-  const lines = [VERSION_MARKER, ''];
-  lines.push('You are wrapping this session. Hand the baton cleanly to the next one.');
+  const lines = [...frontmatterFor('baton'), VERSION_MARKER, ''];
+  lines.push('Wrap this session. Minimum required (two commands):');
+  lines.push('');
+  lines.push('1. **Save the resume prompt.** `dotmd new prompt resume-<plan-slug>` with a 10-20 line body via heredoc: the next concrete decision plus any gotchas. NOT a recap of the plan body. The saved prompt IS the handoff — never print it into chat for copy-paste.');
   lines.push('');
-  lines.push('1. **Update the in-flight plan.** Find it via `dotmd plans --status in-session`. Edit its `current_state:` / `next_step:` frontmatter so they reflect where things actually stand. If status should change (shipped → archive, stuck on a human decision → awaiting, etc.), transition with `dotmd status <file> <status>` — or `dotmd archive <file>` if work is done.');
+  lines.push('2. **Release the lease.** `dotmd release` — or `dotmd archive <file>` if the work is fully shipped (archive auto-releases).');
   lines.push('');
-  lines.push('2. **Save ONE lean handoff prompt.** Run `dotmd new prompt resume-<plan-slug>` with a body of ~10-20 lines: point at the plan file, name the next concrete decision, flag any gotchas. Do NOT recap the plan body (the plan is for that). Do NOT print the handoff into chat for the user to copy-paste — the saved prompt is the handoff.');
+  lines.push('Optional, only when genuinely needed:');
+  lines.push('- Status really changed (paused / awaiting / partial / blocked): `dotmd status <file> <status>` BEFORE `dotmd release`.');
+  lines.push('- Plan dashboard text is misleading the user: edit `next_step:` in the plan frontmatter. Cosmetic — the next session reads the resume prompt, not the plan frontmatter.');
   lines.push('');
-  lines.push('3. **Release the lease.** `dotmd release` (skip if `dotmd archive` already closed out — archive auto-releases).');
+  lines.push('If you don\'t already know which plan you hold: `dotmd hud --json` and read `.owned`. Do NOT use `dotmd plans --status in-session` — that lists every session\'s holdings, not just yours.');
   lines.push('');
   lines.push('The next session\'s `dotmd hud` (SessionStart hook) surfaces the pending prompt automatically.');
   lines.push('');
@@ -66,7 +89,7 @@ function generateDocsCommand(config) {
   const roots = Array.isArray(config.raw?.root) ? config.raw.root : [config.raw?.root ?? 'docs'];
   const rootCount = roots.length;
 
-  const lines = [VERSION_MARKER, ''];
+  const lines = [...frontmatterFor('docs'), VERSION_MARKER, ''];
   lines.push(`All documentation in this repo is managed by **dotmd** (v${pkg.version}). Docs across ${rootCount} root${rootCount > 1 ? 's' : ''}: ${roots.join(', ')}. Config at \`dotmd.config.mjs\`.`);
   lines.push('');
 

package/src/hud.mjs

@@ -1,4 +1,4 @@
-import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { readLeases, findStaleLeases, currentSessionId } from './lease.mjs';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
@@ -124,6 +124,21 @@ export function runHud(argv, config) {
     lines.push(dim(`↻ slash commands refreshed (v${from} → v${to}): ${names}`));
   }
 
+  // Teach-once primer for fresh installs. The first session that runs hud in
+  // a dotmd-managed repo gets one line explaining what dotmd is and how to
+  // hand off — without this, a clean repo emits nothing and Claude has no
+  // signal that dotmd is the prompt/handoff machinery here. Gated on a
+  // marker under .dotmd/ (already the per-repo state dir, already gitignored
+  // by `dotmd init`) so subsequent sessions stay silent.
+  const primerMarker = path.join(config.repoRoot, '.dotmd', 'primer-shown');
+  if (!existsSync(primerMarker)) {
+    lines.push(dim('dotmd: managing this repo\'s docs. Use `dotmd new prompt` for handoffs (never hand-write docs/prompts/*.md). `dotmd plans` shows the queue. `dotmd --help` for more.'));
+    try {
+      mkdirSync(path.dirname(primerMarker), { recursive: true });
+      writeFileSync(primerMarker, '');
+    } catch { /* best-effort — failed marker write just means the primer reprints next session */ }
+  }
+
   if (lines.length === 0) return; // silent when clean
   process.stdout.write(lines.join('\n') + '\n');
 }