@yawlabs/mcp 0.62.0 → 0.63.1

package/dist/index.js

@@ -17,7 +17,7 @@ import {
   signIn,
   signOut,
   userConfigDir
-} from "./chunk-WORQOSXT.js";
+} from "./chunk-BTL5M3GN.js";
 
 // src/audit-cmd.ts
 import { homedir as homedir3 } from "os";
@@ -401,7 +401,7 @@ function parseAuditArgs(argv) {
     if (a === "--json") {
       json = true;
     } else if (a === "--help" || a === "-h") {
-      return { ok: false, error: AUDIT_USAGE };
+      return { ok: false, error: AUDIT_USAGE, help: true };
     } else if (a.startsWith("-")) {
       return { ok: false, error: `yaw-mcp audit: unknown argument "${a}"
 
@@ -451,7 +451,7 @@ async function runAudit(opts = {}) {
   const namespace = opts.namespace;
   if (!namespace) {
     printErr("yaw-mcp audit: missing <namespace>.");
-    return { exitCode: 1, lines };
+    return { exitCode: 2, lines };
   }
   const home = opts.home ?? homedir3();
   const { config, path: path5 } = await loadLocalBundles({ cwd: opts.cwd, home });
@@ -576,6 +576,9 @@ function topPartialBundles(installedNamespaces, limit) {
   }).slice(0, limit);
 }
 
+// src/config.ts
+import { request } from "undici";
+
 // src/config-loader.ts
 import { readFile as readFile3, stat as stat2 } from "fs/promises";
 import { homedir as homedir4 } from "os";
@@ -841,7 +844,6 @@ function profileAllows(profile, namespace) {
 }
 
 // src/config.ts
-import { request } from "undici";
 async function fetchConfig(apiUrl5, token5, currentVersion) {
   const url = `${apiUrl5.replace(/\/$/, "")}/api/connect/config`;
   const headers = {
@@ -1134,14 +1136,14 @@ var SUBCOMMAND_SPEC = [
     name: "sync",
     description: "Sync bundles across machines",
     positional: ["push", "pull", "status"],
-    flags: ["--key", "--json", "--help"]
+    flags: ["--dry-run", "--json", "--help"]
   },
   { name: "stats", description: "Show usage statistics", flags: ["--limit", "--days", "--json", "--help"] },
   {
     name: "secrets",
     description: "Manage stored secrets",
     positional: ["set", "get", "list", "remove", "lock", "push", "pull"],
-    flags: ["--key", "--value", "--stdin", "--json", "--help"]
+    flags: ["--force", "--value", "--stdin", "--json", "--help"]
   },
   {
     name: "set-active",
@@ -1152,6 +1154,12 @@ var SUBCOMMAND_SPEC = [
   // Other.
   { name: "audit", description: "Run a full-pass audit of loaded servers", flags: ["--json", "--help"] },
   { name: "compliance", description: "Run the compliance suite against a server", flags: ["--publish", "--help"] },
+  {
+    name: "foundry",
+    description: "Export the opt-in dispatch-trace corpus",
+    positional: ["export"],
+    flags: ["--out", "--cap", "--json", "--help"]
+  },
   { name: "help", description: "Show usage", flags: [] }
 ];
 function parseCompletionArgs(argv) {
@@ -1226,7 +1234,7 @@ ${posClause}
 # Install: save this to ~/.local/share/bash-completion/completions/yaw-mcp
 #          or source it from your .bashrc.
 _yaw-mcp() {
-  local cur prev words cword
+  local cur cword
   cur="\${COMP_WORDS[COMP_CWORD]}"
   cword=$COMP_CWORD
 
@@ -1337,14 +1345,17 @@ ${caseBranches}
 // src/compliance-cmd.ts
 import { spawn } from "child_process";
 import { request as request2 } from "undici";
+var COMPLIANCE_USAGE = '\n  Usage: yaw-mcp compliance <target> [extraArgs...] [--publish]\n\n  Examples:\n    yaw-mcp compliance "npx -y @modelcontextprotocol/server-filesystem /tmp"\n    yaw-mcp compliance https://example.com/mcp --publish\n\n';
 async function runComplianceCommand(argv) {
+  if (argv.includes("--help") || argv.includes("-h")) {
+    process.stdout.write(COMPLIANCE_USAGE);
+    return 0;
+  }
   const publish = argv.includes("--publish");
   const args = argv.filter((a) => a !== "--publish");
   if (args.length === 0) {
-    process.stderr.write(
-      '\n  Usage: yaw-mcp compliance <target> [extraArgs...] [--publish]\n\n  Examples:\n    yaw-mcp compliance "npx -y @modelcontextprotocol/server-filesystem /tmp"\n    yaw-mcp compliance https://example.com/mcp --publish\n\n'
-    );
-    return 1;
+    process.stderr.write(COMPLIANCE_USAGE);
+    return 2;
   }
   const apiUrl5 = process.env.YAW_MCP_URL ?? "https://yaw.sh/mcp";
   const report = await runTest(args);
@@ -1372,6 +1383,8 @@ Delete token (save this): ${result.deleteToken}
   }
   return 0;
 }
+var MAX_STDOUT_BYTES = 16 * 1024 * 1024;
+var CHILD_TIMEOUT_MS = 5 * 60 * 1e3;
 function runTest(args) {
   return new Promise((resolve7) => {
     const child = spawn("npx", ["-y", "@yawlabs/mcp-compliance", "test", "--format", "json", ...args], {
@@ -1379,16 +1392,48 @@ function runTest(args) {
       shell: process.platform === "win32"
     });
     let stdout = "";
+    let stdoutBytes = 0;
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      child.kill();
+      process.stderr.write(`
+mcp-compliance timed out after ${CHILD_TIMEOUT_MS / 1e3}s; killed.
+`);
+      resolve7(null);
+    }, CHILD_TIMEOUT_MS);
+    timer.unref?.();
     child.stdout.on("data", (chunk) => {
+      if (settled) return;
+      stdoutBytes += chunk.length;
+      if (stdoutBytes > MAX_STDOUT_BYTES) {
+        settled = true;
+        clearTimeout(timer);
+        child.kill();
+        process.stderr.write(
+          `
+mcp-compliance produced more than ${MAX_STDOUT_BYTES / (1024 * 1024)} MB of output; killed.
+`
+        );
+        resolve7(null);
+        return;
+      }
       stdout += chunk.toString();
     });
     child.on("error", (err) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
       process.stderr.write(`
 Failed to launch mcp-compliance: ${err.message}
 `);
       resolve7(null);
     });
     child.on("close", (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
       try {
         const parsed = JSON.parse(stdout);
         if (!parsed.grade || !parsed.summary) {
@@ -1417,12 +1462,36 @@ Target: ${url}
 `
   );
 }
+function projectForPublish(report) {
+  const tests = Array.isArray(report.tests) ? report.tests : [];
+  return {
+    grade: report.grade,
+    score: report.score,
+    url: report.url,
+    summary: {
+      total: report.summary.total,
+      passed: report.summary.passed,
+      failed: report.summary.failed,
+      required: report.summary.required,
+      requiredPassed: report.summary.requiredPassed
+    },
+    tests: tests.map((t) => {
+      const test = t ?? {};
+      const projected = {};
+      if (typeof test.name === "string") projected.name = test.name;
+      if (typeof test.status === "string") projected.status = test.status;
+      if (typeof test.required === "boolean") projected.required = test.required;
+      if (typeof test.message === "string") projected.message = test.message;
+      return projected;
+    })
+  };
+}
 async function publishReport(apiUrl5, report) {
   try {
     const res = await request2(`${apiUrl5.replace(/\/$/, "")}/api/compliance/ext`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify(report)
+      body: JSON.stringify(projectForPublish(report))
     });
     if (res.statusCode !== 200) {
       const body = await res.body.text().catch(() => "");
@@ -1720,7 +1789,7 @@ function resolveShadowedClis(server) {
   if (cache.length < 3) return [];
   const prefixes = /* @__PURE__ */ new Set();
   for (const t of cache) {
-    const first = t.name.split(/[_.\-]/)[0];
+    const first = t.name.split(/[_.-]/)[0];
     if (first) prefixes.add(first.toLowerCase());
   }
   if (prefixes.size !== 1) return [];
@@ -2083,7 +2152,7 @@ async function reportTools(serverId, tools) {
 // src/try-cmd.ts
 import { createHash as createHash2 } from "crypto";
 import { existsSync as existsSync3 } from "fs";
-import { chmod as chmod2, mkdir as mkdir2, readFile as readFile6, readdir, unlink } from "fs/promises";
+import { chmod as chmod2, mkdir as mkdir2, readdir, readFile as readFile6, unlink } from "fs/promises";
 import { homedir as homedir7, hostname, userInfo } from "os";
 import { join as join7, resolve as resolve5 } from "path";
 import { request as request5 } from "undici";
@@ -2189,7 +2258,8 @@ import { chmod, readFile as readFile5 } from "fs/promises";
 import { homedir as homedir6 } from "os";
 import { join as join6, resolve as resolve4 } from "path";
 import { createInterface } from "readline/promises";
-var USAGE = "Usage: yaw-mcp install <claude-code|claude-desktop|cursor|vscode> [--scope user|project|local]\n                       [--token <mcp_pat_\u2026>] [--project-dir <path>] [--os macos|linux|windows]\n                       [--force | --skip] [--dry-run] [--no-yaw-mcp-config]\n       yaw-mcp install --list                       (detect clients; no writes)\n       yaw-mcp install --all  [--token <mcp_pat_\u2026>] (install into every detected client)";
+import { Writable } from "stream";
+var USAGE = "Usage: yaw-mcp install <claude-code|claude-desktop|cursor|vscode> [--scope user|project|local]\n                       [--token <mcp_pat_\u2026>] [--project-dir <path>] [--os macos|linux|windows]\n                       [--force | --skip] [--dry-run] [--no-yaw-mcp-config]\n       yaw-mcp install --list                       (detect clients; no writes)\n       yaw-mcp install --all  [--token <mcp_pat_\u2026>] (install into every detected client)\n\n  Note: --token puts the PAT on the command line, where it is visible in shell\n  history and the process table (ps/Task Manager) -- avoid it on shared machines.\n  Prefer seeding ~/.yaw-mcp/config.json once (install reads the token from there),\n  or set the token via your account before installing.";
 async function runInstall(opts) {
   const stdout = opts.io?.stdout ?? process.stdout;
   const stderr = opts.io?.stderr ?? process.stderr;
@@ -2306,7 +2376,7 @@ ${USAGE}`);
   }
   if (existingHasEntry) {
     let decision;
-    if (opts.force) decision = "overwrite";
+    if (opts.force || opts.dryRun) decision = "overwrite";
     else if (opts.skip) decision = "skip";
     else if (opts.promptAnswer) decision = opts.promptAnswer;
     else if (opts.io?.isTTY ?? (Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY))) {
@@ -2351,7 +2421,7 @@ ${USAGE}`);
   if (opts.dryRun) {
     log2("\n--- dry run: would write the following ---");
     if (writeYawMcpConfig) log2(`# ${yawMcpConfigPath}
-${yawMcpConfigJson}`);
+${redactConfigToken(yawMcpConfigJson)}`);
     log2(`
 # ${resolved.absolute}
 ${clientJson}`);
@@ -2371,7 +2441,7 @@ ${settingsPatch.nextJson}`);
   const written = [];
   if (writeYawMcpConfig) {
     try {
-      await atomicWriteFile(yawMcpConfigPath, yawMcpConfigJson);
+      await atomicWriteFile(yawMcpConfigPath, yawMcpConfigJson, "utf8", 384);
       if (process.platform !== "win32") {
         try {
           await chmod(yawMcpConfigPath, 384);
@@ -2527,6 +2597,21 @@ function removeFromClientConfig(existing, containerPath, entryName) {
   parent[leafKey] = container;
   return out;
 }
+async function writeBackup(path5, raw) {
+  const candidate = `${path5}.bak-${Date.now()}`;
+  try {
+    await atomicWriteFile(candidate, raw, "utf8", 384);
+    if (process.platform !== "win32") {
+      try {
+        await chmod(candidate, 384);
+      } catch {
+      }
+    }
+    return candidate;
+  } catch {
+    return void 0;
+  }
+}
 async function composeYawMcpConfig(path5, token5) {
   let existing = {};
   let backupPath;
@@ -2543,20 +2628,10 @@ async function composeYawMcpConfig(path5, token5) {
         if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
           existing = parsed;
         } else {
-          const candidate = `${path5}.bak-${Date.now()}`;
-          try {
-            await atomicWriteFile(candidate, raw);
-            backupPath = candidate;
-          } catch {
-          }
+          backupPath = await writeBackup(path5, raw);
         }
       } catch {
-        const candidate = `${path5}.bak-${Date.now()}`;
-        try {
-          await atomicWriteFile(candidate, raw);
-          backupPath = candidate;
-        } catch {
-        }
+        backupPath = await writeBackup(path5, raw);
       }
     }
   }
@@ -2566,6 +2641,9 @@ async function composeYawMcpConfig(path5, token5) {
   return { json: `${JSON.stringify(next, null, 2)}
 `, backupPath };
 }
+function redactConfigToken(json) {
+  return json.replace(/("token"\s*:\s*)"(?:[^"\\]|\\.)*"/g, '$1"mcp_pat_***"');
+}
 function parseInstallArgs(argv) {
   if (argv.length === 0) return { ok: false, error: USAGE };
   const positional = [];
@@ -2680,7 +2758,7 @@ async function runInstallList(opts, log2) {
   }
   log2("");
   log2("Install into a specific client: `yaw-mcp install <client> [--scope user|project|local]`");
-  log2("Install into every available user-scope client: `yaw-mcp install --all`");
+  log2("Install into every available client (user scope where supported): `yaw-mcp install --all`");
   return { written: [], wouldWrite: [], messages: [], exitCode: 0 };
 }
 function statusFor(p) {
@@ -2737,15 +2815,35 @@ async function runInstallAll(opts, log2, err) {
   const aggregateMessages = [];
   let failed = 0;
   let succeeded = 0;
+  const collisionClients = [];
+  const realStderr = opts.io?.stderr ?? process.stderr;
+  const isCollisionRefusal = (s) => s.includes(`already has a "${ENTRY_NAME}" entry and stdin is not a TTY`);
   for (const plan of plans) {
     log2(`\u2500\u2500 ${plan.clientId} (${plan.scope}) \u2500\u2500`);
+    let sawCollision = false;
+    const subStderr = new Writable({
+      write(chunk, _enc, cb) {
+        const text = chunk.toString();
+        if (isCollisionRefusal(text)) sawCollision = true;
+        else realStderr.write(text);
+        cb();
+      }
+    });
+    const baseIo = opts.io ?? {
+      stdin: process.stdin,
+      stdout: process.stdout,
+      stderr: process.stderr,
+      isTTY: Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY)
+    };
     const result = await runInstall({
       ...opts,
       listOnly: false,
       all: false,
       clientId: plan.clientId,
-      scope: plan.scope
+      scope: plan.scope,
+      io: { ...baseIo, stderr: subStderr }
     });
+    if (sawCollision) collisionClients.push(plan.clientId);
     aggregateWritten.push(...result.written);
     aggregateWouldWrite.push(...result.wouldWrite);
     aggregateMessages.push(...result.messages);
@@ -2753,6 +2851,12 @@ async function runInstallAll(opts, log2, err) {
     else failed += 1;
     log2("");
   }
+  if (collisionClients.length > 0) {
+    err(
+      `yaw-mcp install --all: ${collisionClients.length} client${collisionClients.length === 1 ? "" : "s"} already have a "${ENTRY_NAME}" entry (${collisionClients.join(", ")}) and stdin is not a TTY.
+  Re-run \`yaw-mcp install --all --force\` to overwrite them, or \`--skip\` to leave them untouched.`
+    );
+  }
   const totalPlanned = plans.length;
   if (failed === 0) {
     log2(`Done: ${succeeded}/${totalPlanned} clients installed successfully.`);
@@ -2829,7 +2933,7 @@ function parseTryArgs(argv) {
       }
       case "--env": {
         const v = next();
-        if (!v || !v.includes("=")) return { ok: false, error: "--env requires KEY=value" };
+        if (!v?.includes("=")) return { ok: false, error: "--env requires KEY=value" };
         const eq = v.indexOf("=");
         const key = v.slice(0, eq);
         const val = v.slice(eq + 1);
@@ -2844,7 +2948,7 @@ function parseTryArgs(argv) {
         break;
       case "--base": {
         const v = next();
-        if (!v) return { ok: false, error: "--base requires a URL" };
+        if (!v || v.startsWith("--")) return { ok: false, error: "--base requires a URL" };
         opts.baseUrl = v;
         break;
       }
@@ -2853,6 +2957,8 @@ function parseTryArgs(argv) {
         return { ok: false, error: TRY_USAGE, help: true };
       default:
         if (a.startsWith("--")) return { ok: false, error: `Unknown flag: ${a}
+${TRY_USAGE}` };
+        if (a === "-") return { ok: false, error: `Invalid argument "-".
 ${TRY_USAGE}` };
         positional.push(a);
     }
@@ -2879,6 +2985,8 @@ function parseTryCleanupArgs(argv) {
       continue;
     }
     if (a.startsWith("--")) return { ok: false, error: `Unknown flag: ${a}
+${TRY_CLEANUP_USAGE}` };
+    if (a === "-") return { ok: false, error: `Invalid argument "-".
 ${TRY_CLEANUP_USAGE}` };
     positional.push(a);
   }
@@ -3045,6 +3153,10 @@ async function runTry(opts) {
   for (const [k, v] of Object.entries(opts.envOverrides ?? {})) {
     if (!(k in trialEnv)) trialEnv[k] = v;
   }
+  const overrides = opts.envOverrides ?? {};
+  const ambientOnlyRequired = (server.requiredEnvVars ?? []).filter(
+    (k) => (!overrides[k] || overrides[k] === "") && (supplied[k] ?? "").trim() !== ""
+  );
   const entry = buildLaunchEntry({
     os,
     upstream: {
@@ -3066,8 +3178,9 @@ async function runTry(opts) {
     entryName,
     createdAt: now
   };
+  const clientPreExisted = existsSync3(resolved.absolute);
   let existing = {};
-  if (existsSync3(resolved.absolute)) {
+  if (clientPreExisted) {
     try {
       const raw = await readFile6(resolved.absolute, "utf8");
       if (raw.trim().length > 0) {
@@ -3110,6 +3223,12 @@ async function runTry(opts) {
   try {
     await atomicWriteFile(resolved.absolute, clientJson);
     written.push(resolved.absolute);
+    if (!clientPreExisted && entry.env && Object.keys(entry.env).length > 0 && process.platform !== "win32") {
+      try {
+        await chmod2(resolved.absolute, 384);
+      } catch {
+      }
+    }
   } catch (e) {
     printErr(`yaw-mcp try: failed to write ${resolved.absolute}: ${e.message}`);
     await unlink(trialMarkerPath(slug, home)).catch(() => void 0);
@@ -3117,11 +3236,16 @@ async function runTry(opts) {
   }
   const anonId = await loadOrCreateAnonId(home);
   const postEvent = opts.postEvent ?? defaultPostEvent;
-  postEvent(baseUrl, { slug, action: "try", anonId }).catch(() => void 0);
+  await postEvent(baseUrl, { slug, action: "try", anonId }).catch(() => void 0);
   const ttlPretty = formatTtl(ttlMs);
   print(`Trial wired: ${server.name} via yaw-mcp-try-${slug} -> ${resolved.absolute}`);
   print(`Expires in ${ttlPretty}; remove sooner with: yaw-mcp try-cleanup ${slug}`);
   print(`Liking it? Sign up at ${baseUrl}/signup to keep ${server.name} on every machine.`);
+  if (ambientOnlyRequired.length > 0) {
+    printErr(
+      `Note: ${ambientOnlyRequired.join(", ")} ${ambientOnlyRequired.length === 1 ? "was" : "were"} read from your shell env and written into the trial entry at ${resolved.absolute}. Remove the trial with: yaw-mcp try-cleanup ${slug}`
+    );
+  }
   return { exitCode: 0, written, marker };
 }
 async function runTryCleanup(opts) {
@@ -3194,7 +3318,7 @@ async function runTryCleanup(opts) {
   }
   const anonId = await loadOrCreateAnonId(home);
   const postEvent = opts.postEvent ?? defaultPostEvent;
-  postEvent(baseUrl, { slug, action: "cleanup", anonId }).catch(() => void 0);
+  await postEvent(baseUrl, { slug, action: "cleanup", anonId }).catch(() => void 0);
   print(`Trial for "${slug}" cleaned up.`);
   return { exitCode: 0, written };
 }
@@ -3268,7 +3392,7 @@ async function gcExpiredTrials(opts) {
         }
       }
       await unlink(trialMarkerPath(marker.slug, home));
-      postEvent(baseUrl, { slug: marker.slug, action: "expiry-gc", anonId }).catch(() => void 0);
+      await postEvent(baseUrl, { slug: marker.slug, action: "expiry-gc", anonId }).catch(() => void 0);
       cleared++;
     } catch (e) {
       log("debug", "trial gc failed", { slug: marker.slug, error: e.message });
@@ -3308,7 +3432,7 @@ ${UPGRADE_USAGE}` };
 function detectInstallMethod(argvPath) {
   if (!argvPath) return "unknown";
   const normalized = argvPath.replace(/\\/g, "/");
-  if (/\/_npx\//.test(normalized)) return "npx";
+  if (/\/_npx\/[0-9a-f]+\/node_modules\/@yawlabs\/mcp\//.test(normalized)) return "npx";
   if (/\/app\.asar\.unpacked\//.test(normalized)) return "bundled-app";
   if (/\/npm\/node_modules\/@yawlabs\/mcp\//.test(normalized)) return "global-npm";
   if (/\/lib\/node_modules\/@yawlabs\/mcp\//.test(normalized)) return "global-npm";
@@ -3521,23 +3645,20 @@ async function runUpgrade(opts = {}) {
     return { exitCode: 0, lines };
   }
   if (method === "binary") {
-    print("yaw-mcp is running as a standalone binary \u2014 there's no package manager");
-    print("to upgrade it. Download the latest build and replace this executable:");
+    print("yaw-mcp is running as a standalone binary \u2014 manual upgrade required.");
+    print("There's no package manager to upgrade it, and `--run` can't automate");
+    print("this: download the latest build and replace this executable:");
     print("");
     print(`  ${BINARY_DOWNLOAD_URL}`);
     return { exitCode: opts.run ? 2 : 1, lines };
   }
-  if (!plan.command) {
-    print("No upgrade command available for this install method.");
-    return { exitCode: 0, lines };
-  }
   const installRoot = method === "local-node-modules" ? localInstallRoot(argvPath) : null;
   const runSpec = method === "global-npm" ? { cmd: "npm", args: ["install", "-g", "@yawlabs/mcp@latest"] } : method === "pnpm-global" ? { cmd: "pnpm", args: ["add", "-g", "@yawlabs/mcp@latest"] } : method === "bun-global" ? { cmd: "bun", args: ["add", "-g", "@yawlabs/mcp@latest"] } : method === "local-node-modules" && installRoot !== null ? { cmd: "npm", args: ["install", "@yawlabs/mcp@latest"], cwd: installRoot } : null;
   if (!opts.run) {
     if (runSpec) {
       print("Run `yaw-mcp upgrade --run` to upgrade in place, or run it yourself:");
     } else {
-      print("Run it yourself (--run can't safely automate this install method):");
+      print("Manual upgrade required (--run can't safely automate this install method). Run it yourself:");
     }
     print("");
     if (installRoot) {
@@ -3547,7 +3668,9 @@ async function runUpgrade(opts = {}) {
     return { exitCode: 1, lines };
   }
   if (!runSpec) {
-    printErr(`yaw-mcp upgrade --run: a "${method}" install can't be upgraded automatically. Run it yourself:`);
+    printErr(
+      `yaw-mcp upgrade --run: a "${method}" install can't be upgraded automatically (manual upgrade required). Run it yourself:`
+    );
     printErr("");
     printErr(`  ${plan.command}`);
     return { exitCode: 2, lines };
@@ -3572,7 +3695,7 @@ async function runUpgrade(opts = {}) {
   return { exitCode: 3, lines };
 }
 function readCurrentVersion() {
-  return true ? "0.62.0" : "dev";
+  return true ? "0.63.1" : "dev";
 }
 
 // src/usage-hints.ts
@@ -3634,7 +3757,7 @@ function selectFlakyNamespaces(entries, limit) {
 }
 
 // src/doctor-cmd.ts
-var VERSION = true ? "0.62.0" : "dev";
+var VERSION = true ? "0.63.1" : "dev";
 function isPersistenceDisabled(env) {
   const raw = env.YAW_MCP_DISABLE_PERSISTENCE;
   return raw !== void 0 && raw !== "" && (raw === "1" || raw.toLowerCase() === "true");
@@ -3677,11 +3800,13 @@ async function runDoctor(opts = {}) {
   renderEnvSection({ env, print });
   const persistenceDisabled = isPersistenceDisabled(env);
   const stateFilePath = join8(userConfigDir(home), STATE_FILENAME);
-  const persistedState = persistenceDisabled ? null : await loadState(stateFilePath);
-  await renderStateSection({
+  const statePeek = persistenceDisabled ? null : await peekStateFile(stateFilePath);
+  const persistedState = statePeek?.kind === "ok" ? await loadState(stateFilePath) : null;
+  renderStateSection({
     filePath: stateFilePath,
     disabled: persistenceDisabled,
     persisted: persistedState,
+    peek: statePeek,
     print
   });
   renderReliabilitySection({ disabled: persistenceDisabled, persisted: persistedState, print });
@@ -3814,6 +3939,31 @@ async function runDoctorJson(opts) {
     }
   }
   const shellShadows = scanShellHistoryForShadows({ home, env });
+  const trialGc = await gcExpiredTrials({ home, env, postEvent: opts.postTryEvent, now: opts.now }).catch(() => ({
+    cleared: 0,
+    failed: 0
+  }));
+  const trialScan = await scanTrials({ home, now: opts.now });
+  const trials = {
+    cleared: trialGc.cleared,
+    live: trialScan.live.map(({ marker, msUntilExpiry }) => ({
+      slug: marker.slug,
+      clientName: marker.clientName,
+      clientPath: marker.clientPath,
+      msUntilExpiry
+    })),
+    malformed: trialScan.malformed
+  };
+  const analyticsFailure = getLastAnalyticsFailure();
+  const reportFailure = getLastReportFailure();
+  const backgroundPosters = {
+    analytics: analyticsFailure ? {
+      statusCode: analyticsFailure.statusCode,
+      url: analyticsFailure.url,
+      at: new Date(analyticsFailure.at).toISOString()
+    } : null,
+    toolReport: reportFailure ? { statusCode: reportFailure.statusCode, url: reportFailure.url, at: new Date(reportFailure.at).toISOString() } : null
+  };
   const skipCheck = (opts.skipRegistryCheck === true || Boolean(process.env.VITEST)) && !opts.registryFetch;
   const latest = skipCheck ? null : await fetchLatestVersion(opts.registryFetch);
   const effectiveVersion = opts.currentVersion ?? VERSION;
@@ -3846,6 +3996,8 @@ async function runDoctorJson(opts) {
     reliability,
     clients,
     shellShadows,
+    trials,
+    backgroundPosters,
     upgrade: { current: effectiveVersion, latest, stale },
     diagnosis: { exitCode, summary }
   };
@@ -3874,16 +4026,15 @@ function renderEnvSection(opts) {
   }
   print("");
 }
-async function renderStateSection(opts) {
-  const { filePath, disabled, persisted, print } = opts;
+function renderStateSection(opts) {
+  const { filePath, disabled, persisted, peek, print } = opts;
   print("STATE");
-  if (disabled) {
-    print("  status: disabled via YAW_MCP_DISABLE_PERSISTENCE");
+  if (disabled || !peek) {
+    if (disabled) print("  status: disabled via YAW_MCP_DISABLE_PERSISTENCE");
     print("");
     return;
   }
   print(`  path:   ${filePath}`);
-  const peek = await peekStateFile(filePath);
   if (peek.kind === "malformed") {
     print("  status: corrupt -- file exists but JSON is unparseable");
     print(`  fix:    \`yaw-mcp reset-learning\` to clear, or open ${filePath} and fix by hand`);
@@ -4042,29 +4193,14 @@ function probeClients(opts) {
         continue;
       }
       const exists3 = existsSync4(resolved.absolute);
-      let hasMcpEntry = false;
-      let hasLegacyEntry = false;
-      let legacyEntryName = null;
-      let malformed = false;
+      let classified = { hasMcpEntry: false, hasLegacyEntry: false, legacyEntryName: null, malformed: false };
       if (exists3) {
         try {
           statSync(resolved.absolute);
           const raw = readFileSync(resolved.absolute, "utf8");
-          if (raw.trim().length > 0) {
-            const parsed = parseJsonc(raw);
-            if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
-              const container = walkContainer(parsed, resolved.containerPath);
-              if (container) {
-                hasMcpEntry = ENTRY_NAME in container;
-                legacyEntryName = findLegacyEntry(container);
-                hasLegacyEntry = legacyEntryName !== null;
-              }
-            } else {
-              malformed = true;
-            }
-          }
+          classified = classifyProbeContent(raw, resolved.containerPath);
         } catch {
-          malformed = true;
+          classified = { hasMcpEntry: false, hasLegacyEntry: false, legacyEntryName: null, malformed: true };
         }
       }
       out.push({
@@ -4072,10 +4208,7 @@ function probeClients(opts) {
         scope: scope.scope,
         path: resolved.absolute,
         exists: exists3,
-        hasMcpEntry,
-        hasLegacyEntry,
-        legacyEntryName,
-        malformed,
+        ...classified,
         unavailable: false
       });
     }
@@ -4091,6 +4224,30 @@ function walkContainer(root, path5) {
   if (typeof cur !== "object" || cur === null || Array.isArray(cur)) return null;
   return cur;
 }
+function classifyProbeContent(raw, containerPath) {
+  if (raw.trim().length === 0) {
+    return { hasMcpEntry: false, hasLegacyEntry: false, legacyEntryName: null, malformed: false };
+  }
+  try {
+    const parsed = parseJsonc(raw);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      return { hasMcpEntry: false, hasLegacyEntry: false, legacyEntryName: null, malformed: true };
+    }
+    const container = walkContainer(parsed, containerPath);
+    if (!container) {
+      return { hasMcpEntry: false, hasLegacyEntry: false, legacyEntryName: null, malformed: false };
+    }
+    const legacyEntryName = findLegacyEntry(container);
+    return {
+      hasMcpEntry: ENTRY_NAME in container,
+      hasLegacyEntry: legacyEntryName !== null,
+      legacyEntryName,
+      malformed: false
+    };
+  } catch {
+    return { hasMcpEntry: false, hasLegacyEntry: false, legacyEntryName: null, malformed: true };
+  }
+}
 async function probeClientsAsync(opts) {
   const result = [];
   for (const target of INSTALL_TARGETS) {
@@ -4110,38 +4267,28 @@ async function probeClientsAsync(opts) {
       continue;
     }
     for (const scope of target.scopes) {
-      const resolved = resolveInstallPath({
-        clientId: target.clientId,
-        scope: scope.scope,
-        os: opts.os,
-        home: opts.home,
-        projectDir: scope.requiresProjectDir ? opts.cwd : void 0,
-        claudeConfigDir: opts.claudeConfigDir
-      });
+      let resolved;
+      try {
+        resolved = resolveInstallPath({
+          clientId: target.clientId,
+          scope: scope.scope,
+          os: opts.os,
+          home: opts.home,
+          projectDir: scope.requiresProjectDir ? opts.cwd : void 0,
+          claudeConfigDir: opts.claudeConfigDir
+        });
+      } catch {
+        continue;
+      }
       const exists3 = existsSync4(resolved.absolute);
-      let hasMcpEntry = false;
-      let hasLegacyEntry = false;
-      let legacyEntryName = null;
-      let malformed = false;
+      let classified = { hasMcpEntry: false, hasLegacyEntry: false, legacyEntryName: null, malformed: false };
       if (exists3) {
         try {
           await stat3(resolved.absolute);
           const raw = await readFile7(resolved.absolute, "utf8");
-          if (raw.trim().length > 0) {
-            const parsed = parseJsonc(raw);
-            if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
-              const container = walkContainer(parsed, resolved.containerPath);
-              if (container) {
-                hasMcpEntry = ENTRY_NAME in container;
-                legacyEntryName = findLegacyEntry(container);
-                hasLegacyEntry = legacyEntryName !== null;
-              }
-            } else {
-              malformed = true;
-            }
-          }
+          classified = classifyProbeContent(raw, resolved.containerPath);
         } catch {
-          malformed = true;
+          classified = { hasMcpEntry: false, hasLegacyEntry: false, legacyEntryName: null, malformed: true };
         }
       }
       result.push({
@@ -4149,10 +4296,7 @@ async function probeClientsAsync(opts) {
         scope: scope.scope,
         path: resolved.absolute,
         exists: exists3,
-        hasMcpEntry,
-        hasLegacyEntry,
-        legacyEntryName,
-        malformed,
+        ...classified,
         unavailable: false
       });
     }
@@ -4284,8 +4428,10 @@ import { mkdirSync, readFileSync as readFileSync3, writeFileSync } from "fs";
 import { homedir as homedir10 } from "os";
 import path3 from "path";
 
-// src/foundry-corpus.ts
-import { readFileSync as readFileSync2 } from "fs";
+// src/foundry.ts
+import { appendFile, mkdir as mkdir3, stat as stat4 } from "fs/promises";
+import { homedir as homedir9 } from "os";
+import path2 from "path";
 
 // src/relevance.ts
 var K1 = 1.2;
@@ -4404,7 +4550,64 @@ function rankServers(context, servers) {
   return results;
 }
 
+// src/foundry.ts
+var SECRET_PREFIXES = ["sk_", "sk-", "tok_", "ghp_", "gho_", "xox", "pk_", "akia"];
+function looksSensitive(token5) {
+  for (const prefix of SECRET_PREFIXES) {
+    if (token5.startsWith(prefix)) return true;
+  }
+  if (token5.length >= 16 && /^[0-9a-f]+$/.test(token5)) return true;
+  if (token5.length >= 12 && /[a-z]/.test(token5) && /[0-9]/.test(token5)) return true;
+  if (token5.length >= 16 && /^[a-z]+$/.test(token5)) return true;
+  return false;
+}
+function redactIntent(intent) {
+  const all = tokenize(intent);
+  const tokens = [];
+  let redactedCount = 0;
+  for (const token5 of all) {
+    if (looksSensitive(token5)) {
+      redactedCount++;
+    } else {
+      tokens.push(token5);
+    }
+  }
+  tokens.sort();
+  return { tokens, redactedCount };
+}
+function isFoundryEnabled() {
+  const raw = process.env.YAW_MCP_FOUNDRY;
+  if (!raw) return false;
+  const v = raw.trim().toLowerCase();
+  return v === "1" || v === "true";
+}
+var MAX_FOUNDRY_BYTES = 5 * 1024 * 1024;
+var FOUNDRY_FILENAME = "foundry.jsonl";
+async function appendFoundryTrace(trace, home = homedir9()) {
+  try {
+    if (!isFoundryEnabled()) return;
+    const dir = userConfigDir(home);
+    const file = path2.join(dir, FOUNDRY_FILENAME);
+    try {
+      const info = await stat4(file);
+      if (info.size >= MAX_FOUNDRY_BYTES) return;
+    } catch {
+    }
+    const line = `${JSON.stringify({
+      tokens: trace.tokens,
+      candidates: trace.candidates,
+      chosen: trace.chosen,
+      redactedCount: trace.redactedCount
+    })}
+`;
+    await mkdir3(dir, { recursive: true });
+    await appendFile(file, line, "utf8");
+  } catch {
+  }
+}
+
 // src/foundry-corpus.ts
+import { readFileSync as readFileSync2 } from "fs";
 var FOUNDRY_CORPUS_VERSION = 1;
 var DEFAULT_CORPUS_CAP = 500;
 function parseTraceLines(text) {
@@ -4485,65 +4688,6 @@ function scoreCorpus(corpus) {
   };
 }
 
-// src/foundry.ts
-import { appendFile, mkdir as mkdir3, stat as stat4 } from "fs/promises";
-import { homedir as homedir9 } from "os";
-import path2 from "path";
-var SECRET_PREFIXES = ["sk_", "sk-", "tok_", "ghp_", "gho_", "xox", "pk_", "akia"];
-function looksSensitive(token5) {
-  for (const prefix of SECRET_PREFIXES) {
-    if (token5.startsWith(prefix)) return true;
-  }
-  if (token5.length >= 16 && /^[0-9a-f]+$/.test(token5)) return true;
-  if (token5.length >= 12 && /[a-z]/.test(token5) && /[0-9]/.test(token5)) return true;
-  if (token5.length >= 16 && /^[a-z]+$/.test(token5)) return true;
-  return false;
-}
-function redactIntent(intent) {
-  const all = tokenize(intent);
-  const tokens = [];
-  let redactedCount = 0;
-  for (const token5 of all) {
-    if (looksSensitive(token5)) {
-      redactedCount++;
-    } else {
-      tokens.push(token5);
-    }
-  }
-  tokens.sort();
-  return { tokens, redactedCount };
-}
-function isFoundryEnabled() {
-  const raw = process.env.YAW_MCP_FOUNDRY;
-  if (!raw) return false;
-  const v = raw.trim().toLowerCase();
-  return v === "1" || v === "true";
-}
-var MAX_FOUNDRY_BYTES = 5 * 1024 * 1024;
-var FOUNDRY_FILENAME = "foundry.jsonl";
-async function appendFoundryTrace(trace, home = homedir9()) {
-  try {
-    if (!isFoundryEnabled()) return;
-    const dir = userConfigDir(home);
-    const file = path2.join(dir, FOUNDRY_FILENAME);
-    try {
-      const info = await stat4(file);
-      if (info.size >= MAX_FOUNDRY_BYTES) return;
-    } catch {
-    }
-    const line = `${JSON.stringify({
-      tokens: trace.tokens,
-      candidates: trace.candidates,
-      chosen: trace.chosen,
-      redactedCount: trace.redactedCount
-    })}
-`;
-    await mkdir3(dir, { recursive: true });
-    await appendFile(file, line, "utf8");
-  } catch {
-  }
-}
-
 // src/foundry-cmd.ts
 var DEFAULT_OUT = path3.join("src", "tests", "fixtures", "foundry-corpus.json");
 var FOUNDRY_USAGE = `Usage: yaw-mcp foundry export [--out <path>] [--cap <n>] [--json]
@@ -4676,60 +4820,6 @@ async function runFoundryExport(opts) {
   return { exitCode: 0, lines };
 }
 
-// src/fuzzy.ts
-function levenshtein(a, b) {
-  if (a === b) return 0;
-  const aLen = a.length;
-  const bLen = b.length;
-  if (aLen === 0) return bLen;
-  if (bLen === 0) return aLen;
-  let prev = new Array(bLen + 1);
-  let curr = new Array(bLen + 1);
-  for (let j = 0; j <= bLen; j++) prev[j] = j;
-  for (let i = 1; i <= aLen; i++) {
-    curr[0] = i;
-    for (let j = 1; j <= bLen; j++) {
-      const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1;
-      curr[j] = Math.min(
-        curr[j - 1] + 1,
-        // insertion
-        prev[j] + 1,
-        // deletion
-        prev[j - 1] + cost
-        // substitution
-      );
-    }
-    [prev, curr] = [curr, prev];
-  }
-  return prev[bLen];
-}
-function closestNames(query, candidates, limit) {
-  if (limit <= 0) return [];
-  const q = query.toLowerCase();
-  const scored = [];
-  for (const c of candidates) {
-    if (c === query) continue;
-    const lc = c.toLowerCase();
-    let score = null;
-    if (lc === q) {
-      score = 0;
-    } else if (lc.startsWith(q) || q.startsWith(lc)) {
-      score = 1;
-    } else if (lc.includes(q) || q.includes(lc)) {
-      score = 2;
-    } else {
-      const d = levenshtein(q, lc);
-      if (d <= 2) score = 2 + d;
-    }
-    if (score !== null) scored.push({ name: c, score });
-  }
-  scored.sort((a, b) => {
-    if (a.score !== b.score) return a.score - b.score;
-    return a.name.localeCompare(b.name);
-  });
-  return scored.slice(0, limit).map((s) => s.name);
-}
-
 // src/local-add-cmd.ts
 import { homedir as homedir11 } from "os";
 var SLUG_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
@@ -4747,7 +4837,7 @@ var ADD_USAGE = `Usage: yaw-mcp add <slug> [flags]
   --json            Emit the written entry as JSON (implies success on stdout).
   --catalog <url>   Override the catalog URL (default the public catalog).`;
 function parseEnvFlag(v, bag) {
-  if (!v || !v.includes("=")) return "--env requires KEY=value";
+  if (!v?.includes("=")) return "--env requires KEY=value";
   const eq = v.indexOf("=");
   const key = v.slice(0, eq);
   if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) return `--env: invalid KEY "${key}"`;
@@ -4776,7 +4866,7 @@ function parseAddArgs(argv) {
         break;
       case "--catalog": {
         const v = next();
-        if (!v) return { ok: false, error: "--catalog requires a URL" };
+        if (!v || v.startsWith("--")) return { ok: false, error: "--catalog requires a URL" };
         opts.catalogUrl = v;
         break;
       }
@@ -4828,7 +4918,7 @@ async function runAdd(opts) {
   }
   const namespace = deriveNamespace(server.name);
   const supplied = { ...env, ...opts.envOverrides ?? {} };
-  const missing = server.requiredEnvKeys.filter((k) => !supplied[k] || supplied[k] === "");
+  const missing = server.requiredEnvKeys.filter((k) => (supplied[k] ?? "").trim() === "");
   if (missing.length > 0) {
     printErr(`yaw-mcp add: ${server.name} needs the following env var(s) before it can run:`);
     for (const k of missing) printErr(`  - ${k}`);
@@ -4840,7 +4930,11 @@ async function runAdd(opts) {
   }
   const entryEnv = {};
   for (const k of server.requiredEnvKeys) entryEnv[k] = "";
-  for (const [k, v] of Object.entries(opts.envOverrides ?? {})) entryEnv[k] = v;
+  for (const [k, v] of Object.entries(opts.envOverrides ?? {})) {
+    const trimmed = v.trim();
+    if (trimmed === "") continue;
+    entryEnv[k] = trimmed;
+  }
   const overrides = opts.envOverrides ?? {};
   const ambientOnlyRequired = server.requiredEnvKeys.filter(
     (k) => (!overrides[k] || overrides[k] === "") && env[k] != null && env[k] !== ""
@@ -4947,7 +5041,7 @@ async function runRemove(opts) {
     printErr(`yaw-mcp remove: ${e.message}`);
     return { exitCode: 1, written: [] };
   }
-  if (!res || !res.removed) {
+  if (!res?.removed) {
     print(`yaw-mcp remove: no server matching "${opts.target}" in ${res?.path ?? "bundles.json"} (nothing to do).`);
     const shadow2 = await findShadowingProjectBundles(cwd, home).catch(() => null);
     if (shadow2) {
@@ -5037,9 +5131,11 @@ function parseLoginArgs(argv) {
     const a = argv[i];
     if (a === "--key") {
       const v = argv[++i];
-      if (!v) return { ok: false, error: `yaw-mcp login: --key requires a value
+      if (!v || v.startsWith("-")) {
+        return { ok: false, error: `yaw-mcp login: --key requires a value
 
 ${LOGIN_USAGE}` };
+      }
       opts.key = v;
     } else if (a === "--json") {
       opts.json = true;
@@ -5142,7 +5238,7 @@ async function runLogout(opts = {}, io = {
 }
 
 // src/reset-learning-cmd.ts
-import { unlink as unlink2 } from "fs/promises";
+import { readFile as readFile8, unlink as unlink2 } from "fs/promises";
 import { homedir as homedir12 } from "os";
 import { join as join9 } from "path";
 var RESET_LEARNING_USAGE = `Usage: yaw-mcp reset-learning
@@ -5154,16 +5250,15 @@ var RESET_LEARNING_USAGE = `Usage: yaw-mcp reset-learning
 
   -h, --help  Show this help.`;
 function parseResetLearningArgs(argv) {
-  for (const arg of argv) {
-    if (arg === "-h" || arg === "--help") return { kind: "help" };
-    return {
-      kind: "error",
-      error: `yaw-mcp reset-learning: unknown argument "${arg}"
+  if (argv.length === 0) return { kind: "ok", options: {} };
+  const first = argv[0];
+  if (first === "-h" || first === "--help") return { kind: "help" };
+  return {
+    kind: "error",
+    error: `yaw-mcp reset-learning: unknown argument "${first}"
 
 ${RESET_LEARNING_USAGE}`
-    };
-  }
-  return { kind: "ok", options: {} };
+  };
 }
 async function runResetLearning(opts = {}) {
   const home = opts.home ?? homedir12();
@@ -5191,6 +5286,7 @@ async function runResetLearning(opts = {}) {
   const persisted = await loadState(filePath);
   const learningCount = Object.keys(persisted.learning).length;
   const packCount = persisted.packHistory.length;
+  const parsedCleanly = await peekParsedCleanly(filePath);
   try {
     await unlink2(filePath);
   } catch (err) {
@@ -5203,12 +5299,33 @@ async function runResetLearning(opts = {}) {
     printErr(`yaw-mcp reset-learning: failed to remove ${filePath}: ${msg}`);
     return { exitCode: 1, lines, removed: false, path: filePath };
   }
+  if (!parsedCleanly) {
+    print("yaw-mcp reset-learning: cleared persisted state (contents unreadable).");
+    print(`  path: ${filePath}`);
+    return { exitCode: 0, lines, removed: true, path: filePath };
+  }
   print("yaw-mcp reset-learning: cleared persisted state.");
   print(`  path: ${filePath}`);
   print(`  learning entries removed:     ${learningCount}`);
   print(`  pack history entries removed: ${packCount}`);
   return { exitCode: 0, lines, removed: true, path: filePath };
 }
+async function peekParsedCleanly(filePath) {
+  let raw;
+  try {
+    raw = await readFile8(filePath, "utf8");
+  } catch (err) {
+    if (isFileNotFound2(err)) return true;
+    return false;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object") return false;
+    return parsed.version === STATE_SCHEMA_VERSION;
+  } catch {
+    return false;
+  }
+}
 function isFileNotFound2(err) {
   return !!err && typeof err === "object" && "code" in err && err.code === "ENOENT";
 }
@@ -5219,7 +5336,7 @@ import { homedir as homedir14 } from "os";
 
 // src/secrets-vault.ts
 import { existsSync as existsSync5 } from "fs";
-import { chmod as chmod3, readFile as readFile8 } from "fs/promises";
+import { chmod as chmod3, readFile as readFile9 } from "fs/promises";
 import { homedir as homedir13 } from "os";
 import { join as join10 } from "path";
 
@@ -5294,7 +5411,7 @@ async function loadVault(path5) {
   if (!existsSync5(path5)) return null;
   let raw;
   try {
-    raw = await readFile8(path5, "utf8");
+    raw = await readFile9(path5, "utf8");
   } catch (err) {
     log("warn", "Failed to read vault", { path: path5, error: err instanceof Error ? err.message : String(err) });
     return null;
@@ -5330,7 +5447,7 @@ function isEncryptedEntry(v) {
 }
 async function saveVault(path5, vault) {
   await atomicWriteFile(path5, `${JSON.stringify(vault, null, 2)}
-`);
+`, "utf8", 384);
   if (process.platform !== "win32") {
     try {
       await chmod3(path5, 384);
@@ -5443,6 +5560,10 @@ Actions:
                           line, no echo). Override with --value <v> or
                           --stdin (raw, multi-line) for scripting.
   get <name>              Decrypt and print one secret value to stdout.
+                          NOTE: this prints the secret in CLEARTEXT (with
+                          or without --json). Redirect to a file or pipe
+                          to a consumer; avoid running it interactively so
+                          the value does not land in terminal scrollback.
   list                    Show vault entry names (values stay encrypted).
   remove <name>           Delete an entry.
   lock                    Clear the in-process passphrase cache.
@@ -5487,9 +5608,14 @@ function parseSecretsArgs(argv) {
     }
     if (a === "--value") {
       const v = argv[++i];
-      if (v === void 0) return { ok: false, error: `yaw-mcp secrets: --value requires a value
+      if (v === void 0 || v.startsWith("-")) {
+        return {
+          ok: false,
+          error: `yaw-mcp secrets: --value requires a value (for a dash-leading value use --stdin)
 
-${SECRETS_USAGE}` };
+${SECRETS_USAGE}`
+        };
+      }
       opts.value = v;
       continue;
     }
@@ -5564,7 +5690,7 @@ function readPassphraseFromTTY(stdin, stdout, prompt = "Vault passphrase: ") {
     stdin.setEncoding("utf8");
     const onData = (chunk) => {
       for (const ch of chunk) {
-        if (ch === "\n" || ch === "\r" || ch === "") {
+        if (ch === "\n" || ch === "\r") {
           stdout.write("\n");
           stdin.removeListener("data", onData);
           try {
@@ -5575,6 +5701,17 @@ function readPassphraseFromTTY(stdin, stdout, prompt = "Vault passphrase: ") {
           resolve7(chunks.join(""));
           return;
         }
+        if (ch === "") {
+          stdout.write("\n");
+          stdin.removeListener("data", onData);
+          try {
+            stdin.setRawMode?.(wasRaw);
+          } catch {
+          }
+          stdin.pause();
+          resolve7("");
+          return;
+        }
         if (ch === "") {
           stdout.write("\n");
           process.exit(130);
@@ -5589,11 +5726,11 @@ function readPassphraseFromTTY(stdin, stdout, prompt = "Vault passphrase: ") {
     stdin.on("data", onData);
   });
 }
-async function readStdinValue(io) {
+async function readStdinValue(io, forceRaw) {
   const stdin = io?.stdin ?? process.stdin;
   const stdout = io?.stdout ?? process.stdout;
   const isTTY = stdin.isTTY === true;
-  if (isTTY) {
+  if (isTTY && !forceRaw) {
     stdout.write("Secret value: ");
     return readPassphraseFromTTY(stdin, stdout);
   }
@@ -5638,6 +5775,18 @@ async function runSecrets(opts, io = {
     }
     return { exitCode: 0 };
   }
+  if (opts.action === "get" || opts.action === "remove") {
+    const existingVault = await loadVault(path5);
+    if (!existingVault || !(opts.name in existingVault.entries)) {
+      const name = opts.name;
+      const msg = `No secret named "${name}" in the vault.`;
+      if (opts.json) io.err(`${JSON.stringify({ ok: false, error: msg })}
+`);
+      else io.err(`yaw-mcp secrets: ${msg}
+`);
+      return { exitCode: 1 };
+    }
+  }
   let vault = await loadVault(path5) ?? newVault();
   const isFresh = !existsSync6(path5);
   const passphrase = await resolvePassphrase(opts);
@@ -5664,7 +5813,7 @@ async function runSecrets(opts, io = {
     const name = opts.name;
     let value;
     if (opts.value !== void 0) value = opts.value;
-    else value = await readStdinValue(opts.io);
+    else value = await readStdinValue(opts.io, opts.fromStdin);
     if (!value) {
       const msg = "Secret value cannot be empty.";
       if (opts.json) io.err(`${JSON.stringify({ ok: false, error: msg })}
@@ -5693,6 +5842,14 @@ async function runSecrets(opts, io = {
 `);
         return { exitCode: 1 };
       }
+      const outStream = opts.io?.stdout ?? process.stdout;
+      if (outStream.isTTY === true) {
+        const stderr = opts.io?.stderr ?? process.stderr;
+        stderr.write(
+          `yaw-mcp secrets: warning -- printing "${name}" in cleartext to your terminal; it will remain in scrollback.
+`
+        );
+      }
       if (opts.json) io.out(`${JSON.stringify({ ok: true, name, value })}
 `);
       else io.out(`${value}
@@ -5811,9 +5968,9 @@ async function runSecretsPull(opts, io) {
     const remote = await getResource(MCP_SECRETS_RESOURCE, { home, baseUrl: opts.baseUrl });
     const remoteEntries = remote.data?.entries;
     const remoteHasEntries = remoteEntries !== void 0 && remoteEntries !== null && typeof remoteEntries === "object" && Object.keys(remoteEntries).length > 0;
-    if (!remote.data || !remote.data.salt || !remoteHasEntries) {
+    if (!remote.data?.salt || !remoteHasEntries) {
       const msg = "Remote mcp_secrets is empty. Push from this machine to seed it.";
-      if (opts.json) io.out(`${JSON.stringify({ ok: true, empty: true })}
+      if (opts.json) io.out(`${JSON.stringify({ ok: true, empty: true, message: msg })}
 `);
       else io.out(`${msg}
 `);
@@ -5864,7 +6021,7 @@ async function runSecretsPull(opts, io) {
 }
 
 // src/server.ts
-import { readFile as readFile10 } from "fs/promises";
+import { readFile as readFile11 } from "fs/promises";
 import { homedir as homedir15 } from "os";
 import { isAbsolute as isAbsolute2, relative, resolve as resolve6 } from "path";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -5930,7 +6087,7 @@ function defaultSpawn2(cmd, args) {
 async function maybeAutoUpgrade(deps = {}) {
   const optOut = process.env.YAW_MCP_AUTO_UPGRADE;
   if (optOut === "0" || optOut?.toLowerCase() === "false") return;
-  const current = deps.currentVersion ?? (true ? "0.62.0" : "dev");
+  const current = deps.currentVersion ?? (true ? "0.63.1" : "dev");
   if (current === "dev") return;
   const method = (deps.isSeaImpl ? await deps.isSeaImpl() : await detectSea()) ? "binary" : detectInstallMethod(deps.argvPath ?? process.argv[1]);
   const latest = await (deps.fetchLatestImpl ?? fetchLatestVersion2)();
@@ -6365,14 +6522,76 @@ function stepBindingKey(step, index) {
   return typeof step.id === "string" && step.id.length > 0 ? step.id : String(index);
 }
 
+// src/fuzzy.ts
+function levenshtein(a, b) {
+  if (a === b) return 0;
+  const aLen = a.length;
+  const bLen = b.length;
+  if (aLen === 0) return bLen;
+  if (bLen === 0) return aLen;
+  let prev = new Array(bLen + 1);
+  let curr = new Array(bLen + 1);
+  for (let j = 0; j <= bLen; j++) prev[j] = j;
+  for (let i = 1; i <= aLen; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= bLen; j++) {
+      const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1;
+      curr[j] = Math.min(
+        curr[j - 1] + 1,
+        // insertion
+        prev[j] + 1,
+        // deletion
+        prev[j - 1] + cost
+        // substitution
+      );
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[bLen];
+}
+function closestNames(query, candidates, limit) {
+  if (limit <= 0) return [];
+  const q = query.toLowerCase();
+  const scored = [];
+  for (const c of candidates) {
+    if (c === query) continue;
+    const lc = c.toLowerCase();
+    let score = null;
+    if (lc === q) {
+      score = 0;
+    } else if (lc.startsWith(q) || q.startsWith(lc)) {
+      score = 1;
+    } else if (
+      // Substring containment is only a credible "typo" signal when the
+      // query is long enough to be specific AND the shorter string covers
+      // at least half the longer one. Without these gates a 1-2 char query
+      // ("ls", "set") substring-matches long commands ("list", "set-active",
+      // "secrets") and surfaces misleading suggestions the header calls
+      // conservative. The Levenshtein tier still catches genuine short typos.
+      q.length >= 3 && (lc.includes(q) || q.includes(lc)) && Math.min(q.length, lc.length) * 2 >= Math.max(q.length, lc.length)
+    ) {
+      score = 2;
+    } else {
+      const d = levenshtein(q, lc);
+      if (d <= 2) score = 2 + d;
+    }
+    if (score !== null) scored.push({ name: c, score });
+  }
+  scored.sort((a, b) => {
+    if (a.score !== b.score) return a.score - b.score;
+    return a.name.localeCompare(b.name);
+  });
+  return scored.slice(0, limit).map((s) => s.name);
+}
+
 // src/guide.ts
-import { readFile as readFile9 } from "fs/promises";
+import { readFile as readFile10 } from "fs/promises";
 var GUIDE_READ_TIMEOUT_MS = 1e3;
 async function readGuide(path5, scope) {
   let raw;
   try {
     raw = await Promise.race([
-      readFile9(path5, "utf8"),
+      readFile10(path5, "utf8"),
       new Promise(
         (_, reject) => setTimeout(() => reject(new Error("guide read timeout")), GUIDE_READ_TIMEOUT_MS)
       )
@@ -7187,7 +7406,7 @@ var PackDetector = class {
   loadSnapshot(snapshot) {
     const clean = [];
     for (const c of snapshot) {
-      if (!c || !c.namespace || !c.toolName) continue;
+      if (!c?.namespace || !c.toolName) continue;
       clean.push({ namespace: c.namespace, toolName: c.toolName, at: c.at });
     }
     if (clean.length > this.maxHistory) {
@@ -7374,7 +7593,7 @@ async function routeResourceRead(uri, resourceRoutes, activeConnections, builtin
     return { contents: [{ uri, text: `Unknown resource: ${uri}` }] };
   }
   const connection = activeConnections.get(route.namespace);
-  if (!connection || connection.status !== "connected") {
+  if (connection?.status !== "connected") {
     return { contents: [{ uri, text: `Server "${route.namespace}" is not connected.` }] };
   }
   try {
@@ -7392,7 +7611,7 @@ async function routePromptGet(name, args, promptRoutes, activeConnections) {
     return { messages: [{ role: "user", content: { type: "text", text: `Unknown prompt: ${name}` } }] };
   }
   const connection = activeConnections.get(route.namespace);
-  if (!connection || connection.status !== "connected") {
+  if (connection?.status !== "connected") {
     return {
       messages: [{ role: "user", content: { type: "text", text: `Server "${route.namespace}" is not connected.` } }]
     };
@@ -7420,7 +7639,7 @@ async function routeToolCall(toolName, args, toolRoutes, activeConnections) {
     };
   }
   const connection = activeConnections.get(route.namespace);
-  if (!connection || connection.status !== "connected") {
+  if (connection?.status !== "connected") {
     return {
       content: [
         {
@@ -7731,10 +7950,50 @@ async function callLegacyRerank(payload) {
   }
 }
 async function readTeamCookie() {
-  const teamSync = await import("./team-sync-B4R6FLKR.js");
+  const teamSync = await import("./team-sync-OONB72BJ.js");
   return teamSync.getCachedCookie();
 }
 
+// src/reward.ts
+var ERROR_SHAPED_CATEGORIES = /* @__PURE__ */ new Set([
+  "validation_error",
+  "timeout",
+  "unauthorized",
+  "unknown_tool",
+  "connection_lost",
+  "rate_limited",
+  "not_found"
+]);
+function firstTextBlock(result) {
+  const content = result.content;
+  if (!content || content.length === 0) return void 0;
+  for (const block of content) {
+    if (typeof block.text === "string" && block.text.trim().length > 0) return block.text;
+  }
+  return void 0;
+}
+function isEmptyBody(result) {
+  const content = result.content;
+  if (!content || content.length === 0) return true;
+  for (const block of content) {
+    if (typeof block.text === "string" && block.text.trim().length > 0) {
+      return false;
+    }
+  }
+  return true;
+}
+function computeOutcomeReward(result) {
+  if (result.isError === true) return 0;
+  const text = firstTextBlock(result);
+  if (text !== void 0) {
+    if (ERROR_SHAPED_CATEGORIES.has(classifyError(text))) {
+      return 0.2;
+    }
+  }
+  if (isEmptyBody(result)) return 0.3;
+  return 1;
+}
+
 // src/reward-grader.ts
 function isRewardGraderEnabled() {
   const raw = process.env.YAW_MCP_REWARD_GRADER;
@@ -7836,46 +8095,6 @@ function extractText(content) {
   return "";
 }
 
-// src/reward.ts
-var ERROR_SHAPED_CATEGORIES = /* @__PURE__ */ new Set([
-  "validation_error",
-  "timeout",
-  "unauthorized",
-  "unknown_tool",
-  "connection_lost",
-  "rate_limited",
-  "not_found"
-]);
-function firstTextBlock(result) {
-  const content = result.content;
-  if (!content || content.length === 0) return void 0;
-  for (const block of content) {
-    if (typeof block.text === "string" && block.text.trim().length > 0) return block.text;
-  }
-  return void 0;
-}
-function isEmptyBody(result) {
-  const content = result.content;
-  if (!content || content.length === 0) return true;
-  for (const block of content) {
-    if (typeof block.text === "string" && block.text.trim().length > 0) {
-      return false;
-    }
-  }
-  return true;
-}
-function computeOutcomeReward(result) {
-  if (result.isError === true) return 0;
-  const text = firstTextBlock(result);
-  if (text !== void 0) {
-    if (ERROR_SHAPED_CATEGORIES.has(classifyError(text))) {
-      return 0.2;
-    }
-  }
-  if (isEmptyBody(result)) return 0.3;
-  return 1;
-}
-
 // src/runtime-detect.ts
 import { spawn as spawn4 } from "child_process";
 import { request as request8 } from "undici";
@@ -8194,7 +8413,9 @@ async function bestOfNViaSampling(server, intent, candidates, n) {
     }
     if (votes.size === 0) return null;
     const order = /* @__PURE__ */ new Map();
-    candidates.forEach((c, i) => order.set(c.namespace, i));
+    candidates.forEach((c, i) => {
+      order.set(c.namespace, i);
+    });
     let winner = null;
     let bestVotes = -1;
     let bestRank = Number.POSITIVE_INFINITY;
@@ -8557,7 +8778,7 @@ function categorizeSpawnError(err) {
 }
 async function connectToUpstream(config, onDisconnect, onListChanged) {
   const client = new Client(
-    { name: "yaw-mcp", version: true ? "0.62.0" : "dev" },
+    { name: "yaw-mcp", version: true ? "0.63.1" : "dev" },
     { capabilities: {} }
   );
   let transport;
@@ -8884,7 +9105,7 @@ var ConnectServer = class _ConnectServer {
     this.apiUrl = apiUrl5;
     this.token = token5;
     this.server = new Server(
-      { name: "yaw-mcp", version: true ? "0.62.0" : "dev" },
+      { name: "yaw-mcp", version: true ? "0.63.1" : "dev" },
       {
         capabilities: {
           tools: { listChanged: true },
@@ -10484,7 +10705,7 @@ ${activeCount} loaded in this session, ${totalTools} tools in context${tokenSumm
     let changed = false;
     for (const [namespace, connection] of this.connections) {
       const newServerConfig = newServersByNs.get(namespace);
-      if (!newServerConfig || !newServerConfig.isActive) {
+      if (!newServerConfig?.isActive) {
         log("info", "Server removed or disabled in config, deactivating", { namespace });
         await disconnectFromUpstream(connection);
         this.connections.delete(namespace);
@@ -10582,7 +10803,7 @@ ${activeCount} loaded in this session, ${totalTools} tools in context${tokenSumm
           isError: true
         };
       }
-      const raw = await readFile10(resolved, "utf-8");
+      const raw = await readFile11(resolved, "utf-8");
       const parsed = JSON.parse(raw);
       if (!parsed.mcpServers || typeof parsed.mcpServers !== "object" || Array.isArray(parsed.mcpServers)) {
         return {
@@ -11386,7 +11607,7 @@ import { homedir as homedir16 } from "os";
 
 // src/sync-state.ts
 import { existsSync as existsSync7 } from "fs";
-import { mkdir as mkdir4, readFile as readFile11 } from "fs/promises";
+import { mkdir as mkdir4, readFile as readFile12 } from "fs/promises";
 import { dirname as dirname2, join as join11 } from "path";
 var SYNC_STATE_FILENAME = "sync-state.json";
 function syncStatePath(home) {
@@ -11396,7 +11617,7 @@ async function readSyncState(home) {
   const path5 = syncStatePath(home);
   if (!existsSync7(path5)) return {};
   try {
-    const raw = await readFile11(path5, "utf8");
+    const raw = await readFile12(path5, "utf8");
     const parsed = JSON.parse(raw);
     if (!parsed || typeof parsed !== "object") return {};
     return parsed;
@@ -11644,7 +11865,11 @@ function formatPlain(events, opts, orderId, total) {
     lines.push(`  ${c.client.padEnd(24)}  ${c.total} calls`);
   }
   lines.push("");
-  lines.push("Recent events (newest first):");
+  if (events.length > renderedCount) {
+    lines.push("Recent events (newest first, capped at --limit; By-server / By-AI-client above span the full window):");
+  } else {
+    lines.push("Recent events (newest first):");
+  }
   const recent = events.slice(-Math.min(events.length, opts.limit ?? 50)).reverse();
   for (const e of recent) {
     const when = new Date(e.ts).toISOString().replace("T", " ").slice(0, 19);
@@ -11715,9 +11940,45 @@ async function runStats(opts, io = {
   }
 }
 
+// src/subcommands.ts
+var FLAG_ALIASES = ["--help", "-h", "--version", "-V"];
+var KNOWN_SUBCOMMANDS = [
+  "compliance",
+  "audit",
+  "foundry",
+  "install",
+  "add",
+  "remove",
+  "list",
+  "doctor",
+  "reset-learning",
+  "servers",
+  "bundles",
+  "completion",
+  "upgrade",
+  "try",
+  "try-cleanup",
+  "login",
+  "logout",
+  "sync",
+  "stats",
+  "secrets",
+  "set-active",
+  "help",
+  ...FLAG_ALIASES
+];
+function suggestSubcommand(input, limit = 3) {
+  const visible = KNOWN_SUBCOMMANDS.filter((s) => !s.startsWith("-"));
+  return closestNames(input, visible, limit);
+}
+function suggestFlag(input, limit = 2) {
+  if (input.length <= 2) return [];
+  return closestNames(input, FLAG_ALIASES, limit);
+}
+
 // src/sync-cmd.ts
 import { existsSync as existsSync8 } from "fs";
-import { mkdir as mkdir5, readFile as readFile12 } from "fs/promises";
+import { mkdir as mkdir5, readFile as readFile13 } from "fs/promises";
 import { homedir as homedir18 } from "os";
 import { dirname as dirname3, join as join12 } from "path";
 var SYNC_USAGE = `Usage: yaw-mcp sync <push|pull|status> [--json]
@@ -11771,7 +12032,7 @@ function bundlesPath(home) {
 async function readLocalBundles(home) {
   const path5 = bundlesPath(home);
   if (!existsSync8(path5)) return { version: 1, servers: [] };
-  const raw = await readFile12(path5, "utf8");
+  const raw = await readFile13(path5, "utf8");
   let parsed;
   try {
     parsed = JSON.parse(raw);
@@ -11932,13 +12193,28 @@ async function syncPull(opts, io, home) {
 }
 async function syncPush(opts, io, home) {
   const local = await readLocalBundles(home);
+  const stripped = local.servers.map(stripEnvValues);
+  if (opts.dryRun) {
+    if (opts.json) {
+      io.out(
+        `${JSON.stringify({ ok: true, dryRun: true, serverCount: stripped.length }, null, 2)}
+`
+      );
+    } else {
+      io.out(
+        `[dry-run] would push ${stripped.length} server${stripped.length === 1 ? "" : "s"} (env values stripped); nothing sent.
+`
+      );
+    }
+    return { exitCode: 0 };
+  }
   const remote = await getResource(MCP_BUNDLES_RESOURCE, {
     home: opts.home,
     baseUrl: opts.baseUrl
   });
   const remoteServers = remote.data?.servers ?? [];
-  const stripped = mergeRemoteActive(local.servers.map(stripEnvValues), remoteServers);
-  const payload = { version: 1, servers: stripped };
+  const merged = mergeRemoteActive(stripped, remoteServers);
+  const payload = { version: 1, servers: merged };
   const syncState = await readSyncState(home);
   const lastPulled = syncState.mcp_bundles?.lastPulledVersion;
   const pushVersion = lastPulled ?? remote.version;
@@ -11948,10 +12224,10 @@ async function syncPush(opts, io, home) {
   });
   await writeSyncState(home, { mcp_bundles: { lastPulledVersion: res.version } });
   if (opts.json) {
-    io.out(`${JSON.stringify({ ok: true, serverCount: stripped.length, newVersion: res.version }, null, 2)}
+    io.out(`${JSON.stringify({ ok: true, serverCount: merged.length, newVersion: res.version }, null, 2)}
 `);
   } else {
-    io.out(`Pushed ${stripped.length} server${stripped.length === 1 ? "" : "s"} -> mcp_bundles v${res.version}.
+    io.out(`Pushed ${merged.length} server${merged.length === 1 ? "" : "s"} -> mcp_bundles v${res.version}.
 `);
     io.out("Env values stripped before upload; use `yaw-mcp secrets push` to sync secrets across machines.\n");
   }
@@ -11989,45 +12265,30 @@ function handleSyncError(err, opts, io) {
 }
 
 // src/index.ts
-var KNOWN_SUBCOMMANDS = [
-  "compliance",
-  "audit",
-  "foundry",
-  "install",
-  "add",
-  "remove",
-  "list",
-  "doctor",
-  "reset-learning",
-  "servers",
-  "bundles",
-  "completion",
-  "upgrade",
-  "try",
-  "try-cleanup",
-  "login",
-  "logout",
-  "sync",
-  "stats",
-  "secrets",
-  "set-active",
-  "help",
-  "--help",
-  "-h",
-  "--version",
-  "-V"
-];
+function dispatch(cmd, p) {
+  p.then((r) => process.exit(typeof r === "number" ? r : r.exitCode)).catch((err) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`yaw-mcp ${cmd}: ${msg}
+`);
+    process.exit(1);
+  });
+}
 var subcommand = process.argv[2];
 if (subcommand === "compliance") {
-  runComplianceCommand(process.argv.slice(3)).then((code) => process.exit(code));
+  dispatch("compliance", runComplianceCommand(process.argv.slice(3)));
 } else if (subcommand === "audit") {
   const parsed = parseAuditArgs(process.argv.slice(3));
   if (!parsed.ok) {
+    if (parsed.help) {
+      process.stdout.write(`${parsed.error}
+`);
+      process.exit(0);
+    }
     process.stderr.write(`${parsed.error}
 `);
     process.exit(2);
   }
-  runAudit(parsed.options).then((r) => process.exit(r.exitCode));
+  dispatch("audit", runAudit(parsed.options));
 } else if (subcommand === "foundry") {
   const parsed = parseFoundryArgs(process.argv.slice(3));
   if (!parsed.ok) {
@@ -12036,7 +12297,7 @@ if (subcommand === "compliance") {
 `);
     process.exit(isHelp ? 0 : 2);
   }
-  runFoundryExport(parsed.options).then((r) => process.exit(r.exitCode));
+  dispatch("foundry", runFoundryExport(parsed.options));
 } else if (subcommand === "install") {
   const parsed = parseInstallArgs(process.argv.slice(3));
   if (!parsed.ok) {
@@ -12050,23 +12311,28 @@ if (subcommand === "compliance") {
     process.exit(2);
   }
   const claudeConfigDir = process.env.CLAUDE_CONFIG_DIR && process.env.CLAUDE_CONFIG_DIR.length > 0 ? process.env.CLAUDE_CONFIG_DIR : void 0;
-  runInstall({ ...parsed.options, claudeConfigDir }).then((r) => process.exit(r.exitCode));
+  dispatch("install", runInstall({ ...parsed.options, claudeConfigDir }));
 } else if (subcommand === "doctor") {
   const doctorArgs = process.argv.slice(3);
   const doctorJson = doctorArgs.includes("--json");
-  const doctorUnknown = doctorArgs.find((a) => a !== "--json" && a !== "--help" && a !== "-h");
-  if (doctorArgs.includes("--help") || doctorArgs.includes("-h")) {
+  const isHelpArg = (a) => a === "--help" || a === "-h";
+  const doctorUnknowns = doctorArgs.filter((a) => a !== "--json" && !isHelpArg(a));
+  const firstHelpIdx = doctorArgs.findIndex(isHelpArg);
+  const firstUnknownIdx = doctorArgs.findIndex((a) => a !== "--json" && !isHelpArg(a));
+  const helpWins = firstHelpIdx !== -1 && (firstUnknownIdx === -1 || firstHelpIdx < firstUnknownIdx);
+  if (helpWins) {
     process.stdout.write(
       "Usage: yaw-mcp doctor [--json]\n\n  Print a diagnostic of your yaw-mcp setup.\n\n  --json  Emit machine-readable JSON instead of text.\n"
     );
     process.exit(0);
   }
-  if (doctorUnknown) {
-    process.stderr.write(`yaw-mcp doctor: unknown argument "${doctorUnknown}"
+  if (doctorUnknowns.length > 0) {
+    const quoted = doctorUnknowns.map((a) => `"${a}"`).join(", ");
+    process.stderr.write(`yaw-mcp doctor: unknown argument${doctorUnknowns.length > 1 ? "s" : ""} ${quoted}
 `);
     process.exit(2);
   }
-  runDoctor({ json: doctorJson }).then((r) => process.exit(r.exitCode));
+  dispatch("doctor", runDoctor({ json: doctorJson }));
 } else if (subcommand === "reset-learning") {
   const parsed = parseResetLearningArgs(process.argv.slice(3));
   if (parsed.kind === "help") {
@@ -12079,7 +12345,7 @@ if (subcommand === "compliance") {
 `);
     process.exit(2);
   }
-  runResetLearning().then((r) => process.exit(r.exitCode));
+  dispatch("reset-learning", runResetLearning());
 } else if (subcommand === "servers") {
   const parsed = parseServersArgs(process.argv.slice(3));
   if (!parsed.ok) {
@@ -12092,7 +12358,7 @@ if (subcommand === "compliance") {
 `);
     process.exit(2);
   }
-  runServersCommand(parsed.options).then((r) => process.exit(r.exitCode));
+  dispatch("servers", runServersCommand(parsed.options));
 } else if (subcommand === "bundles") {
   const parsed = parseBundlesArgs(process.argv.slice(3));
   if (!parsed.ok) {
@@ -12105,7 +12371,7 @@ if (subcommand === "compliance") {
 `);
     process.exit(2);
   }
-  runBundlesCommand(parsed.options).then((r) => process.exit(r.exitCode));
+  dispatch("bundles", runBundlesCommand(parsed.options));
 } else if (subcommand === "completion") {
   const parsed = parseCompletionArgs(process.argv.slice(3));
   if (!parsed.ok) {
@@ -12118,7 +12384,7 @@ if (subcommand === "compliance") {
 `);
     process.exit(2);
   }
-  runCompletion(parsed.options).then((r) => process.exit(r.exitCode));
+  dispatch("completion", runCompletion(parsed.options));
 } else if (subcommand === "upgrade") {
   const parsed = parseUpgradeArgs(process.argv.slice(3));
   if (!parsed.ok) {
@@ -12131,7 +12397,7 @@ if (subcommand === "compliance") {
 `);
     process.exit(2);
   }
-  runUpgrade(parsed.options).then((r) => process.exit(r.exitCode));
+  dispatch("upgrade", runUpgrade(parsed.options));
 } else if (subcommand === "try") {
   const parsed = parseTryArgs(process.argv.slice(3));
   if (!parsed.ok) {
@@ -12144,7 +12410,7 @@ if (subcommand === "compliance") {
 `);
     process.exit(2);
   }
-  runTry(parsed.options).then((r) => process.exit(r.exitCode));
+  dispatch("try", runTry(parsed.options));
 } else if (subcommand === "try-cleanup") {
   const parsed = parseTryCleanupArgs(process.argv.slice(3));
   if (!parsed.ok) {
@@ -12157,7 +12423,7 @@ if (subcommand === "compliance") {
 `);
     process.exit(2);
   }
-  runTryCleanup(parsed.options).then((r) => process.exit(r.exitCode));
+  dispatch("try-cleanup", runTryCleanup(parsed.options));
 } else if (subcommand === "add") {
   const parsed = parseAddArgs(process.argv.slice(3));
   if (!parsed.ok) {
@@ -12170,7 +12436,7 @@ if (subcommand === "compliance") {
 `);
     process.exit(2);
   }
-  runAdd(parsed.options).then((r) => process.exit(r.exitCode));
+  dispatch("add", runAdd(parsed.options));
 } else if (subcommand === "remove") {
   const parsed = parseRemoveArgs(process.argv.slice(3));
   if (!parsed.ok) {
@@ -12183,7 +12449,7 @@ if (subcommand === "compliance") {
 `);
     process.exit(2);
   }
-  runRemove(parsed.options).then((r) => process.exit(r.exitCode));
+  dispatch("remove", runRemove(parsed.options));
 } else if (subcommand === "list") {
   const parsed = parseListArgs(process.argv.slice(3));
   if (!parsed.ok) {
@@ -12196,7 +12462,7 @@ if (subcommand === "compliance") {
 `);
     process.exit(2);
   }
-  runList(parsed.options).then((r) => process.exit(r.exitCode));
+  dispatch("list", runList(parsed.options));
 } else if (subcommand === "login") {
   const parsed = parseLoginArgs(process.argv.slice(3));
   if (!parsed.ok) {
@@ -12209,7 +12475,7 @@ if (subcommand === "compliance") {
 `);
     process.exit(2);
   }
-  runLogin(parsed.options).then((r) => process.exit(r.exitCode));
+  dispatch("login", runLogin(parsed.options));
 } else if (subcommand === "logout") {
   const parsed = parseLogoutArgs(process.argv.slice(3));
   if (!parsed.ok) {
@@ -12222,7 +12488,7 @@ if (subcommand === "compliance") {
 `);
     process.exit(2);
   }
-  runLogout(parsed.options).then((r) => process.exit(r.exitCode));
+  dispatch("logout", runLogout(parsed.options));
 } else if (subcommand === "sync") {
   const parsed = parseSyncArgs(process.argv.slice(3));
   if (!parsed.ok) {
@@ -12235,7 +12501,7 @@ if (subcommand === "compliance") {
 `);
     process.exit(2);
   }
-  runSync(parsed.options).then((r) => process.exit(r.exitCode));
+  dispatch("sync", runSync(parsed.options));
 } else if (subcommand === "stats") {
   const parsed = parseStatsArgs(process.argv.slice(3));
   if (!parsed.ok) {
@@ -12248,7 +12514,7 @@ if (subcommand === "compliance") {
 `);
     process.exit(2);
   }
-  runStats(parsed.options).then((r) => process.exit(r.exitCode));
+  dispatch("stats", runStats(parsed.options));
 } else if (subcommand === "secrets") {
   const parsed = parseSecretsArgs(process.argv.slice(3));
   if (!parsed.ok) {
@@ -12261,7 +12527,7 @@ if (subcommand === "compliance") {
 `);
     process.exit(2);
   }
-  runSecrets(parsed.options).then((r) => process.exit(r.exitCode));
+  dispatch("secrets", runSecrets(parsed.options));
 } else if (subcommand === "set-active") {
   const parsed = parseSetActiveArgs(process.argv.slice(3));
   if (!parsed.ok) {
@@ -12274,7 +12540,7 @@ if (subcommand === "compliance") {
 `);
     process.exit(2);
   }
-  runSetActive(parsed.options).then((r) => process.exit(r.exitCode));
+  dispatch("set-active", runSetActive(parsed.options));
 } else if (subcommand === "--help" || subcommand === "-h" || subcommand === "help") {
   process.stdout.write(`
   yaw-mcp \u2014 one install, every MCP server, managed from the cloud.
@@ -12365,9 +12631,9 @@ if (subcommand === "compliance") {
                                gate (default: a clearly-winning server is
                                activated in the same call).
     YAW_MCP_AUTO_UPGRADE          Set to \`0\` to disable the background
-                               self-upgrade check at \`yaw-mcp serve\` startup
-                               (default: stale global-npm installs are
-                               upgraded in the background).
+                               self-upgrade check at server startup (default:
+                               stale global-npm installs are upgraded in the
+                               background).
     YAW_MCP_PRUNE_RESPONSES       Set to \`0\` to disable response pruning.
     YAW_MCP_DISABLE_PERSISTENCE   Disable cross-session learning state.
     YAW_MCP_CATALOG_URL          Override the catalog \`add\`/\`try\` resolve slugs
@@ -12391,16 +12657,20 @@ if (subcommand === "compliance") {
 `);
   process.exit(0);
 } else if (subcommand === "--version" || subcommand === "-V") {
-  process.stdout.write(`yaw-mcp ${true ? "0.62.0" : "dev"}
+  process.stdout.write(`yaw-mcp ${true ? "0.63.1" : "dev"}
 `);
   process.exit(0);
 } else if (subcommand && !subcommand.startsWith("-")) {
-  const visible = KNOWN_SUBCOMMANDS.filter((s) => !s.startsWith("-") && s !== "help");
-  const suggestions = closestNames(subcommand, visible, 3);
+  const suggestions = suggestSubcommand(subcommand);
   const hint = suggestions.length > 0 ? ` Did you mean: ${suggestions.join(", ")}?` : " Run `yaw-mcp --help` for the list of subcommands.";
   process.stderr.write(`yaw-mcp: unknown subcommand "${subcommand}".${hint}
 `);
   process.exit(2);
+} else if (subcommand && suggestFlag(subcommand).length > 0) {
+  const suggestions = suggestFlag(subcommand);
+  process.stderr.write(`yaw-mcp: unknown flag "${subcommand}". Did you mean: ${suggestions.join(", ")}?
+`);
+  process.exit(2);
 } else {
   runServer();
 }