@openparachute/vault 0.2.4 → 0.3.0-rc.1

package/src/config.ts

@@ -2,25 +2,41 @@
  * Configuration management for Parachute Vault.
  *
  * Directory layout:
- *   ~/.parachute/
- *     config.yaml          — global server config
- *     vault.log / vault.err — daemon logs
- *     vaults/
- *       {name}/
- *         vault.db          — SQLite database
- *         vault.yaml        — per-vault config (description, tool_hints, api_keys)
+ *   ~/.parachute/                 — ecosystem root (shared with sibling services)
+ *     services.json               — CLI-owned manifest (services-manifest.ts)
+ *     well-known/                 — CLI-owned (.well-known serving)
+ *     vault/                      — everything vault owns
+ *       .env
+ *       config.yaml               — global server config
+ *       start.sh / server-path    — daemon wrapper + pointer (daemon.ts)
+ *       logs/
+ *         vault.log / vault.err   — daemon stdout/stderr (matches
+ *                                   `~/.parachute/<svc>/logs/<svc>.log` — the
+ *                                   CLI lifecycle convention from PR #83)
+ *       data/                     — per-vault SQLite data (Postgres-style:
+ *                                   named `data/` rather than `vaults/` so it
+ *                                   doesn't read as doubled)
+ *         {name}/
+ *           vault.db              — SQLite database
+ *           vault.yaml            — per-vault config (description, api_keys, …)
+ *           assets/               — per-vault attachments
+ *
+ * Pre-0.3 installs put vault state directly under `~/.parachute/`; on startup
+ * we auto-migrate those paths into `vault/` (see `migrateFromLegacyLayout`).
+ * Pre-filesystem-hygiene 0.3 installs put per-vault state under
+ * `vault/vaults/` and daemon logs flat in `vault/`; those are moved into
+ * `data/` and `logs/` by `migrateVaultInternalLayout` on startup.
  */
 
 import { homedir } from "os";
 import { join } from "path";
-import { mkdir, readFile, writeFile } from "fs/promises";
-import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync } from "fs";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, renameSync } from "fs";
 import crypto from "node:crypto";
 
 // ---------------------------------------------------------------------------
 // Paths
 //
-// Historical note: the exported `CONFIG_DIR`, `VAULTS_DIR`, etc. used to be
+// Historical note: the exported `CONFIG_DIR`, `DATA_DIR`, etc. used to be
 // `const` captured at module load. That made tests flaky: anything setting
 // `process.env.PARACHUTE_HOME` after import would be ignored, and when `bun
 // test` shares one process across files, whichever test loaded first froze
@@ -28,35 +44,50 @@ import crypto from "node:crypto";
 // getters so `PARACHUTE_HOME` is re-read per call. The top-level constants
 // are kept for backward-compat (other modules import them) and reflect the
 // value at load time.
+//
+// `configDirPath()` is the ecosystem root — shared with sibling services
+// (channel, scribe, …) and with the CLI's `services.json` + `well-known/`.
+// `vaultHomePath()` is the vault-scoped subdir; all vault-owned files live
+// under it.
 // ---------------------------------------------------------------------------
 
 function configDirPath(): string {
   return process.env.PARACHUTE_HOME ?? join(homedir(), ".parachute");
 }
 
