dotmd-cli 0.79.1 → 0.80.0

package/README.md

@@ -54,9 +54,10 @@ shell, and runlist reads it as a per-session identity automatically.
 /plugin install dotmd@dotmd
 ```
 
-The plugin provides SessionStart and SubagentStart orientation, a PreToolUse
-guard, the canonical workflow skill, and `/plans`, `/docs`, `/prompts`, and
-`/baton` commands.
+The plugin provides SessionStart and SubagentStart orientation, a
+UserPromptSubmit hint that gives the exact `runlist baton` form when you ask for
+a handoff, a PreToolUse guard, the canonical workflow skill, and `/plans`,
+`/docs`, `/prompts`, and `/baton` commands.
 
 ### OpenCode Plugin
 

package/bin/dotmd.mjs

@@ -109,8 +109,9 @@ Common commands:
   set <status> [file]   Transition status (start work, finish, archive — all via target status)
   new <type> <name>     Create plan/doc/prompt (pipe stdin or @path for body)
   use [<file-or-slug>]  Open a doc by type: prompt → consume, plan → start, doc → read
-  baton [<plan>|<slug>] <@<file>|-> Save a resume prompt (+ release the plan, if one is in-session)
                         (no file: consume oldest pending prompt)
+  baton [<plan>|<slug>] @<draft-file>
+                        Save a resume prompt (+ release the plan, if one is in-session)
   archive <file>        Close out a plan (status → archived, move, update refs)
 
 More help:
@@ -229,7 +230,7 @@ View & Query:
   grep <term>                       Keyword search incl. document bodies (query --keyword --body --all)
   plans                             Live plans (excludes archived; --include-archived for all)
   use [<file-or-slug>]              Open a doc by type: prompt → consume, plan → start, doc → read
-  baton [<plan>|<slug>] <@<file>|->  Save a resume prompt; releases the plan + prints the commit when one is in-session
+  baton [<plan>|<slug>] @<draft>     Save a resume prompt; releases the plan + prints the commit when one is in-session
   prompts [list|show|archive|new] Prompt admin (list / peek / archive / save). Use \`runlist use\` to consume.
   stale                             Stale docs (preset)
   actionable                        Docs with next steps (preset)
@@ -917,49 +918,53 @@ Use --dry-run (-n) to preview without writing.`,
 
   new: `runlist new <type> <name> [body] — create a new document
 
-Types and their default destinations:
-  plan        docs/plans/<slug>.md     (build-up template: Problem → Phases → Closeout)
-  doc         docs/<slug>.md           (build-up lite: Overview → Version History → Related)
-  prompt      docs/prompts/<slug>.md   (saved prompt to seed a future session — body required)
-
-\`<type>\` can be omitted; defaults to \`doc\`.
-\`<name>\` is slugified for the filename.
-
-Body input (all built-in types — required for prompt, optional for plan/doc):
-  piped stdin            Auto-consumed when stdin is piped/redirected (no flag needed)
-  @path                  Read body from a file
-  -                      Explicit stdin marker (equivalent to piped stdin)
-  --body "<text>"        Explicit inline body (alias: --message)
-  <text>                 Inline body as 3rd positional
-
-Tip for agents: prefer piped stdin or \`@path\` for multi-line bodies. Inline
-bodies put the entire content on the bash command line, which (a) breaks
-under shell quoting for backticks/dollar-signs and (b) trips PreToolUse hooks
-that scan command strings for forbidden literals (destructive-git patterns,
-etc.). \`cat /tmp/foo.md | runlist new …\` and \`@/tmp/foo.md\` both sidestep both.
-
-For plan/doc, a single-section body lands under the type's first scaffolded
-section (e.g. \`## Problem\` for plans). If the body already authors
-\`## Section\` headings start-to-finish, the scaffold short-circuits and only
-the title + your body is emitted — no duplicated empty outline below
-(since 0.36.1).
+Usage (write the draft to a file first):
+  runlist new plan <slug> @/tmp/draft.md     # plan from a draft
+  runlist new doc <slug> @/tmp/draft.md      # reference doc from a draft
+  runlist new prompt <slug> @/tmp/draft.md   # saved prompt (body required)
+  runlist new plan <slug>                    # empty scaffold to fill in
+
+What the draft does:
+  - Draft with its own \`## \` headings → it IS the body. Only a \`# Title\` is
+    added if missing; the template's outline is not appended. This holds for a
+    repo's own plan/doc template too.
+  - Draft with no \`## \` headings → lands in the template's first section
+    (\`## Problem\` for plans).
+  - Draft opening with a \`---\` frontmatter block → those keys replace the
+    scaffold's (status, surfaces, modules, current_state, next_step, …), so no
+    frontmatter edit is needed afterwards. \`type:\` is fixed by <type>.
+  To change status later, use \`runlist set <status> <file>\`.
+
+The repo's own types, starting statuses and folders are listed at the end of
+this help when it runs inside a runlist repo.
+
+Body input (required for prompt, optional for plan/doc):
+  @path                  Read body from a file (preferred)
+  -                      Read stdin explicitly (heredoc: \`runlist new … - <<'EOF'\`)
+  piped stdin            Read when something is piped or redirected in
+  --body "<text>"        Inline body (alias: --message), one-liners only
+  <text>                 Inline body as 3rd positional, one-liners only
+
+Inline bodies put the whole content on the command line, which breaks on
+backticks and dollar signs and trips hooks that scan commands; use @path.
+
+\`<type>\` can be omitted; defaults to \`doc\`. \`<name>\` is slugified for the
+filename; a name with a \`/\` is read relative to the repo (or to --root).
 
 Examples:
-  runlist new plan auth-revamp
+  runlist new plan auth-revamp @/tmp/auth-revamp.md
   runlist new prompt resume-foo @/tmp/draft.md
-  cat /tmp/draft.md | runlist new prompt resume-foo
-  runlist new prompt resume-foo <<'EOF'
-  multi-line
-  prompt body
-  EOF
-  runlist new prompt cleanup-tomorrow "look at remaining lint warnings"
-  runlist new plan full-spec <<'EOF'
+  runlist new plan full-spec - <<'EOF'
+  ---
+  status: planned
+  next_step: Phase 1, extract the token store.
+  ---
   ## Problem
   …
   ## Phases
   …
   EOF
-  runlist new plan auth-revamp "Investigation findings before scoping…"
+  runlist new prompt cleanup-tomorrow "look at remaining lint warnings"
 
 Scaffolding runlists (plans only):
   --runlist <a,b,c>    Create a sprint runlist hub plus one child plan per slug.
@@ -1182,31 +1187,15 @@ Examples:
 
   baton: `runlist baton — save a resume prompt for whatever you're doing (and release the plan, if there is one)
 
