runlist 0.99.2 → 0.100.0

package/README.md

@@ -12,12 +12,120 @@ safe to mutate.
 - Runtime support for Linux, macOS, and Windows
 - Type-aware lifecycle rules for plans, docs, and saved prompts
 
+**New to Runlist? Start with the [beginner setup guide](GETTING_STARTED.md).**
+It covers the terminal, asking an assistant to set up a project, agent plugins,
+and the optional Runlist desktop app.
+
+## Handoffs in 3 steps
+
+The quickest way to get value from runlist: **save where you are, pick it up in
+a later session.** A saved handoff (runlist calls it a *baton*) is a short
+resume note kept in your project, so the next Claude session starts oriented
+instead of from a blank page. There is no setup step.
+
+1. **Install** (once, in a terminal):
+
+   ```bash
+   npm install -g runlist
+   claude plugin marketplace add reowens/runlist
+   claude plugin install runlist@runlist
+   ```
+
+   Terminal sessions, Claude Desktop's **Code** tab (local sessions) and VS Code
+   read the same plugin settings, so one install covers them all. Start a new
+   session afterwards, or run `/reload-plugins` in one that is already open.
+
+   The `claude` command comes with the Claude Code CLI
+   ([install it](https://code.claude.com/docs/en/setup)). If it is missing,
+   `runlist install claude` prints these same commands and where to get it. In
+   Claude Desktop, once the marketplace is registered, the **Code** tab → **+** →
+   **Add plugins** browser lists runlist too (not available in cloud or WSL
+   sessions).
+2. **Stop with a handoff.** In a Claude Code session in your project's Git
+   repository (terminal or Desktop's Code tab), say "baton" or "save where we
+   are", or type `/baton`. The first handoff in a project also writes a small
+   `runlist.config.mjs` and keeps handoffs in `docs/prompts/`.
+3. **Pick it up next time.** In a new session, type `/pickup` or say "pick up
+   where we left off".
+
+Planning is optional: when you want plans, docs and an index, run `runlist
+setup` in the project (see the [beginner setup guide](GETTING_STARTED.md)). It
+previews first, and your saved handoffs stay where they are.
+
+Outside a Git repository the first handoff refuses, since there is no project
+folder to put its config in (run `git init`, or `runlist setup` to configure
+the folder). It also refuses in a home directory that is itself a repository.
+A project that already has a runlist config works outside Git as before. In a
+handoffs-only project runlist manages only the prompts in `docs/prompts/`: any
+other Markdown there is left alone. Handoffs an older runlist saved in a root
+`prompts/` folder move to `docs/prompts/` with the first handoff (it prints one
+line saying so; `--dry-run` lists the moves), and anything else in `prompts/`
+stays where it is.
+
+### What baton-only mode does and doesn't do
+
+Until you run `runlist setup`, a project whose config the first handoff wrote
+uses runlist for handoffs only (its config says `mode: 'handoffs'`), and its
+handoffs live in `docs/prompts/`.
+
+What works:
+
+- Saving: say "baton" or "save where we are", or type `/baton`.
+- Picking up: `/pickup`, or `runlist use [<name>]` in a session, consumes a
+  handoff (archives it and prints it).
+- `runlist prompts` lists the saved handoffs; `runlist prompts show <name>`
+  reads one without consuming it.
+- `runlist check` checks the saved handoffs.
+
+What says planning is off (`Planning is off in this project; runlist setup
+turns it on`):
+
+- Plan views such as `runlist plans`, `health`, `runlists`, `roadmap`,
+  `modules` and `stale` print that line and exit successfully, as an empty
+  dashboard would. With `--json` they print `{ "planning": false, … }`.
+- Plan actions such as `runlist new plan`, `new doc`, `runlist runlist next`,
+  `roadmap next`, `sync-status` and `bulk-tag` refuse with it.
+- So does a command filtered to a type other than prompts (`--type plan`), and
+  a file argument outside the prompt folder (`runlist show docs/plans/x.md`).
+
+Other Markdown in the prompt folder is never listed, checked, searched or
+changed. `runlist flag add` still accepts any file in the repository.
+
+Plans an older runlist saved before there was a config don't stop the first
+handoff from setting this up: they stay where they are, and the planning-off
+line says how many `runlist setup` will bring in ("2 runlist documents saved
+before setup are waiting for it.").
+
+To turn planning on, run `runlist setup` in the project. It widens the
+config's root from `docs/prompts` to `docs` and previews first: the config
+before and after, and how many existing Markdown files under `docs/` planning
+will start checking. Your saved handoffs stay where they are, and plans saved
+before setup in `plans/` move to `docs/plans/`.
+
+If a session hook says it found neither `runlist` nor `dotmd` on its PATH, either
+runlist is not installed yet or the app is searching a different PATH than your
+terminal. In a terminal, compare `command -v runlist` and `echo $PATH` with the
+PATH the hook printed (on Windows, `where runlist`). If runlist is installed but
+its folder is missing from the hook's PATH, add that folder, then
+fully quit and reopen Claude Desktop. On macOS and Linux the folder is `npm prefix -g` plus
+`/bin`, and it goes in your shell profile. On Windows it is the `npm prefix -g`
+folder itself, and it goes in your user environment variables, because Claude
+Desktop does not read PowerShell profiles (see Anthropic's
+[Desktop troubleshooting](https://code.claude.com/docs/en/desktop#session-not-finding-installed-tools)).
+
+This quick path uses Claude Code (the Code tab in Claude Desktop, or a terminal)
+running on your own machine, because that is where the plugin's hooks and the
+local `runlist` command live. For what Chat, Cowork, Codex and remote sessions
+can run, see [Which assistant can run setup?](#which-assistant-can-run-setup).
+The separate Runlist desktop app is optional and comes after this path:
+`runlist desktop install` on a supported Mac.
+
 ## Install
 
 ```bash
-npm install -g runlist      # global CLI and agent-host hooks
+npm install -g runlist      # global CLI; choose agent integration separately
 npm install -D runlist      # project scripts via node_modules/.bin
-npx runlist init            # try it without installing
+npx runlist setup           # guided project setup without a permanent CLI install
 ```
 
 `runlist` is the canonical executable, `rl` is its short convenience alias, and
@@ -26,37 +134,8 @@ same CLI. The npm package is `runlist`; existing `dotmd-cli` installs should be
 replaced with `runlist`. The Claude Code plugin is `runlist@runlist`. Legacy
 `dotmd.config.*` files, `DOTMD_*` variables and `.dotmd/` state keep working.
 
-For local CLI review, run this from the source checkout:
-
-```bash
-npm link --ignore-scripts
-npm ls -g --depth=0 runlist   # shows the checkout path when linked
-```
-
-Now `rl`, `runlist`, and `dotmd` run directly from that checkout wherever this
-Node installation is selected; source edits take effect immediately. npm globals
-and links belong to each Node installation. If entering a repo switches Node
-through NVM, link the checkout using that Node's npm too. Check
-`command -v rl` and `npm ls -g --depth=0 runlist` inside the target repo.
-A normal `npm install -g runlist` instead
-installs a separate copy of the published package. Merely editing or pulling the
-checkout does not update that copy. The version number alone cannot distinguish
-an unreleased checkout from an installed release.
-
-To leave local review and restore a released CLI, run
-`npm install -g runlist@<version>` (replace `<version>` with the release wanted).
-`rl update` also installs the published CLI, replacing the local link. Project
-dependencies installed with `npm install -D` are separate again: project scripts
-and `npx` can resolve those before the global CLI. Linking the CLI does not
-rebuild the desktop app or refresh an agent plugin's installed files.
-
-If you installed the old package globally, remove it before installing the new
-one because both packages provide the same executable names:
-
-```bash
-npm uninstall -g dotmd-cli
-npm install -g runlist
-```
+Running from a source checkout, or replacing an old `dotmd-cli` install? See
+[Checkout review and migration](#checkout-review-and-migration).
 
 The optional desktop app is a separate download with the same Markdown engine; see
 [desktop setup and validation](desktop/README.md). The delivered app includes
@@ -71,9 +150,9 @@ controls are experimental; live retrieval depends on a compatible external
 provider. Local chat and push are deferred.
 
 <!-- runlist:release:start -->
-CLI and desktop release version: **0.99.2**.
-[Mac installer and release notes](https://github.com/reowens/runlist/releases/tag/desktop-v0.99.2).
-Normal product releases publish both components; an installed Mac app is updated with rollback after it has quit.
+CLI and desktop release version: **0.100.0**.
+[Mac installer and release notes](https://github.com/reowens/runlist/releases/tag/desktop-v0.100.0).
+Normal product releases publish both components. Local app installation is separate from release acceptance.
 <!-- runlist:release:end -->
 
 The desktop app bundles the matching engine and runtime. Publishing a product
@@ -117,7 +196,7 @@ for checks and evidence. Full-app dialog accessibility remains an open finding;
 fresh/minimum-host and controlled whole-app performance qualification remain
 follow-up work.
 
-Verify an installed Mac app without opening it:
+Optional installed-app diagnostics, separate from release acceptance:
 
 ```bash
 node desktop/scripts/check-installed.mjs
@@ -192,10 +271,46 @@ Replacement keeps the previous app as a rollback copy. Add `--dry-run` to previe
 an install or launch without network access, file changes or opening the app.
 Use `runlist desktop --app /path/to/application` for a custom installation path.
 
+### Checkout review and migration
+
+For local CLI review, run this from the source checkout:
+
+```bash
+npm link --ignore-scripts
+npm ls -g --depth=0 runlist   # shows the checkout path when linked
+```
+
+Now `rl`, `runlist`, and `dotmd` run directly from that checkout wherever this
+Node installation is selected; source edits take effect immediately. npm globals
+and links belong to each Node installation. If entering a repo switches Node
+through NVM, link the checkout using that Node's npm too. Check
+`command -v rl` and `npm ls -g --depth=0 runlist` inside the target repo.
+A normal `npm install -g runlist` instead
+installs a separate copy of the published package. Merely editing or pulling the
+checkout does not update that copy. The version number alone cannot distinguish
+an unreleased checkout from an installed release.
+
+To leave local review and restore a released CLI, run
+`npm install -g runlist@<version>` (replace `<version>` with the release wanted).
+`rl update` also installs the published CLI, replacing the local link. Project
+dependencies installed with `npm install -D` are separate again: project scripts
+and `npx` can resolve those before the global CLI. Linking the CLI does not
+rebuild the desktop app or refresh an agent plugin's installed files.
+
+If you installed the old package globally, remove it before installing the new
+one because both packages provide the same executable names:
+
+```bash
+npm uninstall -g dotmd-cli
+npm install -g runlist
+```
+
 ### Agent host setup
 
-The CLI alone gives an agent no orientation and no session identity. Install the
-integration for whichever host you run:
+For project onboarding, start with [`runlist setup`](#quick-start). It preserves
+existing configuration and installs a host integration only when selected.
+The CLI alone does not load the workflow skill or hooks into your assistant.
+You can also inspect or install an integration separately:
 
 ```bash
 runlist install             # what's installed for each host
@@ -209,6 +324,51 @@ The integrations are one-time and global. Codex exports `CODEX_THREAD_ID` to
 every tool shell, so its identity works without the plugin; the plugin adds a
 workflow skill, session orientation, and the tool guard.
 
+The Claude Code and Codex plugins include a discoverable **runlist-setup** skill
+for requests such as “Claude, help me set up Runlist in this project,” including
+projects with no Runlist config yet. The ordinary **runlist** skill handles the
+ongoing plan/doc/prompt workflow. The setup skill is available only after its
+plugin is installed and loaded; typing its name in an assistant without that
+plugin does not install it. Use the terminal bootstrap below first.
+Host hooks need a persistent `runlist` executable on that host's `PATH`; an
+ephemeral `npx` run alone does not provide it.
+
+### Which assistant can run setup?
+
+Use a shell in the checkout you want to configure. These surfaces have different
+execution environments:
+
+- **Claude Code (the working path in Claude Desktop):** open the **Code** tab, or
+  use a terminal session, with the intended checkout selected. A local Code
+  session reads the same plugin settings as the terminal, and hooks fire there.
+  Install the plugin with the [three-step quick path](#handoffs-in-3-steps) and
+  start a new session. Desktop Code also supports cloud and SSH environments; those
+  execute elsewhere. See
+  [Claude Code desktop environments](https://code.claude.com/docs/en/desktop).
+  Install and verify the plugin in that environment; follow the host's
+  [plugin activation or reload result](https://code.claude.com/docs/en/discover-plugins).
+- **Claude Desktop Chat:** a conversation alone does not provide Runlist's CLI
+  or the Runlist Claude Code plugin. An assistant without a suitable shell can
+  give you the terminal commands below, but cannot report them as executed.
+  Desktop extensions and connectors are separate integrations; this plugin
+  supplies no Desktop Chat execution bridge. See Anthropic's
+  [connector and desktop-extension guidance](https://support.claude.com/en/articles/11725091-when-to-use-desktop-and-web-connectors).
+- **Claude Cowork:** verify the actual workspace and shell first. Current
+  sessions run in the cloud by default; legacy local sessions execute code in
+  an isolated VM. Connected local-folder access does not establish that shell
+  commands run on your Mac or PC. See the official
+  [Cowork architecture](https://support.claude.com/en/articles/14479288-claude-cowork-architecture-overview).
+- **Codex:** Local and Worktree sessions use your computer; Cloud uses a remote
+  workspace. Choose the intended project and execution mode before setup. See
+  the official [Codex environments documentation](https://learn.chatgpt.com/docs/environments/modes).
+
+A successful `npm install` in a cloud, SSH, container, or Cowork shell installs
+into that environment's npm scope. It does not prove that your local computer's
+CLI, host plugin, or GUI was installed. Report the paths actually changed.
+With no shell or checkout access, run the bootstrap in a local terminal yourself.
+The optional [Runlist desktop GUI](#optional-desktop-gui) is installed separately
+with `runlist desktop install` on supported Macs; `setup` never downloads it.
+
 ### Codex Plugin
 
 `runlist install codex` copies the plugin included in the npm package into the
@@ -294,17 +454,208 @@ if an installed host fails to update. Uninstalled hosts are not added.
 Restart the affected host sessions to load updated integrations; Claude Code also
 supports `/reload-plugins`.
 
+## Host health and selected repairs
+
+Inspect Claude, Codex and OpenCode together before choosing a repair:
+
+```bash
+runlist doctor --hosts
+runlist doctor --hosts --json
+runlist update --check --json
+```
+
+These reports are offline: they read executable paths, registries and managed
+assets without running host programs or importing the project's JavaScript
+config. They work before project initialization and with a broken project config.
+The report includes the CLI launcher, Node/npm scope, Claude profiles and shared
+plugin stores, installed/catalog versions, source comparisons and reload steps.
+Newer published versions are not queried by an offline check; it compares the
+local files and saved catalogs. An online `runlist update` refreshes catalogs.
+
+`missing`, `stale`, `foreign`, `current` and `unknown` are distinct. `current`
+describes the reported files or catalog comparison; installed and loaded states
+remain separate. Cached files never establish that a running session loaded the
+skill or trusted its hooks. A local checkout can contain unreleased assets while
+the published Claude catalog and installed plugin still match.
+
+Host repairs are selected explicitly and previewed by default:
+
+```bash
+runlist doctor --hosts --repair codex
+runlist doctor --hosts --repair codex --apply --dry-run
+runlist doctor --hosts --repair codex --apply
+```
+
+Repeat `--repair` to select several hosts. In host mode, `--apply` requires named
+repair targets; `--dry-run` always prevents execution. A selected repair can
+install a missing integration or refresh managed content. Foreign/unreadable
+content is preserved, independent host failures are reported separately, and
+remaining source/activation checks stay visible. Host application upgrades
+remain with each host's installer.
+Already-current Claude/OpenCode files need no repair. Codex may still require
+an installed-copy check even when its marketplace source is current. Blocked
+repairs offer a safe preview or manual next step instead of an apply command
+that would repeat the refusal. Saved enablement and live activation stay separate.
+
+When Claude has multiple binaries or profiles, use the native binary shown in
+the inventory and explicit absolute profile paths. Replace these placeholders
+with the paths from your report:
+
+```bash
+runlist doctor --hosts --repair claude \
+  --claude-config /absolute/profile --claude-bin /absolute/native/claude
+runlist doctor --hosts --repair claude \
+  --claude-config /absolute/profile --claude-bin /absolute/native/claude --apply
+runlist update --host claude \
+  --claude-config /absolute/profile --claude-bin /absolute/native/claude --dry-run
+```
+
+Repeat `--claude-config` for separate profiles. Shared physical plugin stores are
+updated once, while each profile's enabled settings and each saved scope remain
+visible. A wrapper can override `CLAUDE_CONFIG_DIR`; Runlist refuses ambiguous
+targeting and asks for an explicit native binary. It does not infer an account
+from the wrapper's filename or script contents.
+
+`runlist update --host claude|codex|opencode` restricts the update to that installed
+host integration and conflicts with `--cli-only`. Missing integrations remain
+missing during update. Without a host selector, update retains its CLI and
+installed-host workflow, refreshing official Claude catalogs before scoped
+updates and checking managed asset contents even when versions match. The npm
+scope and effects on local CLI links are reported; checkout sources and project
+dependencies are preserved. Reload/restart the affected hosts and review their
+hook trust settings after repairs or updates.
+
 ## Quick Start
 
+From a terminal in your project, install the CLI using one of the scopes above,
+then start guided setup:
+
+```bash
+cd /path/to/your/project
+runlist setup                   # terminal: collect choices, preview, confirm
+# Or bootstrap without a permanent CLI install:
+npx runlist setup
+```
+
+An interactive terminal without `--yes`, `--json`, or `--dry-run` collects missing choices and asks you to
+confirm the concrete preview. In a noninteractive shell, omitting `--yes` prints
+a preview, writes nothing, and does not wait for input. `--dry-run` always
+previews, even with `--yes`; `--json` requests a machine-readable report.
+
+For deterministic setup, preview explicit options and then apply those same
+options with `--yes`. This example chooses a relative docs root in a new project,
+leaves prompts untracked, and installs no host integration:
+
+```bash
+runlist setup --docs-root docs --prompt-tracking untracked --host none --dry-run --json
+runlist setup --docs-root docs --prompt-tracking untracked --host none --yes --json
+```
+
+`--yes` applies explicit options and defaults without asking more questions.
+Fresh projects default to `docs/`, prompt tracking `untracked`, no ignore-file
+edits, no host install, no first plan, and no document adoption. Existing config,
+roots, JavaScript functions, and hooks are preserved; an existing prompt policy
+is retained unless you explicitly select another. Changing an existing root
+with `--docs-root` is refused with manual configuration guidance. Review and edit
+that project's root export and dependent paths yourself; setup is not a generic
+JavaScript config editor and does not move documents.
+
+To include existing Markdown, select each file explicitly. For example, if
+these two files exist inside your configured docs root:
+
+```bash
+runlist setup --adopt docs/notes/design.md --adopt docs/notes/constraints.md --dry-run
+runlist setup --adopt docs/notes/design.md --adopt docs/notes/constraints.md --yes
+```
+
+Only the selected paths are considered for adoption. Review the proposed
+frontmatter changes; setup never blanket-tags your existing docs. Other
+untagged docs remain outstanding and may still appear in validation findings.
+An `attention` result means setup applied the selected changes and project
+validation still needs attention; it exits with status 1. Inspect the report's
+completed actions and validation findings before retrying.
+
+Optional choices can be combined in the same preview/apply pair:
+
+- `--gitignore` explicitly requests missing ignore rules. Without it, ignore
+  files are untouched. Selecting `tracked` does not remove existing ignore rules.
+- `--host claude`, `--host codex`, or `--host opencode` selects the existing
+  `runlist install` integration. The default is `--host none`. Host installation
+  requires apply; a preview does not install anything. Check which host executable
+  your shell resolves before applying, particularly with multiple Claude installs:
+  in Bash/Zsh use `type -a runlist rl node npm claude` (PowerShell:
+  `Get-Command runlist,rl,node,npm,claude -All`). Setup does not install or update
+  the agent host itself.
+- `--first-plan <slug>` also requires `--current-state <text>` and
+  `--next-step <text>`. Supply your actual state and immediate action; do not use
+  invented progress or placeholders. `current_state` is capped at 1,500 characters
+  and `next_step` at 800; longer details belong in the plan body. For example,
+  after replacing these illustrative values with your own:
+
+  ```bash
+  runlist setup --first-plan auth-refresh \
+    --current-state "The existing login flow has no retry path." \
+    --next-step "Reproduce a failed login and record the expected retry behavior." \
+    --dry-run
+  ```
+
+Read setup's **completed**, **outstanding**, and **failed** results separately;
+**notes** (JSON `notes`) is information, not remaining work.
+Configuration written successfully does not mean every document passed checks
+or that a running host loaded its plugin. Unselected untagged documents,
+unavailable host tools, and required host reloads must remain visible. Address
+the named failure, inspect what already completed, then preview a retry; do not
+silence validation to make onboarding look complete. Use the existing commands
+for follow-up inspection:
+
 ```bash
-runlist init                    # create config, docs/, and the generated index
-runlist new plan auth-refresh  # scaffold a typed document
 runlist plans                  # compact live plan dashboard
-runlist briefing               # comprehensive active-work view
-runlist check                  # validate schema, references, and lifecycle shape
-runlist doctor                 # preview repairs; add --apply to write
+runlist check                  # schema, references, and lifecycle findings
+runlist doctor                 # preview repairs; add --apply only for chosen repairs
+runlist doctor --session        # identity in this shell, not proof of host activation
 ```
 
+After a host install, follow its activation/trust instructions and verify the
+skill and hooks in that host. Restart the session or reload plugins where
+required; setup cannot certify a future session. For lower-level initialization
+without onboarding, `runlist init` remains available.
+
+New projects recommend leaving pending prompts untracked to reduce commit churn.
+`runlist init` leaves `.gitignore` and other ignore files untouched by default.
+Untracked does not mean ignored: `git add -A` can include these files. Inspect or
+explicitly choose the policy in the CLI:
+
+```bash
+runlist config show
+runlist config get promptTracking --json
+runlist config get promptDirectory --json
+runlist config set promptTracking tracked --dry-run
+runlist config set promptTracking tracked
+```
+
+`untracked` warns when agents include pending prompts in Git operations;
+`tracked` allows them; `local` denies them. Existing configs without a choice
+keep `local` behavior until an explicit selection. Policy changes preserve the
+prompt location and existing files and never stage, untrack, move or delete them.
+They never change ignore files. To explicitly add ignore rules during setup,
+preview `runlist init --gitignore --dry-run`, then run `runlist init --gitignore`.
+This adds missing runtime-state rules and, unless `tracked` is selected, prompt
+rules; it preserves unrelated rules. Selecting `tracked` does not remove rules
+that already ignore prompts.
+
+Runtime state in `.runlist/`, such as the parse cache, also remains unignored by
+default and can be staged by `git add -A`. Review the selected files before
+committing. The explicit ignore option covers `.runlist/` and `.dotmd/` (the
+legacy state directory, still readable for compatibility).
+
+`config show` also reports `root`, resolved `docsRoots`, `index.path`,
+`archiveDir`, and the resolved `promptDirectory`. Sources distinguish configured
+values, defaults, the legacy `readme` index alias, and derived paths. Only
+`promptTracking` supports CLI writes; other keys return specific manual-edit
+guidance. These commands import the trusted project's JavaScript config but do
+not invoke document hooks. The GUI uses the same project configuration; it is
+not required to inspect or choose prompt policy.
+
 `runlist plans` is the compact orientation view. `runlist briefing` lists live
 plans with next steps and grows with the corpus. `runlist context` is the fuller
 human/LLM briefing, while `runlist agent-context` emits bounded structured JSON for
@@ -800,7 +1151,7 @@ from `runlist.config.mjs` and return an argv array such as
 `['just', 'commit', message, ...paths]`. Baton quotes the printed command and
 excludes session prompts from `paths`.
 
-Saved prompts are local session state. Consume them with `runlist use`; inspect
+Saved prompts are handoff artifacts with a project-selected Git policy (see `runlist config get promptTracking`). Consume them with `runlist use`; inspect
 without consuming via `runlist prompts show`. Consuming a baton prompt also claims
 its plan; `runlist use --no-claim` reads and archives it without starting the plan.
 Only an agent session consumes: Claude Code, Codex, OpenCode, or a shell with
@@ -1214,6 +1565,16 @@ runlist help statuses
 runlist <command> --help
 ```
 
+For a short recipe for one task, request focused help:
+
+```bash
+runlist new plan --help       # also: new doc, new prompt
+runlist prompts show --help   # inspect without consuming
+runlist baton --subagent --help
+```
+
+The parent command's help retains the complete options and examples.
+
 Shell completion is generated from the same command registry:
 
 ```bash
@@ -1226,11 +1587,18 @@ duplicating the complete command catalog.
 
 ## Configuration
 
-Run `runlist init` to create `runlist.config.mjs` (a legacy `dotmd.config.mjs` is still read). A minimal typed configuration:
+Run `runlist setup` to create `runlist.config.mjs` (a legacy `dotmd.config.mjs` is still read). A minimal typed configuration:
+
+`runlist config show|get|set` currently supports only `promptTracking`. It reports
+the effective value, source and config path. Writes accept validated values,
+preserve unrelated JavaScript and hooks, and refuse symlinks, computed or ambiguous exports
+with instructions for a manual edit. Other settings are edited in the JavaScript
+config; the GUI is optional.
 
 ```js
 export const root = 'docs';
 export const archiveDir = 'archived';
+export const promptTracking = 'untracked';
 
 export const types = {
   plan: {