@kontextmind/kxm 0.7.94 → 0.7.96

package/docs/{cli-reference.md → reference/cli-reference.md}

@@ -1,8 +1,8 @@
 # KXM CLI reference
 
-This page documents every command and subcommand the `kxm` operator CLI registers in KXM 0.7.1 (`@kontextmind/kxm`). For each command it states what the command does, which files and services it reads and writes, whether it needs a running hub or the KXM Runtime supervisor, what `--json` returns, and the exit codes and refusal codes you are likely to see. It supersedes the "Complete CLI guide" section of the [KXM Handbook](kxm-handbook.md). Environment variables are described in [Configuration](configuration.md); this page names them only where a command reads them directly.
+This page documents every command and subcommand the `kxm` operator CLI registers (`@kontextmind/kxm`). For each command it states what the command does, which files and services it reads and writes, whether it needs a running hub or the KXM Runtime supervisor, what `--json` returns, and the exit codes and refusal codes you are likely to see. Environment variables are described in [Environment variables and limits](configuration.md); this page names them only where a command reads them directly.
 
-Output shown under examples was captured from KXM 0.7.1 run from a source checkout, inside a throwaway Git repository, with `HOME`, `KXM_STATE_HOME`, `KXM_USER_CONFIG_DIR`, and the XDG directories pointed at a temporary directory, no harness CLIs on `PATH`, and (where a hub was needed) a disposable hub on a random loopback port. Paths are shortened to `/work/proj` (the project), `/work/kxm` (the KXM checkout), `/state` (the user state root), and `~/.config/kxm` (the user config directory); session tokens are replaced with `<token>`, the machine's host name with `host.local`, and long JSON is trimmed with `...`. Every command either plans under `--dry-run` without changing anything or refuses the flag (see [Dry runs](#dry-runs)); the dry-run examples were captured from the current source tree, with a digest of the throwaway tree taken before and after to confirm that nothing was written. An example captioned "Not run" was not executed for this reference because it starts a long-lived process, writes durable state, stores credentials, or calls an external service; its output is not shown.
+Output shown under examples was captured from a source checkout, inside a throwaway Git repository, with `HOME`, `KXM_STATE_HOME`, `KXM_USER_CONFIG_DIR`, and the XDG directories pointed at a temporary directory, no harness CLIs on `PATH`, and (where a hub was needed) a disposable hub on a random loopback port. Paths are shortened to `/work/proj` (the project), `/work/kxm` (the KXM checkout), `/state` (the user state root), and `~/.config/kxm` (the user config directory); session tokens are replaced with `<token>`, the machine's host name with `host.local`, and long JSON is trimmed with `...`. Every command either plans under `--dry-run` without changing anything or refuses the flag (see [Dry runs](#dry-runs)); the dry-run examples were captured from the current source tree, with a digest of the throwaway tree taken before and after to confirm that nothing was written. An example captioned "Not run" was not executed for this reference because it starts a long-lived process, writes durable state, stores credentials, or calls an external service; its output is not shown.
 
 ## Contents
 
