@kontextmind/kxm 0.7.39 → 0.7.43

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

package/CHANGELOG.md

@@ -4,11 +4,45 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ## Unreleased
 
+### Added
+
+- **Terminal component kit package:** `@kontextmind/tui` (`packages/core/tui`, also
+  exposed as the `@kontextmind/kxm/tui` export) ships the reusable Pi-renderer-based
+  terminal components in the package layer shape (`src/{types,tui,services,adapters,exports}`,
+  `tests/{unit,helpers}`), enforced by `test/core/package-layers.test.ts`.
+- **Per-package workspace tooling:** nx + Bun workspace wiring (`nx.json`,
+  `bunfig.toml`, `packages/*/project.json`, `scripts/build-package.mjs`) with
+  `npm run build:packages|test:packages|check:packages`. Bun is installer and task
+  runner only; tests, the hub, and the CLI remain on Node.
+
+### Changed
+
+- **Naming sweep:** the retired `vnext` naming is gone from file and folder names,
+  symbols, constants, schema `$id` segments, and error codes (`vnext_*` is now
+  `initialization_failed`, `initialization_io_failed`, `wait_failed`); package and
+  folder names dropped the `kxm-` prefix. `docs/vnext/` is `docs/contracts/`,
+  `examples/vnext/` is `examples/project/`. Dated evidence under `plans/` and
+  `.kxm/logs/` keeps its original wording.
+- **Read-only run projection:** `GET /v1/runs/:id` folds the event log without
+  persisting a projection write, so a read cannot mutate run state or surface a
+  false `run_projection_divergent`.
+
+### Fixed
+
+- **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
+  scan that `scripts/check-versions.mjs` enforces (both import
+  `scripts/package-surfaces.mjs`), and patches `package-lock.json` by key rather
+  than by searching for the old version string — a third-party dependency that
+  happens to share the product's version is left alone, and a workspace package
+  with no lock entry fails loudly instead of releasing half-bumped.
+
 ## 0.7.0 - 2026-09-11
 
 ### Added
 
-- **vNext Architecture Engine and Multi-Phase Isolation (Phases 0–4):**
+- **KXM Architecture Engine and Multi-Phase Isolation (Phases 0–4):**
   - **Dead Route Brake (Phase 0):** Fails closed and asserts 404 on obsolete `/dispatch`
     endpoint in supervisor API to eliminate legacy unmonitored dispatch routes.
   - **Objective Propagation (Phase 1):** Propagates accepted run objectives into the producer
