@openparachute/vault 0.2.4 → 0.3.0

package/src/cli.ts

@@ -4,16 +4,16 @@
  * Parachute Vault CLI.
  *
  * Usage:
- *   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 remove <name>           — remove a vault
- *   parachute vault config                  — show all config
- *   parachute vault config set <key> <val>  — set a config value
- *   parachute vault config unset <key>      — remove a config value
- *   parachute vault serve                   — run the server (foreground)
- *   parachute vault status                  — show full status
+ *   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 remove <name>           — remove a vault
+ *   parachute-vault config                  — show all config
+ *   parachute-vault config set <key> <val>  — set a config value
+ *   parachute-vault config unset <key>      — remove a config value
+ *   parachute-vault serve                   — run the server (foreground)
+ *   parachute-vault status                  — show full status
  */
 
 import { resolve } from "path";
@@ -25,6 +25,7 @@ import { existsSync, readFileSync, writeFileSync, rmSync, mkdirSync } from "fs";
 import pkg from "../package.json" with { type: "json" };
 import {
   ensureConfigDirSync,
+  migrateFromLegacyLayout,
   readVaultConfig,
   writeVaultConfig,
   readGlobalConfig,
@@ -45,8 +46,9 @@ import {
   GLOBAL_CONFIG_PATH,
 } from "./config.ts";
 import type { VaultConfig } from "./config.ts";
-import { VAULTS_DIR } from "./config.ts";
+import { DATA_DIR } from "./config.ts";
 import { installAgent, uninstallAgent, isAgentLoaded, restartAgent } from "./launchd.ts";
+import { chooseMcpUrl } from "./mcp-install.ts";
 import {
   runBackup,
   readLastBackup,
@@ -77,7 +79,9 @@ import {
 import { confirm, ask, askPassword, choose } from "./prompt.ts";
 import { generateToken, createToken, listTokens, revokeToken, migrateVaultKeys } from "./token-store.ts";
 import type { TokenPermission } from "./token-store.ts";
+import { resolveCreateTokenFlags, VAULT_SCOPES } from "./scopes.ts";
 import { getVaultStore } from "./vault-store.ts";
+import { upsertService, ServicesManifestError } from "./services-manifest.ts";
 import {
   hasOwnerPassword,
   setOwnerPassword,
@@ -103,7 +107,7 @@ import {
 
 const args = process.argv.slice(2);
 
-// Support both `parachute vault <cmd>` and `parachute <cmd>` patterns
+// Support both `parachute-vault <cmd>` and `parachute <cmd>` patterns
 let command: string;
 let cmdArgs: string[];
 
@@ -119,9 +123,20 @@ if (args[0] === "vault") {
 // Commands
 // ---------------------------------------------------------------------------
 
+// Pre-0.3 installs kept vault state directly under ~/.parachute/. Run the
+// migration unconditionally so any command (including read-only ones like
+// `doctor` and `url`) picks up the relocated state on first post-upgrade run.
+// No-op when no legacy paths exist. Skipped for `help` and `version`, which
+// are expected to produce *only* their documented output — and because scripts
+// piping `parachute-vault --version` shouldn't get migration chatter on stderr.
+const SKIP_MIGRATION = new Set(["help", "--help", "-h", "version", "--version", "-v"]);
+if (!SKIP_MIGRATION.has(command)) {
+  migrateFromLegacyLayout();
+}
+
 switch (command) {
   case "init":
-    await cmdInit();
+    await cmdInit(cmdArgs);
     break;
   case "create":
     cmdCreate(cmdArgs);
@@ -188,7 +203,7 @@ switch (command) {
   case "--version":
   case "-v":
     // Intentionally minimal — just the version string on stdout. Scripts
-    // (and `parachute vault doctor` in a future check) rely on this being
+    // (and `parachute-vault doctor` in a future check) rely on this being
     // a bare-number line; anything else belongs in `vault status`.
     console.log(pkg.version);
     break;
@@ -202,9 +217,16 @@ switch (command) {
 // Command implementations
 // ---------------------------------------------------------------------------
 
-async function cmdInit() {
+async function cmdInit(args: string[] = []) {
   ensureConfigDirSync();
 
+  // Flags: --mcp installs MCP in ~/.claude.json without prompting;
+  // --no-mcp skips it without prompting. If both passed, --no-mcp wins
+  // (safer default). Neither → prompt in a TTY, default-yes in a
+  // non-TTY for back-compat with existing piped install scripts.
+  const flagMcpOn = args.includes("--mcp");
+  const flagMcpOff = args.includes("--no-mcp");
+
   const isMac = process.platform === "darwin";
   const isLinux = process.platform === "linux";
   const isFirstRun = !existsSync(ENV_PATH);
@@ -249,6 +271,32 @@ async function cmdInit() {
   }
   writeGlobalConfig(globalConfig);
 
+  // 2a. Register in the shared services manifest so the @openparachute/cli
+  // dispatcher can discover this service and its health endpoint. Upserts
+  // by name, preserving entries for other services. Non-fatal on failure —
+  // init can complete without the manifest, just with a warning.
+  //
+  // `paths[0]` is the canonical mount point — CLI uses it for the
+  // `.well-known/parachute.json` URL and for `parachute expose`. Advertise
+  // `/vault/<default_vault>` so MCP clients land at the scoped endpoint.
+  // When no default vault exists yet (multi-vault, no fallback), fall back
+  // to "/" — the CLI can detect and prompt.
+  const servicePath = globalConfig.default_vault
+    ? `/vault/${globalConfig.default_vault}`
+    : "/";
+  try {
+    upsertService({
+      name: "parachute-vault",
+      port: globalConfig.port || DEFAULT_PORT,
+      paths: [servicePath],
+      health: "/health",
+      version: pkg.version,
+    });
+  } catch (err) {
+    const msg = err instanceof ServicesManifestError ? err.message : String(err);
+    console.log(`  Warning: could not update ~/.parachute/services.json: ${msg}`);
+  }
+
   // 2b. Migrate existing legacy keys into per-vault token tables
   for (const v of listVaults()) {
     try {
@@ -297,13 +345,32 @@ async function cmdInit() {
   }
   if (serverPath) {
     console.log(`  Server path:  ${serverPath}`);
-    console.log(`  Wrapper:      ~/.parachute/start.sh`);
+    console.log(`  Wrapper:      ~/.parachute/vault/start.sh`);
   }
   console.log(`  Listening on http://0.0.0.0:${globalConfig.port || DEFAULT_PORT}`);
 
-  // 7. Install MCP for Claude Code (with token for auth)
-  installMcpConfig(apiKey);
-  console.log(`  MCP server added to ~/.claude.json`);
+  // 7. Install MCP for Claude Code (with token for auth) — user confirms
+  // unless --mcp / --no-mcp explicitly passed. Writing to ~/.claude.json
+  // is a side effect some users don't want; default-yes in a TTY since
+  // most users installing vault want Claude Code to see it, but ask.
+  let addMcp: boolean;
+  if (flagMcpOff) {
+    addMcp = false;
+  } else if (flagMcpOn) {
+    addMcp = true;
+  } else if (process.stdin.isTTY) {
+    addMcp = await confirm("Add Vault MCP to Claude Code (~/.claude.json)?", true);
+  } else {
+    addMcp = true; // non-interactive: preserve the installable-via-pipe default
+  }
+
+  if (addMcp) {
+    installMcpConfig(apiKey);
+    console.log(`  MCP server added to ~/.claude.json`);
+  } else {
+    console.log("  Skipped adding MCP to ~/.claude.json.");
+    console.log("  Run `parachute-vault mcp-install` later if you want it.");
+  }
 
   // 8. Summary
   console.log("\n---");
@@ -326,8 +393,8 @@ async function cmdInit() {
   }
 
   console.log(`\nNext steps:`);
-  console.log(`  parachute vault status            check everything is running`);
-  console.log(`  parachute vault config             view/edit configuration`);
+  console.log(`  parachute-vault status            check everything is running`);
+  console.log(`  parachute-vault config             view/edit configuration`);
 }
 
 async function promptForOwnerPassword(purpose: string): Promise<boolean> {
@@ -339,7 +406,7 @@ async function promptForOwnerPassword(purpose: string): Promise<boolean> {
   while (true) {
     const pw = await askPassword("  Password (or leave blank to skip)");
     if (!pw) {
-      console.log("  Skipped — you can set one later with `parachute vault set-password`.");
+      console.log("  Skipped — you can set one later with `parachute-vault set-password`.");
       return false;
     }
 
@@ -391,13 +458,13 @@ async function cmdSetPassword(args: string[]) {
 }
 
 // ---------------------------------------------------------------------------
-// 2FA — parachute vault 2fa [enroll | disable | backup-codes | status]
+// 2FA — parachute-vault 2fa [enroll | disable | backup-codes | status]
 // ---------------------------------------------------------------------------
 
 async function confirmOwnerPassword(purpose: string): Promise<boolean> {
   const hash = getOwnerPasswordHash();
   if (!hash) {
-    console.error("No owner password is set. Run: parachute vault set-password");
+    console.error("No owner password is set. Run: parachute-vault set-password");
     return false;
   }
   console.log(purpose);
@@ -460,14 +527,14 @@ async function cmd2fa(args: string[]) {
       console.log(`2FA: enabled (${getBackupCodeCount()} backup code(s) remaining)`);
     } else {
       console.log("2FA: not enabled");
-      console.log("  Enable with: parachute vault 2fa enroll");
+      console.log("  Enable with: parachute-vault 2fa enroll");
     }
     return;
   }
 
   if (sub === "enroll") {
     if (!hasOwnerPassword()) {
-      console.error("Set an owner password first: parachute vault set-password");
+      console.error("Set an owner password first: parachute-vault set-password");
       process.exit(1);
     }
     if (hasTotpEnrolled()) {
@@ -511,7 +578,7 @@ async function cmd2fa(args: string[]) {
       console.log(`  Incorrect code. (${2 - attempt} attempt(s) left)`);
     }
     if (!confirmed) {
-      console.error("Enrollment failed — rolling back. Re-run `parachute vault 2fa enroll` to try again.");
+      console.error("Enrollment failed — rolling back. Re-run `parachute-vault 2fa enroll` to try again.");
       disableTotp();
       process.exit(1);
     }
@@ -539,7 +606,7 @@ async function cmd2fa(args: string[]) {
 
   if (sub === "backup-codes") {
     if (!hasTotpEnrolled()) {
-      console.error("2FA is not enabled. Run: parachute vault 2fa enroll");
+      console.error("2FA is not enabled. Run: parachute-vault 2fa enroll");
       process.exit(1);
     }
     if (!(await confirmForTwoFactor("Confirm ownership to regenerate backup codes:"))) {
@@ -554,14 +621,14 @@ async function cmd2fa(args: string[]) {
   }
 
   console.error(`Unknown 2fa command: ${sub}`);
-  console.error("Usage: parachute vault 2fa [status | enroll | disable | backup-codes]");
+  console.error("Usage: parachute-vault 2fa [status | enroll | disable | backup-codes]");
   process.exit(1);
 }
 
 function cmdCreate(args: string[]) {
   const name = args[0];
   if (!name) {
-    console.error("Usage: parachute vault create <name>");
+    console.error("Usage: parachute-vault create <name>");
     process.exit(1);
   }
 
@@ -570,9 +637,9 @@ function cmdCreate(args: string[]) {
     process.exit(1);
   }
   if (name === "list") {
-    // Reserved — /vaults/list is the public discovery endpoint. Allowing a
-    // vault with this name would let its routes (/vaults/list/mcp, etc.) be
-    // shadowed by the discovery handler.
+    // Reserved — keeps the "list" vault name out of play even though per-vault
+    // routes now live under /vault/<name>/ and no longer collide with the
+    // /vaults/list discovery endpoint.
     console.error(`"list" is a reserved vault name.`);
     process.exit(1);
   }
@@ -610,13 +677,13 @@ function cmdCreate(args: string[]) {
     console.log(`  ${defaultNote}`);
   }
   console.log();
-  console.log(`To add MCP to Claude: parachute vault mcp-install ${name}`);
+  console.log(`To add MCP to Claude: parachute-vault mcp-install ${name}`);
 }
 
 function cmdList() {
   const vaults = listVaults();
   if (vaults.length === 0) {
-    console.log("No vaults. Run: parachute vault init");
+    console.log("No vaults. Run: parachute-vault init");
     return;
   }
 
@@ -637,7 +704,7 @@ function cmdMcpInstall(_args: string[]) {
 function cmdRemove(args: string[]) {
   const name = args[0];
   if (!name) {
-    console.error("Usage: parachute vault remove <name>");
+    console.error("Usage: parachute-vault remove <name>");
     process.exit(1);
   }
 
@@ -651,7 +718,7 @@ function cmdRemove(args: string[]) {
   if (!force) {
     console.log(`This will permanently delete vault "${name}" and all its data.`);
     console.log(`  Path: ${vaultDir(name)}`);
-    console.log(`\nTo confirm: parachute vault remove ${name} --yes`);
+    console.log(`\nTo confirm: parachute-vault remove ${name} --yes`);
     return;
   }
 
@@ -680,7 +747,7 @@ function cmdRemove(args: string[]) {
 async function cmdConfig(args: string[]) {
   const subcmd = args[0];
 
-  // parachute vault config — show current config
+  // parachute-vault config — show current config
   if (!subcmd) {
     loadEnvFile();
     const env = readEnvFile();
@@ -693,7 +760,7 @@ async function cmdConfig(args: string[]) {
     console.log();
 
     if (Object.keys(env).length === 0) {
-      console.log("  No env vars set. Use: parachute vault config set <key> <value>");
+      console.log("  No env vars set. Use: parachute-vault config set <key> <value>");
     } else {
       for (const [key, val] of Object.entries(env)) {
         // Mask sensitive values
@@ -707,46 +774,46 @@ async function cmdConfig(args: string[]) {
     return;
   }
 
-  // parachute vault config set <key> <value>
+  // parachute-vault config set <key> <value>
   if (subcmd === "set") {
     const key = args[1];
     const value = args.slice(2).join(" ");
     if (!key || !value) {
-      console.error("Usage: parachute vault config set <key> <value>");
+      console.error("Usage: parachute-vault config set <key> <value>");
       process.exit(1);
     }
     setEnvVar(key, value);
     console.log(`Set ${key}=${key.includes("KEY") ? value.slice(0, 8) + "..." : value}`);
-    console.log("Restart the daemon to apply: parachute vault restart");
+    console.log("Restart the daemon to apply: parachute-vault restart");
     return;
   }
 
-  // parachute vault config unset <key>
+  // parachute-vault config unset <key>
   if (subcmd === "unset") {
     const key = args[1];
     if (!key) {
-      console.error("Usage: parachute vault config unset <key>");
+      console.error("Usage: parachute-vault config unset <key>");
       process.exit(1);
     }
     unsetEnvVar(key);
     console.log(`Removed ${key}`);
-    console.log("Restart the daemon to apply: parachute vault restart");
+    console.log("Restart the daemon to apply: parachute-vault restart");
     return;
   }
 
   console.error(`Unknown config command: ${subcmd}`);
-  console.error("Usage: parachute vault config [set <key> <value> | unset <key>]");
+  console.error("Usage: parachute-vault config [set <key> <value> | unset <key>]");
   process.exit(1);
 }
 
 // ---------------------------------------------------------------------------
-// Tokens — parachute vault tokens [create | list | revoke]
+// Tokens — parachute-vault tokens [create | list | revoke]
 // ---------------------------------------------------------------------------
 
 function cmdTokens(args: string[]) {
   const subcmd = args[0];
 
-  // parachute vault tokens — list all tokens (across all vaults)
+  // parachute-vault tokens — list all tokens (across all vaults)
   if (!subcmd || subcmd === "list") {
     const vaults = listVaults();
     let anyTokens = false;
@@ -773,12 +840,13 @@ function cmdTokens(args: string[]) {
     }
 
     if (!anyTokens) {
-      console.log("No tokens found. Create one: parachute vault tokens create");
+      console.log("No tokens found. Create one: parachute-vault tokens create");
     }
     return;
   }
 
-  // parachute vault tokens create --vault <name> [--permission full|read]
+  // parachute-vault tokens create --vault <name>
+  //   [--scope vault:read,vault:write | --read | --permission full|read]
   //   [--expires <duration>] [--label <label>]
   if (subcmd === "create") {
     const vaultFlag = args.indexOf("--vault");
@@ -790,15 +858,17 @@ function cmdTokens(args: string[]) {
       process.exit(1);
     }
 
-    // --read shorthand or --permission full|read
-    const isReadShorthand = args.includes("--read");
-    const permFlag = args.indexOf("--permission");
-    const rawPerm = isReadShorthand ? "read" : (permFlag !== -1 ? args[permFlag + 1] : "full");
-    const permission: TokenPermission = rawPerm === "read" ? "read" : "full";
-    if (!["full", "read", "admin", "write"].includes(rawPerm)) {
-      console.error(`Invalid permission: ${rawPerm}. Must be full or read.`);
+    // Combining --scope / --read / --permission is always an error: a
+    // user minting a token expects exactly one narrowing signal, and
+    // silently picking one would mint the opposite of what the other
+    // reading intended. See resolveCreateTokenFlags.
+    const resolved = resolveCreateTokenFlags(args);
+    if (resolved.error) {
+      console.error(resolved.error);
       process.exit(1);
     }
+    const scopes = resolved.scopes;
+    const permission: TokenPermission = resolved.permission;
 
     const expiresFlag = args.indexOf("--expires");
     let expiresAt: string | null = null;
@@ -819,12 +889,15 @@ function cmdTokens(args: string[]) {
     createToken(store.db, fullToken, {
       label,
       permission,
+      scopes,
       expires_at: expiresAt,
     });
 
+    const displayScopes = scopes ?? [...VAULT_SCOPES];
     console.log(`Created token for vault "${vaultName}":`);
     console.log(`  Token:      ${fullToken}`);
     console.log(`  Permission: ${permission}`);
+    console.log(`  Scopes:     ${displayScopes.join(" ")}`);
     if (expiresAt) console.log(`  Expires:    ${expiresAt}`);
     console.log(`  Label:      ${label}`);
     console.log();
@@ -832,11 +905,11 @@ function cmdTokens(args: string[]) {
     return;
   }
 
-  // parachute vault tokens revoke <token-id> --vault <name>
+  // parachute-vault tokens revoke <token-id> --vault <name>
   if (subcmd === "revoke") {
     const tokenId = args[1];
     if (!tokenId) {
-      console.error("Usage: parachute vault tokens revoke <token-id> --vault <name>");
+      console.error("Usage: parachute-vault tokens revoke <token-id> --vault <name>");
       process.exit(1);
     }
 
@@ -860,7 +933,7 @@ function cmdTokens(args: string[]) {
   }
 
   console.error(`Unknown tokens command: ${subcmd}`);
-  console.error("Usage: parachute vault tokens [create | list | revoke <id>]");
+  console.error("Usage: parachute-vault tokens [create | list | revoke <id>]");
   process.exit(1);
 }
 
@@ -1029,7 +1102,7 @@ async function cmdUninstall(argsList: string[]) {
   if (wipe) {
     console.log("`--wipe` will ALSO remove vaults, .env, config.yaml, and daemon logs.\n");
   } else {
-    console.log("User data (~/.parachute/vaults, ~/.parachute/.env) is left alone.\n");
+    console.log("User data (~/.parachute/vault/) is left alone.\n");
   }
 
   // Scripted `--yes --wipe` bypasses both interactive confirms. That's the
@@ -1039,7 +1112,7 @@ async function cmdUninstall(argsList: string[]) {
   // miss this; interactive users already see the prompts.
   if (skipPrompts && wipe) {
     const ts = new Date().toISOString();
-    const targets = [VAULTS_DIR, ENV_PATH, GLOBAL_CONFIG_PATH, LOG_PATH, ERR_PATH].join(", ");
+    const targets = [DATA_DIR, ENV_PATH, GLOBAL_CONFIG_PATH, LOG_PATH, ERR_PATH].join(", ");
     console.log(`[${ts}] scripted destructive wipe: ${targets}`);
   }
 
@@ -1083,7 +1156,7 @@ async function cmdUninstall(argsList: string[]) {
     // Inventory what's actually on disk. Paths that don't exist are a
     // silent no-op on removal, but we also skip listing them so the
     // "would be removed" summary doesn't lie to the user.
-    const vaultsExist = existsSync(VAULTS_DIR);
+    const vaultsExist = existsSync(DATA_DIR);
     const envExists = existsSync(ENV_PATH);
     const configExists = existsSync(GLOBAL_CONFIG_PATH);
     const logExists = existsSync(LOG_PATH);
@@ -1094,7 +1167,7 @@ async function cmdUninstall(argsList: string[]) {
       console.log("No user data to remove.");
     } else {
       console.log("\nUser data that would be removed:");
-      if (vaultsExist) console.log(`  ${VAULTS_DIR} (SQLite vaults)`);
+      if (vaultsExist) console.log(`  ${DATA_DIR} (per-vault SQLite data)`);
       if (envExists) console.log(`  ${ENV_PATH} (.env config + secrets)`);
       if (configExists) console.log(`  ${GLOBAL_CONFIG_PATH} (global config)`);
       if (logExists) console.log(`  ${LOG_PATH} (daemon log)`);
@@ -1108,7 +1181,7 @@ async function cmdUninstall(argsList: string[]) {
         doWipe = await confirm("Delete this data? (cannot be undone)", false);
       }
       if (doWipe) {
-        if (vaultsExist) rmSync(VAULTS_DIR, { recursive: true, force: true });
+        if (vaultsExist) rmSync(DATA_DIR, { recursive: true, force: true });
         if (envExists) rmSync(ENV_PATH, { force: true });
         if (configExists) rmSync(GLOBAL_CONFIG_PATH, { force: true });
         if (logExists) rmSync(LOG_PATH, { force: true });
@@ -1120,7 +1193,7 @@ async function cmdUninstall(argsList: string[]) {
     }
   }
 
-  console.log("\nDone. To reinstall: `parachute vault init`.");
+  console.log("\nDone. To reinstall: `parachute-vault init`.");
 }
 
 interface DoctorCheck {
@@ -1139,7 +1212,7 @@ async function cmdDoctor() {
       name: "server-path pointer",
       status: "fail",
       detail: `missing: ${SERVER_PATH_FILE}`,
-      fix: "Run `parachute vault init` to create it.",
+      fix: "Run `parachute-vault init` to create it.",
     });
   } else {
     const pointed = readServerPathPointer();
@@ -1148,14 +1221,14 @@ async function cmdDoctor() {
         name: "server-path pointer",
         status: "fail",
         detail: `empty: ${SERVER_PATH_FILE}`,
-        fix: "Run `parachute vault init` to rewrite it.",
+        fix: "Run `parachute-vault init` to rewrite it.",
       });
     } else if (!existsSync(pointed)) {
       checks.push({
         name: "server.ts at pointer target",
         status: "fail",
         detail: `points to ${pointed}, which does not exist`,
-        fix: "Run `parachute vault init` from the current repo location.",
+        fix: "Run `parachute-vault init` from the current repo location.",
       });
     } else {
       checks.push({
@@ -1173,7 +1246,7 @@ async function cmdDoctor() {
       name: "wrapper script",
       status: "fail",
       detail: `missing: ${WRAPPER_PATH}`,
-      fix: "Run `parachute vault init`.",
+      fix: "Run `parachute-vault init`.",
     });
   } else {
     checks.push({ name: "wrapper script", status: "pass", detail: WRAPPER_PATH });
@@ -1186,7 +1259,7 @@ async function cmdDoctor() {
       name: "launchd agent",
       status: loaded ? "pass" : "warn",
       detail: loaded ? "loaded" : "not loaded",
-      fix: loaded ? undefined : "Run `parachute vault init` or `parachute vault restart`.",
+      fix: loaded ? undefined : "Run `parachute-vault init` or `parachute-vault restart`.",
     });
   } else if (isSystemdAvailable()) {
     const active = await isServiceActive();
@@ -1194,7 +1267,7 @@ async function cmdDoctor() {
       name: "systemd service",
       status: active ? "pass" : "warn",
       detail: active ? "active" : "not active",
-      fix: active ? undefined : "Run `parachute vault init` or `parachute vault restart`.",
+      fix: active ? undefined : "Run `parachute-vault init` or `parachute-vault restart`.",
     });
   }
 
@@ -1225,7 +1298,7 @@ async function cmdDoctor() {
       name: "MCP entry in ~/.claude.json",
       status: "warn",
       detail: mcpEntry.reason,
-      fix: "Run `parachute vault mcp-install` to register the vault with Claude.",
+      fix: "Run `parachute-vault mcp-install` to register the vault with Claude.",
     });
   } else {
     checks.push({
@@ -1248,7 +1321,7 @@ async function cmdDoctor() {
         name: "MCP URL port matches vault",
         status: "warn",
         detail: `MCP URL port ${mcpEntry.port ?? "(unparseable)"} ≠ vault port ${port}`,
-        fix: "Re-run `parachute vault mcp-install` to refresh the MCP URL.",
+        fix: "Re-run `parachute-vault mcp-install` to refresh the MCP URL.",
       });
     }
 
@@ -1268,7 +1341,7 @@ async function cmdDoctor() {
         name: "MCP URL reachable",
         status: "warn",
         detail: reach.detail,
-        fix: "Start the daemon: `parachute vault restart` (or `init` if not yet installed).",
+        fix: "Start the daemon: `parachute-vault restart` (or `init` if not yet installed).",
       });
     }
   }
@@ -1297,7 +1370,7 @@ async function cmdDoctor() {
         name: `port ${port} availability`,
         status: "warn",
         detail: `port in use by non-vault process: ${collision.detail}`,
-        fix: "Stop the conflicting process, or set a different PORT in ~/.parachute/.env and re-run `parachute vault init`.",
+        fix: "Stop the conflicting process, or set a different PORT in ~/.parachute/vault/.env and re-run `parachute-vault init`.",
       });
       break;
     case "unknown":
@@ -1319,7 +1392,7 @@ async function cmdDoctor() {
         name: "backup agent",
         status: loaded ? "pass" : "warn",
         detail: loaded ? `loaded (schedule: ${backupCfg.schedule})` : `not loaded (schedule: ${backupCfg.schedule})`,
-        fix: loaded ? undefined : `Re-run \`parachute vault backup --schedule ${backupCfg.schedule}\` to reinstall the agent.`,
+        fix: loaded ? undefined : `Re-run \`parachute-vault backup --schedule ${backupCfg.schedule}\` to reinstall the agent.`,
       });
     }
 
@@ -1332,7 +1405,7 @@ async function cmdDoctor() {
         name: "backup destinations",
         status: "warn",
         detail: "schedule is active but no destinations configured",
-        fix: "Edit ~/.parachute/config.yaml and add at least one destination under `backup.destinations`.",
+        fix: "Edit ~/.parachute/vault/config.yaml and add at least one destination under `backup.destinations`.",
       });
     } else {
       for (const dest of backupCfg.destinations) {
@@ -1341,7 +1414,7 @@ async function cmdDoctor() {
           name: `backup destination (${dest.kind})`,
           status: res.ok ? "pass" : "warn",
           detail: res.ok ? res.path : `${res.path}: ${res.error}`,
-          fix: res.ok ? undefined : "Ensure the path exists and is writable, or update it in ~/.parachute/config.yaml.",
+          fix: res.ok ? undefined : "Ensure the path exists and is writable, or update it in ~/.parachute/vault/config.yaml.",
         });
       }
     }
@@ -1361,12 +1434,12 @@ async function cmdDoctor() {
   const hasWarn = checks.some((c) => c.status === "warn");
   console.log();
   if (hasFailure) {
-    console.log("doctor: problems found (exit 1). See `parachute vault status` for runtime details.");
+    console.log("doctor: problems found (exit 1). See `parachute-vault status` for runtime details.");
     process.exit(1);
   } else if (hasWarn) {
-    console.log("doctor: warnings only. `parachute vault status` has live runtime detail.");
+    console.log("doctor: warnings only. `parachute-vault status` has live runtime detail.");
   } else {
-    console.log("doctor: all checks passed. For live runtime state: `parachute vault status`.");
+    console.log("doctor: all checks passed. For live runtime state: `parachute-vault status`.");
   }
 }
 
@@ -1377,7 +1450,7 @@ function cmdUrl() {
 
 /**
  * Resolve the vault's port the way `status`, `restart`, `url`, and `doctor`
- * all need to agree on: env override (~/.parachute/.env) wins, then
+ * all need to agree on: env override (~/.parachute/vault/.env) wins, then
  * config.yaml, then DEFAULT_PORT. Sources .env as a side effect so callers
  * running this before any env read still see PORT.
  */
@@ -1398,7 +1471,7 @@ type McpEntryLookup =
 /**
  * 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>/vaults/<name>/mcp" }`
+ * 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.
  *
  * Invariant: the check is NON-fatal. A missing ~/.claude.json is a warn,
@@ -1573,7 +1646,7 @@ async function describeProcess(pid: number): Promise<string | null> {
 }
 
 // ---------------------------------------------------------------------------
-// Backup — parachute vault backup [--schedule <freq> | status]
+// Backup — parachute-vault backup [--schedule <freq> | status]
 // ---------------------------------------------------------------------------
 
 async function cmdBackup(args: string[]) {
@@ -1588,7 +1661,7 @@ async function cmdBackup(args: string[]) {
   if (schedFlag !== -1) {
     const raw = args[schedFlag + 1];
     if (!raw) {
-      console.error("Usage: parachute vault backup --schedule <hourly|daily|weekly|manual>");
+      console.error("Usage: parachute-vault backup --schedule <hourly|daily|weekly|manual>");
       process.exit(1);
     }
     if (raw !== "hourly" && raw !== "daily" && raw !== "weekly" && raw !== "manual") {
@@ -1606,7 +1679,7 @@ async function cmdBackup(args: string[]) {
 async function cmdBackupRun() {
   const cfg = readGlobalConfig().backup ?? defaultBackupConfig();
   if (cfg.destinations.length === 0) {
-    console.error("No backup destinations configured. Edit ~/.parachute/config.yaml:");
+    console.error("No backup destinations configured. Edit ~/.parachute/vault/config.yaml:");
     console.error("  backup:");
     console.error("    destinations:");
     console.error("      - kind: local");
@@ -1648,7 +1721,7 @@ async function cmdBackupSchedule(schedule: BackupSchedule) {
   if (schedule === "manual") {
     await uninstallBackupAgent();
     console.log("Schedule: manual — backup agent removed.");
-    console.log("Run `parachute vault backup` to trigger a backup on demand.");
+    console.log("Run `parachute-vault backup` to trigger a backup on demand.");
     return;
   }
 
@@ -1656,7 +1729,7 @@ async function cmdBackupSchedule(schedule: BackupSchedule) {
     console.log(`Schedule set to: ${schedule}`);
     console.log();
     console.log("WARNING: no destinations configured — scheduled runs will fail.");
-    console.log("Edit ~/.parachute/config.yaml and add at least one destination under `backup.destinations`.");
+    console.log("Edit ~/.parachute/vault/config.yaml and add at least one destination under `backup.destinations`.");
   }
 
   await installBackupAgent(schedule);
@@ -1759,7 +1832,7 @@ async function cmdImport(args: string[]) {
   sourcePath = positional[0] ?? "";
 
   if (!sourcePath) {
-    console.error("Usage: parachute vault import <path> [--vault <name>] [--dry-run]");
+    console.error("Usage: parachute-vault import <path> [--vault <name>] [--dry-run]");
     console.error("\nImports an Obsidian vault into Parachute Vault.");
     console.error("\nOptions:");
     console.error("  --vault <name>   Target vault (default: 'default')");
@@ -1778,7 +1851,7 @@ async function cmdImport(args: string[]) {
   // Verify vault exists
   const config = readVaultConfig(vaultName);
   if (!config) {
-    console.error(`Vault "${vaultName}" not found. Run: parachute vault create ${vaultName}`);
+    console.error(`Vault "${vaultName}" not found. Run: parachute-vault create ${vaultName}`);
     process.exit(1);
   }
 
@@ -1865,7 +1938,7 @@ async function cmdExport(args: string[]) {
   outputPath = positional[0] ?? "";
 
   if (!outputPath) {
-    console.error("Usage: parachute vault export <output-path> [--vault <name>]");
+    console.error("Usage: parachute-vault export <output-path> [--vault <name>]");
     console.error("\nExports a Parachute Vault as Obsidian-compatible markdown files.");
     process.exit(1);
   }
@@ -1945,12 +2018,16 @@ function installMcpConfig(apiKey?: string) {
     }
   }
 
-  // Single HTTP MCP entry — use per-vault endpoint so pvt_ tokens work
+  // 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 mcpEntry: Record<string, unknown> = {
-    type: "http",
-    url: `http://127.0.0.1:${port}/vaults/${defaultVault}/mcp`,
-  };
+  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}` };
   }
@@ -1979,58 +2056,76 @@ function usage() {
   console.log(`
 Parachute Vault — self-hosted knowledge graph
 
+If you installed via the Parachute CLI, prefer the wrapper commands for
+lifecycle — \`parachute start vault\`, \`parachute stop vault\`,
+\`parachute status\` — and use the vault-direct commands below for setup,
+data, and debugging.
+
+── Standard use ───────────────────────────────────────────────────────
+
 Setup:
-  parachute vault init                     Set up everything (one command, idempotent)
-  parachute vault status                   Check what's running
-  parachute vault doctor                   Diagnose install/config issues
-  parachute vault uninstall [--wipe] [--yes]
+  parachute-vault init [--mcp | --no-mcp]  Set up everything (one command, idempotent)
+  parachute-vault doctor                   Diagnose install/config issues
+  parachute-vault uninstall [--wipe] [--yes]
                                            Remove daemon + MCP entry; --wipe also removes vaults, .env,
                                            config.yaml, and daemon logs (vault.log, vault.err).
                                            --yes skips prompts (DANGEROUS with --wipe: no confirmation).
-  parachute vault url                      Print the local server URL (for scripts)
+  parachute-vault url                      Print the local server URL (for scripts)
   parachute --version                      Print the installed version (alias: -v, version)
 
 Vaults:
-  parachute vault create <name>            Create a new vault
-  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 create <name>            Create a new vault
+  parachute-vault list                     List all vaults
+  parachute-vault remove <name> [--yes]    Remove a vault
+  parachute-vault mcp-install              Add vault MCP to Claude
 
 Tokens:
-  parachute vault tokens                          List all tokens
-  parachute vault tokens create                   Create a full-access token in the default vault
-  parachute vault tokens create --vault <name>    Create a token in a specific vault
-  parachute vault tokens create --read            Read-only token
-  parachute vault tokens create --label x         Set a label
-  parachute vault tokens create --expires 30d     Expiring token
-  parachute vault tokens revoke <token-id>        Revoke a token (default vault)
+  parachute-vault tokens                          List all tokens
+  parachute-vault tokens create                   Create a full-access token in the default vault
+  parachute-vault tokens create --vault <name>    Create a token in a specific vault
+  parachute-vault tokens create --read            Read-only token (shorthand for --scope vault:read)
+  parachute-vault tokens create --scope vault:write
+                                                  Narrow the token's scopes. Accepts a comma-separated
+                                                  list or repeated --scope flags. Valid scopes:
+                                                  vault:read, vault:write, vault:admin.
+  parachute-vault tokens create --label x         Set a label
+  parachute-vault tokens create --expires 30d     Expiring token
+  parachute-vault tokens revoke <token-id>        Revoke a token (default vault)
 
 OAuth:
-  parachute vault set-password             Set/change the owner password (for consent page)
-  parachute vault set-password --clear     Remove the owner password
-  parachute vault 2fa status               Show 2FA state
-  parachute vault 2fa enroll               Enable TOTP 2FA (QR + backup codes)
-  parachute vault 2fa disable              Disable 2FA (requires password)
-  parachute vault 2fa backup-codes         Regenerate backup codes
+  parachute-vault set-password             Set/change the owner password (for consent page)
+  parachute-vault set-password --clear     Remove the owner password
+  parachute-vault 2fa status               Show 2FA state
+  parachute-vault 2fa enroll               Enable TOTP 2FA (QR + backup codes)
+  parachute-vault 2fa disable              Disable 2FA (requires password)
+  parachute-vault 2fa backup-codes         Regenerate backup codes
 
 Config:
-  parachute vault config                   Show current configuration
-  parachute vault config set <key> <val>   Set a config value
-  parachute vault config unset <key>       Remove a config value
+  parachute-vault config                   Show current configuration
+  parachute-vault config set <key> <val>   Set a config value
+  parachute-vault config unset <key>       Remove a config value
 
 Backup:
-  parachute vault backup                        One-shot backup to configured destinations
-  parachute vault backup --schedule <freq>      hourly | daily | weekly | manual (macOS launchd)
-  parachute vault backup status                 Show schedule, last run, destinations, next run
+  parachute-vault backup                        One-shot backup to configured destinations
+  parachute-vault backup --schedule <freq>      hourly | daily | weekly | manual (macOS launchd)
+  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
-
-Server:
-  parachute vault serve                    Run server (foreground)
-  parachute vault logs                     Stream server logs
-  parachute vault restart                  Restart the daemon
+  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
+
+── Advanced / standalone ──────────────────────────────────────────────
+
+Direct daemon controls. For normal use, prefer the Parachute CLI wrappers
+— they add PID tracking, log rotation, and cross-service \`parachute status\`
+visibility. Use these when running vault without the CLI or when debugging.
+
+  parachute-vault serve                    Run server in the foreground (no PID tracking).
+                                           Prefer \`parachute start vault\` for managed lifecycle.
+  parachute-vault status                   Vault-only daemon status.
+                                           Prefer \`parachute status\` for a cross-service view.
+  parachute-vault logs                     Stream server logs
+  parachute-vault restart                  Restart the daemon
 `);
 }