@kontextmind/kxm 0.7.92 → 0.7.93

package/plugins/kxm/src/claude-hook.ts

@@ -0,0 +1,192 @@
+/**
+ * Claude Code plugin hook entry, bundled as dist/claude-hook.js.
+ *
+ * `node dist/claude-hook.js session-start` prints one SessionStart JSON object
+ * whose additionalContext holds a short status for this project (hub state,
+ * this project's active runs, the open request count for this agent, fix hints
+ * addressed to the user) followed by the project memory brief.
+ *
+ * The hook is read-only and scoped to the project Claude Code opened: it
+ * writes no files, mints no token, spawns nothing, and never prints a token,
+ * a plugin option other than server_url, agent_name and project, or journal
+ * text. Outside a KXM project it prints nothing. It always exits 0.
+ *
+ * Bounds: stdin 300 ms, hub health probe 300 ms, SQLite busy timeout 250 ms
+ * across at most three databases. The plugin manifest timeout is the only
+ * hard limit; an internal timer cannot fire while a synchronous SQLite read
+ * blocks.
+ *
+ * The heavy modules load through dynamic import so a failure while they load
+ * (for example a Node without node:sqlite) is caught and the hook stays
+ * silent instead of exiting non-zero.
+ */
+import { readFileSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { sessionTokenFixHint } from "./session-token-hint.ts";
+
+const STDIN_LIMIT_BYTES = 64 * 1024;
+const STDIN_WAIT_MS = 300;
+const HUB_PROBE_MS = 300;
+const SNAPSHOT_BUSY_TIMEOUT_MS = 250;
+const STATUS_MAX_CHARS = 1500;
+const MAX_ACTIVE_RUNS = 3;
+const ACTIVE_RUN_STATUSES = new Set(["running", "waiting", "created", "preparing"]);
+const DEFAULT_SERVER_URL = "http://127.0.0.1:7331";
+
+interface HookInput {
+  cwd?: unknown;
+}
+
+function readHookInput(): Promise<HookInput> {
+  const stdin = process.stdin;
+  if (stdin.isTTY) return Promise.resolve({});
+  return new Promise((resolveInput) => {
+    const chunks: Buffer[] = [];
+    let size = 0;
+    let done = false;
+    const finish = (overflow: boolean): void => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      stdin.off("data", onData);
+      stdin.off("end", onEnd);
+      stdin.off("error", onEnd);
+      stdin.pause();
+      if (overflow) {
+        resolveInput({});
+        return;
+      }
+      try {
+        const parsed: unknown = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+        resolveInput(parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed as HookInput : {});
+      } catch {
+        resolveInput({});
+      }
+    };
+    const onData = (chunk: Buffer | string): void => {
+      const buffer = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+      size += buffer.length;
+      if (size > STDIN_LIMIT_BYTES) finish(true);
+      else chunks.push(buffer);
+    };
+    const onEnd = (): void => finish(false);
+    const timer = setTimeout(onEnd, STDIN_WAIT_MS);
+    stdin.on("data", onData);
+    stdin.once("end", onEnd);
+    stdin.once("error", onEnd);
+  });
+}
+
+function isDirectory(path: string): boolean {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/** Values read from disk or options stay on one line of the context. */
+function oneLine(value: string): string {
+  return value.replace(/\s+/g, " ").trim();
+}
+
+function truncate(text: string, max: number): string {
+  return text.length <= max ? text : `${text.slice(0, max - 1)}…`;
+}
+
+async function sessionStartContext(input: HookInput, env: NodeJS.ProcessEnv): Promise<string | undefined> {
+  const inputCwd = typeof input.cwd === "string" ? input.cwd.trim() : "";
+  const root = resolve(env.CLAUDE_PROJECT_DIR?.trim() || inputCwd || process.cwd());
+  if (!isDirectory(join(root, ".kxm"))) return undefined;
+
+  const [
+    { resolveSessionHubStatus },
+    { loadLocalMeshSnapshot, resolveKxmSnapshotPaths },
+    { formatMemoryBriefText, generateMemoryBrief },
+    { defaultProjectName },
+    { enforceToolPolicy },
+    { parse },
+  ] = await Promise.all([
+    import("./session-work.ts"),
+    import("./local-snapshot.ts"),
+    import("./memory.ts"),
+    import("./project-name.ts"),
+    import("./commands.ts"),
+    import("yaml"),
+  ]);
+
+  // Same inputs .mcp.json hands the MCP server.
+  const hubProject = defaultProjectName(root, { ...env, KXM_PROJECT: env.CLAUDE_PLUGIN_OPTION_PROJECT ?? "" });
+  const recipientName = env.CLAUDE_PLUGIN_OPTION_AGENT_NAME?.trim() || undefined;
+  const url = (env.CLAUDE_PLUGIN_OPTION_SERVER_URL?.trim() || DEFAULT_SERVER_URL).replace(/\/$/, "");
+  let runtimeProjectId: string | undefined;
+  try {
+    const project = parse(readFileSync(join(root, ".kxm", "project.yaml"), "utf8")) as { id?: unknown } | null;
+    if (typeof project?.id === "string" && project.id.trim()) runtimeProjectId = project.id.trim();
+  } catch {
+    // No readable project.yaml: no Runtime runs.
+  }
+
+  const hub = await resolveSessionHubStatus(url, fetch, HUB_PROBE_MS);
+  const lines = [`KXM project ${oneLine(hubProject)} · hub ${hub.state} at ${url}`];
+
+  try {
+    const paths = resolveKxmSnapshotPaths(root, env);
+    const snapshot = loadLocalMeshSnapshot(paths.dataPath, paths.stateDir, {
+      env,
+      projectRoot: root,
+      busyTimeoutMs: SNAPSHOT_BUSY_TIMEOUT_MS,
+      scope: { hubProject, runtimeProjectId, recipientName },
+    });
+    const active = snapshot.runs.filter((run) => ACTIVE_RUN_STATUSES.has(run.status)).slice(0, MAX_ACTIVE_RUNS);
+    if (active.length > 0) {
+      lines.push("Active workflow runs in this project:");
+      for (const run of active) {
+        const stage = run.currentStage ? ` stage=${oneLine(run.currentStage)}` : "";
+        const mine = recipientName && run.targetAgentName === recipientName ? " (assigned to you)" : "";
+        lines.push(`- ${oneLine(run.id)} ${oneLine(run.definitionId)} ${oneLine(run.status)}${stage}${mine}`);
+      }
+    }
+    if (recipientName) lines.push(`Open peer requests to ${oneLine(recipientName)}: ${snapshot.openMessageTotal}`);
+  } catch {
+    // Unreadable local state: report the hub and hints without runs.
+  }
+
+  lines.push("Call kxm_context with your role and task before planning; kxm_workflow_get <runId> for an assigned run; kxm_inbox then kxm_reply for peer requests.");
+  if (hub.state !== "on") {
+    lines.push(`The KXM hub is ${hub.state} at ${url}, so kxm_* tools will fail. Ask the user to start it with \`kxm hub start\` (the kxm CLI installs separately: npm install --global --omit=peer @kontextmind/kxm).`);
+  }
+  const tokenHint = sessionTokenFixHint(enforceToolPolicy("kxm_list", env));
+  if (tokenHint) lines.push(tokenHint);
+
+  const status = truncate(lines.join("\n"), STATUS_MAX_CHARS);
+  let memory: string | undefined;
+  try {
+    // Unmodified and untruncated: the same facts `kxm memory brief` prints.
+    memory = formatMemoryBriefText(generateMemoryBrief(root));
+  } catch {
+    // A malformed memory file: keep the status sections.
+  }
+  return memory === undefined ? status : `${status}\n\n${memory}`;
+}
+
+async function main(argv: readonly string[]): Promise<void> {
+  let output = "";
+  try {
+    if (argv[2] === "session-start") {
+      const context = await sessionStartContext(await readHookInput(), process.env);
+      if (context !== undefined) {
+        output = `${JSON.stringify({ hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: context } })}\n`;
+      }
+    }
+  } catch {
+    output = "";
+  }
+  if (!output) process.exit(0);
+  process.stdout.write(output, () => process.exit(0));
+}
+
+process.on("uncaughtException", () => process.exit(0));
+process.on("unhandledRejection", () => process.exit(0));
+process.stdout.on("error", () => process.exit(0));
+void main(process.argv);

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

@@ -159,7 +159,9 @@ export async function cmdKxmInit(
       : initialized.repairPlan?.issues.length
         ? "managed-template repair is blocked by conflicts or authority changes; local files were preserved"
         : "partial or provenance-free KXM state requires explicit repair; no files were overwritten";
-    return finishInit(1, next);
+    // Name each validation issue, so a definition error reads as one instead of
+    // only as a repair refusal.
+    return finishInit(1, [next, ...initialized.plan.issues.map((issue) => `${issue.file}: ${issue.code}: ${issue.message}`)].join("\n"));
   } catch (error) {
     if (error instanceof KxmConfigError) {
       print(runtime.io, runtime.json, {
@@ -324,7 +326,11 @@ async function readSupervisor(runtime: Runtime, command: string): Promise<Awaite
 }
 
 export const RUN_ENGINE_PHASE = "pre-3a";
-export const RUN_ENGINE_NOTICE = "runs remain created until the run engine lands; no steps execute yet";
+
+/** The next step `kxm run` prints for the run it just created. */
+export function runEngineNotice(runId: string): string {
+  return `drive it model-free: kxm runs drive ${runId} --simulated --wait (or cancel: kxm runs cancel ${runId})`;
+}
 
 /** Where `kxm run <workflow>` would create its run, or the exit code of the
  * refusal it already printed. Reads only; shared with `task run --dry-run`. */
@@ -371,9 +377,9 @@ export async function cmdKxmRun(runtime: Runtime, workflow: string | undefined,
       }, `run plan: workflow ${target.workflowId} at ${target.configRevision.slice(0, 19)}… (no run created)`);
       return 0;
     }
-    const supervisor = await ensureKxmSupervisor({ env: runtime.env });
+    const supervisor = await (kxmDriveCliSeams.ensureSupervisor ?? ensureKxmSupervisor)({ env: runtime.env });
     const prompt = promptParts.join(" ").trim();
-    const acceptance = await kxmRuntimeRequest(supervisor, "POST", "/v1/runs", {
+    const acceptance = await (kxmDriveCliSeams.runtimeRequest ?? kxmRuntimeRequest)(supervisor, "POST", "/v1/runs", {
       projectRoot,
       workflowId: target.workflowId,
       prompt,
@@ -386,7 +392,7 @@ export async function cmdKxmRun(runtime: Runtime, workflow: string | undefined,
       idempotent: acceptance.idempotent === true,
       run,
       supervisor: { runtimeId: supervisor.runtimeId, port: supervisor.port, started: supervisor.started },
-    }, `run ${run.status}: ${run.runId} (home ${run.homeRuntimeId.slice(0, 12)}…, config ${run.configRevision.slice(0, 19)}…)\n${RUN_ENGINE_NOTICE}`);
+    }, `run ${run.status}: ${run.runId} (home ${run.homeRuntimeId.slice(0, 12)}…, config ${run.configRevision.slice(0, 19)}…)\n${runEngineNotice(run.runId)}`);
     return 0;
   } catch (error) {
     if (error instanceof KxmConfigError) {

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

@@ -17,6 +17,8 @@ import {
   groupByBehavior,
   generateRoutingReport,
   formatRoutingReport,
+  type RoutingRecord,
+  type RoutingRecordV2,
 } from "../routing.ts";
 import { loadPriceCatalog, type PriceCatalog } from "../prices.ts";
 import {
@@ -24,6 +26,11 @@ import {
   formatImprovementReport,
   writeImprovementReport,
 } from "../improve.ts";
+import {
+  loadRoutingSources,
+  type LoadedRoutingSources,
+  type RoutingSourceSummary,
+} from "../improve-sources.ts";
 import {
   loadModesConfig,
   resolveActiveMode,
@@ -514,26 +521,77 @@ export async function cmdArtifactsExist(runtime: Runtime, pathFlag: string): Pro
   return 0;
 }
 
-export async function cmdImprove(runtime: Runtime, options: { file?: string | undefined; target?: string | undefined; outDir?: string | undefined } = {}): Promise<number> {
-  const file = options.file ? resolve(runtime.cwd, options.file) : telemetryPath(runtime.dirs.logs);
-  const routingRecords = existsSync(file)
-    ? readRoutingRecords(file).map((entry) => entry.routing)
-    : [];
+const IMPROVE_SOURCE_UNREADABLE = "improve_source_unreadable";
+
+/** Load routing sources, or print the unreadable-source failure (exit 1). */
+function loadRoutingSourcesOrReport(runtime: Runtime, command: string, file?: string | undefined): LoadedRoutingSources | undefined {
+  try {
+    return loadRoutingSources({
+      cwd: runtime.cwd,
+      env: runtime.env,
+      logsDir: runtime.dirs.logs,
+      ...(file !== undefined ? { file } : {}),
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const detail = message.startsWith(`${IMPROVE_SOURCE_UNREADABLE}: `) ? message.slice(IMPROVE_SOURCE_UNREADABLE.length + 2) : message;
+    print(
+      runtime.io,
+      runtime.json,
+      { ok: false, command, error: IMPROVE_SOURCE_UNREADABLE, detail },
+      `${IMPROVE_SOURCE_UNREADABLE}: ${detail}`,
+    );
+    return undefined;
+  }
+}
+
+function formatRoutingSource(source: RoutingSourceSummary): string {
+  const counts = (["records", "skippedInvalid", "excludedSimulated", "undecided", "duplicatesDropped"] as const)
+    .filter((key) => source[key] !== undefined)
+    .map((key) => `${key}=${source[key]}`);
+  return `  ${source.kind.padEnd(9)} ${source.path} (exists=${source.exists}, ${counts.join(", ")})`;
+}
+
+export async function cmdImprove(runtime: Runtime, options: { file?: string | undefined; outDir?: string | undefined } = {}): Promise<number> {
+  const loaded = loadRoutingSourcesOrReport(runtime, "improve", options.file);
+  if (!loaded) return 1;
+  const root = loaded.projectRoot ?? runtime.cwd;
+
+  let config: ReturnType<typeof loadKxmConfig>;
+  try {
+    const userConfigDir = runtime.env.KXM_USER_CONFIG_DIR?.trim();
+    config = loadKxmConfig(root, userConfigDir ? { userConfigDir } : {});
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    print(runtime.io, runtime.json, { ok: false, command: "improve", error: "config_invalid", detail: message }, `config_invalid: ${message}`);
+    return 1;
+  }
 
   const candidatesDir = options.outDir
     ? resolve(runtime.cwd, options.outDir)
-    : join(runtime.cwd, ".kxm", "candidates");
+    : join(root, ".kxm", "candidates");
 
-  const report = buildImprovementReport(routingRecords, {
+  const report = buildImprovementReport(loaded.records, {
     candidatesDir,
-    projectRoot: runtime.cwd,
+    projectRoot: root,
     dryRun: runtime.dryRun,
+    promotionPolicy: config.improvement.promotionPolicy,
+    autoThreshold: config.improvement.autoThreshold,
+    halfLifeDays: config.improvement.telemetryHalfLifeDays,
   });
 
   const reportDir = join(runtime.dirs.assets, "improvements");
   const reportPath = writeImprovementReport(reportDir, report, runtime.dryRun);
 
-  const text = formatImprovementReport(report);
+  const text = [
+    "Sources:",
+    ...loaded.sources.map(formatRoutingSource),
+    loaded.projectRoot !== undefined
+      ? `Project root: ${loaded.projectRoot}`
+      : `Runtime store not read: no KXM project at ${runtime.cwd}`,
+    "",
+    formatImprovementReport(report),
+  ].join("\n");
   print(runtime.io, runtime.json, {
     ok: true,
     command: "improve",
@@ -545,6 +603,8 @@ export async function cmdImprove(runtime: Runtime, options: { file?: string | un
     candidatesCount: report.candidates.length,
     candidates: report.candidates,
     report,
+    sources: loaded.sources,
+    projectRoot: loaded.projectRoot ?? null,
   }, text);
   return 0;
 }
@@ -821,8 +881,20 @@ export async function cmdRoutingReport(
   runtime: Runtime,
   options: { file?: string | undefined; equivalentListCost?: boolean | undefined; listPrices?: boolean | undefined; prices?: string | undefined },
 ): Promise<number> {
-  const file = options.file ?? telemetryPath(runtime.dirs.logs);
-  const records = readRoutingRecords(file).map((entry) => entry.routing);
+  let file: string;
+  let records: Array<RoutingRecord | RoutingRecordV2>;
+  let sources: RoutingSourceSummary[] | undefined;
+  if (options.file !== undefined) {
+    file = options.file;
+    records = readRoutingRecords(file).map((entry) => entry.routing);
+  } else {
+    // The project's Runtime store (when cwd is in a KXM project), then telemetry.
+    const loaded = loadRoutingSourcesOrReport(runtime, "routing report");
+    if (!loaded) return 1;
+    file = telemetryPath(runtime.dirs.logs);
+    records = loaded.records;
+    sources = loaded.sources;
+  }
   const includeEquivalentListCost = Boolean(options.equivalentListCost || options.listPrices);
 
   let catalog: PriceCatalog | undefined;
@@ -838,7 +910,7 @@ export async function cmdRoutingReport(
   const report = generateRoutingReport(records, { catalog, includeEquivalentListCost });
 
   if (records.length === 0) {
-    print(runtime.io, runtime.json, { ok: true, command: "routing report", file, configurations: [], report }, "no routing records in telemetry");
+    print(runtime.io, runtime.json, { ok: true, command: "routing report", file, ...(sources ? { sources } : {}), configurations: [], report }, "no routing records in telemetry");
     return 0;
   }
 
@@ -853,7 +925,7 @@ export async function cmdRoutingReport(
   print(
     runtime.io,
     runtime.json,
-    { ok: true, command: "routing report", file, configurations, report },
+    { ok: true, command: "routing report", file, ...(sources ? { sources } : {}), configurations, report },
     text,
   );
   return 0;

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

@@ -206,7 +206,10 @@ export function redactCliValue(value: unknown, field = ""): unknown {
         || field === "baseRevision"
         || field === "candidateRevision"
         || field === "baseValueSha256"
-        || field === "candidateValueSha256")
+        || field === "candidateValueSha256"
+        || field === "workflowHash"
+        || field === "promptHash"
+        || field === "askSha256")
       && /^(?:sha256:)?[a-f0-9]{64}$/.test(value)
     ) return value;
     return redactSecrets(value);

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

@@ -10,6 +10,7 @@ import {
   addWorkflowDefinition,
   removeWorkflowDefinition,
   modifyWorkflowDefinition,
+  scaffoldWorkflowDefinition,
   WORKFLOW_TEMPLATES,
 } from "../workflow-manager.ts";
 import {
@@ -203,11 +204,26 @@ export async function cmdWorkflowAdd(
     scope?: "global" | "local" | undefined;
     overwrite?: boolean | undefined;
     pick?: string | boolean | undefined;
+    template?: string | undefined;
   },
 ): Promise<number> {
   const scope = options.scope ?? "local";
   let content: Record<string, unknown> | string | undefined;
-  if (!workflowId || options.pick) {
+  if (options.template !== undefined) {
+    const refuse = (error: string, text: string): number => {
+      print(runtime.io, runtime.json, { ok: false, command: "workflow add", error }, `workflow add failed: ${text}`);
+      return 2;
+    };
+    if (options.file !== undefined || options.pick !== undefined) {
+      return refuse("workflow_add_conflict", "--template cannot be combined with --file or --pick");
+    }
+    if (!workflowId) return refuse("workflow_id_required", "usage: kxm workflow add <workflowId> --template <name>");
+    const template = Object.hasOwn(WORKFLOW_TEMPLATES, options.template) ? WORKFLOW_TEMPLATES[options.template] : undefined;
+    if (!template) {
+      return refuse("workflow_template_unknown", `unknown template ${options.template}; choose ${Object.keys(WORKFLOW_TEMPLATES).join(", ")}`);
+    }
+    content = { ...template, ...(options.description ? { description: options.description } : {}) };
+  } else if (!workflowId || options.pick) {
     const candidates: PickCandidate[] = Object.entries(WORKFLOW_TEMPLATES).map(([id, tmpl]) => ({
       id,
       description: String(tmpl.description ?? id),
@@ -243,21 +259,7 @@ export async function cmdWorkflowAdd(
     const filePath = resolve(runtime.cwd, options.file);
     content = readFileSync(filePath, "utf8");
   } else if (!content) {
-    content = {
-      schema: "kxm.workflow.v1",
-      id: workflowId!,
-      description: options.description || `Workflow ${workflowId}`,
-      coordinator: "coordinator",
-      limits: { maxTransitions: 8 },
-      steps: [
-        {
-          id: "step-1",
-          kind: "agent",
-          role: "writer",
-          on: { passed: { target: "$terminal", terminalStatus: "completed" } },
-        },
-      ],
-    };
+    content = scaffoldWorkflowDefinition(options.description || `Workflow ${workflowId}`);
   }
 
   try {

package/plugins/kxm/src/cli.ts

@@ -25,6 +25,7 @@ import {
   enforceToolPolicy,
 } from "./commands.ts";
 import { discoverKxmProjectRoot } from "./project-config.ts";
+import { JOURNAL_CATEGORIES } from "./workflow.ts";
 import { ensureKxmSupervisor, kxmRuntimeRequest } from "./runtime-supervisor.ts";
 
 // Submodule imports
@@ -371,7 +372,7 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
 
   const program = new Command(CLI_NAME);
   program
-    .description("KontextMind local-first orchestration CLI")
+    .description("KXM local-first orchestration CLI")
     .version(readInstalledKxmVersion(findKxmRepoRoot(import.meta.url)), "-V, --version", "Print the installed kxm version")
     .exitOverride()
     .configureOutput({
@@ -412,7 +413,7 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
       result.code = await cmdRestore(runtimeFrom(ctx, this), manifest);
     });
 
-  addGlobalOptions(program.command("run").description("Create a KXM run (offline-first; no steps execute until the run engine lands)")
+  addGlobalOptions(program.command("run").description("Create a KXM run (offline-first; kxm runs drive <runId> --simulated executes it model-free)")
     .argument("[workflow]", "Workflow id to run")
     .argument("[prompt...]", "Run prompt (hashed, never stored raw)")
     .action(async function runAction(this: Command, workflow: string | undefined, promptParts: string[]) {
@@ -696,10 +697,15 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
       };
       result.code = await dispatchAgentCliCommand(runtimeFrom(ctx, this), "kxm_workflow_checkpoint", options);
     });
-  addGlobalOptions(workflow.command("record [runId] [category] [area] [summary]").description("Record workflow journal knowledge"))
+  addGlobalOptions(workflow.command("record").description("Record workflow journal knowledge"))
+    .argument("[runId]", "Workflow run ID")
+    .argument("[category]", "Journal category (see --category)")
+    .argument("[area]", "Optional improvement area; with three positionals and no --summary, the third is the summary")
+    .argument("[summary]", "Entry summary")
     .option("--run-id <id>", "Workflow run ID")
-    .option("--category <category>", "plan, decision, contradiction, error, lesson")
-    .option("--area <area>", "harness, gates, implementation, workflow, documentation, security, other")
+    .option("--category <category>", JOURNAL_CATEGORIES.join(", "))
+    .option("--area <area>", "harness, gates, implementation, workflow, documentation, security, other (defaults to the stage area with --stage-id)")
+    .option("--stage-id <id>", "Stage the entry is about; the hub derives attempt and default area")
     .option("--severity <level>", "info, warning, error")
     .option("--summary <text>", "Entry summary")
     .option("--details <text>", "Detailed text")
@@ -707,12 +713,16 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
     .option("--related-entry-ids <ids...>", "Related entry IDs")
     .option("--payload <json>", "JSON payload")
     .action(async function recordAction(this: Command, runId?: string, category?: string, area?: string, summary?: string, opts?: Record<string, unknown>) {
+      // Area is optional: `record <runId> <category> <summary>` reads the third
+      // positional as the summary when neither a fourth positional nor --summary
+      // supplies one.
+      const areaIsSummary = area !== undefined && summary === undefined && opts?.summary === undefined;
       const options = {
         ...opts,
         ...(runId ? { runId } : {}),
         ...(category ? { category } : {}),
-        ...(area ? { area } : {}),
-        ...(summary ? { summary } : {}),
+        ...(area && !areaIsSummary ? { area } : {}),
+        ...(areaIsSummary ? { summary: area } : summary ? { summary } : {}),
       };
       result.code = await dispatchAgentCliCommand(runtimeFrom(ctx, this), "kxm_workflow_record", options);
     });
@@ -771,7 +781,8 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
     .option("--scope <scope>", "Configuration scope: global or local (default: local)", "local")
     .option("--overwrite", "Overwrite existing workflow definition if present")
     .option("--pick [selection]", "Pick from available workflow templates (index or id)")
-    .action(async function workflowAddAction(this: Command, workflowId?: string, options?: { file?: string; description?: string; scope?: "global" | "local"; overwrite?: boolean; pick?: string | boolean }) {
+    .option("--template <name>", "Start from a built-in template: implement-and-verify, dual-critic-review, or spec-and-plan")
+    .action(async function workflowAddAction(this: Command, workflowId?: string, options?: { file?: string; description?: string; scope?: "global" | "local"; overwrite?: boolean; pick?: string | boolean; template?: string }) {
       result.code = await cmdWorkflowAdd(runtimeFrom(ctx, this), workflowId, options ?? {});
     });
   addGlobalOptions(workflow.command("remove [workflowId]").description("Remove a workflow definition"))
@@ -903,13 +914,12 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
       result.code = await cmdGithubWatch(runtimeFrom(ctx, this), options);
     });
 
-  const improve = addGlobalOptions(program.command("improve").description("Propose CLI or project improvements from routing records and telemetry"));
+  const improve = addGlobalOptions(program.command("improve").description("Propose coded-repeat candidates from this project's Runtime routing records and telemetry"));
   improve.helpCommand("help", "Show improve help");
   addGlobalOptions(improve.command("report", { isDefault: true }).description("Generate improvement report and candidates from routing records"))
-    .option("--file <path>", "Telemetry JSONL file to read routing records from")
-    .option("--target <cli|project>", "Limit proposals to cli or project")
+    .option("--file <path>", "Read only this routing-record JSONL instead of the project's Runtime store and telemetry")
     .option("--out-dir <path>", "Directory for candidates (default .kxm/candidates)")
-    .action(async function improveReportAction(this: Command, options: { file?: string; target?: string; outDir?: string }) {
+    .action(async function improveReportAction(this: Command, options: { file?: string; outDir?: string }) {
       result.code = await cmdImprove(runtimeFrom(ctx, this), options);
     });
 
@@ -1048,7 +1058,7 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
   const routing = addGlobalOptions(program.command("routing").description("Model/harness routing telemetry and behavioral comparisons"));
   routing.helpCommand("help", "Show routing help");
   addGlobalOptions(routing.command("report").description("Compare verified completion, cost, and rework per behavioral configuration"))
-    .option("-f, --file <path>", "Telemetry or event log JSONL file (default: workspace telemetry)")
+    .option("-f, --file <path>", "Read only this telemetry or event log JSONL file (default: this project's Runtime event store plus workspace telemetry)")
     .option("-l, --equivalent-list-cost", "Include equivalent list price column using price catalog")
     .option("--list-prices", "Alias for --equivalent-list-cost")
     .option("--prices <path>", "Path to price catalog (default: .kxm/prices.yaml)")

package/plugins/kxm/src/client.ts

@@ -7,6 +7,7 @@ import {
   canonicalWorkflowEvidenceKey,
   type ImprovementArea,
   type ImprovementAreaReport,
+  type ImprovementSignal,
   type JournalCategory,
   type WorkflowCheckpointStatus,
   type WorkflowEvidenceInput,
@@ -26,8 +27,16 @@ export interface ContextRequestAudit {
   candidateCount: number;
   excludedSuperseded: number;
   unresolvedGaps: string[];
+  /** Numbers only: distinct task tokens, eligible candidates sharing a task
+   * token, and each selected item's rounded relevance (index-aligned with
+   * selectedIds). */
+  relevance: { taskTokens: number; matchedCandidates: number; selected: number[] };
 }
 
+/** One recall result: bounded metadata plus the item's rounded relevance to
+ * the query. Never includes the summary. */
+export type ContextRecallItem = ContextItemAuditMetadata & { relevance: number };
+
 export interface ContextExplanation {
   found: boolean;
   lineage: string[];
@@ -422,13 +431,15 @@ export class HubClient {
     runId: string,
     input: {
       category: JournalCategory;
-      area: ImprovementArea;
+      /** Required unless stageId names a stage that declares an area. */
+      area?: ImprovementArea;
       severity?: "info" | "warning" | "error";
       summary: string;
       details?: string;
       evidence?: string[];
       relatedEntryIds?: string[];
-      /** Stage the entry is recorded against; binds run/stage/attempt provenance. */
+      /** Stage the entry is recorded against; binds run/stage/attempt
+       * provenance. The hub derives the attempt; callers never supply one. */
       stageId?: string;
     },
   ): Promise<WorkflowJournalEntry> {
@@ -439,7 +450,7 @@ export class HubClient {
     return result.entry;
   }
 
-  async improvementReport(): Promise<{ reports: ImprovementAreaReport[]; entries: number }> {
+  async improvementReport(): Promise<{ reports: ImprovementAreaReport[]; signals: ImprovementSignal[]; entries: number }> {
     return await this.request("/v1/improvements");
   }
 
@@ -462,7 +473,7 @@ export class HubClient {
     query?: string;
     kinds?: ContextItemKind[];
     limit?: number;
-  }): Promise<{ items: ContextItemAuditMetadata[]; unresolvedGaps: string[] }> {
+  }): Promise<{ items: ContextRecallItem[]; unresolvedGaps: string[] }> {
     return await this.request("/v1/context/recall", { method: "POST", body: JSON.stringify(input) });
   }