@@ -20,7 +54,7 @@ All notable user-facing changes are documented here. The project follows [Semant
     resolution (`step.model -> agent.model -> refuse`), enforcing model admission policies and role
     roster alignment before birth.
   - **Asynchronous Scheduler & Graceful Lifecycle (Phase 4):** Asynchronous `/drive` execution via
-    `VnextRunScheduler` returning `202 Accepted` with `/v1/runs/:id` poll endpoints, duplicate run
+    `KxmRunScheduler` returning `202 Accepted` with `/v1/runs/:id` poll endpoints, duplicate run
     rejection (`409 Conflict`), and supervisor graceful shutdown that awaits active drives.
 - **Oneshot Harness Isolation, Pricing Safety & Async Probes:**
   - Standardized one-shot harness execution across Anthropic Claude, OpenAI Codex, Kimi, and Google AGY
@@ -48,7 +82,7 @@ All notable user-facing changes are documented here. The project follows [Semant
   baseline metrics, declared outcome, measure, and proposed diff patch. Skills carry
   standard YAML frontmatter (`name`, `description`). `skills promote` emits a unified diff
   patch (`.patch`) instead of moving a directory. Added `improve.yaml` workflow in
-  `examples/vnext/.kxm/workflows/` completing on the driver. Un-gitignored retrospective exports.
+  `examples/project/.kxm/workflows/` completing on the driver. Un-gitignored retrospective exports.
 - **Database backup, restore, and migrations (E6, issue #102):** Unified SQLite
   lifecycle via `openDatabase` with fail-closed schema checks, WAL journal mode with
   retry loop, busy timeout, and transaction helper with a nesting guard. Stepwise
@@ -71,7 +105,7 @@ All notable user-facing changes are documented here. The project follows [Semant
   creation. Reorganized tests into `test/core/` (PR gate) and `test/simulations/`
   (heavy simulations) with parallel `--test-concurrency=4` and scheduled nightly
   coverage.
-- Agent-only vNext run loop (`vnext-engine.ts`): pins a D1 compiled plan in an
+- Agent-only KXM run loop (`engine.ts`): pins a D1 compiled plan in an
   immutable hashed envelope, folds schema-valid `kxm.run-event.v1` events with
   a run_state projection, and drives a model-free simulated producer under
   transition/step budgets. Public drive, step, and scheduler share one
@@ -84,10 +118,10 @@ All notable user-facing changes are documented here. The project follows [Semant
   refused (E6). Gate dispatch stays S3/S4. Evaluated gate settlement applies
   transition-budget failure, and complete/no-start observation facts are
   closed on both insert and replay.
-- Pure vNext workflow compile (`vnext-engine-compile.ts`) turns a validated
+- Pure KXM workflow compile (`engine-compile.ts`) turns a validated
   `kxm.workflow.v1` into a frozen JSON plan. Compile is not execution; D3/D4
   remain open.
-- Routing contract doc (`docs/vnext/routing.md`) and synchronization status
+- Routing contract doc (`docs/contracts/routing.md`) and synchronization status
   (schema-tested; Phase 8 implementation).
 - Tag-triggered `release.yml` packs `kxm-<v>.tgz`, creates or reuses only a
   **draft** GitHub release, and fails unless the REST asset digest equals the
@@ -99,7 +133,7 @@ All notable user-facing changes are documented here. The project follows [Semant
   `--ignore-scripts` install, the job runs that package's `install.cjs` so
   the native binary is present.
 - Session brief `AGENTS.md` / `CLAUDE.md` and Tracking in
-  `docs/vnext/implementation-plan.md` (roles, provider-native harness routing,
+  `docs/contracts/implementation-plan.md` (roles, provider-native harness routing,
   cost/insights, plan hygiene).
 - Hub-local session chrome: `kxm session brief [--status]`, Pi TUI picker and
   status line on new/fork sessions, `/kxm` (`status`/`hub`/`help`), skill

package/docs/README.md

@@ -8,6 +8,8 @@ This documentation is organized by task. Start with the guide that matches what
 | [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 |
 | [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 |
 | [Agent Skills](agent-skills.md) | Users and integrators | Comprehensive skill suite covering all KXM commands with progressive disclosure |
 | [Browser automation](browser-automation.md) | Developers and operators | Self-hosted Steel on DOKS, agent-browser, Playwright, pass-cli, and human takeover. See the [knowledge base](browser-automation.md#knowledge-base) and [prompt templates](browser-automation.md#prompt-templates) |
 | [Skills](skills.md) | Operators and skill authors | Governed candidate lifecycle; also the [repository work delivery](skills/repo-work-delivery.md) skill |
@@ -22,7 +24,7 @@ This documentation is organized by task. Start with the guide that matches what
 | [Agent Envelopes & Quality Gates](agent-communication-envelopes-and-gates.md) | Multi-agent workflow engineers | Production communication envelopes, quality gates, and work loops |
 | [Assignment runner](assignment-runner.md) | Maintainers and developers | Native developer assignments, deterministic witness verification, and multi-vendor dual-critic acceptance |
 | [This host's Pi packages](operator-pi-packages.md) | Maintainers on this development host | Snapshot of operator `pi list` packages and file extensions; not a KXM install requirement |
-| [vNext contract package](vnext/README.md) | Maintainers and reviewers | Review the accepted local-first target architecture and implementation contracts |
+| [KXM contract package](contracts/README.md) | Maintainers and reviewers | Review the accepted local-first target architecture and implementation contracts |
 
 Project-level policies live at the repository root:
 
@@ -34,7 +36,7 @@ Project-level policies live at the repository root:
 
 - Put the shortest successful path before optional details.
 - Use the product terms **hub**, **agent**, **peer**, **project**, **request**, and **reply** consistently.
-- Distinguish verified behavior from planned behavior; `docs/vnext` is a planned normative target until activation.
+- Distinguish verified behavior from planned behavior; `docs/contracts` is a planned normative target until activation.
 - Distinguish durable single-node delivery from clustering and exactly-once execution.
 - Update the relevant guide in the same change that modifies user-visible behavior.
 
@@ -48,6 +50,6 @@ CLI behavior.
 | `build-feature` | [Getting started](getting-started.md), [Configuration](configuration.md), [Architecture](architecture.md), [Test matrix](test-matrix.md) |
 | `refactor-repair-regressions` | [Architecture](architecture.md), [Test matrix](test-matrix.md), [Troubleshooting](troubleshooting.md), [Provenance gates](provenance-gates.md) |
 | `stabilize-flaky-tests` | [Test matrix](test-matrix.md), [Operations](operations.md), [Troubleshooting](troubleshooting.md) |
-| `design-software-system` | [Architecture](architecture.md), [Configuration](configuration.md), [vNext contracts](vnext/README.md) |
+| `design-software-system` | [Architecture](architecture.md), [Configuration](configuration.md), [KXM contracts](contracts/README.md) |
 | `investigate-incident` | [Operations](operations.md), [Troubleshooting](troubleshooting.md), [Webhook workflows](webhook-workflows.md) |
 | `patch-vulnerability` | [Provenance gates](provenance-gates.md), [Operations](operations.md), [Configuration](configuration.md) |

package/docs/agent-skills.md

@@ -17,7 +17,7 @@ authority, admit new writers, or replace trusted `.kxm/roster.yaml` policy.
 | 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 vNext runs while preserving execution boundaries |
+| 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 |

package/docs/architecture.md

@@ -28,7 +28,7 @@ Envelope parity is a **shape** guarantee, not a **trust** guarantee. An agent-au
 |---|---|---|
 | `kxm session start --id <id> (--mix a,b \| --workflow <definitionId>)` | Resolves names against the workspace `agents.json` / `gates.json`, writes `.kxm/assets/sessions/<id>/session.json` (`kxm.session.v1`), creates `inputs/` and `outputs/` (plus `assets/workflows/<definitionId>/{inputs,outputs,generated}` in workflow mode), and exits. | Start any process, dispatch a workflow, run a gate, or set `KXM_SESSION_ID`. In `--workflow` mode it lists the **entire roster**, not the definition's participants, and does not read the definition. |
 | `kxm session status` | Lists PID claim files and worker-recovery envelopes under `.kxm/state`. | Read `session.json` or report anything `session start` created. |
-| `kxm session brief [--status]` | Read-only hub snapshot of recent workflow runs (tasks) and journal `plan` rows. `--status` prints the status line. No message bodies. | Start a hub, dispatch a workflow, or read vNext Runtime runs |
+| `kxm session brief [--status]` | Read-only hub snapshot of recent workflow runs (tasks) and journal `plan` rows. `--status` prints the status line. No message bodies. | Start a hub, dispatch a workflow, or read KXM Runtime runs |
 | `kxm session stop` | Requests shutdown of the hub **and every worker** with a PID file in the workspace. It takes no session ID and is the same operation as `kxm hub stop`. | Stop one session. **Treat it as a global stop.** |
 
 Treat `session.json` as a manifest for humans and dashboards. The effective execution primitives are `kxm hub start` (one hub process), `kxm agent worker` (one worker process), and `kxm workflow start` (one signed run).

package/docs/configuration.md

@@ -2,7 +2,30 @@
 
 KXM uses environment variables for the hub and Pi extension. The Claude Code plugin maps its settings to the same client values.
 
-## vNext local project settings
+## Personalization and workflow settings (`kxm.config.v1`)
+
+`kxm config list|get|set` reads one merged view of three layers, in this order:
+
+1. built-in defaults in `plugins/kxm/src/config.ts`;
+2. user scope at `~/.config/kxm/config.yaml` (override the directory with
+   `KXM_USER_CONFIG_DIR`);
+3. project scope at `<repo>/.kxm/config.yaml`.
+
+`kxm config set <key> <value> --scope user|project` writes exactly one of those
+files, defaulting to project scope. `kxm config list --json` reports which file
+supplied what under `loadedFrom`; an empty `loadedFrom` means nothing is stored
+yet and every value shown is a built-in default. A stored value is not trusted
+because it is in the file: an unknown `hub.autoStart` fails closed to the
+default, and an unset `defaults.harness` means Pi rather than the first harness
+in the catalog.
+
+Project identity and repository bindings are separate, Git-tracked files under
+`.kxm/` (`project.yaml`, `roster.yaml`, `routes.yaml`, `gates.yaml`, `prices.yaml`,
+`roles/`, `workflows/`). They are configuration reviewed in a PR, not personal
+settings, and no panel or editor grants writer admission by editing them. See
+[Terminal components](tui-components.md) for the surface that renders them.
+
+## KXM local project settings
 
 Root `kxm init` discovers the control Git worktree and does not use legacy
 `KXM_*` workspace overrides. A cloned multi-repository project can bind a
@@ -245,21 +268,21 @@ The tool allowlist is a capability boundary inside Pi, not a prompt suggestion
 
 ## Operator CLI
 
-The current hub command groups are `agent`, `session`, `workflow`, `gate`, `hub`, `dash`, `improve`, `context`, and `skills`; the root `init` command is the first configuration-only vNext slice. The CLI is an operator **client**: the hub's durable state, the protocol and schema types, and reviewed Git configuration define behaviour; where the CLI diverges from them, the CLI is the defect.
+The current hub command groups are `agent`, `session`, `workflow`, `gate`, `hub`, `dash`, `improve`, `context`, and `skills`; the root `init` command is the first configuration-only KXM slice. The CLI is an operator **client**: the hub's durable state, the protocol and schema types, and reviewed Git configuration define behaviour; where the CLI diverges from them, the CLI is the defect.
 
 | Command | Purpose |
 |---|---|
-| `kxm init` | Atomically create a provenance-tracked minimal vNext project, validate it without rewriting, resume a pinned interrupted create/repair, apply conflict-free non-authority template updates, or join an existing clone with repeatable `--repository <id=absolute-path>` member bindings stored outside Git. `--dry-run` performs no writes. Provenance-free/ambiguous repair and permission-expanding changes remain planning-only. These configuration slices do **not** activate a vNext Runtime. `kxm init` is project-only; bind a running hub with `kxm hub bind <url>` |
+| `kxm init` | Atomically create a provenance-tracked minimal KXM project, validate it without rewriting, resume a pinned interrupted create/repair, apply conflict-free non-authority template updates, or join an existing clone with repeatable `--repository <id=absolute-path>` member bindings stored outside Git. `--dry-run` performs no writes. Provenance-free/ambiguous repair and permission-expanding changes remain planning-only. These configuration slices do **not** activate a KXM Runtime. `kxm init` is project-only; bind a running hub with `kxm hub bind <url>` |
 | `kxm migrate plan` | Convert legacy `.kxm/config` JSON (agents, gates, workflow definitions) into a deterministic, secret-free `kxm.migration-plan.v1` report: source/target hashes, decision-requiring ambiguities (terminal status, transition budgets, evidence-policy strengthening, secret drops, narrowed ceilings, foreign producers), hashed unmapped fields, and explicit identity renames. Performs no writes, locks, or staging |
 | `kxm migrate apply [--decisions <file>]` | Install a reviewed migration: re-checks the decision binding against current sources, validates the complete target bundle, refuses to overwrite existing paths, installs durably, and writes a self-hashed `kxm.migration-receipt.v1` that keeps legacy inputs read-only. Re-applying is an idempotent no-op. `--dry-run` performs no writes |
 | `kxm migrate verify` | Re-check the migration receipt against current legacy sources and the target bundle (self-hash, source hashes, configuration revision, resource bytes). Performs no writes |
 | `kxm trust diff [--base <rev>]` | Print the structured `kxm.permission-diff.v1` report between a base Git revision (default `HEAD`, materialized into a temporary shadow with a sanitized environment) and the working tree: every authority-bearing field change classified as expansion, narrowing, or neutral with per-field hashes. Performs no project writes |
 | `kxm trust check [--base <rev>]` | Exit non-zero when any expansion exists, so an authority-bearing change cannot merge without a reviewed Git change. Formatting/description-only changes never require review |
-| `kxm run <workflow> [prompt]` | Auto-start the vNext Runtime supervisor if needed, then create an immutable run offline: pins `homeRuntimeId` plus config/executor/tool policy revisions and stores only the prompt hash. `--dry-run` prints the plan without creating anything |
+| `kxm run <workflow> [prompt]` | Auto-start the KXM Runtime supervisor if needed, then create an immutable run offline: pins `homeRuntimeId` plus config/executor/tool policy revisions and stores only the prompt hash. `--dry-run` prints the plan without creating anything |
 | `kxm runs status <runId>` | Show the projected status of a run from its event sequence |
 | `kxm runs cancel <runId>` | Durably request cancellation (ordered `run.cancel_requested` then `run.status_changed` events; idempotent, terminal runs are no-ops). `--dry-run` writes nothing |
 | `kxm runs list` | List recent runs for the current project |
-| `kxm runtime start \| status \| stop` | Manage the detached vNext Runtime supervisor: auto-start with liveness probe, token-authenticated 127.0.0.1 API, crash recovery with a stable logical runtime identity |
+| `kxm runtime start \| status \| stop` | Manage the detached KXM Runtime supervisor: auto-start with liveness probe, token-authenticated 127.0.0.1 API, crash recovery with a stable logical runtime identity |
 | `kxm agent worker` | Start a long-lived Pi worker. Use `--session-isolation workflow` to enable per-workflow Pi contexts; the upgrade-compatible default is `off`. Does not read a workspace `agents.json`; pass `--model`, `--tools`, and related flags explicitly |
 | `kxm session start --id <id> (--mix a,b \| --workflow <definitionId>)` | Write a `kxm.session.v1` manifest under `.kxm/assets/sessions/<id>/` and create asset directories. **Does not start any process.** `--workflow` records the whole roster, not the definition's participants |
 | `kxm session brief [--status]` | Read-only local hub snapshot of recent tasks (workflow runs) and plans (journal). `--status` prints the status line for harness chrome. No message bodies. Does not start a hub |

package/docs/{vnext → contracts}/README.md

@@ -1,7 +1,7 @@
-# KXM vNext contract package
+# KXM contract package
 
 > **Status: planned normative contract.** This directory describes the target
-> architecture accepted for KXM vNext. Not all commands are implemented.
+> architecture accepted for KXM. Not all commands are implemented.
 > Phase 1 (init/migrate/trust) and Phase 2 (Runtime create/recover) have landed
 > slices. Phase 3 has D3 S1–S4 and D4 U2a-2 implemented (unreleased); it is not
 > only an agent-only simulated loop, and the default/fix driver gate remains
@@ -11,7 +11,7 @@
 > For current hub execution behavior, use [Architecture](../architecture.md) and
 > [Configuration](../configuration.md).
 
-KXM vNext is a convention-over-configuration, local-first orchestration and
+KXM is a convention-over-configuration, local-first orchestration and
 context platform. One local Runtime owns execution; an optional multi-project
 hub coordinates requests, synchronized facts, and aggregate views.
 
@@ -30,9 +30,9 @@ The words **MUST**, **MUST NOT**, **SHOULD**, and **MAY** are normative.
 | [Validation](validation.md) | Parse, schema, reference, semantic, permission, and snapshot validation |
 | [Migration](migration.md) | Compatibility from the current environment/JSON/SQLite surfaces |
 | [Implementation plan](../../plans/implementation-plan.md) | Ordered implementation and release gates |
-| [Examples](../../examples/vnext/README.md) | Complete project and workflow fixture |
+| [Examples](../../examples/project/README.md) | Complete project and workflow fixture |
 
-Machine-readable schemas live under [`schemas/vnext`](../../schemas/vnext).
+Machine-readable schemas live under [`schemas`](../../schemas).
 JSON Schema validates the data model after a YAML document has been parsed with
 custom tags disabled and bounded aliases, depth, scalar size, and document size.
 
@@ -54,9 +54,9 @@ custom tags disabled and bounded aliases, depth, scalar size, and document size.
 ## Compatibility rule
 
 The current v0.5 contracts remain authoritative until a release explicitly
-activates a vNext schema. Implementations MUST NOT infer vNext behavior merely
+activates a KXM schema. Implementations MUST NOT infer KXM behavior merely
 because these documents or examples are present.
 
-Every persisted vNext resource carries an exact schema identity. Additive
+Every persisted KXM resource carries an exact schema identity. Additive
 changes require a new compatible schema revision; a semantic breaking change
 requires a new major schema identity and an explicit migration.

package/docs/{vnext → contracts}/architecture.md

@@ -1,13 +1,13 @@
 # ADR-001: Local Runtime, project authority, and aggregate hub
 
 - **Status:** accepted target
-- **Scope:** KXM vNext
+- **Scope:** KXM
 - **Supersedes:** no current contract until migration activation
 
 ## Context
 
 The current implementation combines durable peer transport, workflow state,
-and context in one hub-oriented process. KXM vNext must support multiple
+and context in one hub-oriented process. KXM must support multiple
 projects and repositories while continuing useful work when a shared hub is
 unavailable. It must also prevent a hub, model, or learned record from silently
 becoming an execution or policy authority.

package/docs/{vnext → contracts}/migration.md

@@ -1,11 +1,11 @@
 # Migration and compatibility matrix
 
-KXM vNext is introduced beside the current v0.5 transport/workflow surfaces.
-Presence of vNext documents does not activate new behavior.
+KXM is introduced beside the current v0.5 transport/workflow surfaces.
+Presence of KXM documents does not activate new behavior.
 
 ## Surface matrix
 
-| Current surface | vNext target | Migration rule |
+| Current surface | KXM target | Migration rule |
 |---|---|---|
 | `.kxm/config/agents.json` aggregate roster | `.kxm/agents/<id>.yaml` individual definitions | Split records, infer ID from filename, preserve unrecognized fields in a migration report rather than silently dropping them |
 | `gates.json` descriptive records | Workflow step/gate references plus registered deterministic adapters | Map only implemented gates; report names with no runner |
@@ -26,27 +26,27 @@ Presence of vNext documents does not activate new behavior.
 
 ## Compatibility releases and activation
 
-Local Runtime support may ship publicly before hub vNext, but it remains beside
+Local Runtime support may ship publicly before hub KXM, but it remains beside
 existing hub contracts and stores. Old command names are not preserved. A project
 activates `kxm.*.v1` only by an explicit successful `kxm init`/migration receipt;
 file presence alone never activates it. Legacy hub runs continue on the legacy
 engine.
 
-When Phase 8 activates hub vNext, at least one hub transition release provides:
+When Phase 8 activates hub KXM, at least one hub transition release provides:
 
 - current `mesh_*` peer tools;
 - current hub APIs behind a compatibility adapter;
-- legacy JSON configuration read support while vNext writes only YAML;
+- legacy JSON configuration read support while KXM writes only YAML;
 - current completed workflow history read/export support;
-- Runtime-managed vNext runs in new event stores with new identities;
-- CLI labels for legacy versus vNext state;
+- Runtime-managed KXM runs in new event stores with new identities;
+- CLI labels for legacy versus KXM state;
 - no implicit movement of active runs between engines.
 
-Before activation, a repository MUST NOT use legacy and vNext definitions with
+Before activation, a repository MUST NOT use legacy and KXM definitions with
 the same normalized identity. Validation reports the conflict and requires an
-explicit migration choice. After a migration receipt activates the vNext copy,
+explicit migration choice. After a migration receipt activates the KXM copy,
 the matching legacy definition is read-only compatibility input and cannot be
-selected for a new vNext run.
+selected for a new KXM run.
 
 ## Migration commands
 
@@ -105,12 +105,12 @@ values outside the plan's allowed set fail closed before any write.
    decision digest, target configuration revision, and installed resource
    hashes; the receipt is self-hashed.
 8. Re-load the mixed tree: legacy inputs remain intact but receipt-pinned
-   read-only; `loadVnextProject` accepts coexistence only through the
+   read-only; `loadKxmProject` accepts coexistence only through the
    verified receipt.
 
 Re-applying with the receipt present is an idempotent no-op
 (`already-migrated`). Editing a legacy source after the receipt makes both
-`loadVnextProject` and `kxm migrate verify` fail closed.
+`loadKxmProject` and `kxm migrate verify` fail closed.
 
 ### Verify
 
@@ -131,11 +131,11 @@ Before any database operation:
 
 Current agents, messages, workflow runs, journal entries, and context items are
 imported as typed **legacy records**. They are not fabricated into fine-grained
-vNext run events whose original ordering was never observed.
+KXM run events whose original ordering was never observed.
 
 Completed legacy runs remain queryable. A legacy active run must either finish
 on the old engine or be explicitly cancelled/exported; it is not resumed as a
-vNext run.
+KXM run.
 
 ## Configuration migration
 
@@ -156,7 +156,7 @@ The implemented converter:
   transition budgets, and widens evidence-carrying steps into an explicit
   assignment pool containing their producers;
 - converts legacy peer-reply evidence policies (`acceptedStatuses:
-  ["replied"]`) into vNext producer policies requiring `passed` only through
+  ["replied"]`) into KXM producer policies requiring `passed` only through
   an explicit operator decision;
 - requires decisions for: every legacy `$terminal` edge's terminal status
   (legacy completed the run even on failure outcomes), every unbounded
@@ -174,11 +174,11 @@ The implemented converter:
 Unknown data is preserved in the migration report, not placed into a generic
 runtime extension map.
 
-Legacy typed workflows have a global transition budget but may lack vNext
+Legacy typed workflows have a global transition budget but may lack KXM
 per-back-edge caps. The migrator MUST NOT invent those caps silently. `migrate
 plan` lists every affected edge and a proposed bounded value; `migrate apply`
 requires the values in an operator-approved migration decision. The committed
-vNext `/fix` fixture is one reviewed resolution, not a generic automatic rule.
+KXM `/fix` fixture is one reviewed resolution, not a generic automatic rule.
 
 Stage IDs, outcome keys, evidence keys, oracle references, plan-hash references,
 and eligible producer identities are preserved by default. Any unavoidable
@@ -188,25 +188,25 @@ references atomically.
 ## Session migration
 
 Old shared Pi histories may contain content from broader scopes. They remain
-archived under the old worker binding and are never selected for a vNext run.
-The first vNext physical session starts clean. Durable facts must come from Git,
+archived under the old worker binding and are never selected for a KXM run.
+The first KXM physical session starts clean. Durable facts must come from Git,
 workflow evidence, artifacts, or promoted context rather than conversation
 history.
 
 ## Rollback
 
 Rollback is supported until the operator accepts the migration receipt and
-starts a permission-expanding vNext-only run.
+starts a permission-expanding KXM-only run.
 
 Rollback:
 
-1. stop vNext writers;
-2. preserve vNext stores as diagnostic artifacts;
+1. stop KXM writers;
+2. preserve KXM stores as diagnostic artifacts;
 3. restore the recorded legacy configuration selection and database path;
 4. restart only compatible legacy processes;
 5. verify legacy health and record rollback evidence.
 
-Events created only by vNext are not reverse-translated into fabricated legacy
+Events created only by KXM are not reverse-translated into fabricated legacy
 workflow history.
 
 ## Removal gate
@@ -215,6 +215,6 @@ Legacy readers and command aliases are removed only after:
 
 - at least one compatibility release;
 - migration telemetry shows no material unmapped cases;
-- package/install/Windows tests cover vNext;
+- package/install/Windows tests cover KXM;
 - operator documentation and rollback paths are proven;
 - removal is announced in the changelog.

package/docs/{vnext → contracts}/routing.md

@@ -2,7 +2,7 @@
 
 > **Status.** `kxm.routing-record.v1` is parse-only for legacy records.
 > `kxm.routing-record.v2` is **implemented and active**: emitted at engine
-> attempt settlement (`routing.attempt.recorded` event in `plugins/kxm/src/vnext-engine.ts`),
+> attempt settlement (`routing.attempt.recorded` event in `plugins/kxm/src/engine.ts`),
 > enforced with fail-closed `costBasis` requirement. Price catalog `.kxm/prices.yaml`
 > (`kxm.prices.v1`) is implemented, dated, and hashed. `kxm routing report`
 > is implemented (`plugins/kxm/src/routing.ts`) and ranks routes quality-first,
@@ -164,7 +164,7 @@ Fields carried on `RoutingRecordV2`:
 - Outcomes: `verifierOutcome` (`passed` | `warning` | `failed`), `finalOutcome` (`accepted` | `blocked` | `failed` | `pending`), `retries`, optional `transitions`, optional `humanInterventions`, optional `providerMetadata`.
 - Cost accounting: `costBasis` (`"metered" | "unmetered" | "unknown"`), `costUsd` (required when metered), optional `priceRef`.
 
-The vNext engine settle transaction appends a `routing.attempt.recorded` event carrying the v2 record and refuses to settle without a valid `costBasis`. Attempt dispatch enforces `limits.maxModelCost` against metered cost before invocation (`budget_model_cost`).
+The KXM engine settle transaction appends a `routing.attempt.recorded` event carrying the v2 record and refuses to settle without a valid `costBasis`. Attempt dispatch enforces `limits.maxModelCost` against metered cost before invocation (`budget_model_cost`).
 
 ## Implemented: report and price catalog
 

package/docs/{vnext → contracts}/synchronization.md

@@ -2,7 +2,7 @@
 
 > **Status.** `kxm.sync-event.v1` is a **schema-tested contract**. There is no
 > outbox table, sync transform, or hub ingestion in source. Implementation
-> begins in [Phase 8](../../plans/implementation-plan.md#phase-8-multi-project-hub-vnext).
+> begins in [Phase 8](../../plans/implementation-plan.md#phase-8-multi-project-hub-kxm).
 
 Synchronization is summary-first, project-scoped, at-least-once, and
 allowlist-based. The full local event is never placed directly in the outbox.

package/docs/{vnext → contracts}/validation.md

@@ -23,13 +23,13 @@ the normalized filename without `.yaml`; an in-document identity field is
 forbidden.
 
 The shared implementation is `plugins/kxm/src/restricted-yaml.mjs`. Public
-`vnext-config` callers still receive `VnextConfigError` issue codes, paths, and
+`project-config` callers still receive `KxmConfigError` issue codes, paths, and
 messages.
 
 `schemas/policy-draft` (`kxm.model.v2`, `kxm.role.v2`) and
 `validatePolicyDraft` are non-authoritative scaffolding. They are not live
 registry identities, operator settings, or admission. Live model files remain
-`kxm.model.v1` under `schemas/vnext`.
+`kxm.model.v1` under `schemas`.
 
 ## Validation pipeline
 
@@ -40,7 +40,7 @@ UTF-8, and resource-limit violations.
 
 ### 2. JSON Schema validation
 
-Validate against the exact schema identity under `schemas/vnext`. Unknown fields
+Validate against the exact schema identity under `schemas`. Unknown fields
 are rejected unless a schema explicitly defines an extension map.
 
 ### 3. Path and identity validation
@@ -110,7 +110,7 @@ template revision.
 #### Legacy configuration migration
 
 `kxm migrate plan|apply|verify` converts legacy `.kxm/config` JSON into
-validated vNext resources with an exact receipt:
+validated KXM resources with an exact receipt:
 
 - Legacy files are read with byte/depth/node bounds and token-level
   duplicate-key rejection. Symbolic links and linked `workflows/` directories
@@ -135,7 +135,7 @@ validated vNext resources with an exact receipt:
 - Installation uses durable writes under the project mutation lock and finishes
   with a self-hashed `kxm.migration-receipt.v1` binding source hashes, decision
   digest, target configuration revision, and installed resource hashes. The
-  receipt keeps the legacy inputs read-only: `loadVnextProject` accepts mixed
+  receipt keeps the legacy inputs read-only: `loadKxmProject` accepts mixed
   trees only through a verified receipt, and any later legacy-source edit makes
   loading and `migrate verify` fail closed. Re-apply is an idempotent no-op.
 - `plan`, `verify`, and every `--dry-run` path perform no writes, locks,
@@ -222,7 +222,7 @@ description-only changes do not.
 #### Structured projections and the `kxm trust` gate
 
 The implemented workflow projects every resource into deterministic,
-field-addressed authority entries (`vnextAuthorityEntries`) covering the
+field-addressed authority entries (`kxmAuthorityEntries`) covering the
 categories above, then diffs two complete bundles into a
 `kxm.permission-diff.v1` report. Every change is classified conservatively:
 
@@ -296,7 +296,7 @@ revision.
 
 ## Machine-verifiable fixture
 
-[`test/core/contracts-vnext.test.ts`](../../test/core/contracts-vnext.test.ts) parses the
+[`test/core/contracts.test.ts`](../../test/core/contracts.test.ts) parses the
 committed YAML example with the restricted parser profile and validates each
 resource plus representative event/result/delivery/candidate records against
 the committed JSON Schemas.

package/docs/getting-started.md

@@ -74,7 +74,7 @@ workflow-guide agents and workflows for the harnesses you have installed and
 authenticated. Accepting lists the software-engineering workflows from
 [`workflow-guide.md`](workflow-guide.md); pick by number or slug (`all` works
 too). kxm resolves each role's first guide candidate whose harness is
-authenticated and writes only current vNext project resources —
+authenticated and writes only current KXM project resources —
 `.kxm/agents/<role>.yaml` (`kxm.agent.v1`) and `.kxm/workflows/<slug>.yaml`
 (`kxm.workflow.v1`). It never writes retired legacy authority (`.kxm/config`,
 retired `.kxm/roster.json`) or the trusted `.kxm/roster.yaml` policy. Roles whose candidates have no authenticated harness are

package/docs/kb/qa-authentik-authentication.md

@@ -0,0 +1,47 @@
+# Q&A: Authentik (OIDC) for user/role/agent authentication
+
+> Researched by `claude --model fable` (planner, read-only) · 2026-09-17 · task_c0bb05339e15 · root review: pending
+
+**Short answer:** Yes, but not by swapping the hub's checks for OIDC. The hub has one shared-secret model, and the safest hook is a token broker that exchanges Authentik identity for the kxm tokens the hub already understands. Proxy forward-auth is the zero-code first step for humans; hub-side JWT validation is a later, additive gate.
+
+## What exists today
+
+The hub knows about three credentials. None of them carries a user identity, a role, or a group.
+
+1. **Static admin token.** `MeshHubOptions.authToken` (`plugins/kxm/src/hub.ts:77`) is compared with `safeTokenEqual` (`hub.ts:126`, delegating to the SHA-256 `timingSafeEqual` in `commands.ts:937`) against the `Authorization: Bearer` header parsed by `bearerToken` (`hub.ts:130`). `requireAdminAuth` (`hub.ts:533`) gates `/metrics` (`hub.ts:1390`) and admin-scoped context calls (`hub.ts:525`). `requireConfiguredAdminAuth` (`hub.ts:543`) returns 503 `admin_auth_not_configured` when no token is set, gating `/v1/ops/snapshot` and `/v1/ops/events` (`hub.ts:1396`, `1406`) and workflow degradation. The token is sourced from `KXM_AUTH_TOKEN` (`server.ts:15`) or resolved via `resolveHubCredentials` (`hub-env.ts:140`), which generates `kxm_admin_<24 random bytes>` (`hub-env.ts:44`) and persists it to `hub-env.json` with mode 0600 (`hub-env.ts:86`). Auto-start injects it into the hub child's env (`hub-autostart.ts:175`).
+2. **Per-project tokens.** `KXM_PROJECT_TOKENS` is a JSON map of project name to bearer string (`server.ts:45`, `hub-env.ts:120`). `expectedProjectToken` falls back to the admin token when no project token exists (`hub.ts:495`). `requireProjectAuth` (`hub.ts:499`) throws 401 `invalid_auth` on mismatch. Every agent-facing route calls `requireAgent` then `requireProjectAuth(request, agent.project)` (e.g. `hub.ts:1432`, `2133`, `2200`).
+3. **Agent identity (name + key).** `POST /v1/agents/register` (`hub.ts:2091`) accepts a free-form `name`, `purpose`, `project`, `model`, requires only the project token, and mints a fresh `key` via `newId("key")` on every registration or resume (`hub.ts:2107`, `2115`). Name uniqueness is enforced only against currently online agents in the same project (`hub.ts:2098`). The record is stored as opaque JSON in the `agents` table (`store.ts:26`); `AgentRecord` (`protocol.ts:19`) has no role, owner, or principal field. Clients send `x-kxm-agent-id` and `x-kxm-agent-key` headers (`client.ts:540`), which `requireAgent` checks with `safeTokenEqual` (`hub.ts:554`).
+
+**Fail-open edges to preserve or close.** With no admin token on a loopback bind, `requireAdminAuth` returns without checking (`hub.ts:534`) and `requireProjectAuth` skips when no expected token exists (`hub.ts:501`); `server.ts:92` warns `auth=none`. A non-loopback bind without a token refuses to start (`hub.ts:468`). Repo rule: "Bypass fail-closed identity checks" is on the do-not list (`AGENTS.md:224`).
+
+**Roles and permissions today are not hub-authenticated.** Role definitions map to a `tools` allow/deny/preset block (`role.ts:63`-`137`), and the `role` on `/v1/context/get` is a caller-asserted string used only to pick a context budget and journal categories (`hub.ts:1578`, `arbiter.ts:81`). Tool policy is enforced client-side by `enforceToolPolicy` (`commands.ts:1125`), called from the MCP server (`mcp-server.ts:115`), the Pi extension (`extension.ts:892`), and the CLI (`cli.ts:220`). It reads `KXM_ATTEMPT_TOKEN`, then `KXM_SESSION_TOKEN`, then the on-disk `session.token` (`commands.ts:1130`, `1166`, `1182`), and returns `tool_policy_denied` when `isToolAllowed` (`commands.ts:1086`) rejects. Both token formats are unsigned base64url JSON (`mintAttemptToken` `commands.ts:916`, `mintSessionToken` `commands.ts:977`); `parseSessionToken` checks only schema and expiry (`commands.ts:998`). `kxm auth token --issue` mints an `operator` preset locally with no external identity (`cli/hub.ts:500`). The Studio mutate endpoint compares its session token with plain `!==` rather than the timing-safe helper (`studio-layout.ts:350`). No OIDC, JWT, or JWKS code exists in the repo; the only hits are prose in a role description (`init-guide-setup.ts:136`). The plugin has no JWT dependency (`plugins/kxm/package.json:9`).
+
+## Integration options
+
+### 1. Reverse-proxy forward-auth (Authentik outpost at the proxy; hub unchanged)
+
+Authentik's proxy outpost authenticates browser sessions and passes headers upstream. The hub ignores those headers today, so the proxy must still inject the hub bearer token, or clients must still send it. Covers: Studio, `/v1/ops/*` dashboards, human CLI users via a browser-capable flow. Does not cover: agents (they present `x-kxm-agent-*` headers plus a bearer, not a cookie), and it gives the hub no per-user identity for logging. Effort: low, config only. Risk: low if the hub keeps its token check; medium if someone sets the proxy to add the admin token for every authenticated user, which flattens all Authentik users to admin. Non-loopback bind already requires a token (`hub.ts:468`), so the proxy cannot make the hub anonymous.
+
+### 2. Hub validates Authentik-issued JWTs (OIDC discovery + JWKS)
+
+Add a second accepted credential in `bearerToken`'s callers: if the bearer parses as a JWT, verify `iss`, `aud`, `exp`, and signature against a cached JWKS from `<issuer>/.well-known/openid-configuration`; else fall through to the existing `safeTokenEqual` path. Code changes: a new `oidc.ts` (discovery, JWKS cache, verify via `node:crypto` `createPublicKey` from JWK, or add `jose`), new `MeshHubOptions.oidc` and `KXM_OIDC_ISSUER` / `KXM_OIDC_AUDIENCE` env in `server.ts` and `hub-env.ts`, and changes to `requireAdminAuth` and `requireProjectAuth` to accept a verified claim set. Mapping: `groups` claim to admin (e.g. `kxm-admin`) and to project scope (e.g. `kxm-project:<name>`). Client side: `HubClient.authToken` (`client.ts:539`) already sends any string as bearer, so a client can pass an Authentik access token unchanged. Effort: medium, roughly 300 to 500 lines plus tests. Risk: medium. New network dependency at auth time (JWKS fetch must fail closed, never skip), clock skew, and the hub must reject `alg: none` and HS256. Agent registration would gain a real principal to store on the agent record (`sub`, `preferred_username`), which the schema can absorb since records are opaque JSON (`store.ts:26`).
+
+### 3. Token-broker mapping (Authentik users/groups mint per-user or per-agent kxm tokens)
+
+A small broker (could be a new hub route or a sidecar) accepts an Authentik ID token, verifies it as in option 2, then issues the tokens the runtime already consumes: a project token entry for `requireProjectAuth`, and a `kxm.session-token.v1` with a `toolPolicy` derived from the user's group (`mintSessionToken`, `commands.ts:944`). Mapping table: Authentik group to kxm role id (`role.ts:63` ids `writer`, `planner`, `critic-*`, `verifier`), role `tools` block to `ToolPolicy`, and group to project list to `projectTokens`. Today project tokens are a static map read at startup (`hub.ts:385`), so per-user project tokens need either a dynamic token store in `MeshStore` or short-lived tokens the hub can look up. Session tokens are unsigned (`commands.ts:977`), so a broker-issued one only means something if `parseSessionToken` gains signature verification; otherwise any local process can forge the same payload. Effort: medium to high, because it touches token storage, signing, and revocation. Risk: medium. Benefit: agents and humans converge on one identity source without changing every hub route.
+
+## Recommendation
+
+Phased, honoring the fail-closed rules:
+
+1. **Phase 1, now: forward-auth for human surfaces only.** Put Authentik in front of Studio and `/v1/ops/*` on any non-loopback deployment. Keep `KXM_AUTH_TOKEN` mandatory; the proxy never substitutes for it. This adds SSO without touching `hub.ts`. Fix the plain-string compare in `studio-layout.ts:350` to use `timingSafeStringCompare` while there.
+2. **Phase 2: hub-side JWT verification as an additive gate.** Implement option 2 with a hard rule: if `KXM_OIDC_ISSUER` is set and discovery or JWKS fetch fails, the JWT path returns 401, and the static-token path still works. Never let loopback plus OIDC config produce anonymous admin. Record the verified `sub` on the agent record at registration for provenance.
+3. **Phase 3 (defer): broker-issued signed session and attempt tokens.** Sign `kxm.session-token.v1` and `kxm.attempt-token.v1` payloads and verify in `enforceToolPolicy` before mapping Authentik groups to `ToolPolicy`. Until tokens are signed, group-to-policy mapping is advisory, not enforcement, because the check is client-side and forgeable.
+
+Defer any attempt to remove the static token entirely; it is the only credential the auto-start path (`hub-autostart.ts:175`) and the persisted client resolver (`hub-env.ts:203`) know how to pass.
+
+## Agent auth specifically
+
+Running agents today authenticate non-interactively with whatever string lands in `HubClient.authToken`, resolved by `resolveClientHubAuthToken` (`hub-env.ts:203`): `KXM_AUTH_TOKEN` env, else the persisted project token, else the persisted admin token. The MCP server (`mcp-server.ts:84`) and the Pi extension (`extension.ts:709`) both use this. Pi worker children inherit `process.env` unchanged (`pi-producer.ts:504`), so they get the same token as the supervisor. Tool policy for workers comes from `KXM_ATTEMPT_TOKEN`, which is minted only in tests today (`test/core/commands-policy.test.ts:60`); no runtime path in `plugins/kxm/src` calls `mintAttemptToken`, so engine issuance is planned but not wired.
+
+With Authentik, agents should use the OAuth2 client-credentials grant (one Authentik application per agent class, or per role such as `writer` and `verifier`), obtain an access token at spawn, and pass it as `KXM_AUTH_TOKEN` to the child. This needs option 2 in the hub so the token verifies, and a refresh hook in `HubClient` since `headers()` reads a fixed string (`client.ts:539`) and access tokens expire. Device-code flow is the fallback for Claude Code sessions that start from a human terminal. Whether Authentik's client-credentials tokens carry `groups` claims by default is unknown from this repo; it must be confirmed against the Authentik provider config before mapping roles from claims.