gnosys 5.11.0 → 5.11.1

package/dist/cli.js

@@ -26,6 +26,7 @@ import { loadConfig, generateConfigTemplate, DEFAULT_CONFIG, writeConfig, resolv
 import { getLLMProvider, isProviderAvailable } from "./lib/llm.js";
 import { GnosysDB } from "./lib/db.js";
 import { logError } from "./lib/log.js";
+import { getSecureStorageSetupHint } from "./lib/platform.js";
 import { createProjectIdentity, readProjectIdentity, findProjectIdentity, migrateProject } from "./lib/projectIdentity.js";
 import { setPreference, getPreference, getAllPreferences, deletePreference, KNOWN_PREFERENCE_KEYS, suggestPreferenceKey } from "./lib/preferences.js";
 import { syncToTarget } from "./lib/rulesGen.js";
@@ -2836,7 +2837,7 @@ program
         const envVar = envVarMap[providerName];
         if (envVar) {
             console.error(`No LLM provider available. Configured default is "${providerName}" but its key wasn't found. ` +
-                `Set ${envVar}, run 'gnosys setup' to store one in the macOS Keychain, or add llm.${providerName}.apiKey to gnosys.json.`);
+                `Set ${envVar}, run 'gnosys setup' to store one in ${getSecureStorageSetupHint()}, or add llm.${providerName}.apiKey to gnosys.json.`);
         }
         else {
             console.error(`No LLM provider available. Provider "${providerName}" is not reachable. Run 'gnosys setup' to configure one.`);
@@ -4460,7 +4461,8 @@ program
         setInterval(runMaintenance, SIX_HOURS);
         console.error("[maintenance] Background maintenance enabled (every 6 hours)");
     }
-    await import("./index.js");
+    const { startMcpServer } = await import("./index.js");
+    await startMcpServer();
 });
 // ─── gnosys recall ───────────────────────────────────────────────────────
 program

package/dist/index.d.ts

@@ -13,3 +13,5 @@ export declare function registerCapabilities(s: McpServer): void;
  * need any of these should `await ensureHeavyDeps()` first.
  */
 export declare function ensureHeavyDeps(): Promise<void>;
+/** Start the MCP server (stdio or http). Called by `gnosys serve` and when invoked as `gnosys-mcp`. */
+export declare function startMcpServer(): Promise<void>;

package/dist/index.js

@@ -2955,7 +2955,8 @@ async function initHeavyDeps() {
     heavyDepsReadyResolve?.();
 }
 // ─── Start the server ────────────────────────────────────────────────────
