@kontextmind/kxm 0.6.0 → 0.7.4

package/.claude-plugin/marketplace.json

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

package/.kxm/agents/coordinator.yaml

@@ -0,0 +1,9 @@
+schema: kxm.agent.v1
+purpose: Coordinate the pinned workflow and emit schema-validated commands.
+tools:
+  preset: coordinator
+defaultRepositoryAccess: read
+repositories:
+  control: read
+network: provider-only
+resultSchema: kxm.assignment-result.v1

package/.kxm/agents/critic-arch.yaml

@@ -0,0 +1,13 @@
+schema: kxm.agent.v1
+purpose: Architecture critic for the approved workflow change.
+harness: claude
+model:
+  provider: anthropic
+  model: fable
+tools:
+  preset: read-only
+defaultRepositoryAccess: read
+repositories:
+  control: read
+network: provider-only
+resultSchema: kxm.assignment-result.v1

package/.kxm/agents/critic-cli.yaml

@@ -0,0 +1,13 @@
+schema: kxm.agent.v1
+purpose: CLI and verification critic for the approved workflow change.
+harness: codex
+model:
+  provider: openai
+  model: gpt-5.6-sol
+tools:
+  preset: read-only
+defaultRepositoryAccess: read
+repositories:
+  control: read
+network: provider-only
+resultSchema: kxm.assignment-result.v1

package/.kxm/agents/implementer.yaml

@@ -0,0 +1,13 @@
+schema: kxm.agent.v1
+purpose: Implement the approved change within the declared repository scope.
+harness: grok
+model:
+  provider: xai
+  model: grok-4.6
+tools:
+  preset: workspace-writer
+defaultRepositoryAccess: none
+repositories:
+  control: write
+network: provider-only
+resultSchema: kxm.assignment-result.v1

package/.kxm/gates.yaml

@@ -0,0 +1,8 @@
+schema: kxm.gate-registry.v1
+gates:
+  test:
+    kind: command
+    argv:
+      - npm
+      - test
+    timeoutMs: 3600000

package/.kxm/producers.yaml

@@ -0,0 +1,22 @@
+schema: kxm.producers.v1
+updatedAt: 2026-09-10T17:30:00.000Z
+promoted:
+  - anthropic/fable
+  - openai/gpt-5.6-sol
+  - xai/grok-4.6
+  - openrouter/qwen/qwen3-coder-plus
+demoted: []
+enabled:
+  - anthropic/fable
+  - openai/gpt-5.6-sol
+  - xai/grok-4.6
+  - openrouter/qwen/qwen3-coder-plus
+disabled: []
+roles:
+  implementer:
+    - xai/grok-4.6
+    - openrouter/qwen/qwen3-coder-plus
+  critic-arch:
+    - anthropic/fable
+  critic-cli:
+    - openai/gpt-5.6-sol

package/.kxm/project.yaml

@@ -0,0 +1,15 @@
+schema: kxm.project.v1
+id: prj_kxm_project
+name: KXM
+defaultWorkflow: default
+defaultExecutor: local
+defaultHarness: pi
+repositories:
+  - id: control
+    role: control
+    required: true
+    pathHint: .
+workspace:
+  dirtySnapshot:
+    untracked: ask
+    dirtySubmodules: fail

package/.kxm/roles/writer.yaml

@@ -0,0 +1,7 @@
+schema: kxm.role.v1
+id: writer
+roster:
+  - model: xai/grok-4.6
+    enabled: true
+  - model: openrouter/qwen/qwen3-coder-plus
+    enabled: true

package/.kxm/workflows/default.yaml

