@kontextmind/kxm 0.7.103 → 0.7.105

package/docs/reference/cli-reference.md

@@ -91,7 +91,7 @@ kxm -V
 - The `command` field is not always the words you typed: `hub stop` and `session stop` report `stop`, `session token` reports `auth token`, `routes admit` and `routes disable` report `routes admitted` and `routes disabled`, `models inventory-refresh` reports `models inventory refresh`, `workflow export` reports `retrospective export`, `gate degrade` reports `workflow degrade`, `gate signal` and `workflow signal` report `signal`, `gate github watch` reports `github watch`, `agent worker` reports `worker`, and `improve report` reports `improve`.
 - A result with `ok: false` is written to stderr in both text and JSON mode; everything else goes to stdout. `runtime status` is the exception: when the supervisor is down it prints `ok: true, running: false` on stdout and exits 1.
 - `peer` subcommands and `workflow checkpoint|record|wait` print the hub's result object as returned, tagged with `schema` but without `ok` or `command`. Their failures print `{"ok":false,"error":"command_failed","detail":"..."}`. Text mode prints the same JSON.
-- Several error paths ignore `--json` and print one plain line on stderr: argument checks in `agent worker`, `session start`, `workflow start`, `gate degrade`, `gate signal`, and `gate github watch`; every error from `config`, `role`, `workflow definitions|add|remove|modify` (except the `workflow add` refusals listed under it, which honor `--json`), `goal`, `task`, `memory`, `skills` (other than `skills create --dry-run`), `suggest`, `studio`, and `completion`. Check the exit code before parsing stdout.
+- Several error paths ignore `--json` and print one plain line on stderr: argument checks in `agent worker`, `session start`, `workflow start`, `gate degrade`, `gate signal`, and `gate github watch`; errors from `config`, `role`, `workflow definitions|remove|modify`, `goal`, `task` outside run admission, `memory`, `skills` (other than `skills create --dry-run`), `studio`, and `completion`. `suggest` and `workflow add` failures honor `--json`. Check the exit code before parsing stdout.
 - Every `context` subcommand exits 1 with a Node.js stack trace and no JSON when the hub cannot be reached.
 - Output is redacted. Values of environment variables whose names contain `TOKEN`, `SECRET`, `KEY`, or `PASSWORD` are replaced with `[redacted]`, and 64-character hex strings are replaced unless they appear in a known digest field such as `configRevision` or `sha256`. `session brief` and `auth token` print the session token itself; treat their output as a credential.
 
@@ -173,6 +173,8 @@ kxm init [--name <name>] [--project-id <id>] [--repository <id=absolute-path>]..
 
 Creates, validates, repairs, resumes, or joins a KXM project at the Git root that contains the current directory. A new project gets a minimal configuration: one coordinator agent, one implementer agent, a `test` command gate, and a `default` plan-implement-verify workflow. An existing project is validated without rewriting. Conflict-free template updates to non-authority fields are applied; authority changes, overlapping edits, and provenance-free or legacy state stay planning-only. `init` does not start a hub or the Runtime.
 
+The starter `defaultHarness: pi` and `npm test` gate are generic settings, not repository detection. Creation and create-planning output include `guidance`: for Claude, set `defaultHarness: claude` in `.kxm/project.yaml`, update any explicit `harness` overrides in `.kxm/agents/*.yaml`, and configure compatible agent models; for .NET or other non-npm repositories, set `.kxm/gates.yaml` → `gates.test.argv` to the repository's actual test command. Preflight reports an actionable prerequisite for `npm test` without a readable `package.json` test script; `task run` refuses it before creating a run.
+
 | Option | Argument | Default | Description |
 |---|---|---|---|
 | `--name` | `<name>` | Git root directory name | Project display name for a new project |
