gnosys 5.9.5 → 5.11.0

package/dist/cli.js

@@ -20,14 +20,14 @@ import { getGnosysHome } from "./lib/paths.js";
 import { GnosysSearch } from "./lib/search.js";
 import { GnosysTagRegistry } from "./lib/tags.js";
 import { applyLens } from "./lib/lensing.js";
-import { getFileHistory, rollbackToCommit, hasGitHistory, getFileDiff } from "./lib/history.js";
 import { computeStats } from "./lib/timeline.js";
 import { buildLinkGraph, getBacklinks, getOutgoingLinks, formatGraphSummary } from "./lib/wikilinks.js";
 import { loadConfig, generateConfigTemplate, DEFAULT_CONFIG, writeConfig, resolveTaskModel, ALL_PROVIDERS, getProviderModel } from "./lib/config.js";
 import { getLLMProvider, isProviderAvailable } from "./lib/llm.js";
 import { GnosysDB } from "./lib/db.js";
+import { logError } from "./lib/log.js";
 import { createProjectIdentity, readProjectIdentity, findProjectIdentity, migrateProject } from "./lib/projectIdentity.js";
-import { setPreference, getPreference, getAllPreferences, deletePreference } from "./lib/preferences.js";
+import { setPreference, getPreference, getAllPreferences, deletePreference, KNOWN_PREFERENCE_KEYS, suggestPreferenceKey } from "./lib/preferences.js";
 import { syncToTarget } from "./lib/rulesGen.js";
 // Lazy-loaded inside action handlers (each ~200ms-2.5s on cold cache):
 //   - ./lib/embeddings.js       (@huggingface/transformers — 80MB)