-function vaultsDirPath(): string {
-  return join(configDirPath(), "vaults");
+function vaultHomePath(): string {
+  return join(configDirPath(), "vault");
+}
+
+function dataDirPath(): string {
+  return join(vaultHomePath(), "data");
+}
+
+function logsDirPath(): string {
+  return join(vaultHomePath(), "logs");
 }
 
 function globalConfigPath(): string {
-  return join(configDirPath(), "config.yaml");
+  return join(vaultHomePath(), "config.yaml");
 }
 
 function envFilePath(): string {
-  return join(configDirPath(), ".env");
+  return join(vaultHomePath(), ".env");
 }
 
 export const CONFIG_DIR = configDirPath();
-export const VAULTS_DIR = join(CONFIG_DIR, "vaults");
-export const GLOBAL_CONFIG_PATH = join(CONFIG_DIR, "config.yaml");
-export const ENV_PATH = join(CONFIG_DIR, ".env");
-export const LOG_PATH = join(CONFIG_DIR, "vault.log");
-export const ERR_PATH = join(CONFIG_DIR, "vault.err");
+export const VAULT_HOME = join(CONFIG_DIR, "vault");
+export const DATA_DIR = join(VAULT_HOME, "data");
+export const LOGS_DIR = join(VAULT_HOME, "logs");
+export const GLOBAL_CONFIG_PATH = join(VAULT_HOME, "config.yaml");
+export const ENV_PATH = join(VAULT_HOME, ".env");
+export const LOG_PATH = join(LOGS_DIR, "vault.log");
+export const ERR_PATH = join(LOGS_DIR, "vault.err");
 export const DEFAULT_PORT = 1940;
-export const ASSETS_DIR = join(CONFIG_DIR, "assets");
+export const ASSETS_DIR = join(VAULT_HOME, "assets");
 
 export function vaultDir(name: string): string {
-  return join(vaultsDirPath(), name);
+  return join(dataDirPath(), name);
 }
 
 export function vaultDbPath(name: string): string {
@@ -101,6 +132,29 @@ export interface VaultConfig {
   tag_schemas?: Record<string, TagSchema>;
   /** Tag name that marks a note as publicly viewable. Default: "published". */
   published_tag?: string;
+  /**
+   * What to do with the audio file on disk once the worker is done with it.
+   * - `"keep"` (default): leave the file on disk.
+   * - `"until_transcribed"`: unlink once the transcript lands successfully;
+   *   on failure the file is kept so the user can retry or re-upload.
+   * - `"never"`: unlink whenever the worker reaches a terminal state
+   *   (`done` OR `failed`). Audio is discarded even if transcription
+   *   failed — users who opt in accept that losing a bad transcription
+   *   also loses the source audio.
+   *
+   * In every mode the attachment row (including any stored transcript) is
+   * preserved; only the file on disk is affected.
+   */
+  audio_retention?: "keep" | "until_transcribed" | "never";
+  /**
+   * Transcription worker settings for this vault. Today only `context` is
+   * honored — a list of context predicates the worker attaches to each
+   * transcription POST so scribe sees person/project context alongside the
+   * audio. Same shape as triggers' `action.include_context`.
+   */
+  transcription?: {
+    context?: TriggerIncludeContext[];
+  };
 }
 
 // ---------------------------------------------------------------------------
@@ -131,6 +185,20 @@ export interface TriggerWhen {
  */
 export type TriggerSendMode = "json" | "attachment" | "content";
 
+/**
+ * A single `include_context` entry — a query over the vault whose matching
+ * notes are serialized as context entries and included alongside the primary
+ * webhook payload. See `src/context.ts` for the fetch + serialization rules.
+ */
+export interface TriggerIncludeContext {
+  /** Tag the note must carry. Required. */
+  tag: string;
+  /** If set, notes also carrying this tag are excluded. */
+  exclude_tag?: string;
+  /** Metadata keys to surface on each resulting entry. */
+  include_metadata?: string[];
+}
+
 export interface TriggerAction {
   /** URL to POST the webhook payload to. */
   webhook: string;
@@ -138,6 +206,12 @@ export interface TriggerAction {
   timeout?: number;
   /** How to send data to the webhook. Default "json". */
   send?: TriggerSendMode;
+  /**
+   * If present, the trigger pre-fetches the matching vault notes at fire
+   * time and attaches them as a `context` JSON part (send=attachment) or a
+   * top-level `context` field (send=json). send=content ignores this.
+   */
+  include_context?: TriggerIncludeContext[];
 }
 
 export interface TriggerConfig {
@@ -265,6 +339,23 @@ function serializeVaultConfig(config: VaultConfig): string {
   if (config.published_tag) {
     lines.push(`published_tag: ${config.published_tag}`);
   }
+  if (config.audio_retention) {
+    lines.push(`audio_retention: ${config.audio_retention}`);
+  }
+
+  if (config.transcription?.context?.length) {
+    lines.push("transcription:");
+    lines.push("  context:");
+    for (const entry of config.transcription.context) {
+      lines.push(`    - tag: ${entry.tag}`);
+      if (entry.exclude_tag) {
+        lines.push(`      exclude_tag: ${entry.exclude_tag}`);
+      }
+      if (entry.include_metadata?.length) {
+        lines.push(`      include_metadata: [${entry.include_metadata.map((v) => `"${v}"`).join(", ")}]`);
+      }
+    }
+  }
 
   lines.push("api_keys:");
   for (const key of config.api_keys) {
@@ -320,6 +411,12 @@ function parseVaultConfig(yaml: string, name: string): VaultConfig {
   const pubTagMatch = yaml.match(/^published_tag:\s*(\S+)/m);
   if (pubTagMatch) config.published_tag = pubTagMatch[1];
 
+  const retentionMatch = yaml.match(/^audio_retention:\s*(\S+)/m);
+  if (retentionMatch) {
+    const v = retentionMatch[1];
+    if (v === "keep" || v === "until_transcribed" || v === "never") config.audio_retention = v;
+  }
+
   // Parse description (block scalar)
   const descMatch = yaml.match(/^description:\s*\|\s*\n((?:\s{2}.+\n?)+)/m);
   if (descMatch) {
@@ -358,9 +455,64 @@ function parseVaultConfig(yaml: string, name: string): VaultConfig {
   // Parse tag_schemas
   config.tag_schemas = parseTagSchemas(yaml);
 
+  // Parse transcription.context (same shape as triggers' include_context)
+  const transcriptionContext = parseTranscriptionContext(yaml);
+  if (transcriptionContext) {
+    config.transcription = { context: transcriptionContext };
+  }
+
   return config;
 }
 
+/**
+ * Parse the `transcription: { context: [...] }` section from vault.yaml.
+ * Shape matches triggers' `action.include_context` so callers can reuse the
+ * same `ContextPredicate` helpers from src/context.ts.
+ */
+function parseTranscriptionContext(yaml: string): TriggerIncludeContext[] | undefined {
+  const startMatch = yaml.match(/^transcription:\s*$/m);
+  if (!startMatch) return undefined;
+
+  const startIdx = (startMatch.index ?? 0) + startMatch[0].length;
+  const lines = yaml.slice(startIdx).split("\n");
+
+  const entries: TriggerIncludeContext[] = [];
+  let inContext = false;
+  let current: TriggerIncludeContext | null = null;
+
+  const pushCurrent = () => {
+    if (current && current.tag) entries.push(current);
+    current = null;
+  };
+
+  for (const line of lines) {
+    // Stop at next top-level key.
+    if (line.match(/^\S/) && line.trim().length > 0) break;
+    if (line.trim().length === 0) continue;
+
+    const trimmed = line.trim();
+
+    if (trimmed === "context:") { inContext = true; continue; }
+    if (!inContext) continue;
+
+    const itemStart = trimmed.match(/^-\s+(\w+):\s*(.*)$/);
+    if (itemStart) {
+      pushCurrent();
+      current = { tag: "" };
+      applyContextField(current, itemStart[1], itemStart[2]);
+      continue;
+    }
+    const fieldMatch = trimmed.match(/^(\w+):\s*(.*)$/);
+    if (fieldMatch && current) {
+      applyContextField(current, fieldMatch[1], fieldMatch[2]);
+      continue;
+    }
+  }
+
+  pushCurrent();
+  return entries.length > 0 ? entries : undefined;
+}
+
 /**
  * Parse the tag_schemas section from vault.yaml.
  * Uses line-by-line indent tracking since the main parser is hand-rolled.
@@ -444,6 +596,25 @@ function parseYamlList(val: string): string[] {
   return inner.split(",").map((s) => s.trim().replace(/^"(.*)"$/, "$1")).filter(Boolean);
 }
 
+/**
+ * Apply a single "key: value" line to the include_context item being built.
+ * Shared between triggers and vault-config transcription.context (same shape).
+ */
+function applyContextField(
+  item: TriggerIncludeContext,
+  key: string,
+  raw: string,
+): void {
+  const value = raw.trim();
+  if (key === "tag") { item.tag = value.replace(/^"(.*)"$/, "$1"); return; }
+  if (key === "exclude_tag") { item.exclude_tag = value.replace(/^"(.*)"$/, "$1"); return; }
+  if (key === "include_metadata") {
+    const listMatch = value.match(/^\[([^\]]*)\]/);
+    if (listMatch) item.include_metadata = parseYamlList(listMatch[1]);
+    return;
+  }
+}
+
 function parseTriggers(yaml: string): TriggerConfig[] | undefined {
   const startMatch = yaml.match(/^triggers:\s*$/m);
   if (!startMatch) return undefined;
@@ -454,7 +625,17 @@ function parseTriggers(yaml: string): TriggerConfig[] | undefined {
   const triggers: TriggerConfig[] = [];
   let current: Partial<TriggerConfig> | null = null;
   // Track which section we're in by the last seen section header
-  let section: "top" | "when" | "action" = "top";
+  let section: "top" | "when" | "action" | "include_context" = "top";
+  // When inside include_context, track the item currently being parsed.
+  let currentContext: TriggerIncludeContext | null = null;
+
+  const pushContextItem = () => {
+    if (currentContext && current?.action) {
+      current.action.include_context = current.action.include_context ?? [];
+      current.action.include_context.push(currentContext);
+    }
+    currentContext = null;
+  };
 
   for (const line of lines) {
     // Stop at next top-level key
@@ -466,6 +647,7 @@ function parseTriggers(yaml: string): TriggerConfig[] | undefined {
     // New trigger item: "- name: ..."
     const nameMatch = trimmed.match(/^-\s+name:\s*(.+)/);
     if (nameMatch) {
+      pushContextItem();
       if (current?.name) {
         if (current.action?.webhook) {
           triggers.push(current as TriggerConfig);
@@ -481,8 +663,16 @@ function parseTriggers(yaml: string): TriggerConfig[] | undefined {
     if (!current) continue;
 
     // Section headers — detect by key name regardless of indent
-    if (trimmed === "when:") { section = "when"; continue; }
-    if (trimmed === "action:") { section = "action"; continue; }
+    if (trimmed === "when:") { pushContextItem(); section = "when"; continue; }
+    if (trimmed === "action:") { pushContextItem(); section = "action"; continue; }
+    if (trimmed === "include_context:") {
+      // Entering the nested list under action:.
+      if (!current.action) current.action = { webhook: "" } as TriggerAction;
+      current.action.include_context = current.action.include_context ?? [];
+      section = "include_context";
+      currentContext = null;
+      continue;
+    }
 
     // Top-level trigger field
     const eventsMatch = trimmed.match(/^events:\s*\[([^\]]*)\]/);
@@ -521,8 +711,27 @@ function parseTriggers(yaml: string): TriggerConfig[] | undefined {
         continue;
       }
     }
+
+    // include_context list items: "- tag: X" starts a new item; subsequent
+    // indented lines set fields on it.
+    if (section === "include_context") {
+      const itemStart = trimmed.match(/^-\s+(\w+):\s*(.*)$/);
+      if (itemStart) {
+        pushContextItem();
+        currentContext = { tag: "" };
+        applyContextField(currentContext, itemStart[1], itemStart[2]);
+        continue;
+      }
+      const fieldMatch = trimmed.match(/^(\w+):\s*(.*)$/);
+      if (fieldMatch && currentContext) {
+        applyContextField(currentContext, fieldMatch[1], fieldMatch[2]);
+        continue;
+      }
+    }
   }
 
+  pushContextItem();
+
   // Push the last trigger
   if (current?.name) {
     if (current.action?.webhook) {
@@ -713,14 +922,174 @@ function serializeBackup(backup: BackupConfig): string[] {
 // Directory management
 // ---------------------------------------------------------------------------
 
-export async function ensureConfigDir(): Promise<void> {
-  await mkdir(configDirPath(), { recursive: true });
-  await mkdir(vaultsDirPath(), { recursive: true });
-}
-
 export function ensureConfigDirSync(): void {
   mkdirSync(configDirPath(), { recursive: true });
-  mkdirSync(vaultsDirPath(), { recursive: true });
+  migrateFromLegacyLayout();
+  mkdirSync(vaultHomePath(), { recursive: true });
+  migrateVaultInternalLayout();
+  mkdirSync(dataDirPath(), { recursive: true });
+  mkdirSync(logsDirPath(), { recursive: true });
+}
+
+/**
+ * Move vault-owned state from the legacy root layout (`~/.parachute/.env`,
+ * `~/.parachute/vaults/`, …) into `~/.parachute/vault/`. Fresh installs see
+ * nothing to migrate and exit quickly; double-calls are a no-op.
+ *
+ * Per-path move policy: if a legacy path exists AND the target under `vault/`
+ * does not, rename the legacy path into place. If both exist, the target
+ * wins — we don't overwrite a user's manually-migrated state — and the
+ * legacy path is left alone with a warning logged. Each moved path is
+ * announced on stdout so users notice when vault relocates their files.
+ */
+export function migrateFromLegacyLayout(): void {
+  const root = configDirPath();
+  const dest = vaultHomePath();
+
+  // Pre-0.3 installs targeted flat names at root (`vaults`, `vault.log`);
+  // we now land those directly under their current canonical subdirs
+  // (`data/`, `logs/`) so upgrading users skip the intermediate shape that
+  // `migrateVaultInternalLayout` would otherwise correct on a second pass.
+  const candidates: Array<[string, string]> = [
+    [".env", ".env"],
+    ["config.yaml", "config.yaml"],
+    ["vault.log", "logs/vault.log"],
+    ["vault.err", "logs/vault.err"],
+    ["start.sh", "start.sh"],
+    ["server-path", "server-path"],
+    ["vaults", "data"],
+    ["assets", "assets"],
+  ];
+
+  const present: Array<[string, string]> = [];
+  for (const [from, to] of candidates) {
+    const src = join(root, from);
+    if (existsSync(src)) present.push([from, to]);
+  }
+  if (present.length === 0) return;
+
+  mkdirSync(dest, { recursive: true });
+
+  const moved: string[] = [];
+  const skipped: string[] = [];
+  for (const [from, to] of present) {
+    const src = join(root, from);
+    const dst = join(dest, to);
+    if (existsSync(dst)) {
+      skipped.push(from);
+      continue;
+    }
+    // Target may live in a subdir (logs/, data/); ensure parent exists
+    // before renameSync, which is strict about target parent existence.
+    const parent = join(dst, "..");
+    mkdirSync(parent, { recursive: true });
+    try {
+      renameSync(src, dst);
+      moved.push(from);
+    } catch (err) {
+      console.warn(formatMigrationFailure(src, dst, err));
+    }
+  }
+
+  // Log to stderr — migration is operational/audit output, and keeping
+  // stdout clean lets callers that pipe stdout (the CLI, spawned child
+  // processes, JSON-consuming shells) run without interference.
+  if (moved.length > 0) {
+    console.error(
+      `[parachute-vault] migrated to new layout: moved ${moved.map((p) => join(root, p)).join(", ")} → ${dest}/`,
+    );
+  }
+  if (skipped.length > 0) {
+    console.error(
+      `[parachute-vault] left legacy paths in place (target already exists under vault/): ${skipped.map((p) => join(root, p)).join(", ")}. Remove the legacy copies once you've confirmed the vault/ copies are current.`,
+    );
+  }
+}
+
+/**
+ * Format a migration-rename failure warning. If the underlying error is
+ * EXDEV (cross-device rename — `PARACHUTE_HOME` straddles a mount, a common
+ * shape in Docker with bind-mounts or multi-disk dev setups), the raw error
+ * message is opaque. Surface the likely cause and note that vault continues
+ * on the legacy layout rather than exiting.
+ */
+export function formatMigrationFailure(src: string, dst: string, err: unknown): string {
+  const msg = err instanceof Error ? err.message : String(err);
+  const code = err instanceof Error ? (err as NodeJS.ErrnoException).code : undefined;
+  if (code === "EXDEV") {
+    return `[parachute-vault] migration failed for ${src} → ${dst}: likely because PARACHUTE_HOME crosses a mount boundary (EXDEV). Vault will continue on the legacy layout; move the file manually to complete the upgrade.`;
+  }
+  return `[parachute-vault] failed to migrate ${src} → ${dst}: ${msg}`;
+}
+
+/**
+ * Tidies the layout *inside* `vault/` for installs upgrading across the
+ * filesystem-hygiene refactor:
+ *
+ *   vault/vaults/   → vault/data/         (matches Postgres/Redis convention;
+ *                                          avoids the doubled "vault/vaults")
+ *   vault/vault.log → vault/logs/vault.log
+ *   vault/vault.err → vault/logs/vault.err
+ *
+ * Same target-wins, idempotent, rename-only policy as
+ * `migrateFromLegacyLayout`. Runs every boot — once the moves have
+ * happened, subsequent calls are pure existence checks that exit fast.
+ *
+ * If `vault/` doesn't exist yet (never booted before), this returns
+ * immediately — `ensureConfigDirSync` creates the fresh layout right after.
+ */
+export function migrateVaultInternalLayout(): void {
+  const vaultHome = vaultHomePath();
+  if (!existsSync(vaultHome)) return;
+
+  // vault/vaults/ → vault/data/
+  const legacyData = join(vaultHome, "vaults");
+  const newData = dataDirPath();
+  if (existsSync(legacyData)) {
+    if (existsSync(newData)) {
+      console.error(
+        `[parachute-vault] both ${legacyData}/ and ${newData}/ exist — using data/, leaving vaults/ in place. Remove the legacy copy once you've confirmed data/ is current.`,
+      );
+    } else {
+      try {
+        renameSync(legacyData, newData);
+        console.error(`[parachute-vault] migrated ${legacyData}/ → ${newData}/`);
+      } catch (err) {
+        console.warn(formatMigrationFailure(`${legacyData}/`, `${newData}/`, err));
+      }
+    }
+  }
+
+  // vault/{vault.log,vault.err} → vault/logs/{vault.log,vault.err}
+  const logsDir = logsDirPath();
+  const logsMoved: string[] = [];
+  const logsSkipped: string[] = [];
+  for (const name of ["vault.log", "vault.err"]) {
+    const src = join(vaultHome, name);
+    if (!existsSync(src)) continue;
+    const dst = join(logsDir, name);
+    if (existsSync(dst)) {
+      logsSkipped.push(name);
+      continue;
+    }
+    mkdirSync(logsDir, { recursive: true });
+    try {
+      renameSync(src, dst);
+      logsMoved.push(name);
+    } catch (err) {
+      console.warn(formatMigrationFailure(src, dst, err));
+    }
+  }
+  if (logsMoved.length > 0) {
+    console.error(
+      `[parachute-vault] migrated ${logsMoved.map((n) => join(vaultHome, n)).join(", ")} → ${logsDir}/`,
+    );
+  }
+  if (logsSkipped.length > 0) {
+    console.error(
+      `[parachute-vault] left legacy log files in place (target already exists under logs/): ${logsSkipped.map((n) => join(vaultHome, n)).join(", ")}.`,
+    );
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -857,6 +1226,18 @@ export function writeGlobalConfig(config: GlobalConfig): void {
       if (trigger.action.timeout) {
         lines.push(`      timeout: ${trigger.action.timeout}`);
       }
+      if (trigger.action.include_context?.length) {
+        lines.push("      include_context:");
+        for (const entry of trigger.action.include_context) {
+          lines.push(`        - tag: ${entry.tag}`);
+          if (entry.exclude_tag) {
+            lines.push(`          exclude_tag: ${entry.exclude_tag}`);
+          }
+          if (entry.include_metadata?.length) {
+            lines.push(`          include_metadata: [${entry.include_metadata.map((v) => `"${v}"`).join(", ")}]`);
+          }
+        }
+      }
     }
   }
 
@@ -916,7 +1297,7 @@ export function generateApiKey(): { fullKey: string; keyId: string } {
 }
 
 // ---------------------------------------------------------------------------
-// Environment file (~/.parachute/.env)
+// Environment file (~/.parachute/vault/.env)
 // ---------------------------------------------------------------------------
 
 /**
@@ -952,7 +1333,7 @@ export function writeEnvFile(env: Record<string, string>): void {
   ensureConfigDirSync();
   const lines: string[] = [
     "# Parachute Vault configuration",
-    "# Managed by: parachute vault config",
+    "# Managed by: parachute-vault config",
     "",
   ];
   for (const [key, val] of Object.entries(env)) {
@@ -1001,7 +1382,7 @@ export function loadEnvFile(): void {
 
 export function listVaults(): string[] {
   try {
-    const dir = vaultsDirPath();
+    const dir = dataDirPath();
     if (!existsSync(dir)) return [];
     const entries = Bun.spawnSync(["ls", dir]).stdout.toString().trim();
     if (!entries) return [];
@@ -1014,15 +1395,15 @@ export function listVaults(): string[] {
 }
 
 /**
- * Resolve the vault that unscoped routes (`/mcp`, `/api/*`, `/oauth/*`,
- * `/view/*`) should target.
+ * Resolve the vault that tooling-level defaults (e.g. the `parachute-vault`
+ * MCP entry the CLI writes into `~/.claude.json`) should target. HTTP routing
+ * is vault-scoped — `/vault/<name>/...` is the only URL shape — so this helper
+ * is no longer on the request path; it just picks the one vault the CLI wires
+ * up by default.
  *
  * Resolution order:
  *  1. If `default_vault` is set in config.yaml AND that vault exists → use it.
  *  2. Else if exactly one vault exists → use that vault regardless of its name.
- *     This is the "single-vault auto-default": if you only have `journal`,
- *     `/mcp` transparently targets `journal` without requiring you to visit
- *     `/vaults/journal/mcp`.
  *  3. Otherwise → return `null` (multi-vault deployment with no/bad default;
  *     the caller should surface an explicit error rather than guess).
  *
@@ -1030,8 +1411,7 @@ export function listVaults(): string[] {
  *  - If `default_vault` points to a deleted vault, step 2 still kicks in so
  *    operators aren't stranded after `vault remove`.
  *  - The name "default" has no special meaning here; it's just whatever
- *    `vault init` happens to create on first run. A single vault named
- *    "journal" behaves identically.
+ *    `vault init` happens to create on first run.
  */
 export function resolveDefaultVault(): string | null {
   const globalConfig = readGlobalConfig();