vault-cortex 0.4.6 → 0.5.0-beta.28

package/README.md

@@ -21,14 +21,53 @@ container; this CLI scaffolds the config so you don't have to.
 1. Asks how you want to run it:
    - **Local** — Docker on this machine, your vault folder bind-mounted
    - **Remote** — a VPS with [Obsidian Sync](https://obsidian.md/sync), reachable from any device
-2. Generates a `docker-compose.yml` and `.env`, including a securely generated
-   `MCP_AUTH_TOKEN`
-3. Optionally runs `docker compose up -d` and waits for the health check
+2. Generates a `.env` file with a securely generated `MCP_AUTH_TOKEN`
+3. Optionally starts the container and waits for the health check
 4. Prints your connection details — the MCP URL, your auth token, and how to
    connect your client
 
 Existing files are never overwritten without asking.
 
+## Get Sync Token
+
+Generate an Obsidian Sync auth token without leaving the CLI:
+
+```bash
+npx vault-cortex get-sync-token
+```
+
+The command opens the Obsidian login inside Docker. Once you've signed
+in, it captures your token and prints it — nothing to dig out of the
+login output. Use `--dir` to write the token straight into an existing
+`.env` instead:
+
+```bash
+npx vault-cortex get-sync-token --dir ./vault-cortex
+```
+
+During `init --mode remote`, this flow is offered automatically when Docker
+is available.
+
+## Upgrade
+
+Pull the latest image, re-create the container, and verify health:
+
+```bash
+npx vault-cortex upgrade
+```
+
+Run it from the same directory where you ran `init` — it looks for your
+config in `./vault-cortex/.env` (pass `--dir <path>` if you scaffolded
+somewhere else).
+
+Your vault data, search index, and `.env` settings are preserved across
+upgrades — only the server image is replaced. Also applies `.env` changes
+(`docker restart` does not re-read env files).
+
+Prefer Docker Compose? The CLI uses `docker run` for simplicity, but the
+[deploy guides](https://github.com/aliasunder/vault-cortex/blob/main/deploy/)
+include Compose files you can use directly.
+
 ## Non-interactive
 
 ```bash
@@ -41,7 +80,7 @@ Flags: `--mode local|remote`, `--vault-path <path>`, `--dir <path>` (default
 ## Requirements
 
 - Node.js >= 20.12 (only for this CLI — the server itself runs in Docker)
-- [Docker](https://docs.docker.com/get-docker/) to run the server
+- [Docker](https://docs.docker.com/get-docker/) (or any OCI-compatible runtime) to run the server
 
 ## Docs
 

package/dist/docker.js

@@ -1,19 +1,114 @@
 import { spawnSync } from "node:child_process";
-/** The image whose `get-token` entrypoint issues Obsidian Sync auth tokens. */
-export const GET_TOKEN_IMAGE = "ghcr.io/aliasunder/vault-cortex:remote";
+export const LOCAL_IMAGE = "ghcr.io/aliasunder/vault-cortex:latest";
+export const REMOTE_IMAGE = "ghcr.io/aliasunder/vault-cortex:remote";
+export const CONTAINER_NAME = "vault-cortex";
+/**
+ * Builds the `docker run` args for the Obsidian login with a volume mount
+ * that captures the auth token file. Runs `ob login` directly instead of
+ * the image's get-sync-token script: the script's additions are locating and
+ * printing the token, and the mount makes both unnecessary — the CLI reads
+ * the token file itself, and not echoing a credential keeps it out of
+ * terminal scrollback. Pure function for testability.
+ *
+ * On Linux, includes `--user uid:gid` when uid/gid are provided — Node
+ * exposes process.getuid/getgid on every POSIX platform, so in practice the
+ * flag is always set there — keeping the token file host-user-owned. macOS
+ * Docker Desktop translates UIDs automatically, so no flag is needed.
+ */
+export const buildObsidianLoginArgs = (params) => {
+    const { configMountPath, platform = process.platform, uid, gid } = params;
+    const args = [
+        "run",
+        "--rm",
+        "-it",
+        "--entrypoint",
+        "ob",
+        "-v",
+        `${configMountPath}:/home/obsidian/.config`,
+    ];
+    if (platform === "linux" && uid !== undefined && gid !== undefined) {
+        args.push("--user", `${uid}:${gid}`);
+    }
+    args.push(REMOTE_IMAGE, "login");
+    return args;
+};
+/**
+ * Container-internal env vars that must override the user's .env values.
+ * VAULT_PATH in .env is the host path (for the -v mount); the container
+ * must see /vault. PORT/HOST/INDEX_DB_PATH are hardcoded infrastructure.
+ */
+const CONTAINER_ENV_OVERRIDES = [
+    "VAULT_PATH=/vault",
+    "PORT=8000",
+    "HOST=0.0.0.0",
+    "INDEX_DB_PATH=/data/index.db",
+];
+/** Node one-liner matching the compose healthcheck — exits 0 on HTTP 200. */
+const HEALTH_CMD = "node -e \"fetch('http://127.0.0.1:8000/healthz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))\"";
+/**
+ * Builds the `docker run` args array. Pure function — no I/O — so it's
+ * testable without spawning processes.
+ */
+export const buildDockerRunArgs = (params) => {
+    const { mode, envFilePath, port, vaultPath } = params;
+    const image = mode === "local" ? LOCAL_IMAGE : REMOTE_IMAGE;
+    const args = [
+        "run",
+        "-d",
+        "--name",
+        CONTAINER_NAME,
+        "--restart",
+        "unless-stopped",
+        "--env-file",
+        envFilePath,
+        ...CONTAINER_ENV_OVERRIDES.flatMap((override) => ["-e", override]),
+        "-p",
+        `${port}:8000`,
+    ];
+    if (mode === "local") {
+        if (!vaultPath) {
+            throw new Error("vaultPath is required for local mode");
+        }
+        args.push("-v", `${vaultPath}:/vault:rw`);
+        args.push("-v", "vault-cortex_mcp_data:/data");
+        args.push("--health-cmd", HEALTH_CMD);
+        args.push("--health-interval", "15s");
+        args.push("--health-timeout", "5s");
+        args.push("--health-retries", "3");
+        args.push("--health-start-period", "20s");
+    }
+    else {
+        args.push("--hostname", CONTAINER_NAME);
+        args.push("-v", "vault-cortex_vault_data:/vault");
+        args.push("-v", "vault-cortex_mcp_data:/data");
+        args.push("-v", "vault-cortex_obsidian_config:/home/obsidian/.config");
+        args.push("--health-cmd", HEALTH_CMD);
+        args.push("--health-interval", "15s");
+        args.push("--health-timeout", "5s");
+        args.push("--health-retries", "5");
+        args.push("--health-start-period", "60s");
+        args.push("--log-driver", "json-file");
+        args.push("--log-opt", "max-size=10m");
+        args.push("--log-opt", "max-file=3");
+    }
+    args.push(image);
+    return args;
+};
 export const createDockerRunner = () => ({
-    isComposeAvailable: () => spawnSync("docker", ["compose", "version"]).status === 0,
     isDaemonRunning: () => spawnSync("docker", ["info"], { timeout: 5_000 }).status === 0,
-    composeUp: (cwd) => spawnSync("docker", ["compose", "up", "-d"], { cwd, stdio: "inherit" })
+    dockerRun: (params) => spawnSync("docker", buildDockerRunArgs(params), { stdio: "inherit" })
         .status === 0,
-    runGetToken: () => spawnSync("docker", ["run", "--rm", "-it", "--entrypoint", "get-token", GET_TOKEN_IMAGE], {
-        stdio: "inherit",
-    }).status === 0,
+    pullImage: (image) => spawnSync("docker", ["pull", image], { stdio: "inherit" }).status === 0,
+    stopAndRemoveContainer: () => spawnSync("docker", ["rm", "-f", CONTAINER_NAME]).status === 0,
+    runObsidianLogin: (configMountPath) => spawnSync("docker", buildObsidianLoginArgs({
+        configMountPath,
+        uid: process.getuid?.(),
+        gid: process.getgid?.(),
+    }), { stdio: "inherit" }).status === 0,
 });
 /**
  * Polls the health endpoint until it responds OK or the timeout elapses.
- * The first `docker compose up` pulls a ~150MB image, so the default window
- * is generous.
+ * The first `docker run` pulls the image, so the default window is generous.
  *
  * Native Date.now() rather than the server's Luxon convention: the published
  * CLI deliberately keeps its dependency set to two packages, and this is an

package/dist/env.js

@@ -1,22 +1,22 @@
-import { GET_TOKEN_IMAGE } from "./docker.js";
 // Optional env blocks are synced from deploy/<mode>/.env.example by
-// npm run sync:cli-templates. Edit the deploy/ files, then re-run the script.
-// cli/src/templates.test.ts asserts every required `${VAR:?}` in the compose
-// templates has a matching line here, so a new required var breaks CI until
-// these builders learn it.
+// npm run sync:cli-env-blocks. Edit the deploy/ files, then re-run the script.
+// cli/src/templates.test.ts asserts the CLI optional block vars match the
+// deploy/ .env.example optional vars, so a new var breaks CI until both
+// surfaces carry it.
 // ┌─────────────────────────────────────────────────────────────────────────┐
 // │ GENERATED — do not edit between sync markers.                          │
-// │ Source: deploy/local/.env.example → npm run sync:cli-templates         │
+// │ Source: deploy/local/.env.example → npm run sync:cli-env-blocks         │
 // │ The script replaces everything between :begin and :end on each run.    │
 // └─────────────────────────────────────────────────────────────────────────┘
 // sync:local-optional:begin
 const LOCAL_OPTIONAL_BLOCK = `# Optional ──────────────────────────────────────────────────
-# To override a setting: uncomment it, set a value, then apply with
-# "docker compose up -d" (restart alone does not re-read this file).
+# To change a setting: edit its value (uncommenting it first if needed),
+# then apply with "npx vault-cortex upgrade" (restart alone does not
+# re-read this file).
 
 # Public URL for OAuth issuer URL in discovery metadata (default: http://localhost:8000).
 # Override if you expose the server on a different URL (e.g. via a reverse proxy).
-# PUBLIC_URL=http://localhost:8000
+PUBLIC_URL=http://localhost:8000
 
 # Your IANA timezone — affects daily note resolution and memory timestamps.
 # TZ=America/New_York
@@ -27,20 +27,20 @@ const LOCAL_OPTIONAL_BLOCK = `# Optional ─────────────
 # similarity fused via RRF. First startup is slow (~5min for 700 notes);
 # subsequent starts are fast via content-hash caching.
 # Set to false to disable model download and use FTS5 search only.
-# EMBEDDING_ENABLED=true
+EMBEDDING_ENABLED=true
 
 # Reranking mode for hybrid search results (default: blended).
 # "blended" uses a cross-encoder to refine result ordering with
 # position-aware score blending (~200ms added latency).
 # "none" skips reranking for lower latency.
 # Only takes effect when EMBEDDING_ENABLED=true.
-# RERANK_MODE=blended
+RERANK_MODE=blended
 
 # Enable or disable the memory layer (default: true).
 # Set to false to hide memory tools and skip About Me/ creation.
-# MEMORY_ENABLED=true
+MEMORY_ENABLED=true
 # Memory folder name in your vault (default: About Me).
-# MEMORY_DIR=About Me
+MEMORY_DIR=About Me
 
 # Comma-separated folders protected from deletion (default: MEMORY_DIR, Daily Notes).
 # If your daily notes folder has a custom name (e.g. "Journal"), override to include it.
@@ -55,10 +55,10 @@ const LOCAL_OPTIONAL_BLOCK = `# Optional ─────────────
 # SERVICE_DOCUMENTATION_URL=https://github.com/youruser/your-fork
 
 # Host port to expose (default: 8000).
-# PORT=8000
+PORT=8000
 
 # Log verbosity: debug | info | warn | error (default: info).
-# LOG_LEVEL=info
+LOG_LEVEL=info
 
 # Directory for persistent log files inside the container.
 # Unset by default — logs go to stdout only. Set a path to also write
@@ -66,24 +66,25 @@ const LOCAL_OPTIONAL_BLOCK = `# Optional ─────────────
 # LOG_DIR=/data/logs
 
 # Days to retain persistent log files before cleanup (default: 30).
-# LOG_RETENTION_DAYS=30
+LOG_RETENTION_DAYS=30
 
 # Windows users: set this to true. Makes a vault stored on a C: drive work
 # through Docker Desktop (switches the file watcher to polling and note moves
 # to rename-based writes). Only strictly needed when your vault is on a C:
 # drive rather than inside WSL2, but harmless to enable for any Windows setup.
-# WINDOWS_MODE=true
+WINDOWS_MODE=false
 `;
 // sync:local-optional:end
 // ┌─────────────────────────────────────────────────────────────────────────┐
 // │ GENERATED — do not edit between sync markers.                          │
-// │ Source: deploy/remote/.env.example → npm run sync:cli-templates        │
+// │ Source: deploy/remote/.env.example → npm run sync:cli-env-blocks        │
 // │ VAULT_PASSWORD is excluded (handled conditionally in buildRemoteEnv).  │
 // └─────────────────────────────────────────────────────────────────────────┘
 // sync:remote-optional:begin
 const REMOTE_OPTIONAL_BLOCK = `# Optional ──────────────────────────────────────────────────
-# To override a setting: uncomment it, set a value, then apply with
-# "docker compose up -d" (restart alone does not re-read this file).
+# To change a setting: edit its value (uncommenting it first if needed),
+# then apply with "npx vault-cortex upgrade" (restart alone does not
+# re-read this file).
 
 # Your IANA timezone — affects daily note resolution and memory timestamps.
 # TZ=America/New_York
@@ -94,26 +95,26 @@ const REMOTE_OPTIONAL_BLOCK = `# Optional ────────────
 # similarity fused via RRF. First startup is slow (~5min for 700 notes);
 # subsequent starts are fast via content-hash caching.
 # Set to false to disable model download and use FTS5 search only.
-# EMBEDDING_ENABLED=true
+EMBEDDING_ENABLED=true
 
 # Reranking mode for hybrid search results (default: blended).
 # "blended" uses a cross-encoder to refine result ordering with
 # position-aware score blending (~200ms added latency).
 # "none" skips reranking for lower latency.
 # Only takes effect when EMBEDDING_ENABLED=true.
-# RERANK_MODE=blended
+RERANK_MODE=blended
 
 # Windows bind-mount mode (default: false).
 # Set to true when your vault is on a Windows drive (Docker Desktop).
 # Enables polling for the file watcher and rename-based moves across
 # the Docker Desktop/WSL2 bridge.
-# WINDOWS_MODE=false
+WINDOWS_MODE=false
 
 # Enable or disable the memory layer (default: true).
 # Set to false to hide memory tools and skip About Me/ creation.
-# MEMORY_ENABLED=true
+MEMORY_ENABLED=true
 # Memory folder name in your vault (default: About Me).
-# MEMORY_DIR=About Me
+MEMORY_DIR=About Me
 
 # Comma-separated folders protected from deletion (default: MEMORY_DIR, Daily Notes).
 # If your daily notes folder has a custom name (e.g. "Journal"), override to include it.
@@ -128,31 +129,31 @@ const REMOTE_OPTIONAL_BLOCK = `# Optional ────────────
 # SERVICE_DOCUMENTATION_URL=https://github.com/youruser/your-fork
 
 # Host port to expose (default: 8000).
-# PORT=8000
+PORT=8000
 
 # Log verbosity: debug | info | warn | error (default: info).
-# LOG_LEVEL=info
+LOG_LEVEL=info
 
 # Directory for persistent log files inside the container (default: /data/logs).
 # Set to empty to disable file logging (logs still go to stdout either way).
-# LOG_DIR=/data/logs
+LOG_DIR=/data/logs
 
 # Days to retain persistent log files before cleanup (default: 30).
-# LOG_RETENTION_DAYS=30
+LOG_RETENTION_DAYS=30
 
 # User/group IDs for obsidian-sync (default: 1000).
-# PUID=1000
-# PGID=1000
+PUID=1000
+PGID=1000
 
 # Device name shown in Obsidian Sync settings.
-# DEVICE_NAME=vault-cortex
+DEVICE_NAME=vault-cortex
 
 # Obsidian Sync conflict resolution: merge | conflict (default: merge).
 # 'merge' integrates changes automatically; 'conflict' writes a separate conflict file.
-# CONFLICT_STRATEGY=merge
+CONFLICT_STRATEGY=merge
 
 # Sync direction: bidirectional | pull-only | push-only (default: bidirectional).
-# SYNC_MODE=bidirectional
+SYNC_MODE=bidirectional
 `;
 // sync:remote-optional:end
 export const buildLocalEnv = (answers) => `# vault-cortex — local quickstart
@@ -167,6 +168,10 @@ MCP_AUTH_TOKEN=${answers.mcpAuthToken}
 # Absolute path to your Obsidian vault on this machine.
 VAULT_PATH=${answers.vaultPath}
 
+# Public URL for OAuth issuer URL in discovery metadata.
+# Override if you expose the server on a different URL (e.g. via a reverse proxy).
+PUBLIC_URL=http://localhost:8000
+
 ${LOCAL_OPTIONAL_BLOCK}`;
 export const buildRemoteEnv = (answers) => {
     const vaultPasswordLines = answers.vaultPassword === undefined
@@ -175,10 +180,9 @@ export const buildRemoteEnv = (answers) => {
         : `# Vault end-to-end encryption password.
 VAULT_PASSWORD=${answers.vaultPassword}`;
     const obsidianTokenComment = answers.obsidianAuthToken === ""
-        ? `# Obsidian Sync auth token — FILL THIS IN before docker compose up.
+        ? `# Obsidian Sync auth token — FILL THIS IN before starting the server.
 # Generate once with:
-#   docker run --rm -it --entrypoint get-token \\
-#     ${GET_TOKEN_IMAGE}`
+#   npx vault-cortex get-sync-token`
         : `# Obsidian Sync auth token.`;
     return `# vault-cortex — remote quickstart (Obsidian Sync)
 # Generated by \`npx vault-cortex init\`. Full option reference:

package/dist/get-sync-token.js

@@ -0,0 +1,150 @@
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { patchEnvObsidianToken } from "./scaffold.js";
+import { expandTilde } from "./vault.js";
+/** Message from an unknown throw — Error instances keep their message. */
+const describeError = (error) => error instanceof Error ? error.message : String(error);
+/**
+ * Creates the temp dir the container's config mount writes into.
+ * Returns undefined (after warning) when creation fails.
+ */
+const makeTempMountDir = (prompts) => {
+    try {
+        return mkdtempSync(join(tmpdir(), "vault-cortex-sync-token-"));
+    }
+    catch (error) {
+        prompts.warn(`Could not create a temp directory for token capture — ${describeError(error)}`);
+        return undefined;
+    }
+};
+/**
+ * Runs the interactive Obsidian login container. A throw from the Docker
+ * runner is reported and treated the same as a non-zero exit.
+ */
+const runLoginContainer = (configMountPath, deps) => {
+    const { docker, prompts } = deps;
+    try {
+        return docker.runObsidianLogin(configMountPath);
+    }
+    catch (error) {
+        prompts.warn(`Docker run failed — ${describeError(error)}`);
+        return false;
+    }
+};
+/**
+ * Reads the captured token file from the config mount. Returns undefined
+ * when the file is missing, empty, or unreadable — the caller treats all
+ * three as "no token captured".
+ */
+const readCapturedTokenFile = (configMountPath) => {
+    const tokenPath = join(configMountPath, "obsidian-headless", "auth_token");
+    try {
+        if (!existsSync(tokenPath))
+            return undefined;
+        const token = readFileSync(tokenPath, "utf8").trim();
+        return token || undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * Best-effort removal of the temp mount dir. Failing to remove it (e.g.
+ * root-owned files left by the container) must not turn a successful
+ * capture into a failure, so it warns instead of throwing.
+ */
+const removeTempMountDir = (configMountPath, prompts) => {
+    try {
+        rmSync(configMountPath, { recursive: true, force: true });
+    }
+    catch (error) {
+        prompts.warn(`Could not remove temp directory ${configMountPath} — ${describeError(error)}`);
+    }
+};
+/**
+ * Runs the Obsidian login (`ob login`) inside a Docker container with a
+ * volume mount that captures the auth token file. The interactive login
+ * (email, password, MFA) shows in the terminal, but the resulting token is
+ * read from the mounted config dir — never printed, so it stays out of
+ * terminal scrollback.
+ *
+ * tokenDestinationMessage finishes the handoff message by telling the user
+ * where the captured token ends up — the destination differs per flow
+ * (init stores it in the generated .env; the subcommand prints it, or
+ * writes it to an existing .env with --dir).
+ *
+ * Returns the token string on success, undefined on any failure — each
+ * fallible operation is wrapped individually by the helpers above, so no
+ * catch-all is needed here. The bare try/finally only scopes the temp dir
+ * (acquire → release); it has no catch and swallows nothing.
+ */
+export const captureObsidianToken = (deps, tokenDestinationMessage) => {
+    const { prompts } = deps;
+    const configMountPath = makeTempMountDir(prompts);
+    if (!configMountPath)
+        return undefined;
+    try {
+        prompts.log("Handing the terminal to the Obsidian login — it will ask for your " +
+            `account email, password, and MFA code. ${tokenDestinationMessage}`);
+        const loginSucceeded = runLoginContainer(configMountPath, deps);
+        if (!loginSucceeded) {
+            prompts.warn("The Obsidian login did not complete — you can run it later with:\n" +
+                "  npx vault-cortex get-sync-token");
+            return undefined;
+        }
+        const token = readCapturedTokenFile(configMountPath);
+        if (!token) {
+            prompts.warn("The Obsidian login finished, but no token was captured — the " +
+                "token file was missing, empty, or unreadable. You can retry with:\n" +
+                "  npx vault-cortex get-sync-token");
+            return undefined;
+        }
+        return token;
+    }
+    finally {
+        removeTempMountDir(configMountPath, prompts);
+    }
+};
+/**
+ * Subcommand entry: generate an Obsidian Sync token via Docker.
+ * Without --dir, prints the token to stdout.
+ * With --dir, writes it directly to `<dir>/.env`.
+ */
+export const runGetSyncToken = async (flags, deps) => {
+    const { prompts, docker } = deps;
+    if (!docker.isDaemonRunning()) {
+        prompts.error("Container runtime not running — start Docker Desktop, Colima,\n" +
+            "OrbStack, or another Docker-compatible runtime and try again.");
+        return 1;
+    }
+    prompts.intro("vault-cortex get-sync-token");
+    // Resolve the destination up front so the login handoff message can tell
+    // the user where the token will end up.
+    const envFilePath = flags.dir
+        ? join(resolve(expandTilde(flags.dir)), ".env")
+        : undefined;
+    const tokenDestinationMessage = envFilePath
+        ? `The token is captured automatically and written to ${envFilePath}.`
+        : "The token is captured automatically and printed at the end.";
+    const token = captureObsidianToken({ docker, prompts }, tokenDestinationMessage);
+    if (!token) {
+        prompts.error("Could not capture the auth token.");
+        return 1;
+    }
+    if (!envFilePath) {
+        prompts.log("Your OBSIDIAN_AUTH_TOKEN:");
+        prompts.print(`\n  ${token}\n`);
+        prompts.outro("Done.");
+        return 0;
+    }
+    const patched = patchEnvObsidianToken(envFilePath, token);
+    if (!patched) {
+        prompts.error(`Could not patch ${envFilePath} — the file is missing or has no ` +
+            "OBSIDIAN_AUTH_TOKEN line. Run init first.");
+        return 1;
+    }
+    prompts.log(`Token written to ${envFilePath}`);
+    prompts.outro("Done.");
+    return 0;
+};

package/dist/init.js

@@ -1,7 +1,8 @@
 import { join, resolve } from "node:path";
 import { buildLocalEnv, buildRemoteEnv } from "./env.js";
+import { captureObsidianToken } from "./get-sync-token.js";
 import { buildLocalConnectMessage, buildRemoteConnectMessage, } from "./messages.js";
-import { GET_TOKEN_IMAGE, pollHealth } from "./docker.js";
+import { pollHealth } from "./docker.js";
 import { buildFilesToWrite, readEnvPort, writeFiles, } from "./scaffold.js";
 import { generateToken } from "./token.js";
 import { expandTilde, validateVaultPath } from "./vault.js";
@@ -20,28 +21,18 @@ const askMode = async (prompts) => {
             hint: "VPS + Obsidian Sync, access from anywhere",
         },
     ], "local");
-    // The select only offers mode values; the guard narrows without a cast.
     return isMode(selected) ? selected : "local";
 };
-const GET_TOKEN_COMMAND = `docker run --rm -it --entrypoint get-token \\
-  ${GET_TOKEN_IMAGE}`;
 /**
- * Offers to run the vault-cortex image's get-token flow in this terminal.
- * Returns true only when it ran to completion (and so printed a token the
- * user can scroll up to). The handoff log exists because the clack UI gives
- * way to raw docker output — image pull, then the tool's own login prompts.
+ * Offers to auto-capture the Obsidian Sync token via a Docker volume mount.
+ * Returns the captured token string, or undefined when the user declines or
+ * the capture fails (the caller falls back to a paste prompt).
  */
-const offerGetTokenRun = async (prompts, docker) => {
-    const runNow = await prompts.confirm("Run the get-token command now?", true);
+const offerSyncTokenCapture = async (prompts, docker) => {
+    const runNow = await prompts.confirm("Generate the token now?", true);
     if (!runNow)
-        return false;
-    prompts.log("Handing the terminal to get-token — it will ask for your Obsidian " +
-        "account login and print a token at the end.");
-    if (!docker.runGetToken()) {
-        prompts.warn("get-token did not complete — you can run it later and edit .env.");
-        return false;
-    }
-    return true;
+        return undefined;
+    return captureObsidianToken({ docker, prompts }, "The token is captured automatically and stored in your .env — nothing to copy.");
 };
 /**
  * Asks for the vault path, recursing to re-prompt until it gets a usable
@@ -60,8 +51,6 @@ const askVaultPath = async (prompts) => {
         return askVaultPath(prompts);
     }
     if (validation.kind === "warn") {
-        // Renders as: "<path> doesn't look like an Obsidian vault (no .obsidian
-        // folder). Use it anyway? (Y/n)"
         const useAnyway = await prompts.confirm(`${validation.message} Use it anyway?`, true);
         if (!useAnyway)
             return askVaultPath(prompts);
@@ -140,45 +129,46 @@ const reportWrites = (params, prompts) => {
     }
 };
 /**
- * Offers to start the scaffolded stack, walking a gate ladder where each
- * failed gate degrades to instructions instead of an error: compose
- * installed → daemon running → user consents → compose up succeeds →
- * health check passes. Returns true only when the server is confirmed up;
- * the caller uses that to pick the right connect message.
+ * Offers to start the container, walking a gate ladder where each failed
+ * gate degrades to instructions instead of an error: daemon running → user
+ * consents → docker run succeeds → health check passes. Returns true only
+ * when the server is confirmed up.
  */
-const offerComposeUp = async (params, deps) => {
-    const { targetDir, port } = params;
+const offerDockerRun = async (params, deps) => {
+    const { targetDir, port, mode, vaultPath } = params;
     const { prompts, docker, fetchFn } = deps;
-    if (!docker.isComposeAvailable()) {
-        prompts.warn("Docker Compose not found — install Docker to start the server:\n" +
-            "https://docs.docker.com/get-docker/");
-        return false;
-    }
     if (!docker.isDaemonRunning()) {
-        prompts.warn("Docker is installed but not running — start Docker Desktop (or the\n" +
-            "docker service on Linux), then run: docker compose up -d");
+        prompts.warn("Container runtime not running — start Docker Desktop, Colima,\n" +
+            "OrbStack, or another Docker-compatible runtime, then run:\n" +
+            `  npx vault-cortex upgrade --dir "${targetDir}"`);
         return false;
     }
-    const startNow = await prompts.confirm("Start the server now? (docker compose up -d)", true);
+    const startNow = await prompts.confirm("Start the server now?", true);
     if (!startNow)
         return false;
-    if (!docker.composeUp(targetDir)) {
-        prompts.error("docker compose up failed — see output above.");
+    const containerStarted = docker.dockerRun({
+        mode,
+        envFilePath: join(targetDir, ".env"),
+        port,
+        vaultPath,
+    });
+    if (!containerStarted) {
+        prompts.error("docker run failed — see output above.");
         return false;
     }
     const spinner = prompts.spinner();
-    spinner.start("Waiting for the server to come up (first run pulls a ~150MB image)");
+    spinner.start("Waiting for the server to come up (first run may take a moment)");
     const healthy = await pollHealth({ url: `http://127.0.0.1:${port}/healthz` }, fetchFn);
     if (!healthy) {
-        spinner.stop("Server did not respond within 2 minutes — check: docker compose logs");
+        spinner.stop("Server did not respond within 2 minutes — check: docker logs vault-cortex");
         return false;
     }
     spinner.stop("Server is up — health check passed.");
     return true;
 };
 // Local flow: resolve vault path → resolve target dir → generate token →
-// write docker-compose.yml + .env → optionally start the stack → print
-// connect instructions. Returns a process exit code.
+// write .env → optionally start the container → print connect instructions.
+// Returns a process exit code.
 const runLocalInit = async (flags, deps) => {
     const { prompts } = deps;
     // Vault path comes from --vault-path when given and valid; interactive
@@ -188,7 +178,7 @@ const runLocalInit = async (flags, deps) => {
         ? undefined
         : validateVaultPath(flags.vaultPath);
     if (flags.yes) {
-        if (vaultPathResult === undefined || vaultPathResult.kind === "error") {
+        if (!vaultPathResult || vaultPathResult.kind === "error") {
             prompts.error(vaultPathResult?.message ?? "--yes requires --vault-path.");
             return 1;
         }
@@ -200,7 +190,7 @@ const runLocalInit = async (flags, deps) => {
     }
     // A warn-level flag path (no .obsidian/) is accepted without the confirm a
     // prompted path gets — passing the flag is already an explicit choice.
-    const vaultPath = vaultPathResult !== undefined && vaultPathResult.kind !== "error"
+    const vaultPath = vaultPathResult && vaultPathResult.kind !== "error"
         ? vaultPathResult.path
         : await askVaultPath(prompts);
     // expandTilde before resolve: resolve() treats a leading `~` as a literal
@@ -216,7 +206,7 @@ const runLocalInit = async (flags, deps) => {
     // Conflict policy: identical existing files are skipped silently;
     // differing ones prompt per file (default keep). --yes never overwrites —
     // any differing file becomes an exit-1 below, leaving it untouched.
-    const files = buildFilesToWrite("local", buildLocalEnv({ mcpAuthToken: token, vaultPath }));
+    const files = buildFilesToWrite(buildLocalEnv({ mcpAuthToken: token, vaultPath }));
     const resolveConflict = flags.yes ? keepExisting : confirmOverwrite(prompts);
     const results = await writeFiles({ targetDir, files }, resolveConflict);
     reportWrites({ targetDir, results }, prompts);
@@ -226,8 +216,8 @@ const runLocalInit = async (flags, deps) => {
         return 1;
     }
     // When an existing .env was kept, this run's generated token was never
-    // saved — the connect message must point at the token (and PORT) actually on disk,
-    // or a pasted token fails auth with no hint why.
+    // saved — the connect message must point at the token (and PORT) actually
+    // on disk, or a pasted token fails auth with no hint why.
     const envResult = results.find((result) => result.name === ".env");
     const tokenWritten = envResult?.status === "created" || envResult?.status === "overwritten";
     if (tokenWritten)
@@ -236,15 +226,15 @@ const runLocalInit = async (flags, deps) => {
     // --yes is for scripts/CI, so it never starts Docker.
     const started = flags.yes
         ? false
-        : await offerComposeUp({ targetDir, port }, deps);
+        : await offerDockerRun({ targetDir, port, mode: "local", vaultPath }, deps);
     prompts.print(buildLocalConnectMessage({ targetDir, token, started, port, tokenWritten }));
     return 0;
 };
 // Remote flow (VPS + Obsidian Sync): resolve target dir → PUBLIC_URL →
-// VAULT_NAME → Obsidian Sync token (optionally running get-token via
-// Docker) → optional E2E vault password → generate token → write the
-// single-service compose + .env → optionally start → print connect
-// instructions. Always interactive — the sync-token step can't be defaulted.
+// VAULT_NAME → Obsidian Sync token (optionally running the Obsidian login via
+// Docker) → optional E2E vault password → generate token → write .env →
+// optionally start → print connect instructions. Always interactive —
+// the sync-token step can't be defaulted.
 const runRemoteInit = async (flags, deps) => {
     const { prompts, docker } = deps;
     // expandTilde before resolve: resolve() treats a leading `~` as a literal
@@ -256,21 +246,17 @@ const runRemoteInit = async (flags, deps) => {
         }))));
     const publicUrl = await askPublicUrl(prompts);
     const vaultName = await askVaultName(prompts);
-    // The Obsidian Sync token comes from an interactive docker run (the
-    // get-token entrypoint logs into Obsidian). We print the command, offer to
-    // run it when Docker is usable, then ask the user to paste the result —
-    // get-token writes to the terminal, so it can't be captured automatically.
-    // A blank answer is allowed: the .env is written with an empty
-    // OBSIDIAN_AUTH_TOKEN and a fill-this-in comment.
-    prompts.note(GET_TOKEN_COMMAND, "Obsidian Sync token — generate once with");
-    const getTokenRan = docker.isComposeAvailable() && docker.isDaemonRunning()
-        ? await offerGetTokenRun(prompts, docker)
-        : false;
-    // "printed above" is only true when get-token actually ran to completion.
-    const pastePrompt = getTokenRan
-        ? "Paste the Obsidian Sync token printed above (leave blank to fill in .env later):"
-        : "Paste the Obsidian Sync token (leave blank to fill in .env later):";
-    const obsidianAuthToken = (await prompts.text(pastePrompt, { defaultValue: "" })).trim();
+    // Auto-capture the Obsidian Sync token via a Docker volume mount when
+    // the daemon is reachable. Falls back to a paste prompt when capture
+    // fails or the user declines.
+    const capturedToken = docker.isDaemonRunning()
+        ? await offerSyncTokenCapture(prompts, docker)
+        : undefined;
+    // Masked prompt: the sync token is a credential and must not echo into
+    // the terminal or scrollback. An empty submission still means "fill in
+    // .env later" — clack's password prompt accepts blank input.
+    const obsidianAuthToken = capturedToken ??
+        (await prompts.password("Paste the Obsidian Sync token (leave blank to fill in .env later):")).trim();
     const usesEncryption = await prompts.confirm("Does your vault use end-to-end encryption?", false);
     const vaultPassword = usesEncryption
         ? await prompts.password("Vault encryption password:")
@@ -283,24 +269,23 @@ const runRemoteInit = async (flags, deps) => {
         vaultName,
         vaultPassword,
     });
-    const files = buildFilesToWrite("remote", envContent);
+    const files = buildFilesToWrite(envContent);
     const results = await writeFiles({ targetDir, files }, confirmOverwrite(prompts));
     reportWrites({ targetDir, results }, prompts);
     // Same kept-.env handling as the local flow: the server only reads config
     // from the .env on disk, so when an existing file was kept, this run's
     // generated token was never saved (printing it would fail auth) and PORT
-    // may differ from the default — describe the server that will actually
-    // run, not the one this run intended to configure.
+    // may differ from the default.
     const envResult = results.find((result) => result.name === ".env");
     const tokenWritten = envResult?.status === "created" || envResult?.status === "overwritten";
     if (tokenWritten)
         prompts.log("Generated MCP auth token (saved to .env).");
     const port = readEnvPort(join(targetDir, ".env"));
     // Without the sync token the container can't start (init-check-auth fails
-    // and s6 stops it), so only offer compose up when it was provided.
+    // and s6 stops it), so only offer docker run when it was provided.
     const started = obsidianAuthToken === ""
         ? false
-        : await offerComposeUp({ targetDir, port }, deps);
+        : await offerDockerRun({ targetDir, port, mode: "remote" }, deps);
     prompts.print(buildRemoteConnectMessage({
         targetDir,
         token,
@@ -326,9 +311,8 @@ export const runInit = async (flags, deps) => {
         return 1;
     }
     prompts.intro("vault-cortex init");
-    // Mode resolution: explicit --mode wins (validated above, so the guard
-    // narrows it); --yes implies local; otherwise ask, defaulting to local —
-    // it's the activation path.
+    // Mode resolution: explicit --mode wins; --yes implies local; otherwise
+    // ask, defaulting to local — it's the simpler activation path.
     const mode = flags.mode !== undefined && isMode(flags.mode)
         ? flags.mode
         : flags.yes

package/dist/main.js

@@ -1,7 +1,9 @@
 import { createDockerRunner } from "./docker.js";
+import { runGetSyncToken } from "./get-sync-token.js";
 import { runInit } from "./init.js";
 import { buildProgram } from "./program.js";
 import { createPrompts } from "./prompts.js";
+import { runUpgrade } from "./upgrade.js";
 export const run = async (version) => {
     const program = buildProgram({
         version,
@@ -10,6 +12,15 @@ export const run = async (version) => {
             docker: createDockerRunner(),
             fetchFn: fetch,
         }),
+        runUpgrade: (flags) => runUpgrade(flags, {
+            prompts: createPrompts(),
+            docker: createDockerRunner(),
+            fetchFn: fetch,
+        }),
+        runGetSyncToken: (flags) => runGetSyncToken(flags, {
+            prompts: createPrompts(),
+            docker: createDockerRunner(),
+        }),
     });
     await program.parseAsync();
 };

package/dist/messages.js

@@ -12,15 +12,15 @@ const bottomRule = () => paint("dim", `╰${"─".repeat(RULE_WIDTH - 2)}╯`);
 const sectionRule = (label) => paint("dim", `── ${label} ${"─".repeat(Math.max(0, RULE_WIDTH - label.length - 4))}`);
 // targetDir is quoted: these lines are meant to be copy-pasted into a
 // shell, and an unquoted path breaks on spaces or special characters.
-const composeUpCommand = (targetDir) => `cd "${targetDir}" && docker compose up -d`;
-const startServerLine = (targetDir) => `Start the server:\n  ${composeUpCommand(targetDir)}`;
+const upgradeCommand = (targetDir) => `npx vault-cortex upgrade --dir "${targetDir}"`;
+const startServerLine = (targetDir) => `Start the server:\n  ${upgradeCommand(targetDir)}`;
 /** Remote start line: running, blocked on the missing sync token, or ready to start. */
 const remoteStartLine = (params) => {
     const { targetDir, started, obsidianTokenMissing } = params;
     if (started)
         return "The server is running.";
     if (obsidianTokenMissing) {
-        return `Fill in OBSIDIAN_AUTH_TOKEN in ${targetDir}/.env, then start the server:\n  ${composeUpCommand(targetDir)}`;
+        return `Fill in OBSIDIAN_AUTH_TOKEN in ${targetDir}/.env, then start the server:\n  ${upgradeCommand(targetDir)}`;
     }
     return startServerLine(targetDir);
 };
@@ -62,10 +62,8 @@ const curlGuidance = (mcpUrl) => `Clients without OAuth, scripts, and curl send
   curl -H "Authorization: Bearer <token>" ${mcpUrl}`;
 const smokeTest = (healthUrl) => `Smoke test:
   curl ${healthUrl}`;
-// Compose does not pull new images on `up` — without this hint users stay
-// on the image from init day forever while believing they track releases.
 const updateGuidance = (targetDir) => `Update to the latest release:
-  cd "${targetDir}" && docker compose pull && docker compose up -d`;
+  ${upgradeCommand(targetDir)}`;
 /**
  * Local-mode "Connect" message. port comes from the .env on disk: a kept file
  * may override the default, so the message must describe the server that will
@@ -114,7 +112,7 @@ ${sectionRule("Settings")}
 
 Optional settings (timezone, memory folder, port, logging) are commented
 out in ${targetDir}/.env — uncomment, set a value, then apply with
-"docker compose up -d" (restart alone does not re-read .env).
+"npx vault-cortex upgrade" (restart alone does not re-read .env).
 
 ${updateGuidance(targetDir)}
 
@@ -142,7 +140,8 @@ export const buildRemoteConnectMessage = (params) => {
     // know which case it is, so the http branch states it rather than asking.
     // Case-insensitive: askPublicUrl stores the scheme as typed, so an HTTPS://
     // input is valid and must still route to the https branch.
-    const clientGuidance = publicUrl.toLowerCase().startsWith("https://")
+    const isHttps = publicUrl.toLowerCase().startsWith("https://");
+    const clientGuidance = isHttps
         ? `${connectGuidance(`${publicUrl}/mcp`)}
 
 Reachable over https from any MCP client — Claude Desktop, claude.ai (web
@@ -174,8 +173,8 @@ ${sectionRule("Settings")}
 
 Optional settings (timezone, memory folder, port, logging, sync
 behavior) are commented out in ${targetDir}/.env — uncomment, set a
-value, then apply with "docker compose up -d" (restart alone does not
-re-read .env).
+value, then apply with "npx vault-cortex upgrade" (restart alone does
+not re-read .env).
 
 ${updateGuidance(targetDir)}
 

package/dist/program.js

@@ -7,7 +7,7 @@ export const buildProgram = (options) => {
         .version(options.version);
     program
         .command("init")
-        .description("Scaffold docker-compose.yml + .env and optionally start the server")
+        .description("Scaffold .env and optionally start the server")
         .option("--mode <mode>", 'deployment mode: "local" (default) or "remote"')
         .option("--vault-path <path>", "absolute path to your Obsidian vault (local mode)")
         .option("--dir <path>", "directory to write config files into (default: ./vault-cortex)")
@@ -15,7 +15,20 @@ export const buildProgram = (options) => {
         .action(async (flags) => {
         process.exitCode = await options.runInit(flags);
     });
-    // Bare `npx vault-cortex` shows help instead of a "missing command" error.
+    program
+        .command("upgrade")
+        .description("Pull the latest image, re-create the container, and verify health")
+        .option("--dir <path>", "directory containing .env (default: ./vault-cortex)")
+        .action(async (flags) => {
+        process.exitCode = await options.runUpgrade(flags);
+    });
+    program
+        .command("get-sync-token")
+        .description("Generate an Obsidian Sync auth token via Docker and print it or write it to .env")
+        .option("--dir <path>", "directory containing .env to update with the token")
+        .action(async (flags) => {
+        process.exitCode = await options.runGetSyncToken(flags);
+    });
     program.action(() => {
         program.help();
     });

package/dist/scaffold.js

@@ -1,18 +1,16 @@
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
 import { join } from "node:path";
-import { fileURLToPath } from "node:url";
-/** Default host port — matches the compose templates' `${PORT:-8000}`. */
+/** Default host port — matches the container's internal port. */
 export const DEFAULT_PORT = 8000;
 /** Matches an active (uncommented) PORT line in a .env file. */
 const ENV_PORT_LINE = /^PORT=(\d+)\s*$/m;
-/**
- * Reads the bundled docker-compose template for a mode. The templates are
- * verbatim copies of deploy/<mode>/docker-compose.yml, shipped inside the
- * npm package (kept in sync by cli/src/__tests__/templates.test.ts).
- */
-export const readComposeTemplate = (mode) => readFileSync(fileURLToPath(new URL(`../templates/${mode}/docker-compose.yml`, import.meta.url)), "utf8");
-export const buildFilesToWrite = (mode, envContent) => [
-    { name: "docker-compose.yml", content: readComposeTemplate(mode) },
+/** Matches an active (uncommented) VAULT_PATH line in a .env file. */
+const ENV_VAULT_PATH_LINE = /^VAULT_PATH=(.+)\s*$/m;
+/** Matches an active (uncommented) PUBLIC_URL line. */
+const ENV_PUBLIC_URL_LINE = /^PUBLIC_URL=/m;
+/** Matches an active (uncommented) OBSIDIAN_AUTH_TOKEN line. */
+const OBSIDIAN_AUTH_TOKEN_LINE = /^OBSIDIAN_AUTH_TOKEN=/m;
+export const buildFilesToWrite = (envContent) => [
     // .env holds the bearer token (and possibly a vault password) — owner-only.
     { name: ".env", content: envContent, mode: 0o600 },
 ];
@@ -26,7 +24,57 @@ export const readEnvPort = (envFilePath) => {
     if (!existsSync(envFilePath))
         return DEFAULT_PORT;
     const match = ENV_PORT_LINE.exec(readFileSync(envFilePath, "utf8"));
-    return match === null ? DEFAULT_PORT : Number(match[1]);
+    return match ? Number(match[1]) : DEFAULT_PORT;
+};
+/**
+ * Reads the host vault path from a .env file. Returns undefined when the
+ * file is missing or has no uncommented VAULT_PATH line.
+ */
+export const readEnvVaultPath = (envFilePath) => {
+    if (!existsSync(envFilePath))
+        return undefined;
+    const match = ENV_VAULT_PATH_LINE.exec(readFileSync(envFilePath, "utf8"));
+    return match?.[1].trim();
+};
+/**
+ * Returns true when the .env file has an active (uncommented) PUBLIC_URL line.
+ * Used by upgrade to detect .env files from the old compose-based CLI, where
+ * PUBLIC_URL was provided by docker-compose defaults rather than the .env.
+ */
+export const hasEnvPublicUrl = (envFilePath) => {
+    if (!existsSync(envFilePath))
+        return false;
+    return ENV_PUBLIC_URL_LINE.test(readFileSync(envFilePath, "utf8"));
+};
+/**
+ * Detects the deployment mode from a .env file. Remote mode requires
+ * OBSIDIAN_AUTH_TOKEN (absent from local). Returns undefined when the
+ * .env file does not exist.
+ */
+export const detectMode = (envFilePath) => {
+    if (!existsSync(envFilePath))
+        return undefined;
+    const content = readFileSync(envFilePath, "utf8");
+    return OBSIDIAN_AUTH_TOKEN_LINE.test(content) ? "remote" : "local";
+};
+/**
+ * Patches the OBSIDIAN_AUTH_TOKEN value in an existing .env file.
+ * Returns true when the patch succeeded, false when the file is missing
+ * or has no active OBSIDIAN_AUTH_TOKEN line (e.g. a local-mode .env).
+ */
+export const patchEnvObsidianToken = (envFilePath, token) => {
+    if (!existsSync(envFilePath))
+        return false;
+    const content = readFileSync(envFilePath, "utf8");
+    /** Matches the full OBSIDIAN_AUTH_TOKEN line for replacement. */
+    const fullTokenLine = /^OBSIDIAN_AUTH_TOKEN=.*$/m;
+    if (!fullTokenLine.test(content))
+        return false;
+    // Function replacement avoids $ pattern interpretation ($&, $', etc.)
+    // that String.prototype.replace applies to string replacements.
+    const patched = content.replace(fullTokenLine, () => `OBSIDIAN_AUTH_TOKEN=${token}`);
+    writeFileSync(envFilePath, patched);
+    return true;
 };
 /**
  * Writes the files into targetDir (created if missing). Existing files

package/dist/upgrade.js

@@ -0,0 +1,66 @@
+import { join, resolve } from "node:path";
+import { CONTAINER_NAME, LOCAL_IMAGE, REMOTE_IMAGE, pollHealth, } from "./docker.js";
+import { detectMode, hasEnvPublicUrl, readEnvPort, readEnvVaultPath, } from "./scaffold.js";
+import { expandTilde } from "./vault.js";
+const DEFAULT_TARGET_DIR = "./vault-cortex";
+export const runUpgrade = async (flags, deps) => {
+    const { prompts, docker, fetchFn } = deps;
+    prompts.intro("vault-cortex upgrade");
+    const targetDir = resolve(expandTilde(flags.dir ?? DEFAULT_TARGET_DIR));
+    const envFilePath = join(targetDir, ".env");
+    const mode = detectMode(envFilePath);
+    if (!mode) {
+        prompts.error(`No .env found in ${targetDir} — run \`npx vault-cortex init\` first.`);
+        return 1;
+    }
+    const port = readEnvPort(envFilePath);
+    const vaultPath = mode === "local" ? readEnvVaultPath(envFilePath) : undefined;
+    if (mode === "local" && !vaultPath) {
+        prompts.error(`VAULT_PATH is empty or missing in ${targetDir}/.env — cannot start the container.`);
+        return 1;
+    }
+    if (mode === "local" && !hasEnvPublicUrl(envFilePath)) {
+        prompts.error(`PUBLIC_URL not found in ${targetDir}/.env — the server requires it.\n` +
+            `Add this line to your .env:\n  PUBLIC_URL=http://localhost:${port}`);
+        return 1;
+    }
+    const image = mode === "local" ? LOCAL_IMAGE : REMOTE_IMAGE;
+    if (!docker.isDaemonRunning()) {
+        prompts.error("Container runtime not running — start Docker Desktop, Colima,\n" +
+            "OrbStack, or another Docker-compatible runtime.");
+        return 1;
+    }
+    const spinner = prompts.spinner();
+    spinner.start(`Pulling ${image}`);
+    const imagePulled = docker.pullImage(image);
+    if (!imagePulled) {
+        spinner.stop("Image pull failed — see output above.");
+        return 1;
+    }
+    spinner.stop("Image pulled.");
+    docker.stopAndRemoveContainer();
+    prompts.log("Starting container...");
+    const containerStarted = docker.dockerRun({
+        mode,
+        envFilePath,
+        port,
+        vaultPath,
+    });
+    if (!containerStarted) {
+        prompts.error("docker run failed — see output above.");
+        return 1;
+    }
+    spinner.start("Waiting for the server to come up");
+    const healthy = await pollHealth({
+        url: `http://127.0.0.1:${port}/healthz`,
+        timeoutMs: deps.healthTimeoutMs,
+    }, fetchFn);
+    if (!healthy) {
+        spinner.stop(`Server did not respond within 2 minutes — check: docker logs ${CONTAINER_NAME}`);
+        return 1;
+    }
+    spinner.stop("Server is up — health check passed.");
+    prompts.log("Your vault data, search index, and settings are preserved.");
+    prompts.outro("Upgrade complete.");
+    return 0;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vault-cortex",
-  "version": "0.4.6",
+  "version": "0.5.0-beta.28",
   "description": "Set up a Vault Cortex MCP server for your Obsidian vault in one command: npx vault-cortex init",
   "license": "MIT",
   "type": "module",
@@ -9,7 +9,6 @@
   },
   "files": [
     "dist",
-    "templates",
     "README.md"
   ],
   "engines": {

package/templates/local/docker-compose.yml

@@ -1,66 +0,0 @@
-# vault-cortex — local quickstart
-#
-# Run vault-cortex against a local Obsidian vault with just Docker.
-# No cloud, no Obsidian Sync, no AWS — just your vault folder and a bearer token.
-#
-# 1. cp .env.example .env   (then fill in MCP_AUTH_TOKEN and VAULT_PATH)
-# 2. docker compose up
-# 3. Connect your MCP client to http://localhost:8000/mcp
-#    (Claude Desktop's connector dialog requires https — register a
-#    localhost server via the mcp-remote bridge; see the local README)
-#
-# Full docs: https://github.com/aliasunder/vault-cortex
-
-name: vault-cortex
-
-services:
-  vault-cortex:
-    image: ghcr.io/aliasunder/vault-cortex:latest
-    container_name: vault-cortex
-    restart: unless-stopped
-    environment:
-      PORT: "8000"
-      HOST: "0.0.0.0"
-      VAULT_PATH: /vault
-      INDEX_DB_PATH: /data/index.db
-      MCP_AUTH_TOKEN: "${MCP_AUTH_TOKEN:?Set MCP_AUTH_TOKEN in .env — see .env.example}"
-      PUBLIC_URL: ${PUBLIC_URL:-http://localhost:8000}
-      EMBEDDING_ENABLED: ${EMBEDDING_ENABLED:-true}
-      RERANK_MODE: ${RERANK_MODE:-blended}
-      MEMORY_ENABLED: ${MEMORY_ENABLED:-true}
-      MEMORY_DIR: ${MEMORY_DIR:-About Me}
-      LOG_LEVEL: ${LOG_LEVEL:-info}
-      LOG_DIR: ${LOG_DIR:-}
-      LOG_RETENTION_DAYS: ${LOG_RETENTION_DAYS:-30}
-      TZ: ${TZ:-UTC}
-      # Windows: set WINDOWS_MODE=true in .env when your vault is on a C: drive
-      # (polling watcher + rename-based moves across the Docker Desktop/WSL2 bridge).
-      WINDOWS_MODE: ${WINDOWS_MODE:-false}
-      # Optional overrides. When unset, the server applies smart defaults
-      # (<MEMORY_DIR> below is the resolved MEMORY_DIR value, default "About Me"):
-      #   PROTECTED_PATHS           default: "<MEMORY_DIR>, Daily Notes" (blocked from vault_delete_note)
-      #   ORPHAN_EXCLUDE_FOLDERS    default: "Daily Notes, Templates, <MEMORY_DIR>" (excluded from vault_find_orphans)
-      #   SERVICE_DOCUMENTATION_URL default: https://github.com/aliasunder/vault-cortex
-      PROTECTED_PATHS: ${PROTECTED_PATHS:-}
-      ORPHAN_EXCLUDE_FOLDERS: ${ORPHAN_EXCLUDE_FOLDERS:-}
-      SERVICE_DOCUMENTATION_URL: ${SERVICE_DOCUMENTATION_URL:-}
-    volumes:
-      - "${VAULT_PATH:?Set VAULT_PATH to your Obsidian vault folder}:/vault:rw"
-      - mcp_data:/data
-    ports:
-      - "${PORT:-8000}:8000"
-    healthcheck:
-      test:
-        [
-          "CMD",
-          "node",
-          "-e",
-          "fetch('http://127.0.0.1:8000/healthz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))",
-        ]
-      interval: 15s
-      timeout: 5s
-      retries: 3
-      start_period: 20s
-
-volumes:
-  mcp_data:

package/templates/remote/docker-compose.yml

@@ -1,85 +0,0 @@
-# vault-cortex — remote quickstart (Obsidian Sync)
-#
-# Run vault-cortex on a VPS with Obsidian Sync for remote access from any device.
-# One container: the :remote image bundles Obsidian Sync and the MCP server
-# under s6-overlay supervision.
-#
-# 1. cp .env.example .env   (then fill in required values)
-# 2. docker compose up -d
-# 3. Connect your MCP client to http://<your-server>:8000/mcp
-#
-# Compose is optional — the same container runs with plain `docker run`
-# (or podman/nerdctl); see the README for the one-liner.
-#
-# Full docs: https://github.com/aliasunder/vault-cortex
-
-name: vault-cortex
-
-services:
-  vault-cortex:
-    image: ghcr.io/aliasunder/vault-cortex:remote
-    container_name: vault-cortex
-    hostname: ${DEVICE_NAME:-vault-cortex}
-    restart: unless-stopped
-    environment:
-      # --- Obsidian Sync (s6 init chain + sync service) ---
-      OBSIDIAN_AUTH_TOKEN: "${OBSIDIAN_AUTH_TOKEN:?Set OBSIDIAN_AUTH_TOKEN — see .env.example}"
-      VAULT_NAME: "${VAULT_NAME:?Set VAULT_NAME to your Obsidian vault name (case-sensitive)}"
-      VAULT_PASSWORD: ${VAULT_PASSWORD:-}
-      PUID: ${PUID:-1000}
-      PGID: ${PGID:-1000}
-      DEVICE_NAME: ${DEVICE_NAME:-vault-cortex}
-      CONFLICT_STRATEGY: ${CONFLICT_STRATEGY:-merge}
-      SYNC_MODE: ${SYNC_MODE:-bidirectional}
-      # --- MCP server ---
-      PORT: "8000"
-      HOST: "0.0.0.0"
-      VAULT_PATH: /vault
-      INDEX_DB_PATH: /data/index.db
-      MCP_AUTH_TOKEN: "${MCP_AUTH_TOKEN:?Set MCP_AUTH_TOKEN in .env — see .env.example}"
-      PUBLIC_URL: "${PUBLIC_URL:?Set PUBLIC_URL to your server's public URL}"
-      EMBEDDING_ENABLED: ${EMBEDDING_ENABLED:-true}
-      RERANK_MODE: ${RERANK_MODE:-blended}
-      MEMORY_ENABLED: ${MEMORY_ENABLED:-true}
-      MEMORY_DIR: ${MEMORY_DIR:-About Me}
-      LOG_LEVEL: ${LOG_LEVEL:-info}
-      LOG_DIR: ${LOG_DIR:-/data/logs}
-      LOG_RETENTION_DAYS: ${LOG_RETENTION_DAYS:-30}
-      TZ: ${TZ:-UTC}
-      WINDOWS_MODE: ${WINDOWS_MODE:-false}
-      # Optional overrides. When unset, the server applies smart defaults
-      # (<MEMORY_DIR> below is the resolved MEMORY_DIR value, default "About Me"):
-      #   PROTECTED_PATHS           default: "<MEMORY_DIR>, Daily Notes" (blocked from vault_delete_note)
-      #   ORPHAN_EXCLUDE_FOLDERS    default: "Daily Notes, Templates, <MEMORY_DIR>" (excluded from vault_find_orphans)
-      #   SERVICE_DOCUMENTATION_URL default: https://github.com/aliasunder/vault-cortex
-      PROTECTED_PATHS: ${PROTECTED_PATHS:-}
-      ORPHAN_EXCLUDE_FOLDERS: ${ORPHAN_EXCLUDE_FOLDERS:-}
-      SERVICE_DOCUMENTATION_URL: ${SERVICE_DOCUMENTATION_URL:-}
-    volumes:
-      - vault_data:/vault
-      - mcp_data:/data
-      - obsidian_config:/home/obsidian/.config
-    ports:
-      - "0.0.0.0:${PORT:-8000}:8000"
-    # start_period covers the s6 init chain (Obsidian login + sync-setup)
-    # that runs before the MCP server boots.
-    healthcheck:
-      test:
-        [
-          "CMD",
-          "node",
-          "-e",
-          "fetch('http://127.0.0.1:8000/healthz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))",
-        ]
-      interval: 15s
-      timeout: 5s
-      retries: 5
-      start_period: 60s
-    logging:
-      driver: json-file
-      options: { max-size: "10m", max-file: "3" }
-
-volumes:
-  vault_data:
-  mcp_data:
-  obsidian_config: