vault-cortex 0.7.0 → 0.9.0-beta.43

package/README.md

@@ -15,14 +15,20 @@ and data files — see the
 The server runs as a Docker container; this CLI scaffolds the config and
 manages the container so you don't have to.
 
-![npx vault-cortex init — the interactive setup wizard picks a mode, finds your vault, generates the config, and starts the server](https://raw.githubusercontent.com/aliasunder/vault-cortex/main/assets/demo-cli-init.gif)
+![npx vault-cortex init — the interactive setup wizard picks a mode, finds your vault, offers the optional settings, generates the config, and starts the server](https://raw.githubusercontent.com/aliasunder/vault-cortex/main/assets/demo-cli-init.gif)
 
 ## Commands
 
 - [`init`](#init) — interactive setup: scaffold the config, generate the auth
   token, start the server
+- [`configure`](#configure) — change optional settings interactively and
+  restart to apply them
 - [`upgrade`](#upgrade) — pull the latest image and re-create the container;
   your data stays
+- [`restart`](#restart) — re-create the container so your `.env` edits take
+  effect; no image pull
+- [`logs`](#logs) — show the server's logs, live or after the fact
+- [`down`](#down) — stop and remove the container; your data stays
 - [`get-sync-token`](#get-sync-token) — generate an Obsidian Sync auth token
   for remote setups
 
@@ -40,9 +46,14 @@ What it does:
    - **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 `.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
+2. Offers the most common optional settings — memory layer and folder,
+   file tools, semantic search, port, timezone (plus sync direction for
+   remote) — press enter to keep the defaults, or pick the ones you want to
+   change. Skipped when the target directory already has a `.env` (use
+   [`configure`](#configure) instead)
+3. Generates a `.env` file with a securely generated `MCP_AUTH_TOKEN`
+4. Optionally starts the container and waits for the health check
+5. Prints your connection details — the MCP URL, your auth token, and how to
    connect your client
 
 Existing files are never overwritten without asking. During a remote setup,
@@ -63,6 +74,22 @@ Non-interactive example:
 npx vault-cortex@latest init --yes --vault-path /path/to/YourVault
 ```
 
+## configure
+
+Change optional settings on an existing setup:
+
+```bash
+npx vault-cortex@latest configure
+```
+
+Shows the same settings chooser as [`init`](#init) — memory layer and
+folder, file tools, semantic search, port, timezone (plus sync direction
+for remote) — pre-filled with your current values, saves your picks to
+`.env`, and offers to restart the container so they take effect. Settings not in the chooser
+live in `.env` too: edit the value there, then run [`restart`](#restart).
+
+Use `--dir <path>` if your config isn't in `./vault-cortex`.
+
 ## upgrade
 
 Pull the latest image, re-create the container, and verify health:
@@ -88,6 +115,55 @@ include Compose files you can use directly. If you set up with Compose, stick
 with Compose for updates too (`docker compose pull && docker compose up -d`)
 — the CLI and Compose manage the container independently.
 
+## restart
+
+Re-create the container from your `.env` and verify health:
+
+```bash
+npx vault-cortex@latest restart
+```
+
+Use it after editing `.env` — settings are only read when the container is
+created, so a plain `docker restart` won't pick them up, but this will. Unlike
+[`upgrade`](#upgrade), it never pulls a new image: you get the same server
+version back, with your current settings applied.
+
+Use `--dir <path>` if your config isn't in `./vault-cortex`.
+
+## logs
+
+Show the server's logs:
+
+```bash
+npx vault-cortex@latest logs
+```
+
+Flags:
+
+- `--follow` — keep streaming new output until you press ctrl-C
+- `--since <time>` — only logs newer than this (e.g. `10m`, `2h`, or a
+  timestamp)
+- `--dir <path>` — directory containing `.env` (default `./vault-cortex`)
+
+```bash
+npx vault-cortex@latest logs --follow --since 10m
+```
+
+## down
+
+Stop and remove the container:
+
+```bash
+npx vault-cortex@latest down
+```
+
+Safe by design: your vault, search index, and `.env` settings all live
+outside the container, so nothing is lost. Start again any time with
+[`restart`](#restart). Running `down` when nothing is running is fine — it
+just tells you there's nothing to stop.
+
+Use `--dir <path>` if your config isn't in `./vault-cortex`.
+
 ## get-sync-token
 
 Generate an [Obsidian Sync](https://obsidian.md/sync) auth token — needed for
@@ -114,7 +190,8 @@ is available.
 - Node.js >= 20.12 (only for this CLI — the server itself runs in Docker)
 - [Docker](https://docs.docker.com/get-docker/) or a Docker-compatible
   runtime (e.g. OrbStack, Colima, Podman) to run the server — the CLI
-  manages the container through the `docker` command
+  manages the container through the `docker` command (on Linux, see
+  [Docker Engine](https://docs.docker.com/engine/install/))
 
 ## Docs
 

package/dist/configure.js

@@ -0,0 +1,70 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { recreateContainer, requireInitializedDir, resolveDeployment, } from "./lifecycle.js";
+import { applyOptionalSettings, askOptionalSettings, derivePublicUrlOverride, readOptionalValue, } from "./optional-settings.js";
+/**
+ * Interactively changes optional settings in an existing deployment's .env,
+ * then offers to re-create the container so the new values take effect (the
+ * env-file is only read at container creation). The edit succeeds on its own:
+ * a stopped daemon or a declined restart still exits 0 with the settings
+ * saved and a restart hint printed.
+ */
+export const runConfigure = async (flags, deps) => {
+    const { prompts, docker, fetchFn } = deps;
+    prompts.intro("vault-cortex configure");
+    // Editing settings only needs an init'd .env — the full start validation
+    // (VAULT_PATH, PUBLIC_URL) runs later, only when a restart is requested.
+    const initialized = requireInitializedDir(flags.dir, prompts);
+    if (!initialized)
+        return 1;
+    const { targetDir, envFilePath, mode } = initialized;
+    const envContent = readFileSync(envFilePath, "utf8");
+    const pickedOverrides = await askOptionalSettings({ mode, envContent }, prompts);
+    if (Object.keys(pickedOverrides).length === 0) {
+        prompts.log("No settings selected — nothing changed.");
+        prompts.outro("Done.");
+        return 0;
+    }
+    const overrides = derivePublicUrlOverride(envContent, pickedOverrides);
+    const changedNames = Object.keys(overrides);
+    writeFileSync(envFilePath, applyOptionalSettings(envContent, overrides));
+    prompts.log(`Updated ${changedNames.join(", ")} in ${targetDir}/.env.`);
+    // A custom PUBLIC_URL is never rewritten (see derivePublicUrlOverride), but
+    // a port change can still strand it — surface the consequence non-blocking.
+    const currentPublicUrl = readOptionalValue(envContent, "PUBLIC_URL");
+    if (pickedOverrides.PORT && !overrides.PUBLIC_URL && currentPublicUrl) {
+        prompts.warn(`PORT changed — make sure PUBLIC_URL (${currentPublicUrl}) still reaches the server.`);
+    }
+    const restartHint = `Apply the new settings with: npx vault-cortex@latest restart --dir "${targetDir}"`;
+    const daemonStatus = docker.daemonStatus();
+    if (daemonStatus !== "running") {
+        // Settings are already saved — the runtime state only affects the restart
+        // offer, so both non-running states degrade to the hint; restart itself
+        // prints the full install/start guidance when run.
+        prompts.warn(daemonStatus === "not-installed"
+            ? `No container runtime found — settings saved.\n${restartHint}`
+            : `Container runtime not running — settings saved.\n${restartHint}`);
+        prompts.outro("Done.");
+        return 0;
+    }
+    const restartNow = await prompts.confirm("Restart the container now to apply the new settings?", true);
+    if (!restartNow) {
+        prompts.log(restartHint);
+        prompts.outro("Done.");
+        return 0;
+    }
+    // Resolve from disk after the write so the restart honors the new values
+    // (a changed PORT must drive the port mapping and health URL).
+    const deployment = resolveDeployment(flags.dir, prompts);
+    if (!deployment) {
+        // The edit already succeeded — don't let the failed restart read as a
+        // failed configure.
+        prompts.warn(`The restart did not run — your settings are saved. Fix the issue above, then apply them with: npx vault-cortex@latest restart --dir "${targetDir}"`);
+        return 1;
+    }
+    const exitCode = await recreateContainer({ deployment, healthTimeoutMs: deps.healthTimeoutMs }, { prompts, docker, fetchFn });
+    if (exitCode !== 0)
+        return exitCode;
+    prompts.log("Applied the current .env settings.");
+    prompts.outro("Configure complete.");
+    return 0;
+};

package/dist/docker.js

@@ -1,4 +1,4 @@
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 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";
@@ -94,8 +94,36 @@ export const buildDockerRunArgs = (params) => {
     args.push(image);
     return args;
 };
+/**
+ * Builds the `docker logs` args array. Pure function — no I/O — so it's
+ * testable without spawning processes.
+ */
+export const buildDockerLogsArgs = (params) => {
+    const { follow, since } = params;
+    return [
+        "logs",
+        ...(follow ? ["--follow"] : []),
+        ...(since ? ["--since", since] : []),
+        CONTAINER_NAME,
+    ];
+};
+/**
+ * Classifies a `docker info` spawnSync result. ENOENT on the spawn itself
+ * means the `docker` binary is absent (not installed); any other failure —
+ * non-zero exit, timeout, signal kill — means the binary exists but the
+ * daemon isn't answering. `status` alone can't make that call: it is null
+ * for ENOENT *and* for timeouts, so the split keys on the error code.
+ */
+export const classifyDaemonStatus = (spawnResult) => {
+    if (spawnResult.status === 0)
+        return "running";
+    const spawnErrorCode = spawnResult.error && "code" in spawnResult.error
+        ? spawnResult.error.code
+        : undefined;
+    return spawnErrorCode === "ENOENT" ? "not-installed" : "not-running";
+};
 export const createDockerRunner = () => ({
-    isDaemonRunning: () => spawnSync("docker", ["info"], { timeout: 5_000 }).status === 0,
+    daemonStatus: () => classifyDaemonStatus(spawnSync("docker", ["info"], { timeout: 5_000 })),
     // stdout is discarded: `docker run -d` prints only the container ID there,
     // which lands as a raw hex line between the wizard's prompts. stderr stays
     // inherited — image-pull progress and error output print live, which the
@@ -108,12 +136,61 @@ export const createDockerRunner = () => ({
     }).status === 0,
     pullImage: (image) => spawnSync("docker", ["pull", image], { stdio: "inherit" }).status === 0,
     stopAndRemoveContainer: () => spawnSync("docker", ["rm", "-f", CONTAINER_NAME]).status === 0,
+    // `docker rm -f` on a missing container exits 1 on engines < 23 and 0 on
+    // >= 23, so stopAndRemoveContainer's status can't distinguish "already
+    // gone" from "failed" — callers needing idempotent messaging probe
+    // existence first. Output stays piped (discarded): this is a boolean probe.
+    containerExists: () => spawnSync("docker", ["container", "inspect", CONTAINER_NAME]).status === 0,
+    // Async spawn, not spawnSync: --follow streams until interrupted, and the
+    // exit code must be observable after the stream closes.
+    streamLogs: (params) => new Promise((resolveExitCode) => {
+        const child = spawn("docker", buildDockerLogsArgs(params), {
+            stdio: ["ignore", "inherit", "inherit"],
+        });
+        // ctrl-C delivers SIGINT to the whole foreground process group. Node's
+        // default disposition would kill this process before the child's
+        // "close" event fires; this no-op keep-alive lets the docker child
+        // exit on its own SIGINT, the streams flush, and the exit code
+        // propagate. `once` self-removes, so later ctrl-Cs behave normally.
+        process.once("SIGINT", () => { });
+        child.once("error", (spawnError) => {
+            // Event handler, not a catch — but the same "never swallow" rule
+            // applies: without this line a spawn failure is a bare exit 1.
+            process.stderr.write(`vault-cortex: could not run docker logs — ${spawnError.message}\n`);
+            resolveExitCode(1);
+        });
+        // A null code means the child died to a signal — report the shell
+        // convention for ctrl-C (128 + SIGINT = 130).
+        child.once("close", (code) => resolveExitCode(code ?? 130));
+    }),
     runObsidianLogin: (configMountPath) => spawnSync("docker", buildObsidianLoginArgs({
         configMountPath,
         uid: process.getuid?.(),
         gid: process.getgid?.(),
     }), { stdio: "inherit" }).status === 0,
 });
+/** Default bound on a single health request (shared by probe and poll). */
+const PROBE_TIMEOUT_MS = 10_000;
+/**
+ * One-shot health probe: true on an HTTP 2xx, false on any error, non-2xx,
+ * or timeout — false IS the handled outcome for a boolean probe, so the
+ * catch maps rather than logs. Unlike the localhost poll target (which fails
+ * fast with ECONNREFUSED), a public URL behind a dropped firewall rule can
+ * black-hole the TCP handshake for minutes — the abort timeout bounds every
+ * caller.
+ */
+export const probeHealth = async (params, fetchFn) => {
+    const { url, timeoutMs = PROBE_TIMEOUT_MS } = params;
+    try {
+        const response = await fetchFn(url, {
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+};
 /**
  * Polls the health endpoint until it responds OK or the timeout elapses.
  * The first `docker run` pulls the image, so the default window is generous.
@@ -125,19 +202,20 @@ export const createDockerRunner = () => ({
 export const pollHealth = async (params, fetchFn) => {
     const { url, timeoutMs = 120_000, intervalMs = 2_000 } = params;
     const deadline = Date.now() + timeoutMs;
-    const isHealthy = async () => {
-        try {
-            const response = await fetchFn(url);
-            return response.ok;
-        }
-        catch {
-            return false;
-        }
-    };
+    // Each attempt is bounded by the per-request cap AND the remaining budget
+    // (a bare remaining-budget bound would let one black-holed request consume
+    // the whole window with no retries), and the pause never sleeps past the
+    // deadline — so the loop can't overshoot timeoutMs and the caller's
+    // "did not respond within N minutes" message stays accurate.
     while (Date.now() < deadline) {
-        if (await isHealthy())
+        const attemptTimeoutMs = Math.min(PROBE_TIMEOUT_MS, deadline - Date.now());
+        if (await probeHealth({ url, timeoutMs: attemptTimeoutMs }, fetchFn)) {
             return true;
-        await new Promise((resolvePause) => setTimeout(resolvePause, intervalMs));
+        }
+        const pauseMs = Math.min(intervalMs, deadline - Date.now());
+        if (pauseMs > 0) {
+            await new Promise((resolvePause) => setTimeout(resolvePause, pauseMs));
+        }
     }
     return false;
 };

package/dist/env.js

@@ -10,8 +10,9 @@
 // └─────────────────────────────────────────────────────────────────────────┘
 // sync:local-optional:begin
 const LOCAL_OPTIONAL_BLOCK = `# Optional ──────────────────────────────────────────────────
-# To change a setting: edit its value (uncommenting it first if needed),
-# then apply with "npx vault-cortex upgrade" (restart alone does not
+# To change a setting: run "npx vault-cortex@latest configure", or edit
+# its value here (uncommenting it first if needed) and apply with
+# "npx vault-cortex@latest restart" (plain docker restart does not
 # re-read this file).
 
 # Public URL for OAuth issuer URL in discovery metadata (default: http://localhost:8000).
@@ -100,8 +101,9 @@ WINDOWS_MODE=false
 // └─────────────────────────────────────────────────────────────────────────┘
 // sync:remote-optional:begin
 const REMOTE_OPTIONAL_BLOCK = `# Optional ──────────────────────────────────────────────────
-# To change a setting: edit its value (uncommenting it first if needed),
-# then apply with "npx vault-cortex upgrade" (restart alone does not
+# To change a setting: run "npx vault-cortex@latest configure", or edit
+# its value here (uncommenting it first if needed) and apply with
+# "npx vault-cortex@latest restart" (plain docker restart does not
 # re-read this file).
 
 # Your IANA timezone — affects daily note resolution and memory timestamps.
@@ -193,7 +195,7 @@ SYNC_MODE=bidirectional
 `;
 // sync:remote-optional:end
 export const buildLocalEnv = (answers) => `# vault-cortex — local quickstart
-# Generated by \`npx vault-cortex init\`. Full option reference:
+# Generated by \`npx vault-cortex@latest init\`. Full option reference:
 # https://github.com/aliasunder/vault-cortex/blob/main/deploy/local/.env.example
 
 # Required ──────────────────────────────────────────────────
@@ -204,10 +206,6 @@ 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
@@ -218,10 +216,10 @@ VAULT_PASSWORD=${answers.vaultPassword}`;
     const obsidianTokenComment = answers.obsidianAuthToken === ""
         ? `# Obsidian Sync auth token — FILL THIS IN before starting the server.
 # Generate once with:
-#   npx vault-cortex get-sync-token`
+#   npx vault-cortex@latest get-sync-token`
         : `# Obsidian Sync auth token.`;
     return `# vault-cortex — remote quickstart (Obsidian Sync)
-# Generated by \`npx vault-cortex init\`. Full option reference:
+# Generated by \`npx vault-cortex@latest init\`. Full option reference:
 # https://github.com/aliasunder/vault-cortex/blob/main/deploy/remote/.env.example
 
 # Required ──────────────────────────────────────────────────

package/dist/get-sync-token.js

@@ -1,6 +1,7 @@
 import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
+import { buildDaemonNotRunningMessage, buildDockerNotInstalledMessage, } from "./messages.js";
 import { patchEnvObsidianToken } from "./scaffold.js";
 import { expandTilde } from "./vault.js";
 /** Message from an unknown throw — Error instances keep their message. */
@@ -90,14 +91,14 @@ export const captureObsidianToken = (deps, 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");
+                "  npx vault-cortex@latest 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");
+                "  npx vault-cortex@latest get-sync-token");
             return undefined;
         }
         return token;
@@ -113,9 +114,11 @@ export const captureObsidianToken = (deps, tokenDestinationMessage) => {
  */
 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.");
+    const daemonStatus = docker.daemonStatus();
+    if (daemonStatus !== "running") {
+        prompts.error(daemonStatus === "not-installed"
+            ? buildDockerNotInstalledMessage({ nextStep: "\nThen try again." })
+            : buildDaemonNotRunningMessage(" and try again."));
         return 1;
     }
     prompts.intro("vault-cortex get-sync-token");

package/dist/init.js

@@ -1,9 +1,12 @@
+import { existsSync } from "node:fs";
 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 { buildDaemonNotRunningMessage, buildDockerNotInstalledMessage, buildLocalConnectMessage, buildRemoteConnectMessage, } from "./messages.js";
 import { pollHealth } from "./docker.js";
-import { buildFilesToWrite, readEnvPort, writeFiles, } from "./scaffold.js";
+import { reportPublicUrlProbe } from "./lifecycle.js";
+import { applyOptionalSettings, askOptionalSettings, derivePublicUrlOverride, } from "./optional-settings.js";
+import { buildFilesToWrite, readEnvPort, readEnvPublicUrl, writeFiles, } from "./scaffold.js";
 import { generateToken } from "./token.js";
 import { expandTilde, validateVaultPath } from "./vault.js";
 const DEFAULT_TARGET_DIR = "./vault-cortex";
@@ -137,10 +140,14 @@ const reportWrites = (params, prompts) => {
 const offerDockerRun = async (params, deps) => {
     const { targetDir, port, mode, vaultPath } = params;
     const { prompts, docker, fetchFn } = deps;
-    if (!docker.isDaemonRunning()) {
-        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}"`);
+    const daemonStatus = docker.daemonStatus();
+    if (daemonStatus !== "running") {
+        const upgradeHint = `npx vault-cortex@latest upgrade --dir "${targetDir}"`;
+        prompts.warn(daemonStatus === "not-installed"
+            ? buildDockerNotInstalledMessage({
+                nextStep: `\nThen start the server with:\n  ${upgradeHint}`,
+            })
+            : buildDaemonNotRunningMessage(`, then run:\n  ${upgradeHint}`));
         return false;
     }
     const startNow = await prompts.confirm("Start the server now?", true);
@@ -203,10 +210,25 @@ const runLocalInit = async (flags, deps) => {
                 placeholder: DEFAULT_TARGET_DIR,
             }))));
     const token = generateToken();
+    // Guided optional settings: the chooser reads current values from the
+    // generated defaults; enter with nothing picked keeps them all. --yes
+    // skips the chooser (non-interactive by contract), and so does an existing
+    // .env — the conflict prompt defaults to keeping it, which would discard
+    // the answers; settings on an existing deployment are configure's job.
+    const defaultEnvContent = buildLocalEnv({ mcpAuthToken: token, vaultPath });
+    const envAlreadyExists = existsSync(join(targetDir, ".env"));
+    const offerSettingsChooser = !flags.yes && !envAlreadyExists;
+    if (!flags.yes && envAlreadyExists) {
+        prompts.log('Found an existing .env — settings prompts skipped. Adjust settings with "npx vault-cortex@latest configure".');
+    }
+    const optionalOverrides = offerSettingsChooser
+        ? await askOptionalSettings({ mode: "local", envContent: defaultEnvContent }, prompts)
+        : {};
+    const envContent = applyOptionalSettings(defaultEnvContent, derivePublicUrlOverride(defaultEnvContent, optionalOverrides));
     // 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(buildLocalEnv({ mcpAuthToken: token, vaultPath }));
+    const files = buildFilesToWrite(envContent);
     const resolveConflict = flags.yes ? keepExisting : confirmOverwrite(prompts);
     const results = await writeFiles({ targetDir, files }, resolveConflict);
     reportWrites({ targetDir, results }, prompts);
@@ -248,8 +270,10 @@ const runRemoteInit = async (flags, deps) => {
     const vaultName = await askVaultName(prompts);
     // 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()
+    // fails or the user declines. Both non-running states stay silent here —
+    // the paste fallback is fully functional without Docker, and the start
+    // offer surfaces the differentiated runtime guidance later in the flow.
+    const capturedToken = docker.daemonStatus() === "running"
         ? await offerSyncTokenCapture(prompts, docker)
         : undefined;
     // Masked prompt: the sync token is a credential and must not echo into
@@ -262,13 +286,24 @@ const runRemoteInit = async (flags, deps) => {
         ? await prompts.password("Vault encryption password:")
         : undefined;
     const token = generateToken();
-    const envContent = buildRemoteEnv({
+    // Guided optional settings, mirroring the local flow — remote also offers
+    // SYNC_MODE. Remote init is always interactive (no --yes), so only an
+    // existing .env skips the chooser here.
+    const defaultEnvContent = buildRemoteEnv({
         mcpAuthToken: token,
         publicUrl,
         obsidianAuthToken,
         vaultName,
         vaultPassword,
     });
+    const envAlreadyExists = existsSync(join(targetDir, ".env"));
+    if (envAlreadyExists) {
+        prompts.log('Found an existing .env — settings prompts skipped. Adjust settings with "npx vault-cortex@latest configure".');
+    }
+    const optionalOverrides = envAlreadyExists
+        ? {}
+        : await askOptionalSettings({ mode: "remote", envContent: defaultEnvContent }, prompts);
+    const envContent = applyOptionalSettings(defaultEnvContent, derivePublicUrlOverride(defaultEnvContent, optionalOverrides));
     const files = buildFilesToWrite(envContent);
     const results = await writeFiles({ targetDir, files }, confirmOverwrite(prompts));
     reportWrites({ targetDir, results }, prompts);
@@ -281,15 +316,28 @@ const runRemoteInit = async (flags, deps) => {
     if (tokenWritten)
         prompts.log("Generated MCP auth token (saved to .env).");
     const port = readEnvPort(join(targetDir, ".env"));
+    // Like PORT above, PUBLIC_URL comes from the .env actually on disk — a kept
+    // existing file may hold a different URL than this run's prompt, and the
+    // server only reads the file. The prompted value is the fallback for a kept
+    // legacy .env that predates PUBLIC_URL.
+    const effectivePublicUrl = readEnvPublicUrl(join(targetDir, ".env")) ?? publicUrl;
     // Without the sync token the container can't start (init-check-auth fails
     // and s6 stops it), so only offer docker run when it was provided.
     const started = obsidianAuthToken === ""
         ? false
         : await offerDockerRun({ targetDir, port, mode: "remote" }, deps);
+    // The container check above hit localhost on this machine; the public URL
+    // is the ingress path clients actually use — probe it too, informationally.
+    if (started) {
+        await reportPublicUrlProbe(effectivePublicUrl, {
+            prompts,
+            fetchFn: deps.fetchFn,
+        });
+    }
     prompts.print(buildRemoteConnectMessage({
         targetDir,
         token,
-        publicUrl,
+        publicUrl: effectivePublicUrl,
         started,
         obsidianTokenMissing: obsidianAuthToken === "",
         tokenWritten,