@yawlabs/mcph 0.52.0 → 0.54.0

package/dist/index.js

@@ -245,9 +245,9 @@ async function migrateLegacyConfigPaths(opts) {
   }
 }
 async function findLegacyProjectRoot(cwd, home) {
-  const { resolve: resolve4, dirname: dirname2 } = await import("path");
-  const homeResolved = resolve4(home);
-  let dir = resolve4(cwd);
+  const { resolve: resolve5, dirname: dirname2 } = await import("path");
+  const homeResolved = resolve5(home);
+  let dir = resolve5(cwd);
   let prev = "";
   while (dir !== prev) {
     if (dir === homeResolved) return null;
@@ -921,7 +921,7 @@ Delete token (save this): ${result.deleteToken}
   return 0;
 }
 function runTest(args) {
-  return new Promise((resolve4) => {
+  return new Promise((resolve5) => {
     const child = spawn("npx", ["-y", "@yawlabs/mcp-compliance", "test", "--format", "json", ...args], {
       stdio: ["ignore", "pipe", "inherit"],
       shell: process.platform === "win32"
@@ -934,7 +934,7 @@ function runTest(args) {
       process.stderr.write(`
 Failed to launch mcp-compliance: ${err.message}
 `);
-      resolve4(null);
+      resolve5(null);
     });
     child.on("close", (code) => {
       try {
@@ -943,15 +943,15 @@ Failed to launch mcp-compliance: ${err.message}
           process.stderr.write(`
 mcp-compliance returned unexpected JSON (exit ${code}).
 `);
-          resolve4(null);
+          resolve5(null);
           return;
         }
-        resolve4(parsed);
+        resolve5(parsed);
       } catch {
         process.stderr.write(`
 mcp-compliance exited ${code} without valid JSON output.
 `);
-        resolve4(null);
+        resolve5(null);
       }
     });
   });
@@ -990,10 +990,10 @@ Publish failed: ${err?.message ?? String(err)}
 }
 
 // src/doctor-cmd.ts
-import { existsSync, readFileSync, statSync } from "fs";
-import { readFile as readFile3 } from "fs/promises";
-import { homedir as homedir4 } from "os";
-import { join as join4 } from "path";
+import { existsSync as existsSync3, readFileSync, statSync } from "fs";
+import { readFile as readFile5 } from "fs/promises";
+import { homedir as homedir6 } from "os";
+import { join as join6 } from "path";
 
 // src/analytics.ts
 import { request as request3 } from "undici";
@@ -1453,6 +1453,17 @@ function pathFor(client, scope, os, base) {
   throw new Error(`Unhandled client: ${client}`);
 }
 function buildLaunchEntry(opts) {
+  if (opts.upstream) {
+    const { command, args, env } = opts.upstream;
+    if (opts.os === "windows") {
+      const wrapped = { command: "cmd", args: ["/c", command, ...args] };
+      if (env && Object.keys(env).length > 0) wrapped.env = { ...env };
+      return wrapped;
+    }
+    const entry2 = { command, args: [...args] };
+    if (env && Object.keys(env).length > 0) entry2.env = { ...env };
+    return entry2;
+  }
   const pkg = opts.pkg ?? "@yawlabs/mcph@latest";
   const entry = opts.os === "windows" ? { command: "cmd", args: ["/c", "npx", "-y", pkg] } : { command: "npx", args: ["-y", pkg] };
   if (opts.token) entry.env = { MCPH_TOKEN: opts.token };
@@ -1609,1236 +1620,1817 @@ async function reportTools(serverId, tools) {
   }
 }
 
-// src/usage-hints.ts
-var MAX_PEERS = 3;
-var MIN_SUCCESS_TO_SHOW = 1;
-var RELIABILITY_MIN_OBSERVATIONS = 3;
-var RELIABILITY_THRESHOLD = 0.8;
-function buildCoUsageMap(packs) {
-  const result = /* @__PURE__ */ new Map();
-  for (const pack of packs) {
-    for (const ns of pack.namespaces) {
-      const bucket = result.get(ns) ?? /* @__PURE__ */ new Set();
-      for (const peer of pack.namespaces) {
-        if (peer !== ns) bucket.add(peer);
-      }
-      result.set(ns, bucket);
-    }
+// src/try-cmd.ts
+import { createHash } from "crypto";
+import { existsSync as existsSync2 } from "fs";
+import { chmod as chmod2, mkdir as mkdir3, readFile as readFile4, readdir, unlink as unlink2 } from "fs/promises";
+import { homedir as homedir5, hostname, userInfo } from "os";
+import { join as join5, resolve as resolve3 } from "path";
+import { request as request5 } from "undici";
+
+// src/install-cmd.ts
+import { existsSync } from "fs";
+import { chmod, readFile as readFile3 } from "fs/promises";
+import { homedir as homedir4 } from "os";
+import { join as join4, resolve as resolve2 } from "path";
+import { createInterface } from "readline/promises";
+var USAGE = "Usage: mcph 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-mcph-config]\n       mcph install --list                       (detect clients; no writes)\n       mcph install --all  [--token <mcp_pat_\u2026>] (install into every detected client)";
+async function runInstall(opts) {
+  const stdout = opts.io?.stdout ?? process.stdout;
+  const stderr = opts.io?.stderr ?? process.stderr;
+  const messages = [];
+  const log2 = (s) => {
+    messages.push(s);
+    stdout.write(`${s}
+`);
+  };
+  const err = (s) => {
+    messages.push(s);
+    stderr.write(`${s}
+`);
+  };
+  if (opts.listOnly && opts.all) {
+    err("mcph install: --list and --all are mutually exclusive");
+    return { written: [], wouldWrite: [], messages, exitCode: 2 };
   }
-  const sorted = /* @__PURE__ */ new Map();
-  for (const [ns, peers] of result) {
-    sorted.set(ns, Array.from(peers).sort());
+  if (opts.listOnly) return runInstallList(opts, log2);
+  if (opts.all) return runInstallAll(opts, log2, err);
+  if (opts.force && opts.skip) {
+    err("mcph install: --force and --skip are mutually exclusive");
+    return { written: [], wouldWrite: [], messages, exitCode: 2 };
   }
-  return sorted;
-}
-function formatUsageHint(usage, coUsedWith) {
-  const parts = [];
-  if (usage && usage.succeeded >= MIN_SUCCESS_TO_SHOW) {
-    parts.push(`used ${usage.succeeded}x`);
+  if (!opts.clientId) {
+    err(`mcph install: client argument required
+${USAGE}`);
+    return { written: [], wouldWrite: [], messages, exitCode: 2 };
   }
-  if (coUsedWith.length > 0) {
-    const shown = coUsedWith.slice(0, MAX_PEERS);
-    const more = coUsedWith.length - shown.length;
-    const names = shown.map((n) => `"${n}"`).join(", ");
-    const tail = more > 0 ? ` +${more} more` : "";
-    parts.push(`often loaded with ${names}${tail}`);
+  const target = INSTALL_TARGETS.find((t) => t.clientId === opts.clientId);
+  if (!target) {
+    err(`mcph install: unknown client ${opts.clientId}
+${USAGE}`);
+    return { written: [], wouldWrite: [], messages, exitCode: 2 };
   }
-  if (parts.length === 0) return null;
-  return `usage: ${parts.join("; ")}`;
-}
-function formatReliabilityWarning(usage) {
-  if (!usage || usage.dispatched < RELIABILITY_MIN_OBSERVATIONS) return null;
-  const rate = usage.succeeded / usage.dispatched;
-  if (rate >= RELIABILITY_THRESHOLD) return null;
-  const pct = Math.round(rate * 100);
-  return `reliability: ${pct}% success across ${usage.dispatched} past calls`;
-}
-function selectFlakyNamespaces(entries, limit) {
-  if (limit <= 0) return [];
-  return Array.from(entries).filter(({ usage }) => {
-    if (usage.dispatched < RELIABILITY_MIN_OBSERVATIONS) return false;
-    return usage.succeeded / usage.dispatched < RELIABILITY_THRESHOLD;
-  }).sort((a, b) => {
-    const aRate = a.usage.succeeded / a.usage.dispatched;
-    const bRate = b.usage.succeeded / b.usage.dispatched;
-    if (aRate !== bRate) return aRate - bRate;
-    if (a.usage.dispatched !== b.usage.dispatched) return b.usage.dispatched - a.usage.dispatched;
-    return a.namespace.localeCompare(b.namespace);
-  }).slice(0, limit);
-}
-
-// src/doctor-cmd.ts
-var VERSION = true ? "0.52.0" : "dev";
-async function runDoctor(opts = {}) {
-  if (opts.json) return runDoctorJson(opts);
-  const lines = [];
-  const write = opts.out ?? ((s) => process.stdout.write(s));
-  const print = (s = "") => {
-    lines.push(s);
-    write(`${s}
-`);
-  };
-  const cwd = opts.cwd ?? process.cwd();
-  const home = opts.home ?? homedir4();
   const os = opts.os ?? CURRENT_OS;
-  const env = opts.env ?? process.env;
-  print(`mcph doctor \u2014 ${(/* @__PURE__ */ new Date()).toISOString()}`);
-  print(`mcph version: ${VERSION}`);
-  print(`platform: ${os}`);
-  print("");
-  const config = await loadMcphConfig({ cwd, home, env });
-  print("CONFIG FILES");
-  if (config.loadedFiles.length === 0) {
-    print("  (none \u2014 using defaults + env)");
-  } else {
-    for (const f of config.loadedFiles) {
-      print(`  ${f.scope.padEnd(7)} ${f.path}${schemaSuffix(f)}`);
-    }
+  if (!target.availableOn.includes(os)) {
+    const fix = target.clientId === "claude-desktop" && os === "linux" ? "Anthropic ships Claude Desktop on macOS and Windows only. Install Claude Code or Cursor instead." : "Pick a different client or pass --os to override.";
+    err(`mcph install: ${target.label} is not available on ${os}.
+  ${fix}`);
+    return { written: [], wouldWrite: [], messages, exitCode: 2 };
   }
-  print("");
-  print("TOKEN");
-  print(`  value:  ${tokenFingerprint(config.token)}`);
-  print(`  source: ${config.tokenSource}`);
-  print("");
-  print("API BASE");
-  print(`  value:  ${config.apiBase}`);
-  print(`  source: ${config.apiBaseSource}`);
-  print("");
-  renderEnvSection({ env, print });
-  await renderStateSection({ home, env, print });
-  await renderReliabilitySection({ home, env, print });
-  renderBackgroundPostersSection({ print });
-  const claudeConfigDir = env.CLAUDE_CONFIG_DIR && env.CLAUDE_CONFIG_DIR.length > 0 ? env.CLAUDE_CONFIG_DIR : void 0;
-  const clients = probeClients({ home, os, cwd, claudeConfigDir });
-  print("INSTALLED CLIENTS (probed config files)");
-  for (const c of clients) {
-    const status = c.unavailable ? "unavailable on this OS" : c.malformed ? "exists but JSON is malformed \u2014 fix or rerun `mcph install`" : c.hasMcphEntry ? `OK \u2014 has "${ENTRY_NAME}" entry` : c.exists ? `present, no "${ENTRY_NAME}" entry \u2014 run \`mcph install ${c.clientId}${c.scope === "user" ? "" : ` --scope ${c.scope}`}\`` : `not configured \u2014 run \`mcph install ${c.clientId}${c.scope === "user" ? "" : ` --scope ${c.scope}`}\``;
-    const label = INSTALL_TARGETS.find((t) => t.clientId === c.clientId)?.label ?? c.clientId;
-    print(`  ${label} (${c.scope}): ${status}`);
-    print(`    ${c.path}`);
+  const scope = opts.scope ?? (target.scopes.find((s) => s.scope === "user") ? "user" : target.scopes[0].scope);
+  const scopeSpec = target.scopes.find((s) => s.scope === scope);
+  if (!scopeSpec) {
+    err(
+      `mcph install: ${target.label} does not support scope "${scope}". Available: ${target.scopes.map((s) => s.scope).join(", ")}`
+    );
+    return { written: [], wouldWrite: [], messages, exitCode: 2 };
   }
-  print("");
-  if (config.warnings.length > 0) {
-    print("WARNINGS");
-    for (const w of config.warnings) print(`  ! ${w}`);
-    print("");
+  const projectDir = scopeSpec.requiresProjectDir ? resolve2(opts.projectDir ?? process.cwd()) : void 0;
+  let resolved;
+  try {
+    resolved = resolveInstallPath({
+      clientId: opts.clientId,
+      scope,
+      os,
+      home: opts.home,
+      projectDir,
+      claudeConfigDir: opts.claudeConfigDir
+    });
+  } catch (e) {
+    err(`mcph install: ${e.message}`);
+    return { written: [], wouldWrite: [], messages, exitCode: 2 };
   }
-  const shadowHits = scanShellHistoryForShadows({ home, env });
-  if (shadowHits.length > 0) {
-    print("SHADOWED CLI USAGE (recent shell history)");
-    print("  Commands below have MCP servers that can replace them;");
-    print("  activate the server and prefer its tools over the CLI.");
-    for (const hit of shadowHits) {
-      const pluralHit = hit.count === 1 ? "time" : "times";
-      print(`  ${hit.cli.padEnd(12)} ${hit.count} ${pluralHit} \u2192 server(s): ${hit.namespaces.join(", ")}`);
-    }
-    print("");
+  log2(`Target: ${target.label} (${scope})`);
+  log2(`File:   ${resolved.absolute}`);
+  let token6 = opts.token ?? null;
+  if (!token6) {
+    const cfg = await loadMcphConfig({ home: opts.home, cwd: process.cwd(), env: {} });
+    token6 = cfg.token;
   }
-  const skipCheck = opts.skipRegistryCheck === true || Boolean(process.env.VITEST);
-  const latest = skipCheck ? null : await fetchLatestVersion(opts.registryFetch);
-  const staleHint = latest && VERSION !== "dev" && compareSemver(VERSION, latest) < 0 ? latest : null;
-  if (staleHint) {
-    print("UPGRADE AVAILABLE");
-    print(`  Running ${VERSION}; npm latest is ${staleHint}.`);
-    print("  Run `mcph upgrade` to see the exact command for your install, or");
-    print("  `mcph upgrade --run` to execute it (global-npm installs only).");
-    print("");
+  if (!token6) {
+    err(
+      "\nmcph install: no token available.\n  Pass one with --token mcp_pat_\u2026, or run `mcph install` with --token once to seed ~/.mcph/config.json,\n  or create the token at https://mcp.hosting \u2192 Settings \u2192 API Tokens."
+    );
+    return { written: [], wouldWrite: [], messages, exitCode: 1 };
   }
-  let exitCode = 0;
-  if (config.token === null) {
-    exitCode = 1;
-    print("DIAGNOSIS");
-    print("  No token resolved \u2014 mcph cannot start.");
-    print("  Run `mcph install <client> --token mcp_pat_\u2026` to seed ~/.mcph/config.json.");
-  } else if (config.warnings.length > 0) {
-    exitCode = 2;
-    print("DIAGNOSIS");
-    print("  Token present, but warnings above need attention.");
-  } else {
-    print("DIAGNOSIS");
-    print(staleHint ? "  Healthy, but an upgrade is available (see above)." : "  All good. mcph should start cleanly.");
+  const newEntry = buildLaunchEntry({ os });
+  const containerPath = resolved.containerPath;
+  let existing = {};
+  let existingHasEntry = false;
+  if (existsSync(resolved.absolute)) {
+    let raw;
+    try {
+      raw = await readFile3(resolved.absolute, "utf8");
+    } catch (e) {
+      err(`mcph install: cannot read ${resolved.absolute}: ${e.message}`);
+      return { written: [], wouldWrite: [], messages, exitCode: 1 };
+    }
+    if (raw.trim().length > 0) {
+      try {
+        const parsed = parseJsonc(raw);
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+          err(
+            `mcph install: ${resolved.absolute} is not a JSON object \u2014 refusing to overwrite. Edit by hand or rename the file and re-run.`
+          );
+          return { written: [], wouldWrite: [], messages, exitCode: 1 };
+        }
+        existing = parsed;
+      } catch (e) {
+        err(
+          `mcph install: ${resolved.absolute} is not valid JSON (${e.message}). Refusing to overwrite. Fix the file or rename it and re-run.`
+        );
+        return { written: [], wouldWrite: [], messages, exitCode: 1 };
+      }
+    }
+    const container = readNested(existing, containerPath);
+    if (typeof container === "object" && container !== null && !Array.isArray(container)) {
+      existingHasEntry = ENTRY_NAME in container;
+    }
   }
-  return { exitCode, lines, snapshot: { version: VERSION, config, clients } };
-}
-async function runDoctorJson(opts) {
-  const lines = [];
-  const write = opts.out ?? ((s) => process.stdout.write(s));
-  const cwd = opts.cwd ?? process.cwd();
-  const home = opts.home ?? homedir4();
-  const os = opts.os ?? CURRENT_OS;
-  const env = opts.env ?? process.env;
-  const timestamp = (/* @__PURE__ */ new Date()).toISOString();
-  const config = await loadMcphConfig({ cwd, home, env });
-  const claudeConfigDir = env.CLAUDE_CONFIG_DIR && env.CLAUDE_CONFIG_DIR.length > 0 ? env.CLAUDE_CONFIG_DIR : void 0;
-  const clients = probeClients({ home, os, cwd, claudeConfigDir });
-  const envVarNames = [
-    "MCPH_POLL_INTERVAL",
-    "MCPH_SERVER_CAP",
-    "MCPH_MIN_COMPLIANCE",
-    "MCPH_AUTO_LOAD",
-    "MCPH_AUTO_ACTIVATE",
-    "MCPH_PRUNE_RESPONSES"
-  ];
-  const envOverrides = {};
-  for (const name of envVarNames) {
-    const raw = env[name];
-    envOverrides[name] = raw === void 0 || raw === "" ? null : raw;
-  }
-  const persistRaw = env.MCPH_DISABLE_PERSISTENCE;
-  const persistDisabled = persistRaw !== void 0 && persistRaw !== "" && (persistRaw === "1" || persistRaw.toLowerCase() === "true");
-  const state = persistDisabled ? { disabled: true, path: null, savedAt: null, learningEntries: null, packHistoryEntries: null } : await (async () => {
-    const filePath = join4(userConfigDir(home), STATE_FILENAME);
-    const persisted = await loadState(filePath);
-    const fresh = persisted.savedAt === 0;
-    return {
-      disabled: false,
-      path: filePath,
-      savedAt: fresh ? null : new Date(persisted.savedAt).toISOString(),
-      learningEntries: fresh ? 0 : Object.keys(persisted.learning).length,
-      packHistoryEntries: fresh ? 0 : persisted.packHistory.length
-    };
-  })();
-  const reliability = [];
-  if (!persistDisabled) {
-    const filePath = join4(userConfigDir(home), STATE_FILENAME);
-    const persisted = await loadState(filePath);
-    if (persisted.savedAt !== 0) {
-      const entries = Object.entries(persisted.learning).map(([namespace, usage]) => ({ namespace, usage }));
-      for (const { namespace, usage } of selectFlakyNamespaces(entries, 5)) {
-        reliability.push({
-          namespace,
-          dispatched: usage.dispatched,
-          succeeded: usage.succeeded,
-          successRate: usage.succeeded / usage.dispatched,
-          lastUsedAt: new Date(usage.lastUsedAt).toISOString()
-        });
-      }
+  if (existingHasEntry) {
+    let decision;
+    if (opts.force) decision = "overwrite";
+    else if (opts.skip) decision = "skip";
+    else if (opts.promptAnswer) decision = opts.promptAnswer;
+    else if (opts.io?.isTTY ?? process.stdout.isTTY) {
+      decision = await promptCollision(resolved.absolute, opts.io);
+    } else {
+      err(
+        `mcph install: ${resolved.absolute} already has a "${ENTRY_NAME}" entry and stdin is not a TTY.
+  Re-run with --force to overwrite, --skip to leave it, or --dry-run to preview.`
+      );
+      return { written: [], wouldWrite: [], messages, exitCode: 1 };
     }
+    if (decision === "skip") {
+      log2(`Existing "${ENTRY_NAME}" entry left untouched. Nothing to do.`);
+      return { written: [], wouldWrite: [], messages, exitCode: 0 };
+    }
+    if (decision === "abort") {
+      err("Aborted.");
+      return { written: [], wouldWrite: [], messages, exitCode: 1 };
+    }
+    log2(`Overwriting existing "${ENTRY_NAME}" entry.`);
   }
-  const shellShadows = scanShellHistoryForShadows({ home, env });
-  const skipCheck = opts.skipRegistryCheck === true || Boolean(process.env.VITEST);
-  const latest = skipCheck ? null : await fetchLatestVersion(opts.registryFetch);
-  const stale = latest !== null && VERSION !== "dev" && compareSemver(VERSION, latest) < 0;
-  let exitCode = 0;
-  let summary;
-  if (config.token === null) {
-    exitCode = 1;
-    summary = "No token resolved \u2014 mcph cannot start.";
-  } else if (config.warnings.length > 0) {
-    exitCode = 2;
-    summary = "Token present, but warnings need attention.";
-  } else {
-    summary = stale ? "Healthy, but an upgrade is available." : "All good. mcph should start cleanly.";
-  }
-  const snapshotJson = {
-    timestamp,
-    version: VERSION,
-    platform: os,
-    token: { fingerprint: tokenFingerprint(config.token), source: config.tokenSource },
-    apiBase: { value: config.apiBase, source: config.apiBaseSource },
-    loadedFiles: config.loadedFiles.map((f) => ({
-      scope: f.scope,
-      path: f.path,
-      ...f.version !== void 0 ? { schemaVersion: f.version } : {},
-      schemaAhead: f.version !== void 0 && f.version > CURRENT_SCHEMA_VERSION
-    })),
-    warnings: config.warnings,
-    env: envOverrides,
-    state,
-    reliability,
-    clients,
-    shellShadows,
-    upgrade: { current: VERSION, latest, stale },
-    diagnosis: { exitCode, summary }
-  };
-  const blob = JSON.stringify(snapshotJson, null, 2);
-  lines.push(blob);
-  write(`${blob}
-`);
-  return { exitCode, lines, snapshot: { version: VERSION, config, clients } };
-}
-function renderEnvSection(opts) {
-  const { env, print } = opts;
-  const vars = [
-    { name: "MCPH_POLL_INTERVAL", defaultHint: "default 60s" },
-    { name: "MCPH_SERVER_CAP", defaultHint: "default 6" },
-    { name: "MCPH_MIN_COMPLIANCE", defaultHint: "filter inactive" },
-    { name: "MCPH_AUTO_LOAD", defaultHint: "auto-load inactive" },
-    { name: "MCPH_AUTO_ACTIVATE", defaultHint: "default on" },
-    { name: "MCPH_PRUNE_RESPONSES", defaultHint: "pruning active" }
-  ];
-  const widest = vars.reduce((m, v) => Math.max(m, v.name.length), 0);
-  print("ENVIRONMENT (behavior overrides)");
-  for (const v of vars) {
-    const raw = env[v.name];
-    const value = raw === void 0 || raw === "" ? `(not set \u2014 ${v.defaultHint})` : raw;
-    print(`  ${v.name.padEnd(widest)}  ${value}`);
-  }
-  print("");
-}
-async function renderStateSection(opts) {
-  const { home, env, print } = opts;
-  const raw = env.MCPH_DISABLE_PERSISTENCE;
-  const disabled = raw !== void 0 && raw !== "" && (raw === "1" || raw.toLowerCase() === "true");
-  print("STATE");
-  if (disabled) {
-    print("  status: disabled via MCPH_DISABLE_PERSISTENCE");
-    print("");
-    return;
-  }
-  const filePath = join4(userConfigDir(home), STATE_FILENAME);
-  print(`  path:   ${filePath}`);
-  const peek = await peekStateFile(filePath);
-  if (peek.kind === "malformed") {
-    print("  status: corrupt -- file exists but JSON is unparseable");
-    print(`  fix:    \`mcph reset-learning\` to clear, or open ${filePath} and fix by hand`);
-    print(`  detail: ${peek.message}`);
-    print("");
-    return;
-  }
-  if (peek.kind === "stale-version") {
-    print(`  status: schema mismatch (file is v${peek.version ?? "?"}, this mcph reads v${peek.expected})`);
-    print("  fix:    `mcph reset-learning` to drop the old file -- learning will rebuild on use");
-    print("");
-    return;
-  }
-  if (peek.kind === "unreadable") {
-    print(`  status: unreadable (${peek.message})`);
-    print("");
-    return;
+  const merged = mergeClientConfig(existing, containerPath, newEntry);
+  const clientJson = `${JSON.stringify(merged, null, 2)}
+`;
+  const writeMcphConfig = !opts.skipMcphConfig;
+  const home = opts.home ?? homedir4();
+  const mcphConfigPath = join4(home, CONFIG_DIRNAME, CONFIG_FILENAME);
+  const mcphConfigComposed = await composeMcphConfig(mcphConfigPath, token6);
+  if (mcphConfigComposed.backupPath) {
+    log2(
+      `mcph install: existing ${mcphConfigPath} was malformed; original bytes backed up to ${mcphConfigComposed.backupPath} before overwriting.`
+    );
   }
-  const persisted = await loadState(filePath);
-  if (persisted.savedAt === 0) {
-    print("  (no persisted state yet \u2014 will be created on the first tool call)");
-  } else {
-    print(`  last saved:           ${formatRelativeAge(Date.now() - persisted.savedAt)} ago`);
-    print(`  learning entries:     ${Object.keys(persisted.learning).length}`);
-    print(`  pack history entries: ${persisted.packHistory.length}`);
+  const mcphConfigJson = mcphConfigComposed.json;
+  const settingsPatch = opts.clientId === "claude-code" ? await prepareClaudeCodeSettingsPatch({
+    scope,
+    home,
+    projectDir,
+    os,
+    claudeConfigDir: opts.claudeConfigDir
+  }) : null;
+  if (opts.dryRun) {
+    log2("\n--- dry run: would write the following ---");
+    if (writeMcphConfig) log2(`# ${mcphConfigPath}
+${mcphConfigJson}`);
+    log2(`
+# ${resolved.absolute}
+${clientJson}`);
+    if (settingsPatch?.changed) log2(`# ${settingsPatch.path}
+${settingsPatch.nextJson}`);
+    const wouldWrite = [];
+    if (writeMcphConfig) wouldWrite.push(mcphConfigPath);
+    wouldWrite.push(resolved.absolute);
+    if (settingsPatch?.changed) wouldWrite.push(settingsPatch.path);
+    return { written: [], wouldWrite, messages, exitCode: 0 };
   }
-  print("");
-}
-async function peekStateFile(filePath) {
-  let raw;
-  try {
-    raw = await readFile3(filePath, "utf8");
-  } catch (err) {
-    if (err && typeof err === "object" && "code" in err && err.code === "ENOENT") {
-      return { kind: "missing" };
+  const written = [];
+  if (writeMcphConfig) {
+    try {
+      await atomicWriteFile(mcphConfigPath, mcphConfigJson);
+      if (process.platform !== "win32") {
+        try {
+          await chmod(mcphConfigPath, 384);
+        } catch {
+        }
+      }
+    } catch (e) {
+      err(`mcph install: failed to write ${mcphConfigPath}: ${e.message}`);
+      return { written: [], wouldWrite: [], messages, exitCode: 1 };
     }
-    return { kind: "unreadable", message: err instanceof Error ? err.message : String(err) };
+    log2(`Wrote ${mcphConfigPath}`);
+    written.push(mcphConfigPath);
   }
-  let parsed;
   try {
-    parsed = JSON.parse(raw);
-  } catch (err) {
-    return { kind: "malformed", message: err instanceof Error ? err.message : String(err) };
+    await atomicWriteFile(resolved.absolute, clientJson);
+  } catch (e) {
+    err(`mcph install: failed to write ${resolved.absolute}: ${e.message}`);
+    return { written, wouldWrite: [], messages, exitCode: 1 };
   }
-  if (!parsed || typeof parsed !== "object") return { kind: "malformed", message: "top-level value is not an object" };
-  const version = parsed.version;
-  if (version !== STATE_SCHEMA_VERSION) {
-    return { kind: "stale-version", version, expected: STATE_SCHEMA_VERSION };
+  log2(`Wrote ${resolved.absolute}`);
+  written.push(resolved.absolute);
+  if (settingsPatch?.changed) {
+    try {
+      await atomicWriteFile(settingsPatch.path, settingsPatch.nextJson);
+      log2(`Wrote ${settingsPatch.path} (added ${CLAUDE_CODE_ALLOW_PATTERN} to permissions.allow)`);
+      written.push(settingsPatch.path);
+    } catch (e) {
+      err(
+        `mcph install: warning \u2014 failed to patch ${settingsPatch.path}: ${e.message}. You may be re-prompted for each mcph tool call; add "${CLAUDE_CODE_ALLOW_PATTERN}" to permissions.allow to silence.`
+      );
+    }
   }
-  return { kind: "ok" };
+  if (target.notes) log2(`Note: ${target.notes}`);
+  log2(`
+\u2713 ${target.label} is configured. Restart it to pick up the new MCP server.`);
+  return { written, wouldWrite: [], messages, exitCode: 0 };
 }
-async function renderReliabilitySection(opts) {
-  const { home, env, print } = opts;
-  const raw = env.MCPH_DISABLE_PERSISTENCE;
-  const disabled = raw !== void 0 && raw !== "" && (raw === "1" || raw.toLowerCase() === "true");
-  if (disabled) return;
-  const filePath = join4(userConfigDir(home), STATE_FILENAME);
-  const persisted = await loadState(filePath);
-  if (persisted.savedAt === 0) return;
-  const entries = Object.entries(persisted.learning).map(([namespace, usage]) => ({ namespace, usage }));
-  const flaky = selectFlakyNamespaces(entries, 5);
-  if (flaky.length === 0) return;
-  print("RELIABILITY (dormant, <80% success)");
-  const now = Date.now();
-  for (const { namespace, usage } of flaky) {
-    const rate = Math.round(usage.succeeded / usage.dispatched * 100);
-    const age = formatRelativeAge(now - usage.lastUsedAt);
-    print(`  ${namespace} \u2014 ${usage.dispatched} calls, ${rate}% success, last used ${age} ago`);
-  }
-  print("");
-}
-function renderBackgroundPostersSection(opts) {
-  const { print } = opts;
-  const analyticsFailure = getLastAnalyticsFailure();
-  const reportFailure = getLastReportFailure();
-  if (!analyticsFailure && !reportFailure) return;
-  const now = Date.now();
-  const fmt = (f) => `HTTP ${f.statusCode} from ${f.url}, ${formatRelativeAge(now - f.at)} ago`;
-  print("BACKGROUND POSTERS (recent failures)");
-  print(`  analytics:    ${analyticsFailure ? fmt(analyticsFailure) : "(no recent failure)"}`);
-  print(`  tool-report:  ${reportFailure ? fmt(reportFailure) : "(no recent failure)"}`);
-  print("");
-}
-function formatRelativeAge(ms) {
-  const clamped = Math.max(0, ms);
-  const s = Math.floor(clamped / 1e3);
-  if (s < 60) return `${s}s`;
-  const m = Math.floor(s / 60);
-  if (m < 60) return `${m}m`;
-  const h = Math.floor(m / 60);
-  if (h < 24) return `${h}h`;
-  const d = Math.floor(h / 24);
-  return `${d}d`;
-}
-function schemaSuffix(f) {
-  if (f.version === void 0) return "";
-  if (f.version > CURRENT_SCHEMA_VERSION)
-    return ` (schema v${f.version}, this mcph supports v${CURRENT_SCHEMA_VERSION})`;
-  return ` (schema v${f.version})`;
-}
-function probeClients(opts) {
-  const out = [];
-  for (const target of INSTALL_TARGETS) {
-    const unavailable = !target.availableOn.includes(opts.os);
-    if (unavailable) {
-      out.push({
-        clientId: target.clientId,
-        scope: target.scopes[0].scope,
-        path: "(n/a)",
-        exists: false,
-        hasMcphEntry: false,
-        malformed: false,
-        unavailable: true
-      });
-      continue;
-    }
-    for (const scope of target.scopes) {
-      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 = existsSync(resolved.absolute);
-      let hasMcphEntry = false;
-      let 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) hasMcphEntry = ENTRY_NAME in container;
-            } else {
-              malformed = true;
-            }
-          }
-        } catch {
-          malformed = true;
+async function prepareClaudeCodeSettingsPatch(opts) {
+  const path5 = resolveClaudeCodeSettingsPath(opts.scope, {
+    home: opts.home,
+    projectDir: opts.projectDir,
+    os: opts.os,
+    claudeConfigDir: opts.claudeConfigDir
+  });
+  if (!path5) return null;
+  let existing = {};
+  if (existsSync(path5)) {
+    try {
+      const raw = await readFile3(path5, "utf8");
+      if (raw.trim().length > 0) {
+        const parsed = parseJsonc(raw);
+        if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+          existing = parsed;
+        } else {
+          return { path: path5, nextJson: "", changed: false };
         }
       }
-      out.push({
-        clientId: target.clientId,
-        scope: scope.scope,
-        path: resolved.absolute,
-        exists: exists3,
-        hasMcphEntry,
-        malformed,
-        unavailable: false
-      });
+    } catch {
+      return { path: path5, nextJson: "", changed: false };
     }
   }
+  const merged = mergePermissionsAllow(existing, [CLAUDE_CODE_ALLOW_PATTERN]);
+  const before = JSON.stringify(existing);
+  const after = JSON.stringify(merged);
+  if (before === after) return { path: path5, nextJson: "", changed: false };
+  return { path: path5, nextJson: `${JSON.stringify(merged, null, 2)}
+`, changed: true };
+}
+function mergePermissionsAllow(existing, patterns) {
+  const out = { ...existing };
+  const prev = out.permissions;
+  const perms = typeof prev === "object" && prev !== null && !Array.isArray(prev) ? { ...prev } : {};
+  const prevAllow = perms.allow;
+  const allow = Array.isArray(prevAllow) ? prevAllow.filter((x) => typeof x === "string") : [];
+  for (const p of patterns) {
+    if (!allow.includes(p)) allow.push(p);
+  }
+  perms.allow = allow;
+  out.permissions = perms;
   return out;
 }
-function walkContainer(root, path5) {
+async function promptCollision(path5, io) {
+  const stdin = io?.stdin ?? process.stdin;
+  const stdout = io?.stdout ?? process.stdout;
+  const rl = createInterface({ input: stdin, output: stdout });
+  try {
+    const answer = (await rl.question(
+      `${path5} already has an "${ENTRY_NAME}" entry.
+  [o]verwrite, [s]kip, or [a]bort? (default: skip) `
+    )).trim().toLowerCase();
+    if (answer.startsWith("o")) return "overwrite";
+    if (answer.startsWith("a")) return "abort";
+    return "skip";
+  } finally {
+    rl.close();
+  }
+}
+function readNested(root, containerPath) {
   let cur = root;
-  for (const key of path5) {
-    if (typeof cur !== "object" || cur === null || Array.isArray(cur)) return null;
+  for (const key of containerPath) {
+    if (typeof cur !== "object" || cur === null || Array.isArray(cur)) return void 0;
     cur = cur[key];
   }
-  if (typeof cur !== "object" || cur === null || Array.isArray(cur)) return null;
   return cur;
 }
-async function probeClientsAsync(opts) {
-  const result = [];
-  for (const target of INSTALL_TARGETS) {
-    const unavailable = !target.availableOn.includes(opts.os);
-    if (unavailable) {
-      result.push({
-        clientId: target.clientId,
-        scope: target.scopes[0].scope,
-        path: "(n/a)",
-        exists: false,
-        hasMcphEntry: false,
-        malformed: false,
-        unavailable: true
-      });
-      continue;
+function mergeClientConfig(existing, containerPath, entry, entryName = ENTRY_NAME) {
+  if (containerPath.length === 0) throw new Error("mergeClientConfig: containerPath cannot be empty");
+  const out = { ...existing };
+  let parent = out;
+  for (let i = 0; i < containerPath.length - 1; i++) {
+    const key = containerPath[i];
+    const child = parent[key];
+    const cloned = typeof child === "object" && child !== null && !Array.isArray(child) ? { ...child } : {};
+    parent[key] = cloned;
+    parent = cloned;
+  }
+  const leafKey = containerPath[containerPath.length - 1];
+  const prev = parent[leafKey];
+  const container = typeof prev === "object" && prev !== null && !Array.isArray(prev) ? { ...prev } : {};
+  container[entryName] = entry;
+  parent[leafKey] = container;
+  return out;
+}
+function removeFromClientConfig(existing, containerPath, entryName) {
+  if (containerPath.length === 0) throw new Error("removeFromClientConfig: containerPath cannot be empty");
+  let probe2 = existing;
+  for (const key of containerPath) {
+    if (typeof probe2 !== "object" || probe2 === null || Array.isArray(probe2)) return existing;
+    probe2 = probe2[key];
+  }
+  if (typeof probe2 !== "object" || probe2 === null || Array.isArray(probe2)) return existing;
+  if (!(entryName in probe2)) return existing;
+  const out = { ...existing };
+  let parent = out;
+  for (let i = 0; i < containerPath.length - 1; i++) {
+    const key = containerPath[i];
+    const child = parent[key];
+    const cloned = { ...child };
+    parent[key] = cloned;
+    parent = cloned;
+  }
+  const leafKey = containerPath[containerPath.length - 1];
+  const container = { ...parent[leafKey] };
+  delete container[entryName];
+  parent[leafKey] = container;
+  return out;
+}
+async function composeMcphConfig(path5, token6) {
+  let existing = {};
+  let backupPath;
+  if (existsSync(path5)) {
+    let raw = "";
+    try {
+      raw = await readFile3(path5, "utf8");
+    } catch {
+      raw = "";
     }
-    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
-      });
-      const exists3 = existsSync(resolved.absolute);
-      let hasMcphEntry = false;
-      let malformed = false;
-      if (exists3) {
+    if (raw) {
+      try {
+        const parsed = parseJsonc(raw);
+        if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+          existing = parsed;
+        }
+      } catch {
+        const candidate = `${path5}.bak-${Date.now()}`;
         try {
-          const raw = await readFile3(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) hasMcphEntry = ENTRY_NAME in container;
-            } else {
-              malformed = true;
-            }
-          }
+          await atomicWriteFile(candidate, raw);
+          backupPath = candidate;
         } catch {
-          malformed = true;
         }
       }
-      result.push({
-        clientId: target.clientId,
-        scope: scope.scope,
-        path: resolved.absolute,
-        exists: exists3,
-        hasMcphEntry,
-        malformed,
-        unavailable: false
-      });
     }
   }
-  return result;
-}
-async function fetchLatestVersion(override) {
-  if (override) {
-    try {
-      return await override();
-    } catch {
-      return null;
+  const next = { version: CURRENT_SCHEMA_VERSION, ...existing };
+  next.token = token6;
+  if (typeof next.version !== "number") next.version = CURRENT_SCHEMA_VERSION;
+  return { json: `${JSON.stringify(next, null, 2)}
+`, backupPath };
+}
+function parseInstallArgs(argv) {
+  if (argv.length === 0) return { ok: false, error: USAGE };
+  const positional = [];
+  const opts = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = () => argv[++i];
+    switch (a) {
+      case "--scope": {
+        const v = next();
+        if (!v || !["user", "project", "local"].includes(v))
+          return { ok: false, error: "--scope requires user|project|local" };
+        opts.scope = v;
+        break;
+      }
+      case "--os": {
+        const v = next();
+        if (!v || !["macos", "linux", "windows"].includes(v))
+          return { ok: false, error: "--os requires macos|linux|windows" };
+        opts.os = v;
+        break;
+      }
+      case "--token": {
+        const v = next();
+        if (!v) return { ok: false, error: "--token requires a value" };
+        opts.token = v;
+        break;
+      }
+      case "--project-dir": {
+        const v = next();
+        if (!v) return { ok: false, error: "--project-dir requires a value" };
+        opts.projectDir = v;
+        break;
+      }
+      case "--force":
+        opts.force = true;
+        break;
+      case "--skip":
+        opts.skip = true;
+        break;
+      case "--dry-run":
+        opts.dryRun = true;
+        break;
+      case "--no-mcph-config":
+        opts.skipMcphConfig = true;
+        break;
+      case "--list":
+        opts.listOnly = true;
+        break;
+      case "--all":
+        opts.all = true;
+        break;
+      case "-h":
+      case "--help":
+        return { ok: false, error: USAGE };
+      default:
+        if (a.startsWith("--")) return { ok: false, error: `Unknown flag: ${a}
+${USAGE}` };
+        positional.push(a);
     }
   }
-  const ac = new AbortController();
-  const timer = setTimeout(() => ac.abort(), 2e3);
-  try {
-    const res = await fetch("https://registry.npmjs.org/@yawlabs/mcph/latest", {
-      signal: ac.signal,
-      headers: { accept: "application/json" }
-    });
-    if (!res.ok) return null;
-    const body = await res.json();
-    return typeof body.version === "string" ? body.version : null;
-  } catch {
-    return null;
-  } finally {
-    clearTimeout(timer);
-  }
-}
-var SHELL_HISTORY_TAIL_LINES = 500;
-function scanShellHistoryForShadows(opts) {
-  const shadowMap = cliToNamespaces();
-  const counts = /* @__PURE__ */ new Map();
-  for (const source of shellHistorySources(opts)) {
-    const lines = readTailLines(source.path, SHELL_HISTORY_TAIL_LINES);
-    for (const raw of lines) {
-      const cmd = source.extractCommand(raw);
-      if (!cmd) continue;
-      const binary = extractLeadingBinary(cmd);
-      if (!binary) continue;
-      if (!shadowMap.has(binary)) continue;
-      counts.set(binary, (counts.get(binary) ?? 0) + 1);
+  if (opts.listOnly || opts.all) {
+    if (positional.length > 0) {
+      return {
+        ok: false,
+        error: `mcph install: ${opts.listOnly ? "--list" : "--all"} does not take a client argument.
+${USAGE}`
+      };
     }
+    return { ok: true, options: opts };
   }
-  const hits = [];
-  for (const [cli, count] of counts) {
-    const namespaces = shadowMap.get(cli) ?? [];
-    hits.push({ cli, count, namespaces });
+  if (positional.length !== 1)
+    return { ok: false, error: `Expected exactly one client argument, got ${positional.length}.
+${USAGE}` };
+  const clientId = positional[0];
+  if (!INSTALL_TARGETS.some((t) => t.clientId === clientId)) {
+    return {
+      ok: false,
+      error: `Unknown client: ${clientId}. Choose: ${INSTALL_TARGETS.map((t) => t.clientId).join(", ")}`
+    };
   }
-  hits.sort((a, b) => b.count - a.count);
-  return hits;
+  opts.clientId = clientId;
+  return { ok: true, options: opts };
 }
-function shellHistorySources(opts) {
-  const sources = [];
-  sources.push({ path: join4(opts.home, ".bash_history"), extractCommand: (l) => l.trim() || null });
-  sources.push({
-    path: join4(opts.home, ".zsh_history"),
-    // Zsh extended-history lines look like `: 1700000000:0;npm audit`.
-    // Strip the metadata prefix so we get just the command.
-    extractCommand: (l) => {
-      const trimmed = l.trim();
-      if (!trimmed) return null;
-      if (trimmed.startsWith(":")) {
-        const semi = trimmed.indexOf(";");
-        return semi === -1 ? null : trimmed.slice(semi + 1);
-      }
-      return trimmed;
-    }
-  });
-  const appData = opts.env.APPDATA;
-  if (appData) {
-    sources.push({
-      path: join4(appData, "Microsoft", "Windows", "PowerShell", "PSReadLine", "ConsoleHost_history.txt"),
-      extractCommand: (l) => l.trim() || null
-    });
+async function runInstallList(opts, log2) {
+  const home = opts.home ?? homedir4();
+  const cwd = opts.cwd ?? process.cwd();
+  const os = opts.os ?? CURRENT_OS;
+  const probes = await probeClientsAsync({ home, os, cwd, claudeConfigDir: opts.claudeConfigDir });
+  const rows = probes.map((p) => ({
+    client: INSTALL_TARGETS.find((t) => t.clientId === p.clientId)?.label ?? p.clientId,
+    scope: p.scope,
+    path: displayPath(p.path, home),
+    status: statusFor(p)
+  }));
+  const installed = probes.filter((p) => p.hasMcphEntry).length;
+  const available = probes.filter((p) => !p.unavailable).length;
+  log2(`${installed}/${available} client scopes have mcp.hosting configured on ${os}.`);
+  log2("");
+  const widths = {
+    client: Math.max("CLIENT".length, ...rows.map((r) => r.client.length)),
+    scope: Math.max("SCOPE".length, ...rows.map((r) => r.scope.length)),
+    path: Math.max("PATH".length, ...rows.map((r) => r.path.length)),
+    status: Math.max("STATUS".length, ...rows.map((r) => r.status.length))
+  };
+  const header = `  ${"CLIENT".padEnd(widths.client)}  ${"SCOPE".padEnd(widths.scope)}  ${"PATH".padEnd(widths.path)}  ${"STATUS".padEnd(widths.status)}`;
+  log2(header);
+  for (const r of rows) {
+    log2(
+      `  ${r.client.padEnd(widths.client)}  ${r.scope.padEnd(widths.scope)}  ${r.path.padEnd(widths.path)}  ${r.status.padEnd(widths.status)}`
+    );
   }
-  return sources;
+  log2("");
+  log2("Install into a specific client: `mcph install <client> [--scope user|project|local]`");
+  log2("Install into every available user-scope client: `mcph install --all`");
+  return { written: [], wouldWrite: [], messages: [], exitCode: 0 };
 }
-function readTailLines(path5, n) {
-  try {
-    const raw = readFileSync(path5, "utf8");
-    const all = raw.split(/\r?\n/);
-    return all.length <= n ? all : all.slice(all.length - n);
-  } catch {
-    return [];
+function statusFor(p) {
+  if (p.unavailable) return "unavailable";
+  if (p.malformed) return "malformed";
+  if (p.hasMcphEntry) return "installed";
+  if (p.exists) return "other-entries";
+  return "not installed";
+}
+function displayPath(abs, home) {
+  if (abs === "(n/a)") return abs;
+  if (home && abs.startsWith(home)) {
+    const tail = abs.slice(home.length).replace(/^[\\/]/, "");
+    return `~${process.platform === "win32" ? "\\" : "/"}${tail}`;
   }
+  return abs;
 }
-function extractLeadingBinary(command) {
-  let rest = command.trimStart();
-  if (!rest) return null;
-  if (rest.startsWith("!")) return null;
-  while (/^[A-Z_][A-Z0-9_]*=/i.test(rest)) {
-    const space = rest.indexOf(" ");
-    if (space === -1) return null;
-    rest = rest.slice(space + 1).trimStart();
+async function runInstallAll(opts, log2, err) {
+  const os = opts.os ?? CURRENT_OS;
+  const targets = INSTALL_TARGETS.filter((t) => t.availableOn.includes(os));
+  if (targets.length === 0) {
+    err(`mcph install --all: no installable clients on ${os}.`);
+    return { written: [], wouldWrite: [], messages: [], exitCode: 1 };
   }
-  const prefixes = ["sudo", "time", "command", "exec"];
-  const firstWord = rest.split(/\s+/)[0];
-  if (prefixes.includes(firstWord)) {
-    const space = rest.indexOf(" ");
-    if (space === -1) return null;
-    rest = rest.slice(space + 1).trimStart();
+  const plans = [];
+  const skipped = [];
+  for (const t of targets) {
+    const userScope = t.scopes.find((s) => s.scope === "user");
+    if (userScope) {
+      plans.push({ clientId: t.clientId, scope: "user" });
+      continue;
+    }
+    const firstNoProj = t.scopes.find((s) => !s.requiresProjectDir);
+    if (firstNoProj) {
+      plans.push({ clientId: t.clientId, scope: firstNoProj.scope });
+      continue;
+    }
+    if (opts.projectDir) {
+      plans.push({ clientId: t.clientId, scope: t.scopes[0].scope });
+      continue;
+    }
+    skipped.push({
+      clientId: t.clientId,
+      reason: `requires --project-dir (scopes: ${t.scopes.map((s) => s.scope).join(", ")})`
+    });
   }
-  const first = rest.split(/\s+/)[0];
-  if (!first) return null;
-  if (/[|&;<>()`$]/.test(first)) return null;
-  const slash = Math.max(first.lastIndexOf("/"), first.lastIndexOf("\\"));
-  return slash === -1 ? first : first.slice(slash + 1);
-}
-function compareSemver(a, b) {
-  const parse = (s) => {
-    const m = /^v?(\d+)\.(\d+)\.(\d+)/.exec(s);
-    if (!m) return null;
-    return [Number(m[1]), Number(m[2]), Number(m[3])];
-  };
-  const pa = parse(a);
-  const pb = parse(b);
-  if (!pa || !pb) return 0;
-  for (let i = 0; i < 3; i++) {
-    if (pa[i] < pb[i]) return -1;
-    if (pa[i] > pb[i]) return 1;
+  log2(`Installing into ${plans.length} client${plans.length === 1 ? "" : "s"}\u2026`);
+  if (skipped.length > 0) {
+    for (const s of skipped) log2(`  skip ${s.clientId}: ${s.reason}`);
   }
-  return 0;
+  log2("");
+  const aggregateWritten = [];
+  const aggregateWouldWrite = [];
+  const aggregateMessages = [];
+  let failed = 0;
+  let succeeded = 0;
+  for (const plan of plans) {
+    log2(`\u2500\u2500 ${plan.clientId} (${plan.scope}) \u2500\u2500`);
+    const result = await runInstall({
+      ...opts,
+      listOnly: false,
+      all: false,
+      clientId: plan.clientId,
+      scope: plan.scope
+    });
+    aggregateWritten.push(...result.written);
+    aggregateWouldWrite.push(...result.wouldWrite);
+    aggregateMessages.push(...result.messages);
+    if (result.exitCode === 0) succeeded += 1;
+    else failed += 1;
+    log2("");
+  }
+  const totalPlanned = plans.length;
+  if (failed === 0) {
+    log2(`\u2713 ${succeeded}/${totalPlanned} clients installed successfully.`);
+    return {
+      written: aggregateWritten,
+      wouldWrite: aggregateWouldWrite,
+      messages: aggregateMessages,
+      exitCode: 0
+    };
+  }
+  err(`${failed}/${totalPlanned} client install${failed === 1 ? "" : "s"} failed. ${succeeded} succeeded.`);
+  return {
+    written: aggregateWritten,
+    wouldWrite: aggregateWouldWrite,
+    messages: aggregateMessages,
+    exitCode: 1
+  };
 }
 
-// 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
-      );
+// src/try-cmd.ts
+var TRY_USAGE = `Usage: mcph try <slug> [flags]
+
+  Wire a one-off trial of an MCP server into your AI client. No account
+  needed; the trial points directly at the upstream server and expires
+  after --ttl. Run \`mcph try-cleanup <slug>\` to remove it sooner.
+
+  --client <name>      claude-code | claude-desktop | cursor | vscode
+                       (default: auto-detect, prefers the first installed
+                       client in the order probed by \`mcph install --list\`)
+  --ttl <duration>     How long the trial lives before doctor GCs it
+                       (default: 1h; accepts e.g. 30m, 2h, 7d)
+  --env KEY=value      Set an env var on the trial entry. Repeatable.
+                       Required env vars not supplied here AND not in your
+                       shell's env block the trial with an explainer.
+  --dry-run            Print what would happen without writing anything.
+  --base <url>         Override the explore endpoint base (default:
+                       $MCPH_BASE_URL or https://mcp.hosting).`;
+var TRY_CLEANUP_USAGE = `Usage: mcph try-cleanup <slug>
+
+  Remove a previously-wired trial: peels the mcph-try-<slug> entry out of
+  the AI client config and deletes the marker under ~/.mcph/trials/. Safe
+  to run after the trial expires (no-op if nothing is wired).`;
+var TRIAL_SCHEMA_VERSION = 1;
+var TRIALS_DIRNAME = "trials";
+var ANON_FILENAME = ".anon";
+var DEFAULT_BASE_URL = "https://mcp.hosting";
+var DEFAULT_TTL_MS = 60 * 60 * 1e3;
+function parseTryArgs(argv) {
+  if (argv.length === 0) return { ok: false, error: TRY_USAGE };
+  const positional = [];
+  const opts = {};
+  const env = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = () => argv[++i];
+    switch (a) {
+      case "--client": {
+        const v = next();
+        if (!v || !["claude-code", "claude-desktop", "cursor", "vscode"].includes(v)) {
+          return { ok: false, error: "--client requires claude-code|claude-desktop|cursor|vscode" };
+        }
+        opts.clientId = v;
+        break;
+      }
+      case "--ttl": {
+        const v = next();
+        if (!v) return { ok: false, error: "--ttl requires a value (e.g. 1h, 30m, 7d)" };
+        if (parseDurationMs(v) === null) {
+          return { ok: false, error: `--ttl: cannot parse "${v}" (try 30m, 1h, 2d)` };
+        }
+        opts.ttl = v;
+        break;
+      }
+      case "--env": {
+        const v = next();
+        if (!v || !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);
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+          return { ok: false, error: `--env: invalid KEY "${key}"` };
+        }
+        env[key] = val;
+        break;
+      }
+      case "--dry-run":
+        opts.dryRun = true;
+        break;
+      case "--base": {
+        const v = next();
+        if (!v) return { ok: false, error: "--base requires a URL" };
+        opts.baseUrl = v;
+        break;
+      }
+      case "-h":
+      case "--help":
+        return { ok: false, error: TRY_USAGE };
+      default:
+        if (a.startsWith("--")) return { ok: false, error: `Unknown flag: ${a}
+${TRY_USAGE}` };
+        positional.push(a);
     }
-    [prev, curr] = [curr, prev];
   }
-  return prev[bLen];
+  if (positional.length !== 1) {
+    return { ok: false, error: `Expected exactly one server slug, got ${positional.length}.
+${TRY_USAGE}` };
+  }
+  opts.slug = positional[0];
+  if (Object.keys(env).length > 0) opts.envOverrides = env;
+  return { ok: true, options: opts };
 }
-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;
+function parseTryCleanupArgs(argv) {
+  if (argv.length === 0) return { ok: false, error: TRY_CLEANUP_USAGE };
+  const opts = {};
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "-h" || a === "--help") return { ok: false, error: TRY_CLEANUP_USAGE };
+    if (a === "--base") {
+      const v = argv[++i];
+      if (!v) return { ok: false, error: "--base requires a URL" };
+      opts.baseUrl = v;
+      continue;
     }
-    if (score !== null) scored.push({ name: c, score });
+    if (a.startsWith("--")) return { ok: false, error: `Unknown flag: ${a}
+${TRY_CLEANUP_USAGE}` };
+    positional.push(a);
   }
-  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);
+  if (positional.length !== 1) {
+    return { ok: false, error: `Expected exactly one slug.
+${TRY_CLEANUP_USAGE}` };
+  }
+  opts.slug = positional[0];
+  return { ok: true, options: opts };
 }
-
-// src/install-cmd.ts
-import { existsSync as existsSync2 } from "fs";
-import { chmod, readFile as readFile4 } from "fs/promises";
-import { homedir as homedir5 } from "os";
-import { join as join5, resolve as resolve2 } from "path";
-import { createInterface } from "readline/promises";
-var USAGE = "Usage: mcph 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-mcph-config]\n       mcph install --list                       (detect clients; no writes)\n       mcph install --all  [--token <mcp_pat_\u2026>] (install into every detected client)";
-async function runInstall(opts) {
-  const stdout = opts.io?.stdout ?? process.stdout;
-  const stderr = opts.io?.stderr ?? process.stderr;
-  const messages = [];
-  const log2 = (s) => {
-    messages.push(s);
-    stdout.write(`${s}
-`);
-  };
-  const err = (s) => {
-    messages.push(s);
-    stderr.write(`${s}
-`);
-  };
-  if (opts.listOnly && opts.all) {
-    err("mcph install: --list and --all are mutually exclusive");
-    return { written: [], wouldWrite: [], messages, exitCode: 2 };
+function parseDurationMs(s) {
+  const m = /^(\d+)\s*([smhd])$/i.exec(s.trim());
+  if (!m) return null;
+  const n = Number(m[1]);
+  if (!Number.isFinite(n) || n <= 0) return null;
+  const unit = m[2].toLowerCase();
+  const factor = unit === "s" ? 1e3 : unit === "m" ? 6e4 : unit === "h" ? 36e5 : 864e5;
+  return n * factor;
+}
+function trialsDir(home = homedir5()) {
+  return join5(home, CONFIG_DIRNAME, TRIALS_DIRNAME);
+}
+function trialMarkerPath(slug, home = homedir5()) {
+  return join5(trialsDir(home), `${slug}.json`);
+}
+function anonIdPath(home = homedir5()) {
+  return join5(trialsDir(home), ANON_FILENAME);
+}
+function computeAnonId() {
+  const h = createHash("sha256");
+  h.update(hostname());
+  try {
+    h.update(userInfo().username);
+  } catch {
   }
-  if (opts.listOnly) return runInstallList(opts, log2);
-  if (opts.all) return runInstallAll(opts, log2, err);
-  if (opts.force && opts.skip) {
-    err("mcph install: --force and --skip are mutually exclusive");
-    return { written: [], wouldWrite: [], messages, exitCode: 2 };
+  return h.digest("hex").slice(0, 16);
+}
+async function loadOrCreateAnonId(home = homedir5()) {
+  const path5 = anonIdPath(home);
+  if (existsSync2(path5)) {
+    try {
+      const raw = (await readFile4(path5, "utf8")).trim();
+      if (/^[0-9a-f]{16}$/.test(raw)) return raw;
+    } catch {
+    }
   }
-  if (!opts.clientId) {
-    err(`mcph install: client argument required
-${USAGE}`);
-    return { written: [], wouldWrite: [], messages, exitCode: 2 };
+  const id = computeAnonId();
+  try {
+    await mkdir3(trialsDir(home), { recursive: true });
+    await atomicWriteFile(path5, `${id}
+`);
+    if (process.platform !== "win32") {
+      try {
+        await chmod2(path5, 384);
+      } catch {
+      }
+    }
+  } catch {
   }
-  const target = INSTALL_TARGETS.find((t) => t.clientId === opts.clientId);
-  if (!target) {
-    err(`mcph install: unknown client ${opts.clientId}
-${USAGE}`);
-    return { written: [], wouldWrite: [], messages, exitCode: 2 };
+  return id;
+}
+async function defaultFetchExplore(baseUrl, slug) {
+  const url = `${baseUrl.replace(/\/$/, "")}/api/explore/${encodeURIComponent(slug)}`;
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), 1e4);
+  try {
+    const res = await fetch(url, { signal: ac.signal, headers: { accept: "application/json" } });
+    if (res.status === 404) {
+      throw new Error(`mcph try: no server with slug "${slug}" \u2014 check ${baseUrl}/explore for the catalog.`);
+    }
+    if (!res.ok) {
+      throw new Error(`mcph try: ${url} returned HTTP ${res.status}`);
+    }
+    const body = await res.json();
+    return validateExploreResponse(body, slug);
+  } finally {
+    clearTimeout(timer);
   }
-  const os = opts.os ?? CURRENT_OS;
-  if (!target.availableOn.includes(os)) {
-    const fix = target.clientId === "claude-desktop" && os === "linux" ? "Anthropic ships Claude Desktop on macOS and Windows only. Install Claude Code or Cursor instead." : "Pick a different client or pass --os to override.";
-    err(`mcph install: ${target.label} is not available on ${os}.
-  ${fix}`);
-    return { written: [], wouldWrite: [], messages, exitCode: 2 };
+}
+function validateExploreResponse(body, slug) {
+  if (!body || typeof body !== "object") {
+    throw new Error(`mcph try: /api/explore/${slug} returned a non-object response.`);
   }
-  const scope = opts.scope ?? (target.scopes.find((s) => s.scope === "user") ? "user" : target.scopes[0].scope);
-  const scopeSpec = target.scopes.find((s) => s.scope === scope);
-  if (!scopeSpec) {
-    err(
-      `mcph install: ${target.label} does not support scope "${scope}". Available: ${target.scopes.map((s) => s.scope).join(", ")}`
-    );
-    return { written: [], wouldWrite: [], messages, exitCode: 2 };
+  const b = body;
+  if (typeof b.slug !== "string" || typeof b.name !== "string" || typeof b.command !== "string") {
+    throw new Error(`mcph try: /api/explore/${slug} missing required string fields (slug/name/command).`);
   }
-  const projectDir = scopeSpec.requiresProjectDir ? resolve2(opts.projectDir ?? process.cwd()) : void 0;
-  let resolved;
+  if (!Array.isArray(b.args) || !b.args.every((x) => typeof x === "string")) {
+    throw new Error(`mcph try: /api/explore/${slug} has invalid args (expected string[]).`);
+  }
+  const req = Array.isArray(b.requiredEnvVars) ? b.requiredEnvVars.filter((x) => typeof x === "string") : [];
+  const out = {
+    slug: b.slug,
+    name: b.name,
+    command: b.command,
+    args: b.args,
+    requiredEnvVars: req
+  };
+  if (typeof b.docUrl === "string") out.docUrl = b.docUrl;
+  return out;
+}
+async function defaultPostEvent(baseUrl, body) {
+  const url = `${baseUrl.replace(/\/$/, "")}/api/try/event`;
   try {
-    resolved = resolveInstallPath({
-      clientId: opts.clientId,
-      scope,
-      os,
-      home: opts.home,
-      projectDir,
-      claudeConfigDir: opts.claudeConfigDir
+    const res = await request5(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+      headersTimeout: 5e3,
+      bodyTimeout: 5e3
     });
-  } catch (e) {
-    err(`mcph install: ${e.message}`);
-    return { written: [], wouldWrite: [], messages, exitCode: 2 };
+    await res.body.text().catch(() => {
+    });
+  } catch (err) {
+    log("debug", "try-event post failed", { error: err.message });
   }
-  log2(`Target: ${target.label} (${scope})`);
-  log2(`File:   ${resolved.absolute}`);
-  let token6 = opts.token ?? null;
-  if (!token6) {
-    const cfg = await loadMcphConfig({ home: opts.home, cwd: process.cwd(), env: {} });
-    token6 = cfg.token;
+}
+async function autoDetectClient(opts) {
+  const probes = await probeClientsAsync({
+    home: opts.home,
+    os: opts.os,
+    cwd: opts.cwd,
+    claudeConfigDir: opts.claudeConfigDir
+  });
+  for (const p of probes) {
+    if (!p.unavailable && p.exists && !p.malformed) return p.clientId;
   }
-  if (!token6) {
-    err(
-      "\nmcph install: no token available.\n  Pass one with --token mcp_pat_\u2026, or run `mcph install` with --token once to seed ~/.mcph/config.json,\n  or create the token at https://mcp.hosting \u2192 Settings \u2192 API Tokens."
-    );
-    return { written: [], wouldWrite: [], messages, exitCode: 1 };
+  for (const p of probes) {
+    if (!p.unavailable) return p.clientId;
   }
-  const newEntry = buildLaunchEntry({ os });
-  const containerPath = resolved.containerPath;
-  let existing = {};
-  let existingHasEntry = false;
-  if (existsSync2(resolved.absolute)) {
-    let raw;
-    try {
-      raw = await readFile4(resolved.absolute, "utf8");
-    } catch (e) {
-      err(`mcph install: cannot read ${resolved.absolute}: ${e.message}`);
-      return { written: [], wouldWrite: [], messages, exitCode: 1 };
-    }
-    if (raw.trim().length > 0) {
-      try {
-        const parsed = parseJsonc(raw);
-        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-          err(
-            `mcph install: ${resolved.absolute} is not a JSON object \u2014 refusing to overwrite. Edit by hand or rename the file and re-run.`
-          );
-          return { written: [], wouldWrite: [], messages, exitCode: 1 };
+  return "claude-code";
+}
+async function runTry(opts) {
+  const out = opts.out ?? ((s) => process.stdout.write(s));
+  const err = opts.err ?? ((s) => process.stderr.write(s));
+  const print = (s = "") => out(`${s}
+`);
+  const printErr = (s) => err(`${s}
+`);
+  if (!opts.slug) {
+    printErr(TRY_USAGE);
+    return { exitCode: 2, written: [] };
+  }
+  const slug = opts.slug;
+  if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(slug)) {
+    printErr(`mcph try: invalid slug "${slug}" (lowercase letters, digits, and dashes only).`);
+    return { exitCode: 2, written: [] };
+  }
+  const env = opts.env ?? process.env;
+  const home = opts.home ?? homedir5();
+  const cwd = opts.cwd ?? process.cwd();
+  const os = opts.os ?? CURRENT_OS;
+  const now = opts.now ? opts.now() : Date.now();
+  const baseUrl = opts.baseUrl ?? env.MCPH_BASE_URL ?? DEFAULT_BASE_URL;
+  const ttlMs = opts.ttl ? parseDurationMs(opts.ttl) ?? DEFAULT_TTL_MS : DEFAULT_TTL_MS;
+  const claudeConfigDir = env.CLAUDE_CONFIG_DIR && env.CLAUDE_CONFIG_DIR.length > 0 ? env.CLAUDE_CONFIG_DIR : void 0;
+  const fetchExplore = opts.fetchExplore ?? defaultFetchExplore;
+  let server;
+  try {
+    server = await fetchExplore(baseUrl, slug);
+  } catch (e) {
+    printErr(e.message);
+    return { exitCode: 1, written: [] };
+  }
+  const clientId = opts.clientId ?? await autoDetectClient({ home, os, cwd, claudeConfigDir });
+  const scope = clientId === "vscode" ? "project" : "user";
+  const projectDir = scope === "project" ? resolve3(cwd) : void 0;
+  let resolved;
+  try {
+    resolved = resolveInstallPath({ clientId, scope, os, home, projectDir, claudeConfigDir });
+  } catch (e) {
+    printErr(`mcph try: ${e.message}`);
+    return { exitCode: 1, written: [] };
+  }
+  const supplied = { ...env, ...opts.envOverrides ?? {} };
+  const missing = (server.requiredEnvVars ?? []).filter((k) => !supplied[k] || supplied[k] === "");
+  if (missing.length > 0) {
+    printErr(`mcph try: ${server.name} needs the following env var(s) before it can run:`);
+    for (const k of missing) printErr(`  - ${k}`);
+    printErr("");
+    printErr("Set them via --env KEY=value (repeatable) or your shell, then re-run:");
+    const example = missing.map((k) => `--env ${k}=...`).join(" ");
+    printErr(`  mcph try ${slug} ${example}`);
+    if (server.docUrl) printErr(`Docs: ${server.docUrl}`);
+    return { exitCode: 1, written: [] };
+  }
+  const trialEnv = {};
+  for (const k of server.requiredEnvVars ?? []) {
+    const v = supplied[k];
+    if (v) trialEnv[k] = v;
+  }
+  for (const [k, v] of Object.entries(opts.envOverrides ?? {})) {
+    if (!(k in trialEnv)) trialEnv[k] = v;
+  }
+  const entry = buildLaunchEntry({
+    os,
+    upstream: {
+      command: server.command,
+      args: server.args,
+      env: Object.keys(trialEnv).length > 0 ? trialEnv : void 0
+    }
+  });
+  const entryName = `mcph-try-${slug}`;
+  const expiresAt = now + ttlMs;
+  const marker = {
+    schemaVersion: TRIAL_SCHEMA_VERSION,
+    slug,
+    name: server.name,
+    expiresAt,
+    clientPath: resolved.absolute,
+    clientName: clientId,
+    containerPath: resolved.containerPath,
+    entryName,
+    createdAt: now
+  };
+  let existing = {};
+  if (existsSync2(resolved.absolute)) {
+    try {
+      const raw = await readFile4(resolved.absolute, "utf8");
+      if (raw.trim().length > 0) {
+        const parsed = parseJsonc(raw);
+        if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+          existing = parsed;
+        } else {
+          printErr(`mcph try: ${resolved.absolute} is not a JSON object \u2014 refusing to overwrite.`);
+          return { exitCode: 1, written: [] };
         }
-        existing = parsed;
-      } catch (e) {
-        err(
-          `mcph install: ${resolved.absolute} is not valid JSON (${e.message}). Refusing to overwrite. Fix the file or rename it and re-run.`
-        );
-        return { written: [], wouldWrite: [], messages, exitCode: 1 };
       }
+    } catch (e) {
+      printErr(`mcph try: ${resolved.absolute} is not valid JSON (${e.message}). Refusing to overwrite.`);
+      return { exitCode: 1, written: [] };
     }
-    const container = readNested(existing, containerPath);
-    if (typeof container === "object" && container !== null && !Array.isArray(container)) {
-      existingHasEntry = ENTRY_NAME in container;
+  }
+  const merged = mergeClientConfig(existing, resolved.containerPath, entry, entryName);
+  const clientJson = `${JSON.stringify(merged, null, 2)}
+`;
+  const markerJson = `${JSON.stringify(marker, null, 2)}
+`;
+  if (opts.dryRun) {
+    print(`mcph try (dry-run): would write ${resolved.absolute}`);
+    print(`  entry name: ${entryName}`);
+    print(`  command:    ${entry.command} ${entry.args.join(" ")}`);
+    if (entry.env) print(`  env keys:   ${Object.keys(entry.env).join(", ")}`);
+    print(`  expires:    ${new Date(expiresAt).toISOString()}`);
+    print(`  marker:     ${trialMarkerPath(slug, home)}`);
+    return { exitCode: 0, written: [], marker };
+  }
+  const written = [];
+  try {
+    await mkdir3(trialsDir(home), { recursive: true });
+    await atomicWriteFile(trialMarkerPath(slug, home), markerJson);
+    written.push(trialMarkerPath(slug, home));
+  } catch (e) {
+    printErr(`mcph try: failed to write trial marker: ${e.message}`);
+    return { exitCode: 1, written: [] };
+  }
+  try {
+    await atomicWriteFile(resolved.absolute, clientJson);
+    written.push(resolved.absolute);
+  } catch (e) {
+    printErr(`mcph try: failed to write ${resolved.absolute}: ${e.message}`);
+    await unlink2(trialMarkerPath(slug, home)).catch(() => void 0);
+    return { exitCode: 1, written: [] };
+  }
+  const anonId = await loadOrCreateAnonId(home);
+  const postEvent = opts.postEvent ?? defaultPostEvent;
+  postEvent(baseUrl, { slug, action: "try", anonId }).catch(() => void 0);
+  const ttlPretty = formatTtl(ttlMs);
+  print(`Trial wired: ${server.name} via mcph-try-${slug} -> ${resolved.absolute}`);
+  print(`Expires in ${ttlPretty}; remove sooner with: mcph try-cleanup ${slug}`);
+  print(`Liking it? Sign up at ${baseUrl}/signup to keep ${server.name} on every machine.`);
+  return { exitCode: 0, written, marker };
+}
+async function runTryCleanup(opts) {
+  const out = opts.out ?? ((s) => process.stdout.write(s));
+  const err = opts.err ?? ((s) => process.stderr.write(s));
+  const print = (s = "") => out(`${s}
+`);
+  const printErr = (s) => err(`${s}
+`);
+  if (!opts.slug) {
+    printErr(TRY_CLEANUP_USAGE);
+    return { exitCode: 2, written: [] };
+  }
+  const slug = opts.slug;
+  if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(slug)) {
+    printErr(`mcph try-cleanup: invalid slug "${slug}".`);
+    return { exitCode: 2, written: [] };
+  }
+  const env = opts.env ?? process.env;
+  const home = opts.home ?? homedir5();
+  const baseUrl = opts.baseUrl ?? env.MCPH_BASE_URL ?? DEFAULT_BASE_URL;
+  const markerPath = trialMarkerPath(slug, home);
+  if (!existsSync2(markerPath)) {
+    print(`mcph try-cleanup: no trial marker for "${slug}" (nothing to do).`);
+    return { exitCode: 0, written: [] };
+  }
+  let marker;
+  try {
+    const raw = await readFile4(markerPath, "utf8");
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || typeof parsed.entryName !== "string") {
+      throw new Error("marker is missing required fields");
     }
+    marker = parsed;
+  } catch (e) {
+    printErr(`mcph try-cleanup: marker at ${markerPath} is unreadable (${e.message}).`);
+    return { exitCode: 1, written: [] };
   }
-  if (existingHasEntry) {
-    let decision;
-    if (opts.force) decision = "overwrite";
-    else if (opts.skip) decision = "skip";
-    else if (opts.promptAnswer) decision = opts.promptAnswer;
-    else if (opts.io?.isTTY ?? process.stdout.isTTY) {
-      decision = await promptCollision(resolved.absolute, opts.io);
-    } else {
-      err(
-        `mcph install: ${resolved.absolute} already has a "${ENTRY_NAME}" entry and stdin is not a TTY.
-  Re-run with --force to overwrite, --skip to leave it, or --dry-run to preview.`
+  if (existsSync2(marker.clientPath)) {
+    try {
+      const raw = await readFile4(marker.clientPath, "utf8");
+      if (raw.trim().length > 0) {
+        const parsed = parseJsonc(raw);
+        if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+          const stripped = removeFromClientConfig(
+            parsed,
+            marker.containerPath,
+            marker.entryName
+          );
+          if (stripped !== parsed) {
+            await atomicWriteFile(marker.clientPath, `${JSON.stringify(stripped, null, 2)}
+`);
+            print(`Removed ${marker.entryName} from ${marker.clientPath}`);
+          }
+        }
+      }
+    } catch (e) {
+      printErr(
+        `mcph try-cleanup: warning \u2014 couldn't strip ${marker.entryName} from ${marker.clientPath} (${e.message}).`
       );
-      return { written: [], wouldWrite: [], messages, exitCode: 1 };
     }
-    if (decision === "skip") {
-      log2(`Existing "${ENTRY_NAME}" entry left untouched. Nothing to do.`);
-      return { written: [], wouldWrite: [], messages, exitCode: 0 };
+  }
+  try {
+    await unlink2(markerPath);
+  } catch (e) {
+    printErr(`mcph try-cleanup: couldn't delete marker ${markerPath} (${e.message}).`);
+    return { exitCode: 1, written: [] };
+  }
+  const anonId = await loadOrCreateAnonId(home);
+  const postEvent = opts.postEvent ?? defaultPostEvent;
+  postEvent(baseUrl, { slug, action: "cleanup", anonId }).catch(() => void 0);
+  print(`Trial for "${slug}" cleaned up.`);
+  return { exitCode: 0, written: [marker.clientPath] };
+}
+function formatTtl(ms) {
+  const clamped = Math.max(0, ms);
+  if (clamped < 6e4) return `${Math.round(clamped / 1e3)}s`;
+  if (clamped < 36e5) return `${Math.round(clamped / 6e4)}m`;
+  if (clamped < 864e5) return `${Math.round(clamped / 36e5)}h`;
+  return `${Math.round(clamped / 864e5)}d`;
+}
+async function scanTrials(opts = {}) {
+  const home = opts.home ?? homedir5();
+  const now = opts.now ? opts.now() : Date.now();
+  const dir = trialsDir(home);
+  const result = { live: [], expired: [], malformed: [] };
+  if (!existsSync2(dir)) return result;
+  let entries;
+  try {
+    entries = await readdir(dir);
+  } catch {
+    return result;
+  }
+  for (const filename of entries) {
+    if (!filename.endsWith(".json")) continue;
+    const path5 = join5(dir, filename);
+    try {
+      const raw = await readFile4(path5, "utf8");
+      const parsed = JSON.parse(raw);
+      if (!parsed || typeof parsed !== "object" || typeof parsed.slug !== "string" || typeof parsed.expiresAt !== "number" || typeof parsed.clientPath !== "string" || !Array.isArray(parsed.containerPath) || typeof parsed.entryName !== "string") {
+        result.malformed.push(path5);
+        continue;
+      }
+      const msUntilExpiry = parsed.expiresAt - now;
+      const expired = msUntilExpiry <= 0;
+      const entry = { marker: parsed, msUntilExpiry, expired };
+      if (expired) result.expired.push(entry);
+      else result.live.push(entry);
+    } catch {
+      result.malformed.push(path5);
     }
-    if (decision === "abort") {
-      err("Aborted.");
-      return { written: [], wouldWrite: [], messages, exitCode: 1 };
+  }
+  return result;
+}
+async function gcExpiredTrials(opts) {
+  const home = opts.home ?? homedir5();
+  const env = opts.env ?? process.env;
+  const baseUrl = opts.baseUrl ?? env.MCPH_BASE_URL ?? DEFAULT_BASE_URL;
+  const postEvent = opts.postEvent ?? defaultPostEvent;
+  const scan = await scanTrials({ home, now: opts.now });
+  if (scan.expired.length === 0) return { cleared: 0, failed: 0 };
+  const anonId = await loadOrCreateAnonId(home);
+  let cleared = 0;
+  let failed = 0;
+  for (const { marker } of scan.expired) {
+    try {
+      if (existsSync2(marker.clientPath)) {
+        const raw = await readFile4(marker.clientPath, "utf8");
+        if (raw.trim().length > 0) {
+          const parsed = parseJsonc(raw);
+          if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+            const stripped = removeFromClientConfig(
+              parsed,
+              marker.containerPath,
+              marker.entryName
+            );
+            if (stripped !== parsed) {
+              await atomicWriteFile(marker.clientPath, `${JSON.stringify(stripped, null, 2)}
+`);
+            }
+          }
+        }
+      }
+      await unlink2(trialMarkerPath(marker.slug, home));
+      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 });
+      failed++;
     }
-    log2(`Overwriting existing "${ENTRY_NAME}" entry.`);
   }
-  const merged = mergeClientConfig(existing, containerPath, newEntry);
-  const clientJson = `${JSON.stringify(merged, null, 2)}
-`;
-  const writeMcphConfig = !opts.skipMcphConfig;
-  const home = opts.home ?? homedir5();
-  const mcphConfigPath = join5(home, CONFIG_DIRNAME, CONFIG_FILENAME);
-  const mcphConfigComposed = await composeMcphConfig(mcphConfigPath, token6);
-  if (mcphConfigComposed.backupPath) {
-    log2(
-      `mcph install: existing ${mcphConfigPath} was malformed; original bytes backed up to ${mcphConfigComposed.backupPath} before overwriting.`
-    );
+  return { cleared, failed };
+}
+
+// src/usage-hints.ts
+var MAX_PEERS = 3;
+var MIN_SUCCESS_TO_SHOW = 1;
+var RELIABILITY_MIN_OBSERVATIONS = 3;
+var RELIABILITY_THRESHOLD = 0.8;
+function buildCoUsageMap(packs) {
+  const result = /* @__PURE__ */ new Map();
+  for (const pack of packs) {
+    for (const ns of pack.namespaces) {
+      const bucket = result.get(ns) ?? /* @__PURE__ */ new Set();
+      for (const peer of pack.namespaces) {
+        if (peer !== ns) bucket.add(peer);
+      }
+      result.set(ns, bucket);
+    }
+  }
+  const sorted = /* @__PURE__ */ new Map();
+  for (const [ns, peers] of result) {
+    sorted.set(ns, Array.from(peers).sort());
+  }
+  return sorted;
+}
+function formatUsageHint(usage, coUsedWith) {
+  const parts = [];
+  if (usage && usage.succeeded >= MIN_SUCCESS_TO_SHOW) {
+    parts.push(`used ${usage.succeeded}x`);
+  }
+  if (coUsedWith.length > 0) {
+    const shown = coUsedWith.slice(0, MAX_PEERS);
+    const more = coUsedWith.length - shown.length;
+    const names = shown.map((n) => `"${n}"`).join(", ");
+    const tail = more > 0 ? ` +${more} more` : "";
+    parts.push(`often loaded with ${names}${tail}`);
+  }
+  if (parts.length === 0) return null;
+  return `usage: ${parts.join("; ")}`;
+}
+function formatReliabilityWarning(usage) {
+  if (!usage || usage.dispatched < RELIABILITY_MIN_OBSERVATIONS) return null;
+  const rate = usage.succeeded / usage.dispatched;
+  if (rate >= RELIABILITY_THRESHOLD) return null;
+  const pct = Math.round(rate * 100);
+  return `reliability: ${pct}% success across ${usage.dispatched} past calls`;
+}
+function selectFlakyNamespaces(entries, limit) {
+  if (limit <= 0) return [];
+  return Array.from(entries).filter(({ usage }) => {
+    if (usage.dispatched < RELIABILITY_MIN_OBSERVATIONS) return false;
+    return usage.succeeded / usage.dispatched < RELIABILITY_THRESHOLD;
+  }).sort((a, b) => {
+    const aRate = a.usage.succeeded / a.usage.dispatched;
+    const bRate = b.usage.succeeded / b.usage.dispatched;
+    if (aRate !== bRate) return aRate - bRate;
+    if (a.usage.dispatched !== b.usage.dispatched) return b.usage.dispatched - a.usage.dispatched;
+    return a.namespace.localeCompare(b.namespace);
+  }).slice(0, limit);
+}
+
+// src/doctor-cmd.ts
+var VERSION = true ? "0.54.0" : "dev";
+async function runDoctor(opts = {}) {
+  if (opts.json) return runDoctorJson(opts);
+  const lines = [];
+  const write = opts.out ?? ((s) => process.stdout.write(s));
+  const print = (s = "") => {
+    lines.push(s);
+    write(`${s}
+`);
+  };
+  const cwd = opts.cwd ?? process.cwd();
+  const home = opts.home ?? homedir6();
+  const os = opts.os ?? CURRENT_OS;
+  const env = opts.env ?? process.env;
+  print(`mcph doctor \u2014 ${(/* @__PURE__ */ new Date()).toISOString()}`);
+  print(`mcph version: ${VERSION}`);
+  print(`platform: ${os}`);
+  print("");
+  const config = await loadMcphConfig({ cwd, home, env });
+  print("CONFIG FILES");
+  if (config.loadedFiles.length === 0) {
+    print("  (none \u2014 using defaults + env)");
+  } else {
+    for (const f of config.loadedFiles) {
+      print(`  ${f.scope.padEnd(7)} ${f.path}${schemaSuffix(f)}`);
+    }
+  }
+  print("");
+  print("TOKEN");
+  print(`  value:  ${tokenFingerprint(config.token)}`);
+  print(`  source: ${config.tokenSource}`);
+  print("");
+  print("API BASE");
+  print(`  value:  ${config.apiBase}`);
+  print(`  source: ${config.apiBaseSource}`);
+  print("");
+  renderEnvSection({ env, print });
+  await renderStateSection({ home, env, print });
+  await renderReliabilitySection({ home, env, print });
+  await renderTrialsSection({ home, env, print, postEvent: opts.postTryEvent, now: opts.now });
+  renderBackgroundPostersSection({ print });
+  const claudeConfigDir = env.CLAUDE_CONFIG_DIR && env.CLAUDE_CONFIG_DIR.length > 0 ? env.CLAUDE_CONFIG_DIR : void 0;
+  const clients = probeClients({ home, os, cwd, claudeConfigDir });
+  print("INSTALLED CLIENTS (probed config files)");
+  for (const c of clients) {
+    const status = c.unavailable ? "unavailable on this OS" : c.malformed ? "exists but JSON is malformed \u2014 fix or rerun `mcph install`" : c.hasMcphEntry ? `OK \u2014 has "${ENTRY_NAME}" entry` : c.exists ? `present, no "${ENTRY_NAME}" entry \u2014 run \`mcph install ${c.clientId}${c.scope === "user" ? "" : ` --scope ${c.scope}`}\`` : `not configured \u2014 run \`mcph install ${c.clientId}${c.scope === "user" ? "" : ` --scope ${c.scope}`}\``;
+    const label = INSTALL_TARGETS.find((t) => t.clientId === c.clientId)?.label ?? c.clientId;
+    print(`  ${label} (${c.scope}): ${status}`);
+    print(`    ${c.path}`);
+  }
+  print("");
+  if (config.warnings.length > 0) {
+    print("WARNINGS");
+    for (const w of config.warnings) print(`  ! ${w}`);
+    print("");
+  }
+  const shadowHits = scanShellHistoryForShadows({ home, env });
+  if (shadowHits.length > 0) {
+    print("SHADOWED CLI USAGE (recent shell history)");
+    print("  Commands below have MCP servers that can replace them;");
+    print("  activate the server and prefer its tools over the CLI.");
+    for (const hit of shadowHits) {
+      const pluralHit = hit.count === 1 ? "time" : "times";
+      print(`  ${hit.cli.padEnd(12)} ${hit.count} ${pluralHit} \u2192 server(s): ${hit.namespaces.join(", ")}`);
+    }
+    print("");
+  }
+  const skipCheck = opts.skipRegistryCheck === true || Boolean(process.env.VITEST);
+  const latest = skipCheck ? null : await fetchLatestVersion(opts.registryFetch);
+  const staleHint = latest && VERSION !== "dev" && compareSemver(VERSION, latest) < 0 ? latest : null;
+  if (staleHint) {
+    print("UPGRADE AVAILABLE");
+    print(`  Running ${VERSION}; npm latest is ${staleHint}.`);
+    print("  Run `mcph upgrade` to see the exact command for your install, or");
+    print("  `mcph upgrade --run` to execute it (global-npm installs only).");
+    print("");
+  }
+  let exitCode = 0;
+  if (config.token === null) {
+    exitCode = 1;
+    print("DIAGNOSIS");
+    print("  No token resolved \u2014 mcph cannot start.");
+    print("  Run `mcph install <client> --token mcp_pat_\u2026` to seed ~/.mcph/config.json.");
+  } else if (config.warnings.length > 0) {
+    exitCode = 2;
+    print("DIAGNOSIS");
+    print("  Token present, but warnings above need attention.");
+  } else {
+    print("DIAGNOSIS");
+    print(staleHint ? "  Healthy, but an upgrade is available (see above)." : "  All good. mcph should start cleanly.");
+  }
+  return { exitCode, lines, snapshot: { version: VERSION, config, clients } };
+}
+async function runDoctorJson(opts) {
+  const lines = [];
+  const write = opts.out ?? ((s) => process.stdout.write(s));
+  const cwd = opts.cwd ?? process.cwd();
+  const home = opts.home ?? homedir6();
+  const os = opts.os ?? CURRENT_OS;
+  const env = opts.env ?? process.env;
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+  const config = await loadMcphConfig({ cwd, home, env });
+  const claudeConfigDir = env.CLAUDE_CONFIG_DIR && env.CLAUDE_CONFIG_DIR.length > 0 ? env.CLAUDE_CONFIG_DIR : void 0;
+  const clients = probeClients({ home, os, cwd, claudeConfigDir });
+  const envVarNames = [
+    "MCPH_POLL_INTERVAL",
+    "MCPH_SERVER_CAP",
+    "MCPH_MIN_COMPLIANCE",
+    "MCPH_AUTO_LOAD",
+    "MCPH_AUTO_ACTIVATE",
+    "MCPH_PRUNE_RESPONSES"
+  ];
+  const envOverrides = {};
+  for (const name of envVarNames) {
+    const raw = env[name];
+    envOverrides[name] = raw === void 0 || raw === "" ? null : raw;
+  }
+  const persistRaw = env.MCPH_DISABLE_PERSISTENCE;
+  const persistDisabled = persistRaw !== void 0 && persistRaw !== "" && (persistRaw === "1" || persistRaw.toLowerCase() === "true");
+  const state = persistDisabled ? { disabled: true, path: null, savedAt: null, learningEntries: null, packHistoryEntries: null } : await (async () => {
+    const filePath = join6(userConfigDir(home), STATE_FILENAME);
+    const persisted = await loadState(filePath);
+    const fresh = persisted.savedAt === 0;
+    return {
+      disabled: false,
+      path: filePath,
+      savedAt: fresh ? null : new Date(persisted.savedAt).toISOString(),
+      learningEntries: fresh ? 0 : Object.keys(persisted.learning).length,
+      packHistoryEntries: fresh ? 0 : persisted.packHistory.length
+    };
+  })();
+  const reliability = [];
+  if (!persistDisabled) {
+    const filePath = join6(userConfigDir(home), STATE_FILENAME);
+    const persisted = await loadState(filePath);
+    if (persisted.savedAt !== 0) {
+      const entries = Object.entries(persisted.learning).map(([namespace, usage]) => ({ namespace, usage }));
+      for (const { namespace, usage } of selectFlakyNamespaces(entries, 5)) {
+        reliability.push({
+          namespace,
+          dispatched: usage.dispatched,
+          succeeded: usage.succeeded,
+          successRate: usage.succeeded / usage.dispatched,
+          lastUsedAt: new Date(usage.lastUsedAt).toISOString()
+        });
+      }
+    }
+  }
+  const shellShadows = scanShellHistoryForShadows({ home, env });
+  const skipCheck = opts.skipRegistryCheck === true || Boolean(process.env.VITEST);
+  const latest = skipCheck ? null : await fetchLatestVersion(opts.registryFetch);
+  const stale = latest !== null && VERSION !== "dev" && compareSemver(VERSION, latest) < 0;
+  let exitCode = 0;
+  let summary;
+  if (config.token === null) {
+    exitCode = 1;
+    summary = "No token resolved \u2014 mcph cannot start.";
+  } else if (config.warnings.length > 0) {
+    exitCode = 2;
+    summary = "Token present, but warnings need attention.";
+  } else {
+    summary = stale ? "Healthy, but an upgrade is available." : "All good. mcph should start cleanly.";
+  }
+  const snapshotJson = {
+    timestamp,
+    version: VERSION,
+    platform: os,
+    token: { fingerprint: tokenFingerprint(config.token), source: config.tokenSource },
+    apiBase: { value: config.apiBase, source: config.apiBaseSource },
+    loadedFiles: config.loadedFiles.map((f) => ({
+      scope: f.scope,
+      path: f.path,
+      ...f.version !== void 0 ? { schemaVersion: f.version } : {},
+      schemaAhead: f.version !== void 0 && f.version > CURRENT_SCHEMA_VERSION
+    })),
+    warnings: config.warnings,
+    env: envOverrides,
+    state,
+    reliability,
+    clients,
+    shellShadows,
+    upgrade: { current: VERSION, latest, stale },
+    diagnosis: { exitCode, summary }
+  };
+  const blob = JSON.stringify(snapshotJson, null, 2);
+  lines.push(blob);
+  write(`${blob}
+`);
+  return { exitCode, lines, snapshot: { version: VERSION, config, clients } };
+}
+function renderEnvSection(opts) {
+  const { env, print } = opts;
+  const vars = [
+    { name: "MCPH_POLL_INTERVAL", defaultHint: "default 60s" },
+    { name: "MCPH_SERVER_CAP", defaultHint: "default 6" },
+    { name: "MCPH_MIN_COMPLIANCE", defaultHint: "filter inactive" },
+    { name: "MCPH_AUTO_LOAD", defaultHint: "auto-load inactive" },
+    { name: "MCPH_AUTO_ACTIVATE", defaultHint: "default on" },
+    { name: "MCPH_PRUNE_RESPONSES", defaultHint: "pruning active" }
+  ];
+  const widest = vars.reduce((m, v) => Math.max(m, v.name.length), 0);
+  print("ENVIRONMENT (behavior overrides)");
+  for (const v of vars) {
+    const raw = env[v.name];
+    const value = raw === void 0 || raw === "" ? `(not set \u2014 ${v.defaultHint})` : raw;
+    print(`  ${v.name.padEnd(widest)}  ${value}`);
+  }
+  print("");
+}
+async function renderStateSection(opts) {
+  const { home, env, print } = opts;
+  const raw = env.MCPH_DISABLE_PERSISTENCE;
+  const disabled = raw !== void 0 && raw !== "" && (raw === "1" || raw.toLowerCase() === "true");
+  print("STATE");
+  if (disabled) {
+    print("  status: disabled via MCPH_DISABLE_PERSISTENCE");
+    print("");
+    return;
+  }
+  const filePath = join6(userConfigDir(home), STATE_FILENAME);
+  print(`  path:   ${filePath}`);
+  const peek = await peekStateFile(filePath);
+  if (peek.kind === "malformed") {
+    print("  status: corrupt -- file exists but JSON is unparseable");
+    print(`  fix:    \`mcph reset-learning\` to clear, or open ${filePath} and fix by hand`);
+    print(`  detail: ${peek.message}`);
+    print("");
+    return;
   }
-  const mcphConfigJson = mcphConfigComposed.json;
-  const settingsPatch = opts.clientId === "claude-code" ? await prepareClaudeCodeSettingsPatch({
-    scope,
-    home,
-    projectDir,
-    os,
-    claudeConfigDir: opts.claudeConfigDir
-  }) : null;
-  if (opts.dryRun) {
-    log2("\n--- dry run: would write the following ---");
-    if (writeMcphConfig) log2(`# ${mcphConfigPath}
-${mcphConfigJson}`);
-    log2(`
-# ${resolved.absolute}
-${clientJson}`);
-    if (settingsPatch?.changed) log2(`# ${settingsPatch.path}
-${settingsPatch.nextJson}`);
-    const wouldWrite = [];
-    if (writeMcphConfig) wouldWrite.push(mcphConfigPath);
-    wouldWrite.push(resolved.absolute);
-    if (settingsPatch?.changed) wouldWrite.push(settingsPatch.path);
-    return { written: [], wouldWrite, messages, exitCode: 0 };
+  if (peek.kind === "stale-version") {
+    print(`  status: schema mismatch (file is v${peek.version ?? "?"}, this mcph reads v${peek.expected})`);
+    print("  fix:    `mcph reset-learning` to drop the old file -- learning will rebuild on use");
+    print("");
+    return;
   }
-  const written = [];
-  if (writeMcphConfig) {
-    try {
-      await atomicWriteFile(mcphConfigPath, mcphConfigJson);
-      if (process.platform !== "win32") {
-        try {
-          await chmod(mcphConfigPath, 384);
-        } catch {
-        }
-      }
-    } catch (e) {
-      err(`mcph install: failed to write ${mcphConfigPath}: ${e.message}`);
-      return { written: [], wouldWrite: [], messages, exitCode: 1 };
+  if (peek.kind === "unreadable") {
+    print(`  status: unreadable (${peek.message})`);
+    print("");
+    return;
+  }
+  const persisted = await loadState(filePath);
+  if (persisted.savedAt === 0) {
+    print("  (no persisted state yet \u2014 will be created on the first tool call)");
+  } else {
+    print(`  last saved:           ${formatRelativeAge(Date.now() - persisted.savedAt)} ago`);
+    print(`  learning entries:     ${Object.keys(persisted.learning).length}`);
+    print(`  pack history entries: ${persisted.packHistory.length}`);
+  }
+  print("");
+}
+async function peekStateFile(filePath) {
+  let raw;
+  try {
+    raw = await readFile5(filePath, "utf8");
+  } catch (err) {
+    if (err && typeof err === "object" && "code" in err && err.code === "ENOENT") {
+      return { kind: "missing" };
     }
-    log2(`Wrote ${mcphConfigPath}`);
-    written.push(mcphConfigPath);
+    return { kind: "unreadable", message: err instanceof Error ? err.message : String(err) };
   }
+  let parsed;
   try {
-    await atomicWriteFile(resolved.absolute, clientJson);
-  } catch (e) {
-    err(`mcph install: failed to write ${resolved.absolute}: ${e.message}`);
-    return { written, wouldWrite: [], messages, exitCode: 1 };
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    return { kind: "malformed", message: err instanceof Error ? err.message : String(err) };
   }
-  log2(`Wrote ${resolved.absolute}`);
-  written.push(resolved.absolute);
-  if (settingsPatch?.changed) {
-    try {
-      await atomicWriteFile(settingsPatch.path, settingsPatch.nextJson);
-      log2(`Wrote ${settingsPatch.path} (added ${CLAUDE_CODE_ALLOW_PATTERN} to permissions.allow)`);
-      written.push(settingsPatch.path);
-    } catch (e) {
-      err(
-        `mcph install: warning \u2014 failed to patch ${settingsPatch.path}: ${e.message}. You may be re-prompted for each mcph tool call; add "${CLAUDE_CODE_ALLOW_PATTERN}" to permissions.allow to silence.`
-      );
-    }
+  if (!parsed || typeof parsed !== "object") return { kind: "malformed", message: "top-level value is not an object" };
+  const version = parsed.version;
+  if (version !== STATE_SCHEMA_VERSION) {
+    return { kind: "stale-version", version, expected: STATE_SCHEMA_VERSION };
   }
-  if (target.notes) log2(`Note: ${target.notes}`);
-  log2(`
-\u2713 ${target.label} is configured. Restart it to pick up the new MCP server.`);
-  return { written, wouldWrite: [], messages, exitCode: 0 };
+  return { kind: "ok" };
 }
-async function prepareClaudeCodeSettingsPatch(opts) {
-  const path5 = resolveClaudeCodeSettingsPath(opts.scope, {
-    home: opts.home,
-    projectDir: opts.projectDir,
-    os: opts.os,
-    claudeConfigDir: opts.claudeConfigDir
-  });
-  if (!path5) return null;
-  let existing = {};
-  if (existsSync2(path5)) {
-    try {
-      const raw = await readFile4(path5, "utf8");
-      if (raw.trim().length > 0) {
-        const parsed = parseJsonc(raw);
-        if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
-          existing = parsed;
-        } else {
-          return { path: path5, nextJson: "", changed: false };
-        }
-      }
-    } catch {
-      return { path: path5, nextJson: "", changed: false };
-    }
+async function renderReliabilitySection(opts) {
+  const { home, env, print } = opts;
+  const raw = env.MCPH_DISABLE_PERSISTENCE;
+  const disabled = raw !== void 0 && raw !== "" && (raw === "1" || raw.toLowerCase() === "true");
+  if (disabled) return;
+  const filePath = join6(userConfigDir(home), STATE_FILENAME);
+  const persisted = await loadState(filePath);
+  if (persisted.savedAt === 0) return;
+  const entries = Object.entries(persisted.learning).map(([namespace, usage]) => ({ namespace, usage }));
+  const flaky = selectFlakyNamespaces(entries, 5);
+  if (flaky.length === 0) return;
+  print("RELIABILITY (dormant, <80% success)");
+  const now = Date.now();
+  for (const { namespace, usage } of flaky) {
+    const rate = Math.round(usage.succeeded / usage.dispatched * 100);
+    const age = formatRelativeAge(now - usage.lastUsedAt);
+    print(`  ${namespace} \u2014 ${usage.dispatched} calls, ${rate}% success, last used ${age} ago`);
   }
-  const merged = mergePermissionsAllow(existing, [CLAUDE_CODE_ALLOW_PATTERN]);
-  const before = JSON.stringify(existing);
-  const after = JSON.stringify(merged);
-  if (before === after) return { path: path5, nextJson: "", changed: false };
-  return { path: path5, nextJson: `${JSON.stringify(merged, null, 2)}
-`, changed: true };
+  print("");
 }
-function mergePermissionsAllow(existing, patterns) {
-  const out = { ...existing };
-  const prev = out.permissions;
-  const perms = typeof prev === "object" && prev !== null && !Array.isArray(prev) ? { ...prev } : {};
-  const prevAllow = perms.allow;
-  const allow = Array.isArray(prevAllow) ? prevAllow.filter((x) => typeof x === "string") : [];
-  for (const p of patterns) {
-    if (!allow.includes(p)) allow.push(p);
+async function renderTrialsSection(opts) {
+  const { home, env, print, postEvent, now } = opts;
+  const gc = await gcExpiredTrials({ home, env, postEvent, now }).catch(() => ({ cleared: 0, failed: 0 }));
+  const scan = await scanTrials({ home, now });
+  if (scan.live.length === 0 && gc.cleared === 0 && scan.malformed.length === 0) return;
+  print("TRIALS (mcph try)");
+  if (gc.cleared > 0) {
+    print(`  swept ${gc.cleared} expired trial${gc.cleared === 1 ? "" : "s"} this run`);
+  }
+  for (const { marker, msUntilExpiry } of scan.live) {
+    print(`  ${marker.slug} -> ${marker.clientName} (${marker.clientPath}) \u2014 expires in ${formatTtl(msUntilExpiry)}`);
+  }
+  for (const path5 of scan.malformed) {
+    print(`  ! malformed marker at ${path5} (delete by hand)`);
+  }
+  print("");
+}
+function renderBackgroundPostersSection(opts) {
+  const { print } = opts;
+  const analyticsFailure = getLastAnalyticsFailure();
+  const reportFailure = getLastReportFailure();
+  if (!analyticsFailure && !reportFailure) return;
+  const now = Date.now();
+  const fmt = (f) => `HTTP ${f.statusCode} from ${f.url}, ${formatRelativeAge(now - f.at)} ago`;
+  print("BACKGROUND POSTERS (recent failures)");
+  print(`  analytics:    ${analyticsFailure ? fmt(analyticsFailure) : "(no recent failure)"}`);
+  print(`  tool-report:  ${reportFailure ? fmt(reportFailure) : "(no recent failure)"}`);
+  print("");
+}
+function formatRelativeAge(ms) {
+  const clamped = Math.max(0, ms);
+  const s = Math.floor(clamped / 1e3);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h`;
+  const d = Math.floor(h / 24);
+  return `${d}d`;
+}
+function schemaSuffix(f) {
+  if (f.version === void 0) return "";
+  if (f.version > CURRENT_SCHEMA_VERSION)
+    return ` (schema v${f.version}, this mcph supports v${CURRENT_SCHEMA_VERSION})`;
+  return ` (schema v${f.version})`;
+}
+function probeClients(opts) {
+  const out = [];
+  for (const target of INSTALL_TARGETS) {
+    const unavailable = !target.availableOn.includes(opts.os);
+    if (unavailable) {
+      out.push({
+        clientId: target.clientId,
+        scope: target.scopes[0].scope,
+        path: "(n/a)",
+        exists: false,
+        hasMcphEntry: false,
+        malformed: false,
+        unavailable: true
+      });
+      continue;
+    }
+    for (const scope of target.scopes) {
+      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 = existsSync3(resolved.absolute);
+      let hasMcphEntry = false;
+      let 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) hasMcphEntry = ENTRY_NAME in container;
+            } else {
+              malformed = true;
+            }
+          }
+        } catch {
+          malformed = true;
+        }
+      }
+      out.push({
+        clientId: target.clientId,
+        scope: scope.scope,
+        path: resolved.absolute,
+        exists: exists3,
+        hasMcphEntry,
+        malformed,
+        unavailable: false
+      });
+    }
   }
-  perms.allow = allow;
-  out.permissions = perms;
   return out;
 }
-async function promptCollision(path5, io) {
-  const stdin = io?.stdin ?? process.stdin;
-  const stdout = io?.stdout ?? process.stdout;
-  const rl = createInterface({ input: stdin, output: stdout });
-  try {
-    const answer = (await rl.question(
-      `${path5} already has an "${ENTRY_NAME}" entry.
-  [o]verwrite, [s]kip, or [a]bort? (default: skip) `
-    )).trim().toLowerCase();
-    if (answer.startsWith("o")) return "overwrite";
-    if (answer.startsWith("a")) return "abort";
-    return "skip";
-  } finally {
-    rl.close();
-  }
-}
-function readNested(root, containerPath) {
+function walkContainer(root, path5) {
   let cur = root;
-  for (const key of containerPath) {
-    if (typeof cur !== "object" || cur === null || Array.isArray(cur)) return void 0;
+  for (const key of path5) {
+    if (typeof cur !== "object" || cur === null || Array.isArray(cur)) return null;
     cur = cur[key];
   }
+  if (typeof cur !== "object" || cur === null || Array.isArray(cur)) return null;
   return cur;
 }
-function mergeClientConfig(existing, containerPath, entry) {
-  if (containerPath.length === 0) throw new Error("mergeClientConfig: containerPath cannot be empty");
-  const out = { ...existing };
-  let parent = out;
-  for (let i = 0; i < containerPath.length - 1; i++) {
-    const key = containerPath[i];
-    const child = parent[key];
-    const cloned = typeof child === "object" && child !== null && !Array.isArray(child) ? { ...child } : {};
-    parent[key] = cloned;
-    parent = cloned;
-  }
-  const leafKey = containerPath[containerPath.length - 1];
-  const prev = parent[leafKey];
-  const container = typeof prev === "object" && prev !== null && !Array.isArray(prev) ? { ...prev } : {};
-  container[ENTRY_NAME] = entry;
-  parent[leafKey] = container;
-  return out;
-}
-async function composeMcphConfig(path5, token6) {
-  let existing = {};
-  let backupPath;
-  if (existsSync2(path5)) {
-    let raw = "";
-    try {
-      raw = await readFile4(path5, "utf8");
-    } catch {
-      raw = "";
+async function probeClientsAsync(opts) {
+  const result = [];
+  for (const target of INSTALL_TARGETS) {
+    const unavailable = !target.availableOn.includes(opts.os);
+    if (unavailable) {
+      result.push({
+        clientId: target.clientId,
+        scope: target.scopes[0].scope,
+        path: "(n/a)",
+        exists: false,
+        hasMcphEntry: false,
+        malformed: false,
+        unavailable: true
+      });
+      continue;
     }
-    if (raw) {
-      try {
-        const parsed = parseJsonc(raw);
-        if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
-          existing = parsed;
-        }
-      } catch {
-        const candidate = `${path5}.bak-${Date.now()}`;
+    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
+      });
+      const exists3 = existsSync3(resolved.absolute);
+      let hasMcphEntry = false;
+      let malformed = false;
+      if (exists3) {
         try {
-          await atomicWriteFile(candidate, raw);
-          backupPath = candidate;
+          const raw = await readFile5(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) hasMcphEntry = ENTRY_NAME in container;
+            } else {
+              malformed = true;
+            }
+          }
         } catch {
+          malformed = true;
         }
       }
-    }
-  }
-  const next = { version: CURRENT_SCHEMA_VERSION, ...existing };
-  next.token = token6;
-  if (typeof next.version !== "number") next.version = CURRENT_SCHEMA_VERSION;
-  return { json: `${JSON.stringify(next, null, 2)}
-`, backupPath };
-}
-function parseInstallArgs(argv) {
-  if (argv.length === 0) return { ok: false, error: USAGE };
-  const positional = [];
-  const opts = {};
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i];
-    const next = () => argv[++i];
-    switch (a) {
-      case "--scope": {
-        const v = next();
-        if (!v || !["user", "project", "local"].includes(v))
-          return { ok: false, error: "--scope requires user|project|local" };
-        opts.scope = v;
-        break;
-      }
-      case "--os": {
-        const v = next();
-        if (!v || !["macos", "linux", "windows"].includes(v))
-          return { ok: false, error: "--os requires macos|linux|windows" };
-        opts.os = v;
-        break;
-      }
-      case "--token": {
-        const v = next();
-        if (!v) return { ok: false, error: "--token requires a value" };
-        opts.token = v;
-        break;
-      }
-      case "--project-dir": {
-        const v = next();
-        if (!v) return { ok: false, error: "--project-dir requires a value" };
-        opts.projectDir = v;
-        break;
-      }
-      case "--force":
-        opts.force = true;
-        break;
-      case "--skip":
-        opts.skip = true;
-        break;
-      case "--dry-run":
-        opts.dryRun = true;
-        break;
-      case "--no-mcph-config":
-        opts.skipMcphConfig = true;
-        break;
-      case "--list":
-        opts.listOnly = true;
-        break;
-      case "--all":
-        opts.all = true;
-        break;
-      case "-h":
-      case "--help":
-        return { ok: false, error: USAGE };
-      default:
-        if (a.startsWith("--")) return { ok: false, error: `Unknown flag: ${a}
-${USAGE}` };
-        positional.push(a);
-    }
-  }
-  if (opts.listOnly || opts.all) {
-    if (positional.length > 0) {
-      return {
-        ok: false,
-        error: `mcph install: ${opts.listOnly ? "--list" : "--all"} does not take a client argument.
-${USAGE}`
-      };
-    }
-    return { ok: true, options: opts };
-  }
-  if (positional.length !== 1)
-    return { ok: false, error: `Expected exactly one client argument, got ${positional.length}.
-${USAGE}` };
-  const clientId = positional[0];
-  if (!INSTALL_TARGETS.some((t) => t.clientId === clientId)) {
-    return {
-      ok: false,
-      error: `Unknown client: ${clientId}. Choose: ${INSTALL_TARGETS.map((t) => t.clientId).join(", ")}`
-    };
-  }
-  opts.clientId = clientId;
-  return { ok: true, options: opts };
-}
-async function runInstallList(opts, log2) {
-  const home = opts.home ?? homedir5();
-  const cwd = opts.cwd ?? process.cwd();
-  const os = opts.os ?? CURRENT_OS;
-  const probes = await probeClientsAsync({ home, os, cwd, claudeConfigDir: opts.claudeConfigDir });
-  const rows = probes.map((p) => ({
-    client: INSTALL_TARGETS.find((t) => t.clientId === p.clientId)?.label ?? p.clientId,
-    scope: p.scope,
-    path: displayPath(p.path, home),
-    status: statusFor(p)
-  }));
-  const installed = probes.filter((p) => p.hasMcphEntry).length;
-  const available = probes.filter((p) => !p.unavailable).length;
-  log2(`${installed}/${available} client scopes have mcp.hosting configured on ${os}.`);
-  log2("");
-  const widths = {
-    client: Math.max("CLIENT".length, ...rows.map((r) => r.client.length)),
-    scope: Math.max("SCOPE".length, ...rows.map((r) => r.scope.length)),
-    path: Math.max("PATH".length, ...rows.map((r) => r.path.length)),
-    status: Math.max("STATUS".length, ...rows.map((r) => r.status.length))
-  };
-  const header = `  ${"CLIENT".padEnd(widths.client)}  ${"SCOPE".padEnd(widths.scope)}  ${"PATH".padEnd(widths.path)}  ${"STATUS".padEnd(widths.status)}`;
-  log2(header);
-  for (const r of rows) {
-    log2(
-      `  ${r.client.padEnd(widths.client)}  ${r.scope.padEnd(widths.scope)}  ${r.path.padEnd(widths.path)}  ${r.status.padEnd(widths.status)}`
-    );
-  }
-  log2("");
-  log2("Install into a specific client: `mcph install <client> [--scope user|project|local]`");
-  log2("Install into every available user-scope client: `mcph install --all`");
-  return { written: [], wouldWrite: [], messages: [], exitCode: 0 };
-}
-function statusFor(p) {
-  if (p.unavailable) return "unavailable";
-  if (p.malformed) return "malformed";
-  if (p.hasMcphEntry) return "installed";
-  if (p.exists) return "other-entries";
-  return "not installed";
-}
-function displayPath(abs, home) {
-  if (abs === "(n/a)") return abs;
-  if (home && abs.startsWith(home)) {
-    const tail = abs.slice(home.length).replace(/^[\\/]/, "");
-    return `~${process.platform === "win32" ? "\\" : "/"}${tail}`;
+      result.push({
+        clientId: target.clientId,
+        scope: scope.scope,
+        path: resolved.absolute,
+        exists: exists3,
+        hasMcphEntry,
+        malformed,
+        unavailable: false
+      });
+    }
   }
-  return abs;
+  return result;
 }
-async function runInstallAll(opts, log2, err) {
-  const os = opts.os ?? CURRENT_OS;
-  const targets = INSTALL_TARGETS.filter((t) => t.availableOn.includes(os));
-  if (targets.length === 0) {
-    err(`mcph install --all: no installable clients on ${os}.`);
-    return { written: [], wouldWrite: [], messages: [], exitCode: 1 };
-  }
-  const plans = [];
-  const skipped = [];
-  for (const t of targets) {
-    const userScope = t.scopes.find((s) => s.scope === "user");
-    if (userScope) {
-      plans.push({ clientId: t.clientId, scope: "user" });
-      continue;
+async function fetchLatestVersion(override) {
+  if (override) {
+    try {
+      return await override();
+    } catch {
+      return null;
     }
-    const firstNoProj = t.scopes.find((s) => !s.requiresProjectDir);
-    if (firstNoProj) {
-      plans.push({ clientId: t.clientId, scope: firstNoProj.scope });
-      continue;
+  }
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), 2e3);
+  try {
+    const res = await fetch("https://registry.npmjs.org/@yawlabs/mcph/latest", {
+      signal: ac.signal,
+      headers: { accept: "application/json" }
+    });
+    if (!res.ok) return null;
+    const body = await res.json();
+    return typeof body.version === "string" ? body.version : null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+var SHELL_HISTORY_TAIL_LINES = 500;
+function scanShellHistoryForShadows(opts) {
+  const shadowMap = cliToNamespaces();
+  const counts = /* @__PURE__ */ new Map();
+  for (const source of shellHistorySources(opts)) {
+    const lines = readTailLines(source.path, SHELL_HISTORY_TAIL_LINES);
+    for (const raw of lines) {
+      const cmd = source.extractCommand(raw);
+      if (!cmd) continue;
+      const binary = extractLeadingBinary(cmd);
+      if (!binary) continue;
+      if (!shadowMap.has(binary)) continue;
+      counts.set(binary, (counts.get(binary) ?? 0) + 1);
     }
-    if (opts.projectDir) {
-      plans.push({ clientId: t.clientId, scope: t.scopes[0].scope });
-      continue;
+  }
+  const hits = [];
+  for (const [cli, count] of counts) {
+    const namespaces = shadowMap.get(cli) ?? [];
+    hits.push({ cli, count, namespaces });
+  }
+  hits.sort((a, b) => b.count - a.count);
+  return hits;
+}
+function shellHistorySources(opts) {
+  const sources = [];
+  sources.push({ path: join6(opts.home, ".bash_history"), extractCommand: (l) => l.trim() || null });
+  sources.push({
+    path: join6(opts.home, ".zsh_history"),
+    // Zsh extended-history lines look like `: 1700000000:0;npm audit`.
+    // Strip the metadata prefix so we get just the command.
+    extractCommand: (l) => {
+      const trimmed = l.trim();
+      if (!trimmed) return null;
+      if (trimmed.startsWith(":")) {
+        const semi = trimmed.indexOf(";");
+        return semi === -1 ? null : trimmed.slice(semi + 1);
+      }
+      return trimmed;
     }
-    skipped.push({
-      clientId: t.clientId,
-      reason: `requires --project-dir (scopes: ${t.scopes.map((s) => s.scope).join(", ")})`
+  });
+  const appData = opts.env.APPDATA;
+  if (appData) {
+    sources.push({
+      path: join6(appData, "Microsoft", "Windows", "PowerShell", "PSReadLine", "ConsoleHost_history.txt"),
+      extractCommand: (l) => l.trim() || null
     });
   }
-  log2(`Installing into ${plans.length} client${plans.length === 1 ? "" : "s"}\u2026`);
-  if (skipped.length > 0) {
-    for (const s of skipped) log2(`  skip ${s.clientId}: ${s.reason}`);
+  return sources;
+}
+function readTailLines(path5, n) {
+  try {
+    const raw = readFileSync(path5, "utf8");
+    const all = raw.split(/\r?\n/);
+    return all.length <= n ? all : all.slice(all.length - n);
+  } catch {
+    return [];
   }
-  log2("");
-  const aggregateWritten = [];
-  const aggregateWouldWrite = [];
-  const aggregateMessages = [];
-  let failed = 0;
-  let succeeded = 0;
-  for (const plan of plans) {
-    log2(`\u2500\u2500 ${plan.clientId} (${plan.scope}) \u2500\u2500`);
-    const result = await runInstall({
-      ...opts,
-      listOnly: false,
-      all: false,
-      clientId: plan.clientId,
-      scope: plan.scope
-    });
-    aggregateWritten.push(...result.written);
-    aggregateWouldWrite.push(...result.wouldWrite);
-    aggregateMessages.push(...result.messages);
-    if (result.exitCode === 0) succeeded += 1;
-    else failed += 1;
-    log2("");
+}
+function extractLeadingBinary(command) {
+  let rest = command.trimStart();
+  if (!rest) return null;
+  if (rest.startsWith("!")) return null;
+  while (/^[A-Z_][A-Z0-9_]*=/i.test(rest)) {
+    const space = rest.indexOf(" ");
+    if (space === -1) return null;
+    rest = rest.slice(space + 1).trimStart();
   }
-  const totalPlanned = plans.length;
-  if (failed === 0) {
-    log2(`\u2713 ${succeeded}/${totalPlanned} clients installed successfully.`);
-    return {
-      written: aggregateWritten,
-      wouldWrite: aggregateWouldWrite,
-      messages: aggregateMessages,
-      exitCode: 0
-    };
+  const prefixes = ["sudo", "time", "command", "exec"];
+  const firstWord = rest.split(/\s+/)[0];
+  if (prefixes.includes(firstWord)) {
+    const space = rest.indexOf(" ");
+    if (space === -1) return null;
+    rest = rest.slice(space + 1).trimStart();
   }
-  err(`${failed}/${totalPlanned} client install${failed === 1 ? "" : "s"} failed. ${succeeded} succeeded.`);
-  return {
-    written: aggregateWritten,
-    wouldWrite: aggregateWouldWrite,
-    messages: aggregateMessages,
-    exitCode: 1
+  const first = rest.split(/\s+/)[0];
+  if (!first) return null;
+  if (/[|&;<>()`$]/.test(first)) return null;
+  const slash = Math.max(first.lastIndexOf("/"), first.lastIndexOf("\\"));
+  return slash === -1 ? first : first.slice(slash + 1);
+}
+function compareSemver(a, b) {
+  const parse = (s) => {
+    const m = /^v?(\d+)\.(\d+)\.(\d+)/.exec(s);
+    if (!m) return null;
+    return [Number(m[1]), Number(m[2]), Number(m[3])];
   };
+  const pa = parse(a);
+  const pb = parse(b);
+  if (!pa || !pb) return 0;
+  for (let i = 0; i < 3; i++) {
+    if (pa[i] < pb[i]) return -1;
+    if (pa[i] > pb[i]) return 1;
+  }
+  return 0;
+}
+
+// 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/reset-learning-cmd.ts
-import { unlink as unlink2 } from "fs/promises";
-import { homedir as homedir6 } from "os";
-import { join as join6 } from "path";
+import { unlink as unlink3 } from "fs/promises";
+import { homedir as homedir7 } from "os";
+import { join as join7 } from "path";
 var RESET_LEARNING_USAGE = `Usage: mcph reset-learning
 
   Delete ~/.mcph/state.json so cross-session learning starts fresh.
@@ -2860,7 +3452,7 @@ ${RESET_LEARNING_USAGE}`
   return { kind: "ok", options: {} };
 }
 async function runResetLearning(opts = {}) {
-  const home = opts.home ?? homedir6();
+  const home = opts.home ?? homedir7();
   const env = opts.env ?? process.env;
   const write = opts.out ?? ((s) => process.stdout.write(s));
   const writeErr = opts.err ?? ((s) => process.stderr.write(s));
@@ -2875,7 +3467,7 @@ async function runResetLearning(opts = {}) {
     writeErr(`${s}
 `);
   };
-  const filePath = join6(userConfigDir(home), STATE_FILENAME);
+  const filePath = join7(userConfigDir(home), STATE_FILENAME);
   const raw = env.MCPH_DISABLE_PERSISTENCE;
   const disabled = raw !== void 0 && raw !== "" && (raw === "1" || raw.toLowerCase() === "true");
   if (disabled) {
@@ -2886,7 +3478,7 @@ async function runResetLearning(opts = {}) {
   const learningCount = Object.keys(persisted.learning).length;
   const packCount = persisted.packHistory.length;
   try {
-    await unlink2(filePath);
+    await unlink3(filePath);
   } catch (err) {
     if (isFileNotFound2(err)) {
       print("mcph reset-learning: no persisted state to reset.");
@@ -2908,9 +3500,9 @@ function isFileNotFound2(err) {
 }
 
 // src/server.ts
-import { readFile as readFile6 } from "fs/promises";
-import { homedir as homedir7 } from "os";
-import { isAbsolute, relative, resolve as resolve3 } from "path";
+import { readFile as readFile7 } from "fs/promises";
+import { homedir as homedir8 } from "os";
+import { isAbsolute, relative, resolve as resolve4 } from "path";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import {
@@ -2921,7 +3513,7 @@ import {
   ListToolsRequestSchema,
   ReadResourceRequestSchema
 } from "@modelcontextprotocol/sdk/types.js";
-import { request as request9 } from "undici";
+import { request as request10 } from "undici";
 
 // src/auto-upgrade.ts
 import { spawn as spawn3 } from "child_process";
@@ -3015,10 +3607,10 @@ async function defaultFetchLatest() {
   }
 }
 async function defaultSpawn(cmd, args) {
-  return new Promise((resolve4) => {
+  return new Promise((resolve5) => {
     const child = spawn2(cmd, args, { stdio: "inherit", shell: process.platform === "win32" });
-    child.on("close", (code) => resolve4(typeof code === "number" ? code : 1));
-    child.on("error", () => resolve4(1));
+    child.on("close", (code) => resolve5(typeof code === "number" ? code : 1));
+    child.on("error", () => resolve5(1));
   });
 }
 async function runUpgrade(opts = {}) {
@@ -3109,7 +3701,7 @@ Or re-run with --run to upgrade in place.`);
   return { exitCode: 3, lines };
 }
 function readCurrentVersion() {
-  return true ? "0.52.0" : "dev";
+  return true ? "0.54.0" : "dev";
 }
 
 // src/auto-upgrade.ts
@@ -3157,7 +3749,7 @@ function defaultSpawn2(cmd, args) {
 async function maybeAutoUpgrade(deps = {}) {
   const optOut = process.env.MCPH_AUTO_UPGRADE;
   if (optOut === "0" || optOut?.toLowerCase() === "false") return;
-  const current = deps.currentVersion ?? (true ? "0.52.0" : "dev");
+  const current = deps.currentVersion ?? (true ? "0.54.0" : "dev");
   if (current === "dev") return;
   const method = detectInstallMethod(deps.argvPath ?? process.argv[1]);
   const latest = await (deps.fetchLatestImpl ?? fetchLatestVersion2)();
@@ -3528,13 +4120,13 @@ function stepBindingKey(step, index) {
 }
 
 // src/guide.ts
-import { readFile as readFile5 } from "fs/promises";
+import { readFile as readFile6 } from "fs/promises";
 var GUIDE_READ_TIMEOUT_MS = 1e3;
 async function readGuide(path5, scope) {
   let raw;
   try {
     raw = await Promise.race([
-      readFile5(path5, "utf8"),
+      readFile6(path5, "utf8"),
       new Promise(
         (_, reject) => setTimeout(() => reject(new Error("guide read timeout")), GUIDE_READ_TIMEOUT_MS)
       )
@@ -3641,7 +4233,7 @@ function truncateForWarning(msg) {
 }
 
 // src/heartbeat.ts
-import { request as request5 } from "undici";
+import { request as request6 } from "undici";
 var HEARTBEAT_PATH = "/api/connect/heartbeat";
 var apiUrl3 = "";
 var token3 = "";
@@ -3656,7 +4248,7 @@ function initHeartbeat(url, tok) {
 async function reportHeartbeat(clientName, clientVersion, isRefresh = false) {
   if (!apiUrl3 || !token3) return;
   try {
-    const res = await request5(`${apiUrl3.replace(/\/$/, "")}${HEARTBEAT_PATH}`, {
+    const res = await request6(`${apiUrl3.replace(/\/$/, "")}${HEARTBEAT_PATH}`, {
       method: "POST",
       headers: {
         Authorization: `Bearer ${token3}`,
@@ -4771,7 +5363,7 @@ function rankServers(context, servers) {
 }
 
 // src/rerank.ts
-import { request as request6 } from "undici";
+import { request as request7 } from "undici";
 var apiUrl4 = "";
 var token4 = "";
 var RERANK_TIMEOUT_MS = 2e3;
@@ -4787,7 +5379,7 @@ async function rerank(intent, candidateIds, limit) {
   if (candidateIds && candidateIds.length > 0) payload.candidateIds = candidateIds;
   if (typeof limit === "number" && limit > 0) payload.limit = limit;
   try {
-    const res = await request6(`${apiUrl4.replace(/\/$/, "")}/api/connect/rerank`, {
+    const res = await request7(`${apiUrl4.replace(/\/$/, "")}/api/connect/rerank`, {
       method: "POST",
       headers: {
         Authorization: `Bearer ${token4}`,
@@ -4820,7 +5412,7 @@ async function rerank(intent, candidateIds, limit) {
 
 // src/runtime-detect.ts
 import { spawn as spawn4 } from "child_process";
-import { request as request7 } from "undici";
+import { request as request8 } from "undici";
 var PROBE_TIMEOUT_MS = 3e3;
 var RUNTIME_REPORT_PATH = "/api/connect/runtimes";
 var apiUrl5 = "";
@@ -4866,12 +5458,12 @@ var PROBES = {
   }
 };
 async function probe(name, p) {
-  return new Promise((resolve4) => {
+  return new Promise((resolve5) => {
     let settled = false;
     const settle = (v) => {
       if (settled) return;
       settled = true;
-      resolve4(v);
+      resolve5(v);
     };
     let stdout = "";
     let stderr = "";
@@ -4948,7 +5540,7 @@ async function reportRuntimes() {
     return;
   }
   try {
-    const res = await request7(`${apiUrl5.replace(/\/$/, "")}${RUNTIME_REPORT_PATH}`, {
+    const res = await request8(`${apiUrl5.replace(/\/$/, "")}${RUNTIME_REPORT_PATH}`, {
       method: "POST",
       headers: {
         Authorization: `Bearer ${token5}`,
@@ -5103,12 +5695,12 @@ import {
 
 // src/uv-bootstrap.ts
 import { spawn as spawn5 } from "child_process";
-import { createHash } from "crypto";
+import { createHash as createHash2 } from "crypto";
 import { createWriteStream } from "fs";
 import fs from "fs/promises";
 import path4 from "path";
 import { pipeline } from "stream/promises";
-import { request as request8 } from "undici";
+import { request as request9 } from "undici";
 var UV_VERSION = "0.11.7";
 var RELEASE_BASE = `https://github.com/astral-sh/uv/releases/download/${UV_VERSION}`;
 function uvTarget() {
@@ -5146,12 +5738,12 @@ async function exists2(p) {
   }
 }
 async function onPath(cmd) {
-  return new Promise((resolve4) => {
+  return new Promise((resolve5) => {
     let settled = false;
     const settle = (v) => {
       if (settled) return;
       settled = true;
-      resolve4(v);
+      resolve5(v);
     };
     let child;
     try {
@@ -5185,7 +5777,7 @@ async function onPath(cmd) {
 async function fetchWithRedirects(url, maxHops = 5) {
   let current = url;
   for (let i = 0; i < maxHops; i++) {
-    const res = await request8(current, { method: "GET" });
+    const res = await request9(current, { method: "GET" });
     if (res.statusCode >= 300 && res.statusCode < 400) {
       const loc = res.headers.location;
       if (!loc) throw new Error(`Redirect without Location header from ${current}`);
@@ -5215,7 +5807,7 @@ async function extractArchive(archivePath, destDir) {
   }
 }
 function runCommand(cmd, args) {
-  return new Promise((resolve4, reject) => {
+  return new Promise((resolve5, reject) => {
     const child = spawn5(cmd, args, {
       stdio: ["ignore", "pipe", "pipe"],
       shell: false,
@@ -5227,7 +5819,7 @@ function runCommand(cmd, args) {
     });
     child.on("error", reject);
     child.on("close", (code) => {
-      if (code === 0) resolve4();
+      if (code === 0) resolve5();
       else reject(new Error(`${cmd} exited ${code}: ${stderr.trim()}`));
     });
   });
@@ -5267,7 +5859,7 @@ async function resolveUv() {
   const shaUrl = `${archiveUrl}.sha256`;
   const [archiveBuf, shaBuf] = await Promise.all([fetchWithRedirects(archiveUrl), fetchWithRedirects(shaUrl)]);
   const expected = shaBuf.toString("utf8").trim().split(/\s+/)[0];
-  const actual = createHash("sha256").update(archiveBuf).digest("hex");
+  const actual = createHash2("sha256").update(archiveBuf).digest("hex");
   if (!expected || expected.toLowerCase() !== actual.toLowerCase()) {
     throw new Error(`uv archive checksum mismatch (expected ${expected}, got ${actual})`);
   }
@@ -5334,7 +5926,7 @@ function categorizeSpawnError(err) {
 }
 async function connectToUpstream(config, onDisconnect, onListChanged) {
   const client = new Client(
-    { name: "mcph", version: true ? "0.52.0" : "dev" },
+    { name: "mcph", version: true ? "0.54.0" : "dev" },
     { capabilities: {} }
   );
   let transport;
@@ -5642,7 +6234,7 @@ var ConnectServer = class _ConnectServer {
     this.apiUrl = apiUrl6;
     this.token = token6;
     this.server = new Server(
-      { name: "mcph", version: true ? "0.52.0" : "dev" },
+      { name: "mcph", version: true ? "0.54.0" : "dev" },
       {
         capabilities: {
           tools: { listChanged: true },
@@ -5791,23 +6383,23 @@ var ConnectServer = class _ConnectServer {
     this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
       tools: buildToolList(this.connections, this.getDeferredServers(), this.toolFilters)
     }));
-    this.server.setRequestHandler(CallToolRequestSchema, async (request10, extra) => {
-      const { name, arguments: args } = request10.params;
+    this.server.setRequestHandler(CallToolRequestSchema, async (request11, extra) => {
+      const { name, arguments: args } = request11.params;
       return this.handleToolCall(name, args ?? {}, extra);
     });
     this.server.setRequestHandler(ListResourcesRequestSchema, async () => ({
       resources: buildResourceList(this.connections, this.getBuiltinResources())
     }));
-    this.server.setRequestHandler(ReadResourceRequestSchema, async (request10) => {
-      return routeResourceRead(request10.params.uri, this.resourceRoutes, this.connections, this.getBuiltinResourceMap());
+    this.server.setRequestHandler(ReadResourceRequestSchema, async (request11) => {
+      return routeResourceRead(request11.params.uri, this.resourceRoutes, this.connections, this.getBuiltinResourceMap());
     });
     this.server.setRequestHandler(ListPromptsRequestSchema, async () => ({
       prompts: buildPromptList(this.connections)
     }));
-    this.server.setRequestHandler(GetPromptRequestSchema, async (request10) => {
+    this.server.setRequestHandler(GetPromptRequestSchema, async (request11) => {
       return routePromptGet(
-        request10.params.name,
-        request10.params.arguments,
+        request11.params.name,
+        request11.params.arguments,
         this.promptRoutes,
         this.connections
       );
@@ -7132,7 +7724,7 @@ ${activeCount} loaded in this session, ${totalTools} tools in context${tokenSumm
     }
     const ALLOWED_FILENAMES = ["claude_desktop_config.json", "mcp.json", "settings.json", "mcp_config.json"];
     try {
-      const resolved = filepath.startsWith("~/") || filepath.startsWith("~\\") ? resolve3(homedir7(), filepath.slice(2)) : resolve3(filepath);
+      const resolved = filepath.startsWith("~/") || filepath.startsWith("~\\") ? resolve4(homedir8(), filepath.slice(2)) : resolve4(filepath);
       const resolvedBasename = resolved.split(/[/\\]/).pop() || "";
       if (!ALLOWED_FILENAMES.includes(resolvedBasename)) {
         return {
@@ -7149,7 +7741,7 @@ ${activeCount} loaded in this session, ${totalTools} tools in context${tokenSumm
         const rel = relative(base, p);
         return rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
       };
-      if (!isUnder(homedir7(), resolved) && !isUnder(process.cwd(), resolved)) {
+      if (!isUnder(homedir8(), resolved) && !isUnder(process.cwd(), resolved)) {
         return {
           content: [
             { type: "text", text: "Import path must be under your home directory or the current working directory." }
@@ -7157,7 +7749,7 @@ ${activeCount} loaded in this session, ${totalTools} tools in context${tokenSumm
           isError: true
         };
       }
-      const raw = await readFile6(resolved, "utf-8");
+      const raw = await readFile7(resolved, "utf-8");
       const parsed = JSON.parse(raw);
       if (!parsed.mcpServers || typeof parsed.mcpServers !== "object" || Array.isArray(parsed.mcpServers)) {
         return {
@@ -7193,7 +7785,7 @@ ${activeCount} loaded in this session, ${totalTools} tools in context${tokenSumm
         nsToKeys.set(s.namespace, existing);
       }
       const collisions = [...nsToKeys.entries()].filter(([, keys]) => keys.length > 1);
-      const res = await request9(`${this.apiUrl.replace(/\/$/, "")}/api/connect/import`, {
+      const res = await request10(`${this.apiUrl.replace(/\/$/, "")}/api/connect/import`, {
         method: "POST",
         headers: {
           Authorization: `Bearer ${this.token}`,
@@ -7254,7 +7846,7 @@ Use mcp_connect_discover to see imported servers.`
     }
     const payload = built.payload;
     try {
-      const res = await request9(`${this.apiUrl.replace(/\/$/, "")}/api/connect/servers`, {
+      const res = await request10(`${this.apiUrl.replace(/\/$/, "")}/api/connect/servers`, {
         method: "POST",
         headers: {
           Authorization: `Bearer ${this.token}`,
@@ -7879,6 +8471,8 @@ var KNOWN_SUBCOMMANDS = [
   "bundles",
   "completion",
   "upgrade",
+  "try",
+  "try-cleanup",
   "help",
   "--help",
   "-h",
@@ -7958,6 +8552,22 @@ if (subcommand === "compliance") {
     process.exit(2);
   }
   runUpgrade(parsed.options).then((r) => process.exit(r.exitCode));
+} else if (subcommand === "try") {
+  const parsed = parseTryArgs(process.argv.slice(3));
+  if (!parsed.ok) {
+    process.stderr.write(`${parsed.error}
+`);
+    process.exit(2);
+  }
+  runTry(parsed.options).then((r) => process.exit(r.exitCode));
+} else if (subcommand === "try-cleanup") {
+  const parsed = parseTryCleanupArgs(process.argv.slice(3));
+  if (!parsed.ok) {
+    process.stderr.write(`${parsed.error}
+`);
+    process.exit(2);
+  }
+  runTryCleanup(parsed.options).then((r) => process.exit(r.exitCode));
 } else if (subcommand === "--help" || subcommand === "-h" || subcommand === "help") {
   process.stdout.write(`
   mcph \u2014 one install, every MCP server, managed from the cloud.
@@ -7974,6 +8584,10 @@ if (subcommand === "compliance") {
     install --list           List which MCP clients are installed on this
                              machine (read-only; no writes).
     install --all            Configure every installed MCP client in one go.
+    try <slug>               Wire a one-off trial of an upstream MCP server
+                             into your AI client. No account needed; expires
+                             after --ttl (default 1h). Doctor GCs it after.
+    try-cleanup <slug>       Remove a wired trial early.
 
   Inspection:
     doctor                   Diagnose setup: config, token, clients, learning,
@@ -8023,6 +8637,8 @@ if (subcommand === "compliance") {
                                upgraded in the background).
     MCPH_PRUNE_RESPONSES       Set to \`0\` to disable response pruning.
     MCPH_DISABLE_PERSISTENCE   Disable cross-session learning state.
+    MCPH_BASE_URL              Override the host \`mcph try\` queries for
+                               /api/explore/:slug (default https://mcp.hosting).
 
   Config resolution (highest precedence first):
     1. MCPH_TOKEN / MCPH_URL env vars
@@ -8040,7 +8656,7 @@ if (subcommand === "compliance") {
 `);
   process.exit(0);
 } else if (subcommand === "--version" || subcommand === "-V") {
-  process.stdout.write(`mcph ${true ? "0.52.0" : "dev"}
+  process.stdout.write(`mcph ${true ? "0.54.0" : "dev"}
 `);
   process.exit(0);
 } else if (subcommand && !subcommand.startsWith("-")) {