@kontextmind/kxm 0.7.91 → 0.7.93

package/.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
       "name": "kxm",
       "source": "./plugins/kxm",
       "description": "Durable workflows, peer agents, and kxm tui",
-      "version": "0.7.91",
+      "version": "0.7.93",
       "category": "development",
       "tags": ["kxm", "multi-agent", "workflows", "mcp"]
     }

package/.kxm/workflows/default.yaml

@@ -42,6 +42,6 @@ steps:
       passed:
         target: $terminal
         terminalStatus: completed
-      failed:
+      implementation-failure:
         target: implement
         maxTransitions: 2

package/CHANGELOG.md

@@ -6,6 +6,18 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Added
 
+- **`kxm workflow add --template <name>` writes a valid first workflow.**
+  `implement-and-verify` (the `implementer` agent, then the project's `test` gate; a
+  failing gate sends the work back to `implement` at most twice), `dual-critic-review` (two
+  review steps run as the `coordinator` agent between them) and `spec-and-plan` (plan, then
+  review the plan, both as `coordinator`, read-only) are written under the workflow id you
+  give. Each uses only what `kxm init` creates, the `coordinator` and `implementer` agents,
+  the `control` repository and the `test` gate, so it loads and plans as generated.
+  `--template` needs a workflow id (`workflow_id_required`), cannot be combined with
+  `--file` or `--pick` (`workflow_add_conflict`), and names the three templates when the
+  name is unknown (`workflow_template_unknown`); the three refusals exit 2 and honour
+  `--json`.
+
 - **Fenced hub leases, and shared external effects that will not run without one.**
   `POST /v1/leases/:resource/acquire|renew|release` are agent-authenticated and
   project-scoped (the hub prefixes the caller's project onto the resource name). Each call
@@ -57,6 +69,127 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Changed
 
+- **The workflow loader refuses a gate step that can never settle
+  (`gate_outcome_impossible`).** A gate step settles only on `passed` or
+  `implementation-failure` when `expect` is `pass`, and only on `passed` or `repro-missing`
+  when `expect` is `fail`. A step that declares an outcome it never produces (typically
+  `failed`) and leaves one it does produce undeclared is now a load error naming the
+  outcomes to declare, so `kxm init`, `kxm run` and `kxm run --dry-run` report it before a
+  run exists. Such a workflow used to load, and a failing gate attempt could not settle:
+  the run was handed off with `attempt_unsettled` and later gate steps in the project were
+  held with `gate_recovery_pending`. An extra outcome next to every produced one still
+  loads, as in the `verify` step `kxm init` writes. This repository's `default` workflow,
+  the example project and the unsupported-gate fixture now route gate failures on
+  `implementation-failure`. **Check your workflows:** a gate step that routes failures only
+  on `failed` no longer loads.
+- **`kxm run` prints how to drive the run it created, and drive refusals say why.** The
+  text output's second line is
+  `drive it model-free: kxm runs drive <runId> --simulated --wait (or cancel: kxm runs cancel <runId>)`,
+  and the command's help now reads "Create a KXM run (offline-first;
+  `kxm runs drive <runId> --simulated` executes it model-free)" instead of saying no steps
+  execute until the run engine lands. The JSON result and its
+  `phase` are unchanged. A `run_handoff_required` refusal from `kxm runs drive` now ends
+  with `(handoff reason …; field …; detail …)`, each part capped at 200 characters; a run of
+  the `default` workflow that `kxm init` writes, for example, reports `limit_unsupported`
+  on `limits.maxAgentTimeMs`. Top-level help names the product KXM instead of KontextMind,
+  and `kxm init` text output lists each validation issue as `file: code: message`.
+- **`kxm suggest` recommends only KXM command skills.** Suggested skills come from the
+  command skills shipped in `plugins/kxm/skills` (such as `kxm-workflow`, `kxm-runs`,
+  `kxm-peer` and `kxm-context-memory`), never from skills that do not ship
+  (`troubleshooting`, `modern-web-guidance`) or from the KontextMind knowledge-plane
+  skills.
+- **The Claude plugin's MCP errors name the user's next step, and a session appears to
+  peers before its first tool call.** An unreachable hub names the URL and `kxm hub start`
+  or `/plugin configure kxm@kxm`; `invalid_auth` names the project token; a
+  `session_token_invalid` denial says to unset or replace `KXM_SESSION_TOKEN` when the token
+  came from the environment, or to run `kxm session token --clear` when it came from the
+  token file. Denials still fail closed. A second concurrent session whose agent name is
+  already active registers once as `<name>-<pid>` and says so on stderr. In a KXM project
+  with a project token and a session policy that allows `kxm_inbox` and `kxm_reply`, the
+  server registers right after the MCP handshake instead of at the first tool call, and it
+  leaves the hub when stdin closes. The server instructions point Claude at `kxm_context`
+  and at telling the user the next step, in under 800 characters.
+- **The Claude plugin README is rewritten, and its tool table is pinned to the MCP
+  server.** It covers requirements (`node` on `PATH`, a hub, and the `kxm` CLI for the
+  operator only), installing from Claude Code or the shell, each `userConfig` option and
+  which token to use (this project's token, never the hub admin token), what the MCP server
+  and the SessionStart hook do, every published MCP tool, pushed channel mode versus pull
+  mode, the 0.7.1 version pin with the uninstall-and-reinstall refresh (plugin options must
+  be entered again), and troubleshooting for each user-directed error. A test fails when
+  the README's `## MCP tools` rows and the server's `tools/list` disagree in either
+  direction. The configuration docs now say that `kxm_await` waits at most 60 seconds.
+- **The skill suite is rescoped: every command has one owning skill, and `kxm-setup` is
+  renamed `kxm-mind-setup` with no alias.** `skill-suite.json` declares all 29 bundled
+  skills (13 KXM command skills, 7 browser skills, 9 KontextMind knowledge-plane skills),
+  and each of the 34 registered top-level `kxm` commands is owned by exactly one of them
+  (`models`, `routes` and `ssh` by `kxm-harness-auth`, `tenant` by `kxm-hub-ops`, `explain`
+  by `kxm-context-memory`). The nine knowledge-plane skills are kept; their descriptions now
+  start by saying they cover only the separate `kontext` CLI and `km_` tools, so they
+  trigger only when the user names KontextMind. The command skills were rewritten against
+  the current CLI help and drop stale claims (the run engine "not landed", port 8787,
+  `gate validate` on YAML, `fanout --idempotency-key`). `kxm-project-setup` now walks from
+  `kxm init` through a trust-reviewed first workflow to a simulated, receipt-verified run,
+  stopping where the user reviews and commits `.kxm` changes, and `kxm session brief`
+  (which saves a 24-hour operator token) appears only under its operator steps. **Rename:**
+  anything that names the `kxm-setup` skill must name `kxm-mind-setup`.
+- **Context packets rank by deterministic task relevance.** `kxm context get`,
+  `kxm_context` and Runtime dispatch order eligible items by nine keys: open
+  contradictions first, project before `_shared` defaults, items that share a word with
+  the task before items that do not, role kind priority, a lexical BM25 score over the
+  item's summary and state key, confidence, authority, recency (newest first), then id.
+  Scoring uses a fixed English stopword list and no model, clock or randomness, so the
+  same records and request give the same packet. Contradiction and project-first order
+  are unchanged. The token budget is filled first-fit, so one oversized item no longer
+  stops smaller ones from fitting, and non-current state and proposed skills no longer
+  consume budget. `audit.relevance` reports numbers only (`taskTokens`,
+  `matchedCandidates`, and a rounded score per selected item).
+- **`kxm_improvement_report` returns ranked, redacted cross-run signals.** Alongside the
+  per-area reports, `GET /v1/improvements` returns `signals`: journal entries from the
+  project's runs merged by evidence class, then an error's stage, then a normalized
+  summary that is redacted before it becomes a key. Only errors, open contradictions,
+  lessons and still-proposed skill candidates count. Priority is distinct runs × severity
+  (3/2/1) × mean run attempts × evidence confidence; an unknown run cost counts as 1 and
+  is labelled `unknown`, never 0; security signals rank first. The journal and
+  retrospective loop covers hub webhook runs only; `kxm run` (Runtime) runs have no
+  journal yet.
+- **Recall ranks exact phrases, then token relevance, then id, and returns a relevance
+  per item.** `kxm context recall` and `kxm_recall` previously returned substring matches
+  in id order. Items that neither contain the query nor share a word with it are still
+  left out, and results still carry metadata only, never summaries.
+- **The hub logs task and query sizes, not their text.** `context_packet_assembled` now
+  records `taskChars`, `taskTokens` and `matchedCandidates`, and `context_recall` records
+  `queryChars` and `queryTokens`. The caller still receives its own request in the
+  response.
+- **Engine routing records carry an ask identity and only gate-negative outcomes.** Every
+  `routing.attempt.recorded` record carries four engine-reserved `providerMetadata` keys,
+  written after the producer's so a producer cannot spoof them: `workflowId`, `askSha256`
+  (the same for one step and agent across runs, whatever the run was asked to do),
+  `objectiveSha256` (the run prompt's digest) and `stepWrites`. A producer keeps up to 28
+  keys of its own. `agentRole` defaults to the dispatched agent. `finalOutcome` is written
+  only as `blocked` (a back edge) or `failed` (a producer error, an undeclared outcome or a
+  failing terminal); acceptance is resolved later from the event log. Records written
+  before this change are not backfilled.
+- **`improvement.promotionPolicy` reports review readiness and never authorizes.**
+  `kxm improve` now reads `improvement.*` and reports, per candidate, `readyForReview` and a
+  reason under the configured policy: `manual_pr` is always ready for an operator PR,
+  `critic_quorum` waits for two critic receipts (the CLI supplies none, so it reports not
+  ready), and `auto_threshold` needs `minRuns` distinct runs, `minPassRate`, and a mean
+  recorded cost of at least `minCostSavings` over at least one cost sample. Every policy
+  ends at an operator PR; the old `authorized` result is gone. Values fail closed field by
+  field: an unknown policy is `manual_pr`, a half-life outside (0, 3650] days is 14, and
+  out-of-range thresholds fall back to 10, 0.95 and 0.5.
+  `improvement.telemetryHalfLifeDays` orders report rows through `weightedRecurrence` and
+  never decides candidacy.
+- **`kxm routing report` reads Runtime records by default and counts only event-log
+  acceptance as a Runtime pass.** Without `--file` it reads the current project's Runtime
+  event store and then `.kxm/logs/telemetry.jsonl` (the same sources as `kxm improve`),
+  and `--json` output gains `sources`. A Runtime attempt counts as a pass only when its run
+  completed and the step was not re-entered. The ranking code is unchanged, and the rework
+  column still reads `transitions`, which Runtime records do not set.
+- **`kxm improve --target` is removed.** It was accepted and never applied. Passing it
+  is now an unknown-option error. `KXM_IMPROVE_TARGET` still labels telemetry when it is
+  written; no report reads that label.
+
 - **Hub store schema v3 → v4, external-effects ledger v1 → v2.** The hub store gains a
   `leases` table and the ledger gains `lease_resource`/`fencing_token` columns. Neither has
   a migration lane: an older file is refused at open with `runtime_schema_outdated`, and the
@@ -174,6 +307,77 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Fixed
 
+- **The Claude plugin's SessionStart hook is one bundled, read-only, project-scoped
+  script.** The two shell hooks it replaces (`kxm session brief --status` and
+  `kxm memory brief`) exited 127 without `kxm` on `PATH`, ran whichever `kxm` was on
+  `PATH`, minted a 24-hour operator token and wrote `.kxm/state/session-brief.json` at
+  every session start, ignored the `server_url` option, and had no timeout. The new hook is
+  `node ${CLAUDE_PLUGIN_ROOT}/dist/claude-hook.js session-start` with a 5-second timeout.
+  It reads only the project Claude Code opened (no walk-up), prints nothing outside a KXM
+  project, writes no files, mints no token, spawns nothing and always exits 0. Its context
+  is at most 1,500 characters of status (hub state probed at the plugin's `server_url`, up
+  to three of this project's active runs, the count of open requests for this agent, and
+  user-directed fixes) followed by the unchanged memory brief. The plugin version stays
+  0.7.1, so an existing install gets the hook only after the reinstall described in the
+  plugin README.
+- **The Claude plugin's MCP server never authenticates with the hub admin token.** With a
+  blank `auth_token` it fell back to the admin token saved in `hub-env.json` and registered
+  the agent in a project nobody had issued it a token for. It now uses `KXM_AUTH_TOKEN` or
+  this project's saved project token, and with neither it refuses before contacting the
+  hub. The operator CLI and the Runtime supervisor resolve credentials as before.
+- **`kxm workflow add` writes workflows that load.** The one-step scaffold and the three
+  built-in templates used `role:` where an agent step needs `agent:`, the scaffold added a
+  top-level `id`, and the templates' gate steps named a `verify-gate` no project defines
+  and routed failures on `failed`. One such file in `.kxm/workflows/` made `kxm run` fail
+  with `run_failed` for every workflow in the project. The scaffold is now one
+  `implementer` step, and the templates are the ones described under Added.
+
+- **`kxm improve` sees the Runtime's settled attempts and flags only same-ask repeats
+  across runs.** It read only `.kxm/logs/telemetry.jsonl`, which no Runtime step writes, so
+  it never saw an agent step; and on engine records it grouped per run and scored every pass
+  rate 0. It now reads the current checkout's Runtime event store read-only (one query over
+  the events table; it never creates, writes or migrates a store) plus telemetry, dropping
+  a telemetry copy of an attempt the store already supplied; `--file` still reads only the
+  named file. Each attempt's outcome is resolved from the event log: `accepted` when the run
+  completed and the step was not re-entered, `reworked` when the step was entered again,
+  `failed` when the run failed, and undecided otherwise. Simulated attempts are excluded
+  and counted. Groups key on workflow, step, agent role and ask; a coded-repeat candidate
+  needs the same ask decided in at least 2 runs, an accepted share of at least 0.75, and a
+  step that writes no repository, and a passing group that misses says why
+  (`writes-repository` or `ask-not-repeated`). The output names every source it read, with
+  counts; an unreadable store exits 1 with `improve_source_unreadable` and its path.
+  Workflow-step candidates now propose a `kind: gate` step and a `gates.yaml` entry with a
+  placeholder command, and skill candidates are labelled consolidation. Candidates remain
+  proposals; nothing is applied.
+- **Runtime-dispatched agents receive committed, pinned project memory and hash-verified
+  promoted skills.** The engine built each agent's context packet with no project items, so
+  `.kxm/memory` and promoted skills never reached a `kxm run` agent. Now, when either
+  exists, the Runtime delivers active memory in project or operator scope and promoted
+  skills whose hash verifies, selected for the agent's role and step within 4,000 tokens,
+  and only when those files are tracked and clean at HEAD and still match the run's pinned
+  memory revision. Otherwise the context is withheld with a `dispatch_context_*` gap in the
+  packet (never in the prompt) and the step still runs. Promoted skills render under a new
+  `### Active Skills` heading. No hub call is made at dispatch.
+- **Journal entries accept all ten categories and stage provenance.** The shared
+  `kxm_workflow_record` tool (MCP, Pi and `kxm workflow record`) offered 5 of the 10
+  categories, required an area and dropped `stageId`. It now takes every category and an
+  optional `stageId`; area defaults to the stage's declared area; and the hub, not the
+  caller, derives the attempt: the current attempt for an active or waiting stage, the last
+  one consumed for a finished stage (previously always one past it). Entries the hub writes
+  itself (checkpoint results, signal results, wait timeout, prompt expiry, degraded-quorum
+  approval and premature settlement) carry the stage and attempt; the checkpoint and
+  premature-settlement cases are the ones under test. `kxm workflow record` gained
+  `--stage-id` and accepts `record <runId> <category> <summary>` when area is omitted.
+- **Late journal entries and promotions refresh the exported retrospective.** A terminal
+  run's retrospective is re-exported when an entry is recorded or a promotion decided
+  afterwards. Retrospectives also count only error entries as recurring error classes and
+  propose up to 12 ranked error and lesson signals. A promotion now publishes its update to
+  the run's project rather than to the run id.
+- **Context packets deliver the evidence they select.** Evidence items could be selected
+  and budgeted but no packet section carried them; packets now have an `evidence` section,
+  and the repro and implementer roles receive evidence, so the error, observation and
+  state-change entries they recall reach them.
+
 - **`kxm memory sync` no longer writes this repository's agent policy into other
   projects.** A missing `CLAUDE.md` or `GEMINI.md` used to be created from a header
   copied from KXM's own instruction files — the planner/architecture-critic role, the
@@ -185,6 +389,14 @@ All notable user-facing changes are documented here. The project follows [Semant
   none exist. The block is placed at the end of a file that has no markers yet, rather
   than before a `## Do not` heading that only this repository uses.
 
+- **`kxm memory sync` refuses malformed memory markers instead of eating text.** Sync
+  used to replace from the first `<!-- kxm:memory:start -->` to the first
+  `<!-- kxm:memory:end -->` wherever they appeared, so an orphan start marker got a new
+  block appended and the following sync deleted everything between the orphan and that
+  block; an end before its start duplicated text; a second block went stale. A file
+  must now hold exactly one start marker followed by one end marker, or neither.
+  Otherwise sync exits non-zero naming the file and the problem, and writes no file.
+
 - **Release version surfaces cover workspace packages:** a merged PR no longer
   breaks the release pipeline. `scripts/kxm-bump-version.mjs` now writes the
   version into every package manifest under `packages/`, using the same package

package/README.md

@@ -213,6 +213,9 @@ The hub routes messages; it does not merge contexts, choose tasks, or bypass too
 | Install, configure, and use every KXM surface | [KXM Handbook](docs/kxm-handbook.md) |
 | Complete a Pi-to-Pi or Pi-to-Claude setup | [Getting started](docs/getting-started.md) |
 | Configure the hub or an agent | [Configuration reference](docs/configuration.md) |
+| Look up any `kxm` command, option, or output | [CLI reference](docs/cli-reference.md) |
+| Write project, workflow, agent, role, route, or price files | [Configuration file reference](docs/config-reference.md) |
+| Choose a native harness or OpenRouter for the same model | [Native harness or OpenRouter](docs/harness-routing.md) |
 | Understand components and message flow | [Architecture](docs/architecture.md) |
 | Learn about agent skills | [Agent Skills](docs/agent-skills.md) |
 | Run the hub responsibly | [Operations guide](docs/operations.md) |

package/docs/README.md

@@ -7,6 +7,9 @@ This documentation is organized by task. Start with the guide that matches what
 | [KXM Handbook](kxm-handbook.md) | Operators, Pi users, and Claude Code users | Wiki-ready installation, configuration, and complete feature guide |
 | [Getting started](getting-started.md) | Pi and Claude Code users | Complete the first successful multi-agent exchange |
 | [Configuration](configuration.md) | Users and operators | Understand every supported setting and default |
+| [CLI reference](cli-reference.md) | Operators and agent authors | Every `kxm` command and subcommand with options, JSON output, and examples |
+| [Configuration file reference](config-reference.md) | Project and workflow authors | Every `.kxm` file schema field by field, with validated examples and a worked two-step project |
+| [Native harness or OpenRouter](harness-routing.md) | Operators choosing models | Decide which route runs a model reachable both natively and through an aggregator, and confirm which route a config line uses |
 | [Architecture](architecture.md) | Maintainers and integrators | Learn the component boundaries and message lifecycle |
 | [Terminal components](tui-components.md) | Maintainers and integrators | The reusable panel kit behind `kxm dash` and every configuration surface |
 | [Packages and workspaces](packages.md) | Maintainers | Workspace layout, Nx targets, Bun task running, and the layer gate |

package/docs/agent-skills.md

@@ -1,33 +1,45 @@
 # KXM Agent Skills
 
-This document describes the bundled KXM Agent Skills suite: focused skills
-that cover current KXM top-level command groups. The suite documents the
-existing CLI. It does **not** land unified YAML role/project/workflow
-authority, admit new writers, or replace trusted `.kxm/roster.yaml` policy.
+This document describes the skills bundled in `plugins/kxm/skills`. They
+document the existing CLI and MCP tools. They do **not** land unified YAML
+role/project/workflow authority, admit new writers, or replace trusted
+`.kxm/roster.yaml` policy. For per-command flags, output, and exit codes, see
+the [KXM CLI reference](cli-reference.md); skills do not repeat it.
 
-## Feature-to-Skill Matrix
+The suite has three groups, all declared in `plugins/kxm/skill-suite.json`:
 
-| Feature Area | Skill | Commands Covered | Purpose |
+- 13 KXM command skills that together own every top-level `kxm` command;
+- 7 browser automation skills;
+- 9 skills for KontextMind, a separate product with its own `kontext` CLI and
+  `km_` tools.
+
+## KXM command skills
+
+Each top-level command registered in `plugins/kxm/src/cli.ts` is owned by
+exactly one skill. A skill can own several commands, and the `kxm` router owns
+none.
+
+| Feature area | Skill | Commands owned | Use it to |
 |---|---|---|---|
-| Core Routing | `kxm` | — | Select the right suite skill; state universal safety rules and portable CLI convention |
-| Project Setup | `kxm-project-setup` | `init`, `trust`, `config`, `completion` | Initialize, review permission changes, configure, and install shell completion |
-| Harness & Auth | `kxm-harness-auth` | `harness`, `auth`, `update`, `runtime`, `agent` | Inspect authenticated harness capability and operate supported runtimes/workers |
-| Hub Operations | `kxm-hub-ops` | `hub`, `backup`, `restore` | Run and protect the local hub and its durable SQLite state |
-| Session Management | `kxm-session` | `session`, `dash`, `studio` | Resume/inspect operator work and use UI capabilities each harness supports |
-| Peer Communication | `kxm-peer` | `peer` | Discover, send, poll/await, cancel, fan out, inbox, and reply safely |
-| Workflow Management | `kxm-workflow` | `workflow`, `gate` | Operate webhook workflows, waits/signals, evidence checkpoints, provenance |
-| Definitions | `kxm-definitions` | `role` | Manage role YAML through configuration commands; role edits do not grant trusted writer admission |
-| Run Management | `kxm-runs` | `run`, `runs` | Create and inspect local KXM runs while preserving execution boundaries |
-| Context & Memory | `kxm-context-memory` | `context`, `memory` | Query role-aware context and manage Git-authored memory proposals |
-| Skill Lifecycle | `kxm-skill-lifecycle` | `skills` | Govern candidate/evaluate/promote/reject/verify lifecycle |
-| Routing & Improve | `kxm-routing-improve` | `routing`, `improve` | Inspect real route quality/cost and propose reviewed improvements |
-| Tasks & Goals | `kxm-tasks` | `suggest`, `goal`, `task` | Recommend workflows and manage goals/tasks with SCM/tracker boundaries |
-
-## Browser Automation Skills
-
-KXM includes dedicated skills for remote browser automation on self-hosted Steel (DOKS), exploratory navigation via `agent-browser`, testing with `Playwright`, and visual feedback. See [Browser Automation Guide](browser-automation.md) and [ADR-0002](adr/ADR-0002-browser-automation-steel-doks.md).
-
-| Feature Area | Skill | Purpose |
+| Router | `kxm` | none | Pick the right skill or kxm_* tool and follow the universal safety rules |
+| Project setup | `kxm-project-setup` | `init`, `trust`, `config`, `completion` | Set up a repository, review permission changes, and run a first workflow |
+| Harness and auth | `kxm-harness-auth` | `harness`, `auth`, `update`, `runtime`, `agent`, `models`, `routes`, `ssh` | Check harness auth, update, run the Runtime supervisor, refresh models, admit routes, use SSH and Pi workers |
+| Hub operations | `kxm-hub-ops` | `hub`, `backup`, `restore`, `tenant` | Inspect and bind the hub, read tenant status, back up and restore |
+| Session | `kxm-session` | `session`, `dash`, `studio` | Read session and hub status and open dashboard or studio screens |
+| Peer communication | `kxm-peer` | `peer` | Delegate to, fan out to, await, and answer other agents |
+| Workflows and gates | `kxm-workflow` | `workflow`, `gate` | Record journal entries, pass checkpoints, and wait on signed callbacks |
+| Definitions | `kxm-definitions` | `role` | Inspect or edit roles, role hosts, and model rosters without granting writer admission |
+| Runs | `kxm-runs` | `run`, `runs` | Create, drive, inspect, and cancel runs, or smoke-test a workflow model-free |
+| Context and memory | `kxm-context-memory` | `context`, `memory`, `explain` | Recall what the project knows, explain a context footprint, and record memory candidates |
+| Skill lifecycle | `kxm-skill-lifecycle` | `skills` | Turn a repeated practice into a governed skill candidate |
+| Self-improvement | `kxm-routing-improve` | `routing`, `improve` | Find what KXM learned and what repeats, and read recorded route spend |
+| Tasks and goals | `kxm-tasks` | `suggest`, `goal`, `task` | Pick a workflow and plan work as goals and tasks |
+
+## Browser automation skills
+
+KXM includes dedicated skills for remote browser automation on self-hosted Steel (DOKS), exploratory navigation via `agent-browser`, testing with `Playwright`, and visual feedback. They own no `kxm` command. See [Browser Automation Guide](browser-automation.md) and [ADR-0002](adr/ADR-0002-browser-automation-steel-doks.md).
+
+| Feature area | Skill | Purpose |
 |---|---|---|
 | Browser Sessions | `kxm-browser-session` | Start, attach, inspect, and release Steel sessions on DOKS |
 | Human Takeover | `kxm-browser-takeover` | Handoff protocol for MFA, login, CAPTCHA, and sensitive consent |
@@ -37,54 +49,95 @@ KXM includes dedicated skills for remote browser automation on self-hosted Steel
 | Diagnostics & Recovery | `kxm-browser-diagnostics` | Investigate Steel connectivity, CDP errors, timeouts, and orphan cleanup |
 | Section Annotation | `kxm-browser-annotate` | Capture DOM sections, attach structured annotations, and feed changes to agents |
 
-## Installation and Discovery
+## KontextMind knowledge plane (separate product)
+
+These skills teach KontextMind: its `kontext` CLI, its server, and its `km_`
+tools. They are not KXM and do not use the plugin's kxm_* tools. Each
+description starts with "KontextMind knowledge plane only, the separate
+kontext CLI and km_ tools, not KXM" and ends with "Use only when the user names
+KontextMind, the kontext CLI, or a km_ tool", so a KXM request never loads
+them. They own no `kxm` command. `plugins/kxm/skills/SUITE.md` introduces
+them, and `plugins/kxm/skills/hints.json` holds their slash hints.
+
+| Skill | Purpose |
+|---|---|
+| `kxm-mind` | Route a KontextMind request to the matching knowledge-plane skill |
+| `kxm-query` | Search and read a mind with provenance |
+| `kxm-harvest` | Draft redacted session learnings into a mind |
+| `kxm-triage` | Work the KontextMind review queue |
+| `kxm-work` | Read and update tracker work state and handoffs |
+| `kxm-insights` | List and dismiss loop, gap, and recommendation insights |
+| `kxm-projects` | Manage mind repositories and members |
+| `kxm-protocol` | Explain KontextMind contracts, trailers, trust modes, and authorization |
+| `kxm-mind-setup` | Connect a machine to a KontextMind server with the `kontext` CLI |
+
+`kxm-mind-setup` was named `kxm-setup` before; the old name has no alias.
+
+## Installation and discovery
+
+### Claude Code
 
-### For Pi Users
+Claude Code loads `plugins/kxm/skills` directly; invoke a skill as
+`/kxm:<name>`, for example `/kxm:kxm-project-setup`. The plugin also serves
+the kxm_* MCP tools that the skills name.
 
-Pi automatically discovers skills in the `pi.skills` section of `package.json`. The KXM skills are included in the standard distribution:
+### Pi
+
+Pi discovers the skills from the `pi` section of the root `package.json`:
 
 ```json
 {
-  "pi.skills": [
-    "./plugins/kxm/skills"
-  ]
+  "pi": {
+    "skills": ["./plugins/kxm/skills"]
+  }
 }
 ```
 
-### For Claude Users
-
-Claude plugins package the authored skills from `plugins/kxm/skills/` during the build process.
-
-### For Other Harnesses
-
-Skills in `.agents/skills/` follow the standard agent skill format. Discovery
-outside Pi and Claude remains harness-specific; do not assume every consumer
-loads this mirror.
+### Codex and other harnesses
 
-## Progressive Disclosure Usage
+`scripts/emit-codex-artifacts.mjs` mirrors every declared skill into
+`.agents/skills/`, which Codex reads together with the AGENTS.md command
+block. Discovery by other `.agents/skills` consumers remains harness-specific.
 
-1. Start with the core `kxm` skill to choose a specialized skill.
-2. Use the named skill for that command group.
-3. Teach only verbs and options that exist in `kxm <group> --help`.
+## Progressive disclosure
 
-### Example Usage Patterns
+1. Start with the `kxm` router to choose a skill.
+2. Use the named skill for that request.
+3. Teach only verbs and options that `kxm <group> <verb> --help` prints, and
+   confirm a verb by its `Usage:` line.
 
 ```bash
 kxm peer list --json
 kxm peer send --target alice --content "Please review" --json
-kxm workflow list --json
+kxm runs list --json
 kxm workflow checkpoint run_123 stage_a passed "Completed stage A" --json
 ```
 
-## Verified vs Unverified Harness Limits
+## Writing skill descriptions
+
+Skills are model-visible, and the description decides when a harness loads
+one.
+
+- Say what the skill does and when to use it, key use case first, in at most
+  1024 characters.
+- Write a single line that parses as strict YAML. An unquoted value cannot
+  contain `': '` anywhere; the strict-YAML test in
+  `test/core/skill-suite.test.ts` enforces this for every `SKILL.md`.
+- Do not add `allowed-tools`.
+- Do not use the retired Mesh product name, `pi-extensions`, or `mcp__`.
+- Do not teach `--issue` on token commands, and do not make
+  `kxm session brief` an agent step: it saves a 24-hour operator session
+  token. List it only under an `## Operator steps` heading.
+
+## Verified vs unverified harness limits
 
-### Verified Harnesses
+### Verified harnesses
 
+- **Claude Code**: Loads `plugins/kxm/skills` from the installed plugin
 - **Pi**: Discovers `plugins/kxm/skills`
-- **Claude**: Plugin packaging of the authored skills
 - **Codex**: Consumes the generated `.agents/skills` mirror and AGENTS command block
 
-### Unverified Harnesses
+### Unverified harnesses
 
 The following harnesses have discovery claims that remain explicitly unverified:
 
@@ -93,13 +146,15 @@ The following harnesses have discovery claims that remain explicitly unverified:
 - **OpenCode**: Compatibility unverified
 - **Other `.agents/skills` consumers**: Capabilities unverified
 
-## Distinguishing Operational vs Governed Skills
+## Bundled skills vs governed skills
 
-### Bundled Operational Skills
+### Bundled skills
 
-The skills in this suite (`kxm-*`) are bundled and operational by default. They map 1:1 with KXM's top-level command groups and are maintained as part of the core KXM distribution.
+The skills in this suite ship with the plugin and are maintained in Git as
+part of the KXM distribution. Command skills are grouped by task, so one skill
+can own several command groups.
 
-### Governed Candidates
+### Governed candidates
 
 Separately, `kxm skills` manages community or experimental candidates through
 create/evaluate/promote/reject/verify. Those governed skills are distinct from
@@ -108,20 +163,22 @@ this bundled suite. Telemetry cannot auto-promote a skill. See
 [Repository work delivery](skills/repo-work-delivery.md) for converting a
 repository request into a delivery prompt.
 
-## Development and Maintenance
+## Development and maintenance
 
-### Authoring Location
+### Authoring location
 
 Skills are authored in `plugins/kxm/skills/` as the primary source of truth.
+Every skill directory must be declared in `plugins/kxm/skill-suite.json`
+with `name`, `path`, `ownedCommands`, and a 10-200 character `intent`.
 
-### Generated Mirror
+### Generated mirror
 
 `scripts/emit-codex-artifacts.mjs` copies owned skills byte-for-byte to
 `.agents/skills/` and leaves unrelated skills in that tree untouched. The
 suite manifest `plugins/kxm/skill-suite.json` is required; missing, symlink,
 or malformed manifests fail closed.
 
-### Build Process
+### Build process
 
 1. Validate `plugins/kxm/skill-suite.json`
 2. Replace owned generated skill directories
@@ -130,6 +187,12 @@ or malformed manifests fail closed.
 
 ### Testing
 
-- `test/core/skill-suite.test.ts` validates command coverage and mirrors
-- `test/core/commands-policy.test.ts` checks taught verbs against `cli.ts`
+- `test/core/skill-suite.test.ts` checks that every registered top-level
+  command has exactly one owner, every skill directory is declared, every
+  `SKILL.md` frontmatter parses as strict YAML, the knowledge-plane skills
+  stay separate from the command skills, and the mirrors match
+- `test/core/commands-policy.test.ts` checks taught verbs against `cli.ts` and
+  keeps `kxm session brief` under `## Operator steps`
 - `test/core/generated-artifacts.test.ts` checks manifest-backed generated paths
+- `test/core/docs-copy.test.ts` scans every Markdown file under
+  `plugins/kxm/skills` for removed product names

package/docs/architecture.md

@@ -93,7 +93,7 @@ The hub validates and authenticates requests, stores agents and messages, pushes
 
 **Source of truth.** Semantics are defined by the protocol and schema types (`src/protocol.ts`, `src/workflow.ts`), the hub's durable state (`.kxm/state/kxm.db`: agents, messages, workflow runs, journal), and reviewed workspace configuration in git (`.kxm/config`). The `kxm` CLI, the Pi extension, and the Claude MCP server are **clients** of that state. When a client's behaviour differs from the hub's or a definition's contract, the contract is authoritative and the client is the defect. One deliberate locality limitation remains: `kxm workflow list` / `get` read the local SQLite file rather than the configured hub, so they only describe runs when the operator is on the hub host. Start, signal, and GitHub watch now resolve credentials from the selected active definition and use the start secret as the documented callback fallback.
 
-Signed webhook workflows add a durable run and coordinator message in one request. The stable provider delivery ID prevents duplicate Jira or GitHub retries. Ordered checkpoints enforce attempt limits and exact keyed evidence requirements. Local evidence can be accumulated when a coordinator enters a durable `waiting` state; a separately signed and deduplicated external result must complete the remaining named requirements before it can advance the stage. A separate journal preserves plans, decisions, contradictions, errors, and lessons for reviewed continuous improvement.
+Signed webhook workflows add a durable run and coordinator message in one request. The stable provider delivery ID prevents duplicate Jira or GitHub retries. Ordered checkpoints enforce attempt limits and exact keyed evidence requirements. Local evidence can be accumulated when a coordinator enters a durable `waiting` state; a separately signed and deduplicated external result must complete the remaining named requirements before it can advance the stage. A separate journal preserves plans, decisions, contradictions, errors, lessons, and the other journal categories, each optionally bound to its stage and attempt, for reviewed continuous improvement.
 
 Peer-policy requirements add an evidence plane beside caller-authored strings.
 At run creation, configured eligible agent selectors resolve to stable producer
@@ -219,7 +219,8 @@ workflow state / journal / provenance  →  context engine
   ├─ episodes (journal-derived learning records)
   ├─ knowledge wiki (compiled, source-linked view)
   ├─ skill lifecycle (candidates → protected eval → promote/quarantine)
-  └─ role-aware arbiter (per-role packets under token budgets)
+  └─ role-aware arbiter (task-relevance ranked, per-role packets under token budgets;
+     also feeds Runtime dispatch with committed, pinned memory and promoted skills)
 ```
 
 Key invariants:
@@ -227,6 +228,8 @@ Key invariants:
 - **Workflow state remains authoritative.** Journal entries are evidence, not policy.
 - **Authority never increases through derivation.** A deterministic grant floor per origin (human/workflow → policy, git → instruction, peer/tool/external/derived → evidence) is enforced at parse time.
 - **Project isolation.** Every context request is project-scoped; cross-project content fails closed.
+- **Deterministic selection.** The arbiter ranks by lexical task relevance (BM25 with a fixed stopword list) inside fixed structural keys; no model, clock or randomness decides what a packet holds.
+- **Committed context only at dispatch.** A Runtime-dispatched agent receives project memory and promoted skills only when they are committed, clean, and match the run's pinned memory revision; otherwise they are withheld with a gap and dispatch continues without them. Dispatch reads no hub source.
 - **Promotion is control-plane work.** Agents may propose state and skill candidates; only authorized, evidence-bound decisions promote them.
 
 ### Provider boundary