@@ -0,0 +1,47 @@
+schema: kxm.workflow.v1
+description: Canonical 4-stage KXM delivery workflow
+coordinator: coordinator
+limits:
+  maxTransitions: 8
+steps:
+  - id: implement
+    kind: agent
+    agent: implementer
+    maxAttempts: 3
+    on:
+      passed: review-arch
+      failed:
+        target: $terminal
+        terminalStatus: failed
+  - id: review-arch
+    kind: agent
+    agent: critic-arch
+    maxAttempts: 2
+    on:
+      passed: review-cli
+      failed:
+        target: implement
+        maxTransitions: 2
+  - id: review-cli
+    kind: agent
+    agent: critic-cli
+    maxAttempts: 2
+    on:
+      passed: verify
+      failed:
+        target: implement
+        maxTransitions: 2
+  - id: verify
+    kind: gate
+    gate: test
+    expect: pass
+    repositories:
+      control: write
+    maxAttempts: 2
+    on:
+      passed:
+        target: $terminal
+        terminalStatus: completed
+      failed:
+        target: implement
+        maxTransitions: 2

package/CHANGELOG.md

@@ -4,15 +4,36 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ## Unreleased
 
+## 0.7.0 - 2026-09-11
+
 ### Added
 
-- **Public npm release automation unlatched (E7):** Unlatched `publish-npm` job
-  in `.github/workflows/release.yml` with `environment: npm-publish`. Added
-  `scripts/kxm-publish-npm.mjs` to enforce fail-closed verification: requires the
-  GitHub release for the tag to be published (`draft: false`), validates the
-  release asset presence and SHA-256 digest against the release manifest, and
-  executes `npm publish --access public`. Added `publishConfig.access: "public"`
-  in root `package.json` and unit test suite `test/core/kxm-publish-npm.test.ts`.
+- **vNext 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
+    context packet with cryptographic SHA-256 hash validation against execution drift.
+  - **Dynamic Permission Ceilings (Phase 2):** Dynamically derives sandbox permissions from step
+    repository access declarations (`birthMember`), failing closed immediately on unauthorized
+    live write access outside declared repository scopes.
+  - **Pinned Route Admission & Roster Verification (Phase 3):** Strictly validates producer model
+    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
+    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
+    with unmetered subscription vs metered cost separation, process stdin piping, and timeout protection.
+- **Universal KontextMind Knowledge-Plane Skill Suite:**
+  - Portable, harness-agnostic skill suite under `.agents/skills/` including repository delivery skills,
+    context memory recall, and lifecycle governance.
+- **Pi Workflow Progress TUI & Studio Dashboard:**
+  - Interactive Pi extension workflow progress terminal user interface with live status bars and web studio layout.
+- **Public npm Release Automation Unlatched (E7):**
+  - Unlatched `publish-npm` job in `.github/workflows/release.yml` with `environment: npm-publish`.
+  - Added `scripts/kxm-publish-npm.mjs` verifying published GitHub release assets, digests, and
+    publishing to npm registry.
 
 ## 0.6.0 - 2026-09-08
 
@@ -109,6 +130,17 @@ All notable user-facing changes are documented here. The project follows [Semant
 
 ### Fixed
 
+- **Windows Claude Code / npm shim detection (issue #168):** `kxm harness list`
+  treated Claude Code as `not_detected` when the CLI was only an npm
+  `claude.cmd` shim (no `claude.exe` on `PATH`). The probe now tries `.exe`,
+  then the allowlisted inner package `claude.exe` next to `claude.cmd`, then
+  `.cmd` on win32. Allowlisted `name.cmd` probes still use `shell: true` and
+  record `windows_shim` when that is what answered. Auth still requires
+  parseable `claude auth status`. Headless assignment (`just assign` /
+  `harness-run`) scans every PATH directory for `name.exe` before any `.cmd`
+  (so a user-bin `codex.cmd` cannot hide `codex.exe`), then unwraps the inner
+  npm `claude.exe` and Pi's `node.exe` plus `cli.js`, without running
+  unverified `.cmd` launchers through a shell.
 - Concurrent Runtime registry and event-store initialization now checks and
   creates the schema under one write transaction, preventing duplicate-table
   failures when a supervisor and status reader first open the same database.

package/README.md

@@ -214,6 +214,7 @@ The hub routes messages; it does not merge contexts, choose tasks, or bypass too
 | 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) |
 | 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) |

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 |
+| [Agent Skills](agent-skills.md) | Users and integrators | Comprehensive skill suite covering all KXM commands with progressive disclosure |
+| [Skills](skills.md) | Operators and skill authors | Governed candidate lifecycle; also the [repository work delivery](skills/repo-work-delivery.md) skill |
 | [Operations](operations.md) | Hub operators | Run, monitor, secure, and recover the service |
 | [Troubleshooting](troubleshooting.md) | Everyone | Diagnose common installation and delivery failures |
 | [Test matrix](test-matrix.md) | Users and maintainers | Map features and use cases to automated evidence |
