@kontextmind/kxm 0.7.122 → 0.7.124

package/docs/reference/cli-reference.md

@@ -14,7 +14,7 @@ Output shown under examples was captured from a source checkout, inside a throwa
 - Setup: [`init`](#kxm-init), [`config`](#kxm-config), [`completion`](#kxm-completion), [`trust`](#kxm-trust)
 - Hub and sessions: [`hub`](#kxm-hub-view), [`session`](#kxm-session), [`dash`](#kxm-dash), [`studio`](#kxm-studio)
 - Harnesses, models, and roles: [`harness`](#kxm-harness), [`auth`](#kxm-auth), [`update`](#kxm-update), [`models`](#kxm-models), [`routes`](#kxm-routes), [`role`](#kxm-role)
-- Running work: [`lane`](#kxm-lane), [`assign`](#kxm-assign), [`run`](#kxm-run), [`runs`](#kxm-runs), [`runtime`](#kxm-runtime), [`agent`](#kxm-agent), [`workflow`](#kxm-workflow), [`gate`](#kxm-gate), [`peer`](#kxm-peer), [`task`](#kxm-task), [`goal`](#kxm-goal), [`suggest`](#kxm-suggest), [`explain`](#kxm-explain)
+- Running work: [`lane`](#kxm-lane), [`land`](#kxm-land), [`assign`](#kxm-assign), [`run`](#kxm-run), [`runs`](#kxm-runs), [`docs`](#kxm-docs), [`runtime`](#kxm-runtime), [`agent`](#kxm-agent), [`workflow`](#kxm-workflow), [`gate`](#kxm-gate), [`peer`](#kxm-peer), [`task`](#kxm-task), [`goal`](#kxm-goal), [`suggest`](#kxm-suggest), [`explain`](#kxm-explain)
 - Context and learning: [`context`](#kxm-context), [`memory`](#kxm-memory), [`skills`](#kxm-skills), [`improve`](#kxm-improve), [`routing`](#kxm-routing), [`prices`](#kxm-prices)
 - Operations: [`backup`](#kxm-backup), [`restore`](#kxm-restore), [`tenant`](#kxm-tenant), [`ssh`](#kxm-ssh), [`help`](#kxm-help)
 - [Known behavior gaps](#known-behavior-gaps)
@@ -100,7 +100,7 @@ kxm -V
 `--dry-run` changes nothing: no file is written, deleted, or moved, no request that changes hub or Runtime state is sent, no process is started, and no remote command runs. A command that cannot say what it would do without doing some of it refuses the flag instead of acting.
 
 - Plan with `planned`: `backup`, `restore`, `config set`, `role add|remove|modify|set-host|resume`, `workflow add|remove|modify`, `goal create`, `task create|run|sync`, `memory note|sync`, `skills evaluate|promote|reject`, `context promote`, `context wiki-compile --out`, `auth token`, `session token`, `session brief`, and `ssh run|file|close`. Each prints its normal result plus `dryRun: true` and `planned`, a list of `{action, target}` entries whose `action` is `write`, `delete`, `move`, `request`, or `ssh`. Text mode prints `dry run: <summary>` and one indented `would <action> <target>` line per entry (`session brief` appends `dry run: would write <file>` lines to the brief instead).
-- Plan in their own shape (described in each section): `init`, `run`, `runs drive|cancel`, `runtime start|stop|sync-retry`, `hub start|stop|bind|unbind`, `session start|stop`, `agent worker`, `dash`, `studio serve`, `models inventory-refresh`, `routes admit|disable`, `update`, `completion install`, `workflow start|signal|export|checkpoint|record|wait`, every `peer` subcommand, `gate degrade|signal`, `skills create`, and `improve report`. `gate github watch --dry-run` still polls GitHub but does not post the signal.
+- Plan in their own shape (described in each section): `init`, `run`, `runs drive|cancel`, `docs build|serve`, `runtime start|stop|sync-retry`, `hub start|stop|bind|unbind`, `session start|stop`, `agent worker`, `dash`, `studio serve`, `models inventory-refresh`, `routes admit|disable`, `update`, `completion install`, `workflow start|signal|export|checkpoint|record|wait`, every `peer` subcommand, `gate degrade|signal`, `skills create`, and `improve report`. `gate github watch --dry-run` still polls GitHub but does not post the signal.
 - Read-only commands run as usual, without leaving a trace: a local SQLite store is opened without creating `-wal` or `-shm` files, and `runs status|list|receipt` only attach to a running Runtime supervisor. With no supervisor running they exit 2 with `dry_run_unsupported` instead of starting one. `context wiki-compile --dry-run` still asks the hub to compile, which is a read.
 - Refused: `kxm models` (the interactive screen) and `kxm prices acknowledge` exit 2 with `dry_run_unsupported`. The CLI keeps one list of the commands that answer `--dry-run` and refuses every other command the same way before it runs, so a command added without dry-run support fails closed.
 
@@ -147,7 +147,7 @@ Exit 2 covers an unknown command or option, a missing argument or required optio
 | User config directory (`KXM_USER_CONFIG_DIR`, default `~/.config/kxm`) | `config.yaml` (user scope), `session.token`, global `roles/` and `workflows/`, `role-hosts.yaml`, `completions/` | `config --scope user`, `auth token`, `session brief\|token`, `role`/`workflow` with `--scope global`, `studio serve`, `completion install` |
 | User state root (`KXM_STATE_HOME`; macOS `~/Library/Application Support/KXM`; Linux `$XDG_STATE_HOME/kxm` or `~/.local/state/kxm`; Windows `%LOCALAPPDATA%\KXM`) | `hub-env.json` (persisted hub credentials), `hub-binding.json`, `runtime/` (Runtime supervisor registry and per-project run stores), `update.yaml`, repository bindings | `hub start\|bind\|unbind`, every hub client, `run`, `runs`, `runtime`, `tenant status`, `update`, `init --repository`, and (read-only, the project's run store) `improve` and `routing report` |
 
-`init`, `trust`, `run`, `runs`, `runtime sync-retry`, `tenant status`, and `studio layout` find the project root by walking up from the current directory. `improve` and `routing report` use the current directory's Git root when it holds `.kxm/project.yaml`, to find the project's Runtime run store (and, for `improve`, its configuration and default candidate directory). `config`, `role`, `workflow definitions|add|remove|modify`, `goal`, `task`, `memory`, `skills`, `backup`, `restore`, `studio serve`, and `ssh` (socket directory) use `.kxm` in the current directory. Run those from the project root.
+`init`, `trust`, `run`, `runs`, `docs build`, `docs serve`, `runtime sync-retry`, `tenant status`, and `studio layout` find the project root by walking up from the current directory. `improve` and `routing report` use the current directory's Git root when it holds `.kxm/project.yaml`, to find the project's Runtime run store (and, for `improve`, its configuration and default candidate directory). `config`, `role`, `workflow definitions|add|remove|modify`, `goal`, `task`, `memory`, `skills`, `backup`, `restore`, `studio serve`, and `ssh` (socket directory) use `.kxm` in the current directory. Run those from the project root.
 
 ## Task to command
 
@@ -1431,7 +1431,7 @@ Refusals (exit 1): `lane_missing`, `lane_dirty`, `lane_run_open`, `lane_git_fail
 
 Creates the lane when the record is absent (same rules as `create`), refuses `lane_run_open` when the last run is not settled, then runs the same path as `kxm run --lane <unit> --brief <file>` and `kxm runs drive <runId> --lane <unit>`. `--wait` and `--timeout-ms` are passed through. The run id is stored on the record. Prints the run envelope and the drive result. That open-run check may start the Runtime supervisor; `--dry-run` only attaches to a supervisor that is already running. `kxm lane status` never starts the supervisor.
 
-`--brief` is required. `--workflow` defaults to the lane project's `defaultWorkflow`. `--base` applies only when the lane is created. A live writer step through this verb is subject to the Runtime's one-shot process timeout, which is 120 seconds until `limits.agentStepTimeoutMs` lands, so long implementation briefs should use `just impl-bg` until then (see section 4 of `plans/plan-lane-cli.md`).
+`--brief` is required. `--workflow` defaults to the lane project's `defaultWorkflow`. `--base` applies only when the lane is created. A live agent step uses the step `timeoutMs` when it is set, otherwise the project `limits.agentStepTimeoutMs` (default 3,600,000). This repository's `implement-only`, `review-arch-only`, and `review-cli-only` workflows are the lane forms of the retired transport recipes.
 
 Refusals (exit 1): `brief_unreadable`, `lane_unit_invalid`, `lane_exists`, `lane_base_unresolved`, `lane_run_open`, `lane_git_failed`, `lane_not_project`, `lanes_unreadable`.
 
@@ -1562,6 +1562,59 @@ Prints the task's attempts, rework, and spend. The runner keeps provider-reporte
 |---|---|---|
 | `--task-dir` | `<path>` | Absolute path to the task directory |
 
+## `kxm docs`
+
+Build and serve the tailnet docs site from this checkout. Both subcommands need a KXM project: the Git root that contains `.kxm/project.yaml`. They run from that root. No hub and no Runtime supervisor.
+
+```text
+kxm docs build
+kxm docs serve [--port <port>]
+```
+
+```bash
+kxm docs build --dry-run
+kxm docs serve --dry-run --port 8765
+```
+
+### `kxm docs build`
+
+Runs `node plans/kxm-roadmap/update-dashboard.mjs` and returns that process's exit code. The generator refreshes the roadmap pages and the MkDocs inputs from `plans/kxm-roadmap/state.json`. `kxm docs build` validates the state file and refuses on schema failure.
+
+The build needs either `mkdocs` on `PATH` or `uv`. The command that works on this machine is `uv tool run --from mkdocs-material mkdocs build`. `uv tool install mkdocs-material` does not, because the package exposes no executable. When neither executable exists, the generator refuses with that same pair of options.
+
+- No command-specific options.
+- Honors `--dry-run`: prints `node plans/kxm-roadmap/update-dashboard.mjs` and does not start the process. JSON key: `detail` (that command line), plus `dryRun: true`.
+- Errors (exit 1): `project_required`, `docs_generator_missing` when `plans/kxm-roadmap/update-dashboard.mjs` is absent.
+
+### `kxm docs serve`
+
+Runs `python3 ops/docs-site/serve.py` with output streamed to the terminal, and returns that process's exit code. `--port` is appended as `--port <port>` when it is set. The server binds a tailnet address. With `--port`, it binds only that port and exits if the port is taken. Without `--port`, it tries 80 and then 8765 through 8780. See `ops/docs-site/serve.py`.
+
+| Option | Argument | Default | Description |
+|---|---|---|---|
+| `--port` | `<port>` | the server's own port list | Port passed through to `serve.py` |
+
+- Honors `--dry-run`: prints `python3 ops/docs-site/serve.py` (and `--port <port>` when given) and does not start the process. JSON key: `detail`.
+- Errors (exit 1): `project_required`, `docs_server_missing` when `ops/docs-site/serve.py` is absent.
+
+```bash
+kxm docs build --dry-run --json
+```
+
+```text
+{"schema":"kxm.cli-result.v1","ok":true,"command":"docs build","dryRun":true,"detail":"node plans/kxm-roadmap/update-dashboard.mjs"}
+```
+
+```bash
+kxm docs serve --dry-run --json
+```
+
+```text
+{"schema":"kxm.cli-result.v1","ok":true,"command":"docs serve","dryRun":true,"detail":"python3 ops/docs-site/serve.py"}
+```
+
+A live `kxm docs serve` runs until the server exits. Not run for this page.
+
 ## `kxm run`
 
 ```text

package/docs/reference/config-reference.md

@@ -165,6 +165,7 @@ makes a directory a KXM project. Parser: `loadKxmProject` in
 | `limits.maxConcurrentRuns` | Integer, 1 to 128 | Optional, `1` | Runtime admission. A changed bound is refused (`scheduler_policy_conflict`) while admitted or queued runs still use the previous one. |
 | `limits.maxRunDurationMs` | Integer, 0 to 31,536,000,000 | Optional | Runtime. Combined with the workflow's own value; the smaller one wins. |
 | `limits.maxAgentTimeMs` | Integer, 0 to 31,536,000,000 | Optional | Runtime refuses to drive any run while it is set (`limit_unsupported`); leave it out |
+| `limits.agentStepTimeoutMs` | Integer, 60,000 to 31,536,000,000 | Optional, 3,600,000 | Wall clock for one live agent or moa step when the step omits `timeoutMs`. The supervisor passes it to the one-shot producer. A step `timeoutMs` narrower than this wins; a wider step value is refused (`step_unsupported`, field `timeoutMs`) |
 
 The Runtime binds one project `id` to one control root per state root, so a
 second checkout with the same ID is refused with `project_home_conflict`.
@@ -555,7 +556,7 @@ Duration budgets use the wall clock. `maxRunDurationMs` counts from the time the
 | `signal` | Identifier | Required for `wait` | Compiled and diffed; the Runtime does not match signals to wait steps yet |
 | `model` | Model selector | Optional | Intersected with each allowed agent's own model ceiling; an empty intersection is `model_selector_incompatible`. Live route resolution ignores it. The Runtime refuses it on gate steps. |
 | `maxAttempts` | Integer, 1 to 20 | Optional, `1` | Entering the step again after this many attempts fails the run (`budget_step_attempts`) |
-| `timeoutMs` | Integer, 0 to 31,536,000,000 | Optional | Not `0`. Gate steps: refused for `artifacts-exist` gates or below the gate's `timeoutMs`. Other kinds: unused; the producer times out at 120 s |
+| `timeoutMs` | Integer, 0 to 31,536,000,000 | Optional | Not `0`. Gate steps: refused for `artifacts-exist` gates or below the gate's `timeoutMs`. Agent and moa steps: the one-shot spawn uses this value when it is at most `limits.agentStepTimeoutMs`; a wider value is refused (`step_unsupported`, field `timeoutMs`). When the step omits it, the project limit applies (default 3,600,000). The process default of 120 seconds is only the last resort when neither is set |
 | `repositories` | Map of repository ID to `none`, `read`, or `write` | Optional | IDs must be declared (`repository_unknown`); may not exceed the agent's ceiling (`repository_scope_expansion`) |
 | `tools` | `{preset, allow, deny}` | Optional | Must keep the agent's preset and denials and allow only tools the agent allows (`tool_scope_expansion`). The Runtime refuses steps that declare `tools`. |
 | `secrets` | `[{ref, as, required}]` | Optional | Only refs the agent grants (`secret_scope_expansion`). The Runtime refuses steps that declare `secrets`. |

package/docs/reference/workflow-catalog.md

@@ -1090,6 +1090,16 @@ This cross-reference points each software and security workflow at the KXM pages
 
 `kxm run land --dry-run --json` may be refused by live prerequisites until gate-only workflows are supported. The command `kxm land` runs the same stages without a run receipt.
 
+## Repository developer workflows
+
+These three files live in this repository's `.kxm/workflows`. `kxm init` does not write them.
+
+| Workflow | Replaces |
+|---|---|
+| `implement-only` | `just impl`. The recipe is retired once this lands. |
+| `review-arch-only` | `just review-arch`. The recipe is retired once this lands. |
+| `review-cli-only` | `just review-cli`. The recipe is retired once this lands. |
+
 ## Related
 
 - [Workflow definitions](workflow-definitions.md): write a webhook or Runtime workflow for these stages

package/docs/reference/workflow-definitions.md

@@ -271,7 +271,7 @@ A Runtime workflow is a YAML file whose name is its ID. The [configuration file
 | Transitions | `on` is required on every step. `$terminal` needs `terminalStatus` (`completed`, `failed` or `cancelled`). Each back-edge needs its own `maxTransitions`, plus `limits.maxTransitions` | [Transitions and outcomes](config-reference.md#transitions-and-outcomes) |
 | Gate outcome keys | An `expect: pass` gate produces `passed` or `implementation-failure`; an `expect: fail` gate produces `passed` or `repro-missing`. Declare both produced outcomes | [Transitions and outcomes](config-reference.md#transitions-and-outcomes) |
 | `gate_outcome_impossible` | Refused at load when a gate step declares an outcome it never produces, such as `failed`, and omits one it produces. `gate_outcome_renamed` catches underscore spellings | [Transitions and outcomes](config-reference.md#transitions-and-outcomes) |
-| Agent steps | The model returns a JSON `outcome` from the step's declared keys; anything else becomes `failed`, so declare `failed` | [Transitions and outcomes](config-reference.md#transitions-and-outcomes) |
+| Agent steps | The model returns a JSON `outcome` from the step's declared keys; anything else becomes `failed`, so declare `failed`. `timeoutMs` bounds the one-shot spawn for `agent` and `moa` steps, and must not be wider than the project `limits.agentStepTimeoutMs` | [Step fields](config-reference.md#step-fields) |
 | Not executed yet | Some valid fields make the Runtime hand the run off (`step_unsupported`, `gate_unsupported`, `limit_unsupported`) instead of executing | [Steps the Runtime does not execute yet](config-reference.md#steps-the-runtime-does-not-execute-yet) |
 
 `kxm workflow add bug-fix --template implement-and-verify` writes a valid starting file; `dual-critic-review` and `spec-and-plan` are also available. IDs are flat filename-derived slugs, not catalog paths such as `software-engineering/bug-fix`. Installation validates YAML/schema/transitions before writing, including under `--dry-run`. `kxm run <workflow>` creates a run and reports live prerequisites and separate `runs drive/status/receipt` commands. Current live one-shot profiles are read-only, so a writer template can validate but cannot execute live; `task run` refuses incompatible work before creating a run or changing the task. Simulation remains explicitly available and is not proof of implementation. See [`kxm run`](cli-reference.md#kxm-run) and [`kxm runs`](cli-reference.md#kxm-runs).

package/docs/robots.txt

@@ -0,0 +1,44 @@
+User-agent: *
+Disallow: /
+
+User-agent: GPTBot
+Disallow: /
+
+User-agent: ChatGPT-User
+Disallow: /
+
+User-agent: Google-Extended
+Disallow: /
+
+User-agent: Googlebot
+Disallow: /
+
+User-agent: Bingbot
+Disallow: /
+
+User-agent: ClaudeBot
+Disallow: /
+
+User-agent: anthropic-ai
+Disallow: /
+
+User-agent: CCBot
+Disallow: /
+
+User-agent: Bytespider
+Disallow: /
+
+User-agent: Amazonbot
+Disallow: /
+
+User-agent: PerplexityBot
+Disallow: /
+
+User-agent: Applebot-Extended
+Disallow: /
+
+User-agent: meta-externalagent
+Disallow: /
+
+User-agent: cohere-ai
+Disallow: /

package/docs/stylesheets/extra.css

@@ -0,0 +1,100 @@
+[data-md-color-scheme="slate"] {
+  --md-primary-fg-color: #3068da;
+  --md-primary-fg-color--light: color-mix(in srgb, #3068da 65%, #f2eee7);
+  --md-primary-fg-color--dark: color-mix(in srgb, #3068da 70%, #0e0d0b);
+  --md-primary-bg-color: #f2eee7;
+  --md-primary-bg-color--light: color-mix(in srgb, #f2eee7 70%, transparent);
+  --md-accent-fg-color: #3068da;
+  --md-accent-fg-color--transparent: color-mix(in srgb, #3068da 12%, transparent);
+  --md-accent-bg-color: #0e0d0b;
+  --md-accent-bg-color--light: color-mix(in srgb, #0e0d0b 70%, transparent);
+  --md-default-bg-color: #0e0d0b;
+  --md-default-fg-color: #f2eee7;
+  --md-default-fg-color--light: color-mix(in srgb, #f2eee7 62%, #0e0d0b);
+  --md-default-fg-color--lighter: color-mix(in srgb, #f2eee7 40%, #0e0d0b);
+  --md-default-fg-color--lightest: color-mix(in srgb, #f2eee7 14%, #0e0d0b);
+  --md-code-bg-color: color-mix(in srgb, #f2eee7 8%, #0e0d0b);
+  --md-code-fg-color: #f2eee7;
+  --md-footer-bg-color: #0e0d0b;
+  --md-footer-fg-color: #f2eee7;
+  --md-footer-fg-color--light: color-mix(in srgb, #f2eee7 62%, #0e0d0b);
+  --md-typeset-a-color: #3068da;
+  --md-mermaid-edge-color: #3068da;
+  --md-mermaid-node-bg-color: color-mix(in srgb, #3068da 12%, #0e0d0b);
+  --md-mermaid-node-fg-color: #3068da;
+  --md-mermaid-label-bg-color: #0e0d0b;
+  --md-mermaid-label-fg-color: #f2eee7;
+  --md-mermaid-sequence-actor-border-color: #3068da;
+  --md-mermaid-sequence-message-line-color: #3068da;
+  --md-mermaid-sequence-number-bg-color: #3068da;
+}
+
+.md-header,
+.md-tabs {
+  background-color: #0e0d0b;
+  color: #f2eee7;
+}
+
+.md-header__button.md-logo {
+  display: inline-block;
+}
+
+.md-header__button.md-logo img {
+  height: 1.6rem;
+  width: auto;
+}
+
+.md-typeset .grid.cards > ul > li,
+.md-typeset .admonition,
+.md-typeset details {
+  background-color: color-mix(in srgb, #f2eee7 8%, #0e0d0b);
+  border-color: color-mix(in srgb, #f2eee7 16%, #0e0d0b);
+}
+
+.md-typeset .kxm-diagram {
+  position: relative;
+  background: color-mix(in srgb, #f2eee7 8%, #0e0d0b);
+  border: 1px solid color-mix(in srgb, #f2eee7 16%, #0e0d0b);
+  border-radius: 8px;
+  padding: 1rem;
+}
+
+.md-typeset .mermaid svg {
+  max-width: 100%;
+  height: auto;
+}
+
+.md-typeset .kxm-fs {
+  position: absolute;
+  top: 0.5rem;
+  right: 0.5rem;
+  z-index: 2;
+  background: #0e0d0b;
+  color: #3068da;
+  border: 1px solid #3068da;
+  border-radius: 4px;
+  padding: 0.25rem 0.6rem;
+  cursor: pointer;
+}
+
+.md-typeset .kxm-diagram:fullscreen,
+.md-typeset .kxm-diagram.kxm-fs-open,
+.md-typeset .mermaid:fullscreen,
+.md-typeset .mermaid.kxm-fs-open {
+  background: #0e0d0b;
+  width: 100vw;
+  height: 100vh;
+  margin: 0;
+  box-sizing: border-box;
+  overflow: auto;
+}
+
+.md-typeset .kxm-diagram:fullscreen svg,
+.md-typeset .kxm-diagram.kxm-fs-open svg,
+.md-typeset .mermaid:fullscreen svg,
+.md-typeset .mermaid.kxm-fs-open svg {
+  width: 100%;
+  height: 100%;
+  max-width: 100vw;
+  max-height: 100vh;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontextmind/kxm",
-  "version": "0.7.122",
+  "version": "0.7.124",
   "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.122",
+  "version": "0.7.124",
   "description": "Headless multi-agent orchestration, durable workflows, and a live operator dashboard for Pi and Claude Code",
   "author": {
     "name": "KontextMind",