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

package/CHANGELOG.md

@@ -35,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/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);
+  }
+})();