-async function main() {
+/** Start the MCP server (stdio or http). Called by `gnosys serve` and when invoked as `gnosys-mcp`. */
+export async function startMcpServer() {
     // v5.7.1 (#15): start the upgrade-marker watcher BEFORE anything else.
     // If `gnosys upgrade` was run on this machine while the MCP was idle,
     // pick that up immediately instead of serving stale tool handlers.
@@ -3093,7 +3094,7 @@ async function main() {
 }
 const invokedAsScript = !!process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1]);
 if (invokedAsScript) {
-    main().catch((err) => {
+    startMcpServer().catch((err) => {
         console.error("Fatal error:", err);
         process.exit(1);
     });

package/dist/lib/ask.js

@@ -13,6 +13,7 @@ import { getLLMProvider } from "./llm.js";
 import { GnosysArchive } from "./archive.js";
 import { GnosysMaintenanceEngine } from "./maintenance.js";
 import { auditLog } from "./audit.js";
+import { getSecureStorageSetupHint } from "./platform.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 /**
@@ -132,7 +133,7 @@ export class GnosysAsk {
             }
             if (envVar) {
                 throw new Error(`gnosys_ask requires an LLM. Configured default provider "${providerName}" has no key. ` +
-                    `Set ${envVar} in your shell, run 'gnosys setup' to store one in the macOS Keychain, or add llm.${providerName}.apiKey to gnosys.json.`);
+                    `Set ${envVar} in your shell, run 'gnosys setup' to store one in ${getSecureStorageSetupHint()}, or add llm.${providerName}.apiKey to gnosys.json.`);
             }
             throw new Error(`gnosys_ask requires an LLM. Provider "${providerName}" is not available. Run 'gnosys setup' to configure one.`);
         }

package/dist/lib/ingest.js

@@ -5,6 +5,7 @@
  */
 import { DEFAULT_CONFIG } from "./config.js";
 import { getLLMProvider } from "./llm.js";
+import { getSetupStorageBullet } from "./platform.js";
 export class GnosysIngestion {
     provider = null;
     tagRegistry;
@@ -73,7 +74,7 @@ export class GnosysIngestion {
                 lines.push(`Make sure ${providerName} is running locally (gnosys status --system will probe it).`, `Or use gnosys_add_structured for direct memory writes (no LLM needed).`);
             }
             else if (envVar) {
-                lines.push(`Configure a key for ${providerName} via one of these methods:`, `  • gnosys setup       — interactive (recommended; stores in macOS Keychain)`, `  • Set ${envVar} in your shell profile`, `  • Edit llm.${providerName}.apiKey in gnosys.json`, "", `Or use gnosys_add_structured for direct memory writes (no LLM needed).`);
+                lines.push(`Configure a key for ${providerName} via one of these methods:`, getSetupStorageBullet(), `  • Set ${envVar} in your shell profile`, `  • Edit llm.${providerName}.apiKey in gnosys.json`, "", `Or use gnosys_add_structured for direct memory writes (no LLM needed).`);
             }
             else {
                 lines.push(`Switch to a different default provider with: gnosys config set provider <name>`, `Or use gnosys_add_structured for direct memory writes (no LLM needed).`);

package/dist/lib/mcpClientConfig.js

@@ -8,7 +8,7 @@
  */
 import fs from "fs/promises";
 import path from "path";
-import os from "os";
+import { getClaudeDesktopConfigPath } from "./platform.js";
 /** The MCP server entry for a remote (HTTP/URL) gnosys server. */
 export function remoteMcpEntry(opts) {
     return {
@@ -16,18 +16,6 @@ export function remoteMcpEntry(opts) {
         ...(opts.token ? { headers: { Authorization: `Bearer ${opts.token}` } } : {}),
     };
 }
-/** Platform-specific Claude Desktop config path (mirrors setup.ts). */
-function claudeDesktopConfigPath() {
-    const home = os.homedir();
-    if (process.platform === "darwin") {
-        return path.join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
-    }
-    if (process.platform === "win32") {
-        const appData = process.env.APPDATA || path.join(home, "AppData", "Roaming");
-        return path.join(appData, "Claude", "claude_desktop_config.json");
-    }
-    return path.join(home, ".config", "Claude", "claude_desktop_config.json");
-}
 /** Merge a `gnosys` entry into a JSON file's `mcpServers` map (create if absent). */
 export async function mergeJsonMcpServer(file, entry) {
     let config = {};
@@ -51,7 +39,7 @@ export async function writeCursorRemote(projectDir, opts) {
 }
 /** Write the remote entry into the Claude Desktop config. Returns the path. */
 async function writeClaudeDesktopRemote(opts) {
-    const file = claudeDesktopConfigPath();
+    const file = getClaudeDesktopConfigPath();
     await mergeJsonMcpServer(file, remoteMcpEntry(opts));
     return file;
 }

package/dist/lib/platform.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Cross-platform paths and user-facing hints (macOS, Linux, Windows).
+ */
+export type OsFamily = "macos" | "linux" | "windows";
+/** Current OS family for CLI messages and help text. */
+export declare function getOsFamily(): OsFamily;
+/** Primary secure credential store name on this machine. */
+export declare function getSecureStorageLabel(): string;
+/** Short phrase for error messages (setup may still be required on Windows). */
+export declare function getSecureStorageSetupHint(): string;
+/** Order of API key resolution for user-facing help on the current OS. */
+export declare function getApiKeyResolutionOrderText(): string;
+/** Claude Desktop MCP config file path for the current platform. */
+export declare function getClaudeDesktopConfigPath(): string;
+/** Display path with ~ for home (for logs and help). */
+export declare function displayClaudeDesktopConfigPath(): string;
+/** Shell profile file(s) suggested for env vars on this OS. */
+export declare function getShellProfileHint(): string;
+/** Lines shown when user skips API key setup in gnosys setup. */
+export declare function getApiKeySkipHints(envVarName: string, provider: string): string[];
+/** ffmpeg install instructions (all platforms, for errors). */
+export declare function formatFfmpegInstallHint(): string;
+/** Ingest / LLM missing-key helper bullet for gnosys setup. */
+export declare function getSetupStorageBullet(): string;

package/dist/lib/platform.js

@@ -0,0 +1,114 @@
+/**
+ * Cross-platform paths and user-facing hints (macOS, Linux, Windows).
+ */
+import os from "os";
+import path from "path";
+/** Current OS family for CLI messages and help text. */
+export function getOsFamily() {
+    if (process.platform === "darwin")
+        return "macos";
+    if (process.platform === "win32")
+        return "windows";
+    return "linux";
+}
+/** Primary secure credential store name on this machine. */
+export function getSecureStorageLabel() {
+    switch (getOsFamily()) {
+        case "macos":
+            return "macOS Keychain";
+        case "linux":
+            return "GNOME Keyring";
+        case "windows":
+            return "Windows Credential Manager";
+    }
+}
+/** Short phrase for error messages (setup may still be required on Windows). */
+export function getSecureStorageSetupHint() {
+    switch (getOsFamily()) {
+        case "macos":
+            return "the macOS Keychain (via gnosys setup)";
+        case "linux":
+            return "GNOME Keyring (via gnosys setup, when secret-tool is available)";
+        case "windows":
+            return "your user environment or ~/.config/gnosys/.env (via gnosys setup)";
+    }
+}
+/** Order of API key resolution for user-facing help on the current OS. */
+export function getApiKeyResolutionOrderText() {
+    switch (getOsFamily()) {
+        case "macos":
+            return "macOS Keychain, environment variable, then ~/.config/gnosys/.env";
+        case "linux":
+            return "GNOME Keyring (when available), environment variable, then ~/.config/gnosys/.env";
+        case "windows":
+            return "environment variable, then ~/.config/gnosys/.env";
+    }
+}
+/** Claude Desktop MCP config file path for the current platform. */
+export function getClaudeDesktopConfigPath() {
+    const home = os.homedir();
+    if (process.platform === "darwin") {
+        return path.join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
+    }
+    if (process.platform === "win32") {
+        const appData = process.env.APPDATA || path.join(home, "AppData", "Roaming");
+        return path.join(appData, "Claude", "claude_desktop_config.json");
+    }
+    return path.join(home, ".config", "Claude", "claude_desktop_config.json");
+}
+/** Display path with ~ for home (for logs and help). */
+export function displayClaudeDesktopConfigPath() {
+    const home = os.homedir();
+    const p = getClaudeDesktopConfigPath();
+    return p.startsWith(home) ? "~" + p.slice(home.length) : p;
+}
+/** Shell profile file(s) suggested for env vars on this OS. */
+export function getShellProfileHint() {
+    switch (getOsFamily()) {
+        case "macos": {
+            const shell = path.basename(process.env.SHELL ?? "zsh");
+            return shell === "bash" ? "~/.bash_profile or ~/.bashrc" : "~/.zshrc";
+        }
+        case "linux": {
+            const shell = path.basename(process.env.SHELL ?? "bash");
+            return shell === "zsh" ? "~/.zshrc" : "~/.bashrc";
+        }
+        case "windows":
+            return "%USERPROFILE%\\Documents\\PowerShell\\Microsoft.PowerShell_profile.ps1 (or System Properties → Environment Variables)";
+    }
+}
+/** Lines shown when user skips API key setup in gnosys setup. */
+export function getApiKeySkipHints(envVarName, provider) {
+    const hints = [];
+    const profile = getShellProfileHint();
+    if (getOsFamily() === "macos") {
+        hints.push(`macOS Keychain: security add-generic-password -a "$USER" -s "${envVarName}" -w "key" -U`);
+    }
+    if (getOsFamily() === "linux") {
+        hints.push(`GNOME Keyring: printf '%s' 'key' | secret-tool store --label="Gnosys ${provider}" service gnosys account ${envVarName}`);
+    }
+    if (getOsFamily() === "windows") {
+        hints.push(`PowerShell profile: [Environment]::SetEnvironmentVariable("${envVarName}", "key", "User")`);
+    }
+    hints.push(`Shell profile:  echo 'export ${envVarName}=key' >> ${profile}`);
+    hints.push(`Dotenv file:    echo '${envVarName}=key' >> ~/.config/gnosys/.env`);
+    return hints;
+}
+/** ffmpeg install instructions (all platforms, for errors). */
+export function formatFfmpegInstallHint() {
+    return ("Install it with:\n" +
+        "  macOS:   brew install ffmpeg\n" +
+        "  Linux:   sudo apt install ffmpeg   (Debian/Ubuntu) or your distro package manager\n" +
+        "  Windows: winget install FFmpeg    (or choco install ffmpeg)");
+}
+/** Ingest / LLM missing-key helper bullet for gnosys setup. */
+export function getSetupStorageBullet() {
+    switch (getOsFamily()) {
+        case "macos":
+            return "  • gnosys setup       — interactive (recommended; stores in macOS Keychain)";
+        case "linux":
+            return "  • gnosys setup       — interactive (recommended; stores in GNOME Keyring when available)";
+        case "windows":
+            return "  • gnosys setup       — interactive (recommended; env var or ~/.config/gnosys/.env)";
+    }
+}

package/dist/lib/remote.d.ts

@@ -11,6 +11,10 @@
  */
 import { GnosysDB, type DbMemory } from "./db.js";
 import type { ProgressCallback } from "./progress.js";
+/** Resolve the configured remote directory for this machine (machine.json, then legacy meta). */
+export declare function getConfiguredRemotePath(localDb: GnosysDB): string | null;
+/** Stop using a remote on this machine; does not delete the remote database files. */
+export declare function clearRemoteSyncConfig(localDb: GnosysDB): void;
 interface ConflictInfo {
     memoryId: string;
     title: string;

package/dist/lib/remote.js

@@ -13,7 +13,27 @@ import { existsSync, statSync, mkdirSync, writeFileSync, unlinkSync } from "fs";
 import os from "os";
 import * as path from "path";
 import { GnosysDB } from "./db.js";
-import { readMachineConfig } from "./machineConfig.js";
+import { readMachineConfig, writeMachineConfig } from "./machineConfig.js";
+const META_REMOTE_PATH = "remote_path";
+const META_REMOTE_MODE = "remote_mode";
+/** Resolve the configured remote directory for this machine (machine.json, then legacy meta). */
+export function getConfiguredRemotePath(localDb) {
+    const mc = readMachineConfig();
+    if (mc?.remote?.enabled && mc.remote.path)
+        return mc.remote.path;
+    const fromMeta = localDb.getMeta(META_REMOTE_PATH);
+    return fromMeta || null;
+}
+/** Stop using a remote on this machine; does not delete the remote database files. */
+export function clearRemoteSyncConfig(localDb) {
+    localDb.setMeta(META_REMOTE_PATH, "");
+    localDb.deleteMeta(META_REMOTE_MODE);
+    const mc = readMachineConfig();
+    if (mc) {
+        mc.remote = { enabled: false };
+        writeMachineConfig(mc);
+    }
+}
 // ─── Validation ─────────────────────────────────────────────────────────
 /**
  * Validate that a directory is suitable for hosting the remote gnosys.db.

package/dist/lib/remoteWizard.d.ts

@@ -7,7 +7,7 @@
  *  3. Join existing — second machine joining a remote that already has data
  */
 import { type Interface } from "readline/promises";
-import type { GnosysDB } from "./db.js";
+import { GnosysDB } from "./db.js";
 export declare function runConfigureWizard(centralDb: GnosysDB, externalRl?: Interface): Promise<boolean>;
 export declare function configureFromPath(centralDb: GnosysDB, remotePath: string, opts?: {
     migrate?: boolean;

package/dist/lib/remoteWizard.js

@@ -9,7 +9,8 @@
 import { readdirSync, statSync } from "fs";
 import * as path from "path";
 import { createInterface } from "readline/promises";
-import { RemoteSync, validateLocation } from "./remote.js";
+import { GnosysDB } from "./db.js";
+import { RemoteSync, validateLocation, getConfiguredRemotePath, clearRemoteSyncConfig, } from "./remote.js";
 import { safeQuestion } from "./setup/ui/safePrompt.js";
 import { Spinner } from "./setup/ui/spinner.js";
 import { printStatus } from "./setup/ui/status.js";
@@ -148,7 +149,7 @@ export async function runConfigureWizard(centralDb, externalRl) {
             const choice = await askChoice(rl, "What would you like to do?", [
                 { key: "1", label: "Change remote location" },
                 { key: "2", label: "Re-validate current remote" },
-                { key: "3", label: "Disconnect remote (back to local-only)" },
+                { key: "3", label: "Disconnect remote (local-only — warns if sync is needed)" },
                 { key: "4", label: "Cancel" },
             ], "4");
             if (choice === "4")
@@ -342,14 +343,131 @@ async function setupRemoteFlow(rl, centralDb, localActiveCount) {
     return true;
 }
 // ─── Reconfigure helpers ────────────────────────────────────────────────
-async function disconnectRemote(rl, centralDb) {
-    const confirm = await askConfirm(rl, "Disconnect the remote? Your local DB will remain. The remote DB itself is not deleted.", false);
+async function disconnectRemote(rl, localDb) {
+    const remotePath = getConfiguredRemotePath(localDb);
+    if (!remotePath) {
+        printStatus("warn", "remote is not configured");
+        return false;
+    }
+    const localCounts = localDb.getMemoryCount();
+    let remoteCounts = null;
+    let syncStatus = null;
+    const validation = await validateLocation(remotePath);
+    const sync = new RemoteSync(localDb, remotePath);
+    try {
+        syncStatus = await sync.getStatus();
+        const remoteDb = new GnosysDB(remotePath);
+        if (remoteDb.isAvailable()) {
+            remoteCounts = remoteDb.getMemoryCount();
+            remoteDb.close();
+        }
+    }
+    catch {
+        // Remote unreadable — still show warning with validation hints below.
+    }
+    finally {
+        sync.closeRemote();
+    }
+    const remoteReachable = Boolean(syncStatus?.reachable && validation.ok);
+    const remoteActive = remoteCounts?.active ?? validation.checks.existingDb.memoryCount ?? null;
+    console.log("");
+    printStatus("warn", "disconnecting makes this machine local-only");
+    console.log(`   local    ~/.gnosys/gnosys.db — ${localCounts.active} active memories`);
+    if (remoteReachable && remoteActive !== null) {
+        console.log(`   remote   ${remotePath} — ${remoteActive} active memories`);
+    }
+    else {
+        printStatus("warn", "remote is not reachable", remotePath);
+    }
+    console.log("");
+    console.log("  The remote folder and gnosys.db are not deleted.");
+    console.log("  After disconnect, this Mac will not read or write that remote,");
+    console.log("  even when the volume is mounted.");
+    const pendingPull = syncStatus?.pendingPull ?? 0;
+    const pendingPush = syncStatus?.pendingPush ?? 0;
+    const conflicts = syncStatus?.conflicts.length ?? 0;
+    const countGap = remoteActive !== null && remoteActive > localCounts.active
+        ? remoteActive - localCounts.active
+        : 0;
+    const shouldRecommendSync = remoteReachable &&
+        (pendingPull > 0 || pendingPush > 0 || conflicts > 0 || countGap > 0);
+    if (shouldRecommendSync) {
+        console.log("");
+        printStatus("warn", "your local cache may be behind the shared remote brain");
+        if (countGap > 0) {
+            console.log(`   Remote has about ${countGap} more active memor${countGap === 1 ? "y" : "ies"} than local.`);
+        }
+        if (pendingPull > 0 || pendingPush > 0) {
+            const parts = [];
+            if (pendingPull > 0)
+                parts.push(`${pendingPull} to pull into local`);
+            if (pendingPush > 0)
+                parts.push(`${pendingPush} to push to remote`);
+            console.log(`   Pending sync: ${parts.join(", ")}.`);
+        }
+        if (conflicts > 0) {
+            console.log(`   ${conflicts} unresolved conflict${conflicts === 1 ? "" : "s"} — resolve before or during sync.`);
+        }
+        printStatus("progress", "recommended", "gnosys setup remote sync");
+    }
+    const choice = await askChoice(rl, shouldRecommendSync
+        ? "Sync first so you do not lose access to remote-only memories on this Mac:"
+        : "How do you want to proceed?", remoteReachable
+        ? [
+            { key: "1", label: "Run gnosys setup remote sync, then disconnect (recommended)" },
+            { key: "2", label: "Disconnect now without syncing (keep current local DB only)" },
+            { key: "3", label: "Cancel" },
+        ]
+        : [
+            { key: "2", label: "Disconnect anyway (local DB only; remote not reachable to sync)" },
+            { key: "3", label: "Cancel" },
+        ], "3");
+    if (choice === "3") {
+        console.log("Cancelled.");
+        return false;
+    }
+    if (choice === "1" && remoteReachable) {
+        const spin = Spinner("syncing local and remote…");
+        const syncRun = new RemoteSync(localDb, remotePath);
+        try {
+            const result = await syncRun.sync();
+            if (result.errors.length > 0) {
+                spin.fail("sync had errors");
+                for (const e of result.errors)
+                    printStatus("fail", e);
+                const proceed = await askConfirm(rl, "Disconnect anyway without a clean sync?", false);
+                if (!proceed)
+                    return false;
+            }
+            else {
+                spin.ok("sync complete", `pushed ${result.pushed} · pulled ${result.pulled} · conflicts ${result.conflicts.length}`);
+                if (result.conflicts.length > 0) {
+                    printStatus("warn", "conflicts still open", "gnosys setup remote resolve <id> --keep <local|remote>");
+                }
+            }
+        }
+        finally {
+            syncRun.closeRemote();
+        }
+    }
+    else if (choice === "1" && !remoteReachable) {
+        printStatus("fail", "cannot sync — mount the remote or cancel");
+        return false;
+    }
+    if (choice === "2" && shouldRecommendSync) {
+        const risky = await askConfirm(rl, "Disconnect without syncing? You may only see local memories on this Mac until you reconnect.", false);
+        if (!risky) {
+            console.log("Cancelled.");
+            return false;
+        }
+    }
+    const confirm = await askConfirm(rl, "Disconnect now? Remote files stay on disk; this machine uses ~/.gnosys/gnosys.db only.", false);
     if (!confirm) {
         console.log("Cancelled.");
         return false;
     }
-    centralDb.setMeta(REMOTE_PATH_KEY, "");
-    console.log("✓ Remote disconnected. Gnosys is now local-only.");
+    clearRemoteSyncConfig(localDb);
+    console.log("✓ Remote disconnected. Gnosys is now local-only on this machine.");
     return true;
 }
 async function revalidateRemote(_rl, _centralDb, currentRemote) {

package/dist/lib/setup.js

@@ -18,6 +18,7 @@ import { loadConfig, updateConfig, getProviderModel, } from "./config.js";
 import { validateModel } from "./modelValidation.js";
 import { resolveActiveStorePath, ensureActiveStorePath } from "./setup/storePath.js";
 import { safeQuestion } from "./setup/ui/safePrompt.js";
+import { getClaudeDesktopConfigPath, getApiKeySkipHints } from "./platform.js";
 // ─── ANSI Colors ────────────────────────────────────────────────────────────
 const BOLD = "\x1b[1m";
 const DIM = "\x1b[2m";
@@ -538,7 +539,7 @@ export async function detectIDEs(projectDir) {
     // Check for Claude Desktop — distinct from Claude Code CLI. Detected via the
     // app bundle on macOS or the platform-specific config dir.
     try {
-        const cfg = claudeDesktopConfigPath();
+        const cfg = getClaudeDesktopConfigPath();
         const cfgDir = path.dirname(cfg);
         const stat = await fs.stat(cfgDir);
         if (stat.isDirectory())
@@ -566,23 +567,6 @@ export async function detectIDEs(projectDir) {
     }
     return detected;
 }
-/**
- * Resolve the platform-specific Claude Desktop config file path.
- *   macOS:   ~/Library/Application Support/Claude/claude_desktop_config.json
- *   Windows: %APPDATA%/Claude/claude_desktop_config.json
- *   Linux:   ~/.config/Claude/claude_desktop_config.json (no official build yet)
- */
-function claudeDesktopConfigPath() {
-    const home = os.homedir();
-    if (process.platform === "darwin") {
-        return path.join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
-    }
-    if (process.platform === "win32") {
-        const appData = process.env.APPDATA || path.join(home, "AppData", "Roaming");
-        return path.join(appData, "Claude", "claude_desktop_config.json");
-    }
-    return path.join(home, ".config", "Claude", "claude_desktop_config.json");
-}
 /**
  * Replace (or append) a `[mcp.<name>]` block inside the TOML text for
  * Grok Build's config file. Preserves every line outside that block —
@@ -634,6 +618,25 @@ export function upsertGrokMcpBlock(existing, name, entry) {
     const afterBlock = afterLines.join("\n");
     return `${head}${sectionHeader}\n${blockBody}${gap}${afterBlock}`;
 }
+/**
+ * Absolute path to the `gnosys-mcp` stdio entry (dist/index.js).
+ * Prefer this over `gnosys serve` — v5.11.0 `gnosys serve` imported index.js but
+ * did not call startMcpServer(), so MCP hosts saw "connection closed" on init.
+ */
+function resolveGnosysMcpCommand() {
+    try {
+        const p = execSync("command -v gnosys-mcp", { encoding: "utf-8" }).trim();
+        if (p)
+            return p;
+    }
+    catch {
+        // Fall back to bare name on PATH.
+    }
+    return "gnosys-mcp";
+}
+function gnosysMcpServerEntry() {
+    return { command: resolveGnosysMcpCommand(), args: [] };
+}
 function renderGrokMcpBlock(entry) {
     const argsStr = `[${entry.args.map((a) => JSON.stringify(a)).join(", ")}]`;
     const lines = [
@@ -652,8 +655,15 @@ export async function setupIDE(ide, projectDir) {
     try {
         switch (ide) {
             case "claude": {
+                const mcpCmd = resolveGnosysMcpCommand();
                 try {
-                    execSync("claude mcp add -s user gnosys -- gnosys serve", {
+                    try {
+                        execSync("claude mcp remove gnosys", { stdio: "pipe" });
+                    }
+                    catch {
+                        // Not registered yet — fine.
+                    }
+                    execSync(`claude mcp add -s user gnosys -- ${mcpCmd}`, {
                         stdio: "pipe",
                     });
                 }
@@ -664,7 +674,7 @@ export async function setupIDE(ide, projectDir) {
                     }
                     throw e;
                 }
-                return { success: true, message: "Claude Code MCP server registered" };
+                return { success: true, message: `Claude Code MCP server registered (${mcpCmd})` };
             }
             case "cursor": {
                 const cursorDir = path.join(projectDir, ".cursor");
@@ -680,7 +690,7 @@ export async function setupIDE(ide, projectDir) {
                 }
                 // Merge gnosys entry
                 const servers = (config.mcpServers ?? {});
-                servers.gnosys = { command: "gnosys", args: ["serve"] };
+                servers.gnosys = gnosysMcpServerEntry();
                 config.mcpServers = servers;
                 await fs.writeFile(mcpPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
                 return { success: true, message: "Cursor MCP config updated (.cursor/mcp.json)" };
@@ -713,15 +723,8 @@ export async function setupIDE(ide, projectDir) {
                 catch {
                     // No user-level config.toml to clean — fine.
                 }
-                // 2. Find the absolute path to `gnosys` so Codex can launch it even
-                //    if shell PATH differs from what it has at run time.
-                let gnosysCmd = "gnosys";
-                try {
-                    gnosysCmd = execSync("command -v gnosys", { encoding: "utf-8" }).trim() || "gnosys";
-                }
-                catch {
-                    // Fall back to `gnosys` on PATH if `command -v` fails.
-                }
+                // 2. Absolute path to `gnosys-mcp` (stdio entry) for Codex spawn.
+                const gnosysCmd = resolveGnosysMcpCommand();
                 // 3. Check whether gnosys is already registered. If yes and the
                 //    command matches, leave it alone (idempotent). If it differs,
                 //    remove and re-add.
@@ -730,7 +733,7 @@ export async function setupIDE(ide, projectDir) {
                     const existing = execSync("codex mcp get gnosys 2>/dev/null", {
                         encoding: "utf-8",
                     });
-                    if (existing && existing.includes(gnosysCmd) && existing.includes("serve")) {
+                    if (existing && existing.includes(gnosysCmd) && !existing.includes(" serve")) {
                         alreadyCorrect = true;
                     }
                     else if (existing) {
@@ -755,7 +758,7 @@ export async function setupIDE(ide, projectDir) {
                 }
                 // 4. Register via the canonical Codex CLI command.
                 try {
-                    execSync(`codex mcp add gnosys -- ${gnosysCmd} serve`, { stdio: "pipe" });
+                    execSync(`codex mcp add gnosys -- ${gnosysCmd}`, { stdio: "pipe" });
                 }
                 catch (err) {
                     const msg = err instanceof Error ? err.message : String(err);
@@ -785,7 +788,7 @@ export async function setupIDE(ide, projectDir) {
                     // File doesn't exist or is invalid — start fresh
                 }
                 const servers = (config.mcpServers ?? {});
-                servers.gnosys = { command: "gnosys", args: ["serve"] };
+                servers.gnosys = gnosysMcpServerEntry();
                 config.mcpServers = servers;
                 await fs.writeFile(settingsPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
                 return { success: true, message: "Gemini CLI MCP config updated (~/.gemini/settings.json)" };
@@ -805,7 +808,7 @@ export async function setupIDE(ide, projectDir) {
                     // File doesn't exist or is invalid — start fresh
                 }
                 const servers = (config.mcpServers ?? {});
-                servers.gnosys = { command: "gnosys", args: ["serve"] };
+                servers.gnosys = gnosysMcpServerEntry();
                 config.mcpServers = servers;
                 await fs.writeFile(configPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
                 return { success: true, message: "Antigravity MCP config updated (~/.gemini/antigravity/mcp_config.json)" };
@@ -826,8 +829,7 @@ export async function setupIDE(ide, projectDir) {
                     // File doesn't exist yet — start fresh
                 }
                 const updated = upsertGrokMcpBlock(existing, "gnosys", {
-                    command: "gnosys",
-                    args: ["serve"],
+                    ...gnosysMcpServerEntry(),
                     startup_timeout_sec: 90,
                 });
                 await fs.writeFile(configPath, updated, "utf-8");
@@ -837,7 +839,7 @@ export async function setupIDE(ide, projectDir) {
                 // Claude Desktop reads MCP servers from claude_desktop_config.json
                 // in a platform-specific app data directory. Distinct from Claude
                 // Code CLI which uses `claude mcp add`.
-                const configPath = claudeDesktopConfigPath();
+                const configPath = getClaudeDesktopConfigPath();
                 const configDir = path.dirname(configPath);
                 await fs.mkdir(configDir, { recursive: true });
                 let config = {};
@@ -849,7 +851,7 @@ export async function setupIDE(ide, projectDir) {
                     // File doesn't exist or is invalid — start fresh
                 }
                 const servers = (config.mcpServers ?? {});
-                servers.gnosys = { command: "gnosys", args: ["serve"] };
+                servers.gnosys = gnosysMcpServerEntry();
                 config.mcpServers = servers;
                 await fs.writeFile(configPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
                 // Display path with ~ prefix when inside HOME for clarity
@@ -1432,14 +1434,10 @@ export async function runSetup(opts) {
                 else {
                     // Skip
                     console.log(`  ${DIM}Skipped. Set your key later using one of these methods:`);
-                    if (isMac) {
-                        console.log(`  \u2022 macOS Keychain: security add-generic-password -a "$USER" -s "${envVarName}" -w "key" -U`);
-                    }
-                    if (hasSecret) {
-                        console.log(`  \u2022 GNOME Keyring: printf '%s' 'key' | secret-tool store --label="Gnosys ${provider}" service gnosys account ${envVarName}`);
+                    for (const hint of getApiKeySkipHints(envVarName, provider)) {
+                        console.log(`  \u2022 ${hint}`);
                     }
-                    console.log(`  \u2022 Shell profile:  echo 'export ${envVarName}=key' >> ${profileFile}`);
-                    console.log(`  \u2022 Dotenv file:    echo '${envVarName}=key' >> ~/.config/gnosys/.env${RESET}`);
+                    console.log(`${RESET}`);
                 }
             }
         }

package/dist/lib/upgrade.d.ts

@@ -30,8 +30,11 @@ export declare function getMarkerPath(): string;
 export declare function writeUpgradeMarker(version: string): void;
 export declare function readUpgradeMarker(): UpgradeMarker | null;
 /**
- * Returns true when the on-disk marker names a different version than the
+ * Returns true when the on-disk marker names a **newer** version than the
  * currently running binary. The caller (an MCP server) should exit cleanly
  * so the host respawns it against the upgraded global binary.
+ *
+ * Stale markers from an older install must not restart a newer binary (that
+ * caused an immediate exit loop after patch upgrades).
  */
 export declare function shouldRestartMcp(currentVersion: string): boolean;

package/dist/lib/upgrade.js

@@ -47,14 +47,27 @@ export function readUpgradeMarker() {
         return null;
     }
 }
+function compareSemver(a, b) {
+    const pa = a.split(".").map((x) => parseInt(x, 10) || 0);
+    const pb = b.split(".").map((x) => parseInt(x, 10) || 0);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+        if (d !== 0)
+            return d;
+    }
+    return 0;
+}
 /**
- * Returns true when the on-disk marker names a different version than the
+ * Returns true when the on-disk marker names a **newer** version than the
  * currently running binary. The caller (an MCP server) should exit cleanly
  * so the host respawns it against the upgraded global binary.
+ *
+ * Stale markers from an older install must not restart a newer binary (that
+ * caused an immediate exit loop after patch upgrades).
  */
 export function shouldRestartMcp(currentVersion) {
     const marker = readUpgradeMarker();
     if (!marker)
         return false;
-    return marker.version !== currentVersion;
+    return compareSemver(marker.version, currentVersion) > 0;
 }

package/dist/lib/videoExtract.js

@@ -11,6 +11,7 @@ import * as os from "os";
 import * as fs from "fs/promises";
 import { execFileSync } from "child_process";
 import { transcribeAudio, } from "./audioExtract.js";
+import { formatFfmpegInstallHint } from "./platform.js";
 // ─── Helpers ────────────────────────────────────────────────────────────
 /**
  * Check that ffmpeg is installed and accessible.
@@ -22,10 +23,7 @@ function checkFfmpeg() {
     }
     catch {
         throw new Error("Video transcription requires ffmpeg to be installed.\n" +
-            "Install it with:\n" +
-            "  macOS:   brew install ffmpeg\n" +
-            "  Ubuntu:  sudo apt install ffmpeg\n" +
-            "  Windows: winget install FFmpeg");
+            formatFfmpegInstallHint());
     }
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gnosys",
-  "version": "5.11.0",
+  "version": "5.11.1",
   "description": "Gnosys — Persistent Memory for AI Agents. Sandbox-first runtime, central SQLite brain, federated search, Dream Mode, Web Knowledge Base, Obsidian export.",
   "type": "module",
   "main": "dist/index.js",