@kontextmind/kxm 0.7.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.7.0",
+      "version": "0.7.4",
       "category": "development",
       "tags": ["kxm", "multi-agent", "workflows", "mcp"]
     }

package/.kxm/roles/writer.yaml

@@ -1,5 +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/docs/README.md

@@ -9,6 +9,7 @@ This documentation is organized by task. Start with the guide that matches what
 | [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 |
@@ -16,6 +17,7 @@ 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 |

package/docs/agent-skills.md

@@ -10,7 +10,7 @@ authority, admit new writers, or replace trusted `.kxm/roster.json` policy.
 | 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 add shell completion |
+| 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 |
@@ -89,7 +89,10 @@ The skills in this suite (`kxm-*`) are bundled and operational by default. They
 
 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.
+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
 

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:
@@ -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/env.example`](../ .kxm/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/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/skills/repo-work-delivery.md

@@ -100,3 +100,8 @@ A prompt produced with this skill includes:
 12. PR, CI/review monitoring, bounded remediation, and merge gate
 13. Verified post-merge cleanup
 14. Completion report
+
+## Related
+
+- [Agent Skills](../agent-skills.md) — bundled command-suite skills
+- [Skill candidate lifecycle](../skills.md) — governed `kxm skills` candidates

package/docs/skills.md

@@ -2,6 +2,8 @@
 
 KXM turns verified episodes and lessons into reusable Agent Skills through a governed lifecycle. Runtime experience never becomes promoted skill content automatically, and promoted skills never grant tool or permission authority.
 
+This page is the governed `kxm skills` lifecycle. For the bundled command-suite skills, see [Agent Skills](agent-skills.md). For converting a repository request into a delivery prompt, see [Repository work delivery](skills/repo-work-delivery.md).
+
 ## Lifecycle
 
 ```text

package/docs/troubleshooting.md

@@ -28,7 +28,7 @@ Set `KXM_WORKER_TOOL_TIMEOUT_MS` above the longest legitimate tool call. Its 31-
 
 ### A hub or worker PID claim is stale
 
-Version 0.4.3 prevents a second wrapper from replacing a live hub or worker claim. `kxm hub stop` ignores an invalid, non-running, or ownership-mismatched record rather than guessing. If a crash or pre-0.4.3 process left one behind, inspect the exact `.pid` JSON and verify that its recorded PID is no longer running; for a hub, also verify the configured port has no listener. Then remove only that exact `.pid` and its recorded `.stop` control file before relaunching once. Worker filenames include a project/agent identity digest and their records include the exact names and generation, so do not substitute a similarly sanitized filename. Never delete the `.kxm/state` directory or SQLite database to clear a claim.
+Version 0.4.3 prevents a second wrapper from replacing a live hub or worker claim. `kxm hub stop` ignores an invalid, non-running, or ownership-mismatched record rather than guessing. A hub claim whose wrapper PID is dead is reclaimed automatically on the next `kxm hub start`; the wrapper also terminates an orphaned hub server child recorded by a dead wrapper (for example after `SIGKILL`) before reclaiming, and `kxm hub stop` can stop such an orphan directly. If a pre-0.4.3 process left a malformed claim behind, inspect the exact `.pid` JSON and verify that its recorded PID is no longer running; for a hub, also verify the configured port has no listener. Then remove only that exact `.pid` and its recorded `.stop` control file before relaunching once. Worker filenames include a project/agent identity digest and their records include the exact names and generation, so do not substitute a similarly sanitized filename. Never delete the `.kxm/state` directory or SQLite database to clear a claim.
 
 ### GitHub checks passed but the workflow is still waiting
 
@@ -44,6 +44,14 @@ Set `KXM_PORT` to a valid integer. Remove the variable to use `7331`.
 
 Either restore `KXM_HOST=127.0.0.1` or configure a token before using a non-loopback interface.
 
+**`KXM hub env file is malformed`**
+
+The persisted credential file (`hub-env.json` under the user state root) failed
+validation. It holds only `KXM_AUTH_TOKEN` / `KXM_PROJECT_TOKENS` values in
+`kxm.hub-env.v1` schema; fix its JSON or delete it to have kxm generate a
+fresh admin token on the next start. To rotate the generated token, delete
+the file and run `kxm hub start` again.
+
 #### Database schema is newer than this runtime supports
 
 Do not delete or rewrite the database. Start the package version that created it, or upgrade this runtime. Restore the pre-upgrade backup when rolling back.
@@ -107,6 +115,19 @@ release asset through the authenticated `gh release download` flow in
 `node scripts/kxm.mjs` from a clone after `npm ci`. `npx kxm` and a
 global `git+https` npm install are not supported installation paths.
 
+For bash and zsh, `kxm completion install` can add the kxm bin directory to
+`PATH` in the shell rc file when it is missing; restart the shell afterwards.
+
+### Tab completion is not active
+
+Run `kxm completion install` for the detected shell, or pass
+`--shell bash|zsh|fish` explicitly. The install appends one guarded stanza to
+the shell rc file and is idempotent: rerunning never duplicates it. Fish needs
+no rc entry because fish auto-loads `~/.config/fish/completions`. After
+installing, start a new terminal or `source` the rc file. To inspect without
+writing, use `--dry-run`; to suppress the post-`kxm init` offer, set
+`KXM_SKIP_COMPLETION_PROMPT=1`.
+
 ### An expected peer is missing
 
 The two agents usually have different `KXM_PROJECT` values or one stopped sending heartbeats. Compare settings and check for an `agent_stale` event. Names and projects are case-sensitive for display; live-name uniqueness is case-insensitive.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontextmind/kxm",
-  "version": "0.7.0",
+  "version": "0.7.4",
   "description": "KXM local-first multi-agent orchestration and operator dashboard",
   "type": "module",
   "author": "KontextMind",

package/plugins/kxm/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "kxm",
   "displayName": "KXM",
-  "version": "0.7.0",
+  "version": "0.7.4",
   "description": "Headless multi-agent orchestration, durable workflows, and a live operator dashboard for Pi and Claude Code",
   "author": {
     "name": "KontextMind",