-The "save a resume prompt" verb. Works mid-anything:
-
-Plan mode (a plan is in-session, or you pass one):
-  The following publish in one atomic cooperating transaction:
-  1. A resume prompt named resume-<plan-slug> (collision-safe: -2, -3, …),
-     stamped with a plan: link so consuming it re-claims the plan (see \`runlist
-     use\`). The prompt is session-local — the next session's hud surfaces it;
-     never paste resume text into chat.
-  2. Releases the plan: one status flip, in-session → active by default
-     (--status to override, --note to record why in ## Version History).
-  3. Defers the shared generated index and prints exact repository-only commit
-     guidance. Prompt and ownership records stay session-local and OUT of the
-     pathspec.
-  Which plan? Pass it explicitly, or baton resolves exactly one plan owned by
-  this authoritative session. Journal entries and global in-session counts never
-  grant ownership. A live pickup-hook delivery lease blocks release and force
-  takeover; hooks are at-least-once and deduplicate the stable operationId.
+Usage (write the resume to a file first, then pick the form that matches):
+  runlist baton @/tmp/draft.md               # a plan is in-session: save resume-<plan-slug>, release the plan
+  runlist baton <plan-file> @/tmp/draft.md   # hand off a named plan
+  runlist baton <slug> @/tmp/draft.md        # no plan: save resume-<slug>, change nothing else
+  The resume can also come from stdin (\`-\`, or a pipe) or --message "..." for one-liners.
+  Baton prints the prompt name it saved and, in plan mode, the git commit to run.
 
-Slug mode (no plan involved — "save a resume prompt for this"):
-  runlist baton <slug> @/tmp/draft.md   →  saves resume-<slug>, touches NOTHING
-  else: no status changes, no commit, no plan required. Reference any relevant
-  plans/docs inside the draft body.
-
-Usage:
-  runlist baton [<plan-file> | <slug>] [@<draft-file> | - | --message "..."]
+The resume (10–20 lines): the next concrete decision plus any gotchas, and the
+paths of the plans/docs it concerns — not a recap of the plan body.
 
 Options:
   --status <s>           Target status for the plan (default: active; plan mode only)
@@ -1217,14 +1206,34 @@ Options:
   --dry-run, -n          Preview without writing
 
 Examples:
-  runlist baton @/tmp/draft.md                       # owned plan, body from file
-  runlist baton checkout-fixes @/tmp/draft.md        # no plan: just save resume-checkout-fixes
-  cat /tmp/draft.md | runlist baton                  # body from stdin
-  runlist baton docs/plans/auth.md @/tmp/draft.md    # explicit plan
+  runlist baton @/tmp/draft.md
+  runlist baton checkout-fixes @/tmp/draft.md
+  runlist baton docs/plans/auth.md @/tmp/draft.md
   runlist baton --status paused --note "blocked on review" @/tmp/d.md
+  cat /tmp/draft.md | runlist baton
+
+Plan mode (a plan is in-session, or you pass one) publishes in one atomic
+cooperating transaction:
+  1. A resume prompt named resume-<plan-slug>, stamped with a plan: link so
+     consuming it re-claims the plan (see \`runlist use\`). The prompt is
+     session-local — the next session's hud surfaces it; never paste resume text
+     into chat.
+  2. Releases the plan: one status flip, in-session → active by default.
+  3. Defers the shared generated index and prints exact repository-only commit
+     guidance. Prompt and ownership records stay session-local and OUT of the
+     pathspec.
+  Which plan? Pass it explicitly, or baton resolves exactly one plan owned by
+  this authoritative session. Journal entries and global in-session counts never
+  grant ownership. A live pickup-hook delivery lease blocks release and force
+  takeover; hooks are at-least-once and deduplicate the stable operationId.
+
+Slug mode (no plan involved) saves resume-<slug> and touches nothing else: no
+status change, no commit. A bare word that names a plan is treated as that plan.
 
-Write the draft FIRST (10–20 lines): the next concrete decision plus any
-gotchas — not a recap of the plan body.`,
+Baton saves nothing while a handoff for the same work is pending (resume-<name>,
+or a pending prompt linked to the plan): consume or archive it, then re-run.
+With no @file, \`-\` or --message, baton reads stdin only when something is piped
+in; an open pipe that sends nothing is given up on after a moment.`,
 
   stale: `runlist stale — list stale documents
 
@@ -1600,6 +1609,17 @@ async function main() {
   if (args.includes('--help') || args.includes('-h')) {
     requireCommandPolicy(command, dispatchPolicy);
     process.stdout.write(`${HELP[command] ?? commandUsage(command)}\n`);
+    if (command === 'new') {
+      // Best effort: outside a runlist repo, or with a broken config, the
+      // static help above is the whole answer.
+      try {
+        const repoConfig = await resolveConfig(process.cwd(), explicitConfig);
+        if (repoConfig?.configFound !== false) {
+          const { newHelpForRepo } = await import('../src/new.mjs');
+          process.stdout.write(`\n${newHelpForRepo(repoConfig)}\n`);
+        }
+      } catch { /* static help already printed */ }
+    }
     return;
   }
 
@@ -1619,6 +1639,9 @@ async function main() {
       process.stdout.write('{}\n');
       return;
     }
+    // A prompt hook runs on every user message; a broken config must not
+    // turn each one into an error.
+    if (command === 'hud' && restArgs.includes('--prompt-submit')) return;
     throw err;
   }
   _resolvedConfig = config;
@@ -1820,6 +1843,12 @@ async function main() {
   if (command === 'export') { const { runExport } = await import('../src/export.mjs'); runExport(restArgs, config, { dryRun, root: rootArg, type: typeArg }); return; }
 
   // Lifecycle commands
+  if (command === 'hud' && restArgs.includes('--prompt-submit')) {
+    const { runPromptSubmitHud } = await import('../src/hud.mjs');
+    const { readHookStdin } = await import('../src/guard.mjs');
+    await runPromptSubmitHud(config, { readStdin: readHookStdin });
+    return;
+  }
   if (command === 'hud') { const { runHud } = await import('../src/hud.mjs'); runHud(restArgs, config); return; }
   if (command === 'guard') { const { runGuard } = await import('../src/guard.mjs'); await runGuard(restArgs, config, { dryRun }); return; }
   if (command === 'update') { const { runUpdate } = await import('../src/update.mjs'); runUpdate(restArgs, config, { dryRun }); return; }

package/package.json

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

package/src/baton.mjs

@@ -30,8 +30,13 @@ export function findOwnedPlan(config, index = null) {
 // resume itself: the session that did the work is the only one that knows the
 // next decision, and a prompt assembled from frontmatter reads like a handoff
 // while carrying nothing the plan doesn't already say.
+// The three forms are listed because this is the message a bare `runlist baton`
+// prints, and an agent unsure of the shape should be able to act on it without
+// a trip through --help.
 const BODY_USAGE = `Nothing saved: baton needs the resume you wrote, passed as @<file> or - (stdin).
-  runlist baton [<plan-or-slug>] @/tmp/draft.md`;
+  runlist baton @/tmp/draft.md               # hand off the plan this session owns
+  runlist baton <plan-file> @/tmp/draft.md   # hand off a named plan
+  runlist baton <slug> @/tmp/draft.md        # no plan: save resume-<slug>, change nothing else`;
 
 // A handoff that lands beside a pending one leaves two prompts for the same
 // work, and the next session picks whichever sorts first. Baton used to step to

package/src/commands.mjs

@@ -64,7 +64,7 @@ const definitions = [
   command('briefing', none, 'read', [form('', { options: [flag('--json')] })]),
   command('context', none, 'read', [form('', { options: [flag('--json'), flag('--compact'), flag('--summarize'), value('--model')] })]),
   command('agent-context', none, 'read', [form('', { options: [flag('--json')] })]),
-  command('hud', none, 'read', [form('', { options: [flag('--json'), flag('--subagent')] })]),
+  command('hud', none, 'read', [form('', { options: [flag('--json'), flag('--subagent'), flag('--prompt-submit')] })]),
   command('focus', none, 'read', [form('[status]', { args: positionals(0, 1), options: [flag('--json')] })]),
   command('query', none, 'read', [form('[terms...]', { args: positionals(0, Infinity), options: QUERY_OPTIONS })]),
   command('grep', none, 'read', [form('<term> [terms...]', { args: positionals(1, Infinity), options: QUERY_OPTIONS })]),

package/src/guard.mjs

@@ -365,7 +365,7 @@ export function evaluateGuard(payload, config, deps = {}) {
   return null;
 }
 
-function readStdin() {
+export function readHookStdin() {
   return new Promise((resolve) => {
     let data = '';
     try {
@@ -404,7 +404,7 @@ function emit(result) {
 export async function runGuard(argv, config, opts = {}) {
   let payload = {};
   try {
-    const raw = await readStdin();
+    const raw = await readHookStdin();
     if (raw && raw.trim()) payload = JSON.parse(raw);
   } catch {
     payload = {};

package/src/hud.mjs

@@ -1,12 +1,15 @@
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { currentSessionId, isArchivedPath, relTime } from './util.mjs';
+import { asString, currentSessionId, isArchivedPath, relTime, toRepoPath } from './util.mjs';
+import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
+import { promptDirectory } from './new.mjs';
 import { dim, yellow } from './color.mjs';
 import { buildIndex } from './index.mjs';
 import { readJournalEntries, journalFilePath, readMisuseEntries } from './journal.mjs';
 import { compareVersions } from './update.mjs';
 import { findOwnedPlan } from './baton.mjs';
+import { listOwnedPlans } from './pickup.mjs';
 import { actionablePromptStatuses, comparePromptDocs, resolveStatusMetadata } from './status-metadata.mjs';
 
 export { actionablePromptStatuses } from './status-metadata.mjs';
@@ -48,6 +51,41 @@ export function detectVersionDrift(env = process.env) {
 // status surfaced too, without needing a code change.
 // Returns repo paths, oldest-created first — the same order no-arg `dotmd use`
 // consumes them, so prompts[0] is always "the one you'd pick up next".
+// The same answer from the prompt directory alone, reading frontmatter only.
+// The full index read every body in the repo; at ~5k docs that took 10s and the
+// SessionStart hook's 5s timeout killed hud before it printed anything.
+export function findActionablePromptsInPromptDir(config) {
+  const actionable = actionablePromptStatuses(config);
+  const dir = promptDirectory(config);
+  if (!existsSync(dir)) return [];
+  const docs = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true, recursive: true })) {
+    if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+    const abs = path.join(entry.parentPath ?? entry.path, entry.name);
+    const repoPath = toRepoPath(abs, config.repoRoot);
+    if (isArchivedPath(repoPath, config)) continue;
+    let fm;
+    try { fm = parseSimpleFrontmatter(extractFrontmatter(readFileSync(abs, 'utf8')).frontmatter ?? ''); }
+    catch { continue; }
+    const status = asString(fm.status);
+    if (asString(fm.type) !== 'prompt' || !actionable.has(status)) continue;
+    docs.push({ path: repoPath, status, created: asString(fm.created) || null, updated: asString(fm.updated) || null });
+  }
+  return docs.sort(comparePromptDocs).map(doc => doc.path);
+}
+
+// Text-mode hud: pending prompts and this session's plan, without the index.
+export function buildHudFast(config) {
+  let prompts = [];
+  let owned = null;
+  try { prompts = findActionablePromptsInPromptDir(config); } catch { /* hud must not fail */ }
+  try {
+    const records = listOwnedPlans(config);
+    if (!records.diagnostics?.length && records.length === 1) owned = { path: records[0].plan, title: null, via: 'ownership' };
+  } catch { /* hud must not fail */ }
+  return { owned, prompts, misuseRecap: buildMisuseRecap(config) };
+}
+
 function findActionablePrompts(config, index) {
   const actionable = actionablePromptStatuses(config);
   return index.docs
@@ -266,6 +304,47 @@ export function buildPlanStatusPrimer(config, { maxChars = 220 } = {}) {
 // the zero-false-positive signal for "this is a dotmd repo." A bare docs/ dir is
 // deliberately NOT enough — too many repos have one. In a non-dotmd repo the hook
 // then contributes nothing to the session: no primer, no index build, no heal.
+// UserPromptSubmit: when the user asks for a baton, tell the session the exact
+// form for its situation before it goes looking. Sessions ran `baton --help`
+// before nearly every baton even with the form in CLAUDE.md, because the right
+// form depends on whether this session owns a plan, which only runlist knows.
+const HANDOFF_ASK = /\bbaton\b|\bhand[\s-]?off\b|\bresume[\s-]prompt\b|\bsave (?:a |the )?resume\b|\bpick (?:it|this|that) (?:back )?up (?:next time|later|tomorrow)\b/i;
+
+export function isHandoffAsk(prompt) {
+  return typeof prompt === 'string' && HANDOFF_ASK.test(prompt);
+}
+
+export function buildHandoffContext(config) {
+  // Ownership records name their plans and are checked against those files
+  // alone; building the index here cost 9s in a repo of ~5k docs, past the
+  // hook's timeout.
+  let ownedPaths = [];
+  try {
+    const records = listOwnedPlans(config);
+    if (!records.diagnostics?.length) ownedPaths = records.map(record => record.plan);
+  } catch { /* fall through to the no-plan form */ }
+  const draft = 'Write the resume first (the next concrete decision, any gotchas, the plan/doc paths it concerns; not a recap) to a file in your scratchpad.';
+  const tail = 'Baton prints the prompt name it saved; tell the user that name. No `--help` needed.';
+  if (ownedPaths.length === 1) {
+    return `[runlist] Baton: this session owns ${ownedPaths[0]}. ${draft} Then run \`runlist baton @<file>\`: it saves the prompt, releases the plan to active (\`--status paused|awaiting|partial|blocked\` and \`--note "why"\` if that fits better), and prints the commit to run. ${tail}`;
+  }
+  if (ownedPaths.length > 1) {
+    return `[runlist] Baton: this session owns ${ownedPaths.length} plans (${ownedPaths.join(', ')}), so name the one to hand off. ${draft} Then run \`runlist baton <plan-file> @<file>\`. ${tail}`;
+  }
+  return `[runlist] Baton: this session owns no plan. ${draft} Then run \`runlist baton <slug> @<file>\` (saves resume-<slug>, changes nothing else), or \`runlist baton <plan-file> @<file>\` to hand off a plan by path. ${tail}`;
+}
+
+export async function runPromptSubmitHud(config, { readStdin } = {}) {
+  if (!isDotmdRepo(config)) return;
+  let prompt = '';
+  try {
+    const raw = await readStdin();
+    if (raw && raw.trim()) prompt = JSON.parse(raw).prompt ?? '';
+  } catch { return; }
+  if (!isHandoffAsk(prompt)) return;
+  process.stdout.write(buildHandoffContext(config) + '\n');
+}
+
 function isDotmdRepo(config) {
   return Boolean(config?.configFound);
 }
@@ -291,13 +370,14 @@ export function runHud(argv, config) {
   // the session. Skip the index build, slash-heal, primer, and drift line.
   if (!dotmdRepo && !json) return;
 
-  const hud = buildHud(config);
-
   if (json) {
+    const hud = buildHud(config);
     process.stdout.write(JSON.stringify({ ...hud, drift: drift ?? null }, null, 2) + '\n');
     return;
   }
 
+  const hud = buildHudFast(config);
+
   // SessionStart contract: the command primer, plus ONLY signals that carry a
   // direct instruction for this session. Passive state (error counts,
   // slash-command refresh notices, previous-self / fleet / recent-rejections)
@@ -313,7 +393,7 @@ export function runHud(argv, config) {
   //     Global in-session counts never provide a fallback.
   // The misuse recap stays for the same reason: a repeat-offense rule means
   // the primer alone isn't landing, so name the habit to break.
-  process.stdout.write(dim('runlist: plans|briefing  set <status> [<file>]  new <type> <slug>  use [<file>]  archive <file>  baton [<slug>] <@<file>|-> (save a resume prompt; releases the in-session plan if any)  (use [no-arg] → oldest pending prompt)') + '\n');
+  process.stdout.write(dim('runlist: plans|briefing  set <status> [<file>]  new <type> <slug>  use [<file>]  archive <file>  baton [<plan-or-slug>] @<draft-file> (save a resume prompt; releases the in-session plan if any)  (use [no-arg] → oldest pending prompt)') + '\n');
   process.stdout.write(dim(buildPlanStatusPrimer(config)) + '\n');
   if (hud.owned && hud.owned.via === 'ownership') {
     process.stdout.write(yellow(`[runlist] in-session (yours): ${hud.owned.path} — continue it; hand off with \`runlist baton @/tmp/draft.md\` before stopping.`) + '\n');

package/src/new.mjs

@@ -1,3 +1,4 @@
+import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, mkdirSync, fstatSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -348,13 +349,43 @@ export function readBodyInput(source) {
   return source;
 }
 
+// An agent's shell can hand a command a pipe that is open and never written or
+// closed (Claude Code does for chained and backgrounded commands), so a plain
+// blocking read of an implicit pipe hangs until the tool times out: a bare
+// `runlist baton` sat there for two minutes in the platform transcripts. A
+// child reads the pipe instead and gives up when the first byte doesn't arrive
+// within the window; once data starts it waits for EOF, so a slow producer that
+// has begun writing is never cut off.
+export const PIPED_STDIN_IDLE_MS = 1500;
+const STDIN_SILENT_EXIT = 3;
+const PIPE_READER = `let d='',got=false;` +
+  `const t=setTimeout(()=>{if(!got)process.exit(${STDIN_SILENT_EXIT})},Number(process.argv[1]));` +
+  `process.stdin.setEncoding('utf8');` +
+  `process.stdin.on('data',c=>{got=true;d+=c});` +
+  `process.stdin.on('end',()=>{clearTimeout(t);process.stdout.write(d)});`;
+
+function readPipeUnlessSilent() {
+  const r = spawnSync(process.execPath, ['-e', PIPE_READER, String(PIPED_STDIN_IDLE_MS)], {
+    stdio: [0, 'pipe', 'ignore'],
+    encoding: 'utf8',
+    maxBuffer: 64 * 1024 * 1024,
+    windowsHide: true,
+  });
+  if (r.status !== 0) return null;
+  return r.stdout;
+}
+
 export function readPipedBodyInput() {
   try {
     const stat = fstatSync(0);
+    if (stat.isFile()) {
+      const redirected = readFileSync(0, 'utf8');
+      return redirected.length > 0 ? redirected : null;
+    }
     const isWindowsPipe = process.platform === 'win32' && !process.stdin.isTTY;
-    if (stat.isFIFO() || stat.isFile() || stat.isSocket() || isWindowsPipe) {
-      const piped = readFileSync(0, 'utf8');
-      return piped.length > 0 ? piped : null;
+    if (stat.isFIFO() || stat.isSocket() || isWindowsPipe) {
+      const piped = readPipeUnlessSilent();
+      return piped ? piped : null;
     }
   } catch { /* stdin not introspectable */ }
   return null;
@@ -368,6 +399,18 @@ export function titleize(s) {
   return s.replace(/[-_]/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
 }
 
+// Where saved prompts are written: the prompt template's targetRoot when a
+// root matches it, else the primary root plus the template's `dir`.
+export function promptDirectory(config, template = resolveTemplate('prompt', config)) {
+  let targetRoot = config.docsRoot;
+  let routed = false;
+  if (template.targetRoot) {
+    const match = (config.docsRoots || [config.docsRoot]).find(root => root.endsWith(template.targetRoot) || path.basename(root) === template.targetRoot);
+    if (match) { targetRoot = match; routed = true; }
+  }
+  return template.dir && !routed ? path.join(targetRoot, template.dir) : targetRoot;
+}
+
 export function preparePromptDocument(name, bodyInput, config, { plan = null, dryRun = false } = {}) {
   const template = resolveTemplate('prompt', config);
   const typeStatuses = config.typeStatuses?.get('prompt');
@@ -377,14 +420,7 @@ export function preparePromptDocument(name, bodyInput, config, { plan = null, dr
   if (!bodyInput?.trim()) die('`prompt` template requires a body.');
   const slug = slugify(path.basename(name, '.md'));
   const title = titleize(path.basename(name, '.md'));
-  let targetRoot = config.docsRoot;
-  let routed = false;
-  if (template.targetRoot) {
-    const match = (config.docsRoots || [config.docsRoot]).find(root => root.endsWith(template.targetRoot) || path.basename(root) === template.targetRoot);
-    if (match) { targetRoot = match; routed = true; }
-  }
-  const baseDir = template.dir && !routed ? path.join(targetRoot, template.dir) : targetRoot;
-  const filePath = path.join(baseDir, `${slug}.md`);
+  const filePath = path.join(promptDirectory(config, template), `${slug}.md`);
   authorizeManagedDestination(filePath, config, { kind: 'Baton prompt destination' });
   if (dryRun) return { slug, filePath, repoPath: toRepoPath(filePath, config.repoRoot), content: null };
 
@@ -989,7 +1025,13 @@ export async function runNew(argv, config, opts = {}) {
     if (isRoadmap) fm = mergeBodyFrontmatter(fm, { execution_mode: 'roadmap' }, typeName);
     let body;
     const variantBody = isRunlistHub || isCoordinationHub || isRoadmap || isLite || isAudit;
-    const authored = variantBody ? fullBodyShortcut(docTitle, bodyInput) : null;
+    // A repo that overrides the plan or doc template keeps the built-in promise
+    // that an authored body replaces the outline. Without this, the override's
+    // body fn dropped the draft into its first slot and appended its own
+    // sections after it, so a draft opening `## Problem` came out with two, and
+    // sessions trimmed the tail by hand. Other custom types render as written.
+    const overridesShortcutType = template._overridesBuiltin && (typeName === 'plan' || typeName === 'doc');
+    const authored = variantBody || overridesShortcutType ? fullBodyShortcut(docTitle, bodyInput) : null;
     if (authored !== null) body = authored;
     else if (isRunlistHub) body = runlistHubBody(docTitle, slug, runlistChildren, bodyInput, today);
     else if (isCoordinationHub) body = coordinationHubBody(docTitle, bodyInput, today);
@@ -1074,6 +1116,40 @@ export async function runNew(argv, config, opts = {}) {
   };
 }
 
+// The part of `new --help` only the repo can answer: which types exist here,
+// what status each starts at, which statuses are valid, and where each lands.
+// Sessions otherwise read the config file to find out.
+export function newHelpForRepo(config) {
+  // Only types with a template: a status-only type can't be created by `new`.
+  const types = new Set([...Object.keys(BUILTIN_TEMPLATES), ...Object.keys(config.raw?.templates ?? {})]);
+  const rows = [];
+  const width = Math.max(...[...types].map(t => t.length));
+  for (const typeName of types) {
+    const template = resolveTemplate(typeName, config);
+    if (!template) continue;
+    const statuses = [...(config.typeStatuses?.get(typeName) ?? [])];
+    const tmplDefault = typeof template === 'object' ? template.defaultStatus : null;
+    const start = tmplDefault && (!statuses.length || statuses.includes(tmplDefault)) ? tmplDefault : (statuses[0] ?? tmplDefault ?? 'active');
+    const roots = config.docsRoots ?? [config.docsRoot];
+    // Mirrors runNew: a matching targetRoot wins, else the catch-all root plus
+    // the template's `dir`.
+    const typeRoot = typeof template === 'object' && template.targetRoot
+      ? roots.find(r => r.endsWith(template.targetRoot) || path.basename(r) === template.targetRoot)
+      : null;
+    const dest = typeRoot ?? (typeof template === 'object' && template.dir
+      ? path.join(catchAllRoot(config), template.dir)
+      : catchAllRoot(config));
+    const where = toRepoPath(dest, config.repoRoot) + '/';
+    const custom = Object.prototype.hasOwnProperty.call(config.raw?.templates ?? {}, typeName) ? ' (this repo\'s template)' : '';
+    rows.push(`  ${typeName.padEnd(width)} → ${where}<slug>.md, starts ${start}${custom}`);
+    if (statuses.length) rows.push(`  ${''.padEnd(width)}   statuses: ${statuses.join(', ')}`);
+  }
+  const roots = (config.docsRoots ?? [config.docsRoot]).map(r => path.basename(r));
+  return `This repo:
+${rows.join('\n')}
+  roots (for --root): ${roots.join(', ')}`;
+}
+
 function resolveTemplate(name, config) {
   const configTemplates = config.raw?.templates ?? {};
   const override = configTemplates[name];