@kontextmind/kxm 0.7.122 → 0.7.123

package/plugins/kxm/dist/mcp-server.js

@@ -17313,7 +17313,7 @@ function sessionTokenFixHint(policy) {
 }
 
 // plugins/kxm/src/mcp-server.ts
-var VERSION = "0.7.122";
+var VERSION = "0.7.123";
 var CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 var inbox = /* @__PURE__ */ new Map();
 var notifiedInbox = /* @__PURE__ */ new Set();

package/plugins/kxm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-plugin",
-  "version": "0.7.122",
+  "version": "0.7.123",
   "private": true,
   "type": "module",
   "engines": {

package/plugins/kxm/skills/kxm/SKILL.md

@@ -20,8 +20,7 @@ writers, or replace `.kxm/roster.yaml` trusted policy.
 | Delegate to or answer another agent | `kxm-peer` | `peer` (`peer await` is capped at 60 seconds) |
 | Work inside a durable workflow run, gates, signed callbacks | `kxm-workflow` | `workflow`, `gate` |
 | Role definitions, role hosts, model rosters | `kxm-definitions` | `role` |
-| Create, drive, inspect, or cancel a run, use a worktree lane, or land a branch | `kxm-runs` | `run`, `runs`, `lane`, `land` |
-| Create, drive, inspect, or cancel a run, use a worktree lane, or run the developer assignment loop | `kxm-runs` | `run`, `runs`, `lane`, `assign` |
+| Create, drive, inspect, or cancel a run, use a worktree lane, land a branch, run the developer assignment loop, or build and serve the docs site | `kxm-runs` | `run`, `runs`, `lane`, `land`, `assign`, `docs` |
 | What we know or decided, recall, context footprint, Git memory | `kxm-context-memory` | `context`, `memory`, `explain` |
 | Turn a repeated practice into a governed skill | `kxm-skill-lifecycle` | `skills` |
 | What KXM learned, repeated asks, recorded route spend | `kxm-routing-improve` | `routing`, `improve` |

package/plugins/kxm/skills/kxm-runs/SKILL.md

@@ -11,6 +11,11 @@ the Runtime supervisor. A created run stays `created` until
 an admitted model; `--simulated` is the model-free producer. Do not invent get,
 create, or logs verbs under `runs`.
 
+`kxm docs build` regenerates the docs site from the roadmap state by running
+`node plans/kxm-roadmap/update-dashboard.mjs` at the project root. `kxm docs
+serve` serves that site with `python3 ops/docs-site/serve.py` and passes
+`--port` through when it is set. Both require a KXM project.
+
 ## Commands
 
 | Command | Purpose | Options / arguments |
@@ -34,6 +39,8 @@ create, or logs verbs under `runs`.
 | `kxm assign observe-cost` | Import one cost-only observation | `--task-dir <path>`, `--input <path>` |
 | `kxm assign accept` | Bind a witnessed commit and two critic records | `--task-dir <path>`, `--commit <sha>`, `--record-dir <path>`, `--critic <path>` twice, optional `--observed-pr <id>`, `--observed-ci <id>` |
 | `kxm assign change-report` | Report attempts, rework, and spend | `--task-dir <path>` |
+| `kxm docs build` | Regenerate the docs site from roadmap state | `--dry-run`, `--json` |
+| `kxm docs serve` | Serve the built site on the tailnet address | `--port <port>`, `--dry-run`, `--json` |
 
 The run record and its events keep only the prompt's hash, but the full
 prompt text is kept in a local `run-events.db.run-prompts.json` file (mode

package/plugins/kxm/src/cli/docs.ts

@@ -0,0 +1,78 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { discoverKxmProjectRoot } from "../project-config.ts";
+import { print, type Runtime } from "./types.ts";
+
+const GENERATOR = "plans/kxm-roadmap/update-dashboard.mjs";
+const SERVER = "ops/docs-site/serve.py";
+
+function requireProject(runtime: Runtime, command: string): string | number {
+  const root = discoverKxmProjectRoot(runtime.cwd);
+  if (!root) {
+    print(
+      runtime.io,
+      runtime.json,
+      { ok: false, command, error: "project_required" },
+      `kxm ${command} requires a KXM project (run kxm init first)`,
+    );
+    return 1;
+  }
+  return root;
+}
+
+function requireFile(runtime: Runtime, command: string, root: string, relative: string, error: string): string | number {
+  const file = join(root, relative);
+  if (existsSync(file)) return file;
+  print(
+    runtime.io,
+    runtime.json,
+    { ok: false, command, error, path: relative },
+    `kxm ${command} requires ${relative}`,
+  );
+  return 1;
+}
+
+function printCommand(runtime: Runtime, command: string, line: string): number {
+  print(
+    runtime.io,
+    runtime.json,
+    { ok: true, command, dryRun: true, detail: line },
+    line,
+  );
+  return 0;
+}
+
+function runInherited(command: string, args: readonly string[], cwd: string): Promise<number> {
+  return new Promise((resolveExit) => {
+    const child = spawn(command, [...args], { cwd, stdio: "inherit" });
+    child.once("error", () => resolveExit(1));
+    child.once("exit", (code) => resolveExit(code ?? 1));
+  });
+}
+
+/** Regenerate the docs site from the roadmap state. */
+export async function cmdDocsBuild(runtime: Runtime): Promise<number> {
+  const command = "docs build";
+  const root = requireProject(runtime, command);
+  if (typeof root === "number") return root;
+  const file = requireFile(runtime, command, root, GENERATOR, "docs_generator_missing");
+  if (typeof file === "number") return file;
+  const line = `node ${GENERATOR}`;
+  if (runtime.dryRun) return printCommand(runtime, command, line);
+  return runInherited(process.execPath, [file], root);
+}
+
+/** Serve the built site. `--port` is passed through when set. */
+export async function cmdDocsServe(runtime: Runtime, options: { port?: string } = {}): Promise<number> {
+  const command = "docs serve";
+  const root = requireProject(runtime, command);
+  if (typeof root === "number") return root;
+  const file = requireFile(runtime, command, root, SERVER, "docs_server_missing");
+  if (typeof file === "number") return file;
+  const args = [file];
+  if (options.port !== undefined && options.port !== "") args.push("--port", options.port);
+  const line = ["python3", SERVER, ...args.slice(1)].join(" ");
+  if (runtime.dryRun) return printCommand(runtime, command, line);
+  return runInherited("python3", args, root);
+}

package/plugins/kxm/src/cli.ts

@@ -120,6 +120,7 @@ cmdBackup,
 } from "./cli/project.ts";
 
 import { cmdPluginInstall } from "./cli/plugins.ts";
+import { cmdDocsBuild, cmdDocsServe } from "./cli/docs.ts";
 
 import {
   applyLane,
@@ -227,6 +228,7 @@ const DRY_RUN_COMMANDS: ReadonlySet<string> = new Set([
   "goal create", "goal list",
   "task create", "task list", "task get", "task run", "task sync",
   "studio layout", "studio serve",
+  "docs build", "docs serve",
 ]);
 
 class DryRunRefused extends Error {
@@ -625,6 +627,18 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
       result.code = await cmdKxmRunList(runtimeFrom(ctx, this));
     });
 
+  const docsCmd = addGlobalOptions(program.command("docs").description("Build and serve the tailnet docs site"));
+  docsCmd.helpCommand("help", "Show docs help");
+  addGlobalOptions(docsCmd.command("build").description("Regenerate the docs site from the roadmap state"))
+    .action(async function docsBuildAction(this: Command) {
+      result.code = await cmdDocsBuild(runtimeFrom(ctx, this));
+    });
+  addGlobalOptions(docsCmd.command("serve").description("Serve the built docs site on this machine's tailnet address"))
+    .option("--port <port>", "Port passed through to the docs server")
+    .action(async function docsServeAction(this: Command, options: { port?: string }) {
+      result.code = await cmdDocsServe(runtimeFrom(ctx, this), options);
+    });
+
   const tenantCmd = addGlobalOptions(program.command("tenant").description("Composed tenant reads for machine clients (portal)"));
   tenantCmd.helpCommand("help", "Show tenant help");
   addGlobalOptions(tenantCmd.command("status").description("Read hub metadata and authoritative Runtime run state as one labeled view"))

package/plugins/kxm/src/mcp-server.ts

@@ -11,7 +11,7 @@ import { deliverInboxNotification } from "./inbox.ts";
 import type { HubEvent, MessageRecord } from "./protocol.ts";
 import { sessionTokenFixHint } from "./session-token-hint.ts";
 
-const VERSION = "0.7.122";
+const VERSION = "0.7.123";
 const CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();

package/schemas/roadmap-state.schema.json

@@ -0,0 +1,147 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.kxm.dev/roadmap-state.schema.json",
+  "title": "KXM roadmap state",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "updated", "goal", "phases"],
+  "properties": {
+    "schema": { "const": "kxm.roadmap.v1" },
+    "updated": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" },
+    "goal": { "type": "string", "minLength": 1 },
+    "constraints": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "contacts": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/contact" }
+    },
+    "contacts_comment": { "type": "string" },
+    "history": {
+      "type": "array",
+      "description": "Oldest first. The generator keeps the newest 12 lines and drops the older ones (history_over_cap). That prune is not a schema refusal.",
+      "items": { "$ref": "#/$defs/historyLine" }
+    },
+    "architecture": { "$ref": "#/$defs/architecture" },
+    "improvements": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "phases": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/phase" }
+    }
+  },
+  "$defs": {
+    "date": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" },
+    "historyLine": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["date", "line"],
+      "properties": {
+        "date": { "$ref": "#/$defs/date" },
+        "line": { "type": "string", "minLength": 1, "maxLength": 240 }
+      }
+    },
+    "contact": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["role", "confirmed"],
+      "properties": {
+        "role": { "type": "string", "minLength": 1 },
+        "name": { "type": "string", "minLength": 1 },
+        "confirmed": { "$ref": "#/$defs/date" }
+      }
+    },
+    "architecture": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "verified": {
+          "anyOf": [
+            { "type": "null" },
+            { "$ref": "#/$defs/date" }
+          ]
+        },
+        "docs": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "drift": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["claim", "page", "status"],
+            "properties": {
+              "claim": { "type": "string" },
+              "page": { "type": "string" },
+              "status": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    "phase": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "slug", "title", "goal", "source", "tasks"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "slug": { "type": "string", "minLength": 1 },
+        "title": { "type": "string", "minLength": 1 },
+        "goal": { "type": "string", "minLength": 1 },
+        "source": { "type": "string", "minLength": 1 },
+        "priority": { "const": "later" },
+        "horizon": {
+          "description": "Derived by the generator from phase order and priority (next, soon, or later). Not hand-set. A stored value is ignored.",
+          "enum": ["next", "soon", "later"]
+        },
+        "blockers": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "questions": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "tasks": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/task" }
+        }
+      }
+    },
+    "task": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "title", "status"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "title": { "type": "string", "minLength": 1 },
+        "status": { "enum": ["open", "done"] },
+        "evidence": { "type": "string" },
+        "planSection": { "type": "string", "minLength": 1 },
+        "doneCriterion": { "type": "string", "minLength": 1 },
+        "evidenceNeeded": { "type": "string", "minLength": 1 },
+        "template": {
+          "enum": [
+            "feature",
+            "research",
+            "bug-fix",
+            "architecture",
+            "adr",
+            "test-plan",
+            "test-report",
+            "review",
+            "handoff",
+            "runbook",
+            "postmortem",
+            "none"
+          ]
+        },
+        "detail": { "enum": ["brief", "scoped", "ready"] }
+      }
+    }
+  }
+}