vault-cortex 0.4.4 → 0.4.6-beta.26

package/README.md

@@ -8,25 +8,40 @@ npx vault-cortex@latest init
 ```
 
 Vault Cortex is a standalone, remote-capable MCP server for Obsidian vaults —
-26 tools for hybrid search (FTS5 + vector + cross-encoder reranking), notes, frontmatter, links, daily notes,
-task queries (Tasks-plugin emoji + Dataview inline-field formats), and
-a structured memory layer, plus 3 guided prompts (orientation, memory review,
-daily review). It runs as a Docker container; this CLI scaffolds the config so
-you don't have to.
+Tools for hybrid search (FTS5 + vector + cross-encoder reranking, with
+tag/folder/property/date filters), notes, frontmatter, links, daily notes,
+Kanban-aware task management (query + complete/move/reprioritize, parsing Tasks-plugin emoji + Dataview inline-field formats), and
+a structured memory layer with topic recall (the current take plus the
+dated history behind it), plus guided prompts (orientation, memory
+review, daily review). It runs as a Docker
+container; this CLI scaffolds the config so you don't have to.
 
 ## What `init` does
 
 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.
 
+## Upgrade
+
+Pull the latest image, re-create the container, and verify health:
+
+```bash
+npx vault-cortex upgrade
+```
+
+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
@@ -39,7 +54,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,80 @@
 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";
+/**
+ * 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,
+    runGetToken: () => spawnSync("docker", ["run", "--rm", "-it", "--entrypoint", "get-token", REMOTE_IMAGE], { 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,11 +1,22 @@
-import { GET_TOKEN_IMAGE } from "./docker.js";
-// The optional blocks mirror the canonical deploy/<mode>/.env.example files.
-// 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.
+import { REMOTE_IMAGE } from "./docker.js";
+// Optional env blocks are synced from deploy/<mode>/.env.example by
+// 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-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).
+# "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
 
 # Your IANA timezone — affects daily note resolution and memory timestamps.
 # TZ=America/New_York
@@ -63,9 +74,16 @@ const LOCAL_OPTIONAL_BLOCK = `# Optional ─────────────
 # drive rather than inside WSL2, but harmless to enable for any Windows setup.
 # WINDOWS_MODE=true
 `;
+// sync:local-optional:end
+// ┌─────────────────────────────────────────────────────────────────────────┐
+// │ GENERATED — do not edit between sync markers.                          │
+// │ 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).
+# "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
@@ -130,11 +148,13 @@ const REMOTE_OPTIONAL_BLOCK = `# Optional ────────────
 # 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
 
 # Sync direction: bidirectional | pull-only | push-only (default: bidirectional).
 # SYNC_MODE=bidirectional
 `;
+// sync:remote-optional:end
 export const buildLocalEnv = (answers) => `# vault-cortex — local quickstart
 # Generated by \`npx vault-cortex init\`. Full option reference:
 # https://github.com/aliasunder/vault-cortex/blob/main/deploy/local/.env.example
@@ -147,6 +167,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
@@ -155,10 +179,10 @@ 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}`
+#     ${REMOTE_IMAGE}`
         : `# Obsidian Sync auth token.`;
     return `# vault-cortex — remote quickstart (Obsidian Sync)
 # Generated by \`npx vault-cortex init\`. Full option reference:

package/dist/init.js

@@ -1,7 +1,7 @@
 import { join, resolve } from "node:path";
 import { buildLocalEnv, buildRemoteEnv } from "./env.js";
 import { buildLocalConnectMessage, buildRemoteConnectMessage, } from "./messages.js";
-import { GET_TOKEN_IMAGE, pollHealth } from "./docker.js";
+import { REMOTE_IMAGE, pollHealth } from "./docker.js";
 import { buildFilesToWrite, readEnvPort, writeFiles, } from "./scaffold.js";
 import { generateToken } from "./token.js";
 import { expandTilde, validateVaultPath } from "./vault.js";
@@ -20,11 +20,10 @@ 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}`;
+  ${REMOTE_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
@@ -37,7 +36,8 @@ const offerGetTokenRun = async (prompts, docker) => {
         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()) {
+    const tokenGenerated = docker.runGetToken();
+    if (!tokenGenerated) {
         prompts.warn("get-token did not complete — you can run it later and edit .env.");
         return false;
     }
@@ -60,8 +60,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 +138,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 +187,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 +199,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 +215,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 +225,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 +235,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.
+// 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
@@ -263,7 +262,7 @@ const runRemoteInit = async (flags, deps) => {
     // 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()
+    const getTokenRan = docker.isDaemonRunning()
         ? await offerGetTokenRun(prompts, docker)
         : false;
     // "printed above" is only true when get-token actually ran to completion.
@@ -283,24 +282,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 +324,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

@@ -2,6 +2,7 @@ import { createDockerRunner } from "./docker.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 +11,11 @@ export const run = async (version) => {
             docker: createDockerRunner(),
             fetchFn: fetch,
         }),
+        runUpgrade: (flags) => runUpgrade(flags, {
+            prompts: createPrompts(),
+            docker: createDockerRunner(),
+            fetchFn: fetch,
+        }),
     });
     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,13 @@ 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.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,38 @@ 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";
 };
 /**
  * Writes the files into targetDir (created if missing). Existing files

package/dist/upgrade.js

@@ -0,0 +1,65 @@
+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.outro("Upgrade complete.");
+    return 0;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vault-cortex",
-  "version": "0.4.4",
+  "version": "0.4.6-beta.26",
   "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: