@kontextmind/kxm 0.7.94 → 0.7.96

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.94",
+      "version": "0.7.96",
       "category": "development",
       "tags": ["kxm", "multi-agent", "workflows", "mcp"]
     }

package/.kxm/README.md

@@ -1,14 +1,44 @@
-# KontextMind workspace
+# The `.kxm` directory
 
-`.kxm` is the canonical home for repository-local Pi Mesh configuration, logs, assets, and runtime state.
+`.kxm/` holds a KXM project's reviewable definition and its local workspace. You
+commit the configuration; logs, restart state and generated files stay on the
+machine. This directory is the KXM repository's own project. In your project,
+`kxm init` creates the core files: `project.yaml`, `repo/repo.yaml`, two agents,
+a `default` workflow, `gates.yaml` and `template-provenance.yaml`.
 
-| Directory | Contents | Git policy |
+## Layout
+
+| Path | Contents | Git |
 |---|---|---|
-| `config/` | Reviewable workflow and harness configuration without secrets | Tracked |
-| `logs/` | Hub, worker, and agent process logs | Ignored except documentation |
-| `assets/` | Durable workflow inputs and outputs that belong to this workspace | Track intentionally; generated content is ignored |
-| `state/` | SQLite and other restart-recovery state | Ignored except documentation |
+| `project.yaml` | Project identity, repositories and defaults (`kxm.project.v1`) | Tracked |
+| `repo/repo.yaml` | This repository's definition (`kxm.repository.v1`) | Tracked |
+| `agents/`, `models/`, `workflows/` | Agents, model profiles and workflows, one YAML file each | Tracked |
+| `gates.yaml` | The executable gate registry | Tracked |
+| `roles/`, `routes.yaml`, `prices.yaml` | Role rosters, admitted model routes, dated list prices | Tracked |
+| `roster.yaml` | The developer assignment roster for this repository | Tracked, and must be committed |
+| `template-provenance.yaml` | Hashes of the template `kxm init` used | Tracked |
+| `models/inventory.yaml` | The discovered model catalog | Generated; track it for a reviewed snapshot |
+| `config.yaml` | Shared personalization settings | Tracked if the project shares them |
+| `memory/` | Project memory facts that `kxm memory` projects into `AGENTS.md`, `CLAUDE.md` and `GEMINI.md` | Tracked |
+| `assets/` | Intentional workflow inputs and outputs; `assets/generated/` is for machine output | Tracked intentionally; `generated/` ignored |
+| `tasks/` | Task records from `kxm task` | Your choice |
+| `logs/` | Hub, worker and agent logs | Ignored |
+| `state/` | The hub database `kxm.db`, Pi sessions and restart state | Ignored |
+| `run/` | SSH control sockets from `kxm ssh` | Ignored |
+
+The [configuration reference](../docs/reference/config-reference.md#workspace-layout-tracked-ignored-and-state)
+describes every file, the ignore rules to add, and the state KXM keeps outside
+the project.
 
-Secrets remain in environment variables or an approved secret manager. Do not put tokens, webhook secrets, credentials, or private prompt dumps anywhere under `.kxm/config`.
+## Rules
 
-All directory defaults derive from `.kxm`. Set `KXM_WORKSPACE_DIR` to relocate the complete workspace or use a specific path override when an operator-managed volume requires it.
+- **No secrets here.** Keep tokens, webhook secrets and credentials in
+  environment variables or a secret manager. Never commit logs, SQLite files, or
+  raw prompts.
+- **YAML only.** JSON definitions in a `config/` subdirectory are a retired
+  format: their presence makes the project refuse to load with
+  `legacy_state_unsupported`. The hub may create an empty `config/` directory;
+  that alone is harmless.
+- **Moving the workspace.** `KXM_WORKSPACE_DIR`, `KXM_LOGS_DIR`,
+  `KXM_ASSETS_DIR` and `KXM_STATE_DIR` relocate `logs/`, `assets/` and
+  `state/`. The configuration files always stay in `<project root>/.kxm/`.

package/CHANGELOG.md

@@ -271,7 +271,7 @@ All notable user-facing changes are documented here. The project follows [Semant
   a message naming the process that recreates the store (`kxm hub start` for hub state, the Runtime for registry/event stores; `kxm init` is project-only) — and the refusal never
   advances `user_version`, so the store stays identifiably old (WAL sidecars may still be
   checkpointed by opening the file, so the whole state set remains the backup unit — see
-  [`docs/operations.md`](docs/operations.md)). Relabelling a store it refused to open would
+  [`docs/operations.md`](docs/operations/deploy.md)). Relabelling a store it refused to open would
   only hide the problem until a query hit a missing column. The coordinator fingerprint no
   longer recomputes over stored authority to forgive rows written before set canonicalisation:
   a stale coordinator is re-bound. Intake tests go from 23 to 22; the two forced-race tests

package/README.md

@@ -1,310 +1,200 @@
 # KXM
 
 [![CI](https://github.com/kontextmind/kxm/actions/workflows/ci.yml/badge.svg)](https://github.com/kontextmind/kxm/actions/workflows/ci.yml)
-[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![npm](https://img.shields.io/npm/v/@kontextmind/kxm.svg)](https://www.npmjs.com/package/@kontextmind/kxm)
 [![Node.js 22.19+ or 24+](https://img.shields.io/badge/node-22.19%2B%20%7C%2024%2B-339933.svg)](https://nodejs.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-Give running coding agents a small, dependable communication plane.
+**KXM gives coding agents (Claude Code, Pi and other harnesses) a durable, authenticated message and workflow plane, so they can delegate bounded work to each other and prove who answered, without sharing one giant context.**
+
+KXM runs on your machine: one `kxm` CLI, a local [hub](docs/glossary.md#hub) for messages and webhook workflows, and a local [Runtime](docs/glossary.md#runtime) for workflow runs. Your project is reviewable YAML in Git, every agent keeps its own context and its own safety controls, and the docs say plainly what KXM does not guarantee ([Status and limits](#status-and-limits)).
+
+## What makes KXM different
+
+- **Durable messages, not chat.** Every request is a SQLite record that moves from `queued` to `delivered` to `replied`, survives hub and agent restarts, and deduplicates retries by idempotency key. Agents authenticate with a project token and see only their own project's peers. [Message peer agents](docs/guides/peer-messaging.md)
+- **Provenance you can check.** A quorum gate counts only replies the hub itself routed, from distinct eligible peers, for the exact run, stage and attempt. Text a coordinator writes never counts. It proves who answered, not that the answer is right. [Peer provenance and quorum gates](docs/guides/provenance-gates.md)
+- **Workflows that release the turn.** Signed Jira, GitHub or generic webhooks start durable runs. A coordinator can park a stage, give up its turn, and resume only when a signed CI, review or merge callback arrives. [Run webhook workflows](docs/guides/webhook-workflows.md)
+- **Local-first and reviewable.** The project lives in `.kxm/*.yaml`. `kxm trust diff` lists every permission expansion, and `kxm trust check` fails on any expansion beyond the base revision. `kxm run` executes workflows in an event-sourced Runtime that works with the hub down and ends each drive with a receipt it verifies. [Architecture](docs/concepts/architecture.md)
+- **Native harnesses, fail-closed auth, honest cost.** Before a live run dispatches, KXM checks that the harness hosts the model and runs only admitted routes. KXM will not run a model on Pi when its vendor has its own harness, at dispatch or when a worker starts; route admission is a second layer, and a few reseller and policy cases [remain operator decisions](docs/reference/harness-routing.md#where-the-code-is-looser-than-the-rules). A logged-out harness stops the run instead of billing another provider, and cost is recorded as metered, unmetered or unknown. [Harness routing](docs/reference/harness-routing.md)
+- **Context that ranks, learning that only proposes.** Context packets are ranked deterministically for the role and task and filled to a token budget, and they carry the selected evidence itself. Hub workflow journals feed `kxm_improvement_report`, and `kxm improve` reads the Runtime's settled attempts and routing telemetry. Both only propose: readiness never authorizes, and nothing changes until a person merges a reviewed Git change. [Context and memory](docs/guides/context-and-memory.md) · [Continuous improvement](docs/guides/continuous-improvement.md)
+- **One plane for every harness.** A Claude Code plugin (MCP tools, pushed channel, a read-only SessionStart brief), a Pi extension with the same tools, portable Agent Skills, and the `kxm` CLI all work against the same hub. [Claude Code plugin](plugins/kxm/README.md) · [Agent skills](docs/guides/agent-skills.md)
+
+## How it fits together
+
+Claude Code, Pi and the operator CLI talk to one hub on your machine, while the Runtime executes workflow runs locally and syncs their summaries to the hub.
+
+```mermaid
+flowchart LR
+  subgraph Clients["Agents and operator"]
+    CC["Claude Code<br/>plugin: MCP stdio, channel, SessionStart hook"]
+    PI["Pi<br/>extension and skills"]
+    CLI["kxm CLI<br/>operator"]
+  end
+  subgraph Machine["Your machine: loopback by default"]
+    HUB[("KXM hub<br/>HTTP and SSE, SQLite kxm.db")]
+    RT["Runtime supervisor<br/>runs, event store, outbox"]
+  end
+  GIT[["Git repository<br/>.kxm/*.yaml"]]
+  EXT["Webhooks and CI<br/>signed starts and callbacks"]
+  CC -->|"MCP tools, SSE"| HUB
+  PI -->|"HTTP, SSE"| HUB
+  CLI -->|"admin and project APIs"| HUB
+  EXT -->|"HMAC-signed"| HUB
+  CLI -->|"kxm run, kxm runs"| RT
+  RT -->|"sync events, outbound only"| HUB
+  GIT -.->|"reviewed config"| CLI
+  GIT -.->|"pinned per run"| RT
+```
+
+- The **hub** authenticates agents, stores messages and webhook workflow runs, and pushes events. It routes work but never runs a model or merges agent contexts, and it refuses to listen beyond loopback without a token.
+- The **Runtime supervisor** owns the runs `kxm run` creates, as an append-only event log per project. It listens only on `127.0.0.1` and pushes sync-safe events to the hub whenever it can reach one. [Architecture](docs/concepts/architecture.md) explains each component and lifecycle.
+
+## Feature tour
+
+| Capability | Learn more |
+|---|---|
+| **Peer messaging**: discover peers, send, await, fan out to one to three peers, cancel and reply | [Message peer agents](docs/guides/peer-messaging.md) |
+| **Claude Code plugin**: 19 MCP tools, pushed channel or pull mode, and a SessionStart brief | [Claude Code plugin](plugins/kxm/README.md) |
+| **Supervised Pi workers**: restarts, model fallbacks, tool allowlists and one Pi session per workflow run | [Run supervised Pi workers](docs/guides/pi-workers.md) |
+| **Webhook workflows**: signed starts, ordered stages, checkpoints, durable waits and signed callbacks | [Run webhook workflows](docs/guides/webhook-workflows.md) |
+| **Provenance and quorum gates**: hub-verified peer evidence, with an admin-only degradation path | [Peer provenance and quorum gates](docs/guides/provenance-gates.md) |
+| **Local Runtime runs**: `kxm.workflow.v1` steps and gates, `kxm run`, simulated or live drives, verified receipts, cancel and recovery | [Run your first workflow](docs/start/first-workflow.md) · [Workflow definition reference](docs/reference/workflow-definitions.md) |
+| **Trust review**: permission diffs for changes to the project definition in `.kxm/` | [Reviewed Git configuration](docs/concepts/architecture.md#configuration-is-reviewed-git-yaml) · [`kxm trust`](docs/reference/cli-reference.md#kxm-trust) |
+| **Harness routing and admission**: `kxm harness`, `kxm models` and `kxm routes` | [Harness routing](docs/reference/harness-routing.md) |
+| **Context and memory**: role-aware packets, recall, temporal state, episodes, a compiled wiki, and Git memory projected into `AGENTS.md`, `CLAUDE.md` and `GEMINI.md` | [Context and memory](docs/guides/context-and-memory.md) |
+| **Continuous improvement**: journals, retrospectives, improvement reports and coded-repeat candidates | [Continuous improvement](docs/guides/continuous-improvement.md) |
+| **Governed skills**: candidates, recorded evaluations, promotion or rejection, hash pinning | [Governed skills](docs/guides/governed-skills.md) |
+| **Agent Skills**: a portable `SKILL.md` suite that covers every `kxm` command | [Agent skills](docs/guides/agent-skills.md) |
+| **Live dashboard**: `kxm dash` screens for agents, tasks, workflows, plans, inbox and processes | [Monitor KXM](docs/operations/monitoring.md) |
+| **Backup and restore**: the six state roots, `kxm backup` and `kxm restore`, and what each one covers | [Back up and restore KXM](docs/operations/backup-and-restore.md) |
+| **Runtime sync and leases**: the outbox, refused-event recovery and fenced leases | [Runtime sync](docs/operations/runtime-sync.md) |
+| **Hosted deployment**: supervision, and a pattern for one hub and Runtime per tenant behind an authenticating proxy | [Deploy KXM](docs/operations/deploy.md) |
+| **Browser automation**: Steel sessions, Playwright and human takeover skills | [Browser automation](docs/guides/browser-automation.md) |
+| **Everything else**: tasks, goals, suggestions, SSH workers, Studio layouts and shell completion | [KXM CLI reference](docs/reference/cli-reference.md) |
 
-**KXM** lets Pi and Claude Code agents discover one another, send focused requests, continue working independently, and collect replies without sharing an oversized conversation. It provides communication primitives—not an autonomous swarm manager—so each agent keeps its own context and safety controls.
+## Quick start: Claude Code
 
-> **Project status:** Production candidate (`0.4.x`) for a single hub serving local or trusted-team agents. Durable delivery, signed webhook workflows, operator CLI, security controls, observability, and recovery are tested. It is not a horizontally scaled or multi-tenant orchestration service. See [Production boundaries](#production-boundaries).
+<a id="set-up-a-new-project-with-claude-code"></a>
 
-## Why use it?
+You need Node.js 22.19 or newer on the 22.x line, or Node.js 24 or newer, plus Git and Claude Code. These steps connect a Claude Code session in one of your repositories to a hub on the same machine.
 
-- **Delegate deliberately.** Route a bounded task to a peer selected by name and purpose.
-- **Stay productive.** Poll for a result or wait only when the reply blocks progress.
-- **Mix harnesses.** Connect native Pi sessions and Claude Code through the same hub.
-- **Keep control.** Authentication, project isolation, message limits, and normal agent approval rules remain in place.
-- **Install using native formats.** One repository packages a Pi extension, an Agent Skill, and a Claude Code marketplace plugin.
-- **Start from real events.** Signed Jira, GitHub, or generic webhooks can prompt durable, long-lived coordinators.
-- **Release idle turns.** Coordinators can wait durably for signed CI, review, merge, or Jira callbacks and resume only when work remains.
-- **Verify peer provenance.** Per-requirement quorum gates count unique eligible producers from immutable, attempt-bound replied messages rather than coordinator-authored claims.
-- **Learn from every run.** Capture plans, decisions, contradictions, errors, and lessons without turning unreviewed opinions into policy.
+1. Install the CLI and initialize KXM in your repository. `kxm init` writes no ignore rules, so add them, then review and commit `.kxm/`:
 
-## First run
+   ```bash
+   npm install --global --omit=peer @kontextmind/kxm
+   cd <your-repo>
+   kxm init
+   printf '%s\n' '.kxm/state/' '.kxm/logs/' '.kxm/backups/' >> .gitignore
+   ```
 
-You need Node.js 22.19 or newer on the 22.x line, or Node.js 24 or newer, plus Git, GitHub CLI, Pi, and two terminal windows. Six steps take you from install to `kxm session brief` and `/kxm hub`.
+2. In a second terminal, in the same repository, start the hub with a token for this project. Pick any `<hub-project>` key, for example the repository name:
 
-### 1. Install
+   ```bash
+   PROJECT_TOKEN="$(openssl rand -hex 32)"  # keep a copy in your password manager
+   export KXM_PROJECT_TOKENS="{\"<hub-project>\":\"$PROJECT_TOKEN\"}"
+   kxm hub start  # runs in the foreground; keep this terminal open
+   ```
 
-Download the packed release through an authenticated GitHub CLI session. Run `gh auth login` first if necessary. Pi's Git package install supplies the extension and Agent Skill; it does not place `kxm` on `PATH`.
+   > [!IMPORTANT]
+   > `KXM_PROJECT_TOKENS` replaces the hub's saved token map. If this hub already serves other projects, list every one of them. The [Claude Code quick start](docs/start/quickstart-claude-code.md) has a command that merges the map for you.
 
-PowerShell:
+3. Back in the first terminal, bind this machine to the hub and check it:
 
-```powershell
-$version = "<release-version>"
-$asset = "kxm-$version.tgz"
-$releaseDir = Join-Path $PWD ".kxm-release"
-New-Item -ItemType Directory -Force -Path $releaseDir | Out-Null
-gh release download "v$version" --repo kontextmind/kxm --pattern $asset --dir $releaseDir --clobber
-npm install --global --omit=peer (Join-Path $releaseDir $asset)
-pi install git:github.com/kontextmind/kxm@main
-```
+   ```bash
+   kxm hub bind http://127.0.0.1:7331
+   kxm hub view
+   ```
 
-Bash:
+   Expected output:
 
-```bash
-version='<release-version>'
-asset="kxm-${version}.tgz"
-mkdir -p .kxm-release
-gh release download "v${version}" --repo kontextmind/kxm \
-  --pattern "$asset" --dir .kxm-release --clobber
-npm install --global --omit=peer ".kxm-release/$asset"
-pi install git:github.com/kontextmind/kxm@main
-```
+   ```text
+   bound hub http://127.0.0.1:7331 · loopback · health=on
+   hub health=true ready=true · loopback hub
+   ```
 
-From a clone, run `npm ci` and use `node scripts/kxm.mjs` in place of `kxm`. Do not use `npm install --global git+https://github.com/kontextmind/kxm.git`.
+4. Install the plugin. In Claude Code:
 
-### 2. Initialize the project
+   ```text
+   /plugin marketplace add kontextmind/kxm
+   /plugin install kxm@kxm
+   /reload-plugins
+   ```
 
-```text
-kxm init
-```
-
-### 3. Start the hub in another terminal
+   When Claude Code asks for the plugin options, set `project` to `<hub-project>` and leave `auth_token` blank. On the machine that runs the hub, a blank token uses the project token the hub saved for `<hub-project>`, and only that one. On another machine, enter the project token at `/plugin configure kxm@kxm`. Never enter the hub admin token.
 
-`kxm hub start` is foreground. Keep that terminal running.
+5. Ask Claude to call `kxm_list`. It lists this session as an agent in `<hub-project>`.
 
-PowerShell:
+Next, [run your first workflow](docs/start/first-workflow.md). The full [Claude Code quick start](docs/start/quickstart-claude-code.md) also shows how to <a id="add-claude-code-to-an-existing-kxm-project"></a>[add Claude Code to an existing KXM project](docs/start/quickstart-claude-code.md#add-claude-code-to-an-existing-project) and how to <a id="update-an-existing-install"></a>[update the CLI and the plugin](docs/start/quickstart-claude-code.md#update-kxm-and-the-plugin).
 
-```powershell
-$env:KXM_AUTH_TOKEN = "replace-with-an-admin-token"
-$env:KXM_PROJECT_TOKENS = '{"demo":"replace-with-a-demo-project-token"}'
-kxm hub start
-```
+## Quick start: Pi
 
-Bash:
+These steps add a Pi agent to the same hub and project. Install the CLI and the Pi package, which provides the KXM extension and skills:
 
 ```bash
-export KXM_AUTH_TOKEN="replace-with-an-admin-token"
-export KXM_PROJECT_TOKENS='{"demo":"replace-with-a-demo-project-token"}'
-kxm hub start
-```
-
-The hub listens on `http://127.0.0.1:7331`.
-
-### 4. Bind this machine to the hub
-
-```text
-kxm hub bind http://127.0.0.1:7331
-```
-
-### 5. Confirm the session
-
-```text
-kxm session brief
-```
-
-### 6. Open Pi and check the hub
-
-Give agents the project token, not the administrative token.
-
-PowerShell:
-
-```powershell
-$env:KXM_SERVER_URL = "http://127.0.0.1:7331"
-$env:KXM_AUTH_TOKEN = "replace-with-a-demo-project-token"
-$env:KXM_PROJECT = "demo"
-$env:KXM_AGENT_NAME = "planner"
-$env:KXM_AGENT_PURPOSE = "Plans work and coordinates handoffs"
-pi
+npm install --global --omit=peer @kontextmind/kxm
+pi install git:github.com/kontextmind/kxm@main
+cd <your-repo>
+kxm init  # skip if .kxm/project.yaml already exists
 ```
 
-Bash:
+Start and bind the hub as in steps 2 and 3 above, then start Pi as an agent of `<hub-project>`. Give it the project token (`PROJECT_TOKEN` from step 2), never the admin token:
 
 ```bash
-export KXM_SERVER_URL=http://127.0.0.1:7331
-export KXM_AUTH_TOKEN="replace-with-a-demo-project-token"
-export KXM_PROJECT=demo
+export KXM_PROJECT=<hub-project>
+export KXM_AUTH_TOKEN="replace-with-the-project-token"
 export KXM_AGENT_NAME=planner
 export KXM_AGENT_PURPOSE="Plans work and coordinates handoffs"
 pi
 ```
 
-In Pi, run `/kxm hub`. For a second agent or Claude Code, follow [Getting started](docs/getting-started.md).
+In Pi:
 
-## Command-first operation
+```text
+/kxm hub
+```
 
-The `kxm` entry point manages one project. Tools are `init`, `hub`, `dash`, `session`, `agent`, `workflow`, and `gate`. Runtime configuration, logs, durable state, and generated retrospectives stay under `.kxm`.
+Pi reports the hub's health, its own agent name and how many agents are online, for example `kxm hub view: health=ok; planner; 2 online agent(s)`. Start a second agent the same way under another `KXM_AGENT_NAME`, and ask one to send the other a request. [Quick start: Pi](docs/start/quickstart-pi.md) walks through it, including mixed Pi and Claude Code pools.
 
-After the first-run path above, load a reviewed Jira definition with distinct administrative, project, workflow-start, and callback credentials:
+<details><summary>PowerShell</summary>
 
 ```powershell
-# Create or copy a reviewed definition to .kxm/config/workflows/jira-development.json.
-$env:KXM_AUTH_TOKEN = "replace-with-the-admin-token"
-$env:KXM_PROJECT_TOKENS = '{"product":"replace-with-the-project-token"}'
-$env:JIRA_WEBHOOK_SECRET = "replace-with-the-workflow-start-secret"
-$env:WORKFLOW_SIGNAL_SECRET = "replace-with-the-callback-secret"
-$env:KXM_WEBHOOK_WORKFLOWS_FILE = ".kxm/config/workflows/jira-development.json"
-kxm gate validate --file .kxm/config/workflows/jira-development.json
+# Step 1: ignore runtime state
+Add-Content .gitignore ".kxm/state/", ".kxm/logs/", ".kxm/backups/"
+# Step 2: start the hub with a token for this project
+$ProjectToken = [Convert]::ToHexString([Security.Cryptography.RandomNumberGenerator]::GetBytes(32)).ToLower()
+$env:KXM_PROJECT_TOKENS = @{ "<hub-project>" = $ProjectToken } | ConvertTo-Json -Compress
 kxm hub start
-```
-
-In a separately supervised coordinator terminal, give the single writer only
-the project credential and the tools required by the full Jira lifecycle. This
-PowerShell example uses the Windows shell tool; replace `powershell` with `bash`
-on macOS or Linux.
-
-```powershell
+# Pi: start an agent with the project token
+$env:KXM_PROJECT = "<hub-project>"
 $env:KXM_AUTH_TOKEN = "replace-with-the-project-token"
-$coordinatorTools = @(
-  "read", "powershell", "edit", "write", "grep", "find", "ls",
-  "kxm_list", "kxm_send", "kxm_fanout", "kxm_get", "kxm_await",
-  "kxm_workflow_get", "kxm_workflow_checkpoint", "kxm_workflow_wait",
-  "kxm_workflow_record", "kxm_improvement_report"
-) -join ","
-kxm agent worker --name coordinator --project product --model openrouter/qwen/qwen3-coder-plus `
-  --fallback-models antigravity/gemini-3.1-pro --tools $coordinatorTools `
-  --session-isolation workflow --fresh-start
-```
-
-Give review-only peers `read,grep,find,ls`; do not copy the coordinator's shell
-or write capabilities to them. In an operator terminal, start and inspect work,
-then run external watchers with the separate callback secret:
-
-```powershell
-$env:KXM_WORKFLOW_SECRET = "replace-with-the-workflow-start-secret"
-$env:KXM_WORKFLOW_ID = "jira-development"
-$env:KXM_WORKFLOW_SIGNAL_SECRET = "replace-with-the-callback-secret"
-$env:GITHUB_TOKEN = "replace-with-a-checks-read-token"
-kxm workflow start jira-development --payload '@ticket.json'
-kxm workflow list
-kxm workflow get run_123
-kxm gate github watch --run-id run_123 --stage-id push-watch `
-  --signal-key pr-42-checks --repo org/repo --pr 42 --required ci
-kxm workflow export run_123
-kxm hub stop
-```
-
-Use `--dry-run --json` to inspect mutation plans without exposing configured
-token or secret values. Terminal workflows export proposed Markdown and JSON
-retrospectives automatically; review them before adopting any improvement as
-policy. Provenance quorum degradation is a separate admin-only operation; use
-the [provenance runbook](docs/provenance-gates.md#degrade-only-through-an-explicit-admin-decision)
-only for a workflow whose evidence policy declares a lower minimum.
-
-## What is included?
-
-| Component | What it does | Packaging |
-|---|---|---|
-| KXM hub | Persists presence and routes authenticated HTTP/SSE messages | Node.js executable + SQLite |
-| Pi extension | Adds communication, workflow, journal, and improvement tools | `pi.extensions` |
-| Agent Skill | Teaches agents a safe, efficient coordination workflow | `pi.skills` and `SKILL.md` |
-| Claude bridge | Exposes the same workflow plane through MCP and optional channel events | Claude Code plugin |
-| Marketplace | Makes the Claude plugin installable from this repository | Claude marketplace catalog |
-
-## How it works
-
-```text
-Pi planner ──HTTP──┐
-                   ├── KXM hub ──SSE──> addressed inbound requests
-Pi reviewer ─HTTP──┤      │
-                   │      └── presence, heartbeats, message state
-Claude Code ─MCP───┘
+$env:KXM_AGENT_NAME = "planner"
+pi
 ```
 
-The hub routes messages; it does not merge contexts, choose tasks, or bypass tool permissions. A typical request moves through `queued` → `delivered` → `replied`. It may instead end as `cancelled`, `expired`, or `error`. The sender can check it with `kxm_get`, wait with `kxm_await`, or stop pending work with `kxm_cancel`. A local `kxm_fanout` wait ending is nonterminal: it returns a durable pending handle that can be checked with `kxm_get` or retried with the same correlation and idempotency prefix.
+</details>
 
 ## Documentation
 
-| If you want to… | Read |
-|---|---|
-| 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) |
-| Fix connection or delivery problems | [Troubleshooting](docs/troubleshooting.md) |
-| See which behaviors and examples are verified | [Test matrix](docs/test-matrix.md) |
-| Start work from Jira or another webhook | [Webhook workflows](docs/webhook-workflows.md) |
-| Require verified replies from eligible peers | [Peer provenance and quorum gates](docs/provenance-gates.md) |
-| Improve the harness and delivery process from evidence | [Continuous improvement](docs/continuous-improvement.md) |
-| Navigate Area → Workflow → Stage → Role taxonomy | [Workflow guide](docs/workflow-guide.md) |
-| Develop or submit a change | [Contributing](CONTRIBUTING.md) |
-| Report a vulnerability | [Security policy](SECURITY.md) |
-| Review user-facing changes | [Changelog](CHANGELOG.md) |
-
-The [documentation index](docs/README.md) describes the intended audience and scope of each guide.
-
-## Claude Code installation
-
-Inside Claude Code:
+The [documentation index](docs/README.md) groups every page by what you want to do:
 
-```text
-/plugin marketplace add kontextmind/kxm
-/plugin install kxm
-/reload-plugins
-```
+- [Start here](docs/README.md#start-here): install, the quick starts, your first workflow and the glossary.
+- [Guides](docs/README.md#guides): peer messaging, Pi workers, webhook workflows, provenance gates, context and memory, skills and improvement.
+- [Reference](docs/README.md#reference): the CLI, configuration files, harness routing, tools, HTTP API and workflow definitions.
+- [Concepts](docs/README.md#concepts): architecture, the trust model, data and storage, decisions and contracts.
+- [Operations](docs/README.md#operations): deploy, monitor, back up and restore, upgrade, Runtime sync and troubleshooting.
+- [Contributing](docs/README.md#contributing): development, CI and release, writing docs and the test matrix.
 
-The plugin provides peer messaging plus workflow listing, checkpoints, structured journal capture, and project improvement reports. See the [plugin tool table](plugins/kxm/README.md#tools).
+## Status and limits
 
-Pushed Claude channel delivery is a research-preview feature. Community channels currently require an explicit development-channel launch:
+KXM is under active development and is published to npm as [`@kontextmind/kxm`](https://www.npmjs.com/package/@kontextmind/kxm). Merged pull requests ship as patch releases, and the [changelog](CHANGELOG.md) is not split per release: everything released since its newest dated section is still listed under **Unreleased**. It is built for one workstation or one trusted team host, with these deliberate limits, which [Architecture](docs/concepts/architecture.md#limits-and-trade-offs) and the [trust model](docs/concepts/trust-model.md) cover in detail:
 
-```text
-claude --dangerously-load-development-channels plugin:kxm
-```
-
-Without channel mode, ordinary MCP tools still work; use `kxm_inbox` and `kxm_reply` for inbound requests. See [Getting started](docs/getting-started.md#connect-claude-code) for the complete flow.
-
-## Production boundaries
-
-The codebase is structured, typed, persisted, tested, packaged, and CI-gated. The current hub is suitable for production use on one workstation or a controlled trusted-team host, with these deliberate limits:
-
-- One process owns one SQLite database; there is no clustering, leader election, or shared-state failover.
-- Project tokens isolate hub access by project, but there are no per-user roles or external identity provider.
-- Peer quorum proves durable message provenance only within the shared project-credential boundary; it does not prove truth, model independence, non-collusion, or human approval.
-- Delivery is durable and retry-safe when callers supply an idempotency key, but it is not exactly-once execution.
-- Rate-limit counters reset after restart, and capacity depends on the host and SQLite workload.
-- The hub does not coordinate filesystem ownership; use separate worktrees or a single-writer rule.
-- A non-loopback deployment requires authentication, TLS termination, process supervision, and network access controls.
-
-The [operations guide](docs/operations.md) explains backup, recovery, monitoring, upgrade, and the safe deployment envelope.
-
-## Package standards
-
-This repository follows the native package structures for:
-
-- [Pi package discovery](https://pi.dev/docs/latest/packages) through the `pi-package` keyword and `pi.extensions` / `pi.skills` manifests;
-- portable [Pi Agent Skills](https://pi.dev/docs/latest/skills) using `<skill-name>/SKILL.md`;
-- [Claude Code plugins](https://code.claude.com/docs/en/plugins-reference) through `.claude-plugin/plugin.json`;
-- [Claude marketplaces](https://code.claude.com/docs/en/plugin-marketplaces) through `.claude-plugin/marketplace.json`;
-- standard MCP stdio tools and the optional [Claude channel](https://code.claude.com/docs/en/channels-reference) capability.
-
-## Development
-
-```powershell
-npm ci
-npm run verify
-```
-
-`npm run verify` includes `check:generated`. CI also runs `validate:ci` and
-plugin validation (`claude plugin validate`) as a hosted job. See
-[Contributing](CONTRIBUTING.md) before changing the protocol or generated
-runtimes.
-
-## Repository layout
-
-```text
-.kxm/                          Workspace configuration, logs, assets, and state
-.claude-plugin/                 Claude marketplace catalog
-.github/                        CI and contribution templates
-docs/                           User, operator, and architecture guides
-plugins/kxm/
-├── .claude-plugin/             Claude plugin manifest
-├── dist/                       Generated self-contained CLI, hub, and MCP runtimes
-├── skills/                     Portable Agent Skill
-└── src/                        Pi extension, hub, client, and MCP source
-scripts/                        Build and consistency helpers
-test/                           Integration tests
-examples/                       Executable transport scenarios and callback sender
-scripts/kxm-worker.mjs      Restarting headless Pi RPC worker
-```
+- **Single node.** One hub process owns one SQLite database. There is no clustering, replication or failover.
+- **At-least-once.** Messages survive restarts and retries deduplicate by idempotency key, but work can run more than once. Make external side effects idempotent.
+- **Not a sandbox.** KXM does not contain what an agent's tools can do. Use separate worktrees or a single writer, and separate OS accounts for agents you do not trust.
+- **Provenance, not truth.** A quorum shows which agents answered through the hub under one project credential. It does not prove correctness, model independence or human approval.
 
-## License
+## Contributing, security and license
 
-[MIT](LICENSE) © KontextMind contributors.
+- **Contributing:** read [CONTRIBUTING.md](CONTRIBUTING.md), [Develop KXM](docs/contributing/development.md) and the [code of conduct](CODE_OF_CONDUCT.md), and run `npm ci` and `npm run verify` before you open a pull request.
+- **Security:** report a suspected vulnerability privately, as [SECURITY.md](SECURITY.md) describes.
+- **License:** [MIT](LICENSE) © KontextMind contributors.

package/SECURITY.md

@@ -18,25 +18,32 @@ Do not include real credentials, private prompts, personal data, or unrelated re
 
 ## Security model
 
-The current hub provides:
+This section summarizes KXM's security model. The [trust model](docs/concepts/trust-model.md) explains every credential, what it can reach, and where each boundary stops. [Data and storage](docs/concepts/data-and-storage.md) lists what each store keeps and how long.
+
+The current hub and Runtime provide:
 
 - an administrative bearer token and optional per-project bearer tokens;
-- ephemeral per-agent keys for agent-specific operations;
-- project-scoped discovery and message visibility;
-- loopback binding by default;
-- refusal to bind beyond localhost without a token;
+- per-agent keys, rotated at every registration, for agent-specific operations;
+- hub credentials persisted with mode `0600` in the user state root, never in the project;
+- project-scoped discovery, message visibility, and context requests;
+- loopback binding by default, and refusal to bind beyond localhost without a token;
+- a Runtime supervisor that listens only on `127.0.0.1` behind its own token;
+- a Claude Code plugin whose MCP server and SessionStart hook never use the admin token;
 - bounded request bodies, message content, and hop counts;
 - per-agent request rate limiting and stable request IDs;
 - security response headers and generic public responses for internal errors;
 - SHA-256 HMAC verification and stable-delivery deduplication for webhook workflows;
 - attempt-bound peer-message provenance, unique-producer quorum, and explicit admin-only degradation for configured workflow requirements;
-- structured hub logs that omit prompt and reply bodies.
+- a context authority ceiling per origin, so peer, tool, and external content can never grant instructions or policy;
+- structured hub logs that omit prompt and reply bodies, and an allowlisted, redacted Runtime-to-hub sync.
 
 It does not currently provide:
 
-- per-user roles or external identity-provider integration;
-- durable encrypted storage;
+- per-user roles or identity-provider integration inside the hub (hosted deployments authenticate browsers at a proxy; see [ADR-0004](docs/adr/ADR-0004-edge-identity-authentik.md));
+- encryption of stored message bodies, prompts, evidence, or credentials;
 - end-to-end message encryption;
+- signed session tokens: local tool policy is a guardrail, not an authorization boundary;
+- isolation between processes that run as the same OS user;
 - public-internet hardening;
 - distributed denial-of-service protection;
 - guarantees that peer-provided content is safe or correct.
@@ -49,17 +56,19 @@ a new agent or reclaim an offline agent name and its durable ID in that project,
 so every holder of one shared project credential belongs to the same fully
 trusted provenance domain.
 
-Authentication does not make a mesh message trustworthy. Agents must retain their normal permission, tool, filesystem, and secret-handling controls.
+Authentication does not make a peer message trustworthy. Agents must retain their normal permission, tool, filesystem, and secret-handling controls.
 
 ## Operator responsibilities
 
 - Keep the hub on loopback whenever possible.
 - Use a long random token and load it from a secret manager or protected environment.
-- Use distinct project tokens when different teams share one hub.
+- Use distinct project tokens when different teams share one hub, and list every project in `KXM_PROJECT_TOKENS` so the admin token stops working on agent routes.
 - Reserve a distinct administrative token for admin routes; give agents only their explicit project token. Never give a workflow callback or peer the admin token.
-- Protect and back up `.kxm/state/kxm.db` because it contains messages and agent credentials.
+- Set `KXM_AUTH_TOKEN` to the project token for Pi sessions and Pi workers. Without it, the Pi extension falls back to the admin token saved on the hub's machine.
+- Protect and back up `.kxm/state/kxm.db` because it contains message bodies and agent keys.
+- Protect the user state root: `hub-env.json` holds the raw admin and project tokens, and the Runtime stores hold run prompts and event payloads.
 - Protect `.kxm/logs`; raw long-lived Pi process logs can contain model output, tool output, paths, and other sensitive operational data.
-- Keep secrets out of tracked `.kxm/config` and `.kxm/assets`; runtime logs, generated assets, and state must remain uncommitted.
+- Keep secrets out of tracked `.kxm/*.yaml` configuration and `.kxm/assets`; runtime logs, generated assets, and state must remain uncommitted.
 - Store webhook secrets in dedicated environment variables through `secretEnv`; do not commit them in workflow JSON.
 - Use a separate `signalSecretEnv` for callbacks and never put credentials, private prompts, or sensitive incident details in a degradation reason.
 - Review every quorum degradation as a security-relevant decision. It must be declared by policy, limited to the current attempt, and followed by enough verified replies to meet the approved minimum.