@kontextmind/kxm 0.7.121 → 0.7.123

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), [`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
 
@@ -159,6 +159,7 @@ Exit 2 covers an unknown command or option, a missing argument or required optio
 | Create and drive a run | [`kxm run`](#kxm-run), [`kxm runs drive`](#kxm-runs-drive), [`kxm runtime status`](#kxm-runtime-status) |
 | Work in an isolated checkout | [`kxm lane`](#kxm-lane), [`kxm run --lane`](#kxm-run) |
 | Land the current branch | [`kxm land`](#kxm-land) |
+| Delegate and accept a developer assignment | [`kxm assign`](#kxm-assign) |
 | Inspect runs | [`kxm runs list`](#kxm-runs-list), [`kxm runs status`](#kxm-runs-status), [`kxm runs receipt`](#kxm-runs-receipt), [`kxm tenant status`](#kxm-tenant-status), [`kxm workflow list`](#kxm-workflow-list) |
 | Message peers | [`kxm peer list`](#kxm-peer-list), [`kxm peer send`](#kxm-peer-send), [`kxm peer await`](#kxm-peer-await), [`kxm peer fanout`](#kxm-peer-fanout) |
 | Operate gates and evidence | [`kxm gate validate`](#kxm-gate-validate), [`kxm gate artifacts-exist`](#kxm-gate-artifacts-exist), [`kxm gate signal`](#kxm-gate-signal), [`kxm workflow checkpoint`](#kxm-workflow-checkpoint) |
@@ -1470,6 +1471,150 @@ Outside a KXM project the command refuses `project_required` (exit 1). Unknown a
 
 Refusals (exit 1): `project_required`, `land_dirty_tree`, `land_verify_failed`, `land_docs_failed`, `land_push_rejected`, `land_pr_body_missing`, `land_conflict_manual`, `land_blocked`, `land_merge_failed`, `land_release_failed`, `land_publish_timeout`, `land_milestone_failed`.
 
+## `kxm assign`
+
+`kxm assign` is the entry to this repository's developer assignment runner. Each verb spawns `node scripts/assignment-run.mjs <verb> ...` from the project root with that argument list, `stdio: "inherit"`, and the process environment unchanged. The command returns the child's exit code. It does not load a `.env` file, resolve paths, or repeat any runner check. Every validation rule, refusal code, and file the runner writes stays in [`scripts/assignment-run.mjs`](../../scripts/assignment-run.mjs). The loop, the records, and those codes are documented in [Assignment runner](../contributing/assignment-runner.md).
+
+The command does not start the hub or the Runtime supervisor. It writes nothing itself. `--dry-run` prints the argv that would run and exits 0 without spawning. `--json` formats this command's own refusals and that dry-run plan. The runner's usage text documents no `--json` flag, and `accept` already prints JSON, so `--json` is not forwarded.
+
+Outside a KXM project the command exits 1 with `project_required`. A project that has no `scripts/assignment-run.mjs` exits 1 with `assign_runner_missing`. A missing required flag is a usage error and exits 2. If `node` cannot be started, the command exits 1 with `assign_spawn_failed`.
+
+```text
+kxm assign run --manifest <path>
+kxm assign witness --record-dir <path>
+kxm assign plan-current --task-dir <path> --plan <path> --sha256 <hex> --base-commit <sha> --expected-generation <n>
+kxm assign attribute --task-dir <path> --record-dir <path> --class <class> --explanation-file <path>
+kxm assign observe-cost --task-dir <path> --input <path>
+kxm assign accept --task-dir <path> --commit <sha> --record-dir <path> --critic <path> --critic <path> [--observed-pr <id>] [--observed-ci <id>]
+kxm assign change-report --task-dir <path>
+```
+
+```bash
+kxm assign run --manifest /abs/tasks/fix-improve-sources/asg-writer-1.json
+```
+
+### `kxm assign run`
+
+Dispatches one closed manifest. The runner validates the route, the base, and the plan pointer, then writes the assignment record.
+
+| Option | Argument | Description |
+|---|---|---|
+| `--manifest` | `<path>` | Absolute path to the `kxm.assignment.v1` manifest. Passed through as given |
+
+### `kxm assign witness`
+
+Runs the fixed witness named in the manifest against the staged tree.
+
+| Option | Argument | Description |
+|---|---|---|
+| `--record-dir` | `<path>` | Absolute path to the assignment record directory |
+
+### `kxm assign plan-current`
+
+Stamps or advances `plan-current.json` in the task directory.
+
+| Option | Argument | Description |
+|---|---|---|
+| `--task-dir` | `<path>` | Absolute path to the task directory |
+| `--plan` | `<path>` | Absolute path to the plan file |
+| `--sha256` | `<hex>` | SHA-256 the runner expects for that file |
+| `--base-commit` | `<sha>` | Commit the pointer records |
+| `--expected-generation` | `<n>` | Generation the pointer must currently have |
+
+### `kxm assign attribute`
+
+Attaches one private note under the record's `attribution/` directory. The note is not proof.
+
+| Option | Argument | Description |
+|---|---|---|
+| `--task-dir` | `<path>` | Absolute path to the task directory |
+| `--record-dir` | `<path>` | Absolute path to the assignment record directory |
+| `--class` | `<class>` | `orchestration`, `model`, `environment`, or `unclassified` |
+| `--explanation-file` | `<path>` | Absolute path to the note file |
+
+### `kxm assign observe-cost`
+
+Imports one cost observation. The record is cost-only and cannot authorize acceptance.
+
+| Option | Argument | Description |
+|---|---|---|
+| `--task-dir` | `<path>` | Absolute path to the task directory |
+| `--input` | `<path>` | Absolute path to the observation file |
+
+### `kxm assign accept`
+
+Binds the witnessed commit and two critic records. Optional observation ids are forwarded when present. `accept` prints JSON and takes no `--json` flag.
+
+| Option | Argument | Description |
+|---|---|---|
+| `--task-dir` | `<path>` | Absolute path to the task directory |
+| `--commit` | `<sha>` | Commit whose tree must equal the witnessed tree |
+| `--record-dir` | `<path>` | Absolute path to the writer record directory |
+| `--critic` | `<path>` | Absolute path to a critic record directory. Pass it twice |
+| `--observed-pr` | `<id>` | Observed pull request id. Omitted unless set |
+| `--observed-ci` | `<id>` | Observed CI run id. Omitted unless set |
+
+### `kxm assign change-report`
+
+Prints the task's attempts, rework, and spend. The runner keeps provider-reported, list, unmetered, and unknown cost apart.
+
+| Option | Argument | Description |
+|---|---|---|
+| `--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/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.121",
+  "version": "0.7.123",
   "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.121",
+  "version": "0.7.123",
   "description": "Headless multi-agent orchestration, durable workflows, and a live operator dashboard for Pi and Claude Code",
   "author": {
     "name": "KontextMind",