clef-mcp 0.1.6 → 0.2.1

package/dist/cli.js

@@ -102,11 +102,11 @@ __export(setup_exports, {
   installSkill: () => installSkill,
   runSetup: () => runSetup
 });
-import { execFile as execFile4 } from "child_process";
-import fsSync2 from "fs";
-import fsp6 from "fs/promises";
+import { execFile as execFile5 } from "child_process";
+import fsSync4 from "fs";
+import fsp8 from "fs/promises";
 import os4 from "os";
-import path9 from "path";
+import path10 from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 function bundledSkillPath() {
   return fileURLToPath2(new URL("../skills/clef-decisions/SKILL.md", import.meta.url));
@@ -114,7 +114,7 @@ function bundledSkillPath() {
 async function mergeJsonServerEntry(file, serverKey, container) {
   let doc = {};
   try {
-    doc = JSON.parse(await fsp6.readFile(file, "utf8"));
+    doc = JSON.parse(await fsp8.readFile(file, "utf8"));
   } catch {
     doc = {};
   }
@@ -131,15 +131,15 @@ async function mergeJsonServerEntry(file, serverKey, container) {
     servers[serverKey] = { command: SERVER_ENTRY.command, args: [...SERVER_ENTRY.args] };
     doc.mcpServers = servers;
   }
-  await fsp6.mkdir(path9.dirname(file), { recursive: true });
-  await fsp6.writeFile(file, JSON.stringify(doc, null, 2) + "\n", "utf8");
+  await fsp8.mkdir(path10.dirname(file), { recursive: true });
+  await fsp8.writeFile(file, JSON.stringify(doc, null, 2) + "\n", "utf8");
   return "configured";
 }
 async function setupCodex() {
-  const file = path9.join(HOME(), ".codex", "config.toml");
+  const file = path10.join(HOME(), ".codex", "config.toml");
   let content = "";
   try {
-    content = await fsp6.readFile(file, "utf8");
+    content = await fsp8.readFile(file, "utf8");
   } catch {
     content = "";
   }
@@ -147,26 +147,26 @@ async function setupCodex() {
     return { client: "codex", status: "already-configured", detail: file };
   }
   const next = (content && !content.endsWith("\n") ? content + "\n" : content) + "\n" + CODEX_SECTION;
-  await fsp6.mkdir(path9.dirname(file), { recursive: true });
-  await fsp6.writeFile(file, next, "utf8");
+  await fsp8.mkdir(path10.dirname(file), { recursive: true });
+  await fsp8.writeFile(file, next, "utf8");
   return { client: "codex", status: "configured", detail: file };
 }
 async function setupZcode() {
-  const file = path9.join(HOME(), ".zcode", "cli", "config.json");
+  const file = path10.join(HOME(), ".zcode", "cli", "config.json");
   const status = await mergeJsonServerEntry(file, "clef-mcp", "mcp.servers");
   return { client: "zcode", status, detail: file };
 }
 async function setupCursor() {
-  const file = path9.join(HOME(), ".cursor", "mcp.json");
+  const file = path10.join(HOME(), ".cursor", "mcp.json");
   const status = await mergeJsonServerEntry(file, "clef-mcp", "mcpServers");
   return { client: "cursor", status, detail: file };
 }
 function whichCli(bin) {
-  const dirs = (process.env.PATH ?? "").split(path9.delimiter).filter(Boolean);
+  const dirs = (process.env.PATH ?? "").split(path10.delimiter).filter(Boolean);
   for (const dir of dirs) {
-    const candidate = path9.join(dir, bin);
+    const candidate = path10.join(dir, bin);
     try {
-      fsSync2.accessSync(candidate, fsSync2.constants.X_OK);
+      fsSync4.accessSync(candidate, fsSync4.constants.X_OK);
       return candidate;
     } catch {
     }
@@ -183,13 +183,13 @@ async function setupClaudeCode() {
     };
   }
   const existing = await new Promise((resolve) => {
-    execFile4(claude, ["mcp", "list"], { timeout: 3e4, encoding: "utf8" }, (_err, stdout) => resolve(String(stdout)));
+    execFile5(claude, ["mcp", "list"], { timeout: 3e4, encoding: "utf8" }, (_err, stdout) => resolve(String(stdout)));
   });
   if (existing.includes("clef-mcp")) {
     return { client: "claude-code", status: "already-configured", detail: "claude mcp list" };
   }
   await new Promise((resolve, reject) => {
-    execFile4(
+    execFile5(
       claude,
       ["mcp", "add", "--scope", "user", "clef-mcp", "--", "clef-mcp"],
       { timeout: 6e4, encoding: "utf8" },
@@ -200,19 +200,19 @@ async function setupClaudeCode() {
 }
 async function installSkill() {
   const src = bundledSkillPath();
-  const destDir = path9.join(HOME(), ".agents", "skills", "clef-decisions");
-  const dest = path9.join(destDir, "SKILL.md");
+  const destDir = path10.join(HOME(), ".agents", "skills", "clef-decisions");
+  const dest = path10.join(destDir, "SKILL.md");
   let content = "";
   try {
-    content = await fsp6.readFile(dest, "utf8");
+    content = await fsp8.readFile(dest, "utf8");
   } catch {
   }
-  const incoming = await fsp6.readFile(src, "utf8");
+  const incoming = await fsp8.readFile(src, "utf8");
   if (content === incoming) {
     return { client: "skill", status: "already-configured", detail: dest };
   }
-  await fsp6.mkdir(destDir, { recursive: true });
-  await fsp6.writeFile(dest, incoming, "utf8");
+  await fsp8.mkdir(destDir, { recursive: true });
+  await fsp8.writeFile(dest, incoming, "utf8");
   return { client: "skill", status: "configured", detail: dest };
 }
 function parseClients(raw) {
@@ -493,6 +493,7 @@ function limitsFromEnv(env = process.env) {
 }
 
 // src/config/env.ts
+var SUPPORTED_RUNTIMES = ["llama-cpp", "mlx"];
 var SUPPORTED_LOG_LEVELS = ["error", "warn", "info", "debug"];
 function parseLogLevel(value) {
   if (!value) return void 0;
@@ -504,19 +505,20 @@ function defaultClefHome() {
 }
 function loadConfig(env = process.env) {
   const logLevel = parseLogLevel(env.CLEF_LOG_LEVEL) ?? "error";
-  const runtime = env.CLEF_RUNTIME?.trim() || "llama-cpp";
-  if (runtime !== "llama-cpp") {
-    throw new Error(`Unsupported CLEF_RUNTIME "${runtime}". Supported: llama-cpp`);
+  const runtimeRaw = (env.CLEF_RUNTIME?.trim() || "llama-cpp").toLowerCase();
+  if (!SUPPORTED_RUNTIMES.includes(runtimeRaw)) {
+    throw new Error(`Unsupported CLEF_RUNTIME "${runtimeRaw}". Supported: ${SUPPORTED_RUNTIMES.join(", ")}`);
   }
+  const runtime = runtimeRaw;
   const llamaBin = env.CLEF_LLAMA_BIN?.trim() || void 0;
   const llamaReleaseTag = env.CLEF_LLAMA_RELEASE_TAG?.trim() || void 0;
   return {
     model: env.CLEF_MODEL?.trim() || "clef-flash",
     clefHome: env.CLEF_HOME?.trim() || defaultClefHome(),
-    runtime: "llama-cpp",
+    runtime,
     logLevel,
-    llamaBin,
-    llamaReleaseTag,
+    llamaBin: runtime === "llama-cpp" ? llamaBin : void 0,
+    llamaReleaseTag: runtime === "llama-cpp" ? llamaReleaseTag : void 0,
     limits: limitsFromEnv(env)
   };
 }
@@ -671,10 +673,10 @@ function isModelManifest(v) {
   const m = v;
   return m.schemaVersion === 1 && typeof m.model === "string" && typeof m.quant === "string" && typeof m.file === "string" && typeof m.modelPath === "string" && typeof m.bytes === "number";
 }
-async function readModelManifest(manifestPath) {
+async function readModelManifest(manifestPath2) {
   let raw;
   try {
-    raw = await fsp.readFile(manifestPath, "utf8");
+    raw = await fsp.readFile(manifestPath2, "utf8");
   } catch {
     return void 0;
   }
@@ -685,9 +687,9 @@ async function readModelManifest(manifestPath) {
     return void 0;
   }
 }
-async function writeModelManifest(manifestPath, manifest) {
-  await fsp.mkdir(path3.dirname(manifestPath), { recursive: true });
-  await fsp.writeFile(manifestPath, JSON.stringify(manifest, null, 2) + "\n", "utf8");
+async function writeModelManifest(manifestPath2, manifest) {
+  await fsp.mkdir(path3.dirname(manifestPath2), { recursive: true });
+  await fsp.writeFile(manifestPath2, JSON.stringify(manifest, null, 2) + "\n", "utf8");
 }
 async function findInstalledQuant(modelsDir, model, specs) {
   const installed = [];
@@ -745,23 +747,165 @@ function isRuntimeManifest(v) {
   const m = v;
   return m.schemaVersion === 1 && m.kind === "llama-cpp" && typeof m.releaseTag === "string" && typeof m.asset === "string" && typeof m.binaryPath === "string";
 }
-async function writeRuntimeManifest(manifestPath, manifest) {
-  await fsp.mkdir(path3.dirname(manifestPath), { recursive: true });
-  await fsp.writeFile(manifestPath, JSON.stringify(manifest, null, 2) + "\n", "utf8");
+async function writeRuntimeManifest(manifestPath2, manifest) {
+  await fsp.mkdir(path3.dirname(manifestPath2), { recursive: true });
+  await fsp.writeFile(manifestPath2, JSON.stringify(manifest, null, 2) + "\n", "utf8");
 }
-function readRuntimeManifest(manifestPath) {
+function readRuntimeManifest(manifestPath2) {
   try {
-    const parsed = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+    const parsed = JSON.parse(fs.readFileSync(manifestPath2, "utf8"));
     return isRuntimeManifest(parsed) ? parsed : void 0;
   } catch {
     return void 0;
   }
 }
 
+// src/models/mlx-install.ts
+init_errors();
+import { execFile } from "child_process";
+import fsSync from "fs";
+import fsp2 from "fs/promises";
+import path4 from "path";
+var MLX_MODEL_REPO = "mlx-community/clef-flash-4bit";
+var MLX_MODEL_REVISION = "140bf7e037f5fa95a96535feca112f46c15927cf";
+function manifestPath(clefHome) {
+  return path4.join(pathsFor(clefHome).modelsDir, "clef-flash", "mlx", "manifest.json");
+}
+async function readMlxManifest(clefHome) {
+  let raw;
+  try {
+    raw = await fsp2.readFile(manifestPath(clefHome), "utf8");
+  } catch {
+    return void 0;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed.kind === "mlx" && typeof parsed.snapshotPath === "string") return parsed;
+    return void 0;
+  } catch {
+    return void 0;
+  }
+}
+async function writeMlxManifest(clefHome, manifest) {
+  const file = manifestPath(clefHome);
+  await fsp2.mkdir(path4.dirname(file), { recursive: true });
+  await fsp2.writeFile(file, JSON.stringify(manifest, null, 2) + "\n", "utf8");
+}
+async function mlxIsInstalled(clefHome) {
+  const manifest = await readMlxManifest(clefHome);
+  if (!manifest) return void 0;
+  try {
+    await fsp2.access(path4.join(manifest.snapshotPath, "clef_mlx.py"));
+    return manifest;
+  } catch {
+    return void 0;
+  }
+}
+function resolveUv(envUv) {
+  if (envUv?.trim()) return envUv.trim();
+  const dirs = (process.env.PATH ?? "").split(path4.delimiter).filter(Boolean);
+  for (const dir of dirs) {
+    const candidate = path4.join(dir, "uv");
+    try {
+      fsSync.accessSync(candidate, fsSync.constants.X_OK);
+      return candidate;
+    } catch {
+    }
+  }
+  throw new ClefError(
+    ClefErrorCode.RUNTIME_NOT_FOUND,
+    "uv is required for the MLX runtime but was not found on PATH.",
+    "Install it with: curl -LsSf https://astral.sh/uv/install.sh | sh"
+  );
+}
+async function runUv(uvBin, args, opts = {}) {
+  return new Promise((resolve, reject) => {
+    const child = execFile(
+      uvBin,
+      args,
+      { timeout: opts.timeoutMs ?? 6e5, maxBuffer: 16 * 1024 * 1024, encoding: "utf8" },
+      (err, stdout, stderr) => {
+        if (err) {
+          reject(
+            new ClefError(
+              ClefErrorCode.DOWNLOAD_FAILED,
+              `uv command failed: ${err.message.split("\n")[0]}${stderr ? `
+${stderr.trim().slice(0, 1e3)}` : ""}`,
+              "Make sure uv is up to date: uv self update"
+            )
+          );
+        } else {
+          resolve(stdout.trim());
+        }
+      }
+    );
+    if (opts.onStdoutLine) {
+      let buf = "";
+      child.stdout?.on("data", (chunk) => {
+        buf += chunk.toString();
+        const lines = buf.split("\n");
+        buf = lines.pop() ?? "";
+        for (const line of lines) opts.onStdoutLine(line);
+      });
+    }
+  });
+}
+async function installModelMlx(opts) {
+  const existing = await mlxIsInstalled(opts.clefHome);
+  if (existing) return existing;
+  const uvBin = resolveUv(opts.uvBin ?? process.env.CLEF_MLX_UV);
+  const hfCache = path4.join(pathsFor(opts.clefHome).root, "hf-cache");
+  await fsp2.mkdir(hfCache, { recursive: true });
+  opts.log?.info("downloading MLX model snapshot", { repo: MLX_MODEL_REPO, revision: MLX_MODEL_REVISION });
+  const py = [
+    "from huggingface_hub import snapshot_download",
+    `p = snapshot_download("${MLX_MODEL_REPO}", revision="${MLX_MODEL_REVISION}", cache_dir=r"${hfCache}")`,
+    "print(p)"
+  ].join("\n");
+  const stdout = await runUv(
+    uvBin,
+    ["run", "--with", "huggingface_hub", "python", "-c", py],
+    {
+      timeoutMs: 18e5,
+      onStdoutLine: (line) => {
+        if (line.trim()) opts.log?.debug(line.trimEnd());
+      }
+    }
+  );
+  const lines = stdout.split("\n").filter((l) => l.trim().startsWith("/"));
+  const snapshotPath = lines.at(-1)?.trim();
+  if (!snapshotPath) {
+    throw new ClefError(ClefErrorCode.DOWNLOAD_FAILED, "snapshot_download did not report a snapshot path");
+  }
+  await fsp2.access(path4.join(snapshotPath, "clef_mlx.py"));
+  const manifest = {
+    schemaVersion: 1,
+    kind: "mlx",
+    model: "clef-flash",
+    repo: MLX_MODEL_REPO,
+    revision: MLX_MODEL_REVISION,
+    snapshotPath,
+    licenseId: "Apache-2.0",
+    licenseUrl: "https://huggingface.co/Cloudflare/clef-flash",
+    installedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    clefMcpVersion: opts.clefMcpVersion
+  };
+  await writeMlxManifest(opts.clefHome, manifest);
+  opts.log?.info("MLX model installed", { snapshotPath });
+  return manifest;
+}
+async function removeMlxModel(clefHome) {
+  const manifest = await readMlxManifest(clefHome);
+  if (!manifest) return false;
+  await fsp2.rm(manifest.snapshotPath, { recursive: true, force: true }).catch(() => void 0);
+  await fsp2.rm(path4.dirname(manifestPath(clefHome)), { recursive: true, force: true });
+  return true;
+}
+
 // src/runtime/binary.ts
 init_errors();
 import fs2 from "fs";
-import path4 from "path";
+import path5 from "path";
 function existsExecutable(p) {
   try {
     fs2.accessSync(p, fs2.constants.X_OK);
@@ -771,11 +915,11 @@ function existsExecutable(p) {
   }
 }
 function whichBin(name, platform) {
-  const dirs = (process.env.PATH ?? "").split(path4.delimiter).filter(Boolean);
+  const dirs = (process.env.PATH ?? "").split(path5.delimiter).filter(Boolean);
   const exts = platform === "win32" ? (process.env.PATHEXT ?? ".exe").split(";") : [""];
   for (const dir of dirs) {
     for (const ext of exts) {
-      const candidate = path4.join(dir, name + ext.toLowerCase());
+      const candidate = path5.join(dir, name + ext.toLowerCase());
       if (existsExecutable(candidate)) return candidate;
     }
   }
@@ -783,9 +927,9 @@ function whichBin(name, platform) {
 }
 function managedBinary(clefHome, platform, arch, exists) {
   const platformDir = llamaRuntimeDir(pathsFor(clefHome).runtimeDir, platform, arch);
-  const manifest = readRuntimeManifest(path4.join(platformDir, "runtime-manifest.json"));
+  const manifest = readRuntimeManifest(path5.join(platformDir, "runtime-manifest.json"));
   if (manifest && exists(manifest.binaryPath)) return manifest.binaryPath;
-  const legacy = path4.join(platformDir, llamaServerName(platform));
+  const legacy = path5.join(platformDir, llamaServerName(platform));
   if (exists(legacy)) return legacy;
   return void 0;
 }
@@ -1053,6 +1197,207 @@ ${tail}` : ""),
   }
 };
 
+// src/runtime/mlx.ts
+init_errors();
+import { spawn as spawn2 } from "child_process";
+import net2 from "net";
+var STDERR_TAIL_LIMIT2 = 4e3;
+function freePort2() {
+  return new Promise((resolve, reject) => {
+    const srv = net2.createServer();
+    srv.unref();
+    srv.on("error", reject);
+    srv.listen(0, "127.0.0.1", () => {
+      const addr = srv.address();
+      const port = typeof addr === "object" && addr ? addr.port : 0;
+      srv.close(() => port > 0 ? resolve(port) : reject(new Error("could not acquire a free port")));
+    });
+  });
+}
+async function fetchWithTimeout2(url, init, timeoutMs) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await fetch(url, { ...init, signal: controller.signal });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+var OOM_PATTERNS2 = ["out of memory", "failed to allocate", "unable to allocate", "not enough memory"];
+var MlxRuntime = class {
+  constructor(opts) {
+    this.opts = opts;
+    this.host = opts.host ?? "127.0.0.1";
+    this.loadTimeoutMs = opts.loadTimeoutMs ?? 18e4;
+    this.requestTimeoutMs = opts.requestTimeoutMs ?? 12e4;
+  }
+  opts;
+  proc;
+  resolvedPort;
+  host;
+  loadTimeoutMs;
+  requestTimeoutMs;
+  queue = Promise.resolve();
+  get endpoint() {
+    if (!this.resolvedPort) throw new ClefError(ClefErrorCode.RUNTIME_INIT_FAILED, "Runtime is not started");
+    return `http://${this.host}:${this.resolvedPort}`;
+  }
+  get running() {
+    return this.proc !== void 0 && this.proc.exitCode === null;
+  }
+  async load() {
+    if (this.running) return;
+    const port = this.opts.port ?? await freePort2();
+    this.resolvedPort = port;
+    const args = [
+      "run",
+      "--directory",
+      this.opts.snapshotPath,
+      "--with",
+      "mlx-vlm>=0.7.4,<0.8",
+      "--with",
+      "huggingface_hub",
+      "python",
+      "clef_mlx.py",
+      "serve",
+      "--host",
+      this.host,
+      "--port",
+      String(port)
+    ];
+    this.opts.log?.debug("spawning clef_mlx.py serve", { uv: this.opts.uvBin, snapshot: this.opts.snapshotPath });
+    let proc;
+    try {
+      proc = spawn2(this.opts.uvBin, args, { stdio: ["ignore", "pipe", "pipe"], cwd: this.opts.snapshotPath });
+    } catch (err) {
+      throw new ClefError(
+        ClefErrorCode.RUNTIME_INIT_FAILED,
+        `Failed to start the MLX server: ${err instanceof Error ? err.message : String(err)}`,
+        "Run `clef-mcp doctor` for a full diagnosis."
+      );
+    }
+    this.proc = proc;
+    let stderrTail = "";
+    proc.stderr?.on("data", (chunk) => {
+      const text = chunk.toString();
+      stderrTail = (stderrTail + text).slice(-STDERR_TAIL_LIMIT2);
+      this.opts.log?.debug(text.trimEnd());
+    });
+    proc.stdout?.on("data", (chunk) => {
+      this.opts.log?.debug(chunk.toString().trimEnd());
+    });
+    let rejectOnExit;
+    const exitedBeforeReady = new Promise((_resolve, reject) => {
+      rejectOnExit = reject;
+    });
+    const onEarlyExit = (code, signal) => {
+      const oom = OOM_PATTERNS2.some((p) => stderrTail.toLowerCase().includes(p));
+      const message = `clef_mlx.py exited before becoming ready (code=${code ?? "null"}, signal=${signal ?? "null"})`;
+      const tail = stderrTail.trim();
+      rejectOnExit?.(
+        oom ? new ClefError(ClefErrorCode.OUT_OF_MEMORY, message, "Not enough free memory for this model. Try the llama.cpp runtime with Q4_K_M instead.") : new ClefError(ClefErrorCode.RUNTIME_INIT_FAILED, message + (tail ? `
+stderr tail:
+${tail}` : ""), "Run `clef-mcp doctor` for a full diagnosis.")
+      );
+    };
+    proc.once("exit", onEarlyExit);
+    try {
+      await Promise.race([this.waitUntilReady(), exitedBeforeReady]);
+    } finally {
+      proc.removeListener("exit", onEarlyExit);
+    }
+  }
+  async waitUntilReady() {
+    const deadline = Date.now() + this.loadTimeoutMs;
+    let lastError = "";
+    while (Date.now() < deadline) {
+      if (!this.running) throw new ClefError(ClefErrorCode.RUNTIME_INIT_FAILED, "MLX server is not running");
+      try {
+        const res = await fetchWithTimeout2(`${this.endpoint}/health`, { method: "GET" }, 2e3);
+        if (res.status === 200) return;
+        lastError = `health status ${res.status}`;
+      } catch (err) {
+        lastError = err instanceof Error ? err.message : String(err);
+      }
+      await new Promise((r) => setTimeout(r, 250));
+    }
+    throw new ClefError(
+      ClefErrorCode.MODEL_LOAD_FAILED,
+      `MLX server did not become ready within ${Math.round(this.loadTimeoutMs / 1e3)}s (last health check: ${lastError})`,
+      "The first load can take a while; subsequent loads reuse the snapshot cache."
+    );
+  }
+  async decide(input) {
+    const run = this.queue.then(() => this.decideOnce(input));
+    this.queue = run.catch(() => void 0);
+    return run;
+  }
+  async decideOnce(input) {
+    if (!this.running) {
+      throw new ClefError(ClefErrorCode.RUNTIME_INIT_FAILED, "Runtime is not loaded; call load() first");
+    }
+    let res;
+    try {
+      res = await fetchWithTimeout2(
+        `${this.endpoint}/v1/systemone`,
+        { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(input) },
+        this.requestTimeoutMs
+      );
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new ClefError(ClefErrorCode.CLEF_INFERENCE_FAILED, `Inference request failed: ${msg}`);
+    }
+    const bodyText = await res.text();
+    let body = void 0;
+    try {
+      body = bodyText ? JSON.parse(bodyText) : void 0;
+    } catch {
+    }
+    if (!res.ok) {
+      const apiMessage = body && typeof body === "object" && "error" in body ? String(body.error?.message ?? bodyText) : bodyText;
+      throw new ClefError(ClefErrorCode.CLEF_INFERENCE_FAILED, `Inference failed with HTTP ${res.status}: ${apiMessage.slice(0, 2e3)}`);
+    }
+    if (!body || typeof body !== "object") {
+      throw new ClefError(ClefErrorCode.CLEF_INFERENCE_FAILED, `Runtime returned a non-JSON response (HTTP ${res.status})`);
+    }
+    return body;
+  }
+  async health() {
+    if (!this.running) return { status: "unavailable", detail: "not started" };
+    try {
+      const res = await fetchWithTimeout2(`${this.endpoint}/health`, { method: "GET" }, 1500);
+      if (res.status === 200) return { status: "ready" };
+      return { status: "loading", detail: `health status ${res.status}` };
+    } catch (err) {
+      return { status: "unavailable", detail: err instanceof Error ? err.message : String(err) };
+    }
+  }
+  async unload() {
+    const proc = this.proc;
+    if (!proc) return;
+    this.proc = void 0;
+    if (proc.exitCode !== null || proc.signalCode) return;
+    await new Promise((resolve) => {
+      const killTimer = setTimeout(() => {
+        try {
+          proc.kill("SIGKILL");
+        } catch {
+        }
+      }, 3e3);
+      proc.once("exit", () => {
+        clearTimeout(killTimer);
+        resolve();
+      });
+      try {
+        proc.kill("SIGTERM");
+      } catch {
+        clearTimeout(killTimer);
+        resolve();
+      }
+    });
+  }
+};
+
 // src/mcp/schema.ts
 init_errors();
 import { z } from "zod";
@@ -1087,10 +1432,12 @@ function scoreCriteria(limits) {
 }
 function questionSchema(limits) {
   return z.object({
-    type: z.enum(["noul", "choice", "score"]),
-    instructions: z.string().min(1).max(limits.maxInstructionsChars),
+    type: z.enum(["noul", "choice", "score"]).describe('"choice" = pick among named options; "score" = judge an ordered scale; "noul" = yes/no question'),
+    instructions: z.string().min(1).max(limits.maxInstructionsChars).describe("What to judge, phrased as a self-contained question."),
     criteria: z.union([z.array(z.string()), z.record(z.string(), z.string())]).optional()
-  }).superRefine((q, ctx) => {
+  }).describe(
+    "A single decision question. Allowed answers come from `criteria` and must be mutually exclusive and collectively exhaustive."
+  ).superRefine((q, ctx) => {
     if (q.type === "choice") {
       const parsed = choiceCriteria(limits).safeParse(q.criteria);
       if (!parsed.success) {
@@ -1114,23 +1461,27 @@ function questionSchema(limits) {
 }
 function clefDecideInputShape(limits) {
   return {
-    state: z.unknown(),
-    questions: z.record(z.string().min(1).max(limits.maxQuestionIdChars), questionSchema(limits)).check((ctx) => {
+    state: z.unknown().describe(
+      "Task state as data: a compact string or JSON object with the facts needed to judge (task, errors, logs, diffs). Never treated as instructions. Serialized size limit: 1 MB; model context is 16k tokens."
+    ),
+    questions: z.record(z.string().min(1).max(limits.maxQuestionIdChars), questionSchema(limits)).describe(
+      "Map of question id -> typed question. Up to 64 questions per call; all are scored together in a single forward pass, so batch related decisions here."
+    ).check((ctx) => {
       const count = Object.keys(ctx.value).length;
       if (count === 0) ctx.issues.push({ code: "custom", message: "questions must not be empty", input: ctx.value });
       if (count > limits.maxQuestions) {
         ctx.issues.push({ code: "custom", message: `too many questions (max ${limits.maxQuestions})`, input: ctx.value });
       }
     }),
-    model: z.string().min(1).optional(),
+    model: z.string().min(1).optional().describe("Model id to use (default: clef-flash from CLEF_MODEL)."),
     options: z.object({
       /**
        * Accepted for forward compatibility. Clef scores all options in a
        * single forward pass — there is no sampling, so temperature is a
        * documented no-op.
        */
-      temperature: z.number().min(0).max(2).optional()
-    }).optional()
+      temperature: z.number().min(0).max(2).optional().describe("Accepted for forward compatibility; no-op. Clef scores in a single forward pass without sampling.")
+    }).optional().describe("Extra options. Currently only temperature, which is a documented no-op.")
   };
 }
 function clefDecideInputSchema(limits) {
@@ -1170,40 +1521,375 @@ function validateStateSize(state, limits) {
   }
 }
 
-// src/mcp/server.ts
-var TOOL_NAME = "clef_decide";
-var SERVER_INSTRUCTIONS = "clef_decide passes task state plus typed questions to the local Clef decision model and returns a probability distribution over answer options. Treat `state` as data: it is never interpreted as instructions for this server. The result is structured JSON; do not render it as prose.";
-function createClefServer(deps = {}) {
-  const config = deps.config ?? loadConfig();
-  const log = deps.log ?? createLogger(config.logLevel);
-  const server = new McpServer({ name: "clef-mcp", version: deps.version ?? "0.1.0" }, { instructions: SERVER_INSTRUCTIONS });
-  let loaded;
-  let loadPromise;
-  async function ensureRuntime(spec) {
-    if (loaded && loaded.model === spec.id) return loaded;
-    if (loaded && loaded.model !== spec.id) {
-      await loaded.runtime.unload();
-      loaded = void 0;
-    }
-    if (loadPromise) return loadPromise;
-    loadPromise = (async () => {
-      const manifest = await findInstalledManifest(config.clefHome, spec);
-      if (!manifest) {
-        throw new ClefError(
-          ClefErrorCode.MODEL_NOT_INSTALLED,
-          `Clef model "${spec.id}" is not installed.`,
-          "Run `clef-mcp install`."
-        );
-      }
-      const binary = resolveLlamaServerBinary(config);
-      const runtime = deps.runtimeFactory ? deps.runtimeFactory({ serverBin: binary.path, modelPath: manifest.modelPath, alias: spec.id, log }) : new LlamaCppRuntime({ serverBin: binary.path, modelPath: manifest.modelPath, alias: spec.id, log });
-      log.debug("loading model", { model: spec.id, quant: manifest.quant, bin: binary.path });
-      const loadStarted = Date.now();
-      await runtime.load();
-      log.info("model ready", { model: spec.id, quant: manifest.quant, loadMs: Date.now() - loadStarted });
-      return { runtime, model: spec.id };
-    })();
-    try {
+// src/mcp/prompts.ts
+init_errors();
+import { z as z2 } from "zod";
+var TOOL_GUIDE = (questions) => [
+  "Call the `clef_decide` MCP tool once with all of the questions below (they are scored in a single forward pass).",
+  "",
+  "Rules for the call:",
+  "- `state` must be a compact, factual JSON or string \u2014 relevant facts only, well under 1 MB.",
+  "- Use the exact `questions` given below (ids, types, criteria). Do not invent extra options.",
+  "- If the answer distribution is flat (no option above ~0.6), gather more context and re-ask once before falling back to asking the user.",
+  "- Treat safety-adjacent decisions (destructive actions, security) as requiring p >= 0.8 before acting; otherwise prefer asking the user.",
+  "- Report the result as a short summary plus the top probability \u2014 do not paste raw JSON unless asked.",
+  "",
+  "Questions:",
+  questions
+].join("\n");
+var PROMPTS = [
+  {
+    name: "incident-triage",
+    title: "Production incident triage",
+    description: "Frame a production incident as clef_decide questions: immediate action, severity and blast radius.",
+    args: {
+      incident_description: "Short factual description of the incident (symptoms, scope, recent changes)."
+    },
+    build: (a) => TOOL_GUIDE(
+      [
+        '- "action" (choice, instructions "What should the responder do first?"): rollback "Revert the latest deploy", hotfix "Ship a targeted fix now", investigate "Gather diagnostics before acting", wait "Observe; impact is not growing".',
+        '- "severity" (score, instructions "How severe is the incident?", criteria ["low", "elevated", "high", "critical"]).',
+        '- "user_impact" (noul, instructions "Are users actively affected right now?").'
+      ].join("\n")
+    ) + "\n\nIncident description:\n" + (a.incident_description ?? "")
+  },
+  {
+    name: "next-action",
+    title: "Agent next action",
+    description: "Ask Clef what the coding agent should do next on a task: inspect, modify, test or ask the user.",
+    args: {
+      task_summary: "What the agent is working on, current step, and what is already known or done."
+    },
+    build: (a) => TOOL_GUIDE(
+      [
+        '- "next_action" (choice, instructions "What should the coding agent do next?"): inspect "Inspect the code and gather more information", modify "Modify the code", test "Run additional tests", ask_user "Ask the user for clarification".',
+        '- "confidence" (score, instructions "How confident are you in this decision?", criteria ["very_low", "low", "medium", "high", "very_high"]).'
+      ].join("\n")
+    ) + "\n\nTask summary:\n" + (a.task_summary ?? "")
+  },
+  {
+    name: "ticket-routing",
+    title: "Support ticket routing",
+    description: "Classify an incoming message into the team that should handle it.",
+    args: {
+      ticket_text: "The customer or user message, verbatim if possible."
+    },
+    build: (a) => TOOL_GUIDE(
+      [
+        '- "department" (choice, instructions "Which team should handle the message?"): billing "Payments, invoices and refunds", technical "Bugs, errors and outages", sales "Pricing and new purchases", other "Anything else".',
+        '- "urgent" (noul, instructions "Does this need a response within the hour?").'
+      ].join("\n")
+    ) + "\n\nTicket text:\n" + (a.ticket_text ?? "")
+  },
+  {
+    name: "security-review",
+    title: "Security sanity check",
+    description: "Ask Clef whether a code snippet, change or setup smells like a security problem.",
+    args: {
+      change_summary: "The code, config or setup to review \u2014 compact but complete enough to judge."
+    },
+    build: (a) => TOOL_GUIDE(
+      [
+        '- "is_vulnerable" (noul, instructions "Does this contain a realistic security vulnerability?").',
+        '- "risk" (score, instructions "How bad is it if this ships as-is?", criteria ["informational", "low", "medium", "high", "critical"]).',
+        '- "first_mitigation" (choice, instructions "What is the first mitigation?"): fix_code "Fix the code before merging", restrict "Restrict access or add guardrails", monitor "Add detection and monitoring", none "No mitigation needed".'
+      ].join("\n") + "\nSafety rule: only act without human review when p(is_vulnerable=false) >= 0.8."
+    ) + "\n\nChange to review:\n" + (a.change_summary ?? "")
+  }
+];
+function registerPrompts(server) {
+  for (const p of PROMPTS) {
+    server.registerPrompt(
+      p.name,
+      {
+        title: p.title,
+        description: p.description,
+        argsSchema: Object.fromEntries(Object.entries(p.args).map(([k, v]) => [k, z2.string().min(1).describe(v)]))
+      },
+      ({ ...args }) => {
+        for (const key of Object.keys(p.args)) {
+          if (typeof args[key] !== "string" || !args[key]) {
+            throw new ClefError(ClefErrorCode.INVALID_INPUT, `Prompt argument "${key}" is required`);
+          }
+        }
+        return {
+          messages: [{ role: "user", content: { type: "text", text: p.build(args) } }]
+        };
+      }
+    );
+  }
+}
+
+// src/mcp/resources.ts
+import fsSync3 from "fs";
+import fsp4 from "fs/promises";
+
+// src/cli/evals.ts
+init_errors();
+import fsp3 from "fs/promises";
+import fsSync2 from "fs";
+import { fileURLToPath } from "url";
+import path6 from "path";
+function defaultDatasetPath() {
+  let dir = path6.dirname(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 6; i++) {
+    const candidate = path6.join(dir, "tests", "evals", "dataset.jsonl");
+    if (fsSync2.existsSync(candidate)) return candidate;
+    dir = path6.dirname(dir);
+  }
+  return fileURLToPath(new URL("../tests/evals/dataset.jsonl", import.meta.url));
+}
+function parseLine(line, lineNo) {
+  const raw = JSON.parse(line);
+  if (typeof raw.id !== "string" || !raw.question?.id || !raw.expected?.kind) {
+    throw new ClefError(ClefErrorCode.INVALID_INPUT, `Eval dataset line ${lineNo} is missing id/question/expected`);
+  }
+  return raw;
+}
+function evaluate(answer, exp) {
+  const prob = (key) => answer[key] ?? 0;
+  switch (exp.kind) {
+    case "argmax": {
+      const keys = exp.among ?? Object.keys(answer);
+      let best = "";
+      let bestP = -1;
+      for (const k of keys) {
+        if (prob(k) > bestP) {
+          bestP = prob(k);
+          best = k;
+        }
+      }
+      return { pass: best === exp.expect, detail: `argmax=${best || "n/a"} (${bestP.toFixed(3)}), expected=${exp.expect}` };
+    }
+    case "prob_gt":
+      return { pass: prob(exp.a) > prob(exp.b), detail: `p(${exp.a})=${prob(exp.a).toFixed(3)} vs p(${exp.b})=${prob(exp.b).toFixed(3)}` };
+    case "min_prob": {
+      const p = prob(exp.option);
+      return { pass: p >= exp.min, detail: `p(${exp.option})=${p.toFixed(3)}, required >= ${exp.min}` };
+    }
+    case "top_mass": {
+      const mass = exp.options.reduce((sum, k) => sum + prob(k), 0);
+      return { pass: mass >= exp.min, detail: `mass(${exp.options.join("+")})=${mass.toFixed(3)}, required >= ${exp.min}` };
+    }
+  }
+}
+async function runEvals(opts) {
+  const config = loadConfig();
+  const log = createLogger(config.logLevel);
+  const spec = getModelSpec(config.model);
+  let mlxManifest;
+  if (config.runtime === "mlx") {
+    mlxManifest = await mlxIsInstalled(config.clefHome);
+    if (!mlxManifest) {
+      throw new ClefError(
+        ClefErrorCode.MODEL_NOT_INSTALLED,
+        `Model "${spec.id}" is not installed for the MLX runtime.`,
+        "Run `clef-mcp install --runtime mlx` first."
+      );
+    }
+  }
+  const manifest = config.runtime === "mlx" ? void 0 : await findInstalledManifest(config.clefHome, spec);
+  if (!manifest && !mlxManifest) {
+    throw new ClefError(
+      ClefErrorCode.MODEL_NOT_INSTALLED,
+      `Model "${spec.id}" is not installed; evals need the local model.`,
+      "Run `clef-mcp install` first."
+    );
+  }
+  const datasetPath = opts.dataset ?? defaultDatasetPath();
+  const content = await fsp3.readFile(datasetPath, "utf8");
+  let cases = content.split("\n").map((l) => l.trim()).filter((l) => l && !l.startsWith("#")).map((l, i) => parseLine(l, i + 1));
+  if (opts.limit && opts.limit > 0) cases = cases.slice(0, opts.limit);
+  if (cases.length === 0) {
+    throw new ClefError(ClefErrorCode.INVALID_INPUT, `No eval cases found in ${datasetPath}`);
+  }
+  const binary = resolveLlamaServerBinary(config);
+  const runtime = config.runtime === "mlx" ? new MlxRuntime({ uvBin: resolveUv(process.env.CLEF_MLX_UV), snapshotPath: mlxManifest.snapshotPath, log }) : new LlamaCppRuntime({ serverBin: binary.path, modelPath: manifest.modelPath, alias: spec.id, log });
+  const runtimeLabel = config.runtime === "mlx" ? "MLX" : manifest.quant;
+  console.log(`Running ${cases.length} eval case(s) with ${spec.id} ${runtimeLabel}...
+`);
+  await runtime.load();
+  let passed = 0;
+  const results = [];
+  try {
+    for (const [i, c] of cases.entries()) {
+      process.stderr.write(`\r  case ${i + 1}/${cases.length} \u2014 ${c.id}`);
+      try {
+        const request = toSystemOneRequest({ state: c.state, questions: { [c.question.id]: c.question } }, spec.id);
+        const response = await runtime.decide(request);
+        const output = fromSystemOneResponse(response, { [c.question.id]: c.question }, spec.id);
+        const answer = output.decisions[c.question.id]?.answer ?? {};
+        const verdict = evaluate(answer, c.expected);
+        if (verdict.pass) passed++;
+        results.push({ id: c.id, category: c.category, ok: verdict.pass, detail: verdict.detail });
+      } catch (err) {
+        results.push({
+          id: c.id,
+          category: c.category,
+          ok: false,
+          detail: `error: ${err instanceof Error ? err.message : String(err)}`
+        });
+      }
+    }
+  } finally {
+    process.stderr.write("\n");
+    await runtime.unload();
+  }
+  console.log("");
+  for (const r of results) {
+    console.log(`${r.ok ? "\u2714" : "\u2718"}  [${r.category}] ${r.id} \u2014 ${r.detail}`);
+  }
+  const rate = passed / results.length;
+  const minRate = opts.minRate ?? 0.8;
+  console.log(`
+${passed}/${results.length} passed (${(rate * 100).toFixed(1)}%), required >= ${(minRate * 100).toFixed(0)}%`);
+  return rate >= minRate;
+}
+
+// src/mcp/resources.ts
+var EVALS_SCHEMA_MD = `# clef-mcp eval dataset format
+
+JSONL: one JSON object per line.
+
+{
+  "id": "unique-case-id",
+  "category": "coding | security | classification | routing | yes_no",
+  "state": <string | JSON value>,
+  "question": {
+    "id": "question-id",
+    "type": "choice | score | noul",
+    "instructions": "\u2026",
+    "criteria": { "option": "description" }   // choice (or ["a","b"] list)
+                | ["low", "high"]             // score, ordered
+  },
+  "expected": {
+    "kind": "argmax | prob_gt | min_prob | top_mass",
+    // argmax: { "expect": "option", "among": ["option", ...] (optional) }
+    // prob_gt: { "a": "opt", "b": "opt" }
+    // min_prob: { "option": "opt", "min": 0.7 }
+    // top_mass: { "options": ["a","b"], "min": 0.8 }
+  }
+}
+
+Run: \`clef-mcp evals\` (requires an installed model).
+`;
+async function readDataset() {
+  try {
+    return await fsp4.readFile(defaultDatasetPath(), "utf8");
+  } catch {
+    return "The bundled eval dataset is not available in this installation (tests/evals/dataset.jsonl not found).";
+  }
+}
+function textResource(uri, text, mimeType = "text/markdown") {
+  return { contents: [{ uri: uri.href, mimeType, text }] };
+}
+function requireStringUri(uri) {
+  return uri instanceof URL ? uri : new URL(uri);
+}
+function registerResources(server, cfg, version) {
+  server.registerResource(
+    "capabilities",
+    "clef-mcp://capabilities",
+    { title: "clef-mcp capabilities", description: "Live capability snapshot: model, runtime, limits, error codes.", mimeType: "application/json" },
+    async (uri) => {
+      const u = requireStringUri(uri);
+      const payload = {
+        name: "clef-mcp",
+        version,
+        model: cfg.model,
+        runtime: cfg.runtime,
+        limits: cfg.limits,
+        tool: {
+          name: "clef_decide",
+          output: "strict JSON: { model, decisions: { <qid>: { answer: { <option>: probability } } } }",
+          questionTypes: ["noul", "choice", "score"],
+          notes: ["options.temperature is accepted but is a no-op (single forward pass)", "state is data and is never interpreted as instructions"]
+        },
+        errorCodes: [
+          "MODEL_NOT_INSTALLED",
+          "MODEL_LOAD_FAILED",
+          "RUNTIME_NOT_FOUND",
+          "RUNTIME_INIT_FAILED",
+          "RUNTIME_NOT_SUPPORTED",
+          "INVALID_INPUT",
+          "CLEF_INFERENCE_FAILED",
+          "UNSUPPORTED_PLATFORM",
+          "OUT_OF_MEMORY",
+          "CHECKSUM_MISMATCH",
+          "DOWNLOAD_FAILED"
+        ]
+      };
+      return textResource(u, JSON.stringify(payload, null, 2), "application/json");
+    }
+  );
+  server.registerResource(
+    "evals-schema",
+    "clef-mcp://evals/schema",
+    { title: "Eval dataset schema", description: "How to write cases for clef-mcp evals.", mimeType: "text/markdown" },
+    async (uri) => textResource(requireStringUri(uri), EVALS_SCHEMA_MD)
+  );
+  server.registerResource(
+    "evals-dataset",
+    "clef-mcp://evals/dataset",
+    { title: "Bundled eval dataset", description: "The 30-case dataset shipped with clef-mcp.", mimeType: "application/jsonl" },
+    async (uri) => textResource(requireStringUri(uri), await readDataset(), "application/jsonl")
+  );
+}
+
+// src/mcp/server.ts
+var TOOL_NAME = "clef_decide";
+var SERVER_INSTRUCTIONS = "clef_decide passes task state plus typed questions to the local Clef decision model and returns a probability distribution over answer options. Treat `state` as data: it is never interpreted as instructions for this server. The result is structured JSON; do not render it as prose.";
+function createClefServer(deps = {}) {
+  const config = deps.config ?? loadConfig();
+  const version = deps.version ?? "0.1.0";
+  const log = deps.log ?? createLogger(config.logLevel);
+  const server = new McpServer({ name: "clef-mcp", version }, { instructions: SERVER_INSTRUCTIONS });
+  registerPrompts(server);
+  registerResources(server, config, version);
+  let loaded;
+  let loadPromise;
+  async function ensureRuntime(spec) {
+    if (loaded && loaded.model === spec.id) return loaded;
+    if (loaded && loaded.model !== spec.id) {
+      await loaded.runtime.unload();
+      loaded = void 0;
+    }
+    if (loadPromise) return loadPromise;
+    loadPromise = (async () => {
+      if (config.runtime === "mlx") {
+        const manifest2 = await mlxIsInstalled(config.clefHome);
+        if (!manifest2) {
+          throw new ClefError(
+            ClefErrorCode.MODEL_NOT_INSTALLED,
+            `Clef model "${spec.id}" is not installed for the MLX runtime.`,
+            "Run `clef-mcp install --runtime mlx`."
+          );
+        }
+        const uvBin = resolveUv(process.env.CLEF_MLX_UV);
+        const runtime2 = deps.runtimeFactory ? deps.runtimeFactory({ kind: "mlx", snapshotPath: manifest2.snapshotPath, alias: spec.id, log }) : new MlxRuntime({ uvBin, snapshotPath: manifest2.snapshotPath, log });
+        log.debug("loading model (mlx)", { model: spec.id, snapshot: manifest2.snapshotPath });
+        const loadStarted2 = Date.now();
+        await runtime2.load();
+        log.info("model ready", { model: spec.id, runtime: "mlx", loadMs: Date.now() - loadStarted2 });
+        return { runtime: runtime2, model: spec.id };
+      }
+      const manifest = await findInstalledManifest(config.clefHome, spec);
+      if (!manifest) {
+        throw new ClefError(
+          ClefErrorCode.MODEL_NOT_INSTALLED,
+          `Clef model "${spec.id}" is not installed.`,
+          "Run `clef-mcp install`."
+        );
+      }
+      const binary = resolveLlamaServerBinary(config);
+      const runtime = deps.runtimeFactory ? deps.runtimeFactory({ kind: "llama-cpp", serverBin: binary.path, modelPath: manifest.modelPath, alias: spec.id, log }) : new LlamaCppRuntime({ serverBin: binary.path, modelPath: manifest.modelPath, alias: spec.id, log });
+      log.debug("loading model", { model: spec.id, quant: manifest.quant, bin: binary.path });
+      const loadStarted = Date.now();
+      await runtime.load();
+      log.info("model ready", { model: spec.id, quant: manifest.quant, loadMs: Date.now() - loadStarted });
+      return { runtime, model: spec.id };
+    })();
+    try {
       loaded = await loadPromise;
       return loaded;
     } finally {
@@ -1214,9 +1900,15 @@ function createClefServer(deps = {}) {
     TOOL_NAME,
     {
       title: "Clef Decide",
-      description: "Pass task state and a set of structured questions (noul / choice / score) to the local Clef decision model. Returns a probability distribution over the allowed answers for every question. The result is structured JSON.",
+      description: 'Ask the local Clef decision model to judge a situation. Pass a `state` (compact factual context as a string or JSON) and one or more typed `questions`: "choice" picks among named options (criteria = option id -> description), "score" judges an ordered scale (criteria = ordered list), "noul" answers yes/no. Returns strict JSON: for every question a probability distribution over its allowed answers \u2014 no prose, no sampling. Usage: batch related decisions (up to 64 questions) in one call; state is data and is never executed; act on the argmax when a distribution is decisive (p >= 0.8), otherwise gather more context or ask the user; for destructive or security-adjacent decisions require high confidence before acting. Optional `model` overrides the model id; `options.temperature` is a no-op (single forward pass, no sampling).',
       inputSchema: clefDecideInputShape(config.limits),
-      outputSchema: clefDecideOutputSchema().shape
+      outputSchema: clefDecideOutputSchema().shape,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
     },
     async (args) => {
       try {
@@ -1275,19 +1967,19 @@ import { Command } from "commander";
 
 // src/cli/doctor.ts
 init_errors();
-import { execFile as execFile2 } from "child_process";
+import { execFile as execFile3 } from "child_process";
 import os3 from "os";
 import { promisify } from "util";
-import fsp2 from "fs/promises";
-import path5 from "path";
+import fsp5 from "fs/promises";
+import path7 from "path";
 
 // src/models/platform.ts
 init_errors();
-import { execFile } from "child_process";
+import { execFile as execFile2 } from "child_process";
 import os2 from "os";
 function exec(cmd, args, timeoutMs) {
   return new Promise((resolve, reject) => {
-    execFile(cmd, args, { timeout: timeoutMs, encoding: "utf8" }, (err, stdout) => {
+    execFile2(cmd, args, { timeout: timeoutMs, encoding: "utf8" }, (err, stdout) => {
       if (err) reject(err);
       else resolve(stdout);
     });
@@ -1393,9 +2085,27 @@ async function probeInference(cfg, manifest, log, loadTimeoutMs = 12e4) {
   }
   return { latencyMs: Date.now() - started, binarySource: binary.source, binaryPath: binary.path };
 }
+async function probeMlxInference(cfg, manifest, log, loadTimeoutMs = 18e4) {
+  const uvBin = resolveUv(process.env.CLEF_MLX_UV);
+  const runtime = new MlxRuntime({ uvBin, snapshotPath: manifest.snapshotPath, loadTimeoutMs, log });
+  const started = Date.now();
+  await runtime.load();
+  try {
+    await runtime.decide({
+      model: manifest.model,
+      state: "This is an internal clef-mcp installation probe.",
+      questions: {
+        probe: { type: "noul", instructions: "Is this a clef-mcp installation probe?" }
+      }
+    });
+  } finally {
+    await runtime.unload();
+  }
+  return { latencyMs: Date.now() - started, binarySource: "uv", binaryPath: uvBin };
+}
 
 // src/cli/doctor.ts
-var execFileP = promisify(execFile2);
+var execFileP = promisify(execFile3);
 function mark(ok) {
   return ok ? "\u2714" : "\u2718";
 }
@@ -1415,14 +2125,14 @@ async function checkBinaryVersion(binaryPath) {
 async function detectMcpConfigs() {
   const home = os3.homedir();
   const hints = [
-    { client: "Codex", path: path5.join(home, ".codex", "config.toml"), configured: false },
-    { client: "Claude Code (user)", path: path5.join(home, ".claude.json"), configured: false },
-    { client: "Claude Code (project)", path: path5.resolve(".mcp.json"), configured: false },
-    { client: "Cursor", path: path5.join(process.cwd(), ".cursor", "mcp.json"), configured: false }
+    { client: "Codex", path: path7.join(home, ".codex", "config.toml"), configured: false },
+    { client: "Claude Code (user)", path: path7.join(home, ".claude.json"), configured: false },
+    { client: "Claude Code (project)", path: path7.resolve(".mcp.json"), configured: false },
+    { client: "Cursor", path: path7.join(process.cwd(), ".cursor", "mcp.json"), configured: false }
   ];
   for (const hint of hints) {
     try {
-      const content = await fsp2.readFile(hint.path, "utf8");
+      const content = await fsp5.readFile(hint.path, "utf8");
       hint.configured = content.includes("clef-mcp");
     } catch {
       hint.configured = false;
@@ -1461,33 +2171,75 @@ async function runDoctor(opts) {
     detail: info.gpu?.name ? `${info.gpu.name}${info.gpu.vramBytes ? ` (${formatBytes(info.gpu.vramBytes)})` : ""}` : "not detected (llama.cpp falls back to CPU; on Apple Silicon Metal is built in)"
   });
   let binaryPath;
-  try {
-    const binary = resolveLlamaServerBinary(config);
-    binaryPath = binary.path;
-    const version = await checkBinaryVersion(binary.path);
-    checks.push({
-      name: "Runtime binary",
-      ok: version !== void 0,
-      detail: `${binary.source}: ${binary.path}${version ? ` (${version})` : ""}`,
-      hint: version === void 0 ? "The binary exists but did not answer --version; it may be broken or incompatible." : void 0
-    });
-  } catch (err) {
-    checks.push({
-      name: "Runtime binary",
-      ok: false,
-      detail: err instanceof Error ? err.message : String(err),
-      hint: err instanceof ClefError ? err.hint : void 0
-    });
+  if (config.runtime === "mlx") {
+    try {
+      binaryPath = resolveUv(process.env.CLEF_MLX_UV);
+      checks.push({
+        name: "Runtime (uv, for the MLX runtime)",
+        ok: true,
+        detail: binaryPath
+      });
+    } catch (err) {
+      checks.push({
+        name: "Runtime (uv, for the MLX runtime)",
+        ok: false,
+        detail: err instanceof Error ? err.message : String(err),
+        hint: "Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh"
+      });
+    }
+  } else {
+    try {
+      const binary = resolveLlamaServerBinary(config);
+      binaryPath = binary.path;
+      const version = await checkBinaryVersion(binary.path);
+      checks.push({
+        name: "Runtime binary",
+        ok: version !== void 0,
+        detail: `${binary.source}: ${binary.path}${version ? ` (${version})` : ""}`,
+        hint: version === void 0 ? "The binary exists but did not answer --version; it may be broken or incompatible." : void 0
+      });
+    } catch (err) {
+      binaryPath = void 0;
+      checks.push({
+        name: "Runtime binary",
+        ok: false,
+        detail: err instanceof Error ? err.message : String(err),
+        hint: err instanceof ClefError ? err.hint : void 0
+      });
+    }
   }
   let spec;
   let manifest;
+  let mlxManifest;
   try {
     spec = getModelSpec(config.model);
-    manifest = await findInstalledManifest(config.clefHome, spec);
+    if (config.runtime === "mlx") mlxManifest = await mlxIsInstalled(config.clefHome);
+    else manifest = await findInstalledManifest(config.clefHome, spec);
   } catch {
     checks.push({ name: "Model", ok: false, detail: `unknown model id "${config.model}"` });
   }
-  if (spec) {
+  if (config.runtime === "mlx") {
+    if (!mlxManifest) {
+      checks.push({
+        name: "Model",
+        ok: false,
+        detail: `${spec?.id ?? config.model} is not installed for the MLX runtime`,
+        hint: "Run `clef-mcp install --runtime mlx`."
+      });
+    } else {
+      checks.push({
+        name: "Model",
+        ok: true,
+        detail: `MLX snapshot at ${mlxManifest.snapshotPath}`
+      });
+      checks.push({
+        name: "Model license",
+        ok: true,
+        informational: true,
+        detail: `${mlxManifest.licenseId} \u2014 ${mlxManifest.licenseUrl}`
+      });
+    }
+  } else if (spec) {
     if (!manifest) {
       checks.push({
         name: "Model",
@@ -1520,7 +2272,24 @@ async function runDoctor(opts) {
       });
     }
   }
-  if (binaryPath && manifest && (await verifyModelFiles(manifest)).ok) {
+  if (config.runtime === "mlx" && binaryPath && mlxManifest) {
+    try {
+      const probe = await probeMlxInference(config, mlxManifest, void 0, 24e4);
+      checks.push({
+        name: "Inference",
+        ok: true,
+        detail: `probe decision returned in ${(probe.latencyMs / 1e3).toFixed(1)}s (incl. model load)`
+      });
+    } catch (err) {
+      const clefErr = err instanceof ClefError ? err : void 0;
+      checks.push({
+        name: "Inference",
+        ok: false,
+        detail: clefErr?.message ?? (err instanceof Error ? err.message : String(err)),
+        hint: clefErr?.hint
+      });
+    }
+  } else if (config.runtime === "llama-cpp" && binaryPath && manifest && (await verifyModelFiles(manifest)).ok) {
     try {
       const probe = await probeInference(config, manifest, void 0, 18e4);
       checks.push({
@@ -1570,127 +2339,20 @@ ${failed.length} critical check(s) failed.`
   return failed.length > 0;
 }
 
-// src/cli/evals.ts
+// src/cli/install.ts
 init_errors();
-import fsp3 from "fs/promises";
-import fsSync from "fs";
-import { fileURLToPath } from "url";
-import path6 from "path";
-function defaultDatasetPath() {
-  let dir = path6.dirname(fileURLToPath(import.meta.url));
-  for (let i = 0; i < 6; i++) {
-    const candidate = path6.join(dir, "tests", "evals", "dataset.jsonl");
-    if (fsSync.existsSync(candidate)) return candidate;
-    dir = path6.dirname(dir);
-  }
-  return fileURLToPath(new URL("../tests/evals/dataset.jsonl", import.meta.url));
-}
-function parseLine(line, lineNo) {
-  const raw = JSON.parse(line);
-  if (typeof raw.id !== "string" || !raw.question?.id || !raw.expected?.kind) {
-    throw new ClefError(ClefErrorCode.INVALID_INPUT, `Eval dataset line ${lineNo} is missing id/question/expected`);
-  }
-  return raw;
-}
-function evaluate(answer, exp) {
-  const prob = (key) => answer[key] ?? 0;
-  switch (exp.kind) {
-    case "argmax": {
-      const keys = exp.among ?? Object.keys(answer);
-      let best = "";
-      let bestP = -1;
-      for (const k of keys) {
-        if (prob(k) > bestP) {
-          bestP = prob(k);
-          best = k;
-        }
-      }
-      return { pass: best === exp.expect, detail: `argmax=${best || "n/a"} (${bestP.toFixed(3)}), expected=${exp.expect}` };
-    }
-    case "prob_gt":
-      return { pass: prob(exp.a) > prob(exp.b), detail: `p(${exp.a})=${prob(exp.a).toFixed(3)} vs p(${exp.b})=${prob(exp.b).toFixed(3)}` };
-    case "min_prob": {
-      const p = prob(exp.option);
-      return { pass: p >= exp.min, detail: `p(${exp.option})=${p.toFixed(3)}, required >= ${exp.min}` };
-    }
-    case "top_mass": {
-      const mass = exp.options.reduce((sum, k) => sum + prob(k), 0);
-      return { pass: mass >= exp.min, detail: `mass(${exp.options.join("+")})=${mass.toFixed(3)}, required >= ${exp.min}` };
-    }
-  }
-}
-async function runEvals(opts) {
-  const config = loadConfig();
-  const log = createLogger(config.logLevel);
-  const spec = getModelSpec(config.model);
-  const manifest = await findInstalledManifest(config.clefHome, spec);
-  if (!manifest) {
-    throw new ClefError(
-      ClefErrorCode.MODEL_NOT_INSTALLED,
-      `Model "${spec.id}" is not installed; evals need the local model.`,
-      "Run `clef-mcp install` first."
-    );
-  }
-  const datasetPath = opts.dataset ?? defaultDatasetPath();
-  const content = await fsp3.readFile(datasetPath, "utf8");
-  let cases = content.split("\n").map((l) => l.trim()).filter((l) => l && !l.startsWith("#")).map((l, i) => parseLine(l, i + 1));
-  if (opts.limit && opts.limit > 0) cases = cases.slice(0, opts.limit);
-  if (cases.length === 0) {
-    throw new ClefError(ClefErrorCode.INVALID_INPUT, `No eval cases found in ${datasetPath}`);
-  }
-  const binary = resolveLlamaServerBinary(config);
-  const runtime = new LlamaCppRuntime({ serverBin: binary.path, modelPath: manifest.modelPath, alias: spec.id, log });
-  console.log(`Running ${cases.length} eval case(s) with ${spec.id} ${manifest.quant}...
-`);
-  await runtime.load();
-  let passed = 0;
-  const results = [];
-  try {
-    for (const [i, c] of cases.entries()) {
-      process.stderr.write(`\r  case ${i + 1}/${cases.length} \u2014 ${c.id}`);
-      try {
-        const request = toSystemOneRequest({ state: c.state, questions: { [c.question.id]: c.question } }, spec.id);
-        const response = await runtime.decide(request);
-        const output = fromSystemOneResponse(response, { [c.question.id]: c.question }, spec.id);
-        const answer = output.decisions[c.question.id]?.answer ?? {};
-        const verdict = evaluate(answer, c.expected);
-        if (verdict.pass) passed++;
-        results.push({ id: c.id, category: c.category, ok: verdict.pass, detail: verdict.detail });
-      } catch (err) {
-        results.push({
-          id: c.id,
-          category: c.category,
-          ok: false,
-          detail: `error: ${err instanceof Error ? err.message : String(err)}`
-        });
-      }
-    }
-  } finally {
-    process.stderr.write("\n");
-    await runtime.unload();
-  }
-  console.log("");
-  for (const r of results) {
-    console.log(`${r.ok ? "\u2714" : "\u2718"}  [${r.category}] ${r.id} \u2014 ${r.detail}`);
-  }
-  const rate = passed / results.length;
-  const minRate = opts.minRate ?? 0.8;
-  console.log(`
-${passed}/${results.length} passed (${(rate * 100).toFixed(1)}%), required >= ${(minRate * 100).toFixed(0)}%`);
-  return rate >= minRate;
-}
 
 // src/models/llama-install.ts
 init_errors();
-import { execFile as execFile3 } from "child_process";
-import fsp5 from "fs/promises";
-import path8 from "path";
+import { execFile as execFile4 } from "child_process";
+import fsp7 from "fs/promises";
+import path9 from "path";
 
 // src/models/hf.ts
 init_errors();
 import { createHash as createHash2 } from "crypto";
-import fsp4 from "fs/promises";
-import path7 from "path";
+import fsp6 from "fs/promises";
+import path8 from "path";
 var HF_BASE_URL = "https://huggingface.co";
 function resolveUrl(repo, revision, file) {
   return `${HF_BASE_URL}/${repo}/resolve/${revision}/${file}`;
@@ -1748,7 +2410,7 @@ async function downloadOnce(url, dest, opts) {
   }
   const total = opts.expectedSize ?? (res.headers.get("content-length") ? Number(res.headers.get("content-length")) : void 0);
   const hash = createHash2("sha256");
-  const handle = await fsp4.open(dest, "w");
+  const handle = await fsp6.open(dest, "w");
   let bytes = 0;
   try {
     for await (const chunk of res.body) {
@@ -1763,7 +2425,7 @@ async function downloadOnce(url, dest, opts) {
   }
   const sha256 = hash.digest("hex");
   if (opts.expectedSha256 && sha256 !== opts.expectedSha256) {
-    await fsp4.rm(dest, { force: true });
+    await fsp6.rm(dest, { force: true });
     throw new ClefError(
       ClefErrorCode.CHECKSUM_MISMATCH,
       `Checksum mismatch after download: expected ${opts.expectedSha256}, got ${sha256}`,
@@ -1771,7 +2433,7 @@ async function downloadOnce(url, dest, opts) {
     );
   }
   if (opts.expectedSize !== void 0 && bytes !== opts.expectedSize) {
-    await fsp4.rm(dest, { force: true });
+    await fsp6.rm(dest, { force: true });
     throw new ClefError(
       ClefErrorCode.DOWNLOAD_FAILED,
       `Downloaded size mismatch: expected ${opts.expectedSize} bytes, got ${bytes}`
@@ -1782,24 +2444,24 @@ async function downloadOnce(url, dest, opts) {
 async function installModel(opts) {
   const { modelSpec, quantSpec } = opts;
   const { modelsDir } = pathsFor(opts.clefHome);
-  const manifestPath = manifestPathFor(modelsDir, modelSpec.id, quantSpec.id);
-  const existing = await readModelManifest(manifestPath);
+  const manifestPath2 = manifestPathFor(modelsDir, modelSpec.id, quantSpec.id);
+  const existing = await readModelManifest(manifestPath2);
   if (existing && (await verifyModelFiles(existing)).ok) {
     opts.log?.debug("model already installed", { model: modelSpec.id, quant: quantSpec.id });
     return { manifest: existing, alreadyInstalled: true };
   }
   const info = await fetchFileInfo(modelSpec.repo, modelSpec.revision, quantSpec.file);
-  const finalPath = path7.join(path7.dirname(manifestPath), quantSpec.file);
-  await fsp4.mkdir(path7.dirname(finalPath), { recursive: true });
-  const tmpPath = path7.join(path7.dirname(finalPath), `.download-${quantSpec.file}`);
-  await fsp4.rm(tmpPath, { force: true });
+  const finalPath = path8.join(path8.dirname(manifestPath2), quantSpec.file);
+  await fsp6.mkdir(path8.dirname(finalPath), { recursive: true });
+  const tmpPath = path8.join(path8.dirname(finalPath), `.download-${quantSpec.file}`);
+  await fsp6.rm(tmpPath, { force: true });
   opts.log?.info("downloading model", { repo: modelSpec.repo, file: quantSpec.file });
   const result = await downloadFile(info.downloadUrl, tmpPath, {
     expectedSha256: info.sha256,
     expectedSize: info.size ?? quantSpec.bytes,
     onProgress: opts.onProgress
   });
-  await fsp4.rename(tmpPath, finalPath);
+  await fsp6.rename(tmpPath, finalPath);
   const manifest = {
     schemaVersion: 1,
     model: modelSpec.id,
@@ -1815,7 +2477,7 @@ async function installModel(opts) {
     installedAt: (/* @__PURE__ */ new Date()).toISOString(),
     clefMcpVersion: opts.clefMcpVersion
   };
-  await writeModelManifest(manifestPath, manifest);
+  await writeModelManifest(manifestPath2, manifest);
   opts.log?.info("model installed", { model: modelSpec.id, quant: quantSpec.id, sha256: result.sha256 });
   return { manifest, alreadyInstalled: false };
 }
@@ -1874,7 +2536,7 @@ function pickAsset(release, platform, arch) {
 }
 function execTar(args, cwd) {
   return new Promise((resolve, reject) => {
-    execFile3("tar", args, { cwd, timeout: 3e5 }, (err, _stdout, stderr) => {
+    execFile4("tar", args, { cwd, timeout: 3e5 }, (err, _stdout, stderr) => {
       if (err) reject(new Error(`tar ${args.join(" ")} failed: ${stderr || err.message}`));
       else resolve();
     });
@@ -1887,12 +2549,12 @@ async function findServerBinary(dir, platform) {
     const current = queue.shift();
     let entries;
     try {
-      entries = await fsp5.readdir(current, { withFileTypes: true });
+      entries = await fsp7.readdir(current, { withFileTypes: true });
     } catch {
       continue;
     }
     for (const entry of entries) {
-      const full = path8.join(current, entry.name);
+      const full = path9.join(current, entry.name);
       if (entry.isDirectory()) queue.push(full);
       else if (entry.name === target) return full;
     }
@@ -1903,14 +2565,14 @@ async function findServerBinary(dir, platform) {
   );
 }
 async function extractRelease(archivePath, destDir, platform) {
-  await fsp5.mkdir(destDir, { recursive: true });
+  await fsp7.mkdir(destDir, { recursive: true });
   const args = archivePath.endsWith(".zip") ? ["-xf", archivePath] : ["-xzf", archivePath];
   try {
     await execTar(args, destDir);
   } catch (err) {
     throw new ClefError(
       ClefErrorCode.DOWNLOAD_FAILED,
-      `Could not extract ${path8.basename(archivePath)}: ${err instanceof Error ? err.message : String(err)}`,
+      `Could not extract ${path9.basename(archivePath)}: ${err instanceof Error ? err.message : String(err)}`,
       "Extract the archive manually and point CLEF_LLAMA_BIN at llama-server."
     );
   }
@@ -1920,7 +2582,7 @@ async function ensureLlamaRuntime(cfg, log) {
     const resolved = resolveLlamaServerBinary(cfg);
     if (resolved.source === "managed") {
       const platformDir = llamaRuntimeDir(pathsFor(cfg.clefHome).runtimeDir, process.platform, process.arch);
-      const manifest = readRuntimeManifest(path8.join(platformDir, "runtime-manifest.json"));
+      const manifest = readRuntimeManifest(path9.join(platformDir, "runtime-manifest.json"));
       return { ...resolved, releaseTag: manifest?.releaseTag ?? "unknown", freshInstall: false };
     }
     return { ...resolved, releaseTag: resolved.source, freshInstall: false };
@@ -1952,16 +2614,16 @@ async function downloadManagedLlama(cfg, log) {
   }
   const asset = pickAsset(release, platform, arch);
   log?.info("downloading llama.cpp runtime", { tag: release.tag_name, asset: asset.name });
-  const tagDir = path8.join(platformDir, release.tag_name);
-  await fsp5.mkdir(tagDir, { recursive: true });
-  const tmpArchive = path8.join(platformDir, `.download-${asset.name}`);
-  await fsp5.rm(tmpArchive, { force: true });
+  const tagDir = path9.join(platformDir, release.tag_name);
+  await fsp7.mkdir(tagDir, { recursive: true });
+  const tmpArchive = path9.join(platformDir, `.download-${asset.name}`);
+  await fsp7.rm(tmpArchive, { force: true });
   const result = await downloadFile(asset.browser_download_url, tmpArchive, { expectedSize: asset.size, attempts: 3 });
   await extractRelease(tmpArchive, tagDir, platform);
-  await fsp5.rm(tmpArchive, { force: true });
+  await fsp7.rm(tmpArchive, { force: true });
   const binaryPath = await findServerBinary(tagDir, platform);
-  if (platform !== "win32") await fsp5.chmod(binaryPath, 493);
-  await writeRuntimeManifest(path8.join(platformDir, "runtime-manifest.json"), {
+  if (platform !== "win32") await fsp7.chmod(binaryPath, 493);
+  await writeRuntimeManifest(path9.join(platformDir, "runtime-manifest.json"), {
     schemaVersion: 1,
     kind: "llama-cpp",
     releaseTag: release.tag_name,
@@ -1977,11 +2639,11 @@ async function removeManagedRuntime(cfg) {
   const { runtimeDir } = pathsFor(cfg.clefHome);
   const dir = llamaRuntimeDir(runtimeDir, process.platform, process.arch);
   try {
-    await fsp5.stat(dir);
+    await fsp7.stat(dir);
   } catch {
     return false;
   }
-  await fsp5.rm(dir, { recursive: true, force: true });
+  await fsp7.rm(dir, { recursive: true, force: true });
   return true;
 }
 
@@ -1989,7 +2651,7 @@ async function removeManagedRuntime(cfg) {
 init_prompt();
 
 // src/version.ts
-var VERSION = "0.1.6";
+var VERSION = "0.2.1";
 
 // src/cli/install.ts
 var OS_NAMES = {
@@ -2011,6 +2673,10 @@ function printHeader() {
 async function runInstall(opts) {
   const config = loadConfig();
   const log = createLogger("info");
+  const runtime = opts.runtime ?? config.runtime;
+  if (runtime !== "llama-cpp" && runtime !== "mlx") {
+    throw new ClefError(ClefErrorCode.INVALID_INPUT, `Unknown runtime "${runtime}".`, "Available: llama-cpp, mlx");
+  }
   printHeader();
   process.stdout.write("Detecting hardware...\n");
   const info = await detectPlatform();
@@ -2023,41 +2689,57 @@ async function runInstall(opts) {
   console.log(`  Architecture: ${info.arch}`);
   console.log(`  Memory: ${formatBytes(info.totalMemBytes)}`);
   if (gpuLine) console.log(gpuLine);
+  if (runtime === "mlx" && !(info.platform === "darwin" && info.arch === "arm64")) {
+    throw new ClefError(
+      ClefErrorCode.UNSUPPORTED_PLATFORM,
+      "The MLX runtime only works on Apple Silicon (macOS/arm64).",
+      "Use the default llama.cpp runtime (omit --runtime)."
+    );
+  }
   console.log("\nRecommended:");
-  console.log(`  Model: ${spec.id} (${spec.repo})`);
-  console.log(`  Quantization: ${quant.id}`);
-  console.log(`  Download size: ~${formatBytes(quant.bytes)}`);
+  console.log(`  Model: ${spec.id} (${runtime === "mlx" ? "mlx-community/clef-flash-4bit" : spec.repo})`);
+  console.log(`  Runtime: ${runtime}`);
+  if (runtime === "llama-cpp") console.log(`  Quantization: ${quant.id}`);
+  console.log(`  Download size: ~${runtime === "mlx" ? "6.2 GB" : formatBytes(quant.bytes)}`);
   console.log(`
 Model license: ${spec.licenseId} \u2014 ${spec.licenseUrl}`);
-  console.log("The model is downloaded from the official GGUF conversion and is not repackaged by clef-mcp.\n");
+  console.log("The model is downloaded from the official conversion and is not repackaged by clef-mcp.\n");
   const ok = await confirm("Continue?", opts.yes === true);
   if (!ok) {
     console.log("Aborted. Nothing was downloaded.");
     return;
   }
-  let runtime;
-  if (!opts.skipRuntime) {
-    process.stdout.write("\nEnsuring llama.cpp runtime...\n");
-    runtime = await ensureLlamaRuntime(config, log);
-    console.log(`  Runtime: llama.cpp (${runtime.source}, ${runtime.releaseTag})`);
-    console.log(`  Binary: ${runtime.path}`);
+  let llamaManifest;
+  let mlxManifest;
+  if (runtime === "mlx") {
+    console.log("\nDownloading MLX model snapshot (uv-managed; weights ~6 GB)...\n");
+    mlxManifest = await installModelMlx({ clefHome: config.clefHome, clefMcpVersion: VERSION, log });
+    console.log(`  Installed: ${mlxManifest.snapshotPath}`);
+  } else {
+    if (!opts.skipRuntime) {
+      process.stdout.write("\nEnsuring llama.cpp runtime...\n");
+      const rt = await ensureLlamaRuntime(config, log);
+      console.log(`  Runtime: llama.cpp (${rt.source}, ${rt.releaseTag})`);
+      console.log(`  Binary: ${rt.path}`);
+    }
+    console.log("");
+    const installed = await installModel({
+      clefHome: config.clefHome,
+      modelSpec: spec,
+      quantSpec: quant,
+      clefMcpVersion: VERSION,
+      onProgress: (p) => printProgress(p.bytes, p.total),
+      log
+    });
+    process.stderr.write("\n");
+    console.log(installed.alreadyInstalled ? `  Model already installed: ${installed.manifest.modelPath}` : `  Installed: ${installed.manifest.modelPath}`);
+    console.log(`  sha256: ${installed.manifest.sha256 ?? "n/a (not advertised upstream)"}`);
+    llamaManifest = installed.manifest;
   }
-  console.log("");
-  const { manifest, alreadyInstalled } = await installModel({
-    clefHome: config.clefHome,
-    modelSpec: spec,
-    quantSpec: quant,
-    clefMcpVersion: VERSION,
-    onProgress: (p) => printProgress(p.bytes, p.total),
-    log
-  });
-  process.stderr.write("\n");
-  console.log(alreadyInstalled ? `  Model already installed: ${manifest.modelPath}` : `  Installed: ${manifest.modelPath}`);
-  console.log(`  sha256: ${manifest.sha256 ?? "n/a (not advertised upstream)"}`);
   if (!opts.skipProbe) {
     process.stdout.write("\nVerifying inference (loads the model; first run can take a few minutes)...\n");
-    const probe = await probeInference(config, manifest, log);
-    console.log(`  Inference OK (${(probe.latencyMs / 1e3).toFixed(1)}s incl. model load, via ${probe.binarySource} binary)`);
+    const probe = runtime === "mlx" ? await probeMlxInference(config, mlxManifest, log) : await probeInference(config, llamaManifest, log);
+    console.log(`  Inference OK (${(probe.latencyMs / 1e3).toFixed(1)}s incl. model load)`);
   }
   if (opts.setup) {
     const { runSetup: runSetup2 } = await Promise.resolve().then(() => (init_setup(), setup_exports));
@@ -2070,7 +2752,10 @@ Model license: ${spec.licenseId} \u2014 ${spec.licenseUrl}`);
   console.log("  Claude Code : claude mcp add clef-mcp -- clef-mcp");
   console.log("  Codex       : add [mcp_servers.clef-mcp] to ~/.codex/config.toml (see README)");
   console.log("  Cursor      : add clef-mcp to .cursor/mcp.json (see README)");
-  console.log("  ZCode       : add clef-mcp to ~/.zcode/cli/config.json (see README)\n");
+  console.log("  ZCode       : add clef-mcp to ~/.zcode/cli/config.json (see README)");
+  if (runtime === "mlx") {
+    console.log("\nNote: set CLEF_RUNTIME=mlx for the server (and MCP clients) to use the MLX runtime.");
+  }
 }
 
 // src/cli/models-cmd.ts
@@ -2103,7 +2788,7 @@ async function runStatus() {
     spec = getModelSpec(config.model);
   } catch (err) {
     if (err instanceof ClefError && err.code === "INVALID_INPUT") {
-      console.log(`Runtime: llama.cpp`);
+      console.log(`Runtime: ${config.runtime}`);
       console.log(`Model: ${config.model} (unknown model id)`);
       console.log("Model status: unknown");
       console.log(`Memory: ${formatBytes(info.totalMemBytes)}`);
@@ -2111,6 +2796,26 @@ async function runStatus() {
     }
     throw err;
   }
+  if (config.runtime === "mlx") {
+    const mlx = await mlxIsInstalled(config.clefHome);
+    let uvLine = "not found (install: curl -LsSf https://astral.sh/uv/install.sh | sh)";
+    try {
+      uvLine = `uv: ${resolveUv(process.env.CLEF_MLX_UV)}`;
+    } catch (err) {
+      uvLine = `not found \u2014 ${err.message.split("\n")[0]}`;
+    }
+    console.log(`Runtime: mlx (${uvLine})`);
+    console.log(`Model: ${spec.id}${mlx ? " (MLX 4-bit)" : ""}`);
+    console.log(`Model status: ${mlx ? "installed" : "not installed (run: clef-mcp install --runtime mlx)"}`);
+    console.log(`Memory: ${formatBytes(info.totalMemBytes)}`);
+    if (mlx) {
+      console.log(`Snapshot: ${mlx.snapshotPath}`);
+      console.log(`Installed: ${mlx.installedAt}`);
+    } else {
+      console.log(`Cache home: ${pathsFor(config.clefHome).root}`);
+    }
+    return;
+  }
   const manifest = await findInstalledManifest(config.clefHome, spec);
   let runtimeLine;
   try {
@@ -2135,13 +2840,27 @@ async function runStatus() {
 
 // src/cli/uninstall.ts
 init_errors();
-import fsp7 from "fs/promises";
+import fsp9 from "fs/promises";
 init_prompt();
 async function runUninstall(opts) {
   const config = loadConfig();
   const spec = getModelSpec(opts.model ?? config.model);
-  const manifest = await findInstalledManifest(config.clefHome, spec);
   const { modelsDir } = pathsFor(config.clefHome);
+  if (config.runtime === "mlx") {
+    const mlx = await mlxIsInstalled(config.clefHome);
+    if (!mlx) {
+      throw new ClefError(ClefErrorCode.MODEL_NOT_INSTALLED, "The MLX model is not installed.", "Nothing to remove.");
+    }
+    const ok2 = await confirm(`Remove the MLX snapshot for ${spec.id}?`, opts.yes === true);
+    if (!ok2) {
+      console.log("Aborted.");
+      return;
+    }
+    await removeMlxModel(config.clefHome);
+    console.log("Removed MLX snapshot.");
+    return;
+  }
+  const manifest = await findInstalledManifest(config.clefHome, spec);
   if (!manifest && !opts.runtime) {
     throw new ClefError(
       ClefErrorCode.MODEL_NOT_INSTALLED,
@@ -2160,7 +2879,7 @@ async function runUninstall(opts) {
     return;
   }
   if (target) {
-    await fsp7.rm(target, { recursive: true, force: true });
+    await fsp9.rm(target, { recursive: true, force: true });
     console.log(`Removed: ${target}`);
   }
   if (opts.runtime) {
@@ -2187,7 +2906,7 @@ program.action(async () => {
     handleCliError(err);
   }
 });
-program.command("install").description("Detect the machine, download a Clef model + runtime, verify checksum and inference.").option("--model <id>", "model to install (default: clef-flash)").option("--quant <id>", "quantization override: Q4_K_M | Q8_0 | BF16").option("-y, --yes", "assume yes for all prompts (non-interactive)").option("--skip-runtime", "do not download/verify the llama.cpp runtime").option("--skip-probe", "skip the post-install inference verification").option("--setup", "also register the MCP server + agent skill in detected clients (same as running `clef-mcp setup`)").action(async (opts) => {
+program.command("install").description("Detect the machine, download a Clef model + runtime, verify checksum and inference.").option("--model <id>", "model to install (default: clef-flash)").option("--quant <id>", "quantization override: Q4_K_M | Q8_0 | BF16").option("-y, --yes", "assume yes for all prompts (non-interactive)").option("--skip-runtime", "do not download/verify the llama.cpp runtime").option("--skip-probe", "skip the post-install inference verification").option("--runtime <id>", "inference runtime: llama-cpp (default) | mlx (Apple Silicon)").option("--setup", "also register the MCP server + agent skill in detected clients (same as running `clef-mcp setup`)").action(async (opts) => {
   try {
     await runInstall(opts);
   } catch (err) {