@kontextmind/kxm 0.7.91 → 0.7.93

package/plugins/kxm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-plugin",
-  "version": "0.7.91",
+  "version": "0.7.93",
   "private": true,
   "type": "module",
   "engines": {

package/plugins/kxm/skills/hints.json

@@ -58,7 +58,7 @@
       "complete": ["km_projects", "km_project_add", "km_reindex", "km_invite"]
     },
     {
-      "name": "kxm-setup",
+      "name": "kxm-mind-setup",
       "argumentHint": "[serve|login|init|doctor]",
       "triggers": ["install", "serve", "login", "kontext init", "kontext doctor"],
       "complete": ["npx kontextmind serve", "kontext login", "kontext init", "kontext doctor"]

package/plugins/kxm/skills/kxm/SKILL.md

@@ -1,31 +1,46 @@
 ---
 name: kxm
-description: Select the right suite skill; state universal safety rules and portable CLI convention. Use this skill to route to the appropriate specialized skill for each KXM command category.
+description: Entry point for KXM, the kxm CLI and the Claude Code plugin kxm_* MCP tools. Use when the user mentions KXM or kxm, asks which command or kxm_* tool to use, or a task spans setup, hub, peers, workflows, runs, context and memory, or improvement.
 ---
 
-# KXM Lightweight Router
+# KXM router
 
-This skill routes to the appropriate specialized skill for each KXM command category. Use this skill to determine which specific skill handles the command you need.
+Pick the skill that owns the request, then follow it. These bundled skills
+document the current CLI. They do not switch runtime YAML authority, admit
+writers, or replace `.kxm/roster.yaml` trusted policy.
 
-These bundled skills document the current CLI. They do not switch runtime YAML
-authority, admit writers, or replace `.kxm/roster.yaml` trusted policy.
+## Route by request
 
-## Command Routing Guide
+| Request | Skill | Commands owned |
+|---|---|---|
+| Set up or upgrade a project, onboard, run a first workflow | `kxm-project-setup` | `init`, `trust`, `config`, `completion` |
+| Harness installs and auth, updates, the Runtime supervisor, model inventory, route admission, SSH workers, Pi workers | `kxm-harness-auth` | `harness`, `auth`, `update`, `runtime`, `agent`, `models`, `routes`, `ssh` |
+| Hub health, binding, tenant status, backup and restore | `kxm-hub-ops` | `hub`, `backup`, `restore`, `tenant` |
+| Session status, dashboard screens, studio layout | `kxm-session` | `session`, `dash`, `studio` |
+| Delegate to or answer another agent | `kxm-peer` | `peer` (`peer await` is capped at 60 seconds) |
+| Work inside a durable workflow run, gates, signed callbacks | `kxm-workflow` | `workflow`, `gate` |
+| Role definitions, role hosts, model rosters | `kxm-definitions` | `role` |
+| Create, drive, inspect, or cancel a run | `kxm-runs` | `run`, `runs` |
+| What we know or decided, recall, context footprint, Git memory | `kxm-context-memory` | `context`, `memory`, `explain` |
+| Turn a repeated practice into a governed skill | `kxm-skill-lifecycle` | `skills` |
+| What KXM learned, repeated asks, recorded route spend | `kxm-routing-improve` | `routing`, `improve` |
+| Which workflow fits, goals and tasks | `kxm-tasks` | `suggest`, `goal`, `task` |
+| Remote browser sessions, human takeover, exploration, UI verification | `kxm-browser-session`, `kxm-browser-takeover`, `kxm-browser-auth`, `kxm-browser-explore`, `kxm-browser-verify`, `kxm-browser-diagnostics`, `kxm-browser-annotate` | none |
+| KontextMind, the separate knowledge plane with its own kontext CLI | `kxm-mind` | none |
 
-The KXM Agent Skills suite is organized by functional areas:
+## MCP tools
 
-- **Project Setup**: Use `kxm-project-setup` for `init`, `trust`, `config`, `completion`
-- **Harness & Auth**: Use `kxm-harness-auth` for `harness`, `auth`, `update`, `runtime`, `agent`
-- **Hub Operations**: Use `kxm-hub-ops` for `hub`, `backup`, `restore`
-- **Session Management**: Use `kxm-session` for `session`, `dash`, `studio`
-- **Peer Communication**: Use `kxm-peer` for `peer` commands (`peer await` is capped at 60 seconds)
-- **Workflow Management**: Use `kxm-workflow` for `workflow`, `gate`
-- **Definitions**: Use `kxm-definitions` for `role`
-- **Run Management**: Use `kxm-runs` for `run`, `runs`
-- **Context & Memory**: Use `kxm-context-memory` for `context`, `memory`
-- **Skills Lifecycle**: Use `kxm-skill-lifecycle` for `skills`
-- **Routing & Improvement**: Use `kxm-routing-improve` for `routing`, `improve`
-- **Tasks**: Use `kxm-tasks` for `suggest`, `goal`, `task`
+| Tools | Skill |
+|---|---|
+| `kxm_list`, `kxm_send`, `kxm_get`, `kxm_await`, `kxm_cancel`, `kxm_fanout`, `kxm_inbox`, `kxm_reply` | `kxm-peer` |
+| `kxm_workflow_list`, `kxm_workflow_get`, `kxm_workflow_record`, `kxm_workflow_checkpoint`, `kxm_workflow_wait` | `kxm-workflow` |
+| `kxm_context`, `kxm_recall`, `kxm_state`, `kxm_episode`, `kxm_promote` | `kxm-context-memory` |
+| `kxm_improvement_report` | `kxm-routing-improve` |
+
+## Status
+
+Check hub and session status with `kxm hub view` and `kxm session status`.
+Both read only. `kxm hub view` exits 1 when the hub is down.
 
 ## Universal Safety Rules
 
@@ -33,12 +48,21 @@ The KXM Agent Skills suite is organized by functional areas:
 2. **Credential Protection**: Never include credentials or raw secrets in peer messages or public contexts
 3. **Verification Required**: Always verify outcomes from peer responses before acting on them
 4. **Single Writer**: Never write concurrently to the same checkout; use separate worktrees or rotations
+5. **User-owned actions**: Credentials, hub start and bind, plugin configuration, and reviewing and committing .kxm permission changes are the user's actions. Ask the user to do them and never commit .kxm changes yourself.
 
 ## Portable CLI Convention
 
-All KXM commands support `--json` for machine-readable output and follow consistent parameter patterns:
+- Use `--json` for structured output.
+- Flags differ per command; read `kxm <group> <verb> --help`. For example,
+  `kxm context get` scopes with `--run` and `--stage`, while
+  `kxm workflow checkpoint` uses `--run-id` and `--stage-id`.
+- `--help` after an unknown subcommand prints the group's help and exits 0.
+  Confirm a verb exists by checking that the `Usage:` line names it.
+- Teach only verbs and options that the help prints; do not invent
+  subcommands.
+
+## References
 
-- Use `--json` for structured output
-- Parameter names are consistent across commands (e.g., `--run-id`, `--stage-id`)
-- Help is available with `kxm <group> --help`
-- Teach only verbs and options that exist in `kxm <group> --help`; do not invent subcommands
+- [Hub protocol reference](references/protocol.md): HTTP routes, message
+  states, delivery modes, and the trust boundary behind the peer and workflow
+  tools.

package/plugins/kxm/skills/kxm/references/protocol.md

@@ -1,4 +1,4 @@
-# Pi Mesh protocol reference
+# KXM hub protocol reference
 
 The hub exposes a project-scoped HTTP API and an SSE event stream.
 
@@ -23,8 +23,8 @@ Operational routes are `GET /health`, `GET /ready`, and authenticated `GET /metr
 - `POST /v1/workflows/:runId/waits` pauses the active stage for a named external signal and bounded deadline, optionally accumulating verified local keyed evidence.
 - `POST /v1/workflows/:runId/degradations` uses administrative authentication to approve a configured lower peer quorum for the exact current stage, requirement, and attempt.
 - `POST /v1/webhooks/:definitionId/runs/:runId/signals/:signalKey` accepts a signed, retry-deduplicated external checkpoint result.
-- `POST /v1/workflows/:runId/journal` records a plan, decision, contradiction, error, or lesson.
-- `GET /v1/improvements` groups project journal evidence by improvement area.
+- `POST /v1/workflows/:runId/journal` records an entry in one of ten journal categories. An optional `stageId` binds it to that stage: the hub derives the attempt, and `area` defaults to the stage's declared area.
+- `GET /v1/improvements` groups project journal evidence by improvement area and returns ranked, redacted `signals` merged across runs.
 
 Webhook and signal bodies require SHA-256 HMAC validation and a stable provider delivery ID. Workflow routes require both project authentication and the assigned coordinator identity. Signal routes use `signalSecretEnv` when configured and otherwise use the workflow-start secret.
 

package/plugins/kxm/skills/kxm-context-memory/SKILL.md

@@ -1,38 +1,64 @@
 ---
 name: kxm-context-memory
-description: Retrieve scoped KXM context, inspect evidence lineage, and record Git memory candidates across supported harnesses. Use for recalling decisions or proposing durable learning; distinguish candidates from approved authoritative state.
+description: Retrieve role-aware KXM context and record Git memory candidates with kxm context get, recall, state, episode and explain (MCP kxm_context, kxm_recall, kxm_state, kxm_episode), propose a state change with kxm_promote, check a mode's context footprint with kxm explain, and note or sync project memory. Promoting an approved proposal with kxm context promote is an operator action. Use when asked what we know or decided, to recall prior runs or lessons, to explain why an item is in a packet, or to record a durable learning.
 ---
 
-# KXM Context and Memory
+# KXM context and memory
 
-Use KXM's common CLI across supported harnesses. Do not query underlying
-memory providers directly or copy credentials into context. Begin with a
-small role-aware packet rather than an unbounded history dump.
+Use KXM's common CLI or MCP tools across supported harnesses. Do not query
+underlying memory providers directly or copy credentials into context. Begin
+with a small role-aware packet rather than an unbounded history dump.
 
-## Context Commands
+## Context commands
 
 | Command | Purpose | Options |
 |---|---|---|
 | `kxm context get <project>` | Assemble a role-aware packet | Required `--role`, `--task`; optional `--run`, `--stage`, `--budget`, `--kinds` |
-| `kxm context recall <project>` | Search durable metadata | `--query`, `--kinds`, `--limit` |
-| `kxm context state <project> <key>` | Inspect current or historical state | `--as-of` |
-| `kxm context episode <project>` | Inspect learning from workflow journals | `--run` |
-| `kxm context explain <project> <itemId>` | Inspect evidence and lineage | `--json` |
-| `kxm context promote <project> <proposalId>` | Control-plane promotion of an approved proposal | Required `--evidence <refs>` |
-
-All commands accept `--json`. Use comma-separated kind filters and evidence
-references where requested. Verify command-specific `--help` before mutations.
-The CLI promotion command is not the same interface as an agent tool that
-merely proposes state: never substitute a state key for a proposal ID or
-assume that a proposal grants approval.
+| `kxm context recall <project>` | Search durable context records (metadata only) | `--query`, `--kinds`, `--limit` (1-100) |
+| `kxm context state <project> <key>` | Current or historical value of one state key | `--as-of <iso>` |
+| `kxm context episode <project>` | Episodic learning from workflow journals | `--run` |
+| `kxm context explain <project> <itemId>` | Evidence and lineage behind one context item | `--json` |
+
+All commands accept `--json`. Use comma-separated kind filters. The `context`
+commands need a reachable hub: check `kxm hub view` first, because they exit 1
+with a stack trace and no JSON when the hub is down.
+
+## CLI and MCP
+
+| CLI | MCP tool | MCP arguments |
+|---|---|---|
+| `kxm context get` | `kxm_context` | `role`, `task`, `workflowRunId`, `stageId`, `budgetTokens`, `includeKinds` (`evidence`, `state`, `episode`, `knowledge`, `skill`) |
+| `kxm context recall` | `kxm_recall` | `query`, `kinds`, `limit` (1-100) |
+| `kxm context state` | `kxm_state` | `key`, `asOf` |
+| `kxm context episode` | `kxm_episode` | `workflowRunId` |
+| none | `kxm_promote` | Proposes a state change only (`key`, `summary`, `authority`, `confidence`, `evidenceRefs`) |
+
+Packets and recall are ranked deterministically, without a model. `context get`
+orders eligible items by contradiction, project before shared defaults, task
+match, role kind, lexical relevance to `--task`, confidence, authority and
+recency, fills the budget first-fit, and reports numeric `audit.relevance`.
+`context recall` returns whole-query matches first, then items sharing a query
+word by relevance, then id, each with a numeric `relevance` and never a
+summary. Write a specific `--task` or `--query`: the words drive the ranking.
 
 ```bash
 kxm context get my-project --role implementer --task "inspect configuration authority" --budget 4000 --json
 kxm context recall my-project --query "configuration decisions" --limit 5 --json
 kxm context state my-project "configuration.authority" --json
+kxm context explain my-project ctx_123 --json
+```
+
+## Context footprint
+
+`kxm explain [--mode coder|planner|auditor|browser] [--domains <list>] [--model <id>]`
+estimates the prompt footprint and per-turn cost of a workflow mode before a
+run. It reads only; costs stay unknown when the price catalog is missing.
+
+```bash
+kxm explain --mode planner --model claude/fable --json
 ```
 
-## Git Memory Commands
+## Git memory commands
 
 | Command | Purpose | Options |
 |---|---|---|
@@ -57,19 +83,39 @@ never creates an instruction file. If the project has none of the three, sync
 refuses; create the file your harness reads yourself rather than expecting KXM
 to author it.
 
+Each file must hold exactly one start marker followed by exactly one end
+marker, or neither. An orphan marker, an end before its start, or a second
+block makes sync refuse, name the file and the problem, and write no file at
+all. Fix the markers by hand — keep one pair, or delete both so sync appends a
+fresh block — rather than letting sync guess which text is yours.
+
 Do not invent search, save, delete, list, or clear subcommands under memory.
 Use context retrieval for discovery and reviewed authored changes for
 corrections, respecting provenance and historical records.
 
-## Authority and Safety
+## Authority and safety
 
+- `kxm_promote` only proposes a state change. The proposal is not approval,
+  and a state key is never a proposal ID.
 - A candidate, recommendation, or learned skill cannot grant tools, admit a
   writer, change a workflow gate, or waive independent review.
-- Promotion requires durable evidence and authorized control-plane approval.
-  Do not self-approve a proposal merely because you generated it.
+- Do not self-approve a proposal merely because you generated it.
 - Preserve project/run scope and distinguish hypotheses from verified facts.
 - Keep secrets and unrelated private observations out of shared packets.
 - Pi, native harnesses, and generated instruction projections consume the
   same KXM policy; none creates a separate authoritative memory store here.
+- `kxm run` agents receive only committed, pinned memory (project or operator
+  scope) and hash-verified promoted skills. Uncommitted or changed memory is
+  withheld with a `dispatch_context_*` gap until it is committed and a new run
+  pins it; a successful `memory note` does not reach a dispatched agent.
 - Wiki compile/ingest is deferred by this project's release policy. Do not
   activate it merely because a CLI entry exists.
+
+## Operator steps
+
+Promotion is a control-plane decision that belongs to the user or another
+authorized approver, not to the agent that proposed it.
+
+| Command | Purpose | Options |
+|---|---|---|
+| `kxm context promote <project> <proposalId>` | Promote an approved state proposal | Required `--evidence <refs>` |

package/plugins/kxm/skills/kxm-definitions/SKILL.md

@@ -15,6 +15,7 @@ or permission to execute an assignment.
 ```bash
 kxm role list --scope all --json
 kxm role get writer --scope local --json
+kxm role hosts --json
 kxm role --help
 ```
 
@@ -31,11 +32,19 @@ changes every project or the trusted developer runner.
 | `kxm role add [roleId]` | Add a YAML definition or construct a role | `--file`, `--description`, `--skills`, `--harness`, `--model`, `--scope`, `--overwrite`, `--pick` |
 | `kxm role modify [roleId]` | Change description, skill references, or model roster | `--description`, `--add-skill`, `--remove-skill`, `--add-model <harness:model>`, `--remove-model`, `--scope`, `--pick` |
 | `kxm role remove [roleId]` | Remove a definition | `--scope`, `--pick` |
+| `kxm role hosts` | List role seats and the host, model, and effort each resolves to, with the source of that decision | `--scope all\|global\|local` |
+| `kxm role set-host <seatId> <host>` | Bind a role seat to a host in `.kxm/role-hosts.yaml` | `--model`, `--effort low\|medium\|high\|xhigh`, `--scope global\|local` |
+| `kxm role resume <runId> [ruling]` | Resume an audit-escalated run with an operator directive | `[ruling]` free text |
 
 Use `--json` for structured output. Inspect command-specific `--help` before
 constructing a mutation; do not invent `create`, `update`, `delete`, `validate`,
 or `apply` subcommands under `kxm role`.
 
+`kxm role hosts` reads only. `kxm role set-host` writes `.kxm/role-hosts.yaml`
+(or the global file); show the user the resulting diff. `kxm role resume`
+records the operator's ruling on an audit escalation: run it only with the
+ruling the user gave you, and preview a KXM run with `--dry-run` first.
+
 ## Make an Authorized Change
 
 1. Inspect the existing role and its owning scope.

package/plugins/kxm/skills/kxm-harness-auth/SKILL.md

@@ -1,34 +1,100 @@
 ---
 name: kxm-harness-auth
-description: Inspect authenticated harness capability and operate supported runtimes/workers without inventing fallback.
+description: Check which coding-agent harnesses are installed and authenticated, update kxm, harness CLIs and the Claude plugin, manage the Runtime supervisor, refresh the model inventory, admit or disable model routes, run remote SSH workers, and start Pi workers. Use when a dispatch fails on auth, a route is not admitted, the runtime is down, or the operator asks to update.
 ---
 
-# KXM Harness and Auth
+# KXM harness and auth
 
-`kxm harness list` is observational (`yes|no|unknown`). `unknown` and `no` are
-never eligible. Do not invent install/login/status verbs. Native harnesses
-keep their own login; do not silently bill through Pi.
+`kxm harness list` is observational (`yes|no|unknown`); `unknown` and `no` are
+never eligible. Native harnesses keep their own login; do not silently bill
+through Pi. Do not invent install, login, or status verbs.
 
-## Commands
+## Harnesses and tokens
 
 | Command | Purpose | Options / arguments |
 |---|---|---|
 | `kxm harness list` | Installed harnesses, auth, and native updaters | `--json` |
-| `kxm auth token` | Inspect, issue, or clear local session tokens | `--status`, `--clear`, `--issue` |
-| `kxm update [harness]` | Update kxm, harness CLIs, extensions, catalogs | `--check`, `--kxm`, `--self`, `--extensions`, `--models` |
-| `kxm runtime start` | Start the Runtime supervisor | `--json` |
-| `kxm runtime status` | Supervisor liveness | `--json` |
-| `kxm runtime stop` | Stop the supervisor | `--json` |
+| `kxm auth token --status` | Report the local session token | `--json` |
+| `kxm auth token --clear` | Delete the local session token file | `--json` |
+
+Issuing a token is an operator action. When kxm_* tools fail with
+`tool_policy_denied` for an expired or malformed session token file,
+`kxm auth token --clear` removes it; `--status` reports
+`No active session token found in env or disk` for such a file even though it
+still blocks the tools.
+
+## Updates
+
+| Command | Purpose |
+|---|---|
+| `kxm update --check` | Check for a kxm package update without applying it |
+| `kxm update --kxm` | Apply the kxm package update |
+| `kxm update [harness] --self` | Update only the harness CLI |
+| `kxm update [harness] --extensions` | Update only extensions and plugins (Pi packages, the Claude kxm plugin) |
+| `kxm update [harness] --models` | Refresh model catalogs where the harness supports it |
+
+- `kxm update --kxm` downloads the GitHub release tarball by default, so it
+  needs an authenticated `gh`.
+- `kxm update claude --extensions` updates only a user-scope plugin install;
+  its dry run prints `claude extensions: would claude plugin update kxm -y`.
+  A project-scope install is the operator's `claude plugin update kxm@kxm --scope project`.
+- Preview any update with `--dry-run`.
+
+## Runtime supervisor
+
+| Command | Purpose |
+|---|---|
+| `kxm runtime start` | Start the Runtime supervisor if it is not running |
+| `kxm runtime status` | Supervisor liveness and per-project sync state; exits 1 when it is down |
+| `kxm runtime sync-retry` | Re-queue outbox rows the hub durably refused, after the hub-side state is corrected |
+| `kxm runtime stop` | Gracefully stop the supervisor |
+
+`kxm run` starts the supervisor on demand. Stop it with `kxm runtime stop` when
+work is finished.
+
+## Models and routes
+
+| Command | Purpose | Options |
+|---|---|---|
+| `kxm models inventory-refresh` | Refresh `.kxm/models/inventory.yaml` from the OpenRouter and Nous catalogs (alias `refresh`) | `--dry-run`, `--json` |
+| `kxm routes list` | List admitted and disabled routes | `--json` |
+| `kxm routes count` | Count admitted and disabled routes | `--json` |
+| `kxm routes admit` | Admit a model route from the inventory | `--model <id>`, `--dry-run` |
+| `kxm routes disable` | Disable a model route | `--model <id>`, `--dry-run` |
+
+`kxm routes admit` and `kxm routes disable` write `.kxm/routes.yaml`, and the
+model must exist in the inventory. Without `--model` in a non-interactive
+shell they exit 2 with `model_selection_required`. Run them only when the user
+asks, then show `kxm trust diff` and let the user review and commit the
+change. A listed or admitted route is not proof of authentication.
+
+## SSH workers
+
+| Command | Purpose | Options / arguments |
+|---|---|---|
+| `kxm ssh info [host]` | Discover SSH host aliases and parameters without opening sockets | `--json` |
+| `kxm ssh run <host> <command...>` | Run a command on a host over a multiplexed ControlMaster socket | `--sudo` |
+| `kxm ssh file <host> <path>` | Read or write a remote file | `--read`, `--content <text>`, `--append`, `--sudo` |
+| `kxm ssh close <host>` | Close the host's ControlMaster socket | `--json` |
+
+`kxm ssh run` and `kxm ssh file` act on the remote host. Confirm the host and
+command with the user first and never use `--sudo` unasked.
+
+## Pi workers
+
+| Command | Purpose | Options |
+|---|---|---|
 | `kxm agent worker` | Start a long-lived Pi worker | `--name`, `--project`, `--model`, `--fallback-models`, `--tools`, `--session-isolation`, `--no-continue`, `--fresh-start` |
 
+Only Pi is a supervised RPC worker (`kxm agent worker`, `pi --mode rpc`).
+Grok and agy are one-shot headless CLIs, not workers. Listing a harness does
+not grant edit permission or writer admission.
+
 ```bash
 kxm harness list --json
 kxm auth token --status --json
 kxm update --check --json
-kxm update --models
 kxm runtime status --json
+kxm routes list --json
+kxm ssh info --json
 ```
-
-Only Pi is a supervised RPC worker (`kxm agent worker` / `pi --mode rpc`).
-Grok and agy are one-shot headless CLIs, not workers. Listing a harness does
-not grant edit permission or writer admission.

package/plugins/kxm/skills/kxm-harvest/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: kxm-harvest
-description: Extract durable KontextMind learnings at session end. Use when asked to harvest, close session, file a learning, km_append, save a checkpoint, or write a handoff. Redacts secrets first, dedupes against the mind, then drafts to local/project/org.
+description: KontextMind knowledge plane only, the separate kontext CLI and km_ tools, not KXM or this plugin's kxm_* tools. Drafts redacted session learnings into a KontextMind mind with km_append. Use only when the user names KontextMind, the kontext CLI, or a km_ tool.
 license: Apache-2.0
 compatibility: Any agent that can run a shell or MCP client. No vendor-only tools.
 metadata:

package/plugins/kxm/skills/kxm-hub-ops/SKILL.md

@@ -1,43 +1,71 @@
 ---
 name: kxm-hub-ops
-description: Run and protect the local hub and its durable SQLite state.
+description: Start, inspect, stop, bind, and unbind the KXM hub (default http://127.0.0.1:7331), read tenant status, and back up or restore its SQLite state. Use when kxm_list or peer commands cannot reach the hub, when binding to a local or authenticated remote hub, or before upgrades.
 ---
 
-# KXM Hub Operations
+# KXM hub operations
 
-Hub process CLI is `start`, `view`, `stop`, plus bind/unbind. Backup writes a
-verified SQLite archive; restore takes that manifest. Do not invent restart
-or backup subcommands.
+The hub serves peers and webhook workflows on `http://127.0.0.1:7331` by
+default. Its CLI is `start`, `view`, `stop`, `bind`, and `unbind`. Do not
+invent restart or status subcommands.
 
-## Commands
+## Agent steps
 
 | Command | Purpose | Options / arguments |
 |---|---|---|
-| `kxm hub start` | Start the hub | `--json` |
-| `kxm hub view` | Check `/health` and `/ready` | `--json` |
-| `kxm hub stop` | Request managed shutdown | `--wait-ms <ms>` |
-| `kxm hub bind <url>` | Bind this machine to a running hub | http or https URL |
-| `kxm hub unbind` | Remove this machine's hub binding | `--json` |
-| `kxm backup` | Verified SQLite backup of all stores | `--out <dir>` |
-| `kxm restore <manifest>` | Restore from a verified backup manifest | `--json` |
+| `kxm hub view` | Check `/health` and `/ready`; exits 1 when the hub is down | `--json` |
+| `kxm tenant status` | Hub metadata and Runtime run state as one labeled view; reads only and never starts the supervisor | `--json` |
+| `kxm backup` | Verified SQLite backup of the hub stores with a hashed manifest | `--out <dir>`, `--json` |
+
+```bash
+kxm hub view --json
+kxm tenant status --json
+kxm backup --out .kxm/backups/pre-upgrade --json
+```
+
+`kxm tenant status` reports an unreadable source as `unavailable` with a
+reason such as `hub_unreachable` or `runtime_supervisor_not_running`, and sets
+`degraded`. It exits 0 when at least one source was read. Hub runs and Runtime
+runs have separate ID spaces, so a comparison with no shared ID is
+`unverified`, never agreement.
 
-Durable hub SQLite default is `.kxm/state/kxm.db` (`KXM_DATA_PATH`).
+The durable hub store defaults to `.kxm/state/kxm.db` (`KXM_DATA_PATH`). Do not
+hand-edit it. `kxm backup` does not include the Runtime supervisor's stores
+under the user state root.
 
-`kxm hub start` requires no token setup on a fresh machine: when
-`KXM_AUTH_TOKEN` is unset, a long random admin token is generated once and
-persisted in `hub-env.json` (schema `kxm.hub-env.v1`, `0600`) under the user
-state root, then reused by every restart, worker, and dashboard. Explicit
-`KXM_AUTH_TOKEN` / `KXM_PROJECT_TOKENS` values win and are persisted too.
-Hub PID claims record the wrapper and server child PID; a dead wrapper's
-claim is reclaimed automatically, an orphaned server is terminated first,
-and `kxm hub stop` recovers such orphans directly.
+## Operator steps
+
+Ask the user to run these in their own terminal. Never read, print, or store
+the hub admin token or a project token.
+
+| Command | Purpose | Options / arguments |
+|---|---|---|
+| `kxm hub start` | Start the hub in the foreground | `--json` |
+| `kxm hub stop` | Request managed hub and worker shutdown | `--wait-ms <ms>` |
+| `kxm hub bind <url>` | Bind this machine to a running hub | http or https URL |
+| `kxm hub unbind` | Remove this machine's hub binding | `--json` |
+| `kxm restore <manifest>` | Replace the live stores from a verified backup manifest | `--json` |
 
 ```bash
 kxm hub start
-kxm hub view --json
-kxm hub bind http://127.0.0.1:8787
-kxm backup --out /tmp/kxm-backup
-kxm restore /tmp/kxm-backup/manifest.json
+kxm hub bind http://127.0.0.1:7331
+kxm restore .kxm/backups/pre-upgrade/manifest.json
 ```
 
-Do not hand-edit the hub database or skip restore verification.
+- `kxm hub start` needs no token setup on a fresh machine. When
+  `KXM_AUTH_TOKEN` is unset it generates a long random admin token once and
+  persists it in `hub-env.json` (schema `kxm.hub-env.v1`, mode `0600`) under
+  the user state root, then reuses it on every restart.
+- `KXM_PROJECT_TOKENS` must list every project's token. It replaces the saved
+  token map rather than merging with it, and the replacement is saved. When a
+  hub already serves other projects, build the full map with the merge
+  command in the KXM README before restarting the hub.
+- `kxm hub bind` to a remote (non-loopback) URL fails closed with
+  `hub_bind_unauthenticated` unless a credential for the current project
+  resolves from `KXM_AUTH_TOKEN` or the persisted `hub-env.json`.
+- Hub PID claims record the wrapper and server child PID. A dead wrapper's
+  claim is reclaimed automatically, an orphaned server is terminated first,
+  and `kxm hub stop` recovers such orphans directly.
+- `kxm restore` replaces the live stores. Preview it with
+  `kxm restore <manifest> --dry-run`, stop the hub first, and never skip
+  restore verification.

package/plugins/kxm/skills/kxm-insights/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: kxm-insights
-description: KontextMind workflow intelligence — loop patterns, knowledge gaps, and evidence-backed recommendations. Use when asked for insights, what the mind observed, loops, gaps, or km_insights list/dismiss.
+description: KontextMind knowledge plane only, the separate kontext CLI and km_ tools, not KXM or this plugin's kxm_* tools. Lists and dismisses KontextMind insights with km_insights. Use only when the user names KontextMind, the kontext CLI, or a km_ tool.
 license: Apache-2.0
 compatibility: Any agent that can run a shell or MCP client. No vendor-only tools.
 metadata:

package/plugins/kxm/skills/kxm-mind/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: kxm-mind
-description: Router for the KontextMind knowledge plane on any agent harness. Use when the user mentions KontextMind, the mind, km_ tools, kontext CLI, harvest, triage, handoffs, insights, reindex, or KM-Session trailers. Does not replace the KXM peer/workflow skill named kxm.
+description: KontextMind knowledge plane only, the separate kontext CLI and km_ tools, not KXM or this plugin's kxm_* tools. Routes a KontextMind request to the matching knowledge-plane skill. Use only when the user names KontextMind, the kontext CLI, or a km_ tool.
 license: Apache-2.0
 compatibility: Any agent that can run a shell or MCP client (Claude Code, Cursor, Codex, Pi, Gemini, Grok, and others). No vendor-only tools.
 metadata:
@@ -31,7 +31,7 @@ Slash / skill menu hint — `[intent]`
 | work, handoff, in-flight | `kxm-work` |
 | insights, loop, gap | `kxm-insights` |
 | project, reindex, invite | `kxm-projects` |
-| serve, login, init, doctor | `kxm-setup` |
+| serve, login, init, doctor | `kxm-mind-setup` |
 | trailer, trust, gate, authz | `kxm-protocol` |
 | peer, fanout, checkpoint | `kxm` |
 | brief, hub bind, status line | `kxm-session` |

package/plugins/kxm/skills/{kxm-setup → kxm-mind-setup}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: kxm-setup
-description: Connect a machine or repo to KontextMind — serve, login, init, doctor. Use when asked to install kxm, start the local server, OAuth login, stamp MCP/hooks/AGENTS.md, run kontext doctor, or wire an agent to the mind.
+name: kxm-mind-setup
+description: KontextMind knowledge plane only, the separate kontext CLI and km_ tools, not KXM or this plugin's kxm_* tools. Connects a machine to a KontextMind server with the kontext CLI. Use only when the user names KontextMind, the kontext CLI, or a km_ tool.
 license: Apache-2.0
 compatibility: Any agent that can run a shell or MCP client. No vendor-only tools.
 metadata:
@@ -11,9 +11,9 @@ metadata:
   suite: kxm
 ---
 
-# kxm-setup
+# kxm-mind-setup
 
-Beacon after the server is up — `km_status` with `skill: "kxm-setup"`.
+Beacon after the server is up — `km_status` with `skill: "kxm-mind-setup"`.
 
 ## Zero-install server