dotmd-cli 0.39.1 → 0.39.3

package/bin/dotmd.mjs

@@ -170,6 +170,8 @@ If a plan is already in-session:
 
 Options:
   --takeover             Force-claim a plan held by another session
+  --no-index             Skip index regen (see \`dotmd archive --help\`)
+  --show-files           Append \`files: …\` line to stderr (see \`dotmd archive --help\`)
   --json                 Output as JSON
   --dry-run, -n          Preview without writing
 
@@ -191,6 +193,8 @@ Options:
   --all                  Release every lease in the file (administrative)
   --stale                Release leases whose pid is dead or age >24h
   --force                Override "not yours" refusal on a specific file
+  --no-index             Skip index regen (see \`dotmd archive --help\`)
+  --show-files           Append \`files: …\` line to stderr (see \`dotmd archive --help\`)
   --json                 Output as JSON ({ released, skipped })
   --dry-run, -n          Preview without writing
 
@@ -221,6 +225,11 @@ Moves the document to the new status. If transitioning to an archive
 status, automatically moves the file to the archive directory and
 regenerates the index (if configured).
 
+Options:
+  --no-index             Skip index regen (useful in concurrent-session repos
+                         doing path-limited commits — see \`dotmd archive --help\`).
+  --show-files           Append \`files: …\` line to stderr (see \`dotmd archive --help\`).
+
 Default plan statuses (each maps to a distinct unstuck-action):
   in-session     A Claude session is working on it now
   active         Ready to be picked up
@@ -252,7 +261,17 @@ Options:
 Sets status to 'archived', moves to the archive directory, auto-updates
 references in other docs, and regenerates the index.
 
-Use --dry-run (-n) to preview changes without writing anything.`,
+Options:
+  --no-index             Skip index regen. Use when multiple sessions are
+                         working concurrently and you want a path-limited
+                         commit that doesn't pull other agents' uncommitted
+                         index changes into your staging area. Run \`dotmd index\`
+                         later (or wire it into a commit hook) to refresh.
+  --show-files           Append a final \`files: a b c …\` line to stderr
+                         listing every doc/index path the command touched
+                         (deduped, sorted, repo-relative). Lets agents do
+                         \`git add\` with the exact set instead of guessing.
+  --dry-run, -n          Preview changes without writing anything.`,
 
   coverage: `dotmd coverage — metadata coverage report
 
@@ -488,6 +507,8 @@ 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
+  --show-files         Append \`files: …\` line to stderr listing what was touched
+                       (the new doc + the index file). See \`dotmd archive --help\`.
   --list-types         Show registered types (alias: --list-templates)
 
 For plans, the default status vocabulary is: in-session, active, planned,
@@ -680,6 +701,21 @@ Supports all query flags (--status, --json, --sort, etc.)`,
 Shows documents that reference or depend on the given file.
 Useful for impact analysis before archiving or changing a plan.
 
+The dependency edge is read from each plan's \`blockers:\` frontmatter
+(a YAML list of plan slugs or paths). \`blocked_by:\` is accepted as
+an alias since 0.39.3 — both populate the same index field, so use
+whichever name reads better.
+
+Frontmatter shape:
+
+    ---
+    type: plan
+    status: blocked
+    blockers:
+      - foo-plan.md
+      - docs/plans/bar-plan.md
+    ---
+
 Options:
   --json                 Output as JSON`,
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.39.1",
+  "version": "0.39.3",
   "description": "CLI for managing markdown documents with YAML frontmatter — index, query, validate, graph, export, Notion sync, AI summaries.",
   "type": "module",
   "license": "MIT",

package/src/index.mjs

@@ -175,7 +175,13 @@ export function parseDocFile(filePath, config, opts = {}) {
     }
   }
   const nextStep = asString(parsedFrontmatter.next_step) ?? extractNextStep(body) ?? null;
-  const blockers = normalizeBlockers(parsedFrontmatter.blockers);
+  // `blocked_by` is accepted as an alias for `blockers` since 0.39.3 — agents
+  // filing tickets naturally reach for the JIRA/Linear name. If both are set,
+  // they're merged (de-duped via normalizeBlockers → mergeUniqueStrings).
+  const blockers = mergeUniqueStrings(
+    normalizeBlockers(parsedFrontmatter.blockers),
+    normalizeBlockers(parsedFrontmatter.blocked_by),
+  );
   const surface = asString(parsedFrontmatter.surface) ?? null;
   const surfaces = normalizeStringList(parsedFrontmatter.surfaces);
   const moduleName = asString(parsedFrontmatter.module) ?? null;

