@openparachute/vault 0.4.3 → 0.4.4-rc.11

package/src/cli.ts

@@ -7,7 +7,8 @@
  *   parachute-vault init                    — set up everything, one command
  *   parachute-vault create <name>           — create a new vault
  *   parachute-vault list                    — list all vaults
- *   parachute-vault mcp-install <name>      — add vault MCP to ~/.claude.json
+ *   parachute-vault mcp-install [flags]     — install vault MCP into a client config
+ *                                              (defaults: --mint into ~/.claude.json)
  *   parachute-vault remove <name>           — remove a vault
  *   parachute-vault config                  — show all config
  *   parachute-vault config set <key> <val>  — set a config value
@@ -51,7 +52,21 @@ import {
 import type { VaultConfig } from "./config.ts";
 import { DATA_DIR } from "./config.ts";
 import { installAgent, uninstallAgent, isAgentLoaded, restartAgent } from "./launchd.ts";
-import { chooseMcpUrl } from "./mcp-install.ts";
+import {
+  buildMcpEntryPlan,
+  chooseHubOrigin,
+  detectInstallContext,
+  mintHubJwt,
+  readOperatorToken,
+  removeMcpConfig,
+  resolveInstallTarget,
+  type InstallScope,
+} from "./mcp-install.ts";
+import {
+  defaultInteractiveIO,
+  runInteractiveInstall,
+  type InteractiveIO,
+} from "./mcp-install-interactive.ts";
 import { buildInitSummaryLines } from "./init-summary.ts";
 import {
   runBackup,
@@ -152,7 +167,7 @@ switch (command) {
     cmdList();
     break;
   case "mcp-install":
-    cmdMcpInstall(cmdArgs);
+    await cmdMcpInstall(cmdArgs);
     break;
   case "remove":
   case "rm":
@@ -503,7 +518,25 @@ async function cmdInit(args: string[] = []) {
   }
 
   if (addMcp) {
-    installMcpConfig(apiKey);
+    // Init's bootstrap path stays on the pvt_* shape so a fresh-install
+    // without a hub still works out of the box. Operators with a hub can
+    // re-run `parachute-vault mcp-install` (defaults to hub-mint) to
+    // upgrade. Goes through `buildMcpEntryPlan` for entryKey + url so this
+    // path shares the writer-side invariant with `executeMcpInstall` — a
+    // future URL-shape change can't drift between init and mcp-install.
+    const target = resolveInstallTarget("user");
+    const { entryKey, url, source } = buildMcpEntryPlan({
+      vaultName: defaultVault,
+      vaultExplicit: false,
+      port: globalConfig.port || DEFAULT_PORT,
+    });
+    installMcpConfig({
+      targetPath: target.path,
+      entryKey,
+      url,
+      bearer: apiKey,
+    });
+    console.log(`MCP URL: ${url} (${source})`);
     console.log(`  MCP server added to ~/.claude.json`);
   } else {
     console.log("  Skipped adding MCP to ~/.claude.json.");
@@ -880,10 +913,344 @@ function cmdList() {
   }
 }
 
-function cmdMcpInstall(_args: string[]) {
-  installMcpConfig();
-  console.log(`Added MCP server "parachute-vault" to ~/.claude.json`);
-  console.log(`All vaults accessible via the 'vault' parameter on each tool.`);
+/**
+ * Parse a `--flag value` pair from an args array. Returns the value (or
+ * undefined when the flag isn't present) and a flag whether the flag's value
+ * was actually present (catches `--flag` without an argument).
+ */
+function takeArgValue(args: string[], name: string): { value?: string; missingValue?: boolean } {
+  const idx = args.indexOf(name);
+  if (idx === -1) return {};
+  const next = args[idx + 1];
+  if (!next || next.startsWith("--")) return { missingValue: true };
+  return { value: next };
+}
+
+/**
+ * `parachute-vault mcp-install` — install the vault MCP server into an
+ * AI client's config. Three auth modes (mutually exclusive):
+ *
+ *   --mint                (default) Mint a hub JWT via `POST <hub>/api/auth/mint-token`
+ *                         using the local operator token.
+ *   --token <bearer>      Use an existing token (hub JWT, pvt_*, anything).
+ *   --legacy-pat          Mint a vault-DB `pvt_*` token (deprecated;
+ *                         self-hosted-without-hub setups).
+ *
+ * Targeting:
+ *   --scope <verb>        vault:read | vault:write | vault:admin (default: vault:read).
+ *                         For --mint, expands to vault:<vault-name>:<verb>.
+ *   --install-scope <s>   local (default) | user | project. local writes to
+ *                         ~/.claude.json under projects[<cwd>].mcpServers
+ *                         (private, this directory only — matches Claude
+ *                         Code's own default). user writes to top-level
+ *                         mcpServers (every project). project writes to
+ *                         ./.mcp.json (check into the repo).
+ *   --vault <name>        Vault to target (default: default_vault). Multi-vault
+ *                         installs key the entry as `parachute-vault-<name>`.
+ *   --client <name>       Reserved for Phase C. Only `claude-code` accepted.
+ */
+async function cmdMcpInstall(args: string[]): Promise<void> {
+  // Set of install-shaping flags. Any one flips dispatch to non-interactive
+  // — flag-passing semantics are "I know what I want."
+  //
+  // Declared inside the function (rather than module-top) because this
+  // file's top-level dispatch await runs cmdMcpInstall during module
+  // initialization, and a module-top `const` is still in its temporal
+  // dead zone when the function body first executes from that dispatch.
+  const MCP_INSTALL_FLAG_NAMES = [
+    "--mint",
+    "--legacy-pat",
+    "--token",
+    "--scope",
+    "--install-scope",
+    "--vault",
+    "--client",
+  ];
+
+  const hasFlag = args.some((a) => MCP_INSTALL_FLAG_NAMES.includes(a));
+  const isTTY = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+
+  // Interactive dispatch fires when the operator passed no install-shaping
+  // flags AND stdin is a TTY. No separate `--interactive` flag — TTY+
+  // no-flags already covers the "walk me through it" case, and forcing
+  // interactive with partial flags is a half-feature that silently
+  // discards co-present flag values (vault#292 review F1). Non-TTY
+  // bare invocation falls through to the flag-driven defaults.
+  if (isTTY && !hasFlag) {
+    return await cmdMcpInstallInteractive();
+  }
+
+  // --- Auth-mode parsing (mutually exclusive) ---
+  const wantMint = args.includes("--mint");
+  const wantLegacy = args.includes("--legacy-pat");
+  const tokenArg = takeArgValue(args, "--token");
+  if (tokenArg.missingValue) {
+    console.error("--token requires a value (the bearer token to embed).");
+    process.exit(1);
+  }
+  const wantToken = tokenArg.value !== undefined;
+  const modesSet = (wantMint ? 1 : 0) + (wantLegacy ? 1 : 0) + (wantToken ? 1 : 0);
+  if (modesSet > 1) {
+    console.error("--mint, --token, and --legacy-pat are mutually exclusive.");
+    process.exit(1);
+  }
+  const mode: "mint" | "token" | "legacy-pat" =
+    wantToken ? "token" : wantLegacy ? "legacy-pat" : "mint";
+
+  // --- Scope parsing. Default vault:read (least-privilege). ---
+  const scopeArg = takeArgValue(args, "--scope");
+  if (scopeArg.missingValue) {
+    console.error("--scope requires a value: vault:read, vault:write, or vault:admin.");
+    process.exit(1);
+  }
+  const rawScope = scopeArg.value ?? "vault:read";
+  if (!(VAULT_SCOPES as readonly string[]).includes(rawScope)) {
+    console.error(
+      `--scope must be one of: ${VAULT_SCOPES.join(", ")}. Got: ${rawScope}.`,
+    );
+    process.exit(1);
+  }
+
+  // --- Install scope: local (default), user, or project. ---
+  // `local` matches Claude Code's own `claude mcp add` default — entry sits
+  // under `projects[<cwd>].mcpServers` in ~/.claude.json, private to this
+  // machine + this directory. Operators wanting a global install pass
+  // `--install-scope user`; team-shared installs pass `--install-scope project`.
+  const installScopeArg = takeArgValue(args, "--install-scope");
+  if (installScopeArg.missingValue) {
+    console.error("--install-scope requires a value: local, user, or project.");
+    process.exit(1);
+  }
+  const installScopeRaw = installScopeArg.value ?? "local";
+  if (
+    installScopeRaw !== "user" &&
+    installScopeRaw !== "project" &&
+    installScopeRaw !== "local"
+  ) {
+    console.error(
+      `--install-scope must be "local", "user", or "project". Got: ${installScopeRaw}.`,
+    );
+    process.exit(1);
+  }
+  const installScope: InstallScope = installScopeRaw;
+
+  // --- Client (Phase C placeholder). Reject anything other than claude-code. ---
+  // Validated before filesystem-dependent vault-existence so a static flag
+  // typo fails on its own terms ("--client cursor not supported") rather
+  // than getting masked by an unrelated "vault not found" error.
+  const clientArg = takeArgValue(args, "--client");
+  if (clientArg.missingValue) {
+    console.error("--client requires a value.");
+    process.exit(1);
+  }
+  const client = clientArg.value ?? "claude-code";
+  if (client !== "claude-code") {
+    console.error(
+      `--client "${client}" is not yet supported. Only "claude-code" is wired up; ` +
+        `Cursor / Claude Desktop / Codex / Zed are Phase C work.`,
+    );
+    process.exit(1);
+  }
+
+  // --- Vault target. Default = default_vault; validate existence. ---
+  const vaultArg = takeArgValue(args, "--vault");
+  if (vaultArg.missingValue) {
+    console.error("--vault requires a value (the vault name).");
+    process.exit(1);
+  }
+  const globalConfig = readGlobalConfig();
+  const defaultVault = globalConfig.default_vault || "default";
+  const vaultName = vaultArg.value ?? defaultVault;
+  const vaultExplicit = vaultArg.value !== undefined;
+  if (!readVaultConfig(vaultName)) {
+    console.error(`Vault "${vaultName}" not found. Available: ${listVaults().join(", ") || "(none)"}.`);
+    process.exit(1);
+  }
+
+  await executeMcpInstall({
+    mode,
+    rawScope,
+    installScope,
+    vaultName,
+    vaultExplicit,
+    pastedToken: mode === "token" ? tokenArg.value : undefined,
+    globalConfig,
+  });
+}
+
+/**
+ * Interactive front-end for `mcp-install`. Builds the install context,
+ * walks the operator through prompts, then hands the resolved decision
+ * to `executeMcpInstall`. Failure modes from the walkthrough (operator
+ * aborted, no vaults yet, etc.) exit cleanly without touching disk.
+ */
+async function cmdMcpInstallInteractive(): Promise<void> {
+  const globalConfig = readGlobalConfig();
+  const defaultVault = globalConfig.default_vault || "default";
+  const port = globalConfig.port || DEFAULT_PORT;
+  const ctx = detectInstallContext({
+    vaults: listVaults(),
+    defaultVault,
+    port,
+  });
+  const io = await defaultInteractiveIO();
+  const decision = await runInteractiveInstall(ctx, io);
+  if (decision === "abort") {
+    process.exit(0);
+  }
+  await executeMcpInstall({
+    mode: decision.mode,
+    rawScope: decision.scope,
+    installScope: decision.installScope,
+    vaultName: decision.vaultName,
+    vaultExplicit: decision.vaultExplicit,
+    pastedToken: decision.pastedToken,
+    existingEntryKey: decision.existingEntryKey,
+    globalConfig,
+  });
+}
+
+interface ExecuteMcpInstallOpts {
+  mode: "mint" | "token" | "legacy-pat";
+  /** Full scope string (e.g. "vault:read"). The verb segment narrows downstream. */
+  rawScope: string;
+  installScope: InstallScope;
+  vaultName: string;
+  /** Whether vault target was explicit (controls singular vs per-vault entry key). */
+  vaultExplicit: boolean;
+  /** Bearer the operator pasted in `--token` / interactive paste mode. */
+  pastedToken?: string;
+  /**
+   * When the interactive walkthrough is updating an existing entry, the
+   * walkthrough's preview pinned a specific key (e.g. `parachute-vault-work`
+   * because that's what was already there). Passing it through ensures the
+   * write lands at the same key the operator just confirmed. Absent for
+   * fresh installs and for the flag-driven path (which always synthesizes).
+   * See vault#293.
+   */
+  existingEntryKey?: string;
+  /** Reused across the call chain to avoid re-parsing config.yaml. */
+  globalConfig: ReturnType<typeof readGlobalConfig>;
+}
+
+/**
+ * Shared backend for both the flag-driven path and the interactive
+ * walkthrough. Acquires the bearer per mode, writes the entry, prints the
+ * result. The interactive path delays this call until *after* the
+ * preview-and-confirm step so a cancel skips the network mint entirely.
+ */
+async function executeMcpInstall(opts: ExecuteMcpInstallOpts): Promise<void> {
+  const { mode, rawScope, installScope, vaultName, vaultExplicit, pastedToken, globalConfig, existingEntryKey } = opts;
+  const verb = rawScope.split(":")[1]!;
+  const target = resolveInstallTarget(installScope);
+  // Single source of truth shared with the interactive walkthrough's
+  // preview — preview-shows-this-shape ⇒ this-shape-lands-on-disk. The
+  // helper closes both halves of the invariant (entryKey + url) — see
+  // vault#293 for the seam, vault#302 for closing the writer-side URL.
+  const { entryKey, url, source } = buildMcpEntryPlan({
+    vaultName,
+    vaultExplicit,
+    port: globalConfig.port || DEFAULT_PORT,
+    ...(existingEntryKey ? { existingEntryKey } : {}),
+  });
+
+  let bearer: string;
+  if (mode === "token") {
+    if (!pastedToken) {
+      console.error("Internal error: token mode missing pastedToken.");
+      process.exit(1);
+    }
+    bearer = pastedToken;
+    console.log(`Using supplied token (skipping mint).`);
+  } else if (mode === "legacy-pat") {
+    console.error(
+      "Note: --legacy-pat mints a vault-DB pvt_* token. The hub-issued JWT path (--mint, default) " +
+        "is the canonical install going forward; pvt_* support is preserved for self-hosted-without-hub " +
+        "setups, tracked at vault#288, planned removal 0.6.0.",
+    );
+    const store = getVaultStore(vaultName);
+    const { fullToken } = generateToken();
+    // Narrow the pvt_* to the requested verb's scope set when not full-admin.
+    // `scopes: undefined` leaves the token at full vault permissions
+    // (admin); narrowing to a single-scope array gates it to that verb.
+    const createTokenOpts: Parameters<typeof createToken>[2] = {
+      label: "mcp-install",
+      permission: verb === "read" ? "read" : "full",
+      vault_name: vaultName,
+    };
+    if (verb !== "admin") {
+      createTokenOpts.scopes = [rawScope];
+    }
+    createToken(store.db, fullToken, createTokenOpts);
+    bearer = fullToken;
+  } else {
+    // mode === "mint"
+    const operatorToken = readOperatorToken();
+    if (!operatorToken) {
+      console.error(
+        "No operator token found at ~/.parachute/operator.token. The default install path " +
+          "(--mint) requires a hub-issued operator token to mint scope-narrow JWTs.\n" +
+          "  Fix: run `parachute auth rotate-operator` to create one, then re-run.\n" +
+          "  Or:  use `--token <bearer>` to paste an existing token, or `--legacy-pat` to " +
+          "mint a vault-DB pvt_* token (self-hosted-without-hub).",
+      );
+      process.exit(1);
+    }
+    const port = globalConfig.port || DEFAULT_PORT;
+    const hub = chooseHubOrigin(port);
+    if (hub.source === "loopback") {
+      console.error(
+        "No hub origin configured (PARACHUTE_HUB_ORIGIN unset, no active expose-state). " +
+          "Hub-mint (--mint) needs a real hub URL to call. Either:\n" +
+          "  - Start the hub and set PARACHUTE_HUB_ORIGIN, OR\n" +
+          "  - Bring up an exposure (`parachute expose tailnet`), OR\n" +
+          "  - Use --legacy-pat to mint a vault-DB pvt_* token instead.",
+      );
+      process.exit(1);
+    }
+    const narrowScope = `vault:${vaultName}:${verb}`;
+    const result = await mintHubJwt({
+      hubOrigin: hub.url,
+      operatorToken,
+      scope: narrowScope,
+      subject: "parachute-vault-mcp",
+    });
+    if ("kind" in result) {
+      switch (result.kind) {
+        case "network":
+          console.error(
+            `Hub unreachable at ${result.origin} — ${result.cause}.\n` +
+              `  Fix: verify the hub is running and PARACHUTE_HUB_ORIGIN is set, ` +
+              `or use --legacy-pat to skip hub-mint.`,
+          );
+          break;
+        case "api-error":
+          console.error(
+            `Hub mint-token rejected (HTTP ${result.status}, ${result.error}): ${result.description}`,
+          );
+          break;
+      }
+      process.exit(1);
+    }
+    bearer = result.token;
+    console.log(`Minted hub JWT (jti=${result.jti}, expires ${result.expires_at}, scope ${result.scope}).`);
+  }
+
+  installMcpConfig({
+    targetPath: target.path,
+    entryKey,
+    url,
+    bearer,
+    ...(target.localProjectKey ? { localProjectKey: target.localProjectKey } : {}),
+  });
+  console.log(`MCP URL: ${url} (${source})`);
+  if (target.scope === "local") {
+    console.log(`Added MCP server "${entryKey}" to ${target.path} under projects["${target.localProjectKey}"] (local scope).`);
+    console.log(`  Installed locally for this directory only — runs only when Claude Code launches from ${target.localProjectKey}.`);
+    console.log(`  To install globally instead, re-run with --install-scope user.`);
+  } else {
+    console.log(`Added MCP server "${entryKey}" to ${target.path}`);
+  }
 }
 
 function cmdRemove(args: string[]) {
@@ -1364,6 +1731,16 @@ function printErrLogTail(n: number) {
 async function cmdUninstall(argsList: string[]) {
   const wipe = argsList.includes("--wipe");
   const skipPrompts = argsList.includes("--yes") || argsList.includes("-y");
+  // Test-isolation escape hatch (vault#296): skip the launchd / systemd /
+  // backup-agent uninstall calls. Those target hardcoded labels
+  // (`computer.parachute.vault*`) that ignore `PARACHUTE_HOME`, so a test
+  // run on a developer's machine would `launchctl bootout` their real
+  // daemon. With this flag tests can exercise the rest of the uninstall
+  // flow (wrapper removal, MCP cleanup, ordering, exit codes) safely.
+  // Intentionally not documented in `usage()` — humans should never need
+  // it; surfacing it would invite "I'll just skip the daemon step" misuse
+  // that leaves an orphaned daemon firing on a missing wrapper.
+  const skipDaemon = argsList.includes("--skip-daemon");
 
   console.log("Parachute Vault uninstall\n");
   console.log("This removes the daemon registration and wrapper script.");
@@ -1393,7 +1770,9 @@ async function cmdUninstall(argsList: string[]) {
   }
 
   // 1. Stop and remove the daemon registration.
-  if (process.platform === "darwin") {
+  if (skipDaemon) {
+    console.log("Skipping daemon removal (--skip-daemon).");
+  } else if (process.platform === "darwin") {
     console.log("Removing launchd agent...");
     await uninstallAgent();
     // Scheduled backup agent lives in a separate plist — uninstall it too,
@@ -1554,23 +1933,23 @@ async function cmdDoctor() {
     });
   }
 
-  // MCP entry in ~/.claude.json. Split into three separate checks so the
-  // user can see exactly which condition fails: "entry present", "port
-  // matches vault", "daemon reachable over MCP URL". A common failure is
-  // "entry exists but port is stale" after the user changed PORT without
-  // re-running `mcp-install`.
+  // MCP entry in ~/.claude.json or ./.mcp.json. Split into three separate
+  // checks so the user can see exactly which condition fails: "entry
+  // present", "port matches vault", "daemon reachable over MCP URL". A
+  // common failure is "entry exists but port is stale" after the user
+  // changed PORT without re-running `mcp-install`.
   const port = resolveVaultPort();
   const mcpEntry = readMcpEntry();
   if (!mcpEntry.found) {
     checks.push({
-      name: "MCP entry in ~/.claude.json",
+      name: "MCP entry in MCP client config",
       status: "warn",
       detail: mcpEntry.reason,
       fix: "Run `parachute-vault mcp-install` to register the vault with Claude.",
     });
   } else {
     checks.push({
-      name: "MCP entry in ~/.claude.json",
+      name: `MCP entry in ${mcpEntry.locationLabel}`,
       status: "pass",
       detail: mcpEntry.url,
     });
@@ -1734,57 +2113,92 @@ function resolveVaultPort(): number {
 
 type McpEntryLookup =
   | { found: false; reason: string }
-  | { found: true; url: string; port: number | null };
+  | { found: true; url: string; port: number | null; locationLabel: string };
 
 /**
- * Read `~/.claude.json` and return the shape of the `parachute-vault` MCP
- * entry if present. The entry is always an HTTP MCP pointing at the local
- * daemon — `{ type: "http", url: "http://127.0.0.1:<port>/vault/<name>/mcp" }`
- * — so we parse the URL's port for the port-match check.
+ * Read the parachute vault MCP entry from either `~/.claude.json` (user
+ * scope) or `./.mcp.json` (project scope), preferring user-level. Accepts
+ * the singular `parachute-vault` key or any per-vault `parachute-vault-<name>`
+ * key — multi-vault installs key per-vault. The entry is always an HTTP MCP
+ * pointing at the local daemon, so we parse the URL's port for the
+ * port-match check.
  *
- * Invariant: the check is NON-fatal. A missing ~/.claude.json is a warn,
- * not a fail: plenty of users install the vault first and wire it to
- * Claude later. We just make the "is it wired up?" state legible.
+ * Invariant: the check is NON-fatal. A missing entry is a warn, not a fail:
+ * plenty of users install the vault first and wire it to Claude later. We
+ * just make the "is it wired up?" state legible.
  */
 function readMcpEntry(): McpEntryLookup {
-  const claudeJsonPath = resolve(homedir(), ".claude.json");
-  if (!existsSync(claudeJsonPath)) {
-    return { found: false, reason: `${claudeJsonPath} does not exist` };
-  }
-  let config: any;
-  try {
-    config = JSON.parse(readFileSync(claudeJsonPath, "utf-8"));
-  } catch (err: any) {
-    return {
-      found: false,
-      reason: `${claudeJsonPath} is not valid JSON: ${String(err?.message ?? err)}`,
-    };
-  }
-  const entry = config?.mcpServers?.["parachute-vault"];
-  if (!entry) {
-    return {
-      found: false,
-      reason: `no mcpServers["parachute-vault"] entry in ${claudeJsonPath}`,
-    };
-  }
-  // The entry is always a URL-bearing HTTP MCP. Non-URL shapes are
-  // unexpected (Claude Code would ignore them anyway) but we surface the
-  // raw shape so the user can see what's there.
-  const url = typeof entry.url === "string" ? entry.url : null;
-  if (!url) {
-    return {
-      found: false,
-      reason: `mcpServers["parachute-vault"] has no \`url\` field (got ${JSON.stringify(entry).slice(0, 80)})`,
-    };
-  }
-  let entryPort: number | null = null;
-  try {
-    const parsed = new URL(url);
-    entryPort = parsed.port ? Number(parsed.port) : null;
-  } catch {
-    entryPort = null;
+  // Bun's process.cwd() already follows symlinks on macOS, so resolve()
+  // matches the key the install writer used; tests assert with
+  // fs.realpathSync to match the same shape.
+  const cwd = resolve(process.cwd());
+  // Two entries point at the same ~/.claude.json file but search different
+  // key namespaces — top-level `mcpServers` (user scope) vs
+  // `projects[<cwd>].mcpServers` (local scope). Intentional duplication: a
+  // single read can't satisfy both without restructuring the search loop,
+  // and the cost of reading the file twice is trivial against the doctor
+  // run's other work.
+  const candidates: Array<{ path: string; label: string; localProjectKey?: string }> = [
+    { path: resolve(homedir(), ".claude.json"), label: "~/.claude.json" },
+    { path: resolve(homedir(), ".claude.json"), label: `~/.claude.json (projects["${cwd}"])`, localProjectKey: cwd },
+    { path: resolve(cwd, ".mcp.json"), label: `${cwd}/.mcp.json` },
+  ];
+  const checkedReasons: string[] = [];
+  for (const { path, label, localProjectKey } of candidates) {
+    if (!existsSync(path)) {
+      checkedReasons.push(`${label} does not exist`);
+      continue;
+    }
+    let config: any;
+    try {
+      config = JSON.parse(readFileSync(path, "utf-8"));
+    } catch (err: any) {
+      checkedReasons.push(`${label} is not valid JSON: ${String(err?.message ?? err)}`);
+      continue;
+    }
+    const servers = localProjectKey
+      ? (config?.projects?.[localProjectKey]?.mcpServers ?? {})
+      : (config?.mcpServers ?? {});
+    // Prefer the singular `parachute-vault` slot (canonical default
+    // install); fall back to the first `parachute-vault-<name>` per-vault
+    // entry. Multi-vault installs may have several; the doctor reports on
+    // the one it finds first so the basic "is something wired up?" check
+    // still works without enumerating every vault.
+    let entry = servers["parachute-vault"];
+    let entryKey = "parachute-vault";
+    if (!entry) {
+      for (const key of Object.keys(servers)) {
+        if (key.startsWith("parachute-vault-")) {
+          entry = servers[key];
+          entryKey = key;
+          break;
+        }
+      }
+    }
+    if (!entry) {
+      checkedReasons.push(`no parachute-vault entry in ${label}`);
+      continue;
+    }
+    const url = typeof entry.url === "string" ? entry.url : null;
+    if (!url) {
+      checkedReasons.push(
+        `${label} mcpServers["${entryKey}"] has no \`url\` field (got ${JSON.stringify(entry).slice(0, 80)})`,
+      );
+      continue;
+    }
+    let entryPort: number | null = null;
+    try {
+      const parsed = new URL(url);
+      entryPort = parsed.port ? Number(parsed.port) : null;
+    } catch {
+      entryPort = null;
+    }
+    return { found: true, url, port: entryPort, locationLabel: `${label} (${entryKey})` };
   }
-  return { found: true, url, port: entryPort };
+  return {
+    found: false,
+    reason: checkedReasons.length > 0 ? checkedReasons.join("; ") : "no MCP config files found",
+  };
 }
 
 /**
@@ -2078,21 +2492,21 @@ function describeNextRun(schedule: BackupSchedule): string {
 
 async function cmdImport(args: string[]) {
   // Parse flags
-  let format = "obsidian";
   let vaultName = "default";
   let sourcePath = "";
   let dryRun = false;
+  let blowAway = false;
+  let assumeYes = false;
+  // `--format <name>` / `--obsidian` retained as no-op hints — autodetect
+  // now drives the format choice (presence of `.parachute/vault.yaml`).
+  // Surfaced in help text below; ignored at runtime to avoid surprising
+  // operators with stale flags.
 
   const positional: string[] = [];
   for (let i = 0; i < args.length; i++) {
     const arg = args[i]!;
     if (arg === "--format") {
-      const v = args[++i];
-      if (!v) {
-        console.error("--format requires a value.");
-        process.exit(1);
-      }
-      format = v;
+      i++; // consume the value; ignored.
     } else if (arg === "--vault") {
       const v = args[++i];
       if (!v) {
@@ -2103,7 +2517,11 @@ async function cmdImport(args: string[]) {
     } else if (arg === "--dry-run") {
       dryRun = true;
     } else if (arg === "--obsidian") {
-      format = "obsidian";
+      // no-op; autodetect.
+    } else if (arg === "--blow-away") {
+      blowAway = true;
+    } else if (arg === "--yes" || arg === "-y") {
+      assumeYes = true;
     } else {
       positional.push(arg);
     }
@@ -2111,15 +2529,21 @@ async function cmdImport(args: string[]) {
   sourcePath = positional[0] ?? "";
 
   if (!sourcePath) {
-    console.error("Usage: parachute-vault import <path> [--vault <name>] [--dry-run]");
-    console.error("\nImports an Obsidian vault into Parachute Vault.");
+    console.error("Usage: parachute-vault import <path> [--vault <name>] [--blow-away] [--yes] [--dry-run]");
+    console.error("\nImports a portable-md export OR a legacy Obsidian vault. Format is");
+    console.error("autodetected by the presence of `.parachute/vault.yaml` in the input dir.");
     console.error("\nOptions:");
     console.error("  --vault <name>   Target vault (default: 'default')");
-    console.error("  --dry-run        Show what would be imported without importing");
+    console.error("  --blow-away      DESTRUCTIVE: wipe the target vault first, then replay");
+    console.error("                   the import. Disaster-recovery path. Confirms unless");
+    console.error("                   `--yes` is set.");
+    console.error("  --yes, -y        Skip the destructive-action confirm prompt.");
+    console.error("  --dry-run        Show what would be imported without writing.");
     process.exit(1);
   }
 
   const { resolve: resolvePath } = await import("path");
+  const { join } = await import("path");
   const fullPath = resolvePath(sourcePath);
 
   if (!existsSync(fullPath)) {
@@ -2134,6 +2558,73 @@ async function cmdImport(args: string[]) {
     process.exit(1);
   }
 
+  // Autodetect: portable-md export → `.parachute/vault.yaml` present.
+  const isPortableMd = existsSync(join(fullPath, ".parachute", "vault.yaml"));
+
+  if (isPortableMd) {
+    // New lossless path. Supports --blow-away for disaster recovery.
+    const { importPortableVault } = await import("../core/src/portable-md.ts");
+    const { getVaultStore } = await import("./vault-store.ts");
+    const { assetsDir } = await import("./routes.ts");
+
+    if (blowAway && !assumeYes && !dryRun) {
+      // Confirm-prompt the destructive action. Default NO — every other
+      // destructive confirm in this CLI (uninstall's wipe, 2FA
+      // re-enrollment) defaults NO, so a distracted Enter-press can't
+      // wipe a vault. vault#319 fold F1.
+      const proceed = await confirm(
+        `\nDESTRUCTIVE: --blow-away will DELETE every note in vault "${vaultName}" before replaying from "${fullPath}". Proceed?`,
+        false,
+      );
+      if (!proceed) {
+        console.log("Cancelled.");
+        return;
+      }
+    }
+
+    const store = getVaultStore(vaultName);
+    console.log(
+      `Importing portable-md export from ${fullPath} into vault "${vaultName}"` +
+      `${blowAway ? " (BLOW-AWAY)" : ""}${dryRun ? " (dry-run)" : ""}`,
+    );
+    const stats = await importPortableVault(store, {
+      inDir: fullPath,
+      blowAway,
+      assetsDir: assetsDir(vaultName),
+      dryRun,
+    });
+
+    console.log(
+      `\n${dryRun ? "Would " : ""}created ${stats.notes_created} note(s), ` +
+      `updated ${stats.notes_updated}, ` +
+      `restored ${stats.schemas_restored} schema(s), ` +
+      `${stats.links_restored} link(s), ` +
+      `${stats.attachments_restored} attachment(s).`,
+    );
+    if (stats.notes_wiped > 0) {
+      console.log(`Blow-away: wiped ${stats.notes_wiped} pre-existing note(s).`);
+    }
+    if (stats.skipped_links.length > 0) {
+      console.log(`Skipped ${stats.skipped_links.length} link(s) — target notes not in import set.`);
+    }
+    if (stats.skipped_attachments.length > 0) {
+      console.log(`Skipped ${stats.skipped_attachments.length} attachment(s) — see warnings above.`);
+    }
+    return;
+  }
+
+  // Legacy obsidian-format path. No-op when --blow-away passed (this
+  // path is for "ingest an external Obsidian vault" not disaster
+  // recovery); explicit error so the operator doesn't get a surprising
+  // partial wipe.
+  if (blowAway) {
+    console.error(
+      "--blow-away requires a portable-md export (`.parachute/vault.yaml` present in the input dir). " +
+      "Legacy Obsidian imports don't support --blow-away — they always upsert by path.",
+    );
+    process.exit(1);
+  }
+
   const { parseObsidianVault } = await import("../core/src/obsidian.ts");
   const { getVaultStore } = await import("./vault-store.ts");
 
@@ -2205,6 +2696,7 @@ async function cmdImport(args: string[]) {
 async function cmdExport(args: string[]) {
   let vaultName = "default";
   let outputPath = "";
+  let since: string | undefined;
 
   const positional: string[] = [];
   for (let i = 0; i < args.length; i++) {
@@ -2216,6 +2708,21 @@ async function cmdExport(args: string[]) {
         process.exit(1);
       }
       vaultName = v;
+    } else if (arg === "--since") {
+      const v = args[++i];
+      if (!v) {
+        console.error("--since requires an ISO-8601 timestamp value.");
+        process.exit(1);
+      }
+      // Defensive: parse to verify it's a real ISO timestamp before we
+      // hand it to the store. Avoids silent "no matches" when the
+      // operator typo's the date and gets an empty export.
+      const parsed = Date.parse(v);
+      if (Number.isNaN(parsed)) {
+        console.error(`--since: invalid ISO-8601 timestamp '${v}'`);
+        process.exit(1);
+      }
+      since = v;
     } else {
       positional.push(arg);
     }
@@ -2223,14 +2730,17 @@ async function cmdExport(args: string[]) {
   outputPath = positional[0] ?? "";
 
   if (!outputPath) {
-    console.error("Usage: parachute-vault export <output-path> [--vault <name>]");
-    console.error("\nExports a Parachute Vault as Obsidian-compatible markdown files.");
+    console.error("Usage: parachute-vault export <dir> [--since <iso>] [--vault <name>]");
+    console.error("\nExports a Parachute Vault as portable markdown — round-trippable across");
+    console.error("Obsidian / Logseq / Foam / Quartz / Dendron and most markdown SSGs.");
+    console.error("\nOptions:");
+    console.error("  --vault <name>       Source vault (default: 'default')");
+    console.error("  --since <iso>        Only export notes whose updated_at >= ISO timestamp");
+    console.error("                       (incremental — useful for git-projection cadences)");
     process.exit(1);
   }
 
   const { resolve: resolvePath } = await import("path");
-  const { mkdirSync: mkdir, writeFileSync: writeFile } = await import("fs");
-  const { join, dirname } = await import("path");
   const fullPath = resolvePath(outputPath);
 
   const config = readVaultConfig(vaultName);
@@ -2239,28 +2749,32 @@ async function cmdExport(args: string[]) {
     process.exit(1);
   }
 
-  const { toObsidianMarkdown, exportFilePath } = await import("../core/src/obsidian.ts");
+  const { exportVaultToDir } = await import("../core/src/portable-md.ts");
   const { getVaultStore } = await import("./vault-store.ts");
+  const { assetsDir } = await import("./routes.ts");
 
   const store = getVaultStore(vaultName);
-  const notes = await store.queryNotes({ limit: 100000, sort: "asc" });
-
-  console.log(`Exporting ${notes.length} notes from vault "${vaultName}" to ${fullPath}`);
-  mkdir(fullPath, { recursive: true });
-
-  let exported = 0;
-  for (const note of notes) {
-    const filePath = exportFilePath(note);
-    const fullFilePath = join(fullPath, filePath);
-    const dir = dirname(fullFilePath);
-    mkdir(dir, { recursive: true });
+  const assetsDirPath = assetsDir(vaultName);
+  console.log(`Exporting vault "${vaultName}" to ${fullPath}${since ? ` (since ${since})` : ""}`);
+  const stats = await exportVaultToDir(store, {
+    outDir: fullPath,
+    vaultName,
+    assetsDir: assetsDirPath,
+    ...(config.description ? { vaultDescription: config.description } : {}),
+    ...(since ? { since } : {}),
+  });
 
-    const markdown = toObsidianMarkdown(note);
-    writeFile(fullFilePath, markdown);
-    exported++;
+  console.log(`Exported ${stats.notes} note(s), ${stats.schemas} tag schema(s), ${stats.attachments} attachment(s).`);
+  console.log(`Sidecar: ${fullPath}/.parachute/`);
+  if (stats.filtered_by_since) {
+    console.log(`Incremental: filtered by --since ${since}.`);
+  }
+  if (stats.skipped_traversal > 0) {
+    console.log(`Note: ${stats.skipped_traversal} note(s) skipped (path-traversal). See [export] warnings above.`);
+  }
+  if (stats.skipped_attachments.length > 0) {
+    console.log(`Note: ${stats.skipped_attachments.length} attachment(s) skipped. See [export] warnings above.`);
   }
-
-  console.log(`Exported ${exported} notes as markdown files.`);
 }
 
 // ---------------------------------------------------------------------------
@@ -2282,59 +2796,68 @@ function createVault(name: string): string {
   return fullToken;
 }
 
-function installMcpConfig(apiKey?: string) {
-  const claudeJsonPath = resolve(homedir(), ".claude.json");
+interface InstallMcpConfigOpts {
+  /** Absolute path to the MCP client config file. Computed by the caller via `resolveInstallTarget`. */
+  targetPath: string;
+  /** `mcpServers.<entryKey>` slot the entry lands at. Default is `parachute-vault`; multi-vault installs key as `parachute-vault-<name>`. */
+  entryKey: string;
+  /**
+   * URL embedded in the entry's `url` field. The caller is the sole source of
+   * truth — `buildMcpEntryPlan` produces both `entryKey` and `url` together,
+   * and passing them through closes the preview ⇄ writer invariant (the
+   * shape the preview promised is the shape that lands on disk). See
+   * vault#302; #301 introduced the seam for `entryKey`, this closes it for
+   * `url` too.
+   */
+  url: string;
+  /** Bearer token to embed in `Authorization: Bearer …`. Omitted means the entry is unauthenticated — only useful for OAuth-capable clients (Claude Code does discovery). */
+  bearer?: string;
+  /**
+   * When set, the entry is keyed under `projects[<localProjectKey>].mcpServers`
+   * inside `~/.claude.json` (Claude Code's `local` scope: private to this
+   * machine, scoped to this directory). When unset, keyed at top-level
+   * `mcpServers` (user scope) or written directly to `./.mcp.json`
+   * (project scope — caller passes the project file path).
+   */
+  localProjectKey?: string;
+}
+
+/**
+ * Write the MCP entry into the target config file. Pure file-writer — the
+ * caller has already decided `entryKey` and `url` (via `buildMcpEntryPlan`).
+ * Returns `void`; the caller already has `url` and `source` for logging.
+ */
+function installMcpConfig(opts: InstallMcpConfigOpts): void {
+  const { targetPath, entryKey, url, bearer, localProjectKey } = opts;
+
   let config: any = {};
-  if (existsSync(claudeJsonPath)) {
+  if (existsSync(targetPath)) {
     try {
-      config = JSON.parse(readFileSync(claudeJsonPath, "utf-8"));
+      config = JSON.parse(readFileSync(targetPath, "utf-8"));
     } catch {}
   }
 
-  if (!config.mcpServers) config.mcpServers = {};
-
-  const globalConfig = readGlobalConfig();
-  const port = globalConfig.port || DEFAULT_PORT;
-
-  // Clean up old per-vault stdio entries
-  for (const key of Object.keys(config.mcpServers)) {
-    if (key.startsWith("parachute-vault/")) {
-      delete config.mcpServers[key];
-    }
+  const mcpEntry: Record<string, unknown> = { type: "http", url };
+  if (bearer) {
+    mcpEntry.headers = { Authorization: `Bearer ${bearer}` };
   }
 
-  // Single HTTP MCP entry — use per-vault endpoint so pvt_ tokens work.
-  // Pick the URL that matches the OAuth issuer vault will advertise, in this
-  // order: explicit hub origin env > active tailnet/public exposure >
-  // loopback. Otherwise a strict MCP client (Claude Code) hits a loopback URL
-  // whose discovery issuer points at the hub and rejects on origin mismatch
-  // (RFC 8414).
-  const defaultVault = globalConfig.default_vault || "default";
-  const { url: mcpUrl, source } = chooseMcpUrl(defaultVault, port);
-  console.log(`MCP URL: ${mcpUrl} (${source})`);
-  const mcpEntry: Record<string, unknown> = { type: "http", url: mcpUrl };
-  if (apiKey) {
-    mcpEntry.headers = { Authorization: `Bearer ${apiKey}` };
+  if (localProjectKey) {
+    if (!config.projects || typeof config.projects !== "object") config.projects = {};
+    if (!config.projects[localProjectKey] || typeof config.projects[localProjectKey] !== "object") {
+      config.projects[localProjectKey] = {};
+    }
+    const projectEntry = config.projects[localProjectKey];
+    if (!projectEntry.mcpServers || typeof projectEntry.mcpServers !== "object") {
+      projectEntry.mcpServers = {};
+    }
+    projectEntry.mcpServers[entryKey] = mcpEntry;
+  } else {
+    if (!config.mcpServers) config.mcpServers = {};
+    config.mcpServers[entryKey] = mcpEntry;
   }
-  config.mcpServers["parachute-vault"] = mcpEntry;
 
-  writeFileSync(claudeJsonPath, JSON.stringify(config, null, 2) + "\n");
-}
-
-function removeMcpConfig() {
-  const claudeJsonPath = resolve(homedir(), ".claude.json");
-  if (!existsSync(claudeJsonPath)) return;
-  try {
-    const config = JSON.parse(readFileSync(claudeJsonPath, "utf-8"));
-    delete config.mcpServers?.["parachute-vault"];
-    // Also clean up any old per-vault entries
-    for (const key of Object.keys(config.mcpServers ?? {})) {
-      if (key.startsWith("parachute-vault/")) {
-        delete config.mcpServers[key];
-      }
-    }
-    writeFileSync(claudeJsonPath, JSON.stringify(config, null, 2) + "\n");
-  } catch {}
+  writeFileSync(targetPath, JSON.stringify(config, null, 2) + "\n");
 }
 
 function usage() {
@@ -2377,7 +2900,36 @@ Vaults:
   parachute-vault create <name> [--json]   Create a new vault (--json: emit { name, token, paths, set_as_default })
   parachute-vault list                     List all vaults
   parachute-vault remove <name> [--yes]    Remove a vault
-  parachute-vault mcp-install              Add vault MCP to Claude
+  parachute-vault mcp-install [--mint|--token <t>|--legacy-pat]
+                              [--scope vault:read|vault:write|vault:admin]
+                              [--install-scope local|user|project]
+                              [--vault <name>] [--client claude-code]
+                                            Install vault MCP into a client config.
+                                            From a terminal with no flags: walks you
+                                            through a contextual conversation (vault,
+                                            location, auth) with smart defaults +
+                                            preview before write. Pass any flag and
+                                            the command runs non-interactively.
+                                            Default (non-interactive): --mint
+                                            (hub-issued JWT via ~/.parachute/operator.token)
+                                            into ~/.claude.json under
+                                            projects[<cwd>].mcpServers (local scope,
+                                            matches Claude Code's claude-mcp-add
+                                            default) with vault:read scope.
+                                            --token <t>: paste an existing bearer
+                                            (any shape) instead of minting.
+                                            --legacy-pat: mint a vault-DB pvt_*
+                                            token (deprecated; for self-hosted-
+                                            without-hub setups).
+                                            --install-scope local (default) writes
+                                            ~/.claude.json under
+                                            projects[<cwd>].mcpServers (this
+                                            directory only). user writes top-level
+                                            mcpServers (every project). project
+                                            writes ./.mcp.json (check into the repo).
+                                            --vault <name> targets a specific
+                                            vault and keys the entry as
+                                            parachute-vault-<name>.
 
 Tokens:
   parachute-vault tokens                          List tokens (every vault)
@@ -2415,9 +2967,15 @@ Backup:
   parachute-vault backup status                 Show schedule, last run, destinations, next run
 
 Import/Export:
-  parachute-vault import <path>            Import an Obsidian vault
-  parachute-vault import <path> --dry-run  Preview import without writing
-  parachute-vault export <path>            Export vault as Obsidian markdown
+  parachute-vault import <path>                       Import portable-md export OR legacy
+                                                       Obsidian vault (autodetected by
+                                                       presence of .parachute/vault.yaml)
+  parachute-vault import <path> --blow-away           DESTRUCTIVE: wipe target vault, replay
+                                                       (disaster recovery; confirms)
+  parachute-vault import <path> --dry-run             Preview import without writing
+  parachute-vault export <dir>                        Export vault as portable markdown
+                                                       (Obsidian/Logseq/Foam/Quartz-compatible)
+  parachute-vault export <dir> --since <iso>          Incremental: only notes updated_at >= ISO
 
 ── Advanced / standalone ──────────────────────────────────────────────