runlist 0.99.2 → 0.100.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runlist",
-  "version": "0.99.2",
+  "version": "0.100.0",
   "description": "CLI for managing markdown documents with YAML frontmatter — index, query, validate, graph, export, lifecycle, and AI summaries.",
   "type": "module",
   "license": "MIT",
@@ -17,6 +17,7 @@
     "src/",
     "assets/",
     "plugins/runlist-codex/",
+    "GETTING_STARTED.md",
     "scripts/postinstall.mjs",
     "runlist.config.example.mjs"
   ],
@@ -42,6 +43,7 @@
   },
   "homepage": "https://github.com/reowens/runlist#readme",
   "scripts": {
+    "check:linux": "node scripts/check-linux-docker.mjs",
     "check:public": "node scripts/check-public.mjs",
     "prepack": "node scripts/check-public.mjs",
     "test": "node --import ./test/setup-env.mjs --test --test-concurrency=4 test/*.test.mjs",

package/plugins/runlist-codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "runlist-codex",
-  "version": "0.99.2",
+  "version": "0.100.0",
   "description": "Runlist workflow skill, session orientation, and tool guard for Codex",
   "author": {
     "name": "Reo Owens"

package/plugins/runlist-codex/bin/consume-prompt.mjs

@@ -0,0 +1,45 @@
+import { readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+function block(reason) {
+  process.stdout.write(JSON.stringify({ decision: 'block', reason }) + '\n');
+}
+
+let request;
+try { request = JSON.parse(readFileSync(0, 'utf8')); }
+catch { process.exit(0); }
+
+if (request.hook_event_name !== 'UserPromptSubmit' || typeof request.prompt !== 'string') process.exit(0);
+// T3 adds this role header to its delegated task's user message.
+const prompt = request.prompt.replace(/^Act as the (?:implementation|research|review|design|test|general) sub-agent for this task\.\r?\n\r?\n/, '');
+const match = /^\s*consume[ \t]+([A-Za-z0-9_.\/\\][A-Za-z0-9_.\/\\:-]*)[ \t]*$/i.exec(prompt);
+if (!match) process.exit(0);
+
+if (typeof request.session_id !== 'string' || !request.session_id.trim()
+  || typeof request.cwd !== 'string' || !path.isAbsolute(request.cwd)) {
+  block('Runlist needs the native session_id and absolute cwd to consume the requested handoff.');
+  process.exit(0);
+}
+
+const wrapper = fileURLToPath(new URL('./runlist-hook', import.meta.url));
+const result = spawnSync('sh', [wrapper, 'prompts', 'use', match[1]], {
+  cwd: request.cwd,
+  env: { ...process.env, RUNLIST_SESSION_ID: request.session_id },
+  encoding: 'utf8', timeout: 12_000, maxBuffer: 4 * 1024 * 1024,
+});
+
+if (result.error || result.status !== 0 || !result.stdout?.trim()) {
+  const detail = result.error?.message || result.stderr?.trim() || 'No consumed handoff was returned; check that runlist is on PATH.';
+  block(`Runlist could not consume ${match[1]}: ${detail.slice(0, 2000)}`);
+  process.exit(0);
+}
+
+process.stdout.write(JSON.stringify({
+  hookSpecificOutput: {
+    hookEventName: 'UserPromptSubmit',
+    additionalContext: 'Runlist has already consumed the saved prompt requested by the user for this native session. Continue from the handoff below without consuming it again.\n\n'
+      + result.stdout + (result.stderr ? '\nRunlist receipt:\n' + result.stderr : ''),
+  },
+}) + '\n');

package/plugins/runlist-codex/bin/runlist-hook

@@ -1,23 +1,31 @@
 #!/bin/sh
-# runlist Codex plugin hook wrapper.
+# runlist compatibility plugin hook wrapper.
 #
 # The plugin's hooks drive the whole workflow through the PATH `runlist` binary
 # (`runlist hud`, `runlist guard`), falling back to the legacy `runlist` alias. If a user enables the plugin but hasn't run
-# `npm i -g runlist`, the binary is missing, the hook errors `command not
+# `npm install -g runlist`, the binary is missing, the hook errors `command not
 # found`, and the session is primed with *silent nothing* — no signal that the
 # whole workflow is one install away. runlist can't warn about its own absence
 # (it's the thing that's missing), so the check lives here, outside the binary.
 #
 # Usage: runlist-hook [--hint] <runlist-subcommand> [args...]
-#   --hint  emit a one-line install hint to stdout when no CLI is on PATH.
+#   --hint  emit a short install hint to stdout when no CLI is on PATH.
 #           Only SessionStart passes this, so the hint surfaces once per hook
 #           invocation (stdout becomes session context), never on a tool call.
 #
 # When the CLI is missing we always exit 0 with no further output: hooks must
 # stay non-blocking, and the PreToolUse guard in particular must never deny a
 # tool just because the optional CLI isn't installed.
+# Keep the published hook command stable for hosts caching its definition.
+# Without node on PATH the JSON adapter cannot start; fall through to the
+# plain-text hint below rather than exiting 127.
+if [ "${1:-}" = "--hint" ] && [ "${2:-}" = "hud" ] && command -v node >/dev/null 2>&1; then
+  exec node "$(dirname "$0")/session-start.mjs"
+fi
+
 hint=0
-if [ "$1" = "--hint" ]; then
+# --hint-text is the JSON adapter's internal call back into this wrapper.
+if [ "$1" = "--hint" ] || [ "$1" = "--hint-text" ]; then
   hint=1
   shift
 fi
@@ -28,13 +36,18 @@ elif command -v dotmd >/dev/null 2>&1; then
   CLI=dotmd
 else
   if [ "$hint" = "1" ]; then
-    echo "runlist plugin: neither \`runlist\` nor \`dotmd\` is on PATH, so its hooks are no-ops. Enable the workflow with: npm i -g runlist"
+    # Pure shell on purpose (this is the no-CLI path). Say which PATH was searched so the
+    # reader can compare it with their terminal's. printf, not echo: some shells' echo
+    # interprets backslash sequences in $PATH.
+    searched=$(printf '%.200s' "$PATH")
+    [ "${#PATH}" -gt 200 ] && searched="$searched..."
+    printf '%s\n' "runlist plugin: neither runlist nor dotmd was found on the PATH this app sees, so its hooks are doing nothing here. PATH searched: $searched"
+    printf '%s\n' 'Not installed yet? Run `npm install -g runlist`, then fully quit and reopen the app. Installed already? In a terminal compare `command -v runlist` and `echo $PATH` with the PATH above. If the folder holding runlist is missing here, add it, then fully quit and reopen the app: on macOS/Linux `npm prefix -g` plus /bin, in your shell profile; on Windows the `npm prefix -g` folder itself, in your user environment variables.'
   fi
   exit 0
 fi
 
-# PreToolUse fast path: the guard fires on matched Bash, apply_patch, and MCP
-# read calls, and
+# PreToolUse fast path: the guard fires on matched tool calls, and
 # a full Node boot (~100ms: CLI startup + config discovery) is pure overhead for
 # the vast majority of payloads no guard rule can possibly match. Every rule
 # needs a `.md` path AND either a prompts/ path (commit/cat/read-prompt) or the
@@ -68,14 +81,19 @@ if [ "$1" = "guard" ]; then
   exit 0
 fi
 
-# UserPromptSubmit fast path is retained for compatibility with the Claude
-# wrapper; Codex does not register that hook here. It would fire on every
-# message that asks for a handoff gets an answer. The glob is strictly weaker
+# UserPromptSubmit hints: Claude Code runs this on every user message;
+# Codex handles explicit consumption in consume-prompt.mjs. Only a handoff or
+# pickup request gets an answer. The glob is strictly weaker
 # than the Node-side match, so a skipped payload could never have matched.
 if [ "$1" = "hud" ] && [ "$2" = "--prompt-submit" ]; then
+  # Time/session markers gate the new forms; save/continue alone stay cheap.
+  # Keep next/last time and context-tight forms too, not just session/tomorrow.
+  # Never match bare session: every payload carries session_id. The other
+  # markers must not match cwd/transcript_path or ordinary words such as
+  # somewhere, holiday, collateral, and timeout.
   payload=$(cat)
   case "$payload" in
-    *[Bb][Aa][Tt][Oo][Nn]*|*[Hh][Aa][Nn][Dd]*[Oo][Ff][Ff]*|*[Rr][Ee][Ss][Uu][Mm][Ee]*|*[Pp][Ii][Cc][Kk]*[Uu][Pp]*)
+    *[Bb][Aa][Tt][Oo][Nn]*|*[Hh][Aa][Nn][Dd]*[Oo][Ff][Ff]*|*[Rr][Ee][Ss][Uu][Mm][Ee]*|*[Pp][Ii][Cc][Kk]*[Uu][Pp]*|*\ [Ll][Aa][Tt][Ee][Rr][!a-zA-Z0-9_]*|*[Tt][Oo][Mm][Oo][Rr][Rr][Oo][Ww]*|*[Tt][Oo][Dd][Aa][Yy]*|*[Yy][Ee][Ss][Tt][Ee][Rr][Dd][Aa][Yy]*|*[Ff][Oo][Rr]*[Nn][Oo][Ww]*|*[Nn][Ee][Xx][Tt]*[Ss][Ee][Ss][Ss][Ii][Oo][Nn]*|*[Nn][Ee][Ww]*[Ss][Ee][Ss][Ss][Ii][Oo][Nn]*|*[Ll][Aa][Ss][Tt]*[Ss][Ee][Ss][Ss][Ii][Oo][Nn]*|*[Nn][Ee][Xx][Tt]\ [Tt][Ii][Mm][Ee][!a-zA-Z0-9_]*|*[Ll][Aa][Ss][Tt]*[Tt][Ii][Mm][Ee]*|*[Cc][Oo][Nn][Tt][Ee][Xx][Tt]*[Tt][Ii][Gg][Hh][Tt]*|*[Ww][Hh][Ee][Rr][Ee]\ [WwIiYy]*|*\ [Dd][Aa][Yy]*|*[Tt][Oo][Nn][Ii][Gg][Hh][Tt]*)
       printf '%s' "$payload" | "$CLI" "$@"
       exit 0
       ;;

package/plugins/runlist-codex/bin/session-start.mjs

@@ -0,0 +1,16 @@
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const wrapper = fileURLToPath(new URL('./runlist-hook', import.meta.url));
+const result = spawnSync('sh', [wrapper, '--hint-text', 'hud'], {
+  encoding: 'utf8', timeout: 4_000, maxBuffer: 1024 * 1024,
+});
+const context = result.error || result.status !== 0
+  ? `Runlist session orientation failed: ${result.error?.message || result.stderr?.trim() || `exit ${result.status}`}`
+  : result.stdout.trim();
+
+if (context) {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: context },
+  }) + '\n');
+}