package/src/lifecycle.mjs

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter, replaceFrontmatter } from './frontmatter.mjs';
-import { asString, toRepoPath, die, warn, resolveDocPath, resolveRefPath, escapeRegex, nowIso, suggestCandidates } from './util.mjs';
+import { asString, toRepoPath, die, warn, resolveDocPath, resolveRefPath, escapeRegex, nowIso, suggestCandidates, emitFilesFooter } from './util.mjs';
 import { gitMv, getGitLastModified, getGitLastModifiedBatch } from './git.mjs';
 import { buildIndex, collectDocFiles } from './index.mjs';
 import { renderIndexFile, writeIndex } from './index-file.mjs';
@@ -68,6 +68,9 @@ function uniqueArchiveTarget(targetDir, basename) {
 
 export async function runStatus(argv, config, opts = {}) {
   const { dryRun } = opts;
+  const noIndex = argv.includes('--no-index') || opts.noIndex;
+  const showFiles = argv.includes('--show-files') || opts.showFiles;
+  argv = argv.filter(a => a !== '--no-index' && a !== '--show-files');
   const input = argv[0];
   let newStatus = argv[1];
 
@@ -167,11 +170,24 @@ export async function runStatus(argv, config, opts = {}) {
 
   // Regen the index on every status change — `active → planned` etc. drift
   // the per-status sections just as much as archive crossings. Archive paths
-  // also benefit (replaces the previously-gated regen).
-  regenIndex(config);
+  // also benefit (replaces the previously-gated regen). `--no-index` skips
+  // this so concurrent agents can do path-limited commits without pulling
+  // each other's uncommitted index changes into the staging area.
+  if (noIndex) {
+    process.stderr.write(dim('(index not regenerated — run `dotmd index` to refresh)\n'));
+  } else {
+    regenIndex(config);
+  }
 
   process.stdout.write(`${green(toRepoPath(finalPath, config.repoRoot))}: ${oldStatus ?? 'unknown'} → ${newStatus}\n`);
 
+  if (showFiles) {
+    const touched = [filePath];
+    if (finalPath !== filePath) touched.push(finalPath);
+    if (config.indexPath && !noIndex) touched.push(config.indexPath);
+    emitFilesFooter(touched, config);
+  }
+
   try { config.hooks.onStatusChange?.({ path: toRepoPath(finalPath, config.repoRoot), oldStatus, newStatus }, {
     oldPath: toRepoPath(filePath, config.repoRoot),
     newPath: toRepoPath(finalPath, config.repoRoot),
@@ -183,6 +199,8 @@ export async function runPickup(argv, config, opts = {}) {
   const json = argv.includes('--json');
   const takeover = argv.includes('--takeover');
   const fullBody = argv.includes('--full');
+  const noIndex = argv.includes('--no-index') || opts.noIndex;
+  const showFiles = argv.includes('--show-files') || opts.showFiles;
   let input = argv.find(a => !a.startsWith('-'));
 
   // Interactive: pick from active/planned plans
@@ -253,7 +271,11 @@ export async function runPickup(argv, config, opts = {}) {
     }
     if (oldStatus !== 'in-session') {
       updateFrontmatter(filePath, { status: 'in-session', updated: today });
-      regenIndex(config);
+      if (noIndex) {
+        process.stderr.write(dim('(index not regenerated — run `dotmd index` to refresh)\n'));
+      } else {
+        regenIndex(config);
+      }
     }
     // VH append per lease outcome:
     //   acquired   → `Picked up (<old> → in-session).`
@@ -295,6 +317,12 @@ export async function runPickup(argv, config, opts = {}) {
     }
   }
 
+  if (showFiles && oldStatus !== 'in-session') {
+    const touched = [filePath];
+    if (config.indexPath && !noIndex) touched.push(config.indexPath);
+    emitFilesFooter(touched, config);
+  }
+
   try { config.hooks.onPickup?.({ path: repoPath, oldStatus, newStatus: 'in-session' }); } catch (err) { warn(`Hook 'onPickup' threw: ${err.message}`); }
 }
 
@@ -304,10 +332,13 @@ export async function runUnpickup(argv, config, opts = {}) {
   const all = argv.includes('--all');
   const stale = argv.includes('--stale');
   const force = argv.includes('--force');
+  const noIndex = argv.includes('--no-index') || opts.noIndex;
+  const showFiles = argv.includes('--show-files') || opts.showFiles;
   const toIdx = argv.indexOf('--to');
   const toStatus = toIdx >= 0 ? argv[toIdx + 1] : null;
   const positional = argv.filter((a, i) => !a.startsWith('-') && argv[i - 1] !== '--to');
   const fileArg = positional[0];
+  const touched = [];
 
   const session = currentSessionId();
   const released = [];
@@ -360,7 +391,12 @@ export async function runUnpickup(argv, config, opts = {}) {
         const today = nowIso();
         updateFrontmatter(filePath, { status: newStatus, updated: today });
         appendVersionHistory(filePath, `Released (in-session → ${newStatus}).`);
-        regenIndex(config);
+        touched.push(filePath);
+        if (noIndex) {
+          process.stderr.write(dim('(index not regenerated — run `dotmd index` to refresh)\n'));
+        } else {
+          regenIndex(config);
+        }
       }
       // If frontmatter is no longer in-session (manual flip), leave it alone.
     } catch (err) {
@@ -429,6 +465,12 @@ export async function runUnpickup(argv, config, opts = {}) {
       process.stderr.write(`${yellow('⚠ Skipped')}: ${s.path} (held by ${s.session}; use --force to override)\n`);
     }
   }
+
+  if (showFiles && touched.length > 0) {
+    const all = [...touched];
+    if (config.indexPath && !noIndex) all.push(config.indexPath);
+    emitFilesFooter(all, config);
+  }
 }
 
 export async function runFinish(argv, config, opts = {}) {
@@ -493,6 +535,9 @@ export async function runFinish(argv, config, opts = {}) {
 
 export function runArchive(argv, config, opts = {}) {
   const { dryRun, out = process.stdout } = opts;
+  const noIndex = argv.includes('--no-index') || opts.noIndex;
+  const showFiles = argv.includes('--show-files') || opts.showFiles;
+  argv = argv.filter(a => a !== '--no-index' && a !== '--show-files');
   const input = argv[0];
 
   if (!input) { die('Usage: dotmd archive <file>'); }
@@ -519,7 +564,8 @@ export function runArchive(argv, config, opts = {}) {
     const prefix = dim('[dry-run]');
     out.write(`${prefix} Would update frontmatter: status: ${oldStatus} → archived, updated: ${today}\n`);
     out.write(`${prefix} Would move: ${oldRepoPath} → ${newRepoPath}\n`);
-    if (config.indexPath) out.write(`${prefix} Would regenerate index\n`);
+    if (config.indexPath && !noIndex) out.write(`${prefix} Would regenerate index\n`);
+    if (config.indexPath && noIndex) out.write(`${prefix} Would skip index regen (--no-index)\n`);
 
     // Preview reference updates
     const refCount = countRefsToUpdate(filePath, targetPath, config);
@@ -541,22 +587,31 @@ export function runArchive(argv, config, opts = {}) {
   const selfRefsFixed = updateRefsFromMovedFile(filePath, targetPath, config);
 
   // Auto-update references in other docs
-  const updatedRefCount = updateRefsAfterMove(filePath, targetPath, config);
+  const { count: updatedRefCount, paths: refTouchedPaths } = updateRefsAfterMove(filePath, targetPath, config);
 
-  regenIndex(config);
+  if (!noIndex) regenIndex(config);
 
   out.write(`${green('Archived')}: ${oldRepoPath} → ${newRepoPath}\n`);
   if (selfRefsFixed) out.write('Updated references in archived file.\n');
   if (updatedRefCount > 0) out.write(`Updated references in ${updatedRefCount} file(s).\n`);
-  if (config.indexPath) out.write('Index regenerated.\n');
+  if (config.indexPath && !noIndex) out.write('Index regenerated.\n');
+  if (config.indexPath && noIndex) out.write(dim('(index not regenerated — run `dotmd index` to refresh)\n'));
 
   try { releaseLease(config, oldRepoPath, { force: true }); } catch (err) { warn(`Could not release lease for ${oldRepoPath}: ${err.message}`); }
 
+  const touched = [oldRepoPath, newRepoPath, ...refTouchedPaths];
+  if (config.indexPath && !noIndex) touched.push(config.indexPath);
+  if (showFiles) emitFilesFooter(touched, config);
+
   try { config.hooks.onArchive?.({ path: newRepoPath, oldStatus }, { oldPath: oldRepoPath, newPath: newRepoPath }); } catch (err) { warn(`Hook 'onArchive' threw: ${err.message}`); }
+
+  return { touched };
 }
 
 export function runBulkArchive(argv, config, opts = {}) {
   const { dryRun } = opts;
+  const noIndex = argv.includes('--no-index') || opts.noIndex;
+  const showFiles = argv.includes('--show-files') || opts.showFiles;
   const inputs = argv.filter(a => !a.startsWith('-'));
   if (inputs.length === 0) die('Usage: dotmd bulk archive <file1> <file2> ... or <glob>');
 
@@ -592,14 +647,30 @@ export function runBulkArchive(argv, config, opts = {}) {
   }
 
   process.stdout.write('\n');
+  // Bulk archives always defer index regen to the end — N individual regens
+  // is wasteful and the final state is the same. `--no-index` skips even
+  // the final one.
+  const bulkTouched = [];
   for (const f of unique) {
     const relPath = toRepoPath(f, config.repoRoot);
     try {
-      runArchive([relPath], config, opts);
+      const result = runArchive([relPath], config, { ...opts, noIndex: true, showFiles: false });
+      if (result?.touched) bulkTouched.push(...result.touched);
     } catch (err) {
       warn(`Failed to archive ${relPath}: ${err.message}`);
     }
   }
+  if (!noIndex) {
+    regenIndex(config);
+    if (config.indexPath) process.stdout.write('Index regenerated.\n');
+  } else if (config.indexPath) {
+    process.stdout.write(dim('(index not regenerated — run `dotmd index` to refresh)\n'));
+  }
+  if (showFiles) {
+    const all = [...bulkTouched];
+    if (config.indexPath && !noIndex) all.push(config.indexPath);
+    emitFilesFooter(all, config);
+  }
 }
 
 export function runTouch(argv, config, opts = {}) {
@@ -682,7 +753,7 @@ export function runTouch(argv, config, opts = {}) {
 function updateRefsAfterMove(oldPath, newPath, config) {
   const basename = path.basename(oldPath);
   const allFiles = collectDocFiles(config);
-  let updatedCount = 0;
+  const touched = [];
 
   for (const docFile of allFiles) {
     if (docFile === newPath) continue;
@@ -710,11 +781,11 @@ function updateRefsAfterMove(oldPath, newPath, config) {
     if (newFm !== fm) {
       raw = replaceFrontmatter(raw, newFm);
       writeFileSync(docFile, raw, 'utf8');
-      updatedCount++;
+      touched.push(docFile);
     }
   }
 
-  return updatedCount;
+  return { count: touched.length, paths: touched };
 }
 
 function updateRefsFromMovedFile(oldPath, newPath, config) {

package/src/new.mjs

@@ -1,7 +1,7 @@
 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 { toRepoPath, die, warn, nowIso, emitFilesFooter } from './util.mjs';
 import { green, dim, bold } from './color.mjs';
 import { isInteractive, promptText } from './prompt.mjs';
 import { regenIndex } from './lifecycle.mjs';
@@ -185,12 +185,14 @@ export async function runNew(argv, config, opts = {}) {
   let title = null;
   let rootName = opts.root ?? null;
   let messageFlag = null;
+  let showFiles = opts.showFiles ?? false;
   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] === '--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] === '--show-files') { showFiles = true; continue; }
     if (argv[i] === '--list-templates' || argv[i] === '--list-types') {
       listTemplates(config);
       return;
@@ -265,17 +267,37 @@ export async function runNew(argv, config, opts = {}) {
 
   // Fail-fast when the user passes body input to a template that doesn't
   // consume it — silently discarding heredoc content is the worst UX.
-  // Templates opt in via `acceptsBody: true` or `requiresBody: true`. All
-  // built-in templates (doc, plan, prompt) accept body; this guard fires
-  // only for custom templates that opt out.
+  // Templates opt in via `acceptsBody: true` or `requiresBody: true`.
   if (bodyInput !== null && !template.acceptsBody && !template.requiresBody) {
-    const accepting = Object.entries(BUILTIN_TEMPLATES)
-      .filter(([, t]) => t.acceptsBody || t.requiresBody)
-      .map(([n]) => n);
+    const configTemplates = config.raw?.templates ?? {};
+    // Compute the accepting list from the RESOLVED set (config merged over
+    // built-ins) so the hint doesn't contradict the rejection.
+    const resolvedNames = new Set([...Object.keys(BUILTIN_TEMPLATES), ...Object.keys(configTemplates)]);
+    const accepting = [...resolvedNames]
+      .filter(n => n !== typeName)
+      .filter(n => {
+        const t = resolveTemplate(n, config);
+        return t.acceptsBody || t.requiresBody;
+      });
     const hint = accepting.length > 0
       ? ` Templates that accept body input: ${accepting.join(', ')}.`
       : '';
-    die(`\`${typeName}\` template does not accept body input, but body was passed via ${bodyInputSource}.${hint}\nEither drop the body, switch to a template that accepts it, or set \`acceptsBody: true\` on your custom \`${typeName}\` template in dotmd.config.mjs.`);
+
+    // Override-of-builtin diagnosis: the most common cause is a project
+    // dotmd.config.mjs that copy-pasted a stripped-down `plan` template
+    // and dropped the body-acceptance contract. Name that explicitly so
+    // an agent can self-fix without spelunking the config.
+    const builtin = BUILTIN_TEMPLATES[typeName];
+    const isOverride = Boolean(configTemplates[typeName] && builtin);
+    const builtinAccepts = Boolean(builtin && (builtin.acceptsBody || builtin.requiresBody));
+    let cause;
+    if (isOverride && builtinAccepts) {
+      const where = config.configPath ? toRepoPath(config.configPath, config.repoRoot) : 'dotmd.config.mjs';
+      cause = `Your config (${where}) overrides the built-in \`${typeName}\` template, and the override drops body acceptance.\nFix: in that override, add \`acceptsBody: true\` AND interpolate \`\${ctx?.bodyInput?.trim() ?? ''}\` into your \`body\` fn (e.g., inside \`## Problem\`). Or drop the override to use the built-in.`;
+    } else {
+      cause = `Either drop the body, switch to a template that accepts it, or set \`acceptsBody: true\` on your custom \`${typeName}\` template in dotmd.config.mjs.`;
+    }
+    die(`\`${typeName}\` template does not accept body input, but body was passed via ${bodyInputSource}.${hint}\n${cause}`);
   }
 
   // If name contains path separators, split into directory prefix and basename
@@ -375,14 +397,49 @@ export async function runNew(argv, config, opts = {}) {
 
   regenIndex(config);
 
+  if (showFiles) {
+    const touched = [filePath];
+    if (config.indexPath) touched.push(config.indexPath);
+    emitFilesFooter(touched, config);
+  }
+
   try { config.hooks.onNew?.({ path: repoPath, status, title: docTitle, type: typeName }); } catch (err) { warn(`Hook 'onNew' threw: ${err.message}`); }
 }
 
 function resolveTemplate(name, config) {
-  // Config templates take priority
   const configTemplates = config.raw?.templates ?? {};
-  if (configTemplates[name]) return configTemplates[name];
-  if (BUILTIN_TEMPLATES[name]) return BUILTIN_TEMPLATES[name];
+  const override = configTemplates[name];
+  const builtin = BUILTIN_TEMPLATES[name];
+
+  if (override) {
+    if (!builtin) return { ...override, _overridesBuiltin: false };
+    // Partial-override DX: shallow-merge built-in under override so missing
+    // fields (description, dir, targetRoot, defaultStatus, frontmatter, body,
+    // acceptsBody, requiresBody) fall back to the built-in. Anything the
+    // override explicitly declares wins.
+    const merged = { ...builtin, ...override, _overridesBuiltin: true };
+
+    // Body-loss guard: if the override supplies its OWN body fn but doesn't
+    // explicitly opt in to body acceptance, the inherited built-in
+    // `acceptsBody`/`requiresBody` could let body input flow into a custom
+    // body fn that doesn't honor `ctx.bodyInput` — silently discarding the
+    // heredoc, the worst-UX bug fix #9 was added to prevent. Strip the
+    // inherited flags so the fail-fast guard fires. EXCEPT when the custom
+    // body fn references `bodyInput` itself, in which case it's clearly
+    // body-aware and inheriting acceptsBody is the agent-first move.
+    const overrodeBody = typeof override.body === 'function';
+    const declaredAcceptance = override.acceptsBody !== undefined || override.requiresBody !== undefined;
+    if (overrodeBody && !declaredAcceptance) {
+      const bodyAware = /bodyInput/.test(override.body.toString());
+      if (!bodyAware) {
+        merged.acceptsBody = undefined;
+        merged.requiresBody = undefined;
+      }
+    }
+    return merged;
+  }
+
+  if (builtin) return builtin;
 
   const available = [...new Set([...Object.keys(BUILTIN_TEMPLATES), ...Object.keys(configTemplates)])];
   die(`Unknown type: ${name}\nAvailable: ${available.join(', ')}`);

package/src/prompts.mjs

@@ -116,12 +116,14 @@ function resolvePromptInput(input, config) {
 function runPromptsUse(argv, config, opts = {}) {
   const input = argv.find(a => !a.startsWith('-'));
   if (!input) die('Usage: dotmd prompts use <file-or-slug>');
+  const noIndex = argv.includes('--no-index') || opts.noIndex;
+  const showFiles = argv.includes('--show-files') || opts.showFiles;
   const filePath = resolvePromptInput(input, config);
-  consumePrompt(filePath, config, opts);
+  consumePrompt(filePath, config, { ...opts, noIndex, showFiles });
 }
 
 function consumePrompt(filePath, config, opts) {
-  const { dryRun } = opts;
+  const { dryRun, noIndex, showFiles } = opts;
   const raw = readFileSync(filePath, 'utf8');
   const { frontmatter, body } = extractFrontmatter(raw);
   const parsed = parseSimpleFrontmatter(frontmatter);
@@ -138,20 +140,22 @@ function consumePrompt(filePath, config, opts) {
 
   if (dryRun) {
     process.stderr.write(`${dim('[dry-run]')} Would emit body and archive: ${repoPath} (${status ?? 'unknown'} → archived)\n`);
-    runArchive([filePath], config, { dryRun: true, out: process.stderr });
+    runArchive([filePath], config, { dryRun: true, noIndex, out: process.stderr });
     return;
   }
 
   process.stdout.write(body);
   if (!body.endsWith('\n')) process.stdout.write('\n');
 
-  runArchive([filePath], config, { out: process.stderr });
+  runArchive([filePath], config, { noIndex, showFiles, out: process.stderr });
   process.stderr.write(`${green('✓ Consumed')}: ${repoPath}\n`);
 }
 
 function runPromptsArchive(argv, config, opts = {}) {
   const input = argv.find(a => !a.startsWith('-'));
   if (!input) die('Usage: dotmd prompts archive <file-or-slug>');
+  const noIndex = argv.includes('--no-index') || opts.noIndex;
+  const showFiles = argv.includes('--show-files') || opts.showFiles;
   const filePath = resolvePromptInput(input, config);
 
   const raw = readFileSync(filePath, 'utf8');
@@ -161,7 +165,7 @@ function runPromptsArchive(argv, config, opts = {}) {
     die(`Not a prompt: ${toRepoPath(filePath, config.repoRoot)}`);
   }
 
-  runArchive([filePath], config, opts);
+  runArchive([filePath], config, { ...opts, noIndex, showFiles });
 }
 
 async function runPromptsNew(argv, config, opts = {}) {

package/src/util.mjs

@@ -55,6 +55,18 @@ export function toRepoPath(absolutePath, repoRoot) {
   return path.relative(repoRoot, absolutePath).split(path.sep).join('/');
 }
 
+// Emit a `files: a b c` line to stderr listing every doc / index path
+// the command touched (deduped, sorted, repo-relative). Lets agents do
+// `git add` with the exact set instead of guessing. Opt-in via
+// `--show-files` on lifecycle commands; default off to keep output stable.
+export function emitFilesFooter(paths, config) {
+  const rel = [...new Set(paths.filter(Boolean))]
+    .map(p => path.isAbsolute(p) ? toRepoPath(p, config.repoRoot) : p)
+    .sort();
+  if (rel.length === 0) return;
+  process.stderr.write(`files: ${rel.join(' ')}\n`);
+}
+
 export function nowIso() {
   return new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
 }

package/src/validate.mjs

@@ -95,6 +95,10 @@ export function validateDoc(doc, frontmatter, headingTitle, config) {
     doc.errors.push({ path: doc.path, level: 'error', message: '`blockers` must be a YAML list when present.' });
   }
 
+  if (Object.prototype.hasOwnProperty.call(frontmatter, 'blocked_by') && !Array.isArray(frontmatter.blocked_by)) {
+    doc.errors.push({ path: doc.path, level: 'error', message: '`blocked_by` must be a YAML list when present.' });
+  }
+
   if (Object.prototype.hasOwnProperty.call(frontmatter, 'surfaces') && !Array.isArray(frontmatter.surfaces)) {
     doc.errors.push({ path: doc.path, level: 'error', message: '`surfaces` must be a YAML list when present.' });
   }