@openparachute/vault 0.6.0-rc.1 → 0.6.0

package/src/cli.ts

@@ -56,8 +56,11 @@ import {
   buildMcpConfigJson,
   buildMcpEntryPlan,
   chooseHubOrigin,
+  chooseMcpUrl,
+  detectHubPresence,
   detectInstallContext,
   mintHubJwt,
+  noOperatorTokenGuidance,
   readOperatorToken,
   removeMcpConfig,
   resolveInstallTarget,
@@ -101,7 +104,15 @@ import { resolveBindHostname } from "./bind.ts";
 import { listTokens, revokeToken, migrateVaultKeys } from "./token-store.ts";
 import { VAULT_SCOPES } from "./scopes.ts";
 import { validateVaultName, decideInitVaultName } from "./vault-name.ts";
+import { decideAutostart } from "./autostart.ts";
 import { getVaultStore } from "./vault-store.ts";
+import {
+  defaultMirrorConfig,
+  resolveMirrorPath,
+  writeMirrorConfigForVault,
+  type MirrorConfig,
+} from "./mirror-config.ts";
+import { bootstrapInternalMirror } from "./mirror-manager.ts";
 import { selfRegister } from "./self-register.ts";
 import {
   hasOwnerPassword,
@@ -265,12 +276,16 @@ async function cmdInit(args: string[] = []) {
   const flagMcpOff = args.includes("--no-mcp");
   const flagTokenOn = args.includes("--token");
   const flagTokenOff = args.includes("--no-token");
-  // --autostart / --no-autostart toggle daemon registration. Default is on
-  // (preserves historical behavior). When --no-autostart is passed, init
-  // skips registering with launchd / systemd AND removes any prior
-  // registration — for CI, dev sandboxes, Docker, or any environment where
-  // another supervisor manages the process. --no-autostart wins over
-  // --autostart on the same command line (safer-default precedence).
+  // --autostart / --no-autostart toggle daemon registration. The default is
+  // context-aware (resolved by decideAutostart below): ON for standalone
+  // deploys, but OFF when a hub supervisor is detected, since the hub owns
+  // vault's lifecycle and a launchd/systemd unit would race it for :1940
+  // (ParachuteComputer/parachute-hub#580). --no-autostart always skips
+  // registering AND removes any prior registration — for CI, dev sandboxes,
+  // Docker, or any environment where another supervisor manages the process.
+  // --autostart forces registration even under a hub (logged with a warning).
+  // --no-autostart wins over --autostart on the same command line
+  // (safer-default precedence).
   const flagAutostartOn = args.includes("--autostart");
   const flagAutostartOff = args.includes("--no-autostart");
 
@@ -407,37 +422,73 @@ async function cmdInit(args: string[] = []) {
   // a folder move; this refreshes ~/.parachute/server-path and bounces the
   // daemon so the new location takes effect immediately.
   //
-  // Autostart precedence (resolved here so the user's prior config is
-  // honored on re-runs that don't pass a flag):
-  //   1. --no-autostart on this run → false (and persisted)
-  //   2. --autostart on this run    → true  (and persisted)
-  //   3. Existing config.autostart  → that value
-  //   4. Default                    → true (historical behavior)
+  // Autostart precedence is resolved by `decideAutostart` (pure, unit-tested):
+  //   1. --no-autostart on this run             → false (and persisted)
+  //   2. --autostart on this run                → true  (and persisted; warns
+  //                                                if a supervised hub was seen)
+  //   3. Existing config.autostart              → that value
+  //   4. Hub present, no flag, no persisted val → false (the hub supervisor
+  //                                                owns the lifecycle — #580)
+  //   5. Default                                → true  (standalone deploys
+  //                                                genuinely need a daemon)
   // When false: skip register AND uninstall any prior registration so the
-  // flag's intent ("don't auto-start / don't auto-restart") matches reality
+  // decision's intent ("don't auto-start / don't auto-restart") matches reality
   // even if a previous run had registered a daemon.
-  let autostartEnabled: boolean;
-  if (flagAutostartOff) autostartEnabled = false;
-  else if (flagAutostartOn) autostartEnabled = true;
-  else if (typeof globalConfig.autostart === "boolean") autostartEnabled = globalConfig.autostart;
-  else autostartEnabled = true;
+  //
+  // The hub probe runs only when neither flag was passed AND no value is
+  // persisted — i.e. only when the hub signal can actually change the outcome.
+  // It targets the hub's fixed loopback port (1939 / $PARACHUTE_HUB_PORT) and
+  // never throws (see detectHubPresence). We skip it when a flag/persisted
+  // value already decides, to avoid an 800ms wait on a flagged run.
+  //
+  // False-positive risk: a stale expose-state / leftover PARACHUTE_HUB_ORIGIN
+  // makes detectHubPresence return true on a genuinely hubless box, so init
+  // silently skips registering a daemon. Narrow + accepted — recover with
+  // `parachute-vault init --autostart`. The pre-decided guard below means any
+  // explicit flag or persisted value never even reaches the probe.
+  const autostartPreDecided =
+    flagAutostartOff || flagAutostartOn || typeof globalConfig.autostart === "boolean";
+  const hubPresentForAutostart = autostartPreDecided ? false : await detectHubPresence();
+  const autostartDecision = decideAutostart({
+    flagOn: flagAutostartOn,
+    flagOff: flagAutostartOff,
+    persisted: globalConfig.autostart,
+    hubPresent: hubPresentForAutostart,
+  });
+  const autostartEnabled = autostartDecision.enabled;
 
-  if (flagAutostartOff || flagAutostartOn) {
+  if (autostartDecision.persist) {
     globalConfig.autostart = autostartEnabled;
     writeGlobalConfig(globalConfig);
   }
 
   let serverPath: string | null = null;
   if (!autostartEnabled) {
-    console.log("Autostart disabled — skipping daemon registration.");
+    if (autostartDecision.reason === "hub-default-off") {
+      console.log(
+        "Hub supervisor detected — not registering a separate daemon. The hub manages vault's lifecycle.",
+      );
+      console.log("  To force a standalone daemon anyway: parachute-vault init --autostart");
+    } else {
+      console.log("Autostart disabled — skipping daemon registration.");
+    }
     if (isMac) {
       await uninstallAgent();
     } else if (isLinux && isSystemdAvailable()) {
       await uninstallSystemdService();
     }
     console.log("  To run vault: parachute-vault serve   (or use your own supervisor)");
-    console.log("  To re-enable: parachute-vault init --autostart");
+    if (autostartDecision.reason !== "hub-default-off") {
+      console.log("  To re-enable: parachute-vault init --autostart");
+    }
   } else {
+    if (autostartDecision.overrodeHub) {
+      console.log(
+        "Warning: a supervised hub was detected, but --autostart was passed — registering a "
+          + "standalone daemon anyway. This can race the hub supervisor for the vault port; "
+          + "prefer letting the hub manage vault unless you know you need both.",
+      );
+    }
     console.log("Installing daemon...");
     if (isMac) {
       ({ serverPath } = await installAgent());
@@ -471,11 +522,16 @@ async function cmdInit(args: string[] = []) {
     addMcp = true; // non-interactive: preserve the installable-via-pipe default
   }
 
-  // 7b. Surface an API token for other clients? (Codex, Goose, OpenCode,
-  // Cursor, Zed, Cline, scripts, curl.) Same flag/TTY precedence as MCP.
-  // Note: a token is always minted when addMcp is true (it gets baked into
-  // the ~/.claude.json entry); this prompt controls whether that token is
-  // printed prominently at the end so the user can paste it elsewhere.
+  // 7b. Mint an API token for the header-auth / script use case? (Codex,
+  // Goose, OpenCode, Cursor, Zed, Cline, scripts, curl.)
+  //
+  // vault#442: default vault auth is per-user OAuth — the Claude Code MCP entry
+  // is written WITHOUT a baked bearer, so the first connection does browser
+  // sign-in. We mint a token ONLY when the operator explicitly opts in
+  // (`--token`, or "yes" at the prompt), and then it's scope-narrow
+  // (`vault:<name>:read`), NEVER admin. `--no-token` (and the non-interactive
+  // default) skips minting entirely — no auto-mint, no noisy mint-failure on a
+  // fresh vault.
   let addToken: boolean;
   if (flagTokenOff) {
     addToken = false;
@@ -483,25 +539,22 @@ async function cmdInit(args: string[] = []) {
     addToken = true;
   } else if (process.stdin.isTTY) {
     addToken = await confirm(
-      "Generate an API token for other MCP clients (Codex, Goose, OpenCode, Cursor, Zed, Cline), scripts, or curl?",
-      true,
+      "Also mint a header-auth API token for non-OAuth clients / scripts (Codex, Goose, curl)? (OAuth works without one)",
+      false,
     );
   } else {
-    addToken = true; // non-interactive: default-yes matches addMcp default
+    addToken = false; // non-interactive default: OAuth-first, no auto-mint
   }
 
-  // Mint a token if we need one (for the claude.json entry and/or for
-  // prominent display) and don't already have one from vault creation —
-  // e.g. a re-run of init against an existing vault. vault#282 Stage 2: vault
-  // no longer mints pvt_* tokens, so this is a hub JWT via the operator.token
-  // → hub mint-token path (`mintBootstrapCredential`). When no hub is
-  // reachable, `apiKey` stays undefined and we carry the guidance to the
-  // summary — the operator runs `mcp-install` once a hub is up, or sets
-  // VAULT_AUTH_TOKEN.
+  // Mint a scope-narrow token ONLY when explicitly opted in and we don't
+  // already have one from vault creation. vault#282 Stage 2: vault no longer
+  // mints pvt_* tokens — this is a hub JWT via the operator.token → hub
+  // mint-token path (`mintBootstrapCredential`), scoped `vault:<name>:read`.
+  // When no hub is reachable, `apiKey` stays undefined and we carry the
+  // guidance to the summary. The default (OAuth) path never reaches here.
   const defaultVault = globalConfig.default_vault || "default";
-  const needToken = addMcp || addToken;
-  if (needToken && !apiKey) {
-    const credential = await mintBootstrapCredential(defaultVault);
+  if (addToken && !apiKey) {
+    const credential = await mintBootstrapCredential(defaultVault, "read");
     apiKey = credential.token ?? undefined;
     credentialGuidance = credential.guidance;
     if (!apiKey) console.log(`  ${credential.guidance}`);
@@ -510,10 +563,9 @@ async function cmdInit(args: string[] = []) {
   if (addMcp) {
     // 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. The bearer is the hub
-    // JWT minted above (omitted when no hub was reachable — the entry is then
-    // written unauthenticated, and the operator re-runs `mcp-install` once a
-    // hub is up).
+    // change can't drift between init and mcp-install. By default NO bearer is
+    // baked (vault#442 — OAuth on first connect); a bearer is embedded only
+    // when the operator explicitly opted into a scope-narrow token above.
     const target = resolveInstallTarget("user");
     const { entryKey, url, source } = buildMcpEntryPlan({
       vaultName: defaultVault,
@@ -528,6 +580,9 @@ async function cmdInit(args: string[] = []) {
     });
     console.log(`MCP URL: ${url} (${source})`);
     console.log(`  MCP server added to ~/.claude.json`);
+    if (!apiKey) {
+      console.log(`  No token baked in — you'll sign in via OAuth on first connect.`);
+    }
   } else {
     console.log("  Skipped adding MCP to ~/.claude.json.");
     console.log("  Run `parachute-vault mcp-install` later if you want it.");
@@ -536,6 +591,11 @@ async function cmdInit(args: string[] = []) {
   // 8. Summary
   const port = globalConfig.port || DEFAULT_PORT;
   const mcpUrl = `http://127.0.0.1:${port}/vault/${defaultVault}/mcp`;
+  // Probe whether a hub is present so the summary's "opted into a token but
+  // none minted" copy reflects reality: under a hub the vault is reachable via
+  // browser OAuth even with no header-auth token (#445). Only matters for the
+  // !apiKey branches; cheap + best-effort (never throws).
+  const hubPresent = !apiKey ? await detectHubPresence() : true;
   const lines = buildInitSummaryLines({
     addMcp,
     addToken,
@@ -544,7 +604,9 @@ async function cmdInit(args: string[] = []) {
     bindHost,
     port,
     mcpUrl,
+    vaultName: defaultVault,
     noTokenGuidance: credentialGuidance,
+    hubPresent,
   });
   for (const line of lines) console.log(line);
 }
@@ -814,27 +876,73 @@ async function cmdCreate(args: string[]) {
   // POST /vaults shells out to this CLI and parses stdout). Errors still go
   // to stderr as plain text and exit nonzero — callers branch on exit code.
   const jsonMode = args.includes("--json");
-  // Greedy strip of any `--*` token to recover the positional vault name.
-  // Today only `--json` is recognized; any other `--foo` is silently dropped.
-  // If a future flag (e.g. `--force`, `--dry-run`) is added, the parsing
-  // here needs to whitelist it — otherwise an invalid flag becomes a silent
-  // no-op rather than a usage error.
-  const positional = args.filter((a) => !a.startsWith("--"));
+  // `--no-mirror` opts THIS create out of the default internal live mirror
+  // even when the server-wide `default_mirror` knob is `internal`. Parity for
+  // operators who want one bare vault without flipping the global default.
+  const noMirror = args.includes("--no-mirror");
+
+  // --- Auth opt-in (vault#442). Default = per-user OAuth, NO token minted. ---
+  // `--mint` opts into a scope-narrow hub JWT for the header-auth / script
+  // use case; `--scope read|write` (default read) picks the verb. `:admin` is
+  // intentionally NOT accepted from the create flow. `--token <bearer>` is the
+  // paste path — use an existing bearer instead of minting. The two are
+  // mutually exclusive.
+  const wantMint = args.includes("--mint");
+  const createTokenArg = takeArgValue(args, "--token");
+  if (createTokenArg.missingValue) {
+    console.error("--token requires a value (the bearer token to embed).");
+    process.exit(1);
+  }
+  const pastedToken = createTokenArg.value;
+  if (wantMint && pastedToken !== undefined) {
+    console.error("--mint and --token are mutually exclusive.");
+    process.exit(1);
+  }
+  const createScopeArg = takeArgValue(args, "--scope");
+  if (createScopeArg.missingValue) {
+    console.error("--scope requires a value: read or write.");
+    process.exit(1);
+  }
+  const rawCreateVerb = createScopeArg.value ?? "read";
+  if (rawCreateVerb !== "read" && rawCreateVerb !== "write") {
+    console.error(
+      `--scope must be "read" or "write" for create (admin is minted out-of-band via \`mcp-install --scope vault:admin\`). Got: ${rawCreateVerb}.`,
+    );
+    process.exit(1);
+  }
+  const mintVerb: "read" | "write" | undefined = wantMint ? rawCreateVerb : undefined;
+
+  // Greedy strip of any `--*` token (and any `--flag value` pairs we consumed
+  // above) to recover the positional vault name. `--json`, `--no-mirror`,
+  // `--mint`, `--token <v>`, `--scope <v>` are recognized; any other `--foo` is
+  // silently dropped, and the value following a recognized value-flag is
+  // skipped so it can't be mistaken for the vault name.
+  const VALUE_FLAGS = new Set(["--token", "--scope"]);
+  const positional: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!;
+    if (a.startsWith("--")) {
+      if (VALUE_FLAGS.has(a)) i++; // skip the flag's value
+      continue;
+    }
+    positional.push(a);
+  }
   const name = positional[0];
   if (!name) {
     console.error("Usage: parachute-vault create <name> [--json]");
     process.exit(1);
   }
 
-  if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
-    console.error("Vault name must contain only letters, numbers, hyphens, and underscores.");
-    process.exit(1);
-  }
-  if (name === "list") {
-    // 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.`);
+  // One validator for every name-minting edge (2026-06-09 hub-module-boundary
+  // migration B2). cmdCreate used to carry its own inline charset check plus a
+  // hardcoded `"list"` reservation that had drifted from `validateVaultName`'s
+  // set — a vault named `admin`/`new`/`assets` could enter through `create`
+  // and capture a reserved route (`/vault/admin` is the daemon-level admin
+  // mount as of B3). Consuming the shared validator also picks up its 2–32
+  // length rule, aligning `create` with `init`, the env var, and hub's wizard.
+  const nameValidation = validateVaultName(name);
+  if (!nameValidation.ok) {
+    console.error(nameValidation.error);
     process.exit(1);
   }
 
@@ -846,7 +954,18 @@ async function cmdCreate(args: string[]) {
 
   ensureConfigDirSync();
   const wasFirst = listVaults().length === 0;
-  const credential = await createVault(name);
+  const credential = await createVault(name, {
+    ...(noMirror ? { enableMirror: false } : {}),
+    ...(mintVerb ? { mintVerb } : {}),
+  });
+
+  // `--token <bearer>` paste path: the operator supplied their own bearer
+  // instead of minting one. Surface it as the credential token so the
+  // downstream JSON / human / summary copy treats it the same as a minted one.
+  const effectiveToken = pastedToken ?? credential.token;
+  const effectiveGuidance = pastedToken
+    ? "Using the bearer you supplied via --token."
+    : credential.guidance;
 
   // If this is the only vault now, make it the default so unscoped routes
   // (/mcp, /api/*, /oauth/*) target it. Avoids the "single vault named
@@ -880,17 +999,19 @@ async function cmdCreate(args: string[]) {
     log: () => {}, // CLI create has its own status lines.
   });
 
+  const endpoint = chooseMcpUrl(name, globalConfig.port || DEFAULT_PORT).url;
+
   if (jsonMode) {
     // Contract (hub's admin-vaults.ts requires `typeof token === "string"`):
-    // emit the minted hub JWT when present. When no hub was reachable
-    // (standalone create — no operator.token / no hub origin), `token` is the
-    // empty string and `token_guidance` carries the operator's next step. Hub
-    // only shells out to `create --json` while IT is the orchestrator (a hub is
-    // running, operator.token present), so that path always mints a real JWT.
+    // emit a token string when one was minted/pasted. vault#442 default is
+    // per-user OAuth — no token is minted — so `token` is the empty string and
+    // `token_guidance` carries the OAuth-first connect path. (Hub's admin SPA
+    // already handles the empty-token case + has its own session-cookie admin
+    // mint path, so it doesn't depend on create minting a token.)
     const payload = {
       name,
-      token: credential.token ?? "",
-      token_guidance: credential.guidance,
+      token: effectiveToken ?? "",
+      token_guidance: effectiveGuidance,
       paths: {
         vault_dir: vaultDir(name),
         vault_db: vaultDbPath(name),
@@ -904,18 +1025,20 @@ async function cmdCreate(args: string[]) {
 
   console.log(`Vault "${name}" created.`);
   console.log(`  Path: ${vaultDir(name)}`);
-  if (credential.token) {
-    console.log(`  API token: ${credential.token}`);
-    console.log(`  ${credential.guidance}`);
+  if (effectiveToken) {
+    console.log(`  API token: ${effectiveToken}`);
+    console.log(`  ${effectiveGuidance}`);
     console.log(`  Save this — it will not be shown again.`);
   } else {
-    console.log(`  ${credential.guidance}`);
+    console.log(`  ${effectiveGuidance}`);
   }
   if (defaultNote) {
     console.log(`  ${defaultNote}`);
   }
   console.log();
-  console.log(`To add MCP to Claude: parachute-vault mcp-install ${name}`);
+  console.log(`Connect your AI: claude mcp add --transport http parachute-${name} ${endpoint}`);
+  console.log(`  (no token needed — you'll sign in on first use)`);
+  console.log(`Need a header-auth token for a script? parachute auth mint-token --scope vault:${name}:read`);
 }
 
 function cmdList() {
@@ -1447,20 +1570,52 @@ function cmdRemove(args: string[]) {
   // Keep default_vault in sync. If the removed vault was the default, either
   // promote the remaining vault (if exactly one) or clear the setting.
   const globalConfig = readGlobalConfig();
+  const remaining = listVaults();
+  let configDirty = false;
   if (globalConfig.default_vault === name) {
-    const remaining = listVaults();
     if (remaining.length === 1) {
       globalConfig.default_vault = remaining[0];
-      writeGlobalConfig(globalConfig);
       console.log(`  Default vault is now "${remaining[0]}".`);
     } else {
       delete globalConfig.default_vault;
-      writeGlobalConfig(globalConfig);
       if (remaining.length > 1) {
         console.log(`  Cleared default_vault — set one with: editor ${CONFIG_DIR}/config.yaml`);
       }
     }
+    configDirty = true;
   }
+
+  // Last-vault marker (2026-06-09 hub-module-boundary migration, B1's
+  // CLI-side improvement). Server boot auto-creates `default` when zero
+  // vaults exist — without the marker, an operator who explicitly emptied
+  // the server would find a freshly-credentialed `default` resurrected on
+  // the next restart. Fresh installs never carry the marker (no config.yaml
+  // at all), so Docker / hub-install first-run auto-create is preserved.
+  if (remaining.length === 0 && globalConfig.auto_create !== false) {
+    globalConfig.auto_create = false;
+    configDirty = true;
+    console.log(
+      `  Last vault removed — wrote auto_create: false to ${GLOBAL_CONFIG_PATH} so the` +
+        ` server won't auto-recreate "default" on next boot. Create a vault with:` +
+        ` parachute-vault create <name>`,
+    );
+  }
+  if (configDirty) writeGlobalConfig(globalConfig);
+
+  // Refresh services.json so the removed vault's /vault/<name> path drops
+  // out of the parachute-vault row immediately — the same selfRegister
+  // refresh cmdCreate does (#208). Without this, the hub's well-known
+  // fan-out kept advertising the deleted vault until the next server boot.
+  // Note: with zero vaults remaining, selfRegister falls back to the
+  // manifest's canonical paths (`/vault/default`) — the same row a
+  // subsequent boot would write — so CLI-remove and boot agree on the
+  // zero-vault registration shape. Warnings go to stderr; status lines stay
+  // ours.
+  selfRegister({
+    version: pkg.version,
+    warn: (msg) => console.error(`Warning: ${msg}`),
+    log: () => {},
+  });
 }
 
 async function cmdConfig(args: string[]) {
@@ -1586,15 +1741,15 @@ function cmdTokens(args: string[]) {
     return;
   }
 
-  // `tokens create` was removed at 0.6.0 (vault#282 Stage 2). Vault no longer
+  // `tokens create` was removed at 0.5.0 (vault#282 Stage 2). Vault no longer
   // mints its own (pvt_*) tokens — it's a pure hub resource-server. Tokens are
   // now hub-issued JWTs: run `parachute-vault mcp-install` to mint + wire one
   // for an MCP client, or `parachute auth mint-token --scope vault:<name>:<verb>`
   // for scripts. `tokens list` / `tokens revoke` remain for cleaning up any
-  // vestigial pre-0.6.0 rows.
+  // vestigial pre-0.5.0 rows.
   if (subcmd === "create") {
     console.error(
-      "`parachute-vault tokens create` was removed at 0.6.0 — vault no longer mints its own tokens.\n" +
+      "`parachute-vault tokens create` was removed at 0.5.0 — vault no longer mints its own tokens.\n" +
         "  Mint a hub-issued JWT instead:\n" +
         "    parachute-vault mcp-install --scope vault:<verb>   # wire an MCP client\n" +
         "    parachute auth mint-token --scope vault:<name>:<verb>   # for scripts\n" +
@@ -2760,34 +2915,17 @@ async function cmdImport(args: string[]) {
     return;
   }
 
-  // Import into vault — use createNoteRaw to skip per-note wikilink sync,
-  // then do a single pass after all notes are imported (much faster for large vaults).
+  // Import into vault — use the shared `importObsidianNotes` adapter
+  // (obsidian.ts). It uses createNoteRaw to skip per-note wikilink sync,
+  // id-aware upsert with a path-conflict guard, intra-batch collision
+  // dedup, per-note error isolation, and timestamp preservation. The
+  // single wikilink pass runs below, after all notes exist.
+  const { importObsidianNotes } = await import("../core/src/obsidian.ts");
   const store = getVaultStore(vaultName);
-  let imported = 0;
-  let skipped = 0;
-
-  for (const note of notes) {
-    // Skip if a note with this path already exists
-    const existing = await store.getNoteByPath(note.path);
-    if (existing) {
-      skipped++;
-      continue;
-    }
+  const { imported, skipped } = await importObsidianNotes(store, notes);
 
-    // Build metadata from frontmatter (excluding tags, already extracted)
-    const metadata = Object.keys(note.frontmatter).length > 0 ? note.frontmatter : undefined;
-
-    await store.createNoteRaw(note.content, {
-      path: note.path,
-      tags: note.tags.length > 0 ? note.tags : undefined,
-      metadata: metadata as Record<string, unknown>,
-    });
-    imported++;
-  }
-
-  // Single-pass wikilink sync after all notes exist
   console.log(`\nImported ${imported} notes into vault "${vaultName}"`);
-  if (skipped > 0) console.log(`Skipped ${skipped} notes (path already exists)`);
+  if (skipped > 0) console.log(`Skipped ${skipped} notes (path already exists or conflict)`);
 
   if (imported > 0) {
     const linkResult = await store.syncAllWikilinks();
@@ -3274,38 +3412,58 @@ async function firstChangedNoteTitle(
 /**
  * Outcome of bootstrapping a fresh vault's first credential (vault#282 Stage 2).
  *
- * Vault no longer mints `pvt_*` tokens. The first credential for a new vault is
- * a hub-issued JWT, minted via the same operator.token → hub mint-token path
- * `mcp-install --mint` uses (cli.ts ~`cmdMcpInstall`). When no hub is reachable
- * (standalone install, no operator.token, or no real hub origin), `token` is
- * null and `guidance` carries the operator's next step.
+ * Vault no longer mints `pvt_*` tokens. When a token IS minted (explicit opt-in
+ * only — vault#442), it's a hub-issued JWT scoped narrow (`vault:<name>:read`
+ * or `:write`, NEVER `:admin`), minted via the same operator.token → hub
+ * mint-token path `mcp-install --mint` uses (cli.ts ~`cmdMcpInstall`). When no
+ * hub is reachable (standalone install, no operator.token, or no real hub
+ * origin), `token` is null and `guidance` carries the operator's next step.
  */
 interface VaultCredential {
-  /** Hub-issued JWT scoped to `vault:<name>:admin`, or null when no hub is reachable. */
+  /** Hub-issued JWT scoped narrow (read/write), or null when not minted / no hub reachable. */
   token: string | null;
   /** Human-readable note: how the token was issued, or why it wasn't. */
   guidance: string;
 }
 
 /**
- * Mint the first credential for a freshly-created vault.
+ * Mint a scope-narrow credential for a vault (explicit opt-in — vault#442).
+ *
+ * Default vault auth is per-user OAuth (browser sign-in on first MCP connect);
+ * tokens are only for the header-auth / script use case and are minted ONLY
+ * when explicitly requested. Decision (vault#442): the create/init flow NEVER
+ * auto-mints, and when a token IS requested it's scope-narrow — `verb` is
+ * `read` (default) or `write`, NEVER `admin`. (Admin tokens, when truly
+ * needed, are minted out-of-band via `mcp-install --scope vault:admin` against
+ * a hub running hub#449, or the hub admin SPA's own session-cookie path.)
  *
- * Decision (vault#282 Stage 2): when a hub is reachable (operator.token present
- * AND a real hub origin resolves), mint a `vault:<name>:admin` hub JWT and
- * return it as the bootstrap credential — preserving the `create --json`
- * `token` string contract hub's admin-vaults.ts requires. When no hub is
+ * When a hub is reachable (operator.token present AND a real hub origin
+ * resolves), mint a `vault:<name>:<verb>` hub JWT and return it. When no hub is
  * reachable, return `token: null` plus explicit standalone guidance. There is
  * no local pvt_* fallback anymore.
  */
-async function mintBootstrapCredential(name: string): Promise<VaultCredential> {
+async function mintBootstrapCredential(
+  name: string,
+  verb: "read" | "write" = "read",
+  /**
+   * Test seam — injectable hub-presence probe. Defaults to the live
+   * `detectHubPresence` (loopback `/health` + configured-origin check). Lets
+   * tests drive both branches of the no-operator-token copy without a real hub.
+   */
+  detectHub: typeof detectHubPresence = detectHubPresence,
+): Promise<VaultCredential> {
   const operatorToken = readOperatorToken();
   if (!operatorToken) {
+    // No operator.token. Two very different worlds, identical symptom:
+    //   (a) Hub running on a fresh box — the token isn't minted until the
+    //       admin wizard creates the first admin user (hub init Step 1.5 is a
+    //       no-op until then). NOTHING to do here; the old "install the hub …"
+    //       copy is circular (this very flow was spawned *by* the hub). #445.
+    //   (b) Genuinely standalone — no hub at all. The original guidance holds.
+    const hubPresent = await detectHub();
     return {
       token: null,
-      guidance:
-        "No token issued — no hub operator token at ~/.parachute/operator.token. " +
-        "Install the hub (`bun add -g @openparachute/hub` + `parachute init`) and re-run, " +
-        "or set VAULT_AUTH_TOKEN for an operator-channel bearer.",
+      guidance: noOperatorTokenGuidance(hubPresent),
     };
   }
   const port = readGlobalConfig().port || DEFAULT_PORT;
@@ -3322,7 +3480,7 @@ async function mintBootstrapCredential(name: string): Promise<VaultCredential> {
   const result = await mintHubJwt({
     hubOrigin: hub.url,
     operatorToken,
-    scope: `vault:${name}:admin`,
+    scope: `vault:${name}:${verb}`,
     subject: "parachute-vault-bootstrap",
   });
   if ("kind" in result) {
@@ -3333,7 +3491,7 @@ async function mintBootstrapCredential(name: string): Promise<VaultCredential> {
     return {
       token: null,
       guidance:
-        `No token issued — ${detail}. Verify the hub is running (hub#449 for vault:admin mint), ` +
+        `No token issued — ${detail}. Verify the hub is running, ` +
         "then run `parachute-vault mcp-install`, or set VAULT_AUTH_TOKEN.",
     };
   }
@@ -3344,13 +3502,76 @@ async function mintBootstrapCredential(name: string): Promise<VaultCredential> {
 }
 
 /**
- * Create a vault's config + DB and mint its first credential.
+ * Create a vault's config + DB.
  *
- * Returns the bootstrap credential (a hub JWT, or null + guidance when no hub
- * is reachable — vault#282 Stage 2). The DB is created lazily via
- * `getVaultStore` so migrations + schema run; we no longer write any pvt_* row.
+ * Default vault auth is per-user OAuth (vault#442) — create does NOT mint or
+ * bake in any token. Returns a `VaultCredential` whose `token` is null and
+ * whose `guidance` points at the OAuth-first connect path. A scope-narrow
+ * token is minted only when the caller passes `mintVerb` (the explicit
+ * header-auth / script opt-in: `read` default or `write`, NEVER `admin`). The
+ * DB is created lazily via `getVaultStore` so migrations + schema run; we never
+ * write any pvt_* row.
+ */
+interface CreateVaultOptions {
+  /**
+   * Opt-in token mint (vault#442). Unset → no token is minted; the vault uses
+   * per-user OAuth on first MCP connect. Set to `read`/`write` → mint a
+   * scope-narrow `vault:<name>:<verb>` hub JWT for the header-auth / script
+   * use case. `admin` is intentionally NOT accepted here.
+   */
+  mintVerb?: "read" | "write";
+  /**
+   * Override the server-wide `default_mirror` knob for this one create.
+   * `--no-mirror` on `parachute-vault create` sets this to `false` so the
+   * vault is created with no mirror config even when the knob is `internal`.
+   * Unset → fall back to the `default_mirror` global config knob (default
+   * `internal`).
+   */
+  enableMirror?: boolean;
+  /**
+   * Test seam threaded straight into `bootstrapInternalMirror` (default
+   * `Bun.which`). Inject a fn returning `null` to exercise the
+   * git-not-installed best-effort path without uninstalling git from the
+   * test host.
+   */
+  which?: (cmd: string) => string | null;
+}
+
+/**
+ * The History / "Live Mirror" preset, written at create time when the
+ * `default_mirror` knob resolves to `internal`. Matches the History preset
+ * the admin SPA's VaultMirror page applies:
+ *   `{enabled:true, location:internal, sync_mode:events, auto_commit:true,
+ *    auto_push:false}`.
+ * Built on top of `defaultMirrorConfig()` so the non-preset fields
+ * (commit_template, safety_net_seconds) stay canonical.
+ */
+function historyPresetMirrorConfig(): MirrorConfig {
+  return {
+    ...defaultMirrorConfig(),
+    enabled: true,
+    location: "internal",
+    sync_mode: "events",
+    auto_commit: true,
+    auto_push: false,
+  };
+}
+
+/**
+ * Resolve whether a freshly created vault should get the internal mirror.
+ * Precedence: explicit per-create override (`--no-mirror`) → server-wide
+ * `default_mirror` knob (default `internal`).
  */
-async function createVault(name: string): Promise<VaultCredential> {
+function shouldEnableCreateTimeMirror(opts: CreateVaultOptions): boolean {
+  if (opts.enableMirror !== undefined) return opts.enableMirror;
+  // Default to "internal" when the knob is unset — backup-on-by-default.
+  return (readGlobalConfig().default_mirror ?? "internal") === "internal";
+}
+
+async function createVault(
+  name: string,
+  opts: CreateVaultOptions = {},
+): Promise<VaultCredential> {
   const config: VaultConfig = {
     name,
     api_keys: [],
@@ -3359,9 +3580,62 @@ async function createVault(name: string): Promise<VaultCredential> {
   writeVaultConfig(config);
 
   // Touch the store so the vault's SQLite DB + schema are created. No token
-  // row is written — vault is a pure hub resource-server post-0.6.0.
+  // row is written — vault is a pure hub resource-server post-0.5.0.
   getVaultStore(name);
-  return mintBootstrapCredential(name);
+
+  // Default new vaults to an internal live mirror (local git backup of the
+  // markdown projection). Backup-on-by-default; GitHub off-site backup is an
+  // opt-in upgrade layered on top later. Opt out via the `default_mirror: off`
+  // global knob (operators on git-less / disk-constrained / cloud boxes) or
+  // the `--no-mirror` flag (this one create only).
+  //
+  // BEST-EFFORT, NON-FATAL: write the mirror config first (so the operator's
+  // intent persists even if git is absent), then attempt the bootstrap. A
+  // git-less box leaves the config written but inactive + logs an actionable
+  // hint — it must NEVER fail the vault create. Create-time ONLY: existing
+  // vaults are never retroactively migrated.
+  if (shouldEnableCreateTimeMirror(opts)) {
+    const mirrorConfig = historyPresetMirrorConfig();
+    writeMirrorConfigForVault(name, mirrorConfig);
+    const mirrorPath = resolveMirrorPath(vaultDir(name), mirrorConfig);
+    if (mirrorPath) {
+      try {
+        const result = await bootstrapInternalMirror(mirrorPath, opts.which);
+        if (!result.ok) {
+          // git-not-installed (or refuse-to-clobber) — config stays written,
+          // mirror just isn't active yet. Surface an actionable line; the
+          // vault create succeeds regardless.
+          console.error(
+            `Note: local git backup configured but not yet active — ${result.error} ` +
+              `Install git to activate; the backup turns on automatically on the next vault restart.`,
+          );
+        }
+      } catch (err) {
+        // Defense-in-depth: bootstrapInternalMirror already converts the
+        // git-missing case into a non-throwing { ok:false } result, but a
+        // truly unexpected throw must still not fail the create.
+        console.error(
+          `Note: local git backup configured but bootstrap hit an unexpected error ` +
+            `(${(err as Error).message ?? err}). The vault was still created; ` +
+            `the backup will retry on the next vault restart.`,
+        );
+      }
+    }
+  }
+
+  // vault#442: default to per-user OAuth — do NOT auto-mint or bake in a
+  // shared token. Only mint when the caller explicitly opted in (header-auth /
+  // script use case), and then scope-narrow (read/write, never admin).
+  if (opts.mintVerb) {
+    return mintBootstrapCredential(name, opts.mintVerb);
+  }
+  return {
+    token: null,
+    guidance:
+      "No token minted — this vault uses per-user OAuth (sign in on first connect). " +
+      "Need a header-auth token for a script? Run " +
+      `\`parachute auth mint-token --scope vault:${name}:read\` (or \`:write\`).`,
+  };
 }
 
 interface InstallMcpConfigOpts {
@@ -3443,19 +3717,28 @@ Setup:
   parachute-vault init [--mcp|--no-mcp] [--token|--no-token] [--vault-name <name>]
                        [--autostart|--no-autostart]
                                            Set up everything (one command, idempotent).
-                                           --mcp/--no-mcp controls the Claude Code MCP entry;
-                                           --token/--no-token controls whether an API token is
-                                           printed for pasting into other MCP clients / scripts.
+                                           --mcp/--no-mcp controls the Claude Code MCP entry (written
+                                           for per-user OAuth by default — no baked token; sign in on
+                                           first connect). --token opts into ALSO minting a scope-narrow
+                                           header-auth token (vault:<name>:read) for non-OAuth clients /
+                                           scripts; --no-token (the default) skips minting entirely.
                                            --vault-name skips the prompt and names the vault
                                            (lowercase alphanumeric, hyphens, underscores;
                                            omit to be prompted interactively, default "default").
-                                           --autostart (default) registers vault with launchd /
-                                           systemd so it starts on boot AND auto-restarts on
-                                           crash. --no-autostart skips daemon registration AND
-                                           uninstalls any prior registration — for CI, dev
-                                           sandboxes, Docker, or environments where another
-                                           supervisor manages the process. Persists in
-                                           config.yaml as 'autostart: true|false'.
+                                           --autostart registers vault with launchd / systemd so
+                                           it starts on boot AND auto-restarts on crash; it forces
+                                           registration even when a hub supervisor is detected
+                                           (logged with a warning). --no-autostart skips daemon
+                                           registration AND uninstalls any prior registration — for
+                                           CI, dev sandboxes, Docker, or environments where another
+                                           supervisor manages the process. Default: register when
+                                           standalone, but skip when a hub is detected (the hub
+                                           supervisor owns vault's lifecycle). An explicit flag
+                                           persists in config.yaml as 'autostart: true|false'.
+                                           Upgrade note: a box with a persisted 'autostart: true'
+                                           (from an earlier explicit --autostart) keeps registering
+                                           even under a hub — run init --no-autostart once to clear
+                                           it and let the hub manage vault.
   parachute-vault doctor                   Diagnose install/config issues
   parachute-vault uninstall [--wipe] [--yes]
                                            Remove daemon + MCP entry; --wipe also removes vaults, .env,
@@ -3465,7 +3748,18 @@ Setup:
   parachute --version                      Print the installed version (alias: -v, version)
 
 Vaults:
-  parachute-vault create <name> [--json]   Create a new vault (--json: emit { name, token, paths, set_as_default })
+  parachute-vault create <name> [--json] [--no-mirror] [--mint [--scope read|write]] [--token <bearer>]
+                                           Create a new vault (--json: emit { name, token, paths, set_as_default }).
+                                           Default auth is per-user OAuth — NO token is minted; connect with
+                                           "claude mcp add --transport http parachute-<name> <endpoint>" and sign in
+                                           on first use. --mint opts into a scope-narrow hub JWT for the header-auth /
+                                           script case (--scope read [default] | write — admin is NOT mintable from
+                                           create); --token <bearer> pastes an existing bearer instead of minting.
+                                           New vaults default to an internal live mirror — a local git backup of
+                                           the markdown projection (backup on by default; GitHub off-site is an
+                                           opt-in upgrade). --no-mirror creates a bare vault with no mirror config.
+                                           Operators can flip the server-wide default with 'default_mirror: off' in
+                                           config.yaml (recommended for cloud / disk-constrained boxes).
   parachute-vault list                     List all vaults
   parachute-vault remove <name> [--yes]    Remove a vault
   parachute-vault mcp-install [--mint|--token <t>]
@@ -3539,7 +3833,7 @@ Vaults:
 Tokens (vault#282 Stage 2 — vault is a pure hub resource-server; it no longer
 mints its own tokens. Mint a hub-issued JWT with \`parachute-vault mcp-install\`
 or \`parachute auth mint-token --scope vault:<name>:<verb>\`. \`list\` / \`revoke\`
-below operate on any vestigial pre-0.6.0 rows for cleanup.):
+below operate on any vestigial pre-0.5.0 rows for cleanup.):
   parachute-vault tokens                          List vault-DB tokens (every vault)
   parachute-vault tokens list --vault <name>      List tokens for one vault only
   parachute-vault tokens revoke <token-id>        Revoke a vestigial token (default vault)