runlist 0.99.2 → 0.100.0

package/bin/runlist.mjs

@@ -8,11 +8,15 @@ import { readPlanStage } from '../src/stages.mjs';
 import { scopeFilingCoverage } from '../src/filing.mjs';
 import { die, warn, levenshtein, isArchivedPath, toRepoPath } from '../src/util.mjs';
 import { recordCliInvocation, recordGlobalError, sanitizeTelemetryArgv } from '../src/journal.mjs';
+import { outsideHandoffs, outsideHandoffsLine } from '../src/handoffs-scope.mjs';
 import { findRepeatFailureHint } from '../src/hints.mjs';
+import { focusedCommandHelp, unsupportedCommandHelp } from '../src/help.mjs';
 import {
   KNOWN_COMMANDS,
   canonicalCommand,
+  commandDefinition,
   commandOwnsOption,
+  commandPlanning,
   commandPolicy,
   commandUsage,
   validateCommandArgs,
@@ -30,6 +34,8 @@ const QUERY_VALUE_FLAGS = new Set([
 
 function requireCommandPolicy(command, policy) {
   if (policy) return policy;
+  const correction = unsupportedCommandHelp(command);
+  if (correction) die(`Unknown command: ${command}\n\n${correction}`);
   const matches = KNOWN_COMMANDS
     .map(cmd => ({ cmd, dist: levenshtein(command, cmd) }))
     .sort((a, b) => a.dist - b.dist);
@@ -61,6 +67,9 @@ function applyPathScopeToIndex(index, config, inputs) {
 
   const selected = new Set();
   for (const input of inputs) {
+    // A handoffs-only project checks its prompts and nothing else; any other
+    // path hears that planning is off (src/handoffs-scope.mjs).
+    if (outsideHandoffs(input, config)) die(outsideHandoffsLine(input));
     const resolved = resolveExistingPath(input, config);
     if (!resolved) die(`Could not resolve check path: ${input}`);
 
@@ -108,11 +117,39 @@ function applyPathScopeToIndex(index, config, inputs) {
   }
 }
 
+// Help where planning is off (a handoffs-only project, src/handoffs-mode.mjs):
+// the handoff verbs and the command that turns planning on, nothing else.
+const HANDOFFS_HELP = `runlist v${pkg.version} — session handoffs (planning is off in this project)
+
+Commands:
+  baton <slug> @<draft-file>   Save a resume prompt for the next session (resume-<slug>)
+  prompts                      List saved prompts
+  prompts show <name...>       Read saved prompts without consuming them
+  use [<name>]                 Resume a saved prompt (no name: the oldest pending)
+  new prompt <name> @<file>    Save a prompt under a name of its own
+  hud                          What a new session is told at startup
+  setup                        Turn planning on (plans, docs and an index); prompts stay put
+
+More help:
+  runlist help statuses   Prompt statuses
+  runlist <cmd> --help    Per-command details
+
+Global flags: --config <path>  --dry-run/-n  --verbose  --version`;
+
+const HANDOFFS_STATUS_HELP = `runlist help statuses — prompt statuses (planning is off in this project)
+
+  pending    Saved for a later session. \`runlist use <name>\` resumes it.
+  archived   Consumed or set aside; kept under docs/prompts/archived/.
+
+Plan and doc statuses come with planning; \`runlist setup\` turns it on.`;
+
 const HELP = {
   _main: `runlist v${pkg.version} — frontmatter markdown document manager
 
 Common commands:
+  setup                 Guided project setup; preview changes before applying
   plans                 Live plans (excludes archived)
+  show <file>           Plan/doc outline and open boxes; --section reads one section
   prompts               Prompt queue/admin (list, next, archive, new)
   briefing              Full briefing with plan counts + next steps
   agent-context         Compact bounded JSON context for agents
@@ -140,7 +177,8 @@ sessions keep making, and to log every one for audit:
   {"matcher":"Bash|Read|Edit|Write","hooks":[{"type":"command","command":"runlist guard"}]}
 
 Rules:
-  commit-prompt  deny  git add/commit of a (often gitignored) saved prompt
+  commit-prompt  policy  git add/commit including a pending prompt:
+                        untracked warns, tracked allows, local denies
   cat-prompt     warn  cat/less/head of a docs/prompts/*.md (use \`runlist use\`)
   read-prompt    warn  Read tool on a saved prompt (use \`runlist use\`)
   edit-status    deny  CHANGING a \`status:\` line — via Edit/Write or in-place
@@ -202,15 +240,32 @@ host gets that a different way:
             \`runlist.js\` without that stamp is treated as hand-authored and is
             never overwritten or removed without --force.
 
+Before installing, warns if no persistent CLI is on PATH. Temporary npx,
+pnpm dlx, bunx, Yarn wrapper bins and npm-injected project bins do not
+count. Run \`npm install -g runlist\`, then restart/reload the host.
+--json reports persistentCliMissing only when true.
+
 Writing outside the repo is why this is an explicit verb: \`runlist doctor\`
 reports a missing integration but never installs one.`,
 
-  update: `runlist update — update the runlist CLI and the Claude Code plugin together
+  update: `runlist update — update the CLI and already installed host integrations
 
   runlist update                 npm i -g runlist  +  claude plugin update runlist@runlist
   runlist update --check         report CLI vs plugin versions, do nothing (network-free)
+  runlist update --check --json  offline executable/profile/source report; no host programs run
   runlist update --cli-only      only the npm CLI
-  runlist update --plugin-only   only the plugin
+  runlist update --plugin-only   only installed host integrations
+  runlist update --host codex    only this installed host integration (no npm CLI/GUI update)
+  runlist update --host claude --claude-config /absolute/profile --claude-bin /absolute/native/claude
+
+--host accepts claude, codex or opencode and conflicts with --cli-only.
+Repeat --claude-config to select separate profiles; shared stores update once.
+--claude-bin preserves the chosen executable path. Unknown wrapper/profile
+mapping requires an explicit native binary; no profile is guessed.
+Missing integrations stay missing during update; use install or an explicitly
+selected doctor repair. Unmarked files remain user-owned. Catalog/source parity
+and installed records are checked separately from live activation, which still
+requires reload/trust. Unpublished checkout differences are labelled separately.
 
 The plugin and CLI ship in lockstep; a release bumps both. Updating the plugin
 requires a session restart (or /reload-plugins) to apply. The plugin step needs
@@ -253,7 +308,7 @@ Populated by the \`runlist guard\` PreToolUse hook — see \`runlist help guard\
   'help:all': `runlist v${pkg.version} — full command list
 
 View & Query:
-  hud [--json]                      Command primer + pending-prompt triage — silent when clean
+  hud [--json]                      Session-start handoff orientation + pending-prompt triage
   list [--verbose] [--json]         List docs grouped by status (default command)
   briefing [--json]                 Full briefing with plan status counts + next steps
   context [--summarize] [--json]    Full briefing (LLM-oriented; use --json --compact for bounded JSON)
@@ -327,7 +382,9 @@ Create & Export:
   export [--format md|html|json]    Export docs as markdown, HTML, or JSON
 
 Setup:
+  setup [--yes] [--json]            Guided setup, meaningful first plan and selected document adoption
   init                              Create starter config + docs directory
+  config show|get|set                Inspect project layout/policy; explicitly edit prompt tracking
   install [claude|codex|opencode]  Install the agent-host integration (no arg = status)
   update [--check|--cli-only|--plugin-only]  Update the CLI + Claude Code plugin (--check reports skew, no network)
   statuses [list|add|set|remove|migrate]  Manage per-project status taxonomy
@@ -713,23 +770,26 @@ Options:
 
   hud: `runlist hud — actionable triage for session start
 
-Prints the runlist command primer (the verb cheat-sheet) plus, in --json mode,
-pending prompts and the check-error count for programmatic callers.
-
-Silent when there's nothing actionable — designed for SessionStart hooks where
-zero noise is the right default. Distinct from \`runlist briefing\`, which
-dumps the full plan-status pipeline and per-plan next_step bodies (kilobytes
+Prints pending prompts, this session's owned plan, and actionable notices.
+Before the first saved handoff, a configured repo with no pending prompts or
+owned plan gets one orientation line. Otherwise silent when nothing needs
+attention. --json returns structured state and the check-error count.
+Distinct from \`runlist briefing\`, which dumps the full plan-status pipeline and per-plan next_step bodies (kilobytes
 on large repos). Use hud for ergonomic session boot; use briefing for
 explicit "give me the full picture."
 
-The pending-prompts line tells Claude to consume them via
-\`runlist prompts use <file>\` rather than reading/cat'ing — that atomically
-prints the body and archives the prompt so it cannot be double-consumed.
+The pending-prompts line says to resume only when asked, via
+\`runlist use <name>\`. --prompt-submit reads a hook JSON payload from stdin:
+save requests get baton instructions; pickup requests get a distinct hint only
+when prompts are pending. Text hooks read prompt frontmatter and ownership
+records without building the index.
 
 Recommended SessionStart hook (in ~/.claude/settings.json):
   "SessionStart": [{ "hooks": [{ "type": "command", "command": "runlist hud", "timeout": 5 }] }]
 
 Options:
+  --prompt-submit        Request-specific save/pickup hint (hook JSON on stdin)
+  --subagent             Compact workflow primer for child agents
   --json                 Output as JSON ({ owned, prompts, errors, previousSelf,
                          fleet, recentRejections, misuseRecap, drift })`,
 
@@ -859,6 +919,17 @@ sync hub status rows, sync dates from git, regenerate the index, then show
 remaining issues.
 
 Modes:
+  --hosts                Unified Claude/Codex/OpenCode inventory: executables,
+                         profiles/shared stores, installed/expected versions,
+                         source parity and unknown live-session loading.
+                         Read-only, offline, no project JS import; supports --json.
+  --hosts --repair <h>    Preview repairs for named hosts only; repeat --repair
+                         for more hosts. Add --apply to execute those targets.
+                         --dry-run always wins. --apply alone is refused here.
+                         Use --claude-config /absolute/profile (repeatable) and
+                         --claude-bin /absolute/native/claude for explicit targeting.
+                         Repair may install a selected missing integration;
+                         foreign/unreadable content and ambiguous wrappers are refused.
   (default)              Auto-fix pass — previews by default since 0.37.0
                          (F4). Use --apply (alias --yes) to actually write;
                          explicit --dry-run still wins over --apply if both
@@ -1058,6 +1129,7 @@ What the draft does:
   - 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>.
+    A status invalid for that type is replaced with its normal starting status.
   To change status later, use \`runlist set <status> <file>\`.
 
 The repo's own types, starting statuses and folders are listed at the end of
@@ -1242,13 +1314,83 @@ Examples:
 
 Use --dry-run (-n) to preview changes without writing anything.`,
 
-  init: `runlist init — create starter config and docs directory
+  setup: `runlist setup — guided project setup, with a concrete preview
 
-Creates runlist.config.mjs, docs/, and docs/docs.md in the current
-directory. Skips any files that already exist.
+Run in a terminal for choices and confirmation. Without an interactive terminal,
+setup previews only; add --yes to apply selected actions. --dry-run always
+previews without writing. The CLI works without the optional desktop app.
 
-If docs/ already contains .md files, auto-detects statuses, surfaces,
-modules, and reference fields to pre-populate the config.`,
+  --docs-root <path>       Fresh project docs folder (default docs); existing roots preserved
+  --prompt-tracking <p>    untracked (recommended), tracked, or local; existing choice preserved
+  --gitignore             Explicitly add missing ignore rules; default leaves ignore files alone
+  --host <host>           none (default), claude, codex, or opencode; explicit host install
+  --first-plan <slug>     Create a plan from the following user-supplied state and next action
+  --current-state <text>  What is true now (required with --first-plan)
+  --next-step <text>      Concrete next action (required with --first-plan)
+  --adopt <path>          Preview/adopt selected untagged Markdown; repeat for more paths
+  --no-carry-prompts      Leave pre-setup prompts and plans in place (default carries them over)
+  --json                  Structured preview or completed/outstanding report
+  --yes                   Apply choices without terminal questions
+
+Examples:
+  runlist setup
+  runlist setup --docs-root notes --dry-run
+  runlist setup --first-plan example --current-state "Requirements agreed." --next-step "Build a prototype." --dry-run
+  runlist setup --first-plan example --current-state "Requirements agreed." --next-step "Build a prototype." --yes
+  runlist setup --adopt docs/notes.md --dry-run
+
+Existing JavaScript hooks, configured folders and prompt locations are preserved.
+In a handoffs-only project (the config the first baton writes), setup turns
+planning on: it rewrites that config's mode, widens its root from docs/prompts
+to docs, adds plans and an index, and leaves the prompts where they are. The
+preview counts the existing Markdown under docs/ that planning starts checking.
+--docs-root cannot choose another folder there.
+Fresh setup carries runlist prompts and plans (including archives, and prompts an
+older runlist left in a root prompts/) into the new folders, fixing references
+and local handoff/ownership state. Foreign files stay put.
+Setup must finish transaction recovery before writing the first config; unresolved
+transactions stay Outstanding. Inspect them with runlist doctor --transactions.
+Untracked does not mean ignored: git add -A may include prompts and runtime state.
+Setup lists a missing persistent CLI on PATH under Outstanding.
+JSON includes checks.host.persistentCliMissing only when true.
+Run \`npm install -g runlist\` before reloading.
+Setup reports pre-existing document issues and unfinished host integration;
+installed integration still needs a new/reloaded host session.`,
+
+  init: `runlist init [--prompt-tracking <untracked|tracked|local>] [--gitignore]
+
+Creates starter config and missing scaffold files; respects configured roots
+and index paths. Existing files are preserved. Existing Markdown can be
+inspected to pre-populate a new config; adoption hints identify untagged docs.
+
+New projects default to untracked prompts (recommended to reduce commit churn).
+Untracked does not mean ignored: git add -A can still include them. Existing
+configs keep their policy; use runlist config set promptTracking <value> to change it.
+No ignore files are edited by default; runtime state in .runlist/ and legacy
+.dotmd/ may also be staged by git add -A. --gitignore explicitly appends missing
+state rules and prompt rules (unless tracked). Preview with --dry-run.
+Host integration is separate: runlist install <claude|codex|opencode>.`,
+
+  config: `runlist config — inspect or change supported onboarding settings
+
+  runlist config show [--json]
+  runlist config get promptTracking [--json]
+  runlist config get root [--json]
+  runlist config get promptDirectory [--json]
+  runlist config set promptTracking <untracked|tracked|local> [--dry-run] [--json]
+
+Shows effective values and their sources: promptTracking, mode (plans, or
+handoffs when planning is off), root, docsRoots, index.path, archiveDir and
+promptDirectory. Resolved roots, index and prompt
+directory use absolute paths; root keeps its configured string or array.
+Only promptTracking is CLI-editable; other settings give manual config guidance.
+Inspection imports the trusted project's JavaScript config but invokes no hooks.
+untracked recommends leaving pending prompts out of commits and warns in guards;
+tracked allows prompt Git operations; local denies them (legacy default for
+existing configs without an explicit choice). A new project defaults to untracked.
+Untracked does not mean ignored; git add -A can include pending prompts.
+Writes preserve hooks and refuse symlinks, computed or ambiguous exports. Run setup first
+if no config exists. Changing policy never edits ignore files or Git state.`,
 
   plans: `runlist plans — list live plans (excludes archived by default)
 
@@ -1359,10 +1501,23 @@ 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
-  runlist baton --done [<plan-file>]         # after a plan handoff: confirm the plan was brought up to date
+  runlist baton --done [<plan-file>] --next-step "..."   # after a plan handoff: write next_step, confirm it
   The resume can also come from stdin (\`-\`, or a pipe) or --message "..." for one-liners.
   Baton prints the prompt name it saved, as its last line too, and, in plan mode, the git commit to run.
 
+No setup needed: in a Git repository with no runlist config, the first saved
+prompt also creates a handoffs-only runlist.config.mjs at the worktree root,
+with prompts in docs/prompts/ (planning stays off until \`runlist setup\`).
+Prompts an older runlist saved in a root prompts/ move to docs/prompts/ first,
+in one line of output (--dry-run lists the moves); a name collision there
+refuses the save and writes no config. Other files in prompts/ stay put.
+Only type: prompt files in docs/prompts/ are runlist's: plan views and reads
+filtered to another --type say planning is off; plan actions and files outside
+that folder refuse with the same line. Outside a Git working tree
+baton refuses. Plans and prompts saved before any config elsewhere in the
+repository stay where they are; the planning-off line counts the ones
+\`runlist setup\` brings in.
+
 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.
 
@@ -1376,6 +1531,8 @@ Options:
   --template             Print a resume draft (or --subagent draft), using saved Markdown settings
   --replace              Replace exactly one pending handoff; archive its prior text
   --done                 Report a plan handoff done once next_step changed after the prompt was saved
+  --next-step "..."      With --done: write the plan's next_step (one line; must differ from the saved one)
+  --current-state "..."  With --done: also write current_state (never counts as done on its own)
   --json                 Structured repository/session/generated file result
   --dry-run, -n          Preview without writing
 
@@ -1395,23 +1552,31 @@ Examples:
   runlist baton docs/plans/auth.md @/tmp/draft.md
   runlist baton docs/plans/auth.md @/tmp/new-draft.md --replace
   runlist baton --status paused --note "blocked on review" @/tmp/d.md
+  runlist baton --done --next-step "wire the retry path" --current-state "parser merged"
   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
+     consuming it re-claims the plan (see \`runlist use\`). 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.
+     guidance for the plan. Prompts stay out of this generated pathspec; use
+     \`runlist config get promptTracking\` for the project's prompt Git policy.
+     Ownership records are local runtime state.
   4. When the plan was in-session and has a next_step field, the handoff is not
-     done yet: bring the plan up to date (the body, then next_step), then run
-     \`runlist baton --done\`, which refuses while next_step still reads as it
-     did when the prompt was saved. The prompt is saved first, so a stop between
-     the two steps loses nothing, and \`--done <plan-file>\` works from any session.
+     done yet: update the plan body first, then run
+     \`runlist baton --done --next-step "<next move>"\` (plus
+     \`--current-state "..."\` if that changed). It writes the frontmatter,
+     creating a missing key, and refuses a next_step that still reads as it did
+     when the prompt was saved. The prompt is saved first, so a stop between the
+     two steps loses nothing, and \`--done <plan-file>\` works from any session.
+     \`--dry-run\` with --next-step previews the write and removes nothing.
+     The fields go only to the plan at the path the handoff was saved for. If
+     it moved, update it where it is now and run \`--done <new-path>\`, or clear
+     the handoff with \`--done <old-path>\`.
   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
@@ -1602,6 +1767,7 @@ heading matches case-insensitively: exact first, then as a prefix, then as a
 substring; other matches are named. A section read stops at 500 lines or
 60 KB and prints the command that continues it. Headings and boxes inside code
 fences are ignored. Several files at once get a shorter outline each.
+There is no --lines option; continue with --section "<heading>" --from <line>.
 
 A phase heading shows its own boxes as [done/total], → marks the active phase
 (the one \`use\` would point at), and a marker its boxes contradict is named
@@ -1849,6 +2015,7 @@ function splitGlobalArgs(args) {
   let explicitConfig = null;
   let rootArg = null;
   let typeArg = null;
+  const typeArgs = [];
   let dryRun = false;
   let verbose = false;
 
@@ -1863,7 +2030,7 @@ function splitGlobalArgs(args) {
       if (local) rest.push(arg, next);
       else if (arg === '--config') explicitConfig = next;
       else if (arg === '--root') rootArg = next;
-      else typeArg = next;
+      else { typeArg = next; typeArgs.push(next); }
       i += 1;
       continue;
     }
@@ -1876,7 +2043,49 @@ function splitGlobalArgs(args) {
     rest.push(arg);
   }
 
-  return { command, rest, explicitConfig, rootArg, typeArg, dryRun, verbose };
+  return { command, rest, explicitConfig, rootArg, typeArg, typeArgs, dryRun, verbose };
+}
+
+// Every value given for `option`, as `--type x` or `--type=x`.
+function optionValues(args, option) {
+  const values = [];
+  for (let i = 0; i < args.length; i += 1) {
+    if (args[i] === option && args[i + 1] !== undefined) values.push(args[++i]);
+    else if (args[i].startsWith(`${option}=`)) values.push(args[i].slice(option.length + 1));
+  }
+  return values;
+}
+
+// Where planning is off, the briefing views end with the planning-off line.
+async function writePlanningOffLine(config) {
+  const { planningOffLine } = await import('../src/handoffs-scope.mjs');
+  const { documentsWaitingForSetup } = await import('../src/setup-waiting.mjs');
+  process.stdout.write(`${planningOffLine(await documentsWaitingForSetup(config))}\n`);
+}
+
+// A type a command takes as a positional argument rather than --type, which
+// the planning gate reads like one: `statuses migrate <type>` and the new
+// value of `migrate type <old> <new>`.
+function positionalTypeSelector(command, args) {
+  const positional = args.filter(arg => !arg.startsWith('-'));
+  if (command === 'statuses' && positional[0] === 'migrate' && positional[1]) return { type: positional[1], spelling: `statuses migrate ${positional[1]}` };
+  if (command === 'migrate' && positional[0] === 'type' && positional[2]) return { type: positional[2], spelling: `migrate type ${positional[1]} ${positional[2]}` };
+  return null;
+}
+
+// The verbs that can change a document, for the carry that runs before them
+// in a repository with no config (src/handoffs-mode.mjs carryBeforeChange).
+const DOCUMENT_CHANGES = new Set(['use', 'next', 'archive', 'set', 'status', 'bulk', 'bulk-tag', 'touch', 'rename', 'migrate', 'fix-refs', 'sync-status', 'fix-membership', 'record', 'decision']);
+function changesDocuments(command, args) {
+  if (DOCUMENT_CHANGES.has(command)) return true;
+  if (command === 'prompts') return ['use', 'resume', 'next', 'archive', 'link', 'hold', 'shelve', 'unhold', 'unshelve'].includes(args[0]);
+  if (command === 'runlist' || command === 'roadmap') return args.some(arg => ['next', 'add', 'remove', 'reorder'].includes(arg));
+  if (command === 'yardstick') return ['mark', 'close', 'fold', 'clear'].includes(args[0]);
+  if (command === 'lint' || command === 'check') return args.includes('--fix');
+  // Not the transaction, claim and session tools: they are how a stuck move or
+  // claim is resolved, so nothing may run ahead of them.
+  if (command === 'doctor') return (args.includes('--apply') || args.includes('--yes')) && !args.some(arg => ['--transactions', '--claims', '--session'].includes(arg));
+  return false;
 }
 
 async function main() {
@@ -1891,7 +2100,7 @@ async function main() {
   // Before-command options are global. After the command, a schema-declared
   // local option wins; otherwise the historical anywhere-global form remains.
   const parsed = splitGlobalArgs(args);
-  let { command, explicitConfig, rootArg, typeArg, dryRun, verbose } = parsed;
+  let { command, explicitConfig, rootArg, typeArg, typeArgs, dryRun, verbose } = parsed;
   let restArgs = parsed.rest;
   const captureHelpConfig = async topic => {
     _resolvedCommand = 'help';
@@ -1947,12 +2156,48 @@ async function main() {
     }
   }
 
+  // One help renderer for `runlist help <cmd>` and `runlist <cmd> --help`, so
+  // both spellings say the same thing, including where planning is off.
+  const renderCommandHelp = async (name, helpArgs) => {
+    if (_resolvedConfig?.mode === 'handoffs') {
+      if (commandPlanning(name, helpArgs)) {
+        const { planningOffLine } = await import('../src/handoffs-scope.mjs');
+        const { documentsWaitingForSetup } = await import('../src/setup-waiting.mjs');
+        return `${planningOffLine(await documentsWaitingForSetup(_resolvedConfig))}\n`;
+      }
+      const { handoffsCommandHelp } = await import('../src/handoffs-help.mjs');
+      const text = handoffsCommandHelp(name);
+      if (text) return `${text}\n`;
+    }
+    const focused = focusedCommandHelp(name, helpArgs);
+    let text = focused?.fallback ? `No focused help for this request; showing complete \`runlist ${name} --help\`.\n\n` : '';
+    text += `${focused?.text ?? HELP[name] ?? commandUsage(name)}\n`;
+    if (name === 'new' && !focused?.text) {
+      // Best effort: outside a runlist repo, or with a broken config, the
+      // static help above is the whole answer.
+      try {
+        const repoConfig = _resolvedConfig;
+        if (repoConfig?.configFound !== false) {
+          const { newHelpForRepo } = await import('../src/new.mjs');
+          text += `\n${newHelpForRepo(repoConfig)}\n`;
+        }
+      } catch { /* static help already printed */ }
+    }
+    return text;
+  };
+
   if (command === 'help' || command === '--help' || command === '-h') {
     const topic = restArgs[0];
-    await captureHelpConfig(topic ? (HELP[topic] || HELP[`help:${topic}`] ? topic : '(unknown)') : '_main');
+    const topicCommand = topic && commandDefinition(topic) && !HELP[`help:${topic}`] ? commandDefinition(topic).name : null;
+    await captureHelpConfig(topic ? (HELP[topic] || HELP[`help:${topic}`] || topicCommand ? topic : '(unknown)') : '_main');
+    if (_resolvedConfig?.mode === 'handoffs' && (!topic || topic === 'all' || topic === 'statuses')) {
+      process.stdout.write(`${topic === 'statuses' ? HANDOFFS_STATUS_HELP : HANDOFFS_HELP}\n`);
+      return;
+    }
     if (topic) {
       const key = `help:${topic}`;
       if (HELP[key]) { process.stdout.write(`${HELP[key]}\n`); return; }
+      if (topicCommand) { process.stdout.write(await renderCommandHelp(topicCommand, [])); return; }
       if (HELP[topic]) { process.stdout.write(`${HELP[topic]}\n`); return; }
       process.stderr.write(`Unknown help topic: ${topic}\n\nAvailable topics: all, statuses\nPer-command help: runlist <cmd> --help\n`);
       process.exitCode = 1;
@@ -1972,30 +2217,23 @@ async function main() {
   );
   const doctorExplicitApply = args.includes('--apply') || args.includes('--yes');
   const effectiveDryRun = dryRun || (command === 'doctor' && !doctorSubMode && !doctorExplicitApply);
-  const passiveMachineContext = command === 'agent-context'
+  const passiveMachineContext = command === 'agent-context' || command === 'config' || command === 'setup'
     || (command === 'context' && args.includes('--json') && args.includes('--compact'));
   // Git/frontmatter drift is validation work, not index construction. Keep the
   // bounded history scan on commands that report or repair that drift; ordinary
   // reads still run schema/reference validation without walking 10k commits.
   const gitStaleness = command === 'check' || command === 'doctor';
   _suppressObservability = effectiveDryRun || command === 'hud' || passiveMachineContext;
+  const hostDiagnostics = command === 'doctor' && restArgs.includes('--hosts');
+  const updateInspection = command === 'update' && restArgs.includes('--check');
+  if (hostDiagnostics || updateInspection) _suppressObservability = true;
 
   // Per-command help
   if (args.includes('--help') || args.includes('-h')) {
     requireCommandPolicy(command, dispatchPolicy);
-    await captureHelpConfig(command);
-    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 = _resolvedConfig;
-        if (repoConfig?.configFound !== false) {
-          const { newHelpForRepo } = await import('../src/new.mjs');
-          process.stdout.write(`\n${newHelpForRepo(repoConfig)}\n`);
-        }
-      } catch { /* static help already printed */ }
-    }
+    if (!hostDiagnostics && !updateInspection) await captureHelpConfig(command);
+    const helpArgs = restArgs.filter(arg => arg !== '--help' && arg !== '-h');
+    process.stdout.write(await renderCommandHelp(command, _resolvedConfig?.mode === 'handoffs' ? helpArgs : restArgs));
     return;
   }
 
@@ -2007,6 +2245,37 @@ async function main() {
     return;
   }
 
+  // Host diagnostics must work before project setup and with a broken project
+  // config. This branch deliberately imports no project JavaScript and runs no
+  // state migration or document sweep. Only selected repairs can write.
+  if (command === 'doctor' && restArgs.includes('--hosts')) {
+    requireCommandPolicy(command, dispatchPolicy);
+    try { restArgs = validateCommandArgs(command, restArgs); } catch (err) { die(err.message); }
+    const { runDoctorHosts } = await import('../src/doctor-hosts.mjs');
+    await runDoctorHosts(restArgs, { repoRoot: process.cwd() }, { dryRun });
+    return;
+  }
+
+  if (command === 'update') {
+    requireCommandPolicy(command, dispatchPolicy);
+    try { restArgs = validateCommandArgs(command, restArgs); } catch (err) { die(err.message); }
+    const { runUpdate } = await import('../src/update.mjs');
+    await runUpdate(restArgs, { repoRoot: process.cwd() }, { dryRun });
+    return;
+  }
+
+  if (command === 'install') {
+    requireCommandPolicy(command, dispatchPolicy);
+    try { restArgs = validateCommandArgs(command, restArgs); } catch (err) { die(err.message); }
+    const { runInstall } = await import('../src/install.mjs');
+    await runInstall(restArgs, { repoRoot: process.cwd() }, { dryRun });
+    return;
+  }
+
+  if (command === 'doctor' && restArgs.some(arg => ['--repair', '--claude-config', '--claude-bin'].includes(arg))) {
+    die('Host repair and Claude selectors require runlist doctor --hosts.');
+  }
+
   if (command === 'baton' && restArgs.includes('--template')) {
     _suppressObservability = true;
     requireCommandPolicy(command, dispatchPolicy);
@@ -2049,7 +2318,7 @@ async function main() {
   // nags. `install`/`doctor`/`update` are skipped: they report this themselves,
   // and telling `runlist install opencode` to run `runlist install opencode` is
   // noise.
-  if (!['install', 'doctor', 'update', 'hud', 'guard'].includes(command)) {
+  if (!['install', 'doctor', 'update', 'hud', 'guard', 'setup', 'config'].includes(command)) {
     const { degradedIdentityNotice } = await import('../src/host-integration.mjs');
     const notice = degradedIdentityNotice(config?.repoRoot, { version: pkg.version });
     if (notice) process.stderr.write(`${notice}\n`);
@@ -2060,7 +2329,9 @@ async function main() {
     value: { dryRun, passive: command === 'hud' || passiveMachineContext, suppressSideEffects, gitStaleness },
     enumerable: false,
   });
-  if (!suppressSideEffects) {
+  // Init owns scaffolding and validates policy before writing. Do not migrate
+  // legacy state ahead of that validation (including a refused init request).
+  if (!suppressSideEffects && command !== 'init') {
     const { migrateStateDirectory } = await import('../src/state-migration.mjs');
     const { LEGACY_STATE_DIR, STATE_DIR } = await import('../src/naming.mjs');
     const migration = migrateStateDirectory(config.repoRoot);
@@ -2075,17 +2346,89 @@ async function main() {
   // present in the centralized command policy registry.
   if (!config.presets[command]) requireCommandPolicy(command, dispatchPolicy);
 
+  // Handoffs-only projects (src/handoffs-mode.mjs) have no plans or docs. A
+  // command the registry marks as needing planning, or any command whose
+  // arguments ask for a type other than prompts, says planning is off and
+  // names the command that turns it on. The arguments are read as the command
+  // will run them: a preset's own arguments included, every --type counted
+  // (repeated, comma-separated, or --type=x), and the positional type a
+  // command takes (`statuses migrate <type>`, `migrate type <old> <new>`).
+  // This runs before argument validation so `runlist runlist` with no hub
+  // gets the same answer.
+  if (config.mode === 'handoffs') {
+    const { requirePlanning } = await import('../src/handoffs-scope.mjs');
+    const preset = config.presets[command];
+    const effective = [...(preset ?? []), ...restArgs];
+    const json = effective.includes('--json');
+    const types = [...typeArgs, ...optionValues(effective, '--type')].flatMap(value => value.split(',')).map(type => type.trim()).filter(Boolean);
+    const others = types.filter(type => type !== 'prompt');
+    const positionalType = preset ? null : positionalTypeSelector(command, restArgs);
+    const planning = commandPlanning(command, restArgs);
+    const typed = !planning && others.length > 0;
+    const selected = !planning && !typed && positionalType && positionalType.type !== 'prompt';
+    const requirement = planning?.requirement ?? (typed ? (preset || commandPolicy(command)?.mutation === 'none' ? 'view' : 'action') : selected ? 'action' : null);
+    if (requirement) {
+      for (const w of config.configWarnings ?? []) warn(w);
+      const what = selected ? `\`runlist ${positionalType.spelling}\``
+        : `\`runlist ${[command, planning?.subcommand].filter(Boolean).join(' ')}${typed ? ` --type ${others.join(',')}` : ''}\``;
+      const { documentsWaitingForSetup } = await import('../src/setup-waiting.mjs');
+      if (requirePlanning(config, what, requirement, { json, waiting: await documentsWaitingForSetup(config) })) return;
+    }
+  }
+
   try {
     restArgs = validateCommandArgs(command, restArgs, { preset: Boolean(config.presets[command]) });
   } catch (err) {
     die(err.message);
   }
 
+  // Before any config, prompts an older runlist saved in the root prompts/
+  // move to docs/prompts/ ahead of a command that changes documents
+  // (src/handoffs-mode.mjs), so none is consumed, archived or rewritten where
+  // runlist no longer writes. A file argument naming a moved prompt follows it.
+  if (!config.configFound && changesDocuments(command, restArgs)) {
+    const { carryBeforeChange } = await import('../src/handoffs-mode.mjs');
+    const carried = await carryBeforeChange(config, { dryRun: effectiveDryRun });
+    if (carried?.preview) {
+      process.stderr.write(`[dry-run] \`runlist ${command}\` then runs on the moved prompts; nothing else is previewed until they have moved.\n`);
+      return;
+    }
+    if (carried) {
+      restArgs = restArgs.map(arg => {
+        const move = carried.moves.find(item => [process.cwd(), config.repoRoot].some(base => path.resolve(base, arg) === item.source));
+        return move ? move.target : arg;
+      });
+      // Run from a subfolder, the docs root is that subfolder, and the moved
+      // prompts are in docs/prompts/ at the project's top: the command reads
+      // them there.
+      if (path.resolve(config.docsRoot) !== path.resolve(config.repoRoot)) {
+        const execution = config._execution;
+        config = await resolveConfig(config.repoRoot);
+        Object.defineProperty(config, '_execution', { value: execution, enumerable: false });
+        _resolvedConfig = config;
+      }
+    }
+  }
+
   // Init — runInit re-resolves the config from disk internally (after any
   // starter-config write), so we don't need to pre-pass it.
   if (command === 'init') {
     const { runInit } = await import('../src/init.mjs');
-    await runInit(process.cwd(), config, { dryRun });
+    await runInit(process.cwd(), config, { dryRun, argv: restArgs });
+    return;
+  }
+
+  if (command === 'config') {
+    if (rootArg || typeArg) die('Config inspection does not use --root/--type query filters. Inspect root with runlist config get root; edit project layout manually.');
+    const { runConfig } = await import('../src/config-command.mjs');
+    await runConfig(restArgs, config, { dryRun });
+    return;
+  }
+
+  if (command === 'setup') {
+    if (rootArg || typeArg) die('Setup does not use --root/--type query filters. Choose a fresh docs folder with --docs-root; existing configured roots are preserved.');
+    const { runSetup } = await import('../src/setup.mjs');
+    await runSetup(restArgs, config, { dryRun });
     return;
   }
 
@@ -2098,8 +2441,11 @@ async function main() {
   // runlist isn't used, so don't nag them about a missing config (they no-op
   // cleanly on their own). The warning is still useful for interactive commands.
   const HOOK_COMMANDS = new Set(['hud', 'guard']);
-  if (!config.configFound && command !== 'init' && !HOOK_COMMANDS.has(command)) {
-    warn('No runlist config found — using defaults. Run `runlist init` to create one.');
+  // A prompt saved here creates a handoffs-only config itself (src/handoffs-mode.mjs).
+  const savesPrompt = command === 'baton' || (command === 'new' && restArgs.find(a => !a.startsWith('-')) === 'prompt')
+    || (command === 'prompts' && restArgs[0] === 'new');
+  if (!config.configFound && command !== 'init' && !HOOK_COMMANDS.has(command) && !savesPrompt) {
+    warn('No runlist config found — using defaults. Run `runlist setup` to create one and carry over saved prompts and plans.');
   }
 
   if (config.configWarnings && config.configWarnings.length > 0) {
@@ -2226,7 +2572,7 @@ async function main() {
   // src/baton.mjs for why this is a single verb and not a skill choreography.
   if (command === 'baton') {
     const { runBaton } = await import('../src/baton.mjs');
-    await runBaton(restArgs, config, { dryRun });
+    await runBaton(restArgs, config, { dryRun, verbose });
     return;
   }
   // `runlist next` is a top-level alias for `runlist use` with no arg — consume
@@ -2289,9 +2635,11 @@ async function main() {
   if (command === 'misuse') { const { runMisuse } = await import('../src/misuse-read.mjs'); runMisuse(restArgs, config); return; }
   if (command === 'journal') { const { runJournal } = await import('../src/journal-read.mjs'); runJournal(restArgs, config); return; }
   if (command === 'pickup' || command === 'unpickup' || command === 'release' || command === 'finish') {
+    if (config.mode === 'handoffs') die(`\`runlist ${command}\` was removed. Handoffs: \`runlist baton <slug> @<file>\` saves one, \`runlist use <name>\` resumes one, \`runlist prompts\` lists them.`);
     die(`\`runlist ${command}\` was removed — use the ownership-aware lifecycle verbs:\n  runlist use <file>          # atomically claim + mark in-session + print the plan\n  runlist set <status> <file> # transition and release ownership when leaving in-session\n  runlist archive <file>      # close out atomically`);
   }
   if (command === 'runlist') { const { runRunlist } = await import('../src/runlist.mjs'); await runRunlist(restArgs, config, { dryRun }); return; }
+  if (command === 'handoff' && config.mode === 'handoffs') die('`runlist handoff` was removed. Handoffs: `runlist baton <slug> @<file>` saves one, `runlist use <name>` resumes one, `runlist prompts` lists them.');
   if (command === 'handoff') { die('`runlist handoff` was removed in 0.31.0. Use `runlist prompts new <name>` to create a saved prompt instead. The .dotmd/handoffs/ sidecar mechanism no longer exists; see CHANGELOG.'); }
   if (command === 'status') { const { runStatus } = await import('../src/lifecycle.mjs'); await runStatus(restArgs, config, { dryRun }); return; }
   if (command === 'set') { const { runSet } = await import('../src/lifecycle.mjs'); await runSet(restArgs, config, { dryRun }); return; }
@@ -2529,6 +2877,7 @@ async function main() {
 
   if (command === 'index') {
     if (!config.indexPath) {
+      if (config.mode === 'handoffs') die('There is no generated index: planning is off in this project. `runlist setup` turns planning on and adds one (your prompts stay where they are).');
       die('Index generation is not configured. Add an `index` section to your runlist.config.mjs.');
     }
     const print = args.includes('--print');
@@ -2625,6 +2974,7 @@ async function main() {
       }, null, 2) + '\n');
     } else {
       process.stdout.write(renderBriefing(index, config));
+      if (config.mode === 'handoffs') await writePlanningOffLine(config);
     }
     return;
   }
@@ -2696,6 +3046,7 @@ async function main() {
       return;
     }
     process.stdout.write(renderContext(index, config, { summarize, model }));
+    if (config.mode === 'handoffs') await writePlanningOffLine(config);
     return;
   }