@openparachute/vault 0.4.5 → 0.4.6

package/src/cli.ts

@@ -53,6 +53,7 @@ import type { VaultConfig } from "./config.ts";
 import { DATA_DIR } from "./config.ts";
 import { installAgent, uninstallAgent, isAgentLoaded, restartAgent } from "./launchd.ts";
 import {
+  buildMcpConfigJson,
   buildMcpEntryPlan,
   chooseHubOrigin,
   detectInstallContext,
@@ -169,6 +170,9 @@ switch (command) {
   case "mcp-install":
     await cmdMcpInstall(cmdArgs);
     break;
+  case "mcp-config":
+    await cmdMcpConfig(cmdArgs);
+    break;
   case "remove":
   case "rm":
     cmdRemove(cmdArgs);
@@ -965,6 +969,7 @@ async function cmdMcpInstall(args: string[]): Promise<void> {
     "--install-scope",
     "--vault",
     "--client",
+    "--dry-run",
   ];
 
   const hasFlag = args.some((a) => MCP_INSTALL_FLAG_NAMES.includes(a));
@@ -1053,6 +1058,12 @@ async function cmdMcpInstall(args: string[]): Promise<void> {
   }
 
   // --- Vault target. Default = default_vault; validate existence. ---
+  // Read --dry-run *before* the vault-existence guard so a probe like
+  // `mcp-install --vault future-vault --dry-run` can describe the
+  // intended write even when the vault hasn't been created yet. The
+  // dry-run contract ("no side effects, including failures on state
+  // the caller is asking us about") is broken otherwise.
+  const dryRun = args.includes("--dry-run");
   const vaultArg = takeArgValue(args, "--vault");
   if (vaultArg.missingValue) {
     console.error("--vault requires a value (the vault name).");
@@ -1062,7 +1073,7 @@ async function cmdMcpInstall(args: string[]): Promise<void> {
   const defaultVault = globalConfig.default_vault || "default";
   const vaultName = vaultArg.value ?? defaultVault;
   const vaultExplicit = vaultArg.value !== undefined;
-  if (!readVaultConfig(vaultName)) {
+  if (!dryRun && !readVaultConfig(vaultName)) {
     console.error(`Vault "${vaultName}" not found. Available: ${listVaults().join(", ") || "(none)"}.`);
     process.exit(1);
   }
@@ -1075,6 +1086,7 @@ async function cmdMcpInstall(args: string[]): Promise<void> {
     vaultExplicit,
     pastedToken: mode === "token" ? tokenArg.value : undefined,
     globalConfig,
+    dryRun,
   });
 }
 
@@ -1110,6 +1122,107 @@ async function cmdMcpInstallInteractive(): Promise<void> {
   });
 }
 
+/**
+ * `parachute-vault mcp-config <vault-name>` — emit the JSON shape
+ * `claude -p --mcp-config '<json>'` consumes, scoped to a named vault.
+ * Pattern from Aaron's Gitcoin Brain runner:
+ *
+ *   claude -p --mcp-config "$(parachute-vault mcp-config gitcoin)" \
+ *             --strict-mcp-config ...
+ *
+ * Synthesizing this JSON by hand was per-script boilerplate every runner
+ * that spawned `claude -p` against a vault had to write. This command is
+ * the canonical synthesizer — the JSON shape is owned here once.
+ *
+ * No state is mutated; this only emits to stdout. The bearer is read from
+ * `--token <pvt_...>` or `PARACHUTE_VAULT_TOKEN` env (deliberate — we don't
+ * mint here, since this is a stdout-piped subprocess where prompting would
+ * deadlock the parent script). If neither is present, we exit 1 with a
+ * clear stderr message; runners get a fail-fast.
+ *
+ * Flags:
+ *   --token <bearer>   Bearer to embed verbatim (alternative: PARACHUTE_VAULT_TOKEN).
+ *   --base-url <url>   Override the auto-detected hub origin (default: chooseHubOrigin).
+ *                      Useful for tailnet-exposed hubs (`--base-url https://hub.tail.ts.net`).
+ *   --env-vars         Emit the template form with `${PARACHUTE_HUB_URL}` and
+ *                      `${PARACHUTE_VAULT_TOKEN}` placeholders rather than
+ *                      inlined values. Safe to commit; the shell expands at
+ *                      runtime.
+ */
+async function cmdMcpConfig(args: string[]): Promise<void> {
+  const vaultName = args[0];
+  if (!vaultName || vaultName.startsWith("--")) {
+    console.error("Usage: parachute-vault mcp-config <vault-name> [--token <pvt_...>] [--base-url <url>] [--env-vars]");
+    console.error("");
+    console.error("Emits the JSON config consumed by `claude -p --mcp-config '<json>'`.");
+    console.error("Pattern: claude -p --mcp-config \"$(parachute-vault mcp-config <name>)\" --strict-mcp-config ...");
+    process.exit(1);
+  }
+
+  const tokenArg = takeArgValue(args, "--token");
+  if (tokenArg.missingValue) {
+    console.error("--token requires a value (the bearer to embed).");
+    process.exit(1);
+  }
+  const baseUrlArg = takeArgValue(args, "--base-url");
+  if (baseUrlArg.missingValue) {
+    console.error("--base-url requires a value (e.g. https://hub.example.ts.net).");
+    process.exit(1);
+  }
+  const useEnvVars = args.includes("--env-vars");
+
+  // --env-vars mode is shape-only — no need to resolve the vault, mint a
+  // token, or even verify the vault exists. Operators committing the
+  // template don't necessarily have the target vault on the machine
+  // generating the config.
+  if (useEnvVars) {
+    const json = buildMcpConfigJson({
+      vaultName,
+      baseUrl: "",
+      bearer: "",
+      useEnvVars: true,
+    });
+    process.stdout.write(json + "\n");
+    return;
+  }
+
+  // Literal mode: verify the vault exists locally, resolve the URL, and
+  // require a bearer (either --token or PARACHUTE_VAULT_TOKEN env).
+  if (!readVaultConfig(vaultName)) {
+    const available = listVaults();
+    console.error(`Vault "${vaultName}" not found. Available: ${available.join(", ") || "(none — run `parachute-vault create <name>`)"}.`);
+    process.exit(1);
+  }
+
+  const bearer = tokenArg.value ?? process.env.PARACHUTE_VAULT_TOKEN;
+  if (!bearer) {
+    console.error("No bearer token provided. Pass --token <bearer> or set PARACHUTE_VAULT_TOKEN.");
+    console.error("  Mint a token with: parachute-vault tokens create --vault " + vaultName);
+    console.error("  Or use --env-vars to emit the template form (safe to commit; expands at runtime).");
+    process.exit(1);
+  }
+
+  const globalConfig = readGlobalConfig();
+  const port = globalConfig.port || DEFAULT_PORT;
+  let baseUrl: string;
+  if (baseUrlArg.value) {
+    baseUrl = baseUrlArg.value;
+  } else {
+    // chooseHubOrigin walks PARACHUTE_HUB_ORIGIN → expose-state → loopback;
+    // for a script invoking `claude -p` against a local vault, loopback is
+    // the right default.
+    baseUrl = chooseHubOrigin(port).url;
+  }
+
+  const json = buildMcpConfigJson({
+    vaultName,
+    baseUrl,
+    bearer,
+    useEnvVars: false,
+  });
+  process.stdout.write(json + "\n");
+}
+
 interface ExecuteMcpInstallOpts {
   mode: "mint" | "token" | "legacy-pat";
   /** Full scope string (e.g. "vault:read"). The verb segment narrows downstream. */
@@ -1131,6 +1244,16 @@ interface ExecuteMcpInstallOpts {
   existingEntryKey?: string;
   /** Reused across the call chain to avoid re-parsing config.yaml. */
   globalConfig: ReturnType<typeof readGlobalConfig>;
+  /**
+   * When true, describe the write that *would* happen (target path,
+   * entry key, URL, install scope) and exit 0 without touching the
+   * filesystem or hitting the network for a hub-mint. Useful for
+   * probing the command from a script that's setting up a runner.
+   * Aaron hit this when accidentally creating an empty
+   * `projects[<cwd>]` entry while just running `--help` — see the
+   * `mcp-config` PR notes.
+   */
+  dryRun?: boolean;
 }
 
 /**
@@ -1140,7 +1263,7 @@ interface ExecuteMcpInstallOpts {
  * preview-and-confirm step so a cancel skips the network mint entirely.
  */
 async function executeMcpInstall(opts: ExecuteMcpInstallOpts): Promise<void> {
-  const { mode, rawScope, installScope, vaultName, vaultExplicit, pastedToken, globalConfig, existingEntryKey } = opts;
+  const { mode, rawScope, installScope, vaultName, vaultExplicit, pastedToken, globalConfig, existingEntryKey, dryRun } = opts;
   const verb = rawScope.split(":")[1]!;
   const target = resolveInstallTarget(installScope);
   // Single source of truth shared with the interactive walkthrough's
@@ -1154,6 +1277,29 @@ async function executeMcpInstall(opts: ExecuteMcpInstallOpts): Promise<void> {
     ...(existingEntryKey ? { existingEntryKey } : {}),
   });
 
+  // --dry-run: describe the write that *would* happen without touching
+  // the filesystem or minting any token. Print to stdout (scripts may
+  // parse this); exit 0. Skip the auth-acquisition entirely — the point
+  // of --dry-run is to inspect without side effects, including the
+  // network round-trip for hub-mint *and* the vault-existence guard
+  // (probing the install for a not-yet-created vault is a legitimate
+  // pre-create check, not an error).
+  if (dryRun) {
+    const vaultExists = readVaultConfig(vaultName) !== null;
+    console.log(`[dry-run] No changes written.`);
+    console.log(`  Target file:    ${target.path}`);
+    console.log(`  Install scope:  ${target.scope}`);
+    if (target.localProjectKey) {
+      console.log(`  Project key:    ${target.localProjectKey}`);
+    }
+    console.log(`  Entry key:      ${entryKey}`);
+    console.log(`  MCP URL:        ${url} (${source})`);
+    console.log(`  Auth mode:      ${mode}${mode === "mint" ? ` (scope vault:${vaultName}:${verb})` : ""}`);
+    console.log(`  Vault:          ${vaultName}${vaultExists ? "" : " (does not exist yet — create with `parachute-vault create " + vaultName + "`)"}`);
+    console.log(`  Re-run without --dry-run to apply.`);
+    return;
+  }
+
   let bearer: string;
   if (mode === "token") {
     if (!pastedToken) {
@@ -1248,6 +1394,12 @@ async function executeMcpInstall(opts: ExecuteMcpInstallOpts): Promise<void> {
     console.log(`Added MCP server "${entryKey}" to ${target.path} under projects["${target.localProjectKey}"] (local scope).`);
     console.log(`  Installed locally for this directory only — runs only when Claude Code launches from ${target.localProjectKey}.`);
     console.log(`  To install globally instead, re-run with --install-scope user.`);
+    // Headless-flow heads-up: local-scope MCP entries do NOT propagate
+    // to subprocesses spawned by `claude -p` (script / cron / runner
+    // shapes), even with --setting-sources covering local. Operators
+    // wiring up a runner usually want `--install-scope user` so the
+    // entry reaches every `claude` invocation on this machine.
+    console.log(`  Headless flows (claude -p in scripts, cron, runners): prefer --install-scope user — local-scope entries don't propagate to claude -p subprocesses.`);
   } else {
     console.log(`Added MCP server "${entryKey}" to ${target.path}`);
   }
@@ -2714,6 +2866,12 @@ async function cmdExport(args: string[]) {
   let vaultName = "default";
   let outputPath = "";
   let since: string | undefined;
+  let watch = false;
+  let intervalSeconds = 5;
+  let gitCommit = false;
+  const { DEFAULT_COMMIT_TEMPLATE } = await import("./export-watch.ts");
+  let gitMessageTemplate = DEFAULT_COMMIT_TEMPLATE;
+  let gitPush = false;
 
   const positional: string[] = [];
   for (let i = 0; i < args.length; i++) {
@@ -2740,6 +2898,31 @@ async function cmdExport(args: string[]) {
         process.exit(1);
       }
       since = v;
+    } else if (arg === "--watch") {
+      watch = true;
+    } else if (arg === "--interval") {
+      const v = args[++i];
+      if (!v) {
+        console.error("--interval requires a number of seconds.");
+        process.exit(1);
+      }
+      const n = Number(v);
+      if (!Number.isFinite(n) || n <= 0) {
+        console.error(`--interval: must be a positive number of seconds (got '${v}')`);
+        process.exit(1);
+      }
+      intervalSeconds = n;
+    } else if (arg === "--git-commit") {
+      gitCommit = true;
+    } else if (arg === "--git-message-template") {
+      const v = args[++i];
+      if (!v) {
+        console.error("--git-message-template requires a value.");
+        process.exit(1);
+      }
+      gitMessageTemplate = v;
+    } else if (arg === "--git-push") {
+      gitPush = true;
     } else {
       positional.push(arg);
     }
@@ -2747,13 +2930,37 @@ async function cmdExport(args: string[]) {
   outputPath = positional[0] ?? "";
 
   if (!outputPath) {
-    console.error("Usage: parachute-vault export <dir> [--since <iso>] [--vault <name>]");
+    console.error(
+      "Usage: parachute-vault export <dir> [--since <iso>] [--vault <name>]\n" +
+        "                                  [--watch [--interval <seconds>]]\n" +
+        "                                  [--git-commit [--git-message-template <tpl>] [--git-push]]",
+    );
     console.error("\nExports a Parachute Vault as portable markdown — round-trippable across");
     console.error("Obsidian / Logseq / Foam / Quartz / Dendron and most markdown SSGs.");
     console.error("\nOptions:");
-    console.error("  --vault <name>       Source vault (default: 'default')");
-    console.error("  --since <iso>        Only export notes whose updated_at >= ISO timestamp");
-    console.error("                       (incremental — useful for git-projection cadences)");
+    console.error("  --vault <name>              Source vault (default: 'default')");
+    console.error("  --since <iso>               Only export notes whose updated_at >= ISO timestamp");
+    console.error("                              (incremental — useful for git-projection cadences)");
+    console.error("  --watch                     Stay alive; re-export incrementally on every");
+    console.error("                              vault write. Polls every --interval seconds.");
+    console.error("  --interval <seconds>        Watch poll interval (default: 5)");
+    console.error("  --git-commit                After each export, `git add -A` + commit in <dir>.");
+    console.error("                              Requires <dir> to be an initialized git repo.");
+    console.error("                              Combine with --watch for auto-history.");
+    console.error("  --git-message-template <t>  Commit message template. Variables:");
+    console.error("                                {{date}}, {{notes_changed}}, {{plural}},");
+    console.error("                                {{first_note_title}}, {{vault_name}}");
+    console.error("                              (default: \"export: {{date}} ({{notes_changed}} note{{plural}})\")");
+    console.error("  --git-push                  After commit, run `git push` (non-fatal on failure).");
+    process.exit(1);
+  }
+
+  if (intervalSeconds !== 5 && !watch) {
+    console.error("--interval only applies with --watch.");
+    process.exit(1);
+  }
+  if ((gitPush || gitMessageTemplate !== DEFAULT_COMMIT_TEMPLATE) && !gitCommit) {
+    console.error("--git-push / --git-message-template only apply with --git-commit.");
     process.exit(1);
   }
 
@@ -2772,25 +2979,180 @@ async function cmdExport(args: string[]) {
 
   const store = getVaultStore(vaultName);
   const assetsDirPath = assetsDir(vaultName);
-  console.log(`Exporting vault "${vaultName}" to ${fullPath}${since ? ` (since ${since})` : ""}`);
-  const stats = await exportVaultToDir(store, {
-    outDir: fullPath,
-    vaultName,
-    assetsDir: assetsDirPath,
-    ...(config.description ? { vaultDescription: config.description } : {}),
-    ...(since ? { since } : {}),
-  });
+  const vaultDescription = config.description;
+
+  // Git-repo precheck: fail fast and loud before we run a long-lived loop.
+  if (gitCommit) {
+    await ensureGitRepo(fullPath);
+  }
+
+  /**
+   * Run a single export cycle: export → optionally commit/push. Returns the
+   * stats + a freshly-captured cursor for the next incremental run. We
+   * capture the cursor *before* the export starts, so any write that lands
+   * during the export is picked up next cycle (cost: at most one note
+   * re-exported next round when its `updated_at` equals our cursor).
+   */
+  async function runCycle(opts: { sinceCursor?: string; isInitial: boolean }): Promise<{
+    stats: Awaited<ReturnType<typeof exportVaultToDir>>;
+    nextCursor: string;
+    committed: boolean;
+  }> {
+    const nextCursor = new Date().toISOString();
+    if (opts.isInitial) {
+      console.log(
+        `Exporting vault "${vaultName}" to ${fullPath}${opts.sinceCursor ? ` (since ${opts.sinceCursor})` : ""}`,
+      );
+    }
+    const stats = await exportVaultToDir(store, {
+      outDir: fullPath,
+      vaultName,
+      assetsDir: assetsDirPath,
+      ...(vaultDescription ? { vaultDescription } : {}),
+      ...(opts.sinceCursor ? { since: opts.sinceCursor } : {}),
+    });
+
+    if (opts.isInitial) {
+      console.log(
+        `Exported ${stats.notes} note(s), ${stats.schemas} tag schema(s), ${stats.attachments} attachment(s).`,
+      );
+      console.log(`Sidecar: ${fullPath}/.parachute/`);
+      if (stats.filtered_by_since) {
+        console.log(`Incremental: filtered by --since ${opts.sinceCursor}.`);
+      }
+      if (stats.skipped_traversal > 0) {
+        console.log(
+          `Note: ${stats.skipped_traversal} note(s) skipped (path-traversal). See [export] warnings above.`,
+        );
+      }
+      if (stats.skipped_attachments.length > 0) {
+        console.log(
+          `Note: ${stats.skipped_attachments.length} attachment(s) skipped. See [export] warnings above.`,
+        );
+      }
+    } else {
+      // Watch-mode status line: keep tight; the loop logs every interval.
+      if (stats.notes > 0) {
+        console.log(
+          `[watch] exported ${stats.notes} note${stats.notes === 1 ? "" : "s"} (cursor: ${nextCursor})`,
+        );
+      } else {
+        console.log(`[watch] no changes`);
+      }
+    }
 
-  console.log(`Exported ${stats.notes} note(s), ${stats.schemas} tag schema(s), ${stats.attachments} attachment(s).`);
-  console.log(`Sidecar: ${fullPath}/.parachute/`);
-  if (stats.filtered_by_since) {
-    console.log(`Incremental: filtered by --since ${since}.`);
+    let committed = false;
+    if (gitCommit) {
+      const { runGitCommitCycle } = await import("./export-watch.ts");
+      const commitResult = await runGitCommitCycle({
+        repoDir: fullPath,
+        template: gitMessageTemplate,
+        notesChanged: stats.notes,
+        vaultName,
+        firstNoteTitle: await firstChangedNoteTitle(store, opts.sinceCursor),
+        push: gitPush,
+      });
+      committed = commitResult.committed;
+    }
+
+    return { stats, nextCursor, committed };
   }
-  if (stats.skipped_traversal > 0) {
-    console.log(`Note: ${stats.skipped_traversal} note(s) skipped (path-traversal). See [export] warnings above.`);
+
+  // ---- Single-shot mode ----
+  if (!watch) {
+    await runCycle({ sinceCursor: since, isInitial: true });
+    return;
   }
-  if (stats.skipped_attachments.length > 0) {
-    console.log(`Note: ${stats.skipped_attachments.length} attachment(s) skipped. See [export] warnings above.`);
+
+  // ---- Watch mode ----
+  // Initial full (or since-filtered) export, then poll every interval.
+  const initial = await runCycle({ sinceCursor: since, isInitial: true });
+  let cursor = initial.nextCursor;
+  console.log(`[watch] polling every ${intervalSeconds}s; press Ctrl-C to stop.`);
+
+  let stopping = false;
+  let inFlight = false;
+  let timer: ReturnType<typeof setInterval> | undefined;
+  const onStop = () => {
+    if (stopping) return;
+    stopping = true;
+    // Clear the interval immediately so the timer can't fire one more
+    // time during the in-flight settle window — `stopping` already guards
+    // re-entry, but symmetry beats relying on that guard.
+    if (timer) clearInterval(timer);
+    console.log("\n[watch] stopping watch");
+    // Give an in-flight cycle a brief moment to settle, then exit. Don't
+    // hang forever — operator hit Ctrl-C, they want out.
+    setTimeout(() => process.exit(0), inFlight ? 250 : 0);
+  };
+  process.on("SIGINT", onStop);
+  process.on("SIGTERM", onStop);
+
+  timer = setInterval(async () => {
+    if (stopping || inFlight) return;
+    inFlight = true;
+    try {
+      const cycle = await runCycle({ sinceCursor: cursor, isInitial: false });
+      cursor = cycle.nextCursor;
+    } catch (err) {
+      // Don't kill the loop on a transient export error — log and keep
+      // polling. Operator can Ctrl-C if they want to bail.
+      console.error(`[watch] export error: ${(err as Error).message ?? err}`);
+    } finally {
+      inFlight = false;
+    }
+  }, intervalSeconds * 1000);
+  // Keep a reference so the timer isn't GC'd; nothing else holds the loop open.
+  timer.unref?.();
+  // Block forever (signal handler is the exit path).
+  await new Promise(() => {});
+}
+
+// ---------------------------------------------------------------------------
+// Export-watch glue. The git-shell + commit-message logic lives in
+// `./export-watch.ts` for unit-testability; cli.ts just wires it in.
+// ---------------------------------------------------------------------------
+
+async function ensureGitRepo(dir: string): Promise<void> {
+  const { isGitRepo } = await import("./export-watch.ts");
+  if (!(await isGitRepo(dir))) {
+    console.error(
+      `error: --git-commit requires "${dir}" to be a git repo.\n` +
+        `Initialize it first:\n` +
+        `  cd "${dir}" && git init && git add -A && git commit -m "initial"\n` +
+        `Then re-run the export.`,
+    );
+    process.exit(1);
+  }
+}
+
+/**
+ * Snapshot the title of the first changed note since `cursor` — used as the
+ * `{{first_note_title}}` template variable for single-note commit messages.
+ * Best-effort: returns empty string when nothing matches, or when the cursor
+ * is unset (initial export, where "first changed note" is ambiguous).
+ *
+ * Filters at the DB layer via `dateFilter: { field: "updated_at", from:
+ * cursor }` — earlier versions used `sort: "asc"` + `limit: 1` + a
+ * client-side `stamp >= cursor` post-filter, which fetched the vault's
+ * oldest note and almost always failed the filter, rendering the template
+ * variable as empty in production. See vault#346 reviewer note.
+ */
+async function firstChangedNoteTitle(
+  store: ReturnType<typeof import("./vault-store.ts")["getVaultStore"]>,
+  cursor: string | undefined,
+): Promise<string> {
+  if (!cursor) return "";
+  try {
+    const notes = await store.queryNotes({
+      limit: 1,
+      sort: "asc",
+      dateFilter: { field: "updated_at", from: cursor },
+    });
+    return notes[0]?.path ?? notes[0]?.id ?? "";
+  } catch {
+    // Best-effort; template var defaults to empty.
+    return "";
   }
 }
 
@@ -2921,6 +3283,7 @@ Vaults:
                               [--scope vault:read|vault:write|vault:admin]
                               [--install-scope local|user|project]
                               [--vault <name>] [--client claude-code]
+                              [--dry-run]
                                             Install vault MCP into a client config.
                                             From a terminal with no flags: walks you
                                             through a contextual conversation (vault,
@@ -2944,9 +3307,38 @@ Vaults:
                                             directory only). user writes top-level
                                             mcpServers (every project). project
                                             writes ./.mcp.json (check into the repo).
+                                            For headless flows (\`claude -p\` in
+                                            scripts, cron jobs, runners), prefer
+                                            --install-scope user — local-scope
+                                            entries don't propagate to claude -p
+                                            subprocesses; interactive sessions
+                                            from the install directory still see
+                                            local just fine.
                                             --vault <name> targets a specific
                                             vault and keys the entry as
                                             parachute-vault-<name>.
+                                            --dry-run prints the write that would
+                                            happen (target file, entry key, URL)
+                                            without touching disk or hitting the
+                                            hub. Useful for probing.
+
+  parachute-vault mcp-config <vault-name> [--token <pvt_...>] [--base-url <url>]
+                                          [--env-vars]
+                                            Emit the JSON config consumed by
+                                            \`claude -p --mcp-config '<json>'\`.
+                                            Pattern:
+                                              claude -p --mcp-config \\
+                                                "$(parachute-vault mcp-config <name>)" \\
+                                                --strict-mcp-config ...
+                                            --token or PARACHUTE_VAULT_TOKEN env
+                                            supplies the bearer; both absent
+                                            exits 1 with a clear error.
+                                            --base-url overrides the auto-detected
+                                            origin (e.g. tailnet-exposed hubs).
+                                            --env-vars emits the template form
+                                            with \${PARACHUTE_HUB_URL} and
+                                            \${PARACHUTE_VAULT_TOKEN} placeholders
+                                            (safe to commit; expanded at runtime).
 
 Tokens:
   parachute-vault tokens                          List tokens (every vault)
@@ -2993,6 +3385,12 @@ Import/Export:
   parachute-vault export <dir>                        Export vault as portable markdown
                                                        (Obsidian/Logseq/Foam/Quartz-compatible)
   parachute-vault export <dir> --since <iso>          Incremental: only notes updated_at >= ISO
+  parachute-vault export <dir> --watch                Stay alive; re-export on every write
+                                                       (poll every --interval seconds, default 5)
+  parachute-vault export <dir> --git-commit           After export, git add -A + commit in <dir>
+                                                       (combine with --watch for auto-history;
+                                                       template via --git-message-template;
+                                                       --git-push to push after commit)
 
 ── Advanced / standalone ──────────────────────────────────────────────