@kontextmind/kxm 0.7.121 → 0.7.123

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

package/CHANGELOG.md

@@ -14,6 +14,13 @@ All notable user-facing changes are documented here. The project follows [Semant
   A required review is reported. The `land` workflow in `.kxm/workflows/land.yaml`
   runs the same gates and may be refused until gate-only workflows are supported.
   See the [CLI reference](docs/reference/cli-reference.md#kxm-land).
+- **`kxm assign` is the entry to the developer assignment runner.**
+  `run`, `witness`, `plan-current`, `attribute`, `observe-cost`, `accept` and
+  `change-report` spawn `scripts/assignment-run.mjs` with the same flags as the
+  just recipes. The runner still performs every check and writes every file.
+  The just recipes stay until one real unit has been accepted through
+  `kxm assign`. See the
+  [CLI reference](docs/reference/cli-reference.md#kxm-assign).
 
 - **`kxm lane` keeps one git worktree per unit beside the control checkout.**
   `create`, `list`, `status`, `drop` and `run` store a 0600 record in
@@ -28,6 +35,17 @@ All notable user-facing changes are documented here. The project follows [Semant
   limit lands. See the
   [CLI reference](docs/reference/cli-reference.md#kxm-lane).
 
+- **The tailnet docs site is built and served with `kxm docs build` and `kxm docs serve`.**
+  `kxm docs build` runs `node plans/kxm-roadmap/update-dashboard.mjs` from the
+  project root and returns its exit code. `kxm docs serve` runs
+  `python3 ops/docs-site/serve.py`, streams its output, and passes `--port`
+  through when it is set. Both refuse `project_required` outside a KXM project,
+  and `docs_generator_missing` or `docs_server_missing` when the file is absent.
+  `--dry-run` prints the command and starts nothing. The header wordmark is the
+  portal mark, and the slate palette uses `#0e0d0b`, `#3068da`, and `#f2eee7`.
+  `kxm docs build` validates the roadmap state file and refuses when it does not match the schema.
+  See the [CLI reference](docs/reference/cli-reference.md#kxm-docs).
+
 - **Claude-only workflow recommendations now fail honestly when execution is unavailable.**
   `suggest` honors explicit harness constraints, uses flat installable IDs and verified
   capability-appropriate routes, refuses unchecked existing definitions, and never substitutes a

package/docs/architecture/access-schema.yaml

@@ -0,0 +1,60 @@
+schema: kxm.access.v1
+objects:
+  - kind: principal
+    id: writer
+    source: .kxm/roles/writer.yaml
+    enforced: false
+    note: Roster only. This file has no tools block. role.ts counts tools.allow and does not enforce it.
+  - kind: principal
+    id: planner
+    source: .kxm/roles/planner.yaml
+    enforced: false
+    note: Roster only. This file has no tools block.
+  - kind: principal
+    id: reviewer-arch
+    source: .kxm/roles/reviewer-arch.yaml
+    enforced: false
+    note: Roster only. This file has no tools block.
+  - kind: principal
+    id: reviewer-cli
+    source: .kxm/roles/reviewer-cli.yaml
+    enforced: false
+    note: Roster only. This file has no tools block.
+  - kind: group
+    id: writer
+    members: [writer]
+    enforced: false
+    note: Naming group only. No group object is enforced in code.
+  - kind: group
+    id: critics
+    members: [reviewer-arch, reviewer-cli]
+    enforced: false
+    note: Naming group only. No group object is enforced in code.
+  - kind: claim
+    id: edit
+    enforced: true
+    note: oneShotWriterArgs in plugins/kxm/src/harness.ts for pi, omp, and grok.
+  - kind: claim
+    id: read-only
+    enforced: true
+    note: oneShotReadOnlyArgs in plugins/kxm/src/harness.ts, and isToolAllowed in plugins/kxm/src/commands.ts when preset is read-only.
+  - kind: grant
+    id: coordinator
+    source: BUILTIN_TOOL_PRESETS
+    enforced: false
+    note: Accepted preset name in plugins/kxm/src/project-config.ts. isToolAllowed does not special-case it.
+  - kind: grant
+    id: read-only
+    source: BUILTIN_TOOL_PRESETS
+    enforced: true
+    note: Same read-only claim as above.
+  - kind: grant
+    id: workspace-writer
+    source: BUILTIN_TOOL_PRESETS
+    enforced: false
+    note: Accepted preset name. init-guide-setup.ts assigns it to a writer agent. isToolAllowed does not map it to a tool list.
+  - kind: grant
+    id: tests-writer
+    source: BUILTIN_TOOL_PRESETS
+    enforced: false
+    note: Accepted preset name. isToolAllowed does not special-case it.

package/docs/architecture/access.md

@@ -0,0 +1,33 @@
+# Access
+
+Read from `.kxm/roles/writer.yaml`, `.kxm/roles/planner.yaml`,
+`.kxm/roles/reviewer-arch.yaml`, `.kxm/roles/reviewer-cli.yaml`,
+`plugins/kxm/src/role.ts`, `plugins/kxm/src/commands.ts`,
+`plugins/kxm/src/harness.ts`, and `plugins/kxm/src/project-config.ts`.
+
+The four principals in this checkout are the role files under `.kxm/roles/`.
+None of those files sets `tools`. `listRoles` in `plugins/kxm/src/role.ts`
+sets `toolsCount` from `tools.allow.length` and does not apply the list.
+`DEFAULT_ROLES` in the same file carries preset names such as `author` and
+`read_only`. Those defaults are not the files in `.kxm/roles/`, and those
+preset strings are not the `BUILTIN_TOOL_PRESETS` list.
+
+`isToolAllowed` in `plugins/kxm/src/commands.ts` enforces `preset: read-only`
+by denying mutating `kxm_*` tools. `oneShotReadOnlyArgs` and
+`oneShotWriterArgs` in `plugins/kxm/src/harness.ts` are the harness argument
+sets. Edit arguments exist for `pi`, `omp`, and `grok`. Other harnesses stay
+on the read-only set. A live write step without an edit profile hands off
+instead of spawning unconstrained (`unsupportedLiveWrite` in
+`plugins/kxm/src/engine.ts`).
+
+`BUILTIN_TOOL_PRESETS` in `plugins/kxm/src/project-config.ts` is
+`coordinator`, `read-only`, `workspace-writer`, and `tests-writer`.
+
+```yaml
+--8<-- "architecture/access-schema.yaml"
+```
+
+## Related
+
+- [Authentication](authentication.md)
+- [Agent path](agent-path.md)

package/docs/architecture/agent-path.md

@@ -0,0 +1,36 @@
+# Agent path
+
+Read from `plugins/kxm/src/cli/project.ts`, `plugins/kxm/src/engine.ts`,
+`plugins/kxm/src/worktree-witness.ts`, and `plugins/kxm/src/oneshot-producer.ts`.
+
+`kxm run` resolves the project from the current directory and posts
+`POST /v1/runs` to the Runtime supervisor (`cmdKxmRun`). The response names
+`kxm runs drive <runId> --wait` as the next step. Drive posts
+`POST /v1/runs/<runId>/drive` and later reads the drive receipt. The
+supervisor's producer is the one-shot producer registered from
+`plugins/kxm/src/oneshot-producer.ts`. Around a live spawn, the engine takes
+a checkout fingerprint, invokes the producer, then fingerprints again
+(`captureWorktreeWitness` and `applyAuthoringWitness`). A write step that
+does not change the tree cannot stay `passed`. A read-only step that changes
+the tree cannot stay `passed`.
+
+```mermaid
+sequenceDiagram
+  participant CLI as kxm CLI
+  participant Sup as Runtime supervisor
+  participant Eng as engine
+  participant Har as harness process
+  CLI->>Sup: "POST /v1/runs"
+  CLI->>Sup: "kxm runs drive"
+  Sup->>Eng: "producer dispatch"
+  Eng->>Eng: "fingerprint before spawn"
+  Eng->>Har: "one-shot harness"
+  Har-->>Eng: "producer result"
+  Eng->>Eng: "fingerprint after spawn"
+  Eng-->>CLI: "drive receipt"
+```
+
+## Related
+
+- [Platform](platform.md)
+- [First workflow](../start/first-workflow.md)

package/docs/architecture/authentication.md

@@ -0,0 +1,29 @@
+# Authentication
+
+Read from `plugins/kxm/src/harness.ts` and `plugins/kxm/src/cli.ts`.
+
+`kxm harness list` runs `probeHarnesses` (`cmdHarnessList` in
+`plugins/kxm/src/cli/project.ts`). For each detected harness that has
+`authArgs`, `probeEntry` runs that command and `interpretAuth` reads the
+output. KXM does not store provider credentials. The probe only classifies
+the harness command's own stdout.
+
+| Harness | Probe command | Logged-in signal in this file |
+| --- | --- | --- |
+| Pi | no `authArgs` on the catalog entry | `authenticated` stays null with `auth_context_required`. A separate assignment probe can run `pi auth check`. |
+| Claude | `auth status` | JSON `loggedIn: true`, method `claude.ai` or `api-key` |
+| Codex | `login status` | `Logged in using ChatGPT` or `Logged in using an API key` |
+| Grok | `models` | exact line `You are logged in with grok.com.` |
+| Kimi | `provider list` | a line containing `managed:kimi`, `type=kimi`, or `Default model:` |
+| agy | `models` | a model row matched by `AGY_MODEL_ROW`, method `antigravity-oauth` |
+| omp | `models --json` | success, and a non-empty `models` array when JSON parses |
+| deepseek | no `authArgs` | `authenticated` stays null with `auth_unknown` |
+
+`kxm auth` in `plugins/kxm/src/cli.ts` is `kxm auth token`. It inspects,
+issues, or clears the local session token file. That token is a KXM session
+token, not a provider key. Provider logins stay in each harness.
+
+## Related
+
+- [Access](access.md)
+- [Harness routing](../reference/harness-routing.md)

package/docs/architecture/hosted-direction.md

@@ -0,0 +1,59 @@
+# Hosted direction
+
+Target. This page is a direction, not a live deployment.
+
+Read from `plans/plan-per-tenant-hosting.md`. `plans/plan-greenfield-infra.md`
+is not in this checkout.
+
+```mermaid
+flowchart LR
+  titleNode["Target: hosted direction, not a live deployment"]
+  tenant["one box per tenant"]
+  edge["edge identity in front"]
+  portal["portal backend"]
+  hub["loopback hub"]
+  store["SQLite hub store"]
+  titleNode --> tenant
+  edge --> portal
+  portal --> hub
+  hub --> store
+```
+
+## Per-tenant hosting plan
+
+`plans/plan-per-tenant-hosting.md` frontmatter says `status: "draft"` and
+`blocked_by: []`.
+
+The file's own summary says it is the rationale and boundary for hosting KXM
+beside the portal: one tenant per box, Authentik at the edge, existing
+static-token auth unchanged, hub state stays SQLite, and the portal backend
+is the hosted client of the loopback hub. It says delivery order lives only
+in the implementation tracker and that this file keeps no schedule.
+
+The four decisions in that file, in its words:
+
+1. Tenancy is the machine.
+2. Auth stays exactly as it is. Hosting is additive.
+3. Authentik owns the browser. The portal backend is the hub's client.
+4. No PostgreSQL for the hub. If one is ever needed, one database per hub.
+
+The file says none of the delivery is scheduled there. The ordered queue is
+the tracker's Still open section. The tracker records S0 through S4 as
+delivered and S5 as still open on interactive login. That disagreement is a
+roadmap question. The tracker wins.
+
+## Greenfield infra plan
+
+`plans/plan-greenfield-infra.md` is not observed from this checkout. Its
+`status` and `blocked_by` are not observed from this checkout.
+
+The tracker names that file. The sentences that can be repeated without a
+hostname, an account name, or a secret are: a first move is recorded as
+installed, Postgres and Temporal are described as loopback only, KXM does not
+write those stores, Redis Streams, NATS, raw WebSockets, and the A2A Python
+SDK stay backlog, there is no S3, and the SQLite write path is unchanged.
+
+## Related
+
+- [Roadmap](../roadmap/dashboard.md)
+- [SQLite ADR](../adr/ADR-0003-sqlite-only-store.md)

package/docs/architecture/index.md

@@ -0,0 +1,19 @@
+# Architecture
+
+Read from `plans/kxm-roadmap/state.json` and the pages linked below.
+
+Verified date: null. A review pass has not set `architecture.verified`.
+
+| Page | What it covers |
+| --- | --- |
+| [Platform](platform.md) | Local-first processes and how they connect |
+| [Surfaces](inventory.md) | Executables, listeners, and the stores they own |
+| [Access](access.md) | Roles, claims, and tool presets observed in code |
+| [Authentication](authentication.md) | How harness login is probed, and where credentials are not stored |
+| [Agent path](agent-path.md) | `kxm run` through the drive receipt |
+| [Hosted direction](hosted-direction.md) | Target only. Not a live deployment |
+
+## Related
+
+- [Roadmap](../roadmap/dashboard.md)
+- [Trust model](../concepts/trust-model.md)

package/docs/architecture/inventory.md

@@ -0,0 +1,38 @@
+# Surfaces
+
+Read from `plugins/kxm/src/cli.ts`, `scripts/kxm-hub.mjs`, `plugins/kxm/src/hub.ts`,
+`plugins/kxm/src/runtime-supervisor.ts`, `plugins/kxm/src/runtime-paths.ts`,
+`plugins/kxm/src/mcp-server.ts`, `plugins/kxm/src/oneshot-producer.ts`,
+`plugins/kxm/src/studio-layout.ts`, `plugins/kxm/src/cli/types.ts`
+(`workspaceDirs`), `plugins/kxm/src/local-snapshot.ts`, and
+`scripts/kxm-worker.mjs`.
+
+| Surface | Started by | Listener or path | Store it owns | Defining file |
+| --- | --- | --- | --- | --- |
+| `kxm` CLI | `node scripts/kxm.mjs` or the installed bin | no listener | none | `plugins/kxm/src/cli.ts` |
+| Hub | `kxm hub start` via `scripts/kxm-hub.mjs` | `127.0.0.1:7331` | `.kxm/state/kxm.db` under the workspace state dir | `plugins/kxm/src/hub.ts` |
+| Hub credentials | written when the hub starts | `hub-env.json` under the user state root | that JSON file, not SQLite | `plugins/kxm/src/hub-env.ts` |
+| Runtime supervisor | `kxm runtime` / `scripts/kxm-runtime-supervisor.mjs` | `127.0.0.1` and the requested port, or ephemeral | registry and event stores below | `plugins/kxm/src/runtime-supervisor.ts` |
+| Runtime registry | opened by the supervisor | `runtime/registry.db` under the user state root | `registry.db` | `plugins/kxm/src/runtime-paths.ts` |
+| Runtime event store | opened by the supervisor | `runtime/projects/<key>/run-events.db` | `run-events.db` | `plugins/kxm/src/runtime-paths.ts` |
+| MCP server | Claude plugin or stdio launch | stdio | none | `plugins/kxm/src/mcp-server.ts` |
+| One-shot harness | supervisor producer | child process, no listener | none | `plugins/kxm/src/oneshot-producer.ts` |
+| Pi worker | `kxm agent worker` | no HTTP listener in `scripts/kxm-worker.mjs` | none of its own | `scripts/kxm-worker.mjs` |
+| Studio | `kxm studio serve` | `127.0.0.1:4242` | none | `plugins/kxm/src/studio-layout.ts` |
+| Workspace config | `workspaceDirs` | `.kxm/config`, or `KXM_CONFIG_DIR` | files in that directory | `plugins/kxm/src/cli/types.ts` |
+| Workspace logs | `workspaceDirs` | `.kxm/logs`, or `KXM_LOGS_DIR` | log files | `plugins/kxm/src/cli/types.ts` |
+| Workspace assets | `workspaceDirs` | `.kxm/assets`, or `KXM_ASSETS_DIR` | asset files | `plugins/kxm/src/cli/types.ts` |
+| Workspace state | `workspaceDirs` | `.kxm/state`, or `KXM_STATE_DIR` | `kxm.db` when the hub uses this directory | `plugins/kxm/src/cli/types.ts` |
+
+On macOS the user state root is `Library/Application Support/KXM` under the
+home directory (`kxmUserStateRoot` in `plugins/kxm/src/bindings.ts`). Windows
+uses `AppData/Local/KXM`. Other platforms use `$XDG_STATE_HOME/kxm` or
+`.local/state/kxm`. `KXM_STATE_HOME` overrides that root when it is absolute.
+The tracker mentions `docs/operations.md` for the six backup roots. That file
+is not in this checkout. The six roots are described in
+[Backup and restore](../operations/backup-and-restore.md).
+
+## Related
+
+- [Platform](platform.md)
+- [Backup and restore](../operations/backup-and-restore.md)

package/docs/architecture/platform.md

@@ -0,0 +1,48 @@
+# Platform
+
+Read from `plugins/kxm/src/cli.ts`, `plugins/kxm/src/runtime-supervisor.ts`,
+`scripts/kxm-hub.mjs`, `plugins/kxm/src/hub.ts`, `plugins/kxm/src/mcp-server.ts`,
+and `plugins/kxm/src/oneshot-producer.ts`.
+
+KXM on this checkout is local-first. The `kxm` CLI is the operator entry
+(`plugins/kxm/src/cli.ts`, launched through `scripts/kxm.mjs`). The hub is an
+HTTP server started by `scripts/kxm-hub.mjs`, which loads
+`plugins/kxm/dist/server.js`. `createHub` defaults the listener to
+`127.0.0.1` and port `7331` (`plugins/kxm/src/hub.ts`, `DEFAULT_PORT` in
+`plugins/kxm/src/protocol.ts`). The Runtime supervisor
+(`plugins/kxm/src/runtime-supervisor.ts`) listens on `127.0.0.1`. Its port
+defaults to `0`, so the kernel picks an ephemeral port unless a port is
+requested. The MCP server (`plugins/kxm/src/mcp-server.ts`) uses
+`StdioServerTransport`. It has no TCP listener. It calls the hub at
+`KXM_SERVER_URL` or `http://127.0.0.1:7331`. One-shot harness calls are
+spawned by the producer registered in `plugins/kxm/src/oneshot-producer.ts`.
+That child process is not a listener.
+
+```mermaid
+flowchart LR
+  cli["kxm CLI"]
+  hub["hub"]
+  sup["Runtime supervisor"]
+  mcp["MCP server"]
+  shot["one-shot harness"]
+  cli -->|"kxm hub start"| hub
+  mcp -->|"HTTP to hub"| hub
+  cli -->|"kxm run"| sup
+  sup -->|"spawn producer"| shot
+```
+
+## Listeners
+
+| Route | Listener |
+| --- | --- |
+| Hub HTTP | `127.0.0.1:7331` unless host or port is overridden |
+| Supervisor HTTP | `127.0.0.1` and an ephemeral port when the requested port is `0` |
+| MCP | stdio, no TCP port |
+| CLI and one-shot harness | no listener |
+| Studio, when served | `127.0.0.1:4242` from `createStudioServer` in `plugins/kxm/src/studio-layout.ts` |
+| Antigravity OAuth callback | loopback port `51121` only during login (`plugins/kxm/src/providers/antigravity/auth/oauth.ts`) |
+
+## Related
+
+- [Surfaces](inventory.md)
+- [Agent path](agent-path.md)

package/docs/contributing/assignment-runner.md

@@ -19,9 +19,9 @@ a KXM product feature.
   `origin/main`. The runner loads `.kxm/roster.yaml` only from there.
 - A separate worktree for the writer. `kxm lane create <unit>` creates one from
   `origin/main`.
-- [`just`](https://github.com/casey/just), plus the harness CLIs the roster
-  admits, installed and logged in. `node scripts/kxm.mjs harness list` shows
-  which are.
+- The harness CLIs the roster admits, installed and logged in.
+  `node scripts/kxm.mjs harness list` shows which are. The loop below is
+  `kxm assign`. `just` still runs the transport recipes.
 - A task directory whose final path segment equals the task ID. Every path you
   pass to the runner must be absolute.
 
@@ -80,10 +80,12 @@ Use this slim loop for daily work and for docs. The 13-step `fix` workflow in
 `examples/project/` is a product fixture, not the developer loop.
 
 > [!NOTE]
-> These recipes never load a `.env` file from the working directory. An
+> `kxm assign` never loads a `.env` file from the working directory. An
 > unreviewed file could otherwise set `NODE_OPTIONS` and run code before the
-> runner validates anything. To use one, pass it explicitly:
-> `just --dotenv-path /abs/.env assign /abs/manifest.json`.
+> runner validates anything. The process environment is passed through as it
+> is. Export any variable you need before the command.
+
+The seven `just` assignment recipes remain available and will be removed after one real unit has been accepted through `kxm assign`; until then both forms are equivalent because both call `scripts/assignment-run.mjs` unchanged.
 
 ### 1. Pin the current plan
 
@@ -91,7 +93,7 @@ Every writer assignment binds to the current plan. Stamp the pointer, or advance
 it with a generation check:
 
 ```bash
-just plan-current /abs/task-dir /abs/plan.md <sha256> <base-commit> <expected-generation>
+kxm assign plan-current --task-dir /abs/task-dir --plan /abs/plan.md --sha256 <sha256> --base-commit <base-commit> --expected-generation <expected-generation>
 ```
 
 The runner writes `plan-current.json` (`kxm.plan-pointer.v1`) in the task
@@ -137,7 +139,7 @@ Optional keys are `rework_of`, `timeout_ms` and `max_turns`. Each `inputs`
 entry is `{ "path", "sha256" }`, and the runner checks the hash. Dispatch it:
 
 ```bash
-just assign /abs/tasks/fix-improve-sources/asg-writer-1.json
+kxm assign run --manifest /abs/tasks/fix-improve-sources/asg-writer-1.json
 ```
 
 The runner validates the manifest, the route and the base, writes
@@ -151,7 +153,7 @@ generated files, then run the witness:
 
 ```bash
 git -C /abs/kxm-fix-improve-sources add -A
-just witness /abs/tasks/fix-improve-sources/asg-writer-1
+kxm assign witness --record-dir /abs/tasks/fix-improve-sources/asg-writer-1
 ```
 
 The witness refuses with `dirty_baseline` while anything is unstaged or
@@ -185,17 +187,18 @@ witnessed tree: either the staged index (`base.kind: "staged"` with its
 Commit the exact witnessed tree, then bind the commit and both `PASS` records:
 
 ```bash
-just accept /abs/tasks/fix-improve-sources <commit-sha> \
-  /abs/tasks/fix-improve-sources/asg-writer-1 \
-  /abs/tasks/fix-improve-sources/asg-review-arch-1 \
-  /abs/tasks/fix-improve-sources/asg-review-cli-1
+kxm assign accept \
+  --task-dir /abs/tasks/fix-improve-sources \
+  --commit <commit-sha> \
+  --record-dir /abs/tasks/fix-improve-sources/asg-writer-1 \
+  --critic /abs/tasks/fix-improve-sources/asg-review-arch-1 \
+  --critic /abs/tasks/fix-improve-sources/asg-review-cli-1
 ```
 
-To record an observed pull request or CI run, call the script directly, since
-the recipe does not pass those flags:
+To record an observed pull request or CI run, pass the same flags:
 
 ```bash
-node scripts/assignment-run.mjs accept \
+kxm assign accept \
   --task-dir /abs/tasks/fix-improve-sources \
   --commit <commit-sha> \
   --record-dir /abs/tasks/fix-improve-sources/asg-writer-1 \
@@ -205,7 +208,7 @@ node scripts/assignment-run.mjs accept \
   --observed-ci <ci-id>
 ```
 
-`accept` prints JSON and takes no `--json` flag. It checks, in order, that:
+`accept` prints JSON and takes no `--json` flag, and `kxm assign --json` is not passed through. The runner checks, in order, that:
 
 1. the trusted roster policy loads and validates, before anything is written;
 2. the commit exists and its tree equals the witnessed tree;
@@ -226,7 +229,7 @@ You decide, then dispatch:
 1. Write a new manifest with `"kind": "repair"` and `"rework_of"` set to the
    assignment ID it reworks. The runner checks that the earlier assignment has a
    `completion.json` in the same task directory, with the same task ID.
-2. Dispatch it with `just assign`, then run `just witness` on the new record.
+2. Dispatch it with `kxm assign run`, then run `kxm assign witness` on the new record.
 3. Dispatch fresh critics against the new tree, and accept.
 
 A `BLOCK` stops acceptance only for the tree it judged. A repair that changes
@@ -266,7 +269,7 @@ Record friction or a model regression as a private note, without touching any
 completion:
 
 ```bash
-just attribute /abs/task-dir /abs/record-dir <class> /abs/note.txt
+kxm assign attribute --task-dir /abs/task-dir --record-dir /abs/record-dir --class <class> --explanation-file /abs/note.txt
 ```
 
 The class is `orchestration`, `model`, `environment` or `unclassified`. Each
@@ -277,7 +280,7 @@ Import a cost observation for a run whose native telemetry was not captured,
 such as a subscription session:
 
 ```bash
-just observe-cost /abs/task-dir /abs/observation.json
+kxm assign observe-cost --task-dir /abs/task-dir --input /abs/observation.json
 ```
 
 The record (`kxm.cost-observation.v1`) is cost-only. It cannot mint witness
@@ -286,7 +289,7 @@ proof or authorize acceptance.
 Summarize a task's attempts, rework and spend:
 
 ```bash
-just change-report /abs/task-dir
+kxm assign change-report --task-dir /abs/task-dir
 ```
 
 The report (`kxm.change-report.v1`) keeps provider-reported spend, list-price
@@ -356,7 +359,7 @@ ones:
 |---|---|---|
 | `route_invalid` | Route not in the role's lineup, permission above its ceiling, or the roster policy cannot load | Run from a clean control checkout on `origin/main`; check the lineup |
 | `base_invalid` | `base.commit` is not `HEAD`, the tree is dirty, or a writer targets a staged index | Commit or stash elsewhere; writers need a clean base |
-| `plan_ref_invalid` | The plan hash or path does not match `plan-current.json` | Advance the pointer with `just plan-current` |
+| `plan_ref_invalid` | The plan hash or path does not match `plan-current.json` | Advance the pointer with `kxm assign plan-current` |
 | `rework_invalid` | `rework_of` names no completed assignment in this task | Point it at an existing record directory's assignment ID |
 | `witness_failed` | The fixed gate exited non-zero | Fix the failures and run a repair |
 | `dirty_baseline` | Unstaged or untracked changes when the witness starts | Stage the candidate with `git add -A`, then re-witness |

package/docs/guides/agent-skills.md

@@ -58,7 +58,7 @@ Every top-level `kxm` command is owned by exactly one skill. A skill can own sev
 | `kxm-peer` | `peer` | Delegate to, fan out to, await and answer other agents |
 | `kxm-workflow` | `workflow`, `gate` | Record journal entries, pass checkpoints and wait on signed callbacks |
 | `kxm-definitions` | `role` | Inspect or edit roles, role hosts and model rosters without granting writer admission |
-| `kxm-runs` | `run`, `runs`, `lane` | Create, drive, inspect and cancel runs, manage worktree lanes, or smoke-test a workflow model-free |
+| `kxm-runs` | `run`, `runs`, `lane`, `assign` | Create, drive, inspect and cancel runs, manage worktree lanes, smoke-test a workflow, or call the assignment runner |
 | `kxm-context-memory` | `context`, `memory`, `explain` | Recall what the project knows, explain a context footprint, record memory candidates |
 | `kxm-skill-lifecycle` | `skills` | Turn a repeated practice into a governed skill candidate |
 | `kxm-routing-improve` | `routing`, `improve` | Find what KXM learned and what repeats, and read recorded route spend |

package/docs/index.md

@@ -0,0 +1,56 @@
+# KXM
+
+Pages in this site are generated from this checkout. The roadmap is the
+tracker. Architecture pages name the files they were read from.
+
+<div class="grid cards" markdown>
+
+- [Roadmap](roadmap/dashboard.md)
+
+    ---
+
+    Next phase, open tasks, blockers, and questions.
+
+- [Architecture](architecture/index.md)
+
+    ---
+
+    Platform, surfaces, access, authentication, the agent path, and the hosted target.
+
+- [Start](start/install.md)
+
+    ---
+
+    Install the `kxm` CLI and run a first workflow.
+
+- [Concepts](concepts/architecture.md)
+
+    ---
+
+    How the local Runtime and the hub fit together.
+
+- [Guides](guides/peer-messaging.md)
+
+    ---
+
+    Peer messaging, workers, workflows, context, and browser sessions.
+
+- [Reference](reference/cli-reference.md)
+
+    ---
+
+    Commands, configuration, tools, contracts, and templates.
+
+- [Operations](operations/backup-and-restore.md)
+
+    ---
+
+    Backup, deploy, monitoring, sync, and upgrade.
+
+- [Contributing](contributing/development.md)
+
+    ---
+
+    Development, tests, and the glossary.
+
+</div>

package/docs/javascripts/mermaid-init.js

@@ -0,0 +1,83 @@
+(function () {
+  function addButton(node) {
+    var parent = node.parentElement;
+    if (parent && parent.classList.contains("kxm-diagram")) return parent;
+    var wrap = document.createElement("div");
+    wrap.className = "kxm-diagram";
+    node.parentNode.insertBefore(wrap, node);
+    wrap.appendChild(node);
+    var button = document.createElement("button");
+    button.type = "button";
+    button.className = "kxm-fs";
+    button.textContent = "Full screen";
+    button.addEventListener("click", function () {
+      if (typeof wrap.requestFullscreen === "function") {
+        if (document.fullscreenElement === wrap) {
+          document.exitFullscreen();
+        } else {
+          wrap.requestFullscreen();
+        }
+      }
+      wrap.classList.toggle("kxm-fs-open");
+    });
+    wrap.appendChild(button);
+    return wrap;
+  }
+
+  function boot() {
+    var nodes = Array.prototype.filter.call(document.querySelectorAll(".mermaid"), function (node) {
+      if (node.getAttribute("data-kxm-mermaid") === "1") return false;
+      node.setAttribute("data-kxm-mermaid", "1");
+      addButton(node);
+      return true;
+    });
+    if (window.mermaid && !window.__kxmMermaidReady) {
+      window.mermaid.initialize({
+        startOnLoad: false,
+        securityLevel: "strict",
+        theme: "base",
+        themeVariables: {
+          darkMode: true,
+          background: "#0e0d0b",
+          primaryColor: "#3068da",
+          primaryTextColor: "#f2eee7",
+          primaryBorderColor: "#3068da",
+          secondaryColor: "#0e0d0b",
+          secondaryTextColor: "#f2eee7",
+          secondaryBorderColor: "#3068da",
+          tertiaryColor: "#0e0d0b",
+          tertiaryTextColor: "#f2eee7",
+          tertiaryBorderColor: "#3068da",
+          lineColor: "#3068da",
+          textColor: "#f2eee7",
+          mainBkg: "#0e0d0b",
+          nodeBorder: "#3068da",
+          clusterBkg: "#0e0d0b",
+          titleColor: "#f2eee7",
+          edgeLabelBackground: "#0e0d0b",
+          actorBorder: "#3068da",
+          actorBkg: "#0e0d0b",
+          actorTextColor: "#f2eee7",
+          signalColor: "#3068da",
+          signalTextColor: "#f2eee7",
+          noteBkgColor: "#0e0d0b",
+          noteTextColor: "#f2eee7",
+          noteBorderColor: "#3068da",
+        },
+      });
+      window.__kxmMermaidReady = true;
+    }
+    var pending = window.mermaid && nodes.length
+      ? window.mermaid.run({ nodes: nodes, suppressErrors: true })
+      : Promise.resolve();
+    Promise.resolve(pending).then(function () {
+      nodes.forEach(addButton);
+    });
+  }
+
+  if (window.document$ && typeof window.document$.subscribe === "function") {
+    window.document$.subscribe(boot);
+  } else {
+    document.addEventListener("DOMContentLoaded", boot);
+  }
+})();