package/plugins/runlist-codex/bin/subagent-start.mjs

@@ -0,0 +1,16 @@
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const wrapper = fileURLToPath(new URL('./runlist-hook', import.meta.url));
+const result = spawnSync('sh', [wrapper, 'hud', '--subagent'], {
+  encoding: 'utf8', timeout: 4_000, maxBuffer: 1024 * 1024,
+});
+const context = result.error || result.status !== 0
+  ? `Runlist child orientation failed: ${result.error?.message || result.stderr?.trim() || `exit ${result.status}`}`
+  : result.stdout.trim();
+
+if (context) {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: { hookEventName: 'SubagentStart', additionalContext: context },
+  }) + '\n');
+}

package/plugins/runlist-codex/hooks/hooks.json

@@ -1,11 +1,22 @@
 {
   "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [{ "type": "command", "command": "node \"${PLUGIN_ROOT}/bin/consume-prompt.mjs\"", "timeout": 15 }]
+      }
+    ],
     "SessionStart": [
       {
         "matcher": "startup|resume|clear|compact",
         "hooks": [{ "type": "command", "command": "sh \"${PLUGIN_ROOT}/bin/runlist-hook\" --hint hud", "timeout": 5 }]
       }
     ],
+    "SubagentStart": [
+      {
+        "matcher": "*",
+        "hooks": [{ "type": "command", "command": "node \"${PLUGIN_ROOT}/bin/subagent-start.mjs\"", "timeout": 5 }]
+      }
+    ],
     "PreToolUse": [
       {
         "matcher": "Bash|apply_patch|mcp__.*__(read_file|read_text_file|read_media_file|read_multiple_files)",

package/plugins/runlist-codex/skills/runlist/SKILL.md

@@ -1,29 +1,45 @@
 ---
 name: runlist
-description: Manage a repository's plans, docs, decisions, and saved prompts with the runlist CLI. Use when starting or closing plan work, checking the plan queue, or creating or consuming a handoff.
+description: Save and resume session handoffs, and manage a repository's plans, docs, decisions, and saved prompts with the runlist CLI. Use for explicit consume requests for saved prompts, creating or consuming a handoff, starting or closing plan work, or checking the plan queue.
 ---
 
 # Runlist workflow
 
-Use this skill in repositories with `runlist.config.mjs` or `dotmd.config.mjs`. The CLI is `runlist` (from the `runlist` package; `dotmd` remains an alias). The session hook prints a short live orientation. `CODEX_THREAD_ID` is the session identity used for plan claims; do not replace it with a process ID.
+For an explicit `consume <prompt>` request, run `runlist use <prompt>` before file discovery or other task commands. If the native request hook already supplied the consumed handoff, continue from that output without consuming it again. Report a consumption failure before starting the handoff's work.
 
-**Document model:** a hub organizes related plans and supporting docs. Older docs and filenames call hubs *runlists*; this is the same document, not another level below a hub. A hub can be a coordination map or hold ordered plans in its `runlist:` array. A roadmap is an optional hub collecting other hubs and rolling up progress, with direct plan children also supported. Hubs currently use `type: plan` with hub metadata. Stage describes when a plan should ship, while status describes progress; neither adds a document level. Existing `runlist` commands, fields and output labels remain unchanged. See the repository README's “Hubs, Ordered Plans, And Roadmaps” section for examples.
+For installing Runlist or turning on planning, use the **runlist-setup** skill.
+Handoffs need no setup. This skill covers ongoing work.
 
-**Optional filing policy:** with `export const filing = true` (or `{ categoryDepth: 3 }`), `check` warns on missing/multiple/uncategorized homes, while `coverage` lists direct/inherited homes and hub:line evidence. A home is a status-bearing table row whose first cell links the plan; mentions and order lists are references. A child without its own row can inherit a home through explicit `parent_plan:` ancestors. Categories come from headings or the containing hub's filing category. Scoping retains full evidence; incomplete scans suppress absence findings. Neither command assigns homes or repairs rows. Enable the policy or retire an older custom check only with repository authorization. Available in CLI 0.93.0.
+The CLI is `runlist` (from the `runlist` package; `dotmd` remains an alias). The session hook prints a short live orientation. `CODEX_THREAD_ID` is the session identity used for plan claims; do not replace it with a process ID.
+
+## Handoffs (every project)
+
+- Save where the session stands: write the resume to a temp file (next concrete move, decisions, gotchas, paths; not a recap). If this session owns an in-session plan, run `runlist baton @/tmp/draft.md` with no slug: it hands off that plan, saving its prompt and releasing the claim. Otherwise run `runlist baton <slug> @/tmp/draft.md`, picking a short slug that names the work yourself; it saves `resume-<slug>`. Report the name baton prints last. In a Git repository with no runlist config, this first baton also writes a handoffs-only `runlist.config.mjs` and keeps prompts in `docs/prompts/`, first moving any an older runlist saved in a root `prompts/`.
+- Resume: `runlist prompts` lists pending handoffs and `runlist use <name>` consumes one. With several pending, ask which; never consume the oldest by default.
+- Consume a saved prompt with `runlist use <prompt-file>` (or bare `runlist use` for the oldest). This archives the prompt (and, where planning is on, claims its linked plan) before printing the body. Only an agent session consumes; a plain terminal gets the body plus the `runlist prompts use <path>` line, and the prompt stays pending. A prompt that ends with that line is still pending: run the command first. For read-only triage, survey names with `runlist prompts`, then peek selected bodies with `runlist prompts show a b c`; use `show --all` only with `--limit N`. Never open pending prompts with a file reader or `cat`.
+- Before a second handoff for the same work, inspect the pending one with `runlist prompts show <file>`; keep it if current or pass `--replace` with the new draft. Replacement archives the old text and refreshes exactly one pending prompt.
+- Inspect `runlist config get promptTracking` before prompt Git operations: `untracked` recommends leaving pending prompts out of commits to reduce churn, `tracked` allows commits, `local` denies them (legacy default). Untracked is not ignored; `git add -A` can include prompts. `runlist config set promptTracking <value>` records an explicit choice without changing ignore files or Git state.
+- **Subagent handoffs:** return completed results to the parent. For unfinished work or an explicit saved handoff, use `runlist baton --subagent <task-slug> @/tmp/draft.md` to save `subagent-<task-slug>`. Under a parent-owned plan, choose a distinct task slug that does not resolve to a plan; do not release the parent's claim. A child owning a dedicated plan can use `runlist baton --subagent <plan-file> @/tmp/draft.md`. Add `--parent resume-<session-name>` to link the child beneath its parent in `rl prompts`; the parent may be saved later. Parent-session batons keep the default `resume-*` naming. Matching prefixes are kept once; conflicting prefixes are refused. Existing prompts keep their names, and `--subagent --replace` refuses a parent-prefixed prompt.
+- **Draft outlines:** `runlist baton --template` prints the resume outline. The Runlist desktop app's Templates editor (not Claude Desktop) saves resume/subagent outlines in `runlist.templates.json`; repository baton instructions still apply.
+- **Child draft:** `runlist baton --subagent --template --parent resume-<name>` prints the saved child outline (built-in: Task, State, Next, Evidence and Boundaries). Fill the draft; its `parent_prompt` travels on save. A launcher can pass `RUNLIST_PARENT_PROMPT` into the child environment instead. Keep full records at durable repo-relative paths with commits and checked results; temporary scratch paths are supplementary. Completed work is a result for the parent to record, not another restart. Repair old links without replacing text: `runlist prompts link <child...> --parent resume-<name>`. Showing or consuming a parent surfaces its pending children without consuming them.
+- If `runlist plans` says planning is off, the project uses runlist for handoffs only: skip the planning bullets below, create no plans or docs, and suggest `runlist setup` only when the user asks for planning.
+
+## Planning projects
+
+These apply where `runlist plans` shows a dashboard (a `runlist.config.mjs` or `dotmd.config.mjs` with planning on).
 
 - Orient with `runlist plans`. Use `runlist agent-context` for structured state; `runlist briefing` is the comprehensive view and can be large.
+- Create from a draft with `runlist new plan <slug> @/tmp/draft.md` or `runlist new doc <slug> @/tmp/draft.md`. Draft headings become the body; opening frontmatter supplies fields such as `current_state` and `next_step`, while the command fixes `type`.
 - Read a plan or long doc with `runlist show <file>` (card, outline and open boxes with line numbers, the active phase), then `runlist show <file> --section "<heading>"` one section at a time; never read a plan whole.
 - Start plan work with `runlist use <plan-file>`. It claims the plan, marks it `in-session`, and prints the card.
 - Change status with `runlist set <status> <file> [--note "why"]`; this runs validation, lifecycle hooks, ref repairs, and index updates. Never hand-edit a `status:` field.
 - Close a shipped plan with `runlist archive <file>`; use `partial`, `active`, `awaiting`, or `blocked` when those match the actual state. Valid statuses are repository and type specific: `runlist statuses list --type plan`.
-- For a handoff, write a concrete resume draft, then run `runlist baton [<plan-or-slug>] @<draft-file>`. An owned plan is released in the same operation. If a handoff for that work is pending, inspect it with `runlist prompts show <file>`; keep it if current or pass `--replace` with the new draft. Replacement archives the old text and refreshes exactly one pending prompt.
-- **Subagent handoffs:** use `runlist baton --subagent <task-slug> @/tmp/draft.md` to save `subagent-<task-slug>`. Under a parent-owned plan, choose a distinct task slug that does not resolve to a plan; do not release the parent's claim. A child owning a dedicated plan can use `runlist baton --subagent <plan-file> @/tmp/draft.md`. Add `--parent resume-<session-name>` to link the child beneath its parent in `rl prompts`; the parent may be saved later. Parent-session batons keep the default `resume-*` naming. Matching prefixes are kept once; conflicting prefixes are refused. Existing prompts keep their names, and `--subagent --replace` refuses a parent-prefixed prompt.
-- **Draft outlines:** `runlist baton --template` prints the resume outline. The desktop Templates editor saves resume/subagent outlines in `runlist.templates.json`; repository baton instructions still apply.
-- **Child draft:** `runlist baton --subagent --template --parent resume-<name>` prints the saved child outline (built-in: Task, State, Next, Evidence and Boundaries). Fill the draft; its `parent_prompt` travels on save. A launcher can pass `RUNLIST_PARENT_PROMPT` into the child environment instead. Keep full records at durable repo-relative paths with commits and checked results; temporary scratch paths are supplementary. Completed work is a result for the parent to record, not another restart. Repair old links without replacing text: `runlist prompts link <child...> --parent resume-<name>`. Showing or consuming a parent surfaces its pending children without consuming them.
-- Consume a saved prompt with `runlist use <prompt-file>` (or bare `runlist use` for the oldest). This archives and claims before printing the body. Only an agent session consumes; a plain terminal gets the body plus the `runlist prompts use <path>` line, and the prompt stays pending. A prompt that ends with that line is still pending: run the command first. For read-only triage, survey names with `runlist prompts`, then peek selected bodies with `runlist prompts show a b c`; use `show --all` only with `--limit N`. Never open pending prompts with a file reader or `cat`.
-- Pending prompts are session-local. Commit the tracked plan or source files named by baton, not `docs/prompts/*.md`.
-- Create a document with `runlist new <type> <name> @<draft-file>`. A draft starting with frontmatter can supply scaffold fields; `type` is fixed by the command.
+- For a plan handoff, `runlist baton @<draft-file>` releases the plan this session owns, and `runlist baton <plan-file> @<draft-file>` hands off a named one. If baton says `Handoff not done yet`, update the plan body, then run `runlist baton --done --next-step "<next move>"`. Baton prints a commit hint for the plan/source files only.
 - Record a decision with `runlist new decision <plan> --question "…" @<record-file>`; configured registers may also require `--answers`.
 - If a lifecycle mutation reports an abandoned transaction, inspect `runlist doctor --transactions` before retrying. Use `--apply` only for cases the doctor identifies as recoverable.
 
 The `PreToolUse` hook warns on direct pending-prompt reads and denies hand-edited status transitions or Git operations that would include a live prompt. A repo can opt into blocking direct reads of existing pending prompts with `guard: { promptReads: 'deny' }`. Archived prompts and `runlist prompts show` remain readable. Codex requires explicit trust of a plugin's hooks before they run.
+
+**Document model:** a hub organizes related plans and supporting docs. Older docs and filenames call hubs *runlists*; this is the same document, not another level below a hub. A hub can be a coordination map or hold ordered plans in its `runlist:` array. A roadmap is an optional hub collecting other hubs and rolling up progress, with direct plan children also supported. Hubs currently use `type: plan` with hub metadata. Stage describes when a plan should ship, while status describes progress; neither adds a document level. Existing `runlist` commands, fields and output labels remain unchanged. See the repository README's “Hubs, Ordered Plans, And Roadmaps” section for examples.
+
+**Optional filing policy:** with `export const filing = true` (or `{ categoryDepth: 3 }`), `check` warns on missing/multiple/uncategorized homes, while `coverage` lists direct/inherited homes and hub:line evidence. A home is a status-bearing table row whose first cell links the plan; mentions and order lists are references. A child without its own row can inherit a home through explicit `parent_plan:` ancestors. Categories come from headings or the containing hub's filing category. Scoping retains full evidence; incomplete scans suppress absence findings. Neither command assigns homes or repairs rows. Enable the policy or retire an older custom check only with repository authorization. Available in CLI 0.93.0.

package/plugins/runlist-codex/skills/runlist-setup/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: runlist-setup
+description: Set up Runlist planning in a project, including before any Runlist config exists or after handoffs-only use. Use when asked to install, initialize, onboard, turn on planning, or adopt existing project docs into Runlist. Use the runlist skill for ordinary plan, doc, and prompt work after setup.
+---
+
+# Runlist project setup
+
+Setup is for planning. Session handoffs need none: if the user only wants to
+save where they are and pick it up later, do not run setup; the first
+`runlist baton <slug> @<draft-file>` in a Git repository writes a handoffs-only
+`runlist.config.mjs` and keeps prompts in `docs/prompts/`. In a handoffs-only
+project (`runlist plans` says planning is off), setup turns planning on: it
+rewrites that config's `mode`, widens its `root` from `docs/prompts` to `docs`,
+adds plans and an index, and keeps the saved prompts where they are.
+
+Turn the user's requested choices into a reviewed `runlist setup` preview and
+apply the authorized changes. Ask only for missing preferences that affect the
+requested outcome; honor explicit choices and authorization already given.
+For "show me first" or preview-only requests, return the preview without applying.
+
+Inspect the actual shell, working directory, checkout, config, and executable
+paths first. In Bash/Zsh, `type -a runlist rl node npm claude codex opencode`
+reveals competing installations; use `Get-Command ... -All` in PowerShell.
+Resolve aliases, Node/npm scope, and the intended Claude binary when several
+copies exist. Do not install or update an agent host to resolve a path mismatch.
+For the Runlist CLI, use the executable selected by the current shell unless
+the user chose another; report its path. Several installed copies alone do not
+require a new user decision.
+
+With no suitable shell or checkout access, supply concrete terminal instructions
+and leave execution outstanding. Bootstrap the CLI with `npm install -g runlist`
+or the user's chosen project scope (`npm install -D runlist`, then
+`npx runlist setup`); `npx runlist setup` is also an ephemeral bootstrap. Host
+hooks still need a persistent CLI on their `PATH`. Execute installations only
+within the authorized scope. A plugin skill is unavailable before that
+plugin is installed and loaded; do not claim an unavailable skill was invoked.
+
+Claude Desktop Chat, Cowork, and Claude Code are different execution surfaces.
+Inspect the actual tools: Cowork may use a cloud sandbox or a local VM; Claude
+Code and Codex may run locally or remotely. Local-folder access alone does not
+prove the shell runs on the user's computer. A remote npm success affects that
+environment, not a local CLI, host, or GUI. This plugin provides no Desktop Chat
+execution bridge. If local setup is needed, give commands for a local terminal.
+
+Use `runlist setup` rather than rebuilding onboarding from unrelated verbs:
+
+- Preview with `runlist setup <explicit-options> --dry-run --json`; inspect the
+  proposed paths, policy, adoption, host install, and findings. With no `--yes`,
+  noninteractive setup previews without writing or waiting. An interactive
+  terminal collects choices and confirms the concrete preview. `--dry-run`
+  previews even when `--yes` is present.
+- Apply the same reviewed options with `--yes` when covered by the user's
+  authorization. Ask only about choices or side effects not already authorized;
+  do not impose another blanket confirmation. `--yes` applies explicit flags and
+  defaults; it does not license additional installations or repairs.
+- Fresh defaults: relative `docs/` root, `--prompt-tracking untracked`, no ignore
+  edits, `--host none`, no first plan, no adoption. `untracked` is not ignored:
+  `git add -A` can include prompts. Alternatives are `tracked` and `local`.
+  Preserve existing policy absent an explicit selection. `--gitignore` is opt-in.
+  Requests to leave prompts out of routine commits or reduce commit churn select
+  the `untracked` recommendation; use `local` for an explicit request to deny
+  prompt Git operations through agent guards. Neither policy makes files ignored
+  or prevents manual Git operations outside those guards.
+- A fresh project may choose `--docs-root <relative-path>`; a handoffs-only
+  project's docs root is always `docs`, so setup refuses another. Preserve existing
+  configured roots, JavaScript, and hooks. If a different existing root is
+  requested, explain setup's refusal and the manual config/path review needed;
+  do not replace the config or move docs to force success.
+- Adopt only user-selected files with repeatable `--adopt <path>`, previewing
+  their frontmatter changes before apply. Never blanket-tag existing docs.
+- Fresh setup, and setup turning planning on in a handoffs-only project,
+  carries runlist prompts and plans saved before configuration, including
+  archives, into the new folders by default. This finishes the
+  scaffold rather than tagging existing documents: only valid runlist
+  type/status files in the pre-config output folders qualify. Review each move;
+  references and local handoff/ownership state move with it. Foreign files and
+  destination collisions stay put and are reported. `--no-carry-prompts` opts
+  out for both prompts and plans. Other existing configured projects never carry over.
+- Create a first plan only when requested: `--first-plan <slug>` requires
+  meaningful, user-supplied `--current-state <text>` (cap 1,500 characters) and
+  `--next-step <text>` (cap 800). Ask for missing facts; never invent progress,
+  use placeholders, or disable validation. Keep longer detail in the plan body.
+  Derive the slug from the requested plan title. The user's stated current state
+  and next action are sufficient to preview that plan: save them as metadata.
+  Creating a plan does not authorize executing its next action or inspecting a
+  different checkout to prove the user's description. Include all requested
+  plan fields in the preview and in any later apply command.
+  For example, "first plan: text export; today only JSON works; next review the
+  exporter" becomes `--first-plan text-export --current-state 'Only JSON export
+  works' --next-step 'Review the exporter' --dry-run --json`. Those facts are
+  already supplied; do not ask for them again or start the export work.
+- Only explicit `--host claude|codex|opencode` plus apply authorizes the existing
+  integration installer. Host `none` is the default. Setup never downloads the
+  Runlist GUI. If requested separately, the supported Mac path is
+  `runlist desktop install`, then `runlist desktop`; respect the execution location.
+
+Report **completed**, **outstanding**, and **failed** separately, with paths and
+concrete next actions. Setup's **notes** are information, not remaining work;
+mention them without counting them as outstanding. Keep pre-existing untagged docs, unavailable tools, and
+host activation/trust/reload steps visible. Use `runlist check` and read-only
+`runlist doctor` findings as follow-up evidence; do not silently run broad
+repairs. CLI/plugin files present do not prove hooks or skills loaded in a
+running or future host session. Once configured, route ongoing work to the
+ordinary `runlist` workflow skill.
+
+Setup adoption also previews any missing project scaffold directories. A setup
+preview validates proposed changes; it does not run the whole-project check that
+apply runs. Existing document errors can therefore produce an `attention` result
+and exit 1 after the selected changes apply successfully.

package/runlist.config.example.mjs

@@ -7,6 +7,12 @@
 // Directory containing your markdown docs (relative to this config file)
 export const root = 'docs';
 
+// Pending prompt Git policy: untracked (recommended, guard warns), tracked
+// (guard allows), or local (guard denies). Untracked is not ignored: git add -A
+// can include prompts. Existing configs that omit this export preserve local.
+// No ignore files or Git state are changed by selecting a policy.
+export const promptTracking = 'untracked';
+
 // Optional owner-written product goal. Read its Markdown body beside a plan's
 // delivers: field with `runlist yardstick show <plan>` or on pickup cards.
 // Explicit mark/close/fold commands record owner choices; no fit is inferred.

package/src/agent-context.mjs

@@ -140,9 +140,12 @@ export function buildAgentContext(index, config, options = {}) {
     .sort(comparePromptDocs);
 
   const vocabulary = {};
+  // A handoffs-only project manages prompts alone; plan and doc statuses would
+  // only teach an agent verbs that refuse there.
+  const knownTypes = config.planning === false ? metadata.typeOrder.filter(type => type === 'prompt') : metadata.typeOrder;
   const vocabularyTypes = options.types?.length
-    ? metadata.typeOrder.filter(type => options.types.includes(type))
-    : metadata.typeOrder;
+    ? knownTypes.filter(type => options.types.includes(type))
+    : knownTypes;
   for (const type of vocabularyTypes) {
     vocabulary[type] = boundedCollection(
       (metadata.byType[type] ?? []).map(item => ({
@@ -170,6 +173,9 @@ export function buildAgentContext(index, config, options = {}) {
       types: options.types?.length ? [...options.types] : null,
       ...(options.sections ? { sections: [...sections] } : {}),
     },
+    // Handoffs-only projects have no plans to orient on; say so instead of
+    // leaving an agent to infer it from an empty plan vocabulary.
+    planning: config.planning !== false,
     statusVocabulary: vocabulary,
     counts: {
       documents: index.docs.length,