@@ -12,16 +12,16 @@ Output shown under examples was captured from KXM 0.7.1 run from a source checko
 - [Where commands read and write](#where-commands-read-and-write)
 - [Task to command](#task-to-command)
 - Setup: [`init`](#kxm-init), [`config`](#kxm-config), [`completion`](#kxm-completion), [`trust`](#kxm-trust)
-- Hub and sessions: [`hub`](#hub-commands), [`session`](#kxm-session), [`dash`](#kxm-dash), [`studio`](#kxm-studio)
+- Hub and sessions: [`hub`](#kxm-hub-view), [`session`](#kxm-session), [`dash`](#kxm-dash), [`studio`](#kxm-studio)
 - Harnesses, models, and roles: [`harness`](#kxm-harness), [`auth`](#kxm-auth), [`update`](#kxm-update), [`models`](#kxm-models), [`routes`](#kxm-routes), [`role`](#kxm-role)
 - Running work: [`run`](#kxm-run), [`runs`](#kxm-runs), [`runtime`](#kxm-runtime), [`agent`](#kxm-agent), [`workflow`](#kxm-workflow), [`gate`](#kxm-gate), [`peer`](#kxm-peer), [`task`](#kxm-task), [`goal`](#kxm-goal), [`suggest`](#kxm-suggest), [`explain`](#kxm-explain)
 - Context and learning: [`context`](#kxm-context), [`memory`](#kxm-memory), [`skills`](#kxm-skills), [`improve`](#kxm-improve), [`routing`](#kxm-routing)
 - Operations: [`backup`](#kxm-backup), [`restore`](#kxm-restore), [`tenant`](#kxm-tenant), [`ssh`](#kxm-ssh), [`help`](#kxm-help)
-- [Known behavior gaps in 0.7.1](#known-behavior-gaps-in-071)
+- [Known behavior gaps](#known-behavior-gaps)
 
 ## Invoking the CLI
 
-An installed CLI is on `PATH` as `kxm`. Install it from the versioned release tarball as described in the [KXM Handbook](kxm-handbook.md#install-the-kxm-operator-cli).
+An installed CLI is on `PATH` as `kxm`. Install it as described in [Install KXM](../start/install.md).
 
 ```bash
 kxm --help
@@ -128,11 +128,15 @@ For this page, 63 `--dry-run` invocations (every command in the first list, the
 | Code | Meaning |
 |---|---|
 | 0 | Success, including `--help`, `--version`, and dry-run plans. |
-| 1 | The command ran and failed or found a problem: an `ok: false` result, an unreachable hub for `hub view`, permission expansions for `trust check`, a stopped supervisor for `runtime status`, missing local state, or a planning-only `init`. |
-| 2 | Usage error: unknown command or option, a missing argument or required option, a value KXM rejects before acting, `--workspace` where unsupported, conflicting flags, a group run without a subcommand, a removed command (`removed_command`), or `--dry-run` on a command that cannot plan (`dry_run_unsupported`). |
+| 1 | The command ran and failed or found a problem (see below). |
+| 2 | Usage error: the command refused before acting (see below). |
 | 4 | `gate github watch` timed out and posted (or, under `--dry-run`, would have posted) a signed `failed` signal. |
 | other | `hub start` and `agent worker` return the exit code of the foreground process; `ssh run` returns the remote command's exit code. |
 
+Exit 1 covers an `ok: false` result, an unreachable hub for `hub view`, permission expansions for `trust check`, a stopped supervisor for `runtime status`, missing local state, and a planning-only `init`.
+
+Exit 2 covers an unknown command or option, a missing argument or required option, a value KXM rejects before acting, `--workspace` where unsupported, conflicting flags, a group run without a subcommand, a removed command (`removed_command`), and `--dry-run` on a command that cannot plan (`dry_run_unsupported`).
+
 ## Where commands read and write
 
 | Location | Contents | Used by |
@@ -334,7 +338,7 @@ kxm config set hub.autoStart off --scope user
 kxm completion <bash|zsh|fish>
 ```
 
-Prints a shell completion script to stdout. With no shell, prints `usage: kxm completion <bash|zsh|fish> | kxm completion install [--shell <shell>] [--no-path]` on stderr and exits 2; an unsupported shell exits 1. The script is printed as text even with `--json`. The generated command list lags the CLI in 0.7.1 (see [Known behavior gaps](#known-behavior-gaps-in-071)).
+Prints a shell completion script to stdout. With no shell, prints `usage: kxm completion <bash|zsh|fish> | kxm completion install [--shell <shell>] [--no-path]` on stderr and exits 2; an unsupported shell exits 1. The script is printed as text even with `--json`. The generated command list lags the CLI (see [Known behavior gaps](#known-behavior-gaps)).
 
 - Arguments: `[shell]`, one of `bash`, `zsh`, `fish` (or the `install` subcommand).
 - Reads only.
@@ -383,6 +387,8 @@ kxm completion install --shell zsh --dry-run
 
 Compares the authority-bearing fields of the project configuration against a base Git revision. The base is materialized into a temporary shadow with a sanitized environment; nothing in the project is written. Both subcommands refuse `--workspace` (exit 2) and need no hub.
 
+The comparison covers the loaded bundle only: `project.yaml`, `agents/`, `models/`, `workflows/`, `gates.yaml`, `project/env.yaml`, and each member repository's `repo.yaml` and `env.yaml`. It does not read `routes.yaml`, `roles/`, `roster.yaml`, or `prices.yaml`, so a new route admission, roster entry, developer-roster route, or price change never counts as an expansion. Review those files by hand.
+
 ### `kxm trust diff`
 
 ```text
@@ -778,13 +784,13 @@ would signal pid files
 kxm dash [--screen <name>]
 ```
 
-Opens the live, read-only dashboard over the hub's server-sent events and the local hub store. On a terminal it is interactive (`1`–`7` switch tabs, `h` help, `q` quit). Without a terminal it prints one plain snapshot and exits.
+Opens the live dashboard over the hub's server-sent events and a read-only snapshot of the local hub store. On a terminal it is interactive (`1`–`7` switch tabs, `h` help, `q` quit). Without a terminal it prints one plain snapshot and exits.
 
 | Option | Argument | Default | Description |
 |---|---|---|---|
 | `--screen` | `<name>` | `agents` | agents, tasks, workflows, plans, inbox, procs, or spend |
 
-- Needs a hub for live data. Reads only.
+- Needs a hub for live data. Treat it as an observer: its action keys `a`, `r`, `s` and `c` post to hub routes that do not exist, so they change nothing even though the status line reports success, and `d` creates a git branch and worktree (see [Monitor KXM](../operations/monitoring.md#watch-live-work-with-kxm-dash)).
 - `--json` is refused (exit 2); use `kxm hub view`. An unknown screen exits 2 with `unknown_screen`. `--dry-run` prints `serverUrl`, `transport`, and `screen`.
 
 ```bash
@@ -837,7 +843,10 @@ kxm studio layout --json
 kxm studio serve [-p <port>] [--host <host>] [--token <token>]
 ```
 
-Serves the Web Studio on `http://127.0.0.1:4242` until interrupted. It serves `/`, `/health`, `GET /api/layout`, and `POST /api/mutate`; mutations require the session token. The plan comes from `.kxm/workflows/default.yaml` in the current directory, or the first YAML file in `.kxm/workflows/`.
+Serves the Web Studio on `http://127.0.0.1:4242` until interrupted. It serves `/`, `/health`, `GET /api/layout`, and `POST /api/mutate`. The plan comes from `.kxm/workflows/default.yaml` in the current directory, or the first YAML file in `.kxm/workflows/`.
+
+> [!WARNING]
+> Every response carries `Access-Control-Allow-Origin: *`, so any web page open in a browser on this machine can read `/api/layout` (your workflow plan). `POST /api/mutate` requires `Authorization: Bearer <session token>` only when a session token resolves (`--token`, `KXM_SESSION_TOKEN`, or the on-disk token); with none, it accepts any caller. It accepts an allowlisted command name and answers `ok: true`, but executes nothing. Keep the default loopback `--host`.
 
 | Option | Argument | Default | Description |
 |---|---|---|---|
@@ -875,6 +884,7 @@ No command-specific options.
 
 - Reads only. No hub needed. Always exits 0.
 - JSON keys: `defaultHarness`, `harnesses` (each with `id`, `label`, `default`, `mode`, `detected`, `authenticated`, `dispatch` (`status`, `supported`, `reason`), `canUpdate` (`self`, `extensions`, `models`), `issues`).
+- `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`:
 
@@ -1005,6 +1015,8 @@ kxm models
 Opens an interactive screen over `.kxm/models/inventory.yaml` that shows each model's route state and role bindings. Keys: `a` admit, `d` disable, `r` add a role binding, `x` remove a role binding, `q` quit. Changes are written to `.kxm/routes.yaml` and `.kxm/roles/<role>.yaml` in `KXM_WORKDIR` or the current directory.
 
 - Needs an interactive terminal. With `--json` or without a TTY it exits 2 with `interactive_tty_required`.
+- `r` and `x` also mark the model `admitted` in `.kxm/routes.yaml`. So `x` re-admits a disabled route while it removes the role binding, and `r` admits the route as well as binding it.
+- `r` writes a roster entry `{model: <inventory id>, enabled: true}` with no harness, creating the role file if needed. The inventory id is often a bare model (`grok-4.6`), which the Runtime's roster check does not match against an agent's `provider/model`; edit the entry to the full selector.
 
 ```bash
 kxm models --json
@@ -1198,6 +1210,9 @@ Adds a role definition. Without a role ID, or with `--pick`, you choose from the
 - Writes `<scope dir>/roles/<id>.yaml`. `--dry-run` plans the write and writes nothing.
 - JSON keys: `roleId`, `id`, `filePath`, `scope`.
 
+> [!WARNING]
+> Most built-in template entries, and `--model` as you type it, are bare model IDs such as `grok-4.6`, `fable`, and `gemini-2.5-pro`. The Runtime's roster check needs the agent's full `provider/model` selector, so a live attempt under a local `writer.yaml` copied from the template is refused (`producer_route_unsupported: … not in role 'writer' roster`). Write `--model xai/grok-4.6`, or edit the entries to full selectors, before you drive live runs.
+
 ```bash
 kxm role add demo-role --description "Demo role" --dry-run --json
 ```
@@ -1281,7 +1296,7 @@ kxm role modify reviewer --add-model claude:fable --add-skill kxm-peer
 kxm role hosts [--scope all|global|local]
 ```
 
-Lists role seats (`critic-arch`, `critic-cli`, `planner`, `verifier`, `writer`, plus any configured seat) and the host, model, and effort each resolves to, with the source of the decision (`override`, `role-hosts`, `seat-default`, `role-roster`, or `fallback`).
+Lists role seats (`critic-arch`, `critic-cli`, `planner`, `verifier`, `writer`, plus any configured seat) and the host, model, and effort each resolves to, with the source of the decision (`override`, `role-hosts`, `seat-default`, `role-roster`, or `fallback`). The listing is display-only: no dispatch path reads seats or `role-hosts.yaml`, so a run's harness and model still come from the agent file.
 
 | Option | Argument | Default | Description |
 |---|---|---|---|
@@ -1308,7 +1323,7 @@ ROLE SEATS (default):
 kxm role set-host <seatId> <host> [--model <model>] [--effort low|medium|high|xhigh] [--scope global|local]
 ```
 
-Binds a role seat to a host in `role-hosts.yaml`.
+Binds a role seat to a host in `role-hosts.yaml`. The binding changes what `kxm role hosts` shows, not what runs.
 
 | Option | Argument | Default | Description |
 |---|---|---|---|
@@ -1338,6 +1353,7 @@ Resumes an audit-escalated run with an operator directive. The default ruling is
 - Arguments: `<runId>`; `[ruling]`, free text recorded with the decision.
 - For a KXM run ID (`run_` followed by 32 hex digits) inside a project, posts an `audit_escalation` signal with action `unblock` to the Runtime, starting the supervisor if needed. `--dry-run` plans the request without starting the supervisor. JSON keys: `runId`, `ruling`, `unblocked`.
 - For any other ID, updates the hub store at `.kxm/state/kxm.db` in the current directory directly (ignoring `--workspace` and `KXM_DATA_PATH`) and adds a `decision` journal entry. `--dry-run` reads the store read-only, reports the stage it would resume and the resulting `status`, and plans the write. JSON keys: `runId`, `stageId`, `ruling`, `status`.
+- The hub-run path bypasses the hub even while one is running: it writes SQLite directly, without authentication, in two statements outside one transaction. A running hub keeps runs in memory, so it does not see the change until it restarts, and its next write to that run overwrites it; it also pushes no event and sends the coordinator no resume message. Stop the hub first, or resume a live hub's run with a signed `audit_escalation` signal (see [Waits, signals and escalation](workflow-definitions.md#waits-signals-and-escalation)).
 - Errors: `resume_failed` (exit 1), or a plain `not found` line (exit 1).
 
 ```bash
@@ -1365,9 +1381,9 @@ 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, and it stores only a hash of the prompt. 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 (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.
 
-- Arguments: `<workflow>`, Workflow id to run (a file under `.kxm/workflows/`); `[prompt...]`, Run prompt (hashed, never stored raw).
+- 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.
@@ -1663,10 +1679,11 @@ Starts a long-lived, supervised Pi RPC worker in the foreground through `scripts
 - Needs Pi and a reachable hub. Runs until stopped (`kxm hub stop` stops managed workers too). The exit code is the worker's.
 - A name and project are required (exit 2 otherwise); an invalid isolation mode exits 2.
 - `--dry-run` prints a `kxm.worker-result.v1` envelope with `workspace`, `name`, `project`, `model`, `fallbackModels`, `tools`, `sessionIsolation`, `continue`, `freshStart`.
-- The remaining worker variables are described in [Configuration](configuration.md#long-lived-worker-settings).
+- Before Pi starts, the worker runs `--model` and every `--fallback-models` entry through the Pi native-vendor brake. A model whose vendor has its own harness (for example `xai/…`, `openai-codex/…`, `openrouter/x-ai/…` or `antigravity/claude-…`) exits 1 with `pi_native_impersonation_blocked: <message>` on stderr; use the native harness, or an admitted Pi route such as `openrouter/qwen/qwen3-coder-plus`. `--dry-run` does not run this check. See [Harness routing](harness-routing.md#what-the-brake-refuses).
+- The remaining worker variables are described in [Long-lived worker settings](configuration.md#long-lived-worker-settings).
 
 ```bash
-kxm agent worker --name reviewer --project demo --model xai/grok-4.6 --tools read,grep,find,ls --session-isolation workflow --fresh-start --dry-run
+kxm agent worker --name reviewer --project demo --model openrouter/qwen/qwen3-coder-plus --tools read,grep,find,ls --session-isolation workflow --fresh-start --dry-run
 ```
 
 ```text
@@ -1674,7 +1691,7 @@ would start worker
 ```
 
 ```bash
-kxm agent worker --name coordinator --project demo --model antigravity/claude-sonnet-4-6 --fallback-models xai/grok-4.6 --session-isolation workflow
+kxm agent worker --name coordinator --project demo --model openrouter/qwen/qwen3-coder-plus --session-isolation workflow
 ```
 
 Not run: starts a long-lived Pi worker.
@@ -1809,7 +1826,7 @@ kxm workflow record wf_123 lesson "Flaky test hid a race" --stage-id verify --ev
 kxm workflow wait [runId] [stageId] [signalKey] [summary] [--evidence <json>] [--evidence-refs <json>] [--timeout-ms <ms>]
 ```
 
-Wait for a workflow signal callback: pauses the active stage until a signed external callback checkpoints it. For a KXM run ID (`run_` followed by 32 hex digits) inside a project, the wait is registered with the Runtime instead of the hub (the supervisor starts if needed).
+Wait for a workflow signal callback: pauses the active stage until a signed external callback checkpoints it. For a KXM run ID (`run_` followed by 32 hex digits) inside a project, the command posts to the Runtime instead of the hub (the supervisor starts if needed). The Runtime has no wait state yet: it checks that the run exists, answers `waiting: true`, and records nothing, so the command prints `waiting for signal on KXM run <id>` although the run is unchanged.
 
 | Option | Argument | Default | Description |
 |---|---|---|---|
@@ -1823,7 +1840,7 @@ Wait for a workflow signal callback: pauses the active stage until a signed exte
 | `--payload` | `<json>` | none | JSON payload |
 
 - `--timeout-ms` accepts 1000 through 2592000000 (30 days).
-- Needs a hub (or the Runtime for KXM runs). Mutates the run. Honors `--dry-run`.
+- Needs a hub (or the Runtime for KXM runs). Mutates a hub run; changes nothing for a Runtime run. Honors `--dry-run`.
 
 ```bash
 kxm workflow wait wf_123 verify github-pr-42-checks "Waiting on CI" --timeout-ms 3600000 --dry-run --json
@@ -2521,7 +2538,7 @@ dry run: run workflow default for task task_4f79c0833e41, then mark it in_progre
 kxm task sync <taskId>
 ```
 
-Sync task status and evidence with its linked issue board. In 0.7.1 this is local only: it marks the task's tracker link `synced` and updates timestamps without contacting GitHub or Jira.
+Sync task status and evidence with its linked issue board. Today this is local only: it marks the task's tracker link `synced` and updates timestamps without contacting GitHub or Jira.
 
 - Writes the task file. `--dry-run` returns the synced task and plans the write without making it. JSON keys: `task`.
 - Exit 1 when the task does not exist or has no tracker link.
@@ -2669,7 +2686,7 @@ kxm explain --mode planner --domains git,k8s --model grok/grok-4.6 --json
 
 ## `kxm context`
 
-KXM context operating-system queries. Every subcommand POSTs to the hub's `/v1/context/*` API as the control plane, authenticating only with `KXM_AUTH_TOKEN` (the persisted `hub-env.json` credential is not used; without the variable the hub answers 401 `invalid_auth`). The first argument is the project scope. Results carry the hub's HTTP `status` and response fields. Exit 0 on a 2xx response, 1 otherwise. An unreachable hub crashes the command with a stack trace (exit 1, no JSON). Agents reach the same data through the `kxm_context`, `kxm_recall`, `kxm_state`, `kxm_episode`, and `kxm_promote` tools; there is no `kxm_explain` tool.
+KXM context operating-system queries. Every subcommand POSTs to the hub's `/v1/context/*` API as the control plane, authenticating only with `KXM_AUTH_TOKEN` (the persisted `hub-env.json` credential is not used; without the variable a hub that has an admin token answers 401 `invalid_auth`, while a loopback hub with no admin token accepts the call). The first argument is the project scope. Results carry the hub's HTTP `status` and response fields. Exit 0 on a 2xx response, 1 otherwise. An unreachable hub crashes the command with a stack trace (exit 1, no JSON). Agents reach the same data through the `kxm_context`, `kxm_recall`, `kxm_state`, `kxm_episode`, and `kxm_promote` tools; there is no `kxm_explain` tool.
 
 ### `kxm context get`
 
@@ -2689,6 +2706,7 @@ Assemble a role-aware context packet within a token budget.
 | `--kinds` | `<kinds>` | all | Comma-separated item kinds to include |
 
 - `--budget` must be an integer from 512 to 200000 (exit 2).
+- `--run` and `--stage` do not filter the packet: selection draws on the whole project either way. The hub only echoes them in `audit.request` and its log.
 - Reads only. Output keys: `status`, `packet` (`workingState`, `currentState`, `knowledge`, `evidence`, `episodes`, `skills`, `contradictions`, `unresolvedGaps`, `provenanceSummary`, `estimatedTokens`), `audit`.
 - Selection is deterministic. Eligible items are ordered by open contradiction, project before `_shared`, task-matched before unmatched, role kind priority, lexical BM25 relevance to `--task`, confidence, authority, recency (newest first), then id. The budget is filled first-fit: an item that does not fit is skipped and smaller ones still fill it.
 - `audit.relevance` holds numbers only: `taskTokens` (distinct task words after stopword removal), `matchedCandidates` (eligible items sharing a task word) and `selected` (each selected item's rounded score, in `selectedIds` order).
@@ -2948,27 +2966,39 @@ kxm memory note "Use pnpm, not npm" --kind convention --dry-run --json
 kxm memory sync
 ```
 
-Regenerate memory projection blocks across AGENTS.md, CLAUDE.md, and GEMINI.md: rewrites the section between `<!-- kxm:memory:start -->` and `<!-- kxm:memory:end -->` in each file from the active facts.
+Regenerate the memory block in whichever of `AGENTS.md`, `CLAUDE.md` and `GEMINI.md` exist in the current directory; never creates them.
 
 No command-specific options.
 
-- Writes up to three files in the current directory. `--dry-run` reports which files it would update or create and plans the writes without making them.
-- Warning: a missing `CLAUDE.md` or `GEMINI.md` is created with a header copied from the KXM repository's own agent instructions (planner role, Grok as default writer, links to `plans/implementation-plan.md`). Review or replace the header before committing in another project.
-- JSON keys: `updated`, `created`.
+- Writes only the project's memory block, the active authored facts from `.kxm/memory/`, between `<!-- kxm:memory:start -->` and `<!-- kxm:memory:end -->`. A file without markers gets the block appended at its end. Nothing outside the markers changes, and KXM adds no instructions of its own.
+- Updates only the files that already exist. When none of the three exists, it writes nothing and exits 1 with `memory sync failed: none of AGENTS.md, CLAUDE.md, GEMINI.md exists in <dir>; …`.
+- Refuses malformed markers. Each file must hold exactly one start marker followed by one end marker, or neither. An orphan marker, an end before its start, or a second block exits 1 with `memory sync failed: <file> has <problem>; wrote no file. …`, and no file is written. Keep one pair, or delete both so sync appends a fresh block.
+- `--dry-run` runs the same checks, lists the files it would change, and writes nothing.
+- Refusals are plain text on stderr, also under `--json`. JSON keys: `updated`, `unchanged`, `missing` (files that do not exist and were not created).
 
-In a project without these files:
+In a project that has only `AGENTS.md`, with no memory block yet:
 
 ```bash
 kxm memory sync --dry-run --json
 ```
 
 ```text
-{"schema":"kxm.cli-result.v1","ok":true,"command":"memory sync","updated":[],"created":["AGENTS.md","CLAUDE.md","GEMINI.md"],"dryRun":true,"planned":[{"action":"write","target":"/work/proj/AGENTS.md"},{"action":"write","target":"/work/proj/CLAUDE.md"},{"action":"write","target":"/work/proj/GEMINI.md"}]}
+{"schema":"kxm.cli-result.v1","ok":true,"command":"memory sync","updated":["AGENTS.md"],"unchanged":[],"missing":["CLAUDE.md","GEMINI.md"],"dryRun":true,"planned":[{"action":"write","target":"/work/proj/AGENTS.md"}]}
+```
+
+With a stray start marker in `CLAUDE.md`:
+
+```bash
+kxm memory sync
+```
+
+```text
+memory sync failed: CLAUDE.md has <!-- kxm:memory:start --> with no <!-- kxm:memory:end -->; wrote no file. Keep exactly one <!-- kxm:memory:start --> followed by one <!-- kxm:memory:end --> in each file, or delete both so sync appends a fresh block
 ```
 
 ## `kxm skills`
 
-Governed skill candidate lifecycle under `.kxm/skills/` in `KXM_WORKDIR` or the current directory: `candidates/`, `promoted/`, `quarantined/`, `rejected/`, `history/<id>.jsonl`, and `patches/<id>.patch`. No hub needed. Errors are plain text on stderr.
+Governed skill candidate lifecycle under `.kxm/skills/` in `KXM_WORKDIR` or the current directory: `candidates/`, `promoted/`, `quarantineds/`, `rejected/`, `history/<id>.jsonl`, and `patches/<id>.patch`. No hub needed. Errors are plain text on stderr.
 
 ### `kxm skills create`
 
@@ -2994,7 +3024,7 @@ Submit a skill candidate from verified episodes.
 - Writes a candidate. Honors `--dry-run`. JSON keys: `metadata` (or `name` for a dry run).
 
 ```bash
-kxm skills create --file SKILL.md --name retry-backoff --created-by alice --harness pi --models xai/grok-4.6 --run wf_123 --dry-run --json
+kxm skills create --file SKILL.md --name retry-backoff --created-by alice --harness pi --models openrouter/qwen/qwen3-coder-plus --run wf_123 --dry-run --json
 ```
 
 ```text
@@ -3017,7 +3047,7 @@ Record a protected evaluation for a candidate. A failed evaluation can quarantin
 | `--score` | `<n>` | none | Numeric score |
 | `--details` | `<text>` | none | Bounded evaluation details |
 
-- Arguments: `<skillId>`, Skill candidate ID. Mutates. `--dry-run` returns the evaluation and whether it would quarantine the candidate, and plans the history write (and the move to `quarantined/`) without making them.
+- Arguments: `<skillId>`, Skill candidate ID. Mutates. `--dry-run` returns the evaluation and whether it would quarantine the candidate, and plans the history write (and the move to `quarantineds/`) without making them.
 - JSON keys: `skillId`, `quarantined`, `evaluation`.
 
 ```bash
@@ -3207,13 +3237,16 @@ Without `--file` it reads the same sources as [`kxm improve report`](#kxm-improv
 
 | Option | Argument | Default | Description |
 |---|---|---|---|
-| `-f`, `--file` | `<path>` | the Runtime store, then workspace telemetry | Telemetry or event log JSONL file (default: workspace telemetry) |
+| `-f`, `--file` | `<path>` | the Runtime store, then workspace telemetry | Read only this telemetry or event log JSONL file (default: this project's Runtime event store plus workspace telemetry) |
 | `-l`, `--equivalent-list-cost` | none | off | Include equivalent list price column using price catalog |
 | `--list-prices` | none | off | Alias for --equivalent-list-cost |
 | `--prices` | `<path>` | `.kxm/prices.yaml` | Path to price catalog (default: .kxm/prices.yaml) |
 
 - Reads only. A price catalog that cannot be loaded is skipped silently.
-- The `--file` help text still says `(default: workspace telemetry)`; without `--file` the Runtime store is read first, as described above. A Runtime store that exists but cannot be read exits 1 with `improve_source_unreadable`.
+- `--equivalent-list-cost` loads the catalog without the freshness check the producers apply, so it prices with a catalog of any date, including one the producers treat as stale. Check the catalog `date` before you rely on `ListEquiv($)`.
+- A Runtime store that exists but cannot be read exits 1 with `improve_source_unreadable`.
+- Ranking: quality first (Pass%, then Rwk%), then cost per accepted attempt. Among routes of equal quality, any route with an unknown-cost attempt ranks after every route without one. `$/Acc` still shows only the priced part, so a route mixing unmetered and unknown-cost attempts can read `$0.0000`; the `*` in `Unk` marks it.
+- The `Quota` column counts attempts whose metadata looks quota-exhausted (a quota failure class, a `quota` flag, or text such as `rate limit` or `HTTP 429`). It is a count only: nothing fails over to another route.
 - The text output does not list the sources, and prints `no routing records in telemetry` when no source holds a record. The Rwk% column counts records with `transitions` greater than 0, which Runtime records never set.
 - JSON keys: `file` (the telemetry path, also when the Runtime store was read), `sources` (without `--file`; the same shape as in `kxm improve`), `configurations` (per behavioral hash for v1 records), `report` (`schema`, `generatedAt`, `totalAttempts`, `rows`).
 
@@ -3251,7 +3284,7 @@ no routing records in telemetry
 kxm routing benchmark [--task <fixture>] [--arms <models>] [--runs <count>]
 ```
 
-Dedicated offline benchmark for side-by-side model comparison (Decision Q12). In 0.7.1 this prints fixed placeholder figures: it does not run any model, read the task, or measure anything. Latency, tokens, cost, and outcome are constants chosen from the model name. Do not use its output for routing decisions.
+Dedicated offline benchmark for side-by-side model comparison (Decision Q12). Today this prints fixed placeholder figures: it does not run any model, read the task, or measure anything. Latency, tokens, cost, and outcome are constants chosen from the model name. Do not use its output for routing decisions.
 
 | Option | Argument | Default | Description |
 |---|---|---|---|
@@ -3279,7 +3312,7 @@ pi         qwen3-coder-plus                  560       1200        450      $0.1
 kxm backup [--out <dir>]
 ```
 
-Creates a verified SQLite backup with a hashed `kxm.backup-manifest.v1` manifest. It discovers stores relative to the current directory: the hub store `.kxm/state/kxm.db`, and `registry.db`, `bindings.db`, and `events/*.db` under `.kxm/runtime/`. It ignores `--workspace` and `KXM_DATA_PATH`, and it does not include the Runtime supervisor's stores under the user state root.
+Creates a verified SQLite backup of the project hub store, with a hashed `kxm.backup-manifest.v1` manifest (Runtime stores under the user state root are not included). It discovers stores relative to the current directory: the hub store `.kxm/state/kxm.db`, and any `registry.db`, `bindings.db`, and `events/*.db` it finds under `.kxm/runtime/`. The Runtime writes its stores under the user state root instead, so a backup normally holds only the hub store and `manifest.json`. It ignores `--workspace` and `KXM_DATA_PATH`. To back up the Runtime, see [Backup and restore](../operations/backup-and-restore.md).
 
 | Option | Argument | Default | Description |
 |---|---|---|---|
@@ -3335,6 +3368,7 @@ Restores SQLite stores from a verified backup manifest. It checks the manifest s
 - 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`), `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_file_missing`, `restore_manifest_digest_mismatch`, and `runtime_schema_newer`.
+- 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
 kxm restore ../bk/manifest.json --dry-run
@@ -3393,7 +3427,9 @@ kxm tenant status --json
 
 ## `kxm ssh`
 
-Multiplexed remote SSH execution. Commands reuse an OpenSSH ControlMaster socket in `.kxm/run/ssh-sockets/` in the current directory (`ControlPersist=10m`, `BatchMode=yes`, `StrictHostKeyChecking=yes`, 120 second timeout). JSON results carry `ok`, `action`, `host`, and the fields below, but no `command` field except `ssh close`. Under `--dry-run`, `ssh run`, `ssh file`, and `ssh close` connect to nothing: they print a plan (`command`, `host`, the remote command or path, `dryRun`, and `planned` with action `ssh`) instead. `ssh info` reads only, with or without the flag.
+Multiplexed remote SSH execution. Commands reuse an OpenSSH ControlMaster socket in `.kxm/run/ssh-sockets/` in the current directory (`ControlPersist=10m`, `BatchMode=yes`, `StrictHostKeyChecking=yes`; 120 second timeout, 60 seconds for `ssh file` writes).
+
+Host keys must already be pinned: with those options, OpenSSH refuses a host whose key is not in your `known_hosts` instead of prompting, so add the key yourself (for example with `ssh <host>` once) before the first `kxm ssh` call. KXM also refuses any option that would weaken the check (`StrictHostKeyChecking=accept-new`, `no` or `off`, or `UserKnownHostsFile=/dev/null`). JSON results carry `ok`, `action`, `host`, and the fields below, but no `command` field except `ssh close`. Under `--dry-run`, `ssh run`, `ssh file`, and `ssh close` connect to nothing: they print a plan (`command`, `host`, the remote command or path, `dryRun`, and `planned` with action `ssh`) instead. `ssh info` reads only, with or without the flag.
 
 ### `kxm ssh info`
 
@@ -3428,7 +3464,7 @@ kxm ssh info --json
 kxm ssh run <host> <command...> [--sudo]
 ```
 
-Execute a command on a remote SSH host via multiplexed ControlMaster socket. Commands that match KXM's destructive-command patterns are refused before connecting.
+Execute a command on a remote SSH host via multiplexed ControlMaster socket. Commands that match KXM's destructive-command patterns (`rm` with recursive and force flags, `git reset --hard`, `git clean -f`, `git checkout --` with paths, and `git restore .` or `*`) are refused before connecting.
 
 | Option | Argument | Default | Description |
 |---|---|---|---|
@@ -3436,6 +3472,7 @@ Execute a command on a remote SSH host via multiplexed ControlMaster socket. Com
 
 - Connects to the remote host and runs the command. `--dry-run` connects to nothing and prints the command it would run.
 - JSON keys: `exitCode`, `stdout`, `stderr`, `truncated`, `socketReused`, `durationMs`, `error`. The exit code is the remote command's.
+- stdout and stderr are each capped at 50 KB and 2,000 lines. Longer output is cut, ends with `[kxm: ssh output truncated to 50KB / 2000 lines]`, and sets `truncated: true`. Output over 10 MB fails the command. `ssh file --read` uses the same caps.
 
 ```bash
 kxm ssh run build-01 uptime --dry-run
@@ -3511,17 +3548,22 @@ Inspect KXM runs
 ...
 ```
 
-## Known behavior gaps in 0.7.1
+## Known behavior gaps
 
 These are behaviors of the current build that differ from what the help text or the flag names suggest. Each is also noted in the command's section.
 
 - The `default` workflow that `kxm init` writes sets `limits.maxAgentTimeMs`, so `kxm runs drive` hands every run of it off with `run_handoff_required` (`limit_unsupported`). Use a `kxm workflow add --template` workflow, or remove the limit, to drive a first run.
-- `kxm memory sync` creates `CLAUDE.md` and `GEMINI.md` with headers taken from the KXM repository's own instructions.
 - `kxm routing benchmark` prints constant placeholder figures.
 - `kxm task sync` does not contact GitHub or Jira.
-- `kxm runs drive` without `--simulated` runs live harness calls, although its description says "model-free simulation".
 - `kxm peer inbox` always returns an empty list from the CLI.
 - `kxm context` subcommands crash with a stack trace when the hub is unreachable, and they ignore the persisted hub credential.
 - `kxm completion <shell>` generates a command list that includes a nonexistent `plan` command, omits `models`, `routes`, `explain`, and `ssh`, lists a nonexistent `goal get`, and omits `runs drive`, `runs receipt`, `runtime sync-retry`, and `improve report`.
-- `kxm backup` does not include the Runtime supervisor's stores under the user state root, and its JSON shows `manifestSha256` redacted.
+- `kxm backup` JSON shows `manifestSha256` redacted.
 - `--help` after an unknown subcommand (for example `kxm hub nope --help`) prints the parent group's help and exits 0, so `--help` cannot be used to test whether a subcommand exists; compare the `Usage:` line instead.
+
+## Related
+
+- [Environment variables and limits](configuration.md): every variable the commands read
+- [Configuration file reference](config-reference.md): the files the commands read and write
+- [Agent tools](tools.md): the `kxm_*` tools behind `kxm peer` and `kxm workflow`
+- [Hub HTTP API](http-api.md): the routes the commands call