@kontextmind/kxm 0.7.177 → 0.7.178

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

@@ -23948,6 +23948,7 @@ function loadKxmConfig(repoRoot = process.cwd(), options = {}) {
   const userConfigFile = join(userDir, "config.yaml");
   const repoDir = repoConfigDirectory(repoRoot);
   const repoConfigFile = join(repoDir, "config.yaml");
+  const includeProject = options.layers !== "user";
   let userRaw = {};
   let userLoadedPath;
   if (existsSync(userConfigFile)) {
@@ -23961,7 +23962,7 @@ function loadKxmConfig(repoRoot = process.cwd(), options = {}) {
   }
   let repoRaw = {};
   let repoLoadedPath;
-  if (existsSync(repoConfigFile)) {
+  if (includeProject && existsSync(repoConfigFile)) {
     try {
       const text = readFileSync(repoConfigFile, "utf8");
       repoRaw = (0, import_yaml.parse)(text) ?? {};
@@ -25461,7 +25462,7 @@ function sessionTokenFixHint(policy) {
 }
 
 // plugins/kxm/src/mcp-server.ts
-var VERSION = "0.7.177";
+var VERSION = "0.7.178";
 var CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 var inbox = /* @__PURE__ */ new Map();
 var notifiedInbox = /* @__PURE__ */ new Set();

package/plugins/kxm/dist/runtime-supervisor.js

@@ -25121,6 +25121,7 @@ function loadKxmConfig(repoRoot = process.cwd(), options = {}) {
   const userConfigFile = join11(userDir, "config.yaml");
   const repoDir = repoConfigDirectory(repoRoot);
   const repoConfigFile = join11(repoDir, "config.yaml");
+  const includeProject = options.layers !== "user";
   let userRaw = {};
   let userLoadedPath;
   if (existsSync10(userConfigFile)) {
@@ -25134,7 +25135,7 @@ function loadKxmConfig(repoRoot = process.cwd(), options = {}) {
   }
   let repoRaw = {};
   let repoLoadedPath;
-  if (existsSync10(repoConfigFile)) {
+  if (includeProject && existsSync10(repoConfigFile)) {
     try {
       const text = readFileSync8(repoConfigFile, "utf8");
       repoRaw = (0, import_yaml5.parse)(text) ?? {};

package/plugins/kxm/dist/runtime.js

@@ -25865,6 +25865,7 @@ function loadKxmConfig(repoRoot = process.cwd(), options = {}) {
   const userConfigFile = join11(userDir, "config.yaml");
   const repoDir = repoConfigDirectory(repoRoot);
   const repoConfigFile = join11(repoDir, "config.yaml");
+  const includeProject = options.layers !== "user";
   let userRaw = {};
   let userLoadedPath;
   if (existsSync10(userConfigFile)) {
@@ -25878,7 +25879,7 @@ function loadKxmConfig(repoRoot = process.cwd(), options = {}) {
   }
   let repoRaw = {};
   let repoLoadedPath;
-  if (existsSync10(repoConfigFile)) {
+  if (includeProject && existsSync10(repoConfigFile)) {
     try {
       const text = readFileSync8(repoConfigFile, "utf8");
       repoRaw = (0, import_yaml5.parse)(text) ?? {};

package/plugins/kxm/dist/server.js

@@ -23447,6 +23447,7 @@ function loadKxmConfig(repoRoot = process.cwd(), options = {}) {
   const userConfigFile = join7(userDir, "config.yaml");
   const repoDir = repoConfigDirectory(repoRoot);
   const repoConfigFile = join7(repoDir, "config.yaml");
+  const includeProject = options.layers !== "user";
   let userRaw = {};
   let userLoadedPath;
   if (existsSync7(userConfigFile)) {
@@ -23460,7 +23461,7 @@ function loadKxmConfig(repoRoot = process.cwd(), options = {}) {
   }
   let repoRaw = {};
   let repoLoadedPath;
-  if (existsSync7(repoConfigFile)) {
+  if (includeProject && existsSync7(repoConfigFile)) {
     try {
       const text2 = readFileSync5(repoConfigFile, "utf8");
       repoRaw = (0, import_yaml6.parse)(text2) ?? {};

package/plugins/kxm/package.json

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

package/plugins/kxm/src/autocomplete.ts

@@ -53,7 +53,7 @@ const SUBCOMMANDS: Record<string, string[]> = {
   memory: ["brief", "note", "sync"],
   routing: ["report", "benchmark"],
   hub: ["view", "start", "stop", "bind", "unbind"],
-  config: ["get", "set", "list"],
+  config: ["get", "set", "edit", "list"],
   goal: ["create", "list", "get"],
   task: ["create", "list", "get", "run", "sync"],
   studio: ["layout", "serve"],
@@ -179,7 +179,7 @@ _kxm() {
           _arguments '1:shell:(bash zsh fish)'
           ;;
         config)
-          _arguments '1:action:(get set list)'
+          _arguments '1:action:(get set edit list)'
           ;;
         runs)
           _arguments '1:subcommand:(status cancel list)'
@@ -224,7 +224,7 @@ complete -c kxm -n "__fish_seen_subcommand_from completion" -a "bash zsh fish"
 complete -c kxm -n "__fish_seen_subcommand_from dash" -l screen -a "agents tasks workflows plans inbox procs spend"
 
 # Config subcommand
-complete -c kxm -n "__fish_seen_subcommand_from config" -a "get set list"
+complete -c kxm -n "__fish_seen_subcommand_from config" -a "get set edit list"
 
 # Runs subcommand
 complete -c kxm -n "__fish_seen_subcommand_from runs" -a "status cancel list"

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

@@ -48,7 +48,9 @@ import {
   setKxmConfigValue,
   getKxmConfigValue,
   formatKxmConfig,
+  userConfigDirForEnv,
 } from "../config.ts";
+import { runKxmConfigEditor } from "../config-editor.ts";
 import { generateShellCompletion, type SupportedShell } from "../autocomplete.ts";
 import {
   completionRcTarget,
@@ -736,6 +738,41 @@ export async function cmdConfigSet(
   }
 }
 
+export async function cmdConfigEdit(
+  runtime: Runtime,
+  options: { scope?: string },
+  isTty = Boolean(process.stdin.isTTY && process.stdout.isTTY),
+): Promise<number> {
+  const scope = options.scope;
+  if (scope !== "project" && scope !== "user") {
+    const detail = "config edit requires --scope project or --scope user";
+    print(runtime.io, runtime.json, { ok: false, command: "config edit", error: "config_edit_unsupported", detail }, detail);
+    return 2;
+  }
+  if (runtime.json) {
+    const detail = "config edit does not print machine-readable output";
+    print(runtime.io, runtime.json, { ok: false, command: "config edit", error: "config_edit_unsupported", detail }, detail);
+    return 2;
+  }
+  try {
+    const userConfigDir = userConfigDirForEnv(runtime.env);
+    return await runKxmConfigEditor({
+      target: {
+        cwd: runtime.cwd,
+        scope,
+        ...(userConfigDir === undefined ? {} : { userConfigDir }),
+      },
+      stdout: (text) => runtime.io.stdout(text),
+      isTty,
+      dryRun: runtime.dryRun,
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    runtime.io.stderr(`config edit failed: ${message}\n`);
+    return 1;
+  }
+}
+
 export async function cmdConfigList(runtime: Runtime): Promise<number> {
   try {
     const config = loadKxmConfig(runtime.cwd);

package/plugins/kxm/src/cli.ts

@@ -165,6 +165,7 @@ import {
   cmdImprove,
   cmdConfigGet,
   cmdConfigSet,
+  cmdConfigEdit,
   cmdConfigList,
   cmdCompletion,
   cmdCompletionInstall,
@@ -228,7 +229,7 @@ const DRY_RUN_COMMANDS: ReadonlySet<string> = new Set([
   "routing report", "routing benchmark",
   "ssh info", "ssh run", "ssh file", "ssh close",
   "hub view", "hub start", "hub stop", "hub bind", "hub unbind",
-  "config get", "config set", "config list",
+  "config get", "config set", "config edit", "config list",
   "goal create", "goal list",
   "task create", "task list", "task get", "task run", "task sync",
   "studio layout", "studio serve",
@@ -1430,6 +1431,11 @@ function createProgram(ctx: CliContext, result: { code: number }, argv: readonly
     .action(async function configSetAction(this: Command, key: string, value: string, options: { scope: string }) {
       result.code = await cmdConfigSet(runtimeFrom(ctx, this), key, value, options);
     });
+  addGlobalOptions(configCmd.command("edit").description("Edit supported non-secret settings in the terminal panel"))
+    .option("--scope <scope>", "Write scope: project or user")
+    .action(async function configEditAction(this: Command, options: { scope?: string }) {
+      result.code = await cmdConfigEdit(runtimeFrom(ctx, this), options);
+    });
   addGlobalOptions(configCmd.command("list", { isDefault: true }).description("List resolved configuration values"))
     .action(async function configListAction(this: Command) {
       result.code = await cmdConfigList(runtimeFrom(ctx, this));

package/plugins/kxm/src/config-editor.ts

@@ -0,0 +1,479 @@
+/**
+ * Owner for the `kxm.config.v1` terminal editor.
+ *
+ * The panel publishes this contribution and routes every write back here.
+ * `listSections` re-reads the merged files on each publish. `set` and `clear`
+ * validate the field and the value, then call the config owner. A refusal
+ * throws before either owner call, so the file bytes stay as they were.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { parse } from "yaml";
+import {
+  KXM_TUI_CLEAR_ACTION,
+  KXM_TUI_SET_ACTION,
+  createKxmTuiRegistry,
+  createKxmTuiPiPanel,
+  createPlainKxmTuiTheme,
+  runKxmTuiPanel,
+  type KxmTuiContribution,
+  type KxmTuiField,
+  type KxmTuiSectionView,
+} from "@kontextmind/tui";
+import {
+  deleteKxmConfigValue,
+  getKxmConfigValue,
+  kxmConfigFileForScope,
+  loadKxmConfig,
+  setKxmConfigValue,
+  userConfigDirForEnv,
+  type KxmResolvedConfig,
+} from "./config.ts";
+
+export const KXM_CONFIG_EDITOR_SOURCE = "kxm/config";
+
+export type KxmConfigEditorScope = "project" | "user";
+
+const INTEGER_TEXT = /^(0|[1-9][0-9]*)$/;
+const DECIMAL_TEXT = /^(0|[1-9][0-9]*)(\.[0-9]{1,6})?$/;
+/** Workflow and harness ids already in use, including `@`, with no whitespace. */
+const TEXT_VALUE = /^[A-Za-z0-9@][A-Za-z0-9@._:/-]{0,127}$/;
+
+interface EnumSpec {
+  readonly kind: "enum";
+  readonly choices: readonly string[];
+}
+
+interface NumberSpec {
+  readonly kind: "number";
+  readonly integer: boolean;
+  readonly min: number;
+  readonly max: number;
+}
+
+interface TextSpec {
+  readonly kind: "text";
+}
+
+type ValueSpec = EnumSpec | NumberSpec | TextSpec;
+
+interface ConfigEditorFieldSpec {
+  readonly id: string;
+  readonly label: string;
+  readonly keyPath: string;
+  readonly spec: ValueSpec;
+  readonly note?: string;
+}
+
+interface ConfigEditorSectionSpec {
+  readonly id: string;
+  readonly title: string;
+  readonly order: number;
+  readonly fields: readonly ConfigEditorFieldSpec[];
+}
+
+const SCREEN_CHOICES = ["agents", "tasks", "workflows", "plans", "inbox", "procs", "spend"] as const;
+
+const SECTIONS: readonly ConfigEditorSectionSpec[] = [
+  {
+    id: "user",
+    title: "User",
+    order: 10,
+    fields: [
+      { id: "user-theme", label: "Theme", keyPath: "user.theme", spec: { kind: "enum", choices: ["dark", "light", "minimal"] } },
+      { id: "user-token-budget", label: "Token budget", keyPath: "user.tokenBudget", spec: { kind: "number", integer: true, min: 1, max: 2_000_000 } },
+    ],
+  },
+  {
+    id: "defaults",
+    title: "Defaults",
+    order: 20,
+    fields: [
+      { id: "defaults-workflow", label: "Workflow", keyPath: "defaults.workflow", spec: { kind: "text" } },
+      { id: "defaults-harness", label: "Harness", keyPath: "defaults.harness", spec: { kind: "text" } },
+    ],
+  },
+  {
+    id: "dash",
+    title: "Dashboard",
+    order: 30,
+    fields: [
+      { id: "dash-screen", label: "Default screen", keyPath: "dash.defaultScreen", spec: { kind: "enum", choices: SCREEN_CHOICES } },
+      { id: "dash-refresh", label: "Refresh interval", keyPath: "dash.refreshIntervalMs", spec: { kind: "number", integer: true, min: 250, max: 3_600_000 } },
+      { id: "dash-auto-open", label: "Auto-open", keyPath: "dash.autoOpen", spec: { kind: "enum", choices: ["true", "false"] } },
+    ],
+  },
+  {
+    id: "sync",
+    title: "Sync",
+    order: 40,
+    fields: [
+      { id: "sync-tracker", label: "Default tracker", keyPath: "sync.defaultTracker", spec: { kind: "enum", choices: ["github", "jira", "none"] } },
+    ],
+  },
+  {
+    id: "hub",
+    title: "Hub",
+    order: 50,
+    fields: [
+      {
+        id: "hub-auto-start",
+        label: "Auto-start",
+        keyPath: "hub.autoStart",
+        spec: { kind: "enum", choices: ["background", "off"] },
+        note: "Hub URLs and key references stay out of this panel.",
+      },
+    ],
+  },
+  {
+    id: "improvement",
+    title: "Improvement",
+    order: 60,
+    fields: [
+      { id: "improvement-policy", label: "Promotion policy", keyPath: "improvement.promotionPolicy", spec: { kind: "enum", choices: ["manual_pr", "critic_quorum", "auto_threshold"] } },
+      { id: "improvement-half-life", label: "Telemetry half-life", keyPath: "improvement.telemetryHalfLifeDays", spec: { kind: "number", integer: false, min: 0.000001, max: 3650 } },
+      { id: "improvement-min-runs", label: "Minimum runs", keyPath: "improvement.autoThreshold.minRuns", spec: { kind: "number", integer: true, min: 1, max: 1_000_000 } },
+      { id: "improvement-min-pass-rate", label: "Minimum pass rate", keyPath: "improvement.autoThreshold.minPassRate", spec: { kind: "number", integer: false, min: 0, max: 1 } },
+      { id: "improvement-min-cost-savings", label: "Minimum cost savings", keyPath: "improvement.autoThreshold.minCostSavings", spec: { kind: "number", integer: false, min: 0, max: 1_000_000 } },
+    ],
+  },
+  {
+    id: "routing",
+    title: "Routing",
+    order: 70,
+    fields: [
+      {
+        id: "routing-shadow",
+        label: "Shadow execution",
+        keyPath: "routing.shadowExecution.enabled",
+        spec: { kind: "enum", choices: ["true", "false"] },
+        note: "Strategy, fallback, and context limits stay in role and route files.",
+      },
+      { id: "routing-sample-rate", label: "Sample rate", keyPath: "routing.shadowExecution.sampleRate", spec: { kind: "number", integer: false, min: 0, max: 1 } },
+      { id: "routing-breaker-mode", label: "Breaker mode", keyPath: "routing.circuitBreaker.mode", spec: { kind: "enum", choices: ["soft_demotion", "quarantine"] } },
+      { id: "routing-failure-threshold", label: "Failure threshold", keyPath: "routing.circuitBreaker.failureThreshold", spec: { kind: "number", integer: true, min: 1, max: 10_000 } },
+      { id: "routing-window-seconds", label: "Window seconds", keyPath: "routing.circuitBreaker.windowSeconds", spec: { kind: "number", integer: true, min: 1, max: 31_536_000 } },
+      { id: "routing-cooldown-seconds", label: "Cooldown seconds", keyPath: "routing.circuitBreaker.cooldownSeconds", spec: { kind: "number", integer: true, min: 0, max: 31_536_000 } },
+      { id: "routing-penalty", label: "Penalty multiplier", keyPath: "routing.circuitBreaker.penaltyMultiplier", spec: { kind: "number", integer: false, min: 0.000001, max: 1000 } },
+    ],
+  },
+  {
+    id: "telemetry",
+    title: "Telemetry",
+    order: 80,
+    fields: [
+      { id: "telemetry-federated", label: "Federated", keyPath: "telemetry.federated", spec: { kind: "enum", choices: ["true", "false"] } },
+      { id: "telemetry-anonymize", label: "Anonymize", keyPath: "telemetry.anonymize", spec: { kind: "enum", choices: ["true", "false"] } },
+    ],
+  },
+];
+
+
+export class KxmConfigEditorError extends Error {
+  readonly code = "config_edit_refused";
+
+  constructor(message: string) {
+    super(message);
+    this.name = "KxmConfigEditorError";
+  }
+}
+
+export interface KxmConfigEditorTarget {
+  readonly cwd: string;
+  readonly scope: KxmConfigEditorScope;
+  readonly userConfigDir?: string | undefined;
+}
+
+export function kxmConfigEditorKeyPaths(): readonly string[] {
+  return SECTIONS.flatMap((section) => section.fields.map((field) => field.keyPath));
+}
+
+export function createKxmConfigEditorContribution(target: KxmConfigEditorTarget): KxmTuiContribution {
+  return {
+    source: KXM_CONFIG_EDITOR_SOURCE,
+    republishAfterWrite: true,
+    listSections: () => listConfigEditorSections(target),
+    handlers: {
+      [KXM_TUI_SET_ACTION]: (input) => {
+        writeConfigEditorValue(target, input.sectionId, input.fieldId, input.value);
+      },
+      [KXM_TUI_CLEAR_ACTION]: (input) => {
+        clearConfigEditorValue(target, input.sectionId, input.fieldId);
+      },
+    },
+    describeError: (error) => (error instanceof Error && error.message ? error.message : "config edit failed"),
+  };
+}
+
+function scopeFile(target: KxmConfigEditorTarget): string {
+  return kxmConfigFileForScope(target.cwd, target.scope, target.userConfigDir);
+}
+
+function scopePhrase(scope: KxmConfigEditorScope): string {
+  return scope === "project" ? "the project file .kxm/config.yaml" : "the user file config.yaml";
+}
+
+function listConfigEditorSections(target: KxmConfigEditorTarget): KxmTuiSectionView[] {
+  const config = loadKxmConfig(target.cwd, {
+    ...(target.userConfigDir === undefined ? {} : { userConfigDir: target.userConfigDir }),
+    layers: target.scope === "user" ? "user" : "all",
+  });
+  const owned = readScopeDocument(scopeFile(target));
+  const where = scopePhrase(target.scope);
+  return SECTIONS.map((section) => {
+    const fields = section.fields.map((field) => publishField(field, config, owned, where));
+    const diagnosis = fields.find((field) => field.statusText)?.statusText;
+    return {
+      source: KXM_CONFIG_EDITOR_SOURCE,
+      id: section.id,
+      title: section.title,
+      order: section.order,
+      detail: `kxm.config.v1 · ${target.scope} scope. Re-read from disk after each write.`,
+      ...(diagnosis === undefined ? {} : { notice: diagnosis, noticeLevel: "error" as const }),
+      fields,
+    };
+  });
+}
+
+function publishField(
+  field: ConfigEditorFieldSpec,
+  config: KxmResolvedConfig,
+  owned: Record<string, unknown> | undefined,
+  where: string,
+): KxmTuiField {
+  const effective = getKxmConfigValue(config, field.keyPath);
+  const stored = ownValue(owned, field.keyPath);
+  const shown = displayScalar(effective);
+  const inherited = !stored.present;
+  const diagnosis = storedDiagnosis(field, stored, effective);
+  const detail = [
+    `Writes ${where}.`,
+    inherited ? "Inherited." : "Set in this scope.",
+    "Clear removes only this override.",
+    field.note ?? "",
+    diagnosis ?? "",
+  ].filter((part) => part.length > 0).join(" ");
+  const choices = field.spec.kind === "enum"
+    ? field.spec.choices.map((choice) => ({ id: choice, label: choice }))
+    : undefined;
+  return {
+    id: field.id,
+    label: field.label,
+    kind: field.spec.kind === "enum" ? "enum" : "text",
+    keyPath: field.keyPath,
+    detail,
+    status: "ready",
+    ...(shown === undefined ? {} : { value: shown }),
+    ...(choices === undefined ? {} : { choices }),
+    ...(diagnosis === undefined ? {} : { statusText: diagnosis }),
+  };
+}
+
+function displayScalar(value: unknown): string | undefined {
+  if (typeof value === "string" && value.length > 0) return value;
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (typeof value === "number" && Number.isFinite(value)) return String(value);
+  return undefined;
+}
+
+function isBooleanEnum(spec: ValueSpec): boolean {
+  return spec.kind === "enum"
+    && spec.choices.length === 2
+    && spec.choices.every((choice) => choice === "true" || choice === "false");
+}
+
+/** A display string such as `"true"` is not a boolean. The stored YAML type has to match the descriptor. */
+function storedTypeMatches(field: ConfigEditorFieldSpec, value: unknown): boolean {
+  if (field.spec.kind === "number") {
+    return typeof value === "number"
+      && Number.isFinite(value)
+      && (!field.spec.integer || Number.isInteger(value));
+  }
+  if (isBooleanEnum(field.spec)) return typeof value === "boolean";
+  return typeof value === "string";
+}
+
+function storedDiagnosis(
+  field: ConfigEditorFieldSpec,
+  stored: { present: boolean; value: unknown },
+  effective: unknown,
+): string | undefined {
+  if (!stored.present) return undefined;
+  if (!storedTypeMatches(field, stored.value)) return "stored type does not match this field";
+  if (field.spec.kind === "enum" && !isBooleanEnum(field.spec) && !field.spec.choices.includes(stored.value as string)) {
+    return "stored value is not a supported scalar";
+  }
+  if (field.spec.kind === "number") {
+    const value = stored.value as number;
+    if (value < field.spec.min || value > field.spec.max) return "stored value is not a supported scalar";
+  }
+  if (stored.value !== effective) return "stored value is not a supported scalar";
+  return undefined;
+}
+
+function writeConfigEditorValue(target: KxmConfigEditorTarget, sectionId: string, fieldId: string, raw: string | undefined): void {
+  const field = requireField(sectionId, fieldId);
+  const value = parseEditorValue(field, raw);
+  setKxmConfigValue(target.cwd, field.keyPath, value, {
+    scope: target.scope,
+    ...(target.userConfigDir === undefined ? {} : { userConfigDir: target.userConfigDir }),
+  });
+}
+
+function clearConfigEditorValue(target: KxmConfigEditorTarget, sectionId: string, fieldId: string): void {
+  const field = requireField(sectionId, fieldId);
+  deleteKxmConfigValue(target.cwd, field.keyPath, {
+    scope: target.scope,
+    ...(target.userConfigDir === undefined ? {} : { userConfigDir: target.userConfigDir }),
+  });
+}
+
+function requireField(sectionId: string, fieldId: string): ConfigEditorFieldSpec {
+  const section = SECTIONS.find((item) => item.id === sectionId);
+  const field = section?.fields.find((item) => item.id === fieldId);
+  if (!field) throw new KxmConfigEditorError("unknown configuration field");
+  return field;
+}
+
+function parseEditorValue(field: ConfigEditorFieldSpec, raw: string | undefined): string | number | boolean {
+  if (raw === undefined) throw new KxmConfigEditorError("a value is required");
+  if (raw.length === 0 || raw.length > 128 || /[\u0000-\u001f\u007f]/u.test(raw)) {
+    throw new KxmConfigEditorError("value must be a single bounded line");
+  }
+  if (field.spec.kind === "enum") {
+    if (!field.spec.choices.includes(raw)) throw new KxmConfigEditorError("value is not a supported choice");
+    if (isBooleanEnum(field.spec)) return raw === "true";
+    return raw;
+  }
+  if (field.spec.kind === "text") {
+    if (!TEXT_VALUE.test(raw)) throw new KxmConfigEditorError("value must be a single bounded line");
+    return raw;
+  }
+  if (!(field.spec.integer ? INTEGER_TEXT : DECIMAL_TEXT).test(raw)) {
+    throw new KxmConfigEditorError("value must be a finite number in range");
+  }
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || (field.spec.integer && !Number.isInteger(parsed)) || parsed < field.spec.min || parsed > field.spec.max) {
+    throw new KxmConfigEditorError("value must be a finite number in range");
+  }
+  return parsed;
+}
+
+function readScopeDocument(file: string): Record<string, unknown> | undefined {
+  if (!existsSync(file)) return undefined;
+  const parsed = parse(readFileSync(file, "utf8")) as unknown;
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new KxmConfigEditorError(`config file ${file} must be a mapping`);
+  }
+  return parsed as Record<string, unknown>;
+}
+
+function ownValue(root: Record<string, unknown> | undefined, keyPath: string): { present: boolean; value: unknown } {
+  if (!root) return { present: false, value: undefined };
+  let cursor: unknown = root;
+  for (const part of keyPath.split(".")) {
+    if (!cursor || typeof cursor !== "object" || Array.isArray(cursor)) return { present: false, value: undefined };
+    const record = cursor as Record<string, unknown>;
+    if (!Object.prototype.hasOwnProperty.call(record, part)) return { present: false, value: undefined };
+    cursor = record[part];
+  }
+  return { present: true, value: cursor };
+}
+
+const EDITOR_HELP = [
+  "↑↓ move · enter edits · x clears this scope's override · q quits",
+  "Writes are checked, saved, then re-read. A refused edit leaves the file unchanged.",
+] as const;
+
+const FRAME_NOW_MS = Date.UTC(2026, 9, 11);
+
+export async function runKxmConfigEditor(input: {
+  readonly target: KxmConfigEditorTarget;
+  readonly stdout: (text: string) => void;
+  readonly isTty: boolean;
+  readonly dryRun: boolean;
+}): Promise<number> {
+  const registry = createKxmTuiRegistry();
+  try {
+    registry.register(createKxmConfigEditorContribution(input.target));
+    registry.getSections();
+    const failed = registry.getIssues()[0];
+    if (failed) throw new KxmConfigEditorError(failed.message);
+    const interactive = input.isTty && !input.dryRun;
+    return await runKxmTuiPanel({
+      registry,
+      title: "KXM configuration",
+      breadcrumb: `kxm.config.v1 · ${input.target.scope} scope`,
+      helpLines: EDITOR_HELP,
+      stdout: input.stdout,
+      isTty: interactive,
+      ...(interactive ? {} : { theme: createPlainKxmTuiTheme() }),
+      now: () => FRAME_NOW_MS,
+    });
+  } finally {
+    registry.dispose();
+  }
+}
+
+interface ConfigPanelUi {
+  notify?: ((message: string, type?: "error" | "info" | "warning") => void) | undefined;
+  custom?: ((
+    factory: (
+      tui: { requestRender(): void },
+      theme: { fg(token: string, text: string): string; bg(token: string, text: string): string },
+      keybindings: unknown,
+      done: (result: undefined) => void,
+    ) => { render(width: number): string[]; handleInput(data: string): void; invalidate(): void },
+    options?: { overlay?: boolean },
+  ) => Promise<unknown>) | undefined;
+}
+
+/** Mount the project-scope editor on Pi's generic custom panel. Only a TUI session may open it. */
+export async function openKxmProjectConfigPanel(
+  ui: { notify?: (message: string, type?: "error" | "info" | "warning") => void; custom?: unknown },
+  cwd: string,
+  env: NodeJS.ProcessEnv = process.env,
+  mode?: string,
+): Promise<void> {
+  if (mode !== "tui") {
+    ui.notify?.(
+      "kxm: /kxm config opens only in the Pi TUI. Nothing was written. Run kxm config edit --scope project",
+      "warning",
+    );
+    return;
+  }
+  if (typeof ui.custom !== "function") {
+    ui.notify?.(
+      "kxm: /kxm config needs Pi's custom panel. Open the repository in the Pi TUI, or run kxm config edit --scope project",
+      "warning",
+    );
+    return;
+  }
+  const custom = ui.custom as NonNullable<ConfigPanelUi["custom"]>;
+  const registry = createKxmTuiRegistry();
+  const userConfigDir = userConfigDirForEnv(env);
+  try {
+    registry.register(createKxmConfigEditorContribution({
+      cwd,
+      scope: "project",
+      ...(userConfigDir === undefined ? {} : { userConfigDir }),
+    }));
+    await custom(
+      (tui, theme, _keybindings, done) => createKxmTuiPiPanel({
+        registry,
+        tui,
+        theme,
+        title: "KXM configuration",
+        breadcrumb: "kxm.config.v1 · project scope",
+        helpLines: EDITOR_HELP,
+        done: () => {
+          registry.dispose();
+          done(undefined);
+        },
+      }),
+      { overlay: true },
+    );
+  } finally {
+    registry.dispose();
+  }
+}