@@ -15,8 +17,10 @@ This documentation is organized by task. Start with the guide that matches what
 | [Peer provenance and quorum gates](provenance-gates.md) | Workflow authors and security reviewers | Require durable replies from eligible peer identities without overstating the trust guarantee |
 | [Continuous improvement](continuous-improvement.md) | Product and engineering leads | Turn run evidence into reviewed workflow improvements |
 | [Workflow guide](workflow-guide.md) | Workflow designers and operators | Area -> Workflow -> Stage -> Role taxonomy with documentation slugs, dated research candidates, and selection policy |
+| [Templates](templates/README.md) | Workflow authors | Markdown templates for features, ADRs, reviews, runbooks, and related artifacts |
 | [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 |
 
 Project-level policies live at the repository root:

package/docs/agent-skills.md

@@ -0,0 +1,121 @@
+# KXM Agent Skills
+
+This document describes the bundled KXM Agent Skills suite: focused skills
+that cover current KXM top-level command groups. The suite documents the
+existing CLI. It does **not** land unified YAML role/project/workflow
+authority, admit new writers, or replace trusted `.kxm/roster.json` policy.
+
+## Feature-to-Skill Matrix
+
+| Feature Area | Skill | Commands Covered | Purpose |
+|---|---|---|---|
+| Core Routing | `kxm` | — | Select the right suite skill; state universal safety rules and portable CLI convention |
+| Project Setup | `kxm-project-setup` | `init`, `migrate`, `trust`, `config`, `completion` | Initialize, migrate, review permission changes, configure, and install shell completion |
+| Harness & Auth | `kxm-harness-auth` | `harness`, `auth`, `update`, `runtime`, `agent` | Inspect authenticated harness capability and operate supported runtimes/workers |
+| Hub Operations | `kxm-hub-ops` | `hub`, `backup`, `restore` | Run and protect the local hub and its durable SQLite state |
+| Session Management | `kxm-session` | `session`, `dash`, `studio` | Resume/inspect operator work and use UI capabilities each harness supports |
+| Peer Communication | `kxm-peer` | `peer` | Discover, send, poll/await, cancel, fan out, inbox, and reply safely |
+| Workflow Management | `kxm-workflow` | `workflow`, `gate` | Operate webhook workflows, waits/signals, evidence checkpoints, provenance |
+| Definitions | `kxm-definitions` | `role` | Manage role YAML through configuration commands; role edits do not grant trusted writer admission |
+| Run Management | `kxm-runs` | `run`, `runs` | Create and inspect local vNext runs while preserving execution boundaries |
+| Context & Memory | `kxm-context-memory` | `context`, `memory` | Query role-aware context and manage Git-authored memory proposals |
+| Skill Lifecycle | `kxm-skill-lifecycle` | `skills` | Govern candidate/evaluate/promote/reject/verify lifecycle |
+| Routing & Improve | `kxm-routing-improve` | `routing`, `improve` | Inspect real route quality/cost and propose reviewed improvements |
+| Tasks & Goals | `kxm-tasks` | `suggest`, `goal`, `task` | Recommend workflows and manage goals/tasks with SCM/tracker boundaries |
+
+## Installation and Discovery
+
+### For Pi Users
+
+Pi automatically discovers skills in the `pi.skills` section of `package.json`. The KXM skills are included in the standard distribution:
+
+```json
+{
+  "pi.skills": [
+    "./plugins/kxm/skills"
+  ]
+}
+```
+
+### For Claude Users
+
+Claude plugins package the authored skills from `plugins/kxm/skills/` during the build process.
+
+### For Other Harnesses
+
+Skills in `.agents/skills/` follow the standard agent skill format. Discovery
+outside Pi and Claude remains harness-specific; do not assume every consumer
+loads this mirror.
+
+## Progressive Disclosure Usage
+
+1. Start with the core `kxm` skill to choose a specialized skill.
+2. Use the named skill for that command group.
+3. Teach only verbs and options that exist in `kxm <group> --help`.
+
+### Example Usage Patterns
+
+```bash
+kxm peer list --json
+kxm peer send --target alice --content "Please review" --json
+kxm workflow list --json
+kxm workflow checkpoint run_123 stage_a passed "Completed stage A" --json
+```
+
+## Verified vs Unverified Harness Limits
+
+### Verified Harnesses
+
+- **Pi**: Discovers `plugins/kxm/skills`
+- **Claude**: Plugin packaging of the authored skills
+- **Codex**: Consumes the generated `.agents/skills` mirror and AGENTS command block
+
+### Unverified Harnesses
+
+The following harnesses have discovery claims that remain explicitly unverified:
+
+- **Kimi**: `.agents/skills` consumer capability unverified
+- **Copilot**: Integration capability unverified
+- **OpenCode**: Compatibility unverified
+- **Other `.agents/skills` consumers**: Capabilities unverified
+
+## Distinguishing Operational vs Governed Skills
+
+### Bundled Operational Skills
+
+The skills in this suite (`kxm-*`) are bundled and operational by default. They map 1:1 with KXM's top-level command groups and are maintained as part of the core KXM distribution.
+
+### Governed Candidates
+
+Separately, `kxm skills` manages community or experimental candidates through
+create/evaluate/promote/reject/verify. Those governed skills are distinct from
+this bundled suite. Telemetry cannot auto-promote a skill. See
+[Skill candidate lifecycle](skills.md) for the full lifecycle, and
+[Repository work delivery](skills/repo-work-delivery.md) for converting a
+repository request into a delivery prompt.
+
+## Development and Maintenance
+
+### Authoring Location
+
+Skills are authored in `plugins/kxm/skills/` as the primary source of truth.
+
+### Generated Mirror
+
+`scripts/emit-codex-artifacts.mjs` copies owned skills byte-for-byte to
+`.agents/skills/` and leaves unrelated skills in that tree untouched. The
+suite manifest `plugins/kxm/skill-suite.json` is required; missing, symlink,
+or malformed manifests fail closed.
+
+### Build Process
+
+1. Validate `plugins/kxm/skill-suite.json`
+2. Replace owned generated skill directories
+3. Preserve foreign skills in `.agents/skills/`
+4. `scripts/check-generated.mjs` requires every owned mirror path
+
+### Testing
+
+- `test/core/skill-suite.test.ts` validates command coverage and mirrors
+- `test/core/commands-policy.test.ts` checks taught verbs against `cli.ts`
+- `test/core/generated-artifacts.test.ts` checks manifest-backed generated paths

package/docs/architecture.md

@@ -163,7 +163,7 @@ Workflow session isolation is a context-routing and accidental-cross-run safety
 
 | Path | Responsibility |
 |---|---|
-| `.kxm/config/` | Tracked workspace workflow and harness configuration |
+| `.kxm/` | Tracked workspace workflow and harness configuration |
 | `.kxm/logs/` | Ignored hub, worker, and Pi process logs |
 | `.kxm/assets/` | Intentional workflow inputs and outputs |
 | `.kxm/state/` | Ignored SQLite and restart-recovery state |

package/docs/assignment-runner.md

@@ -35,6 +35,17 @@ and models are admitted with strict permission and vendor boundaries:
   a requested harness/model is not in the admitted role lineup, or if permissions
   exceed the admitted ceiling (e.g. attempting to give edit permissions to a
   read-only reviewer).
+- **Trusted roster policy:** Dispatch (`assign` / `run`) and accept load
+  `.kxm/roster.json` through the trusted control Git loader
+  (`loadTrustedRosterPolicy`). Loader errors, missing/empty policy, and
+  malformed policy fail closed with `route_invalid`. There is no raw working-tree
+  JSON fallback and no null-policy acceptance. Tests may inject an explicit
+  policy object; that seam is not a CLI or environment bypass. The witness
+  verifies the bound candidate against the fixed gate (`npm run verify`) and
+  does not itself call the policy loader today. Unified YAML
+  role/project/workflow authority is still open and is not this runner's live
+  source. Passive `schemas/policy-draft` / `validatePolicyDraft` scaffolding is
+  not operator settings and is not admission.
 - **Deterministic witness beats extra models:** Implementers run `npm run verify`.
   Root re-runs the fixed witness. Reviewers verify candidate trees; they do not
   replace tests.
@@ -145,14 +156,16 @@ node scripts/assignment-run.mjs accept \
 
 `accept` validates all acceptance invariants:
 
-1. The commit exists and its tree matches the witness index tree.
-2. The writer record matches the latest passed witness.
-3. Both required critic roles (`review-arch` and `review-cli`) are present.
-4. Both critics judged the exact accepted tree and issued `PASS`.
-5. No unresolved `BLOCK` review exists for the tree in the task directory (unless
+1. Trusted roster policy is loaded and valid **before** acceptance artifacts are
+   written. Failure to obtain required policy refuses acceptance.
+2. The commit exists and its tree matches the witness index tree.
+3. The writer record matches the latest passed witness.
+4. Both required critic roles (`review-arch` and `review-cli`) are present.
+5. Both critics judged the exact accepted tree and issued `PASS`.
+6. No unresolved `BLOCK` review exists for the tree in the task directory (unless
    superseded by an unbroken `rework_of` lineage).
-6. The writer and all critics satisfy pairwise vendor independence.
-7. Writes `accepted.json` (`kxm.task-accepted.v1`) into the task directory.
+7. The writer and all critics satisfy pairwise vendor independence.
+8. Writes `accepted.json` (`kxm.task-accepted.v1`) into the task directory.
 
 ---
 
@@ -206,7 +219,7 @@ The runner fails closed with bounded error codes defined in `RUNNER_CODES`:
 
 | Code | Trigger condition | Remedy |
 |---|---|---|
-| `route_invalid` | Harness/model not admitted in lineup for the requested role, or permission exceeds route ceiling. | Check `.kxm/roster.json` lineup and permissions for the role. |
+| `route_invalid` | Harness/model not admitted in lineup for the requested role, permission exceeds route ceiling, or trusted roster policy cannot be loaded/validated. | Use a trusted clean control checkout; do not dispatch from a dirty implementation branch. Check `.kxm/roster.json` lineup and permissions for the role. |
 | `critic_invalid` | Missing required critic role, duplicate roles, wrong model, or vendor collision between writer and critics. | Ensure independent critics (Fable + Sol) from distinct providers. |
 | `critic_block` | An unresolved `BLOCK` verdict exists for the target tree. | Rework the changes, address findings, and pass review with a `rework_of` link. |
 | `commit_tree_mismatch` | Git commit tree does not equal the witnessed tree. | Commit the exact candidate tree verified by the witness before running accept. |

package/docs/configuration.md

@@ -74,6 +74,15 @@ rewrites it.
 
 The hub refuses a non-loopback bind without `KXM_AUTH_TOKEN`. Use a long random administrative token even when project tokens are configured, because administrative endpoints such as `/metrics` require it outside loopback.
 
+When `KXM_AUTH_TOKEN` is unset, `kxm hub start` resolves credentials from the
+persisted `kxm.hub-env.v1` file under the user state root
+(`~/.local/state/kxm/hub-env.json`; honors `KXM_STATE_HOME` and platform
+equivalents). A missing admin token is generated once, persisted with `0600`
+permissions, and reused across hub restarts so workers and dashboards on the
+same machine share one stable credential. Explicit `KXM_AUTH_TOKEN` or
+`KXM_PROJECT_TOKENS` environment values take precedence and are persisted for
+later restarts. Delete the file and restart to rotate the generated token.
+
 Project tokens are an authorization boundary. A project-specific token can register only in its mapped project and see only that project's agents and messages. The administrative token remains a fallback for projects without an explicit entry. For provenance-gated workflows, configure an explicit project token and give workers only that token; reserve a distinct administrative token for operations such as quorum degradation approval.
 
 PowerShell example:
@@ -269,7 +278,7 @@ Global flags: `--json`, `--dry-run`, `--workspace`. Project-root `kxm init` disc
 
 Configure either `KXM_WEBHOOK_WORKFLOWS` or `KXM_WEBHOOK_WORKFLOWS_FILE`, never both. A definition selects a provider source, project, coordinator, event and payload filters, prompt template, and ordered stages. Use `secretEnv` to resolve the workflow-start HMAC secret from another environment variable. Use the optional `signalSecretEnv` for a separate callback secret; otherwise external signals use the workflow-start secret. Do not store either secret in JSON.
 
-See [Webhook workflows](webhook-workflows.md) for the base schema and the complete Jira configuration under `.kxm/config/workflows`. See [Peer provenance and quorum gates](provenance-gates.md) for `evidencePolicies`, `workflowContext`, `evidenceRefs`, and explicit degradation.
+See [Webhook workflows](webhook-workflows.md) for the base schema and the complete Jira configuration under `.kxm/workflows`. See [Peer provenance and quorum gates](provenance-gates.md) for `evidencePolicies`, `workflowContext`, `evidenceRefs`, and explicit degradation.
 
 ## Delivery modes
 
@@ -279,7 +288,7 @@ See [Webhook workflows](webhook-workflows.md) for the base schema and the comple
 | `steer` | An active blocker requires a course change | Deliver at the next decision boundary |
 | `nextTurn` | Information should wait for a later turn | Queue context without immediate work |
 
-`followUp` is the safe default. Use [`.kxm/config/env.example`](../.kxm/config/env.example) as a reference, but load values through your shell, supervisor, container platform, or secret manager. Never commit real tokens.
+`followUp` is the safe default. Load values through your shell, supervisor, container platform, or secret manager using the variables documented on this page and in the [KXM Handbook](kxm-handbook.md). Never commit real tokens.
 
 ## Nous providers (opt-in)
 

package/docs/getting-started.md

@@ -61,6 +61,27 @@ kxm init
 
 `kxm init` never copies the package repository's dogfood roster or workflows into a consumer workspace.
 
+When `kxm init` succeeds in an interactive terminal, it offers to install shell
+completion for the detected shell. Accepting writes the completion script
+under the user config directory, appends one idempotent stanza to the shell
+rc file, and, when the kxm bin directory is not already on `PATH`, adds a
+`PATH` export. Declining is safe: run `kxm completion install` later, or set
+`KXM_SKIP_COMPLETION_PROMPT=1` to suppress the offer. Non-interactive,
+`--json`, and `--dry-run` runs never prompt or write shell files.
+
+After the completion offer, an interactive `kxm init` also offers to set up
+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 —
+`.kxm/agents/<role>.yaml` (`kxm.agent.v1`) and `.kxm/workflows/<slug>.yaml`
+(`kxm.workflow.v1`). It never writes retired legacy authority (`.kxm/config`,
+`.kxm/roster.json`). Roles whose candidates have no authenticated harness are
+reported as skipped, not silently downgraded. Guide candidates are dated
+research — verify them before dispatch. Declining is safe: set
+`KXM_SKIP_GUIDE_SETUP_PROMPT=1` to suppress the offer.
+
 ## 3. Start the hub in another terminal
 
 `kxm hub start` is foreground. Keep that terminal running.

package/docs/kxm-handbook.md

@@ -695,7 +695,7 @@ Claude MCP also exposes:
 Set exactly one of:
 
 ```text
-KXM_WEBHOOK_WORKFLOWS_FILE=.kxm/config/workflows/product.json
+KXM_WEBHOOK_WORKFLOWS_FILE=.kxm/workflows/default.yaml
 ```
 
 or:
@@ -712,7 +712,7 @@ required evidence, attempt limits, and optional peer policies.
 Validate before restart:
 
 ```powershell
-kxm gate validate --file .kxm/config/workflows/product.json
+kxm gate validate --file .kxm/workflows/default.yaml
 ```
 
 Secrets belong in environment variables named by `secretEnv` and
@@ -921,7 +921,7 @@ with content hashes. See `docs/skills.md` for the full lifecycle.
 
 ### Reference /fix workflow
 
-`.kxm/config/workflows/fix.json` implements the reference bug-fix flow:
+`.kxm/workflows/default.yaml` implements the reference bug-fix flow:
 read-only exploration, a tests-only reproduction draft, independent two-critic
 `repro-review` that captures the immutable oracle (a sibling API is invalid),
 plan review by independent critics, a human approval gate, bounded rework

package/docs/operations.md

@@ -21,10 +21,34 @@ These operator commands assume the packed release CLI installation from
 [Getting started](getting-started.md#install-the-operator-command). From a
 source clone, use `npm run hub` instead.
 
+When `KXM_AUTH_TOKEN` is not set, `kxm hub start` loads the persisted hub
+credential file (schema `kxm.hub-env.v1`) under the user state root
+(`~/.local/state/kxm/hub-env.json` on Linux, honoring `KXM_STATE_HOME` and
+platform equivalents). If no persisted token exists, a long random
+administrative token is generated, saved there with `0600` permissions, and
+used. The hub therefore never silently starts with `auth=none` because a
+token was forgotten; a missing token is created once and reused by every
+later restart, worker, and dashboard on the same machine. Explicit
+`KXM_AUTH_TOKEN` / `KXM_PROJECT_TOKENS` environment values always win and are
+persisted so restarts keep them. The generated value is never printed in
+full; kxm only reports which file it came from.
+
 Stop with `Ctrl+C` or `SIGTERM`. The hub stops accepting connections, closes SSE streams, waits for active HTTP connections, and closes SQLite.
 
 For unattended service, use a supervisor that sets a stable working directory, injects secrets, captures stdout, restarts after failure, and allows at least five seconds for graceful shutdown.
 
+### PID claims and restart recovery
+
+The hub wrapper records its own PID and the server child PID in
+`.kxm/state/hub.pid`. A claim whose wrapper is dead is reclaimed automatically
+on the next `kxm hub start`; when the dead wrapper left an orphaned server
+child behind (for example after `SIGKILL` or a machine crash), the new
+wrapper terminates that orphan before reclaiming. `kxm hub stop` also
+recovers orphans directly: it signals a still-running recorded server child
+of a dead wrapper, waits for exit, and removes the stale claim. Malformed or
+foreign PID claims stay fail-closed; remove those only after verifying no
+hub process is running.
+
 Run each long-lived coordinator with `kxm agent worker --name <stable-name> --project <project> [--model <provider/model>] [--fallback-models <provider/model,...>] [--tools <name,...>]` under a separate service-manager unit. Use distinct worktrees for concurrent writers, explicit CPU and memory limits, and restart throttling outside the built-in bounded backoff. Enforce role ownership with the Pi tool allowlist: omit `bash`, `edit`, and `write` from read-only reviewers, even if their prompt also says not to edit. The worker launches Pi RPC mode and retains the most recent session unless configured otherwise. Use `--fresh-start` for a clean first session that may still resume after a later provider failure; reserve `--no-continue` for a worker that must never resume. For release verification, configure the [exact extension and skill sets](configuration.md#long-lived-worker-settings), including every required provider extension; configured categories disable discovery and fail closed on invalid paths. `kxm hub stop` writes a generation-matched control request; the worker asks Pi RPC to abort, waits for confirmation and state flush, and only force-stops the process tree after the bounded drain deadline. A final provider error leaves the inbound hub message delivered, gracefully restarts Pi, rotates to an unused fallback model, and preserves the session; Pi's own automatic retries always finish first. A tool that exceeds `KXM_WORKER_TOOL_TIMEOUT_MS` follows the same durable restart path without changing models. If `--continue` reports an invalid tool-result session, the worker retries once fresh, journals a redacted recovery envelope, and injects a bounded resume instruction for the durable run and stage. Do not copy `pi-agent-*.log` into journals or retrospectives.
 
 ### Workflow-specific Pi sessions

package/docs/operator-pi-packages.md

@@ -0,0 +1,63 @@
+# This host's Pi packages
+
+Snapshot of the operator Pi user packages and file extensions on this KXM
+development host (2026-09-10). It is **not** a KXM install requirement and is
+**not** copied by `kxm init`. `pi list` is authoritative; this page is a
+checked-in copy for agents working in this repository.
+
+## User packages (`pi list`)
+
+| Source | Version | What it loads |
+|---|---|---|
+| `npm:pi-antigravity` | 0.7.2 | Antigravity / Cloud Code Assist provider (`./src/index.ts`) |
+| `git:git@github.com:kontextmind/kxm.git@main` | 0.6.0 (`10a1b77` at snapshot) | KXM Pi extension and Agent Skills |
+| `npm:@xynogen/pix-core` | 0.5.38 | pix UI/tool aggregator (`src/extension.ts`); activates bundled pix members, not separate `pi list` sources |
+| `npm:@tian.zuo/pi-antigravity` | 0.10.3 | Antigravity via `agy` stream-json (`./index.ts`) |
+| `npm:@latentminds/pi-quotas` | 0.5.0 | Quota and usage status commands |
+| `npm:pi-provider-kimi-code` | 0.6.12 | Kimi Code provider (`./index.ts`) |
+
+Install roots on this host:
+
+- npm: `%USERPROFILE%\.pi\agent\npm\node_modules\`
+- git KXM: `%USERPROFILE%\.pi\agent\git\github.com\kontextmind\kxm`
+
+Project-local Pi extension (gitignored `.pi/`): `.pi/extensions/rtk.ts` from
+`rtk init --agent pi`. User-level `~/.pi/agent/extensions/rtk.ts` is also
+installed.
+
+## File extensions
+
+Loaded from `%USERPROFILE%\.pi\agent\extensions\` (not shown by `pi list`):
+
+| File | Role |
+|---|---|
+| `rtk.ts` | RTK bash rewrite via `rtk rewrite`; needs `rtk` 0.23 or newer on `PATH` |
+| `quotas.json` | Config for `@latentminds/pi-quotas`, not an extension factory |
+
+`rtk` 0.48.0 is installed as winget `rtk-ai.rtk`. New shells pick up the User
+`PATH` entry. `pix-core` also activates `pix-optimizer`, which can rewrite
+commands for RTK independently of `rtk.ts`.
+
+## Notes
+
+- `pi-antigravity` and `@tian.zuo/pi-antigravity` are different Pi providers.
+  They do not replace the native `agy` harness used by the assignment runner.
+- For KXM development loads, prefer the working tree:
+  `pi --no-extensions -e ./plugins/kxm/src/extension.ts`. Add every required
+  provider extension with another `-e`; otherwise Pi discovery is disabled.
+  See [Troubleshooting](troubleshooting.md#pi-shows-huboff).
+- Refresh this page when `pi list` or
+  `%USERPROFILE%\.pi\agent\extensions\` changes.
+
+## Project-scoped RTK (this checkout)
+
+`rtk init` in this repository (2026-09-10). Not copied by `kxm init`.
+
+| Path | Role |
+|---|---|
+| `RTK.md` | Slim RTK instructions for Codex and `@RTK.md` includes |
+| `AGENTS.md` | `@RTK.md` reference (Codex / Kimi) |
+| `CLAUDE.md` | `@RTK.md` reference (Claude Code) |
+| `.rtk/filters.toml` | Project filter template |
+| `.agents/rules/antigravity-rtk-rules.md` | Antigravity rules |
+| `.pi/extensions/rtk.ts` | Project Pi rewrite extension (gitignored) |