@@ -209,6 +209,45 @@ program
     .description("Read a specific memory. Supports layer prefix (e.g., project:decisions/auth.md)")
     .option("--json", "Output as JSON")
     .action(async (memoryPath, opts) => {
+    const centralDb = GnosysDB.openCentral();
+    if (centralDb.isAvailable()) {
+        const dbMem = centralDb.getMemory(memoryPath);
+        if (dbMem) {
+            try {
+                const tags = dbMem.tags || "[]";
+                const headerLines = [
+                    `---`,
+                    `id: ${dbMem.id}`,
+                    `title: '${dbMem.title}'`,
+                    `category: ${dbMem.category}`,
+                    `tags: ${tags}`,
+                    `relevance: ${dbMem.relevance}`,
+                    `author: ${dbMem.author}`,
+                    `authority: ${dbMem.authority}`,
+                    `confidence: ${dbMem.confidence}`,
+                    `status: ${dbMem.status}`,
+                    `tier: ${dbMem.tier}`,
+                    `created: '${dbMem.created}'`,
+                    `modified: '${dbMem.modified}'`,
+                ];
+                if (dbMem.source_file) {
+                    headerLines.push(`source_file: ${dbMem.source_file}${dbMem.source_page != null ? ` (page ${Number(dbMem.source_page)})` : ""}`);
+                }
+                if (dbMem.source_path)
+                    headerLines.push(`source_path: ${dbMem.source_path}`);
+                headerLines.push(`---`);
+                const raw = `[Source: gnosys.db]\n\n${headerLines.join("\n")}\n\n${dbMem.content}`;
+                outputResult(!!opts.json, { path: memoryPath, source: "gnosys.db", content: raw, memory: dbMem }, () => {
+                    console.log(raw);
+                });
+                return;
+            }
+            finally {
+                centralDb.close();
+            }
+        }
+    }
+    centralDb.close();
     const resolver = await getResolver();
     const memory = await resolver.readMemory(memoryPath);
     if (!memory) {
@@ -262,7 +301,7 @@ program
             });
         }
         catch (err) {
-            console.error(`Error: ${err instanceof Error ? err.message : err}`);
+            logError(err, { module: "cli", op: "discover" });
             process.exit(1);
         }
         finally {
@@ -302,7 +341,7 @@ program
         });
     }
     catch (err) {
-        console.error(`Error: ${err instanceof Error ? err.message : err}`);
+        logError(err, { module: "cli", op: "discover" });
         process.exit(1);
     }
     finally {
@@ -354,7 +393,7 @@ program
             });
         }
         catch (err) {
-            console.error(`Error: ${err instanceof Error ? err.message : err}`);
+            logError(err, { module: "cli", op: "search" });
             process.exit(1);
         }
         finally {
@@ -393,7 +432,7 @@ program
         });
     }
     catch (err) {
-        console.error(`Error: ${err instanceof Error ? err.message : err}`);
+        logError(err, { module: "cli", op: "search" });
         process.exit(1);
     }
     finally {
@@ -468,7 +507,7 @@ program
         });
     }
     catch (err) {
-        console.error(`Error: ${err instanceof Error ? err.message : err}`);
+        logError(err, { module: "cli", op: "list" });
         process.exit(1);
     }
     finally {
@@ -1961,6 +2000,7 @@ program
     .option("--modified-after <date>", "Modified after ISO date")
     .option("--modified-before <date>", "Modified before ISO date")
     .option("--or", "Combine filters with OR instead of AND (default: AND)")
+    .option("--json", "Output as JSON")
     .action(async (opts) => {
     const resolver = await getResolver();
     const allMemories = await resolver.getAllMemories();
@@ -1990,82 +2030,73 @@ program
     if (opts.modifiedBefore)
         lens.modifiedBefore = opts.modifiedBefore;
     const result = applyLens(allMemories, lens);
-    if (result.length === 0) {
-        console.log("No memories match the lens filter.");
-        return;
-    }
-    console.log(`${result.length} memories match:\n`);
-    for (const m of result) {
-        const src = m.sourceLabel || "";
-        console.log(`  [${m.frontmatter.status}] ${m.frontmatter.title} (${m.frontmatter.confidence})`);
-        console.log(`    ${src ? src + ":" : ""}${m.relativePath}`);
-        console.log();
-    }
+    const items = result.map((m) => ({
+        title: m.frontmatter.title,
+        status: m.frontmatter.status,
+        confidence: m.frontmatter.confidence,
+        sourceLabel: m.sourceLabel || "",
+        relativePath: m.relativePath,
+    }));
+    outputResult(!!opts.json, { count: items.length, items }, () => {
+        if (result.length === 0) {
+            console.log("No memories match the lens filter.");
+            return;
+        }
+        console.log(`${result.length} memories match:\n`);
+        for (const m of result) {
+            const src = m.sourceLabel || "";
+            console.log(`  [${m.frontmatter.status}] ${m.frontmatter.title} (${m.frontmatter.confidence})`);
+            console.log(`    ${src ? src + ":" : ""}${m.relativePath}`);
+            console.log();
+        }
+    });
 });
 // ─── gnosys history <path> ───────────────────────────────────────────────
 program
     .command("history <memoryPath>")
-    .description("Show version history for a memory (git-backed)")
+    .description("Show audit history for a memory")
     .option("-n, --limit <number>", "Max entries", "20")
-    .option("--diff <hash>", "Show diff from this commit to current")
+    .option("--json", "Output as JSON")
     .action(async (memPath, opts) => {
-    const resolver = await getResolver();
-    const memory = await resolver.readMemory(memPath);
-    if (!memory) {
-        console.error(`Memory not found: ${memPath}`);
-        process.exit(1);
-    }
-    const sourceStore = resolver.getStores().find((s) => s.label === memory.sourceLabel);
-    if (!sourceStore) {
-        console.error("Could not locate source store.");
-        process.exit(1);
-    }
-    if (!hasGitHistory(sourceStore.path)) {
-        console.error("No git history available for this store.");
+    const centralDb = GnosysDB.openCentral();
+    if (!centralDb.isAvailable()) {
+        console.error("Central DB not available.");
         process.exit(1);
     }
-    if (opts.diff) {
-        const diff = getFileDiff(sourceStore.path, memory.relativePath, opts.diff, "HEAD");
-        if (!diff) {
-            console.error("Could not generate diff.");
+    try {
+        const dbMem = centralDb.getMemory(memPath);
+        if (!dbMem) {
+            console.error(`Memory not found: ${memPath}`);
             process.exit(1);
         }
-        console.log(diff);
-        return;
-    }
-    const history = getFileHistory(sourceStore.path, memory.relativePath, parseInt(opts.limit));
-    if (history.length === 0) {
-        console.log("No history found for this memory.");
-        return;
-    }
-    console.log(`History for ${memory.frontmatter.title}:\n`);
-    for (const entry of history) {
-        console.log(`  ${entry.commitHash.substring(0, 7)}  ${entry.date}  ${entry.message}`);
-    }
-});
-// ─── gnosys rollback <path> <hash> ──────────────────────────────────────
-program
-    .command("rollback <memoryPath> <commitHash>")
-    .description("Rollback a memory to its state at a specific commit")
-    .action(async (memPath, commitHash) => {
-    const resolver = await getResolver();
-    const memory = await resolver.readMemory(memPath);
-    if (!memory) {
-        console.error(`Memory not found: ${memPath}`);
-        process.exit(1);
-    }
-    const sourceStore = resolver.getStores().find((s) => s.label === memory.sourceLabel);
-    if (!sourceStore?.writable) {
-        console.error("Cannot rollback: store is read-only.");
-        process.exit(1);
-    }
-    const success = rollbackToCommit(sourceStore.path, memory.relativePath, commitHash);
-    if (success) {
-        console.log(`Rolled back ${memory.frontmatter.title} to commit ${commitHash.substring(0, 7)}.`);
+        const limit = parseInt(opts.limit, 10) || 20;
+        const audits = centralDb.getAuditLog(dbMem.id, limit);
+        outputResult(!!opts.json, {
+            memoryId: dbMem.id,
+            title: dbMem.title,
+            created: dbMem.created,
+            modified: dbMem.modified,
+            entries: audits,
+        }, () => {
+            if (audits.length === 0) {
+                console.log(`Memory: ${dbMem.title} (${dbMem.id})`);
+                console.log(`Created: ${dbMem.created}`);
+                console.log(`Modified: ${dbMem.modified}`);
+                console.log("No audit history recorded.");
+                return;
+            }
+            console.log(`History for ${dbMem.title} (${dbMem.id}, ${audits.length} entries):\n`);
+            console.log(`Created: ${dbMem.created}`);
+            console.log(`Modified: ${dbMem.modified}\n`);
+            for (const entry of audits) {
+                const date = entry.timestamp.split("T")[0];
+                const detail = entry.details ? ` (${entry.details})` : "";
+                console.log(`  ${date}  ${entry.operation}${detail}`);
+            }
+        });
     }
-    else {
-        console.error(`Rollback failed. Check that the commit hash is valid.`);
-        process.exit(1);
+    finally {
+        centralDb.close();
     }
 });
 // ─── gnosys timeline ────────────────────────────────────────────────────
@@ -2075,6 +2106,7 @@ program
     .option("-p, --period <period>", "Group by: day, week, month (default), year", "month")
     .option("--project <id>", "Filter to a specific project ID (default: all projects)")
     .option("--limit-titles <n>", "Show titles inline when an entry has <= N memories (default 5)", "5")
+    .option("--json", "Output as JSON")
     .action(async (opts) => {
     const { groupDbByPeriod } = await import("./lib/timeline.js");
     const centralDb = GnosysDB.openCentral();
@@ -2087,25 +2119,29 @@ program
             ? centralDb.getMemoriesByProject(opts.project)
             : centralDb.getActiveMemories();
         if (memories.length === 0) {
-            console.log("No memories found.");
+            outputResult(!!opts.json, { period: opts.period, count: 0, entries: [] }, () => {
+                console.log("No memories found.");
+            });
             return;
         }
         const entries = groupDbByPeriod(memories, opts.period);
         const titleLimit = Math.max(0, parseInt(opts.limitTitles, 10) || 5);
-        console.log(`Knowledge Timeline (by ${opts.period}, ${memories.length} memories):\n`);
-        for (const entry of entries) {
-            const parts = [];
-            if (entry.created > 0)
-                parts.push(`${entry.created} created`);
-            if (entry.modified > 0)
-                parts.push(`${entry.modified} modified`);
-            console.log(`  ${entry.period}: ${parts.join(", ")}`);
-            if (entry.titles.length > 0 && entry.titles.length <= titleLimit) {
-                for (const t of entry.titles) {
-                    console.log(`    + ${t}`);
+        outputResult(!!opts.json, { period: opts.period, count: memories.length, entries }, () => {
+            console.log(`Knowledge Timeline (by ${opts.period}, ${memories.length} memories):\n`);
+            for (const entry of entries) {
+                const parts = [];
+                if (entry.created > 0)
+                    parts.push(`${entry.created} created`);
+                if (entry.modified > 0)
+                    parts.push(`${entry.modified} modified`);
+                console.log(`  ${entry.period}: ${parts.join(", ")}`);
+                if (entry.titles.length > 0 && entry.titles.length <= titleLimit) {
+                    for (const t of entry.titles) {
+                        console.log(`    + ${t}`);
+                    }
                 }
             }
-        }
+        });
     }
     finally {
         centralDb.close();
@@ -2253,7 +2289,8 @@ program
 program
     .command("links <memoryPath>")
     .description("Show wikilinks for a memory — both outgoing [[links]] and backlinks from other memories")
-    .action(async (memPath) => {
+    .option("--json", "Output as JSON")
+    .action(async (memPath, opts) => {
     const resolver = await getResolver();
     const memory = await resolver.readMemory(memPath);
     if (!memory) {
@@ -2263,33 +2300,41 @@ program
     const allMemories = await resolver.getAllMemories();
     const outgoing = getOutgoingLinks(allMemories, memory.relativePath);
     const backlinks = getBacklinks(allMemories, memory.relativePath);
-    console.log(`Links for ${memory.frontmatter.title}:\n`);
-    if (outgoing.length > 0) {
-        console.log(`  Outgoing (${outgoing.length}):`);
-        for (const link of outgoing) {
-            const display = link.displayText ? ` (${link.displayText})` : "";
-            console.log(`    → [[${link.target}]]${display}`);
+    outputResult(!!opts.json, {
+        memoryPath: memPath,
+        title: memory.frontmatter.title,
+        outgoing,
+        backlinks,
+    }, () => {
+        console.log(`Links for ${memory.frontmatter.title}:\n`);
+        if (outgoing.length > 0) {
+            console.log(`  Outgoing (${outgoing.length}):`);
+            for (const link of outgoing) {
+                const display = link.displayText ? ` (${link.displayText})` : "";
+                console.log(`    → [[${link.target}]]${display}`);
+            }
         }
-    }
-    else {
-        console.log("  No outgoing links.");
-    }
-    console.log();
-    if (backlinks.length > 0) {
-        console.log(`  Backlinks (${backlinks.length}):`);
-        for (const link of backlinks) {
-            console.log(`    ← ${link.sourceTitle} (${link.sourcePath})`);
+        else {
+            console.log("  No outgoing links.");
         }
-    }
-    else {
-        console.log("  No backlinks.");
-    }
+        console.log();
+        if (backlinks.length > 0) {
+            console.log(`  Backlinks (${backlinks.length}):`);
+            for (const link of backlinks) {
+                console.log(`    ← ${link.sourceTitle} (${link.sourcePath})`);
+            }
+        }
+        else {
+            console.log("  No backlinks.");
+        }
+    });
 });
 // ─── gnosys graph ───────────────────────────────────────────────────────
 program
     .command("graph")
     .description("Show the [[wikilink]] cross-reference graph between memories. Empty until you start using [[Title]] in memory content — then this shows which memories reference each other.")
-    .action(async () => {
+    .option("--json", "Output as JSON")
+    .action(async (opts) => {
     // v5.4.1: Query the central DB directly. Previously this used the
     // filesystem resolver, which returns nothing in v5.x DB-only mode
     // because memories no longer live as markdown files.
@@ -2302,7 +2347,9 @@ program
         }
         const dbMemories = centralDb.getAllMemories();
         if (dbMemories.length === 0) {
-            console.log("No memories found.");
+            outputResult(!!opts.json, { totalLinks: 0, orphanedLinks: [], nodes: [] }, () => {
+                console.log("No memories found.");
+            });
             return;
         }
         // Adapt DbMemory → legacy Memory shape that buildLinkGraph expects.
@@ -2339,7 +2386,13 @@ program
             };
         });
         const graph = buildLinkGraph(adapted);
-        console.log(formatGraphSummary(graph));
+        outputResult(!!opts.json, {
+            totalLinks: graph.totalLinks,
+            orphanedLinks: graph.orphanedLinks,
+            nodes: Array.from(graph.nodes.values()),
+        }, () => {
+            console.log(formatGraphSummary(graph));
+        });
     }
     finally {
         centralDb?.close();
@@ -2689,6 +2742,7 @@ program
     .command("semantic-search <query>")
     .description("Search using semantic similarity only (requires embeddings)")
     .option("-l, --limit <n>", "Max results", "15")
+    .option("--json", "Output as JSON")
     .action(async (query, opts) => {
     const resolver = await getResolver();
     const stores = resolver.getStores();
@@ -2707,10 +2761,20 @@ program
     const embeddings = new GnosysEmbeddings(storePath);
     const hybridSearch = new GnosysHybridSearch(search, embeddings, resolver, storePath);
     const results = await hybridSearch.hybridSearch(query, parseInt(opts.limit), "semantic");
-    if (results.length === 0) {
-        console.log(`No semantic results for "${query}". Run gnosys reindex first.`);
-    }
-    else {
+    outputResult(!!opts.json, {
+        query,
+        count: results.length,
+        results: results.map((r) => ({
+            title: r.title,
+            relativePath: r.relativePath,
+            score: r.score,
+            snippet: r.snippet,
+        })),
+    }, () => {
+        if (results.length === 0) {
+            console.log(`No semantic results for "${query}". Run gnosys reindex first.`);
+            return;
+        }
         console.log(`Found ${results.length} semantic results for "${query}":\n`);
         for (const r of results) {
             console.log(`  ${r.title}`);
@@ -2718,7 +2782,7 @@ program
             console.log(`    Similarity: ${r.score.toFixed(4)}`);
             console.log(`    ${r.snippet.substring(0, 120)}...\n`);
         }
-    }
+    });
     search.close();
     embeddings.close();
 });
@@ -2732,6 +2796,7 @@ program
     .option("--federated", "Use federated search with tier boosting (project > user > global)")
     .option("--scope <scope>", "Filter by scope: project, user, global (comma-separated)")
     .option("-d, --directory <dir>", "Project directory for context")
+    .option("--json", "Output as JSON")
     .action(async (question, opts) => {
     const resolver = await getResolver();
     const stores = resolver.getStores();
@@ -2808,7 +2873,7 @@ program
         }
     }
     const mode = opts.mode;
-    const useStream = opts.stream !== false;
+    const useStream = opts.stream !== false && !opts.json;
     try {
         const result = await ask.ask(question, {
             limit: parseInt(opts.limit),
@@ -2827,25 +2892,35 @@ program
                 }
                 : undefined,
         });
-        if (!useStream) {
-            console.log(result.answer);
-        }
-        // Print sources
-        if (result.sources.length > 0) {
-            console.log("\n\n--- Sources ---");
-            for (const s of result.sources) {
-                console.log(`  [[${s.relativePath.split("/").pop()}]] — ${s.title}`);
+        outputResult(!!opts.json, {
+            question,
+            answer: result.answer,
+            sources: result.sources.map((s) => ({
+                title: s.title,
+                relativePath: s.relativePath,
+            })),
+            deepQueryUsed: result.deepQueryUsed ?? false,
+        }, () => {
+            if (!useStream) {
+                console.log(result.answer);
+            }
+            if (result.sources.length > 0) {
+                console.log("\n\n--- Sources ---");
+                for (const s of result.sources) {
+                    console.log(`  [[${s.relativePath.split("/").pop()}]] — ${s.title}`);
+                }
             }
-            // Reinforce used memories (best-effort)
+            if (result.deepQueryUsed) {
+                console.log("\n(Deep query was used — a follow-up search expanded the context)");
+            }
+        });
+        if (result.sources.length > 0) {
             const writeTarget = resolver.getWriteTarget();
             if (writeTarget) {
                 const { GnosysMaintenanceEngine } = await import("./lib/maintenance.js");
                 await GnosysMaintenanceEngine.reinforceBatch(writeTarget.store, result.sources.map((s) => s.relativePath)).catch(() => { });
             }
         }
-        if (result.deepQueryUsed) {
-            console.log("\n(Deep query was used — a follow-up search expanded the context)");
-        }
     }
     catch (err) {
         console.error(`Ask failed: ${err instanceof Error ? err.message : String(err)}`);
@@ -3254,7 +3329,7 @@ program
     }
     const archive = new GnosysArchive(writeTarget.path);
     if (!archive.isAvailable()) {
-        console.error("Archive not available. Is better-sqlite3 installed?");
+        console.error("Archive not available. Install it with: npm install better-sqlite3");
         process.exit(1);
     }
     const results = archive.searchArchive(query, parseInt(opts.limit));
@@ -3598,20 +3673,27 @@ program
 // global binary (see src/lib/upgrade.ts).
 program
     .command("upgrade")
-    .description("Upgrade gnosys itself (npm install -g gnosys@latest) and signal running MCP servers to restart. After upgrading, suggests running 'gnosys setup sync-projects'.")
+    .description("Upgrade gnosys itself and signal running MCP servers to restart. After upgrading, suggests running 'gnosys setup sync-projects'.")
     .option("--yes", "Skip the post-upgrade sync-projects prompt and exit")
     .option("--no-sync", "Don't suggest running sync-projects afterward")
     .action(async (opts) => {
     const currentVersion = pkg.version;
     console.log(`Gnosys CLI: currently v${currentVersion}`);
-    console.log(`Running: npm install -g gnosys@latest ...`);
+    const { detectPackageManager, upgradeCommand } = await import("./lib/packageManager.js");
+    const pm = detectPackageManager();
+    const cmd = upgradeCommand(pm);
+    if (!cmd) {
+        console.log("Running under npx — there's no global install to upgrade. Use `npx gnosys@latest` to run the latest.");
+        return;
+    }
+    console.log(`Running: ${cmd} ...`);
     const { execSync } = await import("child_process");
     try {
-        execSync("npm install -g gnosys@latest", { stdio: "inherit" });
+        execSync(cmd, { stdio: "inherit" });
     }
     catch (err) {
         console.error(`\nUpgrade failed: ${err instanceof Error ? err.message : err}`);
-        console.error(`Try running 'npm install -g gnosys@latest' manually.`);
+        console.error(`Try running '${cmd}' manually.`);
         process.exit(1);
     }
     // Read the newly-installed version (best-effort — we may still be the
@@ -3898,6 +3980,7 @@ async function isLegacyStoreSafeToRemove(localDbPath) {
     try {
         const Database = (await import("better-sqlite3")).default;
         const localDb = new Database(localDbPath, { readonly: true });
+        localDb.pragma("busy_timeout = 5000");
         let localIds = [];
         try {
             const rows = localDb.prepare("SELECT id FROM memories").all();
@@ -4322,6 +4405,9 @@ exportCmd
             const ratio = (result.compressedBytes / result.uncompressedBytes * 100).toFixed(1);
             console.log(`Exported project ${projectId}`);
             console.log(`  Memories:      ${result.memoryCount}`);
+            if (result.archivedExcluded > 0) {
+                console.log(`  Archived:      ${result.archivedExcluded} excluded — re-run with --include-archived for a full backup`);
+            }
             console.log(`  Relationships: ${result.relationshipCount}`);
             console.log(`  Audit entries: ${result.auditEntryCount}`);
             console.log(`  Bundle:        ${result.outputPath}`);
@@ -4337,7 +4423,18 @@ program
     .command("serve")
     .description("Start the MCP server (stdio mode). Used by IDE integrations — Claude Code/Desktop, Cursor, Codex, etc. spawn this command in the background to talk to gnosys via the Model Context Protocol. You don't normally invoke this yourself; `gnosys init <ide>` wires it into the IDE config.")
     .option("--with-maintenance", "Run maintenance every 6 hours in background")
+    .option("--transport <mode>", "Transport: 'stdio' (default) or 'http' (central-server topology)", "stdio")
+    .option("--host <addr>", "HTTP bind address — http transport (default 127.0.0.1; use a tailnet addr to share)", "127.0.0.1")
+    .option("--port <n>", "HTTP port — http transport", "7777")
+    .option("--token <token>", "Require 'Authorization: Bearer <token>' — http transport")
     .action(async (opts) => {
+    if (opts.transport === "http") {
+        process.env.GNOSYS_TRANSPORT = "http";
+        process.env.GNOSYS_HTTP_HOST = opts.host || "127.0.0.1";
+        process.env.GNOSYS_HTTP_PORT = String(opts.port || "7777");
+        if (opts.token)
+            process.env.GNOSYS_SERVE_TOKEN = opts.token;
+    }
     if (opts.withMaintenance) {
         // Start background maintenance loop
         const SIX_HOURS = 6 * 60 * 60 * 1000;
@@ -4715,6 +4812,150 @@ program
 function isDeadProjectDir(dir) {
     return !existsSync(dir);
 }
+program
+    .command("connect")
+    .description("Point an IDE at a remote gnosys server (central-server topology) instead of spawning a local one")
+    .requiredOption("--url <url>", "Remote MCP URL, e.g. http://studio.tailnet.ts.net:7777/mcp")
+    .option("--token <token>", "Bearer token if the server requires auth")
+    .option("--ide <ide>", "IDE config to write: cursor | claude-desktop", "cursor")
+    .option("--dir <dir>", "Project dir for cursor config (default: cwd)")
+    .option("--print", "Print the config snippet instead of writing files")
+    .action(async (opts) => {
+    const m = await import("./lib/mcpClientConfig.js");
+    const remote = { url: opts.url, token: opts.token };
+    if (opts.print) {
+        console.log(JSON.stringify({ mcpServers: { gnosys: m.remoteMcpEntry(remote) } }, null, 2));
+        return;
+    }
+    const ide = opts.ide === "claude-desktop" ? "claude-desktop" : "cursor";
+    try {
+        const file = await m.writeRemoteClientConfig(ide, opts.dir || process.cwd(), remote);
+        console.log(`✓ Pointed ${ide} at ${opts.url}`);
+        console.log(`  wrote: ${file}${opts.token ? "  (bearer token included)" : ""}`);
+        console.log("  Restart the IDE / MCP servers to pick it up.");
+    }
+    catch (e) {
+        console.error(`connect failed: ${e instanceof Error ? e.message : e}`);
+        process.exit(1);
+    }
+});
+program
+    .command("centralize")
+    .description("Copy this machine's local brain (~/.gnosys/gnosys.db) to seed a central server — a Docker volume or another host")
+    .requiredOption("--to <dir>", "Target directory to write gnosys.db into (e.g. a mounted volume)")
+    .option("--from-local", "Source is this machine's local brain (default)")
+    .option("--force", "Overwrite an existing gnosys.db at the target")
+    .action(async (opts) => {
+    const { centralizeDb } = await import("./lib/centralize.js");
+    try {
+        const r = await centralizeDb({ to: opts.to, force: opts.force });
+        const mb = (r.bytes / 1024 / 1024).toFixed(1);
+        console.log("✓ Seeded central brain:");
+        console.log(`  from: ${r.source}`);
+        console.log(`  to:   ${r.target} (${mb} MB)`);
+        console.log("");
+        console.log(`Run the server against it with GNOSYS_HOME=${opts.to}, or mount this dir as the container's /data volume.`);
+    }
+    catch (e) {
+        console.error(`centralize failed: ${e instanceof Error ? e.message : e}`);
+        process.exit(1);
+    }
+});
+const machineCmd = program
+    .command("machine")
+    .description("Manage this machine's local config (machine.json: machineId, roots, remote)");
+machineCmd
+    .command("show")
+    .description("Show this machine's machine.json")
+    .option("--json", "Output as JSON")
+    .action(async (opts) => {
+    const { readMachineConfig } = await import("./lib/machineConfig.js");
+    const { getMachineConfigPath } = await import("./lib/paths.js");
+    const cfg = readMachineConfig();
+    if (!cfg) {
+        console.log(`No machine.json yet (${getMachineConfigPath()}).`);
+        console.log("Run 'gnosys machine migrate' (existing setup) or 'gnosys scan' to create it.");
+        return;
+    }
+    outputResult(!!opts.json, cfg, () => {
+        console.log(`machine.json: ${getMachineConfigPath()}`);
+        console.log(`  machineId: ${cfg.machineId}`);
+        console.log(`  hostname:  ${cfg.hostname}`);
+        console.log(`  roots:     ${JSON.stringify(cfg.roots)}`);
+        console.log(`  remote:    ${cfg.remote.enabled ? (cfg.remote.path ?? "(enabled, no path)") : "(disabled)"}`);
+    });
+});
+machineCmd
+    .command("migrate")
+    .description("Move machine-local config (machineId, remote) out of the synced DB into machine.json, set roots, and scan")
+    .option("--root <dir>", "Set the 'dev' root for this machine (default: derived from the registry)")
+    .option("--no-scan", "Skip the project scan after migrating")
+    .action(async (opts) => {
+    const { migrateMachine } = await import("./lib/machineMigrate.js");
+    const { getMachineConfigPath } = await import("./lib/paths.js");
+    const db = GnosysDB.openLocal();
+    if (!db.isAvailable()) {
+        console.error("Central DB not available (better-sqlite3 missing).");
+        process.exit(1);
+    }
+    const res = await migrateMachine(db, { root: opts.root, scan: opts.scan });
+    db.close();
+    console.log(`✓ machine.json written: ${getMachineConfigPath()}`);
+    const idNote = res.adoptedMachineId
+        ? " (adopted from synced meta)"
+        : res.regeneratedMachineId ? " (regenerated)" : "";
+    console.log(`  machineId: ${res.machineId}${idNote}`);
+    if (res.adoptedRemotePath) {
+        console.log("  remote: adopted remote_path from synced meta (removed from shared DB)");
+    }
+    console.log(`  roots: ${JSON.stringify(res.rootsConfigured)}`);
+    if (res.scan) {
+        console.log(`  scanned ${res.scan.entries.length} project(s):`);
+        for (const e of res.scan.entries)
+            console.log(`    ${e.name}  [${e.mode}]  ${e.absPath}`);
+    }
+    else {
+        console.log("  (scan skipped — set a root in machine.json, then run 'gnosys scan')");
+    }
+});
+program
+    .command("scan")
+    .description("Discover projects under this machine's roots (machine.json) and record their machine-portable locations")
+    .option("--json", "Output as JSON")
+    .action(async (opts) => {
+    const { ensureMachineConfig } = await import("./lib/machineConfig.js");
+    const { getMachineConfigPath } = await import("./lib/paths.js");
+    const { scanProjects } = await import("./lib/projectScan.js");
+    const ens = ensureMachineConfig();
+    const machine = ens.config;
+    if (Object.keys(machine.roots).length === 0) {
+        console.error("No project roots configured for this machine.");
+        console.error(`Add roots to ${getMachineConfigPath()}, e.g.`);
+        console.error('  { "roots": { "dev": "/Users/edward/MSDev/projects" } }');
+        process.exit(1);
+    }
+    const db = GnosysDB.openCentral();
+    if (!db.isAvailable()) {
+        console.error("Central DB not available (better-sqlite3 missing).");
+        process.exit(1);
+    }
+    const result = await scanProjects(db, machine);
+    db.close();
+    outputResult(!!opts.json, {
+        machineId: machine.machineId,
+        roots: result.roots,
+        count: result.entries.length,
+        entries: result.entries,
+    }, () => {
+        if (ens.regenerated) {
+            console.log("⚠ machine.json hostname mismatch — regenerated machineId for this machine.\n");
+        }
+        console.log(`Scanned ${result.roots.length} root(s); registered ${result.entries.length} project(s):`);
+        for (const e of result.entries) {
+            console.log(`  ${e.name}  [${e.mode}]  ${e.absPath}`);
+        }
+    });
+});
 program
     .command("projects")
     .description("List registered projects from the central DB")
@@ -4732,6 +4973,16 @@ program
             process.exit(1);
         }
         const allProjects = centralDb.getAllProjects();
+        // v5.11: resolve each project's path for THIS machine (machine.json),
+        // falling back to working_directory when machine.json is absent.
+        const { readMachineConfig } = await import("./lib/machineConfig.js");
+        const { effectiveProjectPath } = await import("./lib/projectPaths.js");
+        const machine = readMachineConfig();
+        const resolvedDirOf = (p) => effectiveProjectPath(centralDb, p, machine);
+        const isNotHere = (p) => {
+            const ep = resolvedDirOf(p);
+            return ep === null || !existsSync(ep);
+        };
         if (opts.prune) {
             // Find dead projects first — never just delete without showing
             // them. v5.7.0 adds confirmation by default; --yes skips for
@@ -4776,10 +5027,10 @@ program
             });
             return;
         }
-        // Normal listing — filter dead projects by default
+        // Normal listing — filter dead / not-on-this-machine projects by default
         const visibleProjects = opts.all
             ? allProjects
-            : allProjects.filter((p) => !isDeadProjectDir(p.working_directory));
+            : allProjects.filter((p) => !isNotHere(p));
         if (visibleProjects.length === 0) {
             const deadCount = allProjects.length;
             outputResult(!!opts.json, {
@@ -4800,6 +5051,7 @@ program
         }
         const projectData = visibleProjects.map((p) => ({
             ...p,
+            resolvedDir: resolvedDirOf(p) ?? "(not on this machine)",
             memoryCount: centralDb.getMemoriesByProject(p.id).length,
         }));
         const deadCount = allProjects.length - visibleProjects.length;
@@ -4816,7 +5068,7 @@ program
             for (const p of projectData) {
                 console.log(`  ${p.name}`);
                 console.log(`    ID:        ${p.id}`);
-                console.log(`    Directory: ${p.working_directory}`);
+                console.log(`    Directory: ${p.resolvedDir}`);
                 console.log(`    Memories:  ${p.memoryCount}`);
                 console.log(`    Created:   ${p.created}`);
                 console.log();
@@ -4848,6 +5100,13 @@ prefCmd
             console.error("Central DB not available (better-sqlite3 missing).");
             process.exit(1);
         }
+        if (!KNOWN_PREFERENCE_KEYS.includes(key)) {
+            const suggestion = suggestPreferenceKey(key);
+            if (suggestion) {
+                console.error(`Unknown preference key \`${key}\` — did you mean \`${suggestion}\`?`);
+                process.exit(1);
+            }
+        }
         const tags = opts.tags ? opts.tags.split(",").map((t) => t.trim()) : undefined;
         const pref = setPreference(centralDb, key, value, { title: opts.title, tags });
         console.log(`Preference set: ${pref.title}`);
@@ -5288,8 +5547,8 @@ program
             const dashboardPath = path.join(home, "gnosys-dashboard.html");
             const { writeFileSync } = await import("fs");
             writeFileSync(dashboardPath, generatePortfolioHtml(report, dashboardPath), "utf-8");
-            const { exec } = await import("child_process");
-            exec(`open "${dashboardPath}"`);
+            const { execFile } = await import("child_process");
+            execFile("open", [dashboardPath]);
             console.log(`Dashboard opened: ${dashboardPath}`);
             return;
         }
@@ -5623,7 +5882,7 @@ program
         const dbDir = GnosysDB.getCentralDbDir();
         const db = new GnosysDB(dbDir);
         if (!db.isAvailable()) {
-            console.error("Error: GnosysDB not available. Is better-sqlite3 installed?");
+            console.error("Error: GnosysDB not available. Install it with: npm install better-sqlite3");
             process.exit(1);
         }
         const result = traceCodebase(db, directory, {
@@ -5668,7 +5927,7 @@ program
         const dbDir = GnosysDB.getCentralDbDir();
         const db = new GnosysDB(dbDir);
         if (!db.isAvailable()) {
-            console.error("Error: GnosysDB not available. Is better-sqlite3 installed?");
+            console.error("Error: GnosysDB not available. Install it with: npm install better-sqlite3");
             process.exit(1);
         }
         const params = {
@@ -5728,7 +5987,7 @@ program
         const dbDir = GnosysDB.getCentralDbDir();
         const db = new GnosysDB(dbDir);
         if (!db.isAvailable()) {
-            console.error("Error: GnosysDB not available. Is better-sqlite3 installed?");
+            console.error("Error: GnosysDB not available. Install it with: npm install better-sqlite3");
             process.exit(1);
         }
         const params = {
@@ -6416,7 +6675,11 @@ if (!isTestEnv()) {
         const centralDb = GnosysDB.openCentral();
         if (centralDb.isAvailable()) {
             const lastVersion = centralDb.getMeta("app_version");
-            const currentVersion = pkg.version;
+            // GNOSYS_FORCE_VERSION lets the upgrade-nag tests pin a synthetic
+            // "running" version independent of the real release number, so a .0
+            // minor release can't break the patch/minor scenarios. Production
+            // always falls through to pkg.version.
+            const currentVersion = process.env.GNOSYS_FORCE_VERSION || pkg.version;
             const isUpgradeCmd = process.argv.slice(2).some(a => a === "upgrade");
             const isSetupSyncCmd = process.argv.slice(2).join(" ").includes("setup sync-projects");
             // CRITICAL: `serve` writes JSON-RPC to stdout for MCP transport. Any
@@ -6461,4 +6724,3 @@ if (!isTestEnv()) {
     }
 }
 program.parse();
-//# sourceMappingURL=cli.js.map