@@ -184,7 +186,7 @@ Creates, validates, repairs, resumes, or joins a KXM project at the Git root tha
 - Needs a Git repository. Does not need a hub or the Runtime.
 - Writes `.kxm/project.yaml`, `.kxm/agents/coordinator.yaml`, `.kxm/agents/implementer.yaml`, `.kxm/gates.yaml`, `.kxm/repo/repo.yaml`, `.kxm/workflows/default.yaml`, and `.kxm/template-provenance.yaml`, using a `.kxm-init-transaction` directory at the Git root while a create or repair is in flight. Repository bindings are written under the user state root, never into Git. `--dry-run` writes nothing.
 - On an interactive terminal without `--json` or `--dry-run`, a successful create or join offers to install shell completion (suppress with `KXM_SKIP_COMPLETION_PROMPT=1`) and to write workflow-guide agents (suppress with `KXM_SKIP_GUIDE_SETUP_PROMPT=1`). Guided setup keeps a role only when one of its guide candidates is on a fixed map of reviewed harness/model pairs and that harness is authenticated; it writes the agent and workflow files, appends those selectors to `.kxm/routes.yaml`, and skips every other candidate. Google candidates are not on the map and are always skipped, because the Runtime's Pi one-shot cannot reach Google's `antigravity` Pi provider yet (see [Harness routing](harness-routing.md#google-through-the-antigravity-pi-provider)).
-- JSON keys: `action` (`planned`, `created`, `joined`, `repaired`, `resumed`, or `validated`), `mode`, `inspectedFrom`, `projectRoot`, `changesRequired`, `legacyInputs`, `issues`, `configRevision`, `files`, `plannedOnly`, and, when relevant, `localBindingFile`, `bindingsChanged`, `repairPlan`, `resumePending`, `transactionKind`.
+- JSON keys: `action` (`planned`, `created`, `joined`, `repaired`, `resumed`, or `validated`), `mode`, `inspectedFrom`, `projectRoot`, `changesRequired`, `legacyInputs`, `issues`, `configRevision`, `files`, `plannedOnly`, and, when relevant, `guidance`, `localBindingFile`, `bindingsChanged`, `repairPlan`, `resumePending`, `transactionKind`.
 - Exit 0 for every completed action and every dry-run plan. Exit 1 when the result is planning-only (legacy state, blocked repair, partial state without provenance) or for `initialization_failed` (with `issues`) and `initialization_io_failed`. A planning-only text result prints the reason and then one `<file>: <code>: <message>` line per validation issue, for example `.kxm/workflows/first.yaml: gate_outcome_impossible: ...`.
 
 Preview what a new project would contain:
@@ -882,8 +884,9 @@ Probes the built-in harness catalog (`pi`, `claude`, `kimi`, `codex`, `deepseek`
 
 No command-specific options.
 
-- Reads only. No hub needed. Always exits 0.
+- Reads only. No hub needed. In a KXM project, `defaultHarness` and the inventory's default marker reflect `.kxm/project.yaml`; outside a project they default to Pi. Invalid project configuration must be repaired before the project default can be resolved.
 - JSON keys: `defaultHarness`, `harnesses` (each with `id`, `label`, `default`, `mode`, `detected`, `authenticated`, `dispatch` (`status`, `supported`, `reason`), `canUpdate` (`self`, `extensions`, `models`), `issues`).
+- Errors: `harness_list_failed` with configuration `issues`, or `harness_list_io_failed` (exit 1); both honor `--json` and write to stderr without claiming a fallback project default.
 - `dispatch` is `yes` only when the harness is detected, has an audited read-only one-shot profile, and is authenticated. Otherwise the first failing check gives the reason: `not_detected`, `no_headless_mode`, `permission_profile_unaudited` (a detected `deepseek`), `not_authenticated`, or the auth issue when login state is unknown (`auth_context_required` for Pi, `auth_unknown`, `auth_unparsed`, or another `auth_*` code).
 
 Captured with no harness CLIs on `PATH`:
@@ -893,7 +896,7 @@ kxm harness list
 ```
 
 ```text
-default harness: pi (omit agent harness: to use headless Pi)
+default harness: pi (used when an agent omits harness:)
 enable/disable = Git YAML (.kxm/agents, .kxm/models) or the harness's own plugin CLI
 governed kxm skills are not auto-updated
 id        default  detected  auth     dispatch                   updates
@@ -1383,12 +1386,12 @@ dry run: resume workflow run wf_dry_run (stage: review)
 kxm run <workflow> [prompt...]
 ```
 
-Create a KXM run (offline-first; `kxm runs drive <runId> --simulated` executes it model-free). The run is immutable and pins the project's `homeRuntimeId`, config revision, and executor and tool policy revisions. Run events record only the SHA-256 of the prompt; the full prompt text is kept in a local sidecar file, `run-events.db.run-prompts.json`, next to the project's Runtime event store and written with mode 0600, and a dispatch refuses the run (`run_prompt_mismatch`) if that text no longer matches the hash. The Runtime supervisor is started first if it is not running. No steps execute until the run is driven (see [`kxm runs drive`](#kxm-runs-drive)); the text output's second line prints the command that drives the new run model-free and the one that cancels it.
+Create a KXM run without executing steps. The run pins the project's `homeRuntimeId`, config revision, and executor and tool policy revisions. Events store the prompt's SHA-256; its full text is kept in a local mode-0600 sidecar, `run-events.db.run-prompts.json`, and dispatch refuses a hash mismatch (`run_prompt_mismatch`). The Runtime supervisor starts if needed. Output explicitly reports no execution, live prerequisites, and separate drive/status/receipt commands. Use `kxm runs drive <runId> --wait` for supported live one-shot calls; no hub or Pi worker is required. `--simulated` is a model-free experiment, not evidence that implementation ran. Local runs are inspected with `kxm runs`, not the webhook-only `kxm workflow get`.
 
 - Arguments: `<workflow>`, Workflow id to run (a file under `.kxm/workflows/`); `[prompt...]`, Run prompt (events keep its hash; the full text is kept in a local 0600 sidecar file).
 - No command-specific options. Refuses `--workspace` (exit 2).
 - Needs a KXM project. Starts and uses the Runtime; no hub needed. Honors `--dry-run`, which validates the project and prints the plan without starting the supervisor.
-- JSON keys: `phase`, `idempotent`, `run` (`runId`, `homeRuntimeId`, `status`, `configRevision`), `supervisor` (`runtimeId`, `port`, `started`). Dry run: `projectRoot`, `workflowId`, `configRevision`. The JSON result does not carry the drive command.
+- JSON keys: `idempotent`, `run` (`runId`, `homeRuntimeId`, `status`, `configRevision`), `supervisor` (`runtimeId`, `port`, `started`), and `execution` (`status: not_started`, `mode: live`, `defaultHarness`, `authentication: not_checked`, `prerequisites`, `nextSteps`). Dry run: `projectRoot`, `workflowId`, `configRevision`, `defaultHarness`, `prerequisites`. The obsolete `phase: pre-3a` field is no longer returned.
 - Errors: `workflow_required` (exit 2), `project_required`, `run_workflow_unknown`, `run_failed` with `issues` (any invalid file in the project fails the load, for example `gate_outcome_impossible`), `run_io_failed` (exit 1).
 - The `default` workflow that `kxm init` writes does not set `limits.maxAgentTimeMs`, so it can be driven. A workflow that sets that limit is created, but `kxm runs drive` refuses it with `run_handoff_required` (`limit_unsupported`); projects from older `kxm init` templates carry it on `default`.
 
@@ -1416,7 +1419,12 @@ kxm run default "Fix the flaky login test"
 
 ```text
 run created: run_a80e84c98f514299b82f0157f4537ea3 (home rtm_1a42e069…, config sha256:b45f8f51a506…)
-drive it model-free: kxm runs drive run_a80e84c98f514299b82f0157f4537ea3 --simulated --wait (or cancel: kxm runs cancel run_a80e84c98f514299b82f0157f4537ea3)
+No steps executed. Project default harness: pi; per-agent harness settings take precedence.
+Live prerequisite (...): ...
+Live execution uses one-shot harness calls; no hub or Pi worker is required. Check installation/authentication with kxm harness list.
+Resolve the prerequisites above, then execute: kxm runs drive run_a80e84c98f514299b82f0157f4537ea3 --wait
+Inspect: kxm runs status run_a80e84c98f514299b82f0157f4537ea3 --json; receipt: kxm runs receipt run_a80e84c98f514299b82f0157f4537ea3 --json; cancel: kxm runs cancel run_a80e84c98f514299b82f0157f4537ea3
+These are local Runtime runs, not webhook workflows; use kxm runs, not kxm workflow get.
 ```
 
 ## `kxm runs`
@@ -1965,6 +1973,8 @@ kxm workflow add [workflowId] [--template <name> | --file <path> | --pick [selec
 
 Add a workflow definition to global or local configuration. With `--template <name>`, the named built-in template is written under the workflow ID. Without a workflow ID, or with `--pick`, you choose from the built-in templates and, for local scope, existing global definitions; a global definition with a template's ID is not offered. The choice is written under its own ID with its content: the template, or a copy of the global definition's file, with `--description` replacing its description. With `--file`, the YAML file is copied as-is once it passes the local check below. Otherwise a one-step scaffold is written: one `implementer` agent step with write access to `control` that ends the run `completed` on `passed` and `failed` on `failed`.
 
+IDs are flat, portable lowercase slugs, at most 64 characters: use `bug-fix`, not `software-engineering/bug-fix`. Paths, traversal, and reserved platform names fail before writing. Imported definitions must use `kxm.workflow.v1`, with `agent` rather than legacy `role` steps and no top-level `id`; installation validates the runner's restricted YAML, schema, and transitions before creating directories or replacing a file. `--pick` copies a selected global definition, honors `--description`, and preserves an explicit destination ID. A global definition is not silently replaced with a scaffold.
+
 | Option | Argument | Default | Description |
 |---|---|---|---|
 | `--file` | `<path>` | none | Path to YAML workflow definition file |
@@ -1977,8 +1987,8 @@ Add a workflow definition to global or local configuration. With `--template <na
 - Templates: `implement-and-verify` runs the `implementer` agent, then the project's `test` gate, and a failing gate (`implementation-failure`) sends the work back to `implement` at most twice. `dual-critic-review` adds two review steps between them, both run as the `coordinator` agent with read access; point `review-arch` and `review-cli` at your own agents for independent critics. `spec-and-plan` plans and then reviews the plan, both as `coordinator`, reading the repository only.
 - The templates and the scaffold are valid `kxm.workflow.v1` definitions that use only what `kxm init` creates: the `coordinator` and `implementer` agents, the `control` repository, and the `test` gate. Each was checked with `kxm init --json` and `kxm run <id> --dry-run` for this page. A new file under `.kxm/workflows/` is a permission expansion that `kxm trust check` asks you to review before you commit it.
 - Writes `<scope dir>/workflows/<id>.yaml`. `kxm run` loads only `.kxm/workflows/`, so a `--scope global` definition is not runnable until it is copied into a project. `--dry-run` plans the write and writes nothing.
-- Local scope belongs to a KXM project: the file lands in the project root's `.kxm/workflows/` from any subdirectory, and outside a project the command refuses with `project_not_found` and creates nothing. Before writing, the project loader checks the project with the new document in place of any file of that ID, using the parser, schema and bundle rules `kxm run` uses. If the project would not load, the command refuses with `workflow_invalid`, lists each issue and writes nothing, also under `--dry-run`. So `--file` or a picked global definition with a top-level `id` or a `role:` step, the shape `workflow add` wrote through 0.7.92, is refused, and `--overwrite` replaces a file left in that shape. Global scope is not checked, because no loader reads it.
-- Refusals exit 2 and honor `--json`: `workflow_template_unknown` (the text names the three templates), `workflow_id_required` (no workflow ID), `workflow_add_conflict` (`--template` combined with `--file` or `--pick`), `project_not_found`, and `workflow_invalid` (with `issues`, each `{phase, code, file, message}`). An existing definition without `--overwrite` exits 1 with a plain `workflow add failed: workflow_already_exists: ...` line, also under `--dry-run`.
+- Local scope belongs to a KXM project: the file lands in the project root's `.kxm/workflows/` from any subdirectory, and outside a project the command refuses with `project_not_found` and creates nothing. Before writing, the project loader checks the project with the new document in place of any file of that ID, using the parser, schema and bundle rules `kxm run` uses. If the project would not load, the command refuses with `workflow_invalid`, lists each issue and writes nothing, also under `--dry-run`. So `--file` or a picked global definition with a top-level `id` or a `role:` step, the shape `workflow add` wrote through 0.7.92, is refused, and `--overwrite` replaces a file left in that shape. Global definitions receive ID, schema and transition checks, but have no project references to validate.
+- Refusals exit 2 and honor `--json`: `workflow_template_unknown` (the text names the three templates), `workflow_id_required` (no workflow ID), `workflow_add_conflict` (`--template` combined with `--file` or `--pick`), `project_not_found`, and `workflow_invalid` (with `issues`, each `{phase, code, file, message}`). Other input, file and overwrite failures exit 1 with `workflow_add_failed` and `message`. No failure writes the destination, and dry runs do not create missing local, global, or runtime directories.
 - JSON keys: `workflowId`, `id`, `filePath`, `scope`.
 
 Start a first workflow from a template:
@@ -2071,17 +2081,23 @@ Validates workflow definitions and operates evidence gates. The group has exactl
 kxm gate validate [--file <path>]
 ```
 
-Parse workflow definitions without printing secrets, using the same single source the hub loads: `--file`, else `KXM_WEBHOOK_WORKFLOWS_FILE`, else inline `KXM_WEBHOOK_WORKFLOWS`.
+Validate workflow definitions without printing secrets. An explicit `--file` accepts a local `kxm.workflow.v1` YAML/JSON mapping or a webhook JSON array. Local mappings use the runner's restricted YAML parser, schema, and transition compiler; use `kxm init --dry-run` to also validate project references. Without `--file`, `KXM_WEBHOOK_WORKFLOWS_FILE` or inline `KXM_WEBHOOK_WORKFLOWS` remain webhook-only JSON sources, exactly as the hub loads them.
 
 | Option | Argument | Default | Description |
 |---|---|---|---|
 | `--file` | `<path>` | configured source | Workflow definition file |
 
-- Each definition's `secretEnv` must name a set variable holding at least 16 characters (likewise `signalSecretEnv` when declared); otherwise parsing fails, for example with `workflow.secret must be a string`.
+- For webhook definitions, each `secretEnv` must name a set variable holding at least 16 characters (likewise `signalSecretEnv` when declared); otherwise parsing fails.
 - Reads definitions; appends telemetry. No hub needed.
-- JSON keys: `source`, `file`, `workflows` (`id`, `secretConfigured`, `signalSecretConfigured`), `warnings`; `outcome` is `warning` when warnings exist.
+- JSON keys: `source`, `file`, `workflows`, `warnings`; local entries contain `id` and `schema`, while webhook entries contain `id`, `secretConfigured`, and `signalSecretConfigured`. `outcome` is `warning` when warnings exist.
 - Exit 2 for `workflow_source_required` or `ambiguous_workflow_source` (both variables set); exit 1 for `file_not_found` or a parse error.
 
+Validate an installed local template:
+
+```bash
+kxm gate validate --file .kxm/workflows/bug-fix.yaml
+```
+
 ```bash
 KXM_WORKFLOW_SECRET="$SECRET" kxm gate validate --file workflows.json
 ```
@@ -2523,19 +2539,20 @@ Workflow: default
 kxm task run <taskId>
 ```
 
-Launch a workflow run driven by this task: runs `kxm run <workflow> <objective>` with the task's assigned workflow (default `default`), then sets the task status to `in_progress` when that succeeds.
+Prepare a local run from a task's objective and assigned workflow, or the project's `defaultWorkflow` when none is assigned. Read-only live preflight reports unsupported steps, limits, gates, harnesses, or model routes before creating a run. Unsupported work exits 1 with `run_execution_unavailable`, `defaultHarness`, and `execution.prerequisites`; neither the task nor Runtime is mutated. In particular, Claude-only writer work receives the read-only harness limitation instead of a dead-end created run.
+
+- On compatible configuration, output is that of [`kxm run`](#kxm-run): creation only, `execution.status: not_started`, and explicit live drive/status/receipt commands. Authentication is checked on dispatch, not certified by creation. Task status is not changed to `in_progress` merely because a run exists.
+- `--dry-run` applies the same live preflight and plans only the run request, with no task write or process start. JSON includes `taskId`, the unchanged task `status`, `projectRoot`, `workflowId`, `configRevision`, `defaultHarness`, `prerequisites`, `execution`, `dryRun`, and `planned`.
 
-- Output, requirements, and errors are those of [`kxm run`](#kxm-run), including the `--workspace` refusal.
-- Mutates the task file. `--dry-run` validates the project and the workflow as `kxm run --dry-run` does, then plans the run request and the task file write without making either; the status stays unchanged. Dry-run JSON keys: `taskId`, `projectRoot`, `workflowId`, `configRevision`, `status` (the status it would set), `dryRun`, `planned`.
+For a task assigned a configured, supported read-only workflow, a dry-run excerpt is:
 
 ```bash
 kxm task run task_4f79c0833e41 --dry-run
 ```
 
 ```text
-dry run: run workflow default for task task_4f79c0833e41, then mark it in_progress
+dry run: create workflow architecture-spike for task task_4f79c0833e41; task status stays todo until work actually starts
   would request POST kxm-runtime /v1/runs (starts the Runtime supervisor if it is not running)
-  would write /work/proj/.kxm/tasks/task_4f79c0833e41.yaml
 ```
 
 ### `kxm task sync`
@@ -2617,30 +2634,20 @@ kxm goal list
 kxm suggest <prompt...>
 ```
 
-Recommends a workflow, area, roles, and skills for a prompt or issue description using keyword matching and the detected harnesses. The suggested workflow ID comes from a built-in catalog and may not exist in your project; check with `kxm workflow definitions` before running the suggested command.
+Recommends a flat workflow ID backed by a shipped template, with category metadata and explicit execution prerequisites. The install command creates a definition only; it does not create or drive a run.
 
-- Arguments: `<prompt...>`, the task description.
-- No command-specific options. Probes harnesses as `harness list` does; reads nothing else. No hub needed.
-- Suggested skills are always KXM command skills shipped in `plugins/kxm/skills` (for example `kxm-workflow`, `kxm-runs`, `kxm-peer`, `kxm-context-memory`), never the KontextMind knowledge-plane skills.
-- JSON keys: `prompt`, `workflowId`, `area`, `confidence`, `reasons`, `suggestedSkills`, `roles` (`planner`, `writer`, `critics`, `verifier`), `suggestedCommand`.
+- Explicit `Claude only`, `Claude-only`, or `only Claude Code` constraints exclude other harnesses. A missing, unauthenticated, or unsupported required harness produces `harness_unavailable`; KXM never silently substitutes Grok or Codex.
+- A write workflow requires an audited writer profile for the selected harness. Only Pi and Grok currently have one; Claude-only bug fixes produce `live_write_unsupported` with direct-Claude implementation guidance, never a Grok substitution. No misleading create/drive command is emitted for an unsupported profile.
+- For supported work, every suggested agent binding uses the selected detected, authenticated, dispatch-ready harness. Configure its compatible admitted model, install the exact template, validate project configuration, then use the separate create/live-drive/status/receipt commands. Writers also require single-assignment/single-run admission, any configured developer-roster writer approval, and the repository's actual verification gate. An already-present recommended workflow ID produces `workflow_already_exists`; KXM will not assume its agents or permissions match the template.
+- Arguments: `<prompt...>`; no command-specific options. No hub needed. `--dry-run` skips native authentication probes to avoid their side effects and does not claim verified availability.
+- JSON keys: `prompt`, `workflowId`, `template`, `area`, `confidence`, `reasons`, `suggestedSkills`, `roles` (an array of `{agent, harness, role}`), `suggestedCommand` (installation only), and `execution`. Supported execution includes `prerequisites`, `shell`, `createCommand`, `driveCommand`, `statusCommand`, and `receiptCommand`; refusal includes `error`, `reason`, and `nextSteps`, sets `ok: false`, and exits 1.
 
 ```bash
-kxm suggest "Add retry with backoff to the payment webhook handler"
+kxm suggest "Fix a bug in an isolated worktree using Claude only" --json
 ```
 
 ```text
-Suggested Workflow: software-engineering/feature-implementation (software-engineering)
-Confidence: 65%
-Reasons: Matched keywords: add
-Suggested Skills: kxm-workflow, kxm-peer, kxm-context-memory
-Roles:
-  Planner:     claude (fable)
-  Writer:      grok (grok-4.6)
-  Critics:     claude:fable, codex:gpt-5.6-sol
-  Verifier:    npm run verify
-
-Execute with:
-  kxm run software-engineering/feature-implementation "Add retry with backoff to the payment webhook handler"
+{"ok":false,"workflowId":"bug-fix","template":"implement-and-verify","roles":[],"suggestedCommand":"kxm workflow add bug-fix --template implement-and-verify","error":"live_write_unsupported",...}
 ```
 
 ## `kxm explain`
@@ -3340,17 +3347,18 @@ price catalog stamped 2026-09-23 (list estimate only; vendor rates were not fetc
 ## `kxm backup`
 
 ```text
-kxm backup [--out <dir>]
+kxm backup [--out <dir>] [--all-projects]
 ```
 
-Creates a verified SQLite backup of the project hub store and the Runtime stores under the user state root, with a hashed `kxm.backup-manifest.v1` manifest. Relative to the current directory it discovers the hub store `.kxm/state/kxm.db`, and any `registry.db`, `bindings.db`, and `events/*.db` under `.kxm/runtime/`. Under the user state root (`KXM_STATE_HOME` or the platform default) it discovers `runtime/registry.db`, the `run-events.db` of every project under `runtime/projects/`, and each store's `run-events.db.run-prompts.json` prompt sidecar, which it copies as a plain file. Those Runtime stores belong to every project on the machine, not only this one. It ignores `--workspace` and `KXM_DATA_PATH`. Bindings, `update.yaml` and the other state roots are not included; see [Backup and restore](../operations/backup-and-restore.md).
+Creates a verified SQLite backup of this checkout's hub store and Runtime event store, with a hashed `kxm.backup-manifest.v1` manifest. It acts for the checkout the Runtime would use: the Git root that holds `.kxm/project.yaml`, or the current directory outside one. Under that checkout it discovers the hub store `.kxm/state/kxm.db`, and any `registry.db`, `bindings.db`, and `events/*.db` under `.kxm/runtime/`. Under the user state root (`KXM_STATE_HOME` or the platform default) it discovers the checkout's own `runtime/projects/<key>/run-events.db`, with `<key>` derived from the canonical checkout path as the Runtime derives it, and that store's `run-events.db.run-prompts.json` prompt sidecar, which it copies as a plain file. The shared `runtime/registry.db` and other projects' event stores are left out unless you pass `--all-projects`. It ignores `--workspace` and `KXM_DATA_PATH`. Bindings, `update.yaml` and the other state roots are not included; see [Backup and restore](../operations/backup-and-restore.md).
 
 | Option | Argument | Default | Description |
 |---|---|---|---|
 | `--out` | `<dir>` | `.kxm/backups/backup-<timestamp>` | Directory to write backup and manifest |
+| `--all-projects` | | Off | Also back up the Runtime registry and the event store and prompt sidecar of every project under `runtime/projects/`. Restoring that backup needs `kxm restore --all-projects` |
 
-- Writes a copy of each store and sidecar and `manifest.json`. `--dry-run` lists the stores and files it found and the files it would write without opening any store, so no WAL is checkpointed (JSON: `outDir`, `stores` with `storeId`, `sourcePath`, `backupFile`, `files` with `id`, `sourcePath`, `backupFile`, plus `dryRun` and `planned`).
-- JSON keys: `ok`, `backupId`, `outDir`, `manifest` (`schema`, `backupId`, `createdAt`, `projectRoot`, `stores` with `storeId`, `sourcePath`, `backupFile`, `schemaVersion`, `sha256`, `bytes`, `integrity`; `files` with `id`, `sourcePath`, `backupFile`, `sha256`, `bytes`; `complete`; `omitted`; `manifestSha256`).
+- Writes a copy of each store and sidecar and `manifest.json`. `--dry-run` lists the stores and files it found and the files it would write without opening any store, so no WAL is checkpointed (JSON: `scope`, `outDir`, `stores` with `storeId`, `sourcePath`, `backupFile`, `files` with `id`, `sourcePath`, `backupFile`, plus `dryRun` and `planned`).
+- JSON keys: `ok`, `backupId`, `outDir`, `manifest` (`schema`, `backupId`, `createdAt`, `projectRoot`, `scope` (`project` or `all-projects`), `stateRoot`, `runtimeProjectKey`, `stores` with `storeId`, `sourcePath`, `backupFile`, `schemaVersion`, `sha256`, `bytes`, `integrity`; `files` with `id`, `sourcePath`, `backupFile`, `sha256`, `bytes`; `complete`; `omitted`; `manifestSha256`).
 - A store or sidecar that cannot be copied, or that appears while the backup runs, is listed in `omitted` and the manifest records `complete: false`. The command then prints `Backup is incomplete (<n> omitted); not ok:`, sets `ok: false`, and exits 1; `kxm restore` refuses that manifest.
 - Exit 1 with `backup_failed`; `issues` carry codes such as `backup_no_stores` (no store found, or none could be copied) and `database_corrupted`.
 
@@ -3359,31 +3367,29 @@ kxm backup --out ../bk
 ```
 
 ```text
-Created SQLite backup with 3 store(s):
+Created SQLite backup with 2 store(s) (project scope):
   - hub-store: /work/proj/.kxm/state/kxm.db -> kxm.db (schema v5, 110592 bytes, sha256 sha256:56c6d...)
-  - registry: /home/me/.local/state/kxm/runtime/registry.db -> registry.db (schema v1, 20480 bytes, sha256 sha256:a5bde...)
   - events:38ed26cb8eeaa297f3b0b452: /home/me/.local/state/kxm/runtime/projects/38ed26cb8eeaa297f3b0b452/run-events.db -> run-events.db (schema v7, 348160 bytes, sha256 sha256:27c13...)
 Manifest: /work/bk/manifest.json
 ```
 
 The summary lists stores; the prompt sidecar appears under `files` in the manifest.
 
-In a project with a hub store and one Runtime project:
+In a project with a hub store and a Runtime event store:
 
 ```bash
 kxm backup --dry-run
 ```
 
 ```text
-dry run: back up 3 store(s) and 1 file(s) to /work/proj/.kxm/backups/backup-2026-09-23T17-44-51-277Z (sources are not opened, so their WAL is not checkpointed)
+dry run: back up 2 store(s) and 1 file(s) (project scope) to /work/proj/.kxm/backups/backup-2026-09-23T17-44-51-277Z (sources are not opened, so their WAL is not checkpointed)
   would write /work/proj/.kxm/backups/backup-2026-09-23T17-44-51-277Z/kxm.db
-  would write /work/proj/.kxm/backups/backup-2026-09-23T17-44-51-277Z/registry.db
   would write /work/proj/.kxm/backups/backup-2026-09-23T17-44-51-277Z/run-events.db
   would write /work/proj/.kxm/backups/backup-2026-09-23T17-44-51-277Z/run-events.db.run-prompts.json
   would write /work/proj/.kxm/backups/backup-2026-09-23T17-44-51-277Z/manifest.json
 ```
 
-On a machine with no hub store and no Runtime stores yet:
+On a machine with no hub store and no Runtime event store for this checkout yet:
 
 ```bash
 kxm backup --json
@@ -3396,17 +3402,20 @@ kxm backup --json
 ## `kxm restore`
 
 ```text
-kxm restore <manifest>
+kxm restore <manifest> [--all-projects]
 ```
 
-Restores SQLite stores and prompt sidecars from a verified backup manifest. It checks the manifest schema, refuses a manifest that records `complete: false` (`restore_incomplete`), checks that every backup file is present and each file's digest, then restores each store to its recorded source path, then each sidecar. A path under the manifest's project root is rebased onto the current directory when the manifest came from another project root; Runtime stores under the user state root go back to their recorded absolute paths. A manifest without a `complete` field, from an older build, still restores.
+Restores SQLite stores and prompt sidecars from a verified backup manifest into the checkout the Runtime would use, found as for `kxm backup`. It checks the manifest schema, refuses a manifest that records `complete: false` (`restore_incomplete`), checks that every backup file is present and each file's digest, and works out each target. A path under the manifest's project root is rebased onto this checkout. The backed-up checkout's own event store and its sidecar go to the store the Runtime derives for this checkout under the current user state root. Anything else under the user state root, such as the registry or another project's event store, is refused with `restore_requires_all_projects` unless you pass `--all-projects`, which rebases it onto the current user state root. A manifest written before backups were scoped records its Runtime stores as bare absolute paths; they count as machine-wide too, and `--all-projects` writes them back to those paths. A manifest without a `complete` field, from an older build, still restores.
+
+| Option | Argument | Default | Description |
+|---|---|---|---|
+| `--all-projects` | | Off | Also restore the Runtime registry and other projects' event stores the backup holds, rolling back every project on the machine |
 
-- Arguments: `<manifest>`, path to `manifest.json`.
-- No command-specific options.
-- Overwrites live stores, including the Runtime stores of every project the backup holds; it does not check whether the hub or the Runtime is running. Stop both before restoring.
-- Before overwriting anything, a restore checks every store's recorded schema version against the ceiling for that store, so a store newer than this build is refused (`runtime_schema_newer`) before the first file is replaced. `--dry-run` runs the same manifest, file, digest, and schema checks and plans each target it would overwrite (and any `-wal` or `-shm` sidecar it would delete) without touching them. Dry-run JSON keys: `backupId`, `manifestPath`, `stores` (`storeId`, `targetPath`, `schemaVersion`), `files` (`id`, `targetPath`), `dryRun`, `planned`.
-- JSON keys: `backupId`, `manifestPath`, `restoredStores` (`storeId`, `sourcePath`, `backupFile`, `schemaVersion`, `integrity`).
-- Exit 1 with `restore_failed`; `issues` carry codes such as `runtime_path_invalid`, `restore_manifest_invalid`, `restore_incomplete`, `restore_file_missing`, `restore_manifest_digest_mismatch`, and `runtime_schema_newer`.
+- Arguments: `<manifest>`, path to `manifest.json` or the directory that holds it.
+- Refuses before writing anything while the Runtime supervisor is running (`restore_runtime_running`), judged as `kxm runtime status` judges it but through a read-only open of the registry, and while a live `hub.pid` claim sits beside a hub store it would overwrite (`restore_hub_running`). Stop both first.
+- Before overwriting anything, a restore checks every store's recorded schema version against the ceiling for that store, so a store newer than this build is refused (`runtime_schema_newer`) before the first file is replaced. `--dry-run` runs the same manifest, file, digest, schema, scope, supervisor and hub checks and plans each target it would overwrite (and any `-wal` or `-shm` sidecar it would delete) without touching them. Dry-run JSON keys: `backupId`, `manifestPath`, `scope`, `stores` (`storeId`, `targetPath`, `schemaVersion`), `files` (`id`, `targetPath`), `dryRun`, `planned`.
+- JSON keys: `backupId`, `manifestPath`, `scope`, `restoredStores` (`storeId`, `sourcePath`, `backupFile`, `schemaVersion`, `integrity`). `scope` is absent for a manifest written before backups were scoped.
+- Exit 1 with `restore_failed`; `issues` carry codes such as `runtime_path_invalid`, `restore_manifest_invalid`, `restore_incomplete`, `restore_file_missing`, `restore_manifest_digest_mismatch`, `runtime_schema_newer`, `restore_requires_all_projects`, `restore_runtime_running`, `restore_runtime_unverified` (the registry could not be read to check the supervisor), and `restore_hub_running`.
 - Two more checks run per store while restoring, after the plan checks: a backup file whose schema version differs from the version the manifest records is refused with `runtime_schema_mismatch`, and one that fails its SQLite integrity check with `database_corrupted`. In a multi-store restore, stores restored before the refused one stay restored.
 
 ```bash
@@ -3414,13 +3423,22 @@ kxm restore ../bk/manifest.json --dry-run
 ```
 
 ```text
-dry run: restore 3 store(s) and 1 file(s) from /work/bk/manifest.json; digests verified against the manifest
+dry run: restore 2 store(s) and 1 file(s) from /work/bk/manifest.json; digests verified against the manifest
   would write /work/proj/.kxm/state/kxm.db
-  would write /home/me/.local/state/kxm/runtime/registry.db
   would write /home/me/.local/state/kxm/runtime/projects/38ed26cb8eeaa297f3b0b452/run-events.db
   would write /home/me/.local/state/kxm/runtime/projects/38ed26cb8eeaa297f3b0b452/run-events.db.run-prompts.json
 ```
 
+While the Runtime supervisor is running:
+
+```bash
+kxm restore ../bk/manifest.json
+```
+
+```text
+restore failed: /home/me/.local/state/kxm/runtime/registry.db: restore_runtime_running: the Runtime supervisor is running (pid 48213); stop it with `kxm runtime stop` and keep it stopped until the restore finishes
+```
+
 A missing manifest:
 
 ```bash

package/docs/reference/config-reference.md

@@ -1731,7 +1731,7 @@ Everything under `.kxm/` at the project root falls into one of three groups.
 | `logs/` | Ignored runtime logs | The hub and workers |
 | `state/` | Ignored restart state: the hub database `kxm.db`, Pi sessions, worker manifests | The hub and workers |
 | `run/` | Ignored sockets (`run/ssh-sockets/`) | `kxm ssh` |
-| `backups/` | Ignored; each `backup-<time>/` holds copies of the hub database, the Runtime stores and their prompt sidecars, and `manifest.json` | `kxm backup` (without `--out`) |
+| `backups/` | Ignored; each `backup-<time>/` holds copies of the hub database, this project's Runtime event store and prompt sidecar (every project's, and the registry, with `--all-projects`), and `manifest.json` | `kxm backup` (without `--out`) |
 | `config/` | Legacy: its JSON files make the project unloadable | Nothing current |
 | `.kxm-init-transaction/` (sibling of `.kxm/` at the Git root) | Ignored; interrupted `kxm init` state | `kxm init` |
 

package/docs/reference/workflow-definitions.md

@@ -1,6 +1,6 @@
 # Workflow definition reference
 
-KXM has two kinds of workflow definition. A **webhook workflow definition** is JSON that the [hub](../glossary.md#hub) loads; a signed webhook starts a run, and one coordinator agent works through its ordered **stages**. A **Runtime workflow** is a `kxm.workflow.v1` YAML file in your project; `kxm run` starts it, and the local Runtime executes its **steps**. This page compares the two, documents every field of the JSON format, and summarizes the YAML format with links to its full reference.
+KXM has two kinds of workflow definition. A **webhook workflow definition** is JSON that the [hub](../glossary.md#hub) loads; a signed webhook starts a run, and one coordinator agent works through its ordered **stages**. A **Runtime workflow** is a `kxm.workflow.v1` YAML file in your project; `kxm run` creates a run, and `kxm runs drive` executes supported **steps**. This page compares the two, documents every field of the JSON format, and summarizes the YAML format with links to its full reference.
 
 ## Two workflow systems
 
@@ -10,12 +10,12 @@ KXM has two kinds of workflow definition. A **webhook workflow definition** is J
 | Location | Any JSON file named by `KXM_WEBHOOK_WORKFLOWS_FILE`, or inline in `KXM_WEBHOOK_WORKFLOWS` | `.kxm/workflows/<id>.yaml`, tracked in Git |
 | Loaded by | The hub, once at start | Every project load (`kxm init`, `kxm run`) |
 | Units | Stages, in order | Steps, connected by typed transitions |
-| Started by | A signed `POST /v1/webhooks/<id>`, or `kxm workflow start` | `kxm run <workflow> [prompt]` |
+| Started by | A signed `POST /v1/webhooks/<id>`, or `kxm workflow start` | Create with `kxm run <workflow> [prompt]`, execute with `kxm runs drive <runId> --wait` |
 | Who does the work | One coordinator agent, prompted with every stage, using the [workflow tools](tools.md#workflow-tools) | The Runtime: agent steps through a model producer, gate steps by running `.kxm/gates.yaml` commands |
 | Evidence | Keyed strings plus verified peer replies | Gate evidence the Runtime records itself |
 | External results | `kxm_workflow_wait`, then a signed signal | Recovery signals only; `wait` steps compile but are not matched yet |
 | Inspect with | `kxm_workflow_get`, `kxm workflow get`, `kxm dash` | `kxm runs status`, `kxm runs list` |
-| Validate with | `kxm gate validate` | `kxm init --dry-run`, `kxm run --dry-run` |
+| Validate with | `kxm gate validate` | `kxm gate validate --file <yaml>` (schema/transitions), `kxm init --dry-run` (project references), `kxm run --dry-run` (run prerequisites) |
 
 Both kinds of run have IDs of the form `run_<32 hex>`. The journal, checkpoints and waits belong to webhook runs only.
 
@@ -274,7 +274,7 @@ A Runtime workflow is a YAML file whose name is its ID. The [configuration file
 | Agent steps | The model returns a JSON `outcome` from the step's declared keys; anything else becomes `failed`, so declare `failed` | [Transitions and outcomes](config-reference.md#transitions-and-outcomes) |
 | Not executed yet | Some valid fields make the Runtime hand the run off (`step_unsupported`, `gate_unsupported`, `limit_unsupported`) instead of executing | [Steps the Runtime does not execute yet](config-reference.md#steps-the-runtime-does-not-execute-yet) |
 
-`kxm workflow add --template <name>` writes a valid starting file from a built-in template (`implement-and-verify`, `dual-critic-review` or `spec-and-plan`). `kxm run <workflow>` creates a run and prints the commands that drive it with the model-free simulation (`kxm runs drive <runId> --simulated --wait`) or cancel it. See [`kxm run`](cli-reference.md#kxm-run) and [`kxm runs`](cli-reference.md#kxm-runs).
+`kxm workflow add bug-fix --template implement-and-verify` writes a valid starting file; `dual-critic-review` and `spec-and-plan` are also available. IDs are flat filename-derived slugs, not catalog paths such as `software-engineering/bug-fix`. Installation validates YAML/schema/transitions before writing, including under `--dry-run`. `kxm run <workflow>` creates a run and reports live prerequisites and separate `runs drive/status/receipt` commands. Current live one-shot profiles are read-only, so a writer template can validate but cannot execute live; `task run` refuses incompatible work before creating a run or changing the task. Simulation remains explicitly available and is not proof of implementation. See [`kxm run`](cli-reference.md#kxm-run) and [`kxm runs`](cli-reference.md#kxm-runs).
 
 ## Related
 

package/docs/start/first-workflow.md

@@ -153,13 +153,17 @@ The hash is the project's configuration revision, the same one `kxm trust diff`
 kxm run first "Plan a hello script"
 ```
 
-Expected output:
+Creation output includes:
 
 ```text
 run created: run_<id> (home rtm_<id>…, config sha256:<revision>…)
-drive it model-free: kxm runs drive run_<id> --simulated --wait (or cancel: kxm runs cancel run_<id>)
+No steps executed. Project default harness: pi; per-agent harness settings take precedence.
 ```
 
+The remaining output lists live prerequisites and the commands for `runs drive`,
+`runs status`, and `runs receipt`. A created run is not an executed workflow;
+the deliberate simulation below does not require a live authenticated model.
+
 `kxm run` starts the Runtime supervisor if it is not running. Check the new run, using the run ID from the output:
 
 ```bash

package/docs/start/quickstart-claude-code.md

@@ -38,6 +38,16 @@ In an interactive terminal, `kxm init` then offers shell completion and workflow
 
 > [!TIP]
 > If your tests do not run with `npm test`, change `gates.test.argv` in `.kxm/gates.yaml` now, before you commit.
+>
+> The starter settings are not repository detection. For a Claude project, set
+> `defaultHarness: claude` in `.kxm/project.yaml`, update any explicit `harness` overrides
+> in `.kxm/agents/*.yaml`, and configure compatible agent models;
+> `kxm harness list` reports that project default. Claude's Runtime one-shot profile is
+> read-only: a Claude-only bug-fix suggestion or incompatible `task run`
+> refuses with prerequisites rather than substituting another writer. Implement
+> directly in Claude Code, or use a genuinely read-only Runtime workflow. A local
+> `kxm run` only creates a run; execute supported work with `kxm runs drive <runId>
+> --wait` and inspect it with `kxm runs status`, not `kxm workflow get`.
 
 ### 2. Ignore runtime state and commit `.kxm/`
 
@@ -331,7 +341,7 @@ kxm runtime stop
 `kxm backup` writes a verified copy and a hashed manifest to `.kxm/backups/backup-<timestamp>/`.
 
 > [!WARNING]
-> `kxm backup` copies the hub store and the Runtime's registry and run event stores, and those Runtime stores belong to every project on this machine. A later `kxm restore` rolls all of them back. It does not copy bindings, `update.yaml` or the other state roots; [Back up everything else](../operations/backup-and-restore.md#back-up-everything-else) covers those.
+> `kxm backup` copies this project's hub store and its Runtime run event store. The Runtime registry and other projects' run stores are shared by every project on this machine, so they are copied only with `--all-projects`, and a later `kxm restore` refuses to roll them back without the same flag. It does not copy bindings, `update.yaml` or the other state roots; [Back up everything else](../operations/backup-and-restore.md#back-up-everything-else) covers those.
 
 [Back up and restore KXM](../operations/backup-and-restore.md) and [Upgrade KXM](../operations/upgrade.md) cover restores and rollback.
 

package/docs/templates/runbook.md

@@ -77,5 +77,6 @@ flowchart TD
 ## Rollback and escalation
 
 - **Rollback:** restore the last verified backup with
-  `kxm restore <manifest>` while the hub is stopped.
+  `kxm restore <manifest>` while the hub and the Runtime are stopped; it
+  refuses while either is running.
 - **Escalation:** <primary on-call or human operator contact>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontextmind/kxm",
-  "version": "0.7.103",
+  "version": "0.7.105",
   "description": "KXM local-first multi-agent orchestration and operator dashboard",
   "type": "module",
   "author": "KontextMind",

package/plugins/kxm/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "kxm",
   "displayName": "KXM",
-  "version": "0.7.103",
+  "version": "0.7.105",
   "description": "Headless multi-agent orchestration, durable workflows, and a live operator dashboard for Pi and Claude Code",
   "author": {
     "name": "KontextMind",