@yawlabs/mcp 0.64.2 → 0.66.0

package/README.md

@@ -373,6 +373,8 @@ Rotate a credential in one place (the dashboard), every machine picks up the new
 | `YAW_MCP_DISABLE_PERSISTENCE` | No | Set to `1` or `true` to keep learning + pack-history scoped to the current process -- nothing loaded at start, nothing written on shutdown. Intended for ephemeral / shared environments (CI, containers). Default: cross-session persistence enabled at `~/.yaw-mcp/state.json`. |
 | `YAW_MCP_AUTO_LOAD` | No | Set to `1` or `true` to pre-activate the top recurring pack (from persisted pack-history) on startup -- no LLM round-trip required. Skips silently when history is empty or no pack's namespaces are all installed. Default: off. Requires persistence to be enabled. |
 | `YAW_MCP_MIN_COMPLIANCE` | No | Minimum compliance grade (`A`, `B`, `C`, `D`, or `F`, case-insensitive) an installed server must report before `mcp_connect_activate` will load it. Ungraded servers always pass (don't punish unknown). `discover()` annotates below-grade servers in place and shows a "Compliance filter active" header when set. Invalid values log a warning and disable the filter. Default: unset (no filter). |
+| `YAW_MCP_VAULT_PASSPHRASE` | No | Passphrase for the local secret vault (`~/.yaw-mcp/secrets.json`). Required for spawn-time `${secret:NAME}` substitution and to avoid the interactive prompt on `yaw-mcp secrets`. Stripped from every spawned upstream server's env. |
+| `YAW_MCP_VAULT_PASSPHRASE_NEW` | No | The NEW passphrase for `yaw-mcp secrets rotate`. When unset, rotate prompts (confirm-twice) on a TTY instead. |
 | `MCP_CONNECT_TIMEOUT` | No | Connection timeout in ms for upstream servers (default: `15000`) |
 | `MCP_CONNECT_IDLE_THRESHOLD` | No | Baseline for idle auto-unload (default: `10`). The per-namespace adaptive cap is `[5, 50]` -- bursty namespaces extend past the baseline, long-idle ones unload at it. |
 
@@ -388,6 +390,104 @@ The popular Python-based MCP servers (`sqlite`, `time`, `sentry`, and other uvx-
 
 `uvx ARGS` is always rewritten to `uv tool run ARGS` at spawn time -- so only `uv` needs to be reachable, not `uvx` separately. Fixes Windows setups where one was on PATH and the other wasn't.
 
+## Local secret vault (no account required)
+
+There are two ways a secret reaches a server yaw-mcp spawns, and they have
+different threat models:
+
+1. **Backend-credential path (account required).** Paste a token into a
+   server's `env` block in the yaw.sh/mcp dashboard. The value is encrypted
+   at rest on the backend and injected at spawn time. It syncs across every
+   machine signed in to the same account, and revoking the account token cuts
+   off access everywhere on the next poll. This is the path the
+   "Cross-machine config sync" and "Trust & security" sections describe.
+
+2. **Local secret vault (no account required).** Keep the value in an
+   encrypted file on your own machine at `~/.yaw-mcp/secrets.json` and
+   reference it from any server's `env` with a `${secret:NAME}` placeholder.
+   yaw-mcp substitutes the decrypted value into the child env at spawn time.
+   The value never leaves your machine, never goes to the backend, and works
+   with no login. This is the right path when you want a credential that is
+   strictly local to one machine, or you don't have an account at all.
+
+### How `${secret:NAME}` references work
+
+Put a placeholder in a server's `env` value -- it can stand alone or be
+composed inline:
+
+```jsonc
+{
+  "namespace": "gh",
+  "command": "npx",
+  "args": ["-y", "@modelcontextprotocol/server-github"],
+  "env": {
+    "GITHUB_PERSONAL_ACCESS_TOKEN": "${secret:gh}",
+    "AUTH_HEADER": "Bearer ${secret:gh}"
+  }
+}
+```
+
+At spawn time, if `YAW_MCP_VAULT_PASSPHRASE` is set in yaw-mcp's own
+environment, yaw-mcp loads the vault, decrypts the referenced names, and
+substitutes the values into the child's env. If the passphrase is absent, the
+vault is missing, or a referenced name isn't stored, the literal
+`${secret:NAME}` is passed through unchanged -- the child then surfaces its
+own "missing/invalid credential" error, which is louder than silently passing
+an empty string.
+
+### Managing the vault -- `yaw-mcp secrets`
+
+```bash
+yaw-mcp secrets set <name>      # store a value (stdin prompt, no echo; or --value/--stdin)
+yaw-mcp secrets get <name>      # decrypt and print one value
+yaw-mcp secrets list            # show entry NAMES (values stay encrypted)
+yaw-mcp secrets remove <name>   # delete an entry
+yaw-mcp secrets lock            # clear the in-process passphrase cache
+yaw-mcp secrets rotate [--push] # re-encrypt the whole vault under a NEW passphrase
+yaw-mcp secrets audit [--secret NAME] [--server NS] [--json]   # who consumed which secret, when
+yaw-mcp secrets push            # upload the encrypted blob to your account (login required)
+yaw-mcp secrets pull            # download it back (login required)
+```
+
+The passphrase derives the encryption key via scrypt and is cached in memory
+for the lifetime of one yaw-mcp process; the on-disk file only ever holds
+ciphertext (AES-256-GCM, per-entry IV + auth tag, one vault-level salt). Set
+`YAW_MCP_VAULT_PASSPHRASE` in the env to avoid the prompt -- this is required
+for spawn-time substitution, since a spawned MCP server runs non-interactively
+and can't prompt on a TTY.
+
+`rotate` re-encrypts every entry under a fresh salt + key derived from a NEW
+passphrase (read from `YAW_MCP_VAULT_PASSPHRASE_NEW` or a confirm-twice
+prompt). It decrypts every entry under the current passphrase FIRST and aborts
+the whole operation -- leaving the on-disk vault untouched -- if any entry
+fails to decrypt. **Rotate re-wraps the ENCRYPTION, not the underlying token
+values:** a token that has leaked is still leaked after a rotate; rotate it at
+its source. Rotate does NOT push to your account unless you pass `--push`.
+
+`audit` reads an append-only NDJSON log at `~/.yaw-mcp/secrets-audit.log`
+(mode `0600`, tail-capped) recording that a secret NAME was `injected` into
+(or was `missing` for) a given server namespace, with a timestamp. **The log
+never records a value** -- only names, namespaces, and times. Writes to it are
+fail-open: a broken or unwritable log never blocks a server spawn.
+
+The `mcp_connect_secrets` meta-tool gives the same picture to the model
+without any decryption: per server it lists `injectedSecrets` (names the vault
+has and the server references) and `missing` (referenced names the vault
+lacks). It reads only the vault's key list and the servers' reference names --
+it never decrypts or returns a value, and needs no passphrase.
+
+### Offline threat model
+
+The vault protects the on-disk file against **offline brute-force after
+exfiltration** -- a stolen laptop, a leaked backup, a synced dotfile repo. The
+file is useless without the passphrase: scrypt key derivation makes guessing
+expensive, and AES-256-GCM means a tampered ciphertext fails to decrypt rather
+than yielding garbage plaintext. What the vault does **not** defend against: a
+process running as you while the passphrase is cached in memory (it can ask
+yaw-mcp to decrypt), a keylogger capturing the passphrase, or a value already
+leaked at its source. For those, rotate the underlying token, not the vault
+encryption.
+
 ## Trust & security
 
 MCP servers are third-party code that you choose to run, and yaw-mcp launches them on your machine or calls them over the network. We don't sandbox arbitrary code and we're not an antivirus -- that's your OS and network. What yaw-mcp gives you is **visibility and a gate**:

package/dist/index.js

@@ -825,6 +825,7 @@ async function readConfigAt(path5, scope, warnings) {
   }
   const servers = Array.isArray(obj.servers) ? obj.servers.filter((v) => typeof v === "string") : void 0;
   const blocked = Array.isArray(obj.blocked) ? obj.blocked.filter((v) => typeof v === "string") : void 0;
+  const installNudge = typeof obj.installNudge === "boolean" ? obj.installNudge : void 0;
   if (token5) {
     if (scope === "project") {
       warnings.push(
@@ -833,7 +834,7 @@ async function readConfigAt(path5, scope, warnings) {
     }
     await checkPermissions(path5, warnings);
   }
-  return { path: path5, scope, version, token: token5, apiBase, servers, blocked };
+  return { path: path5, scope, version, token: token5, apiBase, servers, blocked, installNudge };
 }
 async function checkPermissions(path5, warnings) {
   if (process.platform === "win32") return;
@@ -855,6 +856,13 @@ function pickServers(files) {
   if (project !== void 0) return project;
   return files.find((f) => f.scope === "global")?.servers;
 }
+function pickInstallNudge(files) {
+  const local = files.find((f) => f.scope === "local")?.installNudge;
+  if (local !== void 0) return local;
+  const project = files.find((f) => f.scope === "project")?.installNudge;
+  if (project !== void 0) return project;
+  return files.find((f) => f.scope === "global")?.installNudge;
+}
 function unionBlocked(files) {
   const set = /* @__PURE__ */ new Set();
   let touched = false;
@@ -934,6 +942,7 @@ async function loadYawMcpConfig(opts = {}) {
     apiBaseSource,
     servers: pickServers(loadedFiles),
     blocked: unionBlocked(loadedFiles),
+    installNudge: pickInstallNudge(loadedFiles),
     projectConfigDir,
     loadedFiles,
     warnings
@@ -963,10 +972,6 @@ function toProfile(config) {
   }
   return result;
 }
-async function loadEffectiveProfile(cwd, home) {
-  const config = await loadYawMcpConfig({ cwd, home });
-  return toProfile(config);
-}
 function isAllowed(rules, namespace) {
   if (!rules) return true;
   if (rules.blocked?.includes(namespace)) return false;
@@ -2060,6 +2065,18 @@ function cliToNamespaces() {
   reverseIndexCache = map;
   return map;
 }
+var SHADOW_INSTALL_TARGETS = {
+  aws: { package: "@yawlabs/aws-mcp", namespace: "aws", name: "AWS" },
+  caddy: { package: "@yawlabs/caddy-mcp", namespace: "caddy", name: "Caddy" },
+  curl: { package: "@yawlabs/fetch-mcp", namespace: "fetch", name: "Fetch" },
+  wget: { package: "@yawlabs/fetch-mcp", namespace: "fetch", name: "Fetch" },
+  psql: { package: "@yawlabs/postgres-mcp", namespace: "postgres", name: "Postgres" },
+  pg_dump: { package: "@yawlabs/postgres-mcp", namespace: "postgres", name: "Postgres" },
+  tailscale: { package: "@yawlabs/tailscale-mcp", namespace: "tailscale", name: "Tailscale" }
+};
+function installTargetForCli(cli) {
+  return SHADOW_INSTALL_TARGETS[cli];
+}
 function formatShadowLine(server) {
   const shadows = resolveShadowedClis(server);
   if (shadows.length === 0) return null;
@@ -3987,7 +4004,7 @@ async function runUpgrade(opts = {}) {
   return { exitCode: 3, lines };
 }
 function readCurrentVersion() {
-  return true ? "0.64.2" : "dev";
+  return true ? "0.66.0" : "dev";
 }
 
 // src/usage-hints.ts
@@ -4049,7 +4066,7 @@ function selectFlakyNamespaces(entries, limit) {
 }
 
 // src/doctor-cmd.ts
-var VERSION = true ? "0.64.2" : "dev";
+var VERSION = true ? "0.66.0" : "dev";
 function isPersistenceDisabled(env) {
   const raw = env.YAW_MCP_DISABLE_PERSISTENCE;
   return raw !== void 0 && raw !== "" && (raw === "1" || raw.toLowerCase() === "true");
@@ -5663,13 +5680,85 @@ function isFileNotFound2(err) {
 }
 
 // src/secrets-cmd.ts
+import { existsSync as existsSync6 } from "fs";
+import { homedir as homedir15 } from "os";
+
+// src/secrets-audit.ts
 import { existsSync as existsSync5 } from "fs";
-import { homedir as homedir14 } from "os";
+import { appendFile as appendFile2, chmod as chmod4, readFile as readFile9, writeFile } from "fs/promises";
+import { homedir as homedir13 } from "os";
+import { join as join10 } from "path";
+var SECRETS_AUDIT_FILENAME = "secrets-audit.log";
+var AUDIT_TAIL_CAP = 5e3;
+function auditLogPath(home = homedir13()) {
+  return join10(home, CONFIG_DIRNAME, SECRETS_AUDIT_FILENAME);
+}
+async function appendAuditEvent(input, home = homedir13()) {
+  try {
+    const event = {
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      server: input.server,
+      secret: input.secret,
+      event: input.event
+    };
+    const path5 = auditLogPath(home);
+    const line = `${JSON.stringify(event)}
+`;
+    if (!existsSync5(path5)) {
+      await atomicWriteFile(path5, line);
+    } else {
+      await appendFile2(path5, line, "utf8");
+    }
+    if (process.platform !== "win32") {
+      await chmod4(path5, 384).catch(() => void 0);
+    }
+    await trimToTailCap(path5);
+  } catch {
+  }
+}
+async function trimToTailCap(path5) {
+  const raw = await readFile9(path5, "utf8");
+  const lines = raw.split("\n").filter((l) => l.length > 0);
+  if (lines.length <= AUDIT_TAIL_CAP) return;
+  const kept = lines.slice(lines.length - AUDIT_TAIL_CAP);
+  await writeFile(path5, `${kept.join("\n")}
+`, "utf8");
+}
+async function readAuditLog(filter = {}, home = homedir13()) {
+  const path5 = auditLogPath(home);
+  if (!existsSync5(path5)) return [];
+  let raw;
+  try {
+    raw = await readFile9(path5, "utf8");
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const line of raw.split("\n")) {
+    if (line.length === 0) continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (!isAuditEvent(parsed)) continue;
+    if (filter.secret !== void 0 && parsed.secret !== filter.secret) continue;
+    if (filter.server !== void 0 && parsed.server !== filter.server) continue;
+    out.push(parsed);
+  }
+  return out;
+}
+function isAuditEvent(v) {
+  if (!v || typeof v !== "object") return false;
+  const e = v;
+  return typeof e.ts === "string" && typeof e.server === "string" && typeof e.secret === "string" && (e.event === "injected" || e.event === "missing");
+}
 
 // src/secrets-vault.ts
-import { chmod as chmod4, mkdir as mkdir4, readFile as readFile9 } from "fs/promises";
-import { homedir as homedir13 } from "os";
-import { dirname as dirname2, join as join10 } from "path";
+import { chmod as chmod5, mkdir as mkdir4, readFile as readFile10 } from "fs/promises";
+import { homedir as homedir14 } from "os";
+import { dirname as dirname2, join as join11 } from "path";
 
 // src/secrets-crypto.ts
 import { createCipheriv, createDecipheriv, randomBytes, scrypt as scryptCb } from "crypto";
@@ -5728,8 +5817,8 @@ function decryptEntry(entry, key) {
 var SECRETS_FILENAME = "secrets.json";
 var SECRETS_SCHEMA_VERSION = 1;
 var VAULT_CHECK_PLAINTEXT = "yaw-mcp-vault-v1";
-function vaultPath(home = homedir13()) {
-  return join10(home, CONFIG_DIRNAME, SECRETS_FILENAME);
+function vaultPath(home = homedir14()) {
+  return join11(home, CONFIG_DIRNAME, SECRETS_FILENAME);
 }
 function emptyVault() {
   return {
@@ -5741,7 +5830,7 @@ function emptyVault() {
 async function loadVault(path5) {
   let raw;
   try {
-    raw = await readFile9(path5, "utf8");
+    raw = await readFile10(path5, "utf8");
   } catch (err) {
     const code = err.code;
     if (code === "ENOENT") return null;
@@ -5786,7 +5875,7 @@ async function saveVault(path5, vault) {
   await mkdir4(dir, { recursive: true });
   if (process.platform !== "win32") {
     try {
-      await chmod4(dir, 448);
+      await chmod5(dir, 448);
     } catch {
     }
   }
@@ -5794,7 +5883,7 @@ async function saveVault(path5, vault) {
 `, "utf8", 384, 448);
   if (process.platform !== "win32") {
     try {
-      await chmod4(path5, 384);
+      await chmod5(path5, 384);
     } catch {
     }
   }
@@ -5828,6 +5917,44 @@ function ensureCheck(vault, key) {
   if (vault.check) return vault;
   return { ...vault, check: encryptEntry(VAULT_CHECK_PLAINTEXT, key) };
 }
+async function rotateVault(vault, oldKey, newPassphrase) {
+  if (vault.check) {
+    try {
+      const probe2 = decryptEntry(vault.check, oldKey);
+      if (probe2 !== VAULT_CHECK_PLAINTEXT) {
+        throw new Error("vault check marker did not match expected plaintext");
+      }
+    } catch {
+      throw new Error("rotate aborted: current passphrase is wrong (vault check failed to decrypt)");
+    }
+  }
+  const plaintext = /* @__PURE__ */ new Map();
+  for (const [name, entry] of Object.entries(vault.entries)) {
+    try {
+      plaintext.set(name, decryptEntry(entry, oldKey));
+    } catch {
+      plaintext.clear();
+      throw new Error(`rotate aborted: entry "${name}" failed to decrypt under the current passphrase`);
+    }
+  }
+  const newSalt = generateSalt();
+  const newKey = await deriveKey(newPassphrase, newSalt);
+  try {
+    const entries = {};
+    for (const [name, value] of plaintext) {
+      entries[name] = encryptEntry(value, newKey);
+    }
+    return {
+      version: SECRETS_SCHEMA_VERSION,
+      salt: newSalt.toString("base64"),
+      entries,
+      check: encryptEntry(VAULT_CHECK_PLAINTEXT, newKey)
+    };
+  } finally {
+    plaintext.clear();
+    newKey.fill(0);
+  }
+}
 function listKeys(vault) {
   return Object.keys(vault.entries).sort();
 }
@@ -5919,6 +6046,19 @@ Actions:
                           \`yaw-mcp login\` first. Refuses when the local
                           vault has a different salt (different passphrase
                           lineage) unless --force is passed.
+  rotate                  Re-encrypt every entry under a NEW passphrase
+                          (fresh salt + derived key). Re-wraps the
+                          ENCRYPTION, NOT the underlying token values -- a
+                          leaked token is still leaked; rotate it at its
+                          source. Reads the current passphrase, then the
+                          new one (env YAW_MCP_VAULT_PASSPHRASE_NEW or a
+                          confirm-twice TTY prompt). Pass --push to also
+                          upload the re-encrypted blob to mcp_secrets.
+  audit [--secret NAME] [--server NS]
+                          Show the local secret-resolution audit trail
+                          (~/.yaw-mcp/secrets-audit.log): which secret
+                          NAMES were injected into (or missing for) which
+                          server, and when. Never shows a value.
 
 Flags:
   --json                  Machine-readable output (where applicable).
@@ -5930,12 +6070,18 @@ Flags:
   --replace               (push only) Overwrite even when the remote vault
                           salt differs from the local (different passphrase
                           lineage). Coordinate with your team first.
+  --push                  (rotate only) After re-encrypting, push the new
+                          blob to mcp_secrets (requires a login session).
+  --secret <name>         (audit only) Filter to one secret name.
+  --server <ns>           (audit only) Filter to one server namespace.
 
 Passphrase:
   Set YAW_MCP_VAULT_PASSPHRASE in the env, or you will be prompted on
   the controlling TTY. The passphrase derives the encryption key via
   scrypt and is cached in memory for the lifetime of this yaw-mcp
-  process; the on-disk vault only ever holds ciphertext.`;
+  process; the on-disk vault only ever holds ciphertext. For rotate, the
+  NEW passphrase comes from YAW_MCP_VAULT_PASSPHRASE_NEW (or a TTY
+  confirm-twice prompt).`;
 function parseSecretsArgs(argv) {
   const opts = {};
   for (let i = 0; i < argv.length; i++) {
@@ -5957,6 +6103,10 @@ function parseSecretsArgs(argv) {
       opts.replace = true;
       continue;
     }
+    if (a === "--push") {
+      opts.push = true;
+      continue;
+    }
     if (a === "--value") {
       const v = argv[++i];
       if (v === void 0 || v.startsWith("-")) {
@@ -5970,13 +6120,31 @@ ${SECRETS_USAGE}`
       opts.value = v;
       continue;
     }
+    if (a === "--secret") {
+      const v = argv[++i];
+      if (v === void 0)
+        return { ok: false, error: `yaw-mcp secrets: --secret requires a value
+
+${SECRETS_USAGE}` };
+      opts.secretFilter = v;
+      continue;
+    }
+    if (a === "--server") {
+      const v = argv[++i];
+      if (v === void 0)
+        return { ok: false, error: `yaw-mcp secrets: --server requires a value
+
+${SECRETS_USAGE}` };
+      opts.serverFilter = v;
+      continue;
+    }
     if (a.startsWith("-")) {
       return { ok: false, error: `yaw-mcp secrets: unknown flag "${a}"
 
 ${SECRETS_USAGE}` };
     }
     if (!opts.action) {
-      if (a !== "set" && a !== "get" && a !== "list" && a !== "remove" && a !== "lock" && a !== "push" && a !== "pull") {
+      if (a !== "set" && a !== "get" && a !== "list" && a !== "remove" && a !== "lock" && a !== "push" && a !== "pull" && a !== "rotate" && a !== "audit") {
         return { ok: false, error: `yaw-mcp secrets: unknown action "${a}"
 
 ${SECRETS_USAGE}` };
@@ -6040,6 +6208,35 @@ async function resolvePassphrase(opts) {
   }
   return null;
 }
+async function resolveNewPassphrase(opts) {
+  if (opts.newPassphrase !== void 0) return opts.newPassphrase.length > 0 ? opts.newPassphrase : null;
+  const fromEnv = process.env.YAW_MCP_VAULT_PASSPHRASE_NEW;
+  if (typeof fromEnv === "string" && fromEnv.length > 0) {
+    if (fromEnv.length < MIN_PASSPHRASE_WARN_LEN) {
+      const stderr = opts.io?.stderr ?? process.stderr;
+      stderr.write(
+        `yaw-mcp secrets: warning -- the new passphrase is shorter than ${MIN_PASSPHRASE_WARN_LEN} characters; consider a longer passphrase.
+`
+      );
+    }
+    return fromEnv;
+  }
+  const stdin = opts.io?.stdin ?? process.stdin;
+  const stdout = opts.io?.stdout ?? process.stdout;
+  const isTTY = stdin.isTTY === true && stdout.isTTY === true;
+  if (!isTTY) return null;
+  for (let attempt = 0; attempt < MAX_PASSPHRASE_PROMPTS; attempt++) {
+    const first = await readPassphraseFromTTY(stdin, stdout, "New vault passphrase: ");
+    if (first.length === 0) {
+      stdout.write("Passphrase cannot be empty.\n");
+      continue;
+    }
+    const second = await readPassphraseFromTTY(stdin, stdout, "Confirm new passphrase: ");
+    if (first === second) return first;
+    stdout.write("Passphrases did not match. Try again.\n");
+  }
+  return null;
+}
 var MAX_PASSPHRASE_PROMPTS = 3;
 var MIN_PASSPHRASE_WARN_LEN = 12;
 function readPassphraseFromTTY(stdin, stdout, prompt = "Vault passphrase: ") {
@@ -6108,7 +6305,7 @@ async function runSecrets(opts, io = {
   out: (s) => process.stdout.write(s),
   err: (s) => process.stderr.write(s)
 }) {
-  const home = opts.home ?? homedir14();
+  const home = opts.home ?? homedir15();
   const path5 = vaultPath(home);
   if (opts.action === "lock") {
     lock();
@@ -6123,12 +6320,18 @@ async function runSecrets(opts, io = {
   if (opts.action === "pull") {
     return await runSecretsPull(opts, io);
   }
+  if (opts.action === "rotate") {
+    return await runSecretsRotate(opts, io);
+  }
+  if (opts.action === "audit") {
+    return await runSecretsAudit(opts, io);
+  }
   if (opts.action === "list") {
     const loaded = await safeLoadVault(path5, io, opts.json, "list");
     if (!loaded.ok) return loaded.result;
     const vault2 = loaded.vault;
     const keys = vault2 ? listKeys(vault2) : [];
-    if (opts.json) io.out(`${JSON.stringify({ ok: true, vault: existsSync5(path5), keys }, null, 2)}
+    if (opts.json) io.out(`${JSON.stringify({ ok: true, vault: existsSync6(path5), keys }, null, 2)}
 `);
     else if (!vault2) io.out(`No vault at ${path5}. Run \`yaw-mcp secrets set <name>\` to create one.
 `);
@@ -6159,7 +6362,7 @@ async function runSecrets(opts, io = {
   const loadedForMutate = await safeLoadVault(path5, io, opts.json, opts.action ?? "");
   if (!loadedForMutate.ok) return loadedForMutate.result;
   let vault = loadedForMutate.vault ?? newVault();
-  const isFresh = !existsSync5(path5);
+  const isFresh = !existsSync6(path5);
   const passphrase = await resolvePassphrase(opts);
   if (passphrase === null) {
     const msg = "Passphrase required. Set YAW_MCP_VAULT_PASSPHRASE or run from a TTY so we can prompt.";
@@ -6261,7 +6464,7 @@ async function runSecrets(opts, io = {
 }
 var MCP_SECRETS_RESOURCE = "mcp_secrets";
 async function runSecretsPush(opts, io) {
-  const home = opts.home ?? homedir14();
+  const home = opts.home ?? homedir15();
   const path5 = vaultPath(home);
   const session = await getSession({ home, baseUrl: opts.baseUrl });
   if (!session) {
@@ -6335,7 +6538,7 @@ async function runSecretsPush(opts, io) {
   }
 }
 async function runSecretsPull(opts, io) {
-  const home = opts.home ?? homedir14();
+  const home = opts.home ?? homedir15();
   const path5 = vaultPath(home);
   const session = await getSession({ home, baseUrl: opts.baseUrl });
   if (!session) {
@@ -6403,10 +6606,159 @@ async function runSecretsPull(opts, io) {
     return { exitCode: 1 };
   }
 }
+async function runSecretsRotate(opts, io) {
+  const home = opts.home ?? homedir15();
+  const path5 = vaultPath(home);
+  const vault = await loadVault(path5);
+  if (!vault) {
+    const msg = `No vault at ${path5} to rotate. Run \`yaw-mcp secrets set <name>\` first.`;
+    if (opts.json) io.err(`${JSON.stringify({ ok: false, error: msg })}
+`);
+    else io.err(`yaw-mcp secrets rotate: ${msg}
+`);
+    return { exitCode: 1 };
+  }
+  const currentPassphrase = await resolvePassphrase(opts);
+  if (currentPassphrase === null) {
+    const msg = "Current passphrase required. Set YAW_MCP_VAULT_PASSPHRASE or run from a TTY so we can prompt.";
+    if (opts.json) io.err(`${JSON.stringify({ ok: false, error: msg })}
+`);
+    else io.err(`yaw-mcp secrets rotate: ${msg}
+`);
+    return { exitCode: 1 };
+  }
+  let oldKey;
+  try {
+    oldKey = await unlock(vault, currentPassphrase);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (opts.json) io.err(`${JSON.stringify({ ok: false, error: msg })}
+`);
+    else io.err(`yaw-mcp secrets rotate: ${msg}
+`);
+    return { exitCode: 1 };
+  }
+  const newPassphrase = await resolveNewPassphrase(opts);
+  if (newPassphrase === null) {
+    const msg = "New passphrase required (and must be confirmed). Set YAW_MCP_VAULT_PASSPHRASE_NEW or run from a TTY so we can prompt.";
+    if (opts.json) io.err(`${JSON.stringify({ ok: false, error: msg })}
+`);
+    else io.err(`yaw-mcp secrets rotate: ${msg}
+`);
+    return { exitCode: 1 };
+  }
+  let rotated;
+  try {
+    rotated = await rotateVault(vault, oldKey, newPassphrase);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (opts.json) io.err(`${JSON.stringify({ ok: false, error: msg })}
+`);
+    else io.err(`yaw-mcp secrets rotate: ${msg}
+`);
+    lock();
+    return { exitCode: 1 };
+  }
+  await saveVault(path5, rotated);
+  lock();
+  const count = Object.keys(rotated.entries).length;
+  let pushedVersion = null;
+  if (opts.push) {
+    const session = await getSession({ home, baseUrl: opts.baseUrl });
+    if (!session) {
+      const msg = "Rotated locally, but --push needs a session. Run `yaw-mcp login --key <license-key>` then push.";
+      if (opts.json) io.err(`${JSON.stringify({ ok: true, rotated: true, pushed: false, note: msg })}
+`);
+      else io.err(`yaw-mcp secrets rotate: ${msg}
+`);
+      return { exitCode: 0 };
+    }
+    try {
+      const remote = await getResource(MCP_SECRETS_RESOURCE, { home, baseUrl: opts.baseUrl });
+      const result = await putResource(MCP_SECRETS_RESOURCE, remote.version, rotated, {
+        home,
+        baseUrl: opts.baseUrl
+      });
+      pushedVersion = result.version;
+    } catch (err) {
+      if (err instanceof TeamSyncStaleVersionError) {
+        const hint = `Rotated locally. Push skipped -- remote is at v${err.currentVersion}; pull and reconcile, then push.`;
+        if (opts.json) io.err(`${JSON.stringify({ ok: true, rotated: true, pushed: false, note: hint })}
+`);
+        else io.err(`yaw-mcp secrets rotate: ${hint}
+`);
+        return { exitCode: 0 };
+      }
+      if (err instanceof TeamSyncAuthError) {
+        const hint = "Rotated locally. Push skipped -- session expired. Run `yaw-mcp login` again, then push.";
+        if (opts.json) io.err(`${JSON.stringify({ ok: true, rotated: true, pushed: false, note: hint })}
+`);
+        else io.err(`yaw-mcp secrets rotate: ${hint}
+`);
+        return { exitCode: 0 };
+      }
+      const message = err instanceof Error ? err.message : String(err);
+      if (opts.json) io.err(`${JSON.stringify({ ok: true, rotated: true, pushed: false, error: message })}
+`);
+      else io.err(`yaw-mcp secrets rotate: rotated locally but push failed: ${message}
+`);
+      return { exitCode: 0 };
+    }
+  }
+  if (opts.json) {
+    io.out(
+      `${JSON.stringify({ ok: true, rotated: true, secret_count: count, pushed: pushedVersion !== null, ...pushedVersion !== null ? { new_version: pushedVersion } : {} })}
+`
+    );
+  } else {
+    io.out(
+      `Rotated ${count} secret${count === 1 ? "" : "s"} under a new passphrase (encryption re-wrapped, token values unchanged).
+`
+    );
+    if (pushedVersion !== null) io.out(`Pushed the re-encrypted vault -> mcp_secrets v${pushedVersion}.
+`);
+    io.out("Vault locked -- the next secrets command will prompt for the new passphrase.\n");
+  }
+  return { exitCode: 0 };
+}
+async function runSecretsAudit(opts, io) {
+  const home = opts.home ?? homedir15();
+  let events;
+  try {
+    events = await readAuditLog(
+      {
+        ...opts.secretFilter !== void 0 ? { secret: opts.secretFilter } : {},
+        ...opts.serverFilter !== void 0 ? { server: opts.serverFilter } : {}
+      },
+      home
+    );
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (opts.json) io.err(`${JSON.stringify({ ok: false, error: msg })}
+`);
+    else io.err(`yaw-mcp secrets audit: ${msg}
+`);
+    return { exitCode: 1 };
+  }
+  if (opts.json) {
+    io.out(`${JSON.stringify({ ok: true, count: events.length, events }, null, 2)}
+`);
+    return { exitCode: 0 };
+  }
+  if (events.length === 0) {
+    io.out("No secret-resolution audit events recorded yet.\n");
+    return { exitCode: 0 };
+  }
+  for (const e of events) {
+    io.out(`${e.ts}  ${e.event === "injected" ? "injected" : "missing "}  ${e.server}  ${e.secret}
+`);
+  }
+  return { exitCode: 0 };
+}
 
 // src/server.ts
-import { readFile as readFile11 } from "fs/promises";
-import { homedir as homedir15 } from "os";
+import { readFile as readFile12 } from "fs/promises";
+import { homedir as homedir16 } from "os";
 import { isAbsolute as isAbsolute2, relative, resolve as resolve6 } from "path";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -6522,7 +6874,7 @@ function defaultSpawn2(cmd, args) {
 async function maybeAutoUpgrade(deps = {}) {
   const optOut = process.env.YAW_MCP_AUTO_UPGRADE;
   if (optOut === "0" || optOut?.toLowerCase() === "false") return;
-  const current = deps.currentVersion ?? (true ? "0.64.2" : "dev");
+  const current = deps.currentVersion ?? (true ? "0.66.0" : "dev");
   if (current === "dev") return;
   const method = (deps.isSeaImpl ? await deps.isSeaImpl() : await detectSea()) ? "binary" : detectInstallMethod(deps.argvPath ?? process.argv[1]);
   const latest = await (deps.fetchLatestImpl ?? fetchLatestVersion2)();
@@ -7028,14 +7380,14 @@ function closestNames(query, candidates, limit) {
 }
 
 // src/guide.ts
-import { readFile as readFile10 } from "fs/promises";
+import { readFile as readFile11 } from "fs/promises";
 var GUIDE_READ_TIMEOUT_MS = 1e3;
 async function readGuide(path5, scope) {
   let raw;
   const ac = new AbortController();
   const timer = setTimeout(() => ac.abort(new Error("guide read timeout")), GUIDE_READ_TIMEOUT_MS);
   try {
-    raw = await readFile10(path5, { encoding: "utf8", signal: ac.signal });
+    raw = await readFile11(path5, { encoding: "utf8", signal: ac.signal });
   } catch (err) {
     const isTimeout = err instanceof Error && err.code === "ABORT_ERR";
     if (isTimeout) {
@@ -7255,6 +7607,63 @@ function pushToolCall(history, record, limit = HISTORY_LIMIT) {
   return history;
 }
 
+// src/install-nudge.ts
+import { existsSync as existsSync7, mkdirSync as mkdirSync2, readFileSync as readFileSync4, writeFileSync as writeFileSync2 } from "fs";
+import { dirname as dirname4, join as join12 } from "path";
+var INSTALL_NUDGE_MIN_COUNT = 5;
+var INSTALL_NUDGE_COOLDOWN_MS = 7 * 24 * 60 * 60 * 1e3;
+var INSTALL_NUDGE_STATE_FILENAME = "install-nudge-state.json";
+function installNudgeStatePath(home) {
+  return join12(home, CONFIG_DIRNAME, INSTALL_NUDGE_STATE_FILENAME);
+}
+function installNudgeEnabled(env, config) {
+  if (env.YAW_MCP_INSTALL_NUDGE === "1") return true;
+  if (config?.installNudge === true) return true;
+  return false;
+}
+function readState(home) {
+  const path5 = installNudgeStatePath(home);
+  if (!existsSync7(path5)) return { nudges: [] };
+  try {
+    const parsed = JSON.parse(readFileSync4(path5, "utf8"));
+    if (!parsed || typeof parsed !== "object") return { nudges: [] };
+    const raw = parsed.nudges;
+    if (!Array.isArray(raw)) return { nudges: [] };
+    const nudges = [];
+    for (const entry of raw) {
+      if (entry && typeof entry === "object" && typeof entry.cli === "string" && typeof entry.nudgedAt === "number") {
+        nudges.push({ cli: entry.cli, nudgedAt: entry.nudgedAt });
+      }
+    }
+    return { nudges };
+  } catch {
+    return { nudges: [] };
+  }
+}
+function shouldNudge(cli, home, now = Date.now) {
+  const state = readState(home);
+  const rec = state.nudges.find((n) => n.cli === cli);
+  if (!rec) return true;
+  return now() - rec.nudgedAt >= INSTALL_NUDGE_COOLDOWN_MS;
+}
+function recordNudge(cli, home, now = Date.now) {
+  try {
+    const at = now();
+    const state = readState(home);
+    const kept = state.nudges.filter((n) => n.cli !== cli && at - n.nudgedAt < INSTALL_NUDGE_COOLDOWN_MS);
+    kept.push({ cli, nudgedAt: at });
+    const path5 = installNudgeStatePath(home);
+    mkdirSync2(dirname4(path5), { recursive: true });
+    writeFileSync2(path5, `${JSON.stringify({ nudges: kept }, null, 2)}
+`, "utf8");
+  } catch (err) {
+    log("debug", "install-nudge: failed to record nudge state", {
+      cli,
+      error: err instanceof Error ? err.message : String(err)
+    });
+  }
+}
+
 // src/learning.ts
 var LEARNING_MIN_OBSERVATIONS = 3;
 var LEARNING_MAX_BOOST = 1.1;
@@ -7647,6 +8056,26 @@ var META_TOOLS = {
       openWorldHint: false
     }
   },
+  secrets: {
+    name: "mcp_connect_secrets",
+    description: "List, per installed server, which local-vault secrets its `${secret:NAME}` env references resolve to -- by NAME only, never a value. Use this to confirm a server will get the credentials it needs before activating it, or to spot a typo'd / un-set secret reference. `injectedSecrets` are the names the local vault HAS and the server references; `missing` are names the server references but the vault LACKS (set them via `yaw-mcp secrets set <name>`). This is a values-free preview: it reads the vault's KEY LIST and the server's env-reference NAMES, and never decrypts or returns any secret value. Servers with no `${secret:...}` references are omitted. Requires no passphrase (no decryption happens).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        server: {
+          type: "string",
+          description: 'Optional: restrict the report to a single server namespace (e.g. "gh"). Omit to report every installed server that references a vault secret.'
+        }
+      }
+    },
+    annotations: {
+      title: "Inspect Vault Secret Resolution",
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    }
+  },
   exec: {
     name: "mcp_connect_exec",
     description: "Run a short DECLARATIVE pipeline of upstream tool calls in a single round-trip. Use this when you already know the exact 2-4 tool calls to make and one call's output feeds another's args \u2014 e.g. `a = gh_list_prs(); b = gh_get_pr(a[0].number); return b`. NOT a code sandbox: there is no expression language, no loops, no branching, no arithmetic. The only control flow is sequential step execution; the only data-flow primitive is `{\"$ref\": \"<stepId>[.path.to.value]\"}` which substitutes a prior step's output (or a nested field of it) into the next step's args. Paths support dot keys and `[N]` / `.N` array indexing. Each step's `tool` must be a namespaced, already-loaded tool name (the exec does not auto-activate \u2014 call `mcp_connect_activate` first). Max 16 steps per exec. If any step fails, the whole pipeline fails and returns `{ ok: false, failedStep, error, partial: { ...completed outputs } }`. On success returns `{ ok: true, result: <return-step output>, steps: { ...all outputs } }`. Prefer this over back-to-back tool calls when the chain is deterministic \u2014 it saves prompt-token replay and client round-trips.",
@@ -7764,6 +8193,30 @@ function buildInstallPayload(args) {
   }
   return { ok: true, payload };
 }
+var SECRETS_REPORT_REF_RE = /\$\{secret:([a-zA-Z0-9_.-]+)\}/g;
+function computeSecretsReport(servers, vaultKeys) {
+  const rows = [];
+  for (const server of servers) {
+    const referenced = /* @__PURE__ */ new Set();
+    for (const v of Object.values(server.env ?? {})) {
+      if (typeof v !== "string") continue;
+      for (const m of v.matchAll(SECRETS_REPORT_REF_RE)) referenced.add(m[1]);
+    }
+    if (referenced.size === 0) continue;
+    const injectedSecrets = [];
+    const missing = [];
+    for (const name of referenced) {
+      if (vaultKeys.has(name)) injectedSecrets.push(name);
+      else missing.push(name);
+    }
+    rows.push({
+      server: server.namespace,
+      injectedSecrets: injectedSecrets.sort(),
+      missing: missing.sort()
+    });
+  }
+  return rows;
+}
 var META_TOOL_NAMES = /* @__PURE__ */ new Set([
   META_TOOLS.discover.name,
   META_TOOLS.activate.name,
@@ -7775,7 +8228,8 @@ var META_TOOL_NAMES = /* @__PURE__ */ new Set([
   META_TOOLS.read_tool.name,
   META_TOOLS.suggest.name,
   META_TOOLS.exec.name,
-  META_TOOLS.bundles.name
+  META_TOOLS.bundles.name,
+  META_TOOLS.secrets.name
 ]);
 
 // src/pack-detect.ts
@@ -8973,6 +9427,62 @@ import {
   ToolListChangedNotificationSchema
 } from "@modelcontextprotocol/sdk/types.js";
 
+// src/oam-spawn.ts
+import { execFileSync } from "child_process";
+import { createRequire } from "module";
+var requireFrom = createRequire(import.meta.url);
+function packageName(spec) {
+  const start = spec.startsWith("@") ? 1 : 0;
+  const at = spec.indexOf("@", start);
+  return at === -1 ? spec : spec.slice(0, at);
+}
+var oamBinCache;
+function oamBin() {
+  if (oamBinCache !== void 0) return oamBinCache;
+  const bin = process.env.OAM_BIN || (process.platform === "win32" ? "oam.exe" : "oam");
+  try {
+    execFileSync(bin, ["--version"], { stdio: "ignore" });
+    oamBinCache = bin;
+  } catch {
+    oamBinCache = null;
+  }
+  return oamBinCache;
+}
+function rewriteForOam(command, args, deps) {
+  const bin = deps.oamBin;
+  if (!bin) return { command, args };
+  const toOam = (entry, rest) => ({
+    command: bin,
+    args: rest.length > 0 ? ["run", entry, "--", ...rest] : ["run", entry]
+  });
+  if (command === "node") {
+    const [entry, ...rest] = args;
+    if (!entry) return { command, args };
+    return toOam(entry, rest);
+  }
+  if (command === "npx") {
+    const positional = args.filter((a) => a !== "-y" && a !== "--yes");
+    const [spec, ...rest] = positional;
+    if (!spec) return { command, args };
+    const entry = deps.resolveEntry(packageName(spec));
+    if (!entry) return { command, args };
+    return toOam(entry, rest);
+  }
+  return { command, args };
+}
+function resolveOamSpawn(command, args) {
+  return rewriteForOam(command, args, {
+    oamBin: oamBin(),
+    resolveEntry: (pkg) => {
+      try {
+        return requireFrom.resolve(pkg);
+      } catch {
+        return null;
+      }
+    }
+  });
+}
+
 // src/uv-bootstrap.ts
 import { spawn as spawn5 } from "child_process";
 import { createHash as createHash3 } from "crypto";
@@ -9213,7 +9723,7 @@ async function resolveUvSpawn(command, args) {
 }
 
 // src/upstream.ts
-async function resolveServerEnv(env) {
+async function resolveServerEnv(env, namespace) {
   if (!hasSecretRefs(env)) return env;
   const refKeys = Object.entries(env).filter(([, v]) => typeof v === "string" && v.includes("${secret:")).map(([k]) => k);
   const passphrase = process.env.YAW_MCP_VAULT_PASSPHRASE;
@@ -9235,8 +9745,36 @@ async function resolveServerEnv(env) {
   if (missing.length > 0) {
     throw new Error(`vault: missing or undecryptable secret refs: ${missing.join(", ")}`);
   }
+  try {
+    await recordResolveAudit(namespace, env, missing);
+  } catch (auditErr) {
+    log("warn", "Failed to record secret-resolve audit (non-fatal)", {
+      namespace,
+      error: auditErr instanceof Error ? auditErr.message : String(auditErr)
+    });
+  }
   return resolved;
 }
+async function recordResolveAudit(namespace, env, missing) {
+  const missingSet = new Set(missing);
+  const referenced = collectSecretNames(env);
+  for (const name of referenced) {
+    if (missingSet.has(name)) continue;
+    await appendAuditEvent({ server: namespace, secret: name, event: "injected" });
+  }
+  for (const name of missingSet) {
+    await appendAuditEvent({ server: namespace, secret: name, event: "missing" });
+  }
+}
+function collectSecretNames(env) {
+  const names = /* @__PURE__ */ new Set();
+  const re = /\$\{secret:([a-zA-Z0-9_.-]+)\}/g;
+  for (const v of Object.values(env)) {
+    if (typeof v !== "string") continue;
+    for (const m of v.matchAll(re)) names.add(m[1]);
+  }
+  return [...names];
+}
 var DEFAULT_CONNECT_TIMEOUT = (() => {
   const env = process.env.MCP_CONNECT_TIMEOUT;
   if (!env) return 15e3;
@@ -9284,7 +9822,7 @@ function categorizeSpawnError(err) {
 }
 async function connectToUpstream(config, onDisconnect, onListChanged) {
   const client = new Client(
-    { name: "yaw-mcp", version: true ? "0.64.2" : "dev" },
+    { name: "yaw-mcp", version: true ? "0.66.0" : "dev" },
     { capabilities: {} }
   );
   let transport;
@@ -9299,8 +9837,11 @@ async function connectToUpstream(config, onDisconnect, onListChanged) {
       YAW_MCP_VAULT_PASSPHRASE: _excludedVaultPassphrase,
       ...parentEnv
     } = process.env;
-    const resolved = await resolveUvSpawn(config.command, config.args ?? []);
-    const serverEnv = await resolveServerEnv(config.env ?? {});
+    let resolved = await resolveUvSpawn(config.command, config.args ?? []);
+    if (config.runtime === "oam") {
+      resolved = resolveOamSpawn(resolved.command, resolved.args);
+    }
+    const serverEnv = await resolveServerEnv(config.env ?? {}, config.namespace);
     resolvedServerEnv = serverEnv;
     const stdioTransport = new StdioClientTransport({
       command: resolved.command,
@@ -9616,7 +10157,7 @@ var ConnectServer = class _ConnectServer {
     this.apiUrl = apiUrl5;
     this.token = token5;
     this.server = new Server(
-      { name: "yaw-mcp", version: true ? "0.64.2" : "dev" },
+      { name: "yaw-mcp", version: true ? "0.66.0" : "dev" },
       {
         capabilities: {
           tools: { listChanged: true },
@@ -9662,6 +10203,19 @@ var ConnectServer = class _ConnectServer {
   // same namespace, on deactivate, and on config reconcile.
   toolFilters = /* @__PURE__ */ new Map();
   profile = null;
+  // Shadow-driven install-nudge gate. Resolved once at start() from the
+  // env override (YAW_MCP_INSTALL_NUDGE=1) OR config (installNudge: true);
+  // off by default. When false, discover NEVER runs the shell-history scan
+  // and its output is byte-identical to today (the load-bearing privacy
+  // property). See install-nudge.ts. Stays false in unit tests that skip
+  // start(), so the nudge block is opt-in there too.
+  installNudge = false;
+  // home / env used by the install-nudge shell-history scan. Default to the
+  // real process values; overridable so tests can point the scan at a
+  // synthetic home + stubbed env without touching the developer's real
+  // shell history or ~/.yaw-mcp/ state file.
+  nudgeHome = homedir16();
+  nudgeEnv = process.env;
   // Loaded YAW-MCP.md guides (user-global + project-local). Null until
   // start() has run the loader; fail-open if either file is missing,
   // unreadable, or empty.
@@ -9886,7 +10440,8 @@ var ConnectServer = class _ConnectServer {
       }
       this.persistenceReady = true;
     }
-    this.profile = await loadEffectiveProfile(process.cwd()).catch(() => null);
+    const resolvedConfig = await loadYawMcpConfig({ cwd: process.cwd() }).catch(() => null);
+    this.profile = resolvedConfig ? toProfile(resolvedConfig) : null;
     if (this.profile) {
       log("info", "Loaded profile", {
         path: this.profile.path,
@@ -9895,6 +10450,10 @@ var ConnectServer = class _ConnectServer {
         block: this.profile.blocked
       });
     }
+    this.installNudge = installNudgeEnabled(process.env, resolvedConfig);
+    if (this.installNudge) {
+      log("info", "Shadow-driven install nudge enabled");
+    }
     this.guides = await loadGuides(process.cwd()).catch(() => ({ user: null, project: null }));
     if (this.guides.user || this.guides.project) {
       log("info", "Loaded YAW-MCP.md guide", {
@@ -10198,6 +10757,17 @@ var ConnectServer = class _ConnectServer {
       recordConnectEvent({ namespace: null, toolName: null, action: "bundles", latencyMs: null, success: true });
       return this.attachGuideNudge(this.handleBundles(action));
     }
+    if (name === META_TOOLS.secrets.name) {
+      const serverArg = typeof args.server === "string" ? args.server : void 0;
+      recordConnectEvent({
+        namespace: serverArg ?? null,
+        toolName: null,
+        action: "secrets",
+        latencyMs: null,
+        success: true
+      });
+      return this.attachGuideNudge(await this.handleSecretsReport(serverArg));
+    }
     let routes = this.toolRoutes;
     let route = routes.get(name);
     if (route?.deferred) {
@@ -10678,6 +11248,7 @@ var ConnectServer = class _ConnectServer {
         lines.push(`  ${server.namespace} \u2014 ${server.name} (disabled in dashboard)`);
       }
     }
+    lines.push(...this.buildInstallCandidatesLines(activeServers));
     const activeCount = this.connections.size;
     const totalTools = Array.from(this.connections.values()).reduce((sum, c) => {
       const f = this.toolFilters.get(c.config.namespace);
@@ -10696,6 +11267,51 @@ ${activeCount} loaded in this session, ${totalTools} tools in context${tokenSumm
     }
     return { content: [{ type: "text", text: lines.join("\n") }] };
   }
+  // Build the opt-in "Install candidates" block from the offline shell-
+  // history shadow scan. Returns [] (no lines, byte-identical output) when
+  // the gate is off — the load-bearing privacy property: with the gate
+  // unset the scan never runs and nothing about shell history is read.
+  //
+  // When ON, for each heavily-used CLI the scan found:
+  //   - skip unless count >= INSTALL_NUDGE_MIN_COUNT (noise floor),
+  //   - skip unless a FIRST-PARTY install target exists (installTargetForCli;
+  //     a CLI like kubectl/npm/ssh with no target produces no nudge),
+  //   - skip if ANY namespace the CLI maps to is already installed (the user
+  //     already has a server that covers it — intersect the hit's namespaces
+  //     with the installed set),
+  //   - skip if the per-CLI cooldown hasn't elapsed (shouldNudge).
+  // Surviving CLIs are recorded (recordNudge) so they stay suppressed for
+  // the cooldown, and rendered as one line + an mcp_connect_install sketch.
+  //
+  // Privacy: the only data emitted is the aggregate integer count + the
+  // first-party package / namespace / name. No raw history line, command
+  // text, or argument ever reaches this output, and nothing here is sent to
+  // analytics — scanShellHistoryForShadows is local-only and returns just
+  // { cli, count, namespaces }.
+  buildInstallCandidatesLines(activeServers) {
+    if (!this.installNudge) return [];
+    const installedNamespaces = new Set(activeServers.map((s) => s.namespace));
+    const hits = scanShellHistoryForShadows({ home: this.nudgeHome, env: this.nudgeEnv });
+    const candidates = [];
+    for (const hit of hits) {
+      if (hit.count < INSTALL_NUDGE_MIN_COUNT) continue;
+      if (hit.namespaces.some((ns) => installedNamespaces.has(ns))) continue;
+      const target = installTargetForCli(hit.cli);
+      if (!target) continue;
+      if (installedNamespaces.has(target.namespace)) continue;
+      if (!shouldNudge(hit.cli, this.nudgeHome)) continue;
+      candidates.push({ cli: hit.cli, count: hit.count, target });
+    }
+    if (candidates.length === 0) return [];
+    const lines = ["\nInstall candidates (from your recent shell usage; history stays local):"];
+    for (const { cli, count, target } of candidates) {
+      lines.push(`  ${cli.padEnd(10)} (ran ${count}x recently) -> install ${target.package}`);
+      const sketch = `mcp_connect_install({ name: ${JSON.stringify(target.name)}, namespace: ${JSON.stringify(target.namespace)}, type: "local", command: "npx", args: ["-y", ${JSON.stringify(target.package)}] })`;
+      lines.push(`     ${sketch}`);
+      recordNudge(cli, this.nudgeHome);
+    }
+    return lines;
+  }
   // Activate a single server by namespace. Shared by handleActivate,
   // handleDispatch, and handleDiscoverWithAutoWarm so error handling,
   // retries, caching, and tool-report round-trips live in one place.
@@ -11293,7 +11909,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("~\\") ? resolve6(homedir15(), filepath.slice(2)) : resolve6(filepath);
+      const resolved = filepath.startsWith("~/") || filepath.startsWith("~\\") ? resolve6(homedir16(), filepath.slice(2)) : resolve6(filepath);
       const resolvedBasename = resolved.split(/[/\\]/).pop() || "";
       if (!ALLOWED_FILENAMES.includes(resolvedBasename)) {
         return {
@@ -11310,7 +11926,7 @@ ${activeCount} loaded in this session, ${totalTools} tools in context${tokenSumm
         const rel = relative(base, p);
         return rel === "" || !rel.startsWith("..") && !isAbsolute2(rel);
       };
-      if (!isUnder(homedir15(), resolved) && !isUnder(process.cwd(), resolved)) {
+      if (!isUnder(homedir16(), resolved) && !isUnder(process.cwd(), resolved)) {
         return {
           content: [
             { type: "text", text: "Import path must be under your home directory or the current working directory." }
@@ -11318,7 +11934,7 @@ ${activeCount} loaded in this session, ${totalTools} tools in context${tokenSumm
           isError: true
         };
       }
-      const raw = await readFile11(resolved, "utf-8");
+      const raw = await readFile12(resolved, "utf-8");
       const parsed = JSON.parse(raw);
       if (!parsed.mcpServers || typeof parsed.mcpServers !== "object" || Array.isArray(parsed.mcpServers)) {
         return {
@@ -11610,6 +12226,43 @@ Use mcp_connect_discover to see imported servers.`
       );
     }
   }
+  // Values-free preview of which local-vault secrets each installed
+  // server's `${secret:NAME}` env refs resolve to. NAMES ONLY -- this
+  // reads the vault's KEY LIST (listKeys, no unlock, no passphrase) and
+  // the servers' env-reference names, and NEVER calls getSecret /
+  // decryptEntry. Servers with no refs are omitted.
+  async handleSecretsReport(serverArg) {
+    const vault = await loadVault(vaultPath()).catch(() => null);
+    const vaultKeys = new Set(vault ? listKeys(vault) : []);
+    let servers = this.getProfiledActiveServers().map((s) => ({ namespace: s.namespace, env: s.env }));
+    if (serverArg) servers = servers.filter((s) => s.namespace === serverArg);
+    const rows = computeSecretsReport(servers, vaultKeys);
+    if (serverArg && servers.length === 0) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `No installed server with namespace "${serverArg}". Call mcp_connect_discover to list installed servers.`
+          }
+        ],
+        isError: true
+      };
+    }
+    if (rows.length === 0) {
+      const scope = serverArg ? `Server "${serverArg}"` : "No installed server";
+      return {
+        content: [
+          {
+            type: "text",
+            text: `${scope} references any \${secret:NAME} vault values. Add a reference in a server's env (e.g. GITHUB_TOKEN=\${secret:gh}) and store the value with \`yaw-mcp secrets set <name>\`.`
+          }
+        ]
+      };
+    }
+    return {
+      content: [{ type: "text", text: JSON.stringify(rows, null, 2) }]
+    };
+  }
   handleHealth() {
     const lines = [];
     if (this.profile) {
@@ -12122,21 +12775,21 @@ function truncateVersion(v) {
 }
 
 // src/set-active-cmd.ts
-import { homedir as homedir16 } from "os";
+import { homedir as homedir17 } from "os";
 
 // src/sync-state.ts
-import { existsSync as existsSync6 } from "fs";
-import { mkdir as mkdir5, readFile as readFile12 } from "fs/promises";
-import { dirname as dirname4, join as join11 } from "path";
+import { existsSync as existsSync8 } from "fs";
+import { mkdir as mkdir5, readFile as readFile13 } from "fs/promises";
+import { dirname as dirname5, join as join13 } from "path";
 var SYNC_STATE_FILENAME = "sync-state.json";
 function syncStatePath(home) {
-  return join11(home, CONFIG_DIRNAME, SYNC_STATE_FILENAME);
+  return join13(home, CONFIG_DIRNAME, SYNC_STATE_FILENAME);
 }
 async function readSyncState(home) {
   const path5 = syncStatePath(home);
-  if (!existsSync6(path5)) return {};
+  if (!existsSync8(path5)) return {};
   try {
-    const raw = await readFile12(path5, "utf8");
+    const raw = await readFile13(path5, "utf8");
     const parsed = JSON.parse(raw);
     if (!parsed || typeof parsed !== "object") return {};
     return parsed;
@@ -12146,7 +12799,7 @@ async function readSyncState(home) {
 }
 async function writeSyncState(home, state) {
   const path5 = syncStatePath(home);
-  await mkdir5(dirname4(path5), { recursive: true });
+  await mkdir5(dirname5(path5), { recursive: true });
   const existing = await readSyncState(home);
   const merged = { ...existing, ...state };
   await atomicWriteFile(path5, `${JSON.stringify(merged, null, 2)}
@@ -12240,7 +12893,7 @@ async function runSetActive(opts, io = { out: (s) => process.stdout.write(s), er
           base
         );
         if (typeof putRes.version === "number") {
-          await deps.writeSyncState(opts.home ?? homedir16(), {
+          await deps.writeSyncState(opts.home ?? homedir17(), {
             mcp_bundles: { lastPulledVersion: putRes.version }
           }).catch(() => {
           });
@@ -12286,7 +12939,7 @@ function fail(io, json, message, code) {
 }
 
 // src/stats-cmd.ts
-import { homedir as homedir17 } from "os";
+import { homedir as homedir18 } from "os";
 var STATS_USAGE = `Usage: yaw-mcp stats [--json] [--limit N] [--days N]
 
   Print a digest of recent AI tool calls recorded against your Yaw
@@ -12410,7 +13063,7 @@ async function runStats(opts, io = {
   out: (s) => process.stdout.write(s),
   err: (s) => process.stderr.write(s)
 }) {
-  const home = opts.home ?? homedir17();
+  const home = opts.home ?? homedir18();
   const session = await getSession({ home, baseUrl: opts.baseUrl });
   if (!session) {
     const msg = "Not signed in. Yaw MCP analytics requires a Yaw Team account.\n  - Yaw Team: $15/seat/mo or $150/seat/yr -- https://yaw.sh/mcp\nSign in with: yaw-mcp login --key <license-key>";
@@ -12511,10 +13164,10 @@ function suggestFlag(input, limit = 2) {
 }
 
 // src/sync-cmd.ts
-import { existsSync as existsSync7 } from "fs";
-import { mkdir as mkdir6, readFile as readFile13 } from "fs/promises";
-import { homedir as homedir18 } from "os";
-import { dirname as dirname5, join as join12 } from "path";
+import { existsSync as existsSync9 } from "fs";
+import { mkdir as mkdir6, readFile as readFile14 } from "fs/promises";
+import { homedir as homedir19 } from "os";
+import { dirname as dirname6, join as join14 } from "path";
 var SYNC_USAGE = `Usage: yaw-mcp sync <push|pull|status> [--json]
 
   Replicate ~/.yaw-mcp/bundles.json across machines via your Yaw
@@ -12561,12 +13214,12 @@ ${SYNC_USAGE}` };
   return { ok: true, options: opts };
 }
 function bundlesPath(home) {
-  return join12(home, CONFIG_DIRNAME, BUNDLES_FILENAME2);
+  return join14(home, CONFIG_DIRNAME, BUNDLES_FILENAME2);
 }
 async function readLocalBundles(home) {
   const path5 = bundlesPath(home);
-  if (!existsSync7(path5)) return { version: 1, servers: [] };
-  const raw = await readFile13(path5, "utf8");
+  if (!existsSync9(path5)) return { version: 1, servers: [] };
+  const raw = await readFile14(path5, "utf8");
   let parsed;
   try {
     parsed = JSON.parse(raw);
@@ -12581,7 +13234,7 @@ async function readLocalBundles(home) {
 }
 async function writeLocalBundles(home, file) {
   const path5 = bundlesPath(home);
-  await mkdir6(dirname5(path5), { recursive: true });
+  await mkdir6(dirname6(path5), { recursive: true });
   await atomicWriteFile(path5, `${JSON.stringify(file, null, 2)}
 `);
   return path5;
@@ -12617,7 +13270,7 @@ async function runSync(opts, io = {
   out: (s) => process.stdout.write(s),
   err: (s) => process.stderr.write(s)
 }) {
-  const home = opts.home ?? homedir18();
+  const home = opts.home ?? homedir19();
   const session = await getSession({ home, baseUrl: opts.baseUrl });
   if (!session) {
     const msg = "Not signed in. Run `yaw-mcp login --key <license-key>` first.";
@@ -13192,7 +13845,7 @@ if (subcommand === "compliance") {
 `);
   process.exit(0);
 } else if (subcommand === "--version" || subcommand === "-V") {
-  process.stdout.write(`yaw-mcp ${true ? "0.64.2" : "dev"}
+  process.stdout.write(`yaw-mcp ${true ? "0.66.0" : "dev"}
 `);
   process.exit(0);
 } else if (subcommand && !subcommand.startsWith("-")) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/mcp",
-  "version": "0.64.2",
+  "version": "0.66.0",
   "mcpName": "io.github.YawLabs/mcp",
   "description": "Yaw MCP -- MCP servers, managed. Free to run locally; Yaw Team adds cross-machine sync.",
   "license": "UNLICENSED",