dotmd-cli 0.38.1 → 0.39.0

package/package.json

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

@@ -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: "Wrap the current session cleanly: update the in-flight plan, save ONE resume prompt via 'dotmd new prompt', release the lease. 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,7 +66,7 @@ function generatePlansCommand(config) {
 }
 
 function generateBatonCommand() {
-  const lines = [VERSION_MARKER, ''];
+  const lines = [...frontmatterFor('baton'), VERSION_MARKER, ''];
   lines.push('You are wrapping this session. Hand the baton cleanly to the next one.');
   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.');
@@ -66,7 +85,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');
 }