gnosys 5.6.0 → 5.7.1

package/dist/cli.js

@@ -17,7 +17,7 @@ import { GnosysTagRegistry } from "./lib/tags.js";
 import { GnosysIngestion } from "./lib/ingest.js";
 import { applyLens } from "./lib/lensing.js";
 import { getFileHistory, rollbackToCommit, hasGitHistory, getFileDiff } from "./lib/history.js";
-import { groupByPeriod, computeStats } from "./lib/timeline.js";
+import { computeStats } from "./lib/timeline.js";
 import { buildLinkGraph, getBacklinks, getOutgoingLinks, formatGraphSummary } from "./lib/wikilinks.js";
 import { bootstrap, discoverFiles } from "./lib/bootstrap.js";
 import { performImport, formatImportSummary } from "./lib/import.js";
@@ -163,6 +163,23 @@ program
     .name("gnosys")
     .description("Gnosys — Persistent memory for AI agents. Sandbox-first runtime, central SQLite brain, federated search, reflection API, process tracing, preferences, Dream Mode, Obsidian export. Also runs as a full MCP server.")
     .version(pkg.version)
+    .addHelpText("after", `
+Commands by group (alphabetical within group):
+  Setup & status:    setup · status · doctor · check · upgrade
+  Memory ops:        add · add-structured · update · read · reinforce · ingest
+                     bootstrap · import · export
+  Search:            discover · search · hybrid-search · semantic-search · ask · recall
+                     fsearch · briefing · lens
+  Project mgmt:      init · projects · list · stats · timeline · graph · tags · tags-add
+                     stale · history · rollback · audit · links
+  Chat (TUI):        chat
+  Maintenance:       maintain · reindex · reindex-graph · dearchive · dream · backup · restore · prune
+  Multi-machine:     setup remote (configure | status | push | pull | sync | resolve)
+  Agent runtime:     serve · sandbox · helper · pref · sync · update-status · working-set
+  Legacy / advanced: dashboard · migrate · migrate-db · stores · config
+
+Run 'gnosys <command> --help' for command-specific help.
+`)
     .hook("preAction", async () => {
     // Check if central DB was upgraded to a newer version on another machine
     try {
@@ -208,6 +225,7 @@ program
     .option("--federated", "Use federated discovery with tier boosting (project > user > global)")
     .option("--scope <scope>", "Filter by scope: project, user, global (comma-separated for multiple)")
     .option("-d, --directory <dir>", "Project directory for context")
+    .option("--id-format <format>", "ID display format: short | long | raw (default: short)", "short")
     .action(async (query, opts) => {
     // Federated discover path
     if (opts.federated || opts.scope) {
@@ -262,11 +280,16 @@ program
             });
             return;
         }
+        const { formatMemoryId, buildProjectNameLookup, parseIdFormat } = await import("./lib/idFormat.js");
+        const idFormat = parseIdFormat(opts.idFormat);
+        const projectNames = buildProjectNameLookup(centralDb);
         outputResult(!!opts.json, { query, count: results.length, results }, () => {
             console.log(`Found ${results.length} relevant memories for "${query}":\n`);
             for (const r of results) {
+                const projectName = r.project_id ? projectNames.get(r.project_id) || null : null;
+                const displayId = formatMemoryId(r.id, projectName, idFormat);
                 console.log(`  ${r.title}`);
-                console.log(`    id: ${r.id}`);
+                console.log(`    id: ${displayId}`);
                 if (r.relevance)
                     console.log(`    Relevance: ${r.relevance}`);
                 console.log();
@@ -374,6 +397,7 @@ program
     .option("-t, --tag <tag>", "Filter by tag")
     .option("-s, --store <store>", "Filter by store layer (project|user|global)")
     .option("--json", "Output as JSON")
+    .option("--id-format <format>", "ID display format: short | long | raw (default: short)", "short")
     .action(async (opts) => {
     let centralDb = null;
     try {
@@ -407,6 +431,9 @@ program
                 }
             });
         }
+        const { formatMemoryId, buildProjectNameLookup, parseIdFormat } = await import("./lib/idFormat.js");
+        const idFormat = parseIdFormat(opts.idFormat);
+        const projectNames = buildProjectNameLookup(centralDb);
         outputResult(!!opts.json, {
             count: memories.length,
             memories: memories.map((m) => ({
@@ -416,12 +443,15 @@ program
                 status: m.status,
                 scope: m.scope,
                 confidence: m.confidence,
+                project: m.project_id ? projectNames.get(m.project_id) || null : null,
             })),
         }, () => {
             console.log(`${memories.length} memories:\n`);
             for (const m of memories) {
+                const projectName = m.project_id ? projectNames.get(m.project_id) || null : null;
+                const displayId = formatMemoryId(m.id, projectName, idFormat);
                 console.log(`  [${m.scope}] [${m.status}] ${m.title}`);
-                console.log(`    id: ${m.id} | category: ${m.category} | confidence: ${m.confidence}`);
+                console.log(`    id: ${displayId} | category: ${m.category} | confidence: ${m.confidence}`);
                 console.log();
             }
         });
@@ -543,13 +573,26 @@ program
 const setupCmd = program
     .command("setup")
     .description("Configure Gnosys — LLM provider, models, remote sync, and IDE integration");
-// Bare `gnosys setup` runs the full interactive wizard
+// Bare `gnosys setup` — when config exists, opens the summary-first menu
+// so the user can edit one section without re-running the whole wizard.
+// First-time setup or `--full` runs the linear 5-step flow.
 setupCmd
     .option("--non-interactive", "Skip prompts, use defaults (for CI/scripting)")
+    .option("--full", "Run the linear 5-step wizard even when a config exists")
     .action(async (opts) => {
     const { runSetup } = await import("./lib/setup.js");
+    const projectDir = process.cwd();
+    // Detect existing config — if present and the user didn't pass --full,
+    // route to the summary-first menu.
+    const configPath = path.join(os.homedir(), ".gnosys", "gnosys.json");
+    const hasConfig = existsSync(configPath);
+    if (hasConfig && !opts.full && !opts.nonInteractive) {
+        const { runSummaryWizard } = await import("./lib/setup/summary.js");
+        await runSummaryWizard({ directory: projectDir });
+        return;
+    }
     await runSetup({
-        directory: process.cwd(),
+        directory: projectDir,
         nonInteractive: opts.nonInteractive,
     });
 });
@@ -569,14 +612,17 @@ setupCmd
         validate: opts.validate,
     });
 });
-// `gnosys setup remote` — configure remote sync (alias for `gnosys remote configure`)
-setupCmd
+// ─── gnosys setup remote (parent + subcommands) ────────────────────────
+// v5.7.0: the standalone `gnosys remote` parent was dropped; everything
+// (configure, status, push, pull, sync, resolve) lives here now.
+const setupRemoteCmd = setupCmd
     .command("remote")
-    .description("Configure multi-machine sync (NAS/shared drive)")
+    .description("Multi-machine sync — configure, sync, and resolve conflicts");
+// Bare `gnosys setup remote` — configure wizard (back-compat with v5.6.x)
+setupRemoteCmd
     .option("--path <path>", "Set remote path directly (non-interactive)")
     .action(async (opts) => {
     const { GnosysDB } = await import("./lib/db.js");
-    // Sync configuration needs explicit local DB access (not auto-routed remote).
     const db = GnosysDB.openLocal();
     if (!db.isAvailable()) {
         console.error("Central DB not available.");
@@ -597,6 +643,265 @@ setupCmd
         db.close();
     }
 });
+setupRemoteCmd
+    .command("status")
+    .description("Show remote sync status: pending changes, conflicts, last sync")
+    .option("--json", "Output as JSON")
+    .action(async (opts) => {
+    let centralDb = null;
+    try {
+        centralDb = GnosysDB.openLocal();
+        if (!centralDb.isAvailable()) {
+            console.error("Central DB not available.");
+            process.exit(1);
+        }
+        const remotePath = centralDb.getMeta("remote_path");
+        if (!remotePath) {
+            if (opts.json) {
+                console.log(JSON.stringify({ configured: false, message: "Remote not configured. Run 'gnosys setup remote'." }, null, 2));
+            }
+            else {
+                console.log("Remote sync: not configured.");
+                console.log("Run 'gnosys setup remote' to set up multi-machine sync.");
+            }
+            return;
+        }
+        const { RemoteSync, formatStatus } = await import("./lib/remote.js");
+        const { withHeartbeat } = await import("./lib/heartbeat.js");
+        const sync = new RemoteSync(centralDb, remotePath);
+        const status = await withHeartbeat("Checking remote sync status", () => sync.getStatus());
+        sync.closeRemote();
+        if (opts.json) {
+            console.log(JSON.stringify(status, null, 2));
+        }
+        else {
+            console.log(formatStatus(status));
+            if (status.conflicts.length > 0) {
+                console.log("\nConflicts:");
+                for (const c of status.conflicts) {
+                    console.log(`  ${c.memoryId}: ${c.title}`);
+                    console.log(`    local:  ${c.localModified}`);
+                    console.log(`    remote: ${c.remoteModified}`);
+                }
+                console.log("\nResolve with: gnosys setup remote resolve <memory-id> --keep <local|remote>");
+            }
+        }
+    }
+    catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : err}`);
+        process.exit(1);
+    }
+    finally {
+        centralDb?.close();
+    }
+});
+setupRemoteCmd
+    .command("push")
+    .description("Push local changes to remote")
+    .option("--newer-wins", "Auto-resolve conflicts by taking the newer version")
+    .option("--verbose", "Stream per-memory progress to stderr")
+    .action(async (opts) => {
+    let centralDb = null;
+    try {
+        centralDb = GnosysDB.openLocal();
+        if (!centralDb.isAvailable()) {
+            console.error("Central DB not available.");
+            process.exit(1);
+        }
+        const remotePath = centralDb.getMeta("remote_path");
+        if (!remotePath) {
+            console.error("Remote not configured.");
+            process.exit(1);
+        }
+        const { RemoteSync } = await import("./lib/remote.js");
+        const { withHeartbeat } = await import("./lib/heartbeat.js");
+        const { createProgress } = await import("./lib/progress.js");
+        const progress = createProgress(!!opts.verbose);
+        const sync = new RemoteSync(centralDb, remotePath);
+        // Suppress heartbeat when verbose is on (progress already streams).
+        const runPush = () => sync.push({
+            strategy: opts.newerWins ? "newer-wins" : "skip-and-flag",
+            onProgress: progress.noop ? undefined : progress.emit.bind(progress),
+        });
+        const result = opts.verbose
+            ? await runPush()
+            : await withHeartbeat("Pushing to remote", runPush);
+        sync.closeRemote();
+        const projParts = (result.projectsPushed || 0) > 0 ? ` | Projects pushed: ${result.projectsPushed}` : "";
+        const auditParts = (result.auditPushed || 0) > 0 ? ` | Audit pushed: ${result.auditPushed}` : "";
+        console.log(`Pushed: ${result.pushed} | Skipped: ${result.skipped} | Conflicts: ${result.conflicts.length}${projParts}${auditParts}`);
+        if (result.errors.length > 0) {
+            console.log("\nErrors:");
+            for (const e of result.errors)
+                console.log(`  ${e}`);
+        }
+        if (result.conflicts.length > 0) {
+            console.log("\nConflicts flagged (run 'gnosys setup remote status' for details):");
+            for (const c of result.conflicts)
+                console.log(`  ${c.memoryId} — ${c.title}`);
+        }
+    }
+    catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : err}`);
+        process.exit(1);
+    }
+    finally {
+        centralDb?.close();
+    }
+});
+setupRemoteCmd
+    .command("pull")
+    .description("Pull remote changes to local")
+    .option("--newer-wins", "Auto-resolve conflicts by taking the newer version")
+    .option("--verbose", "Stream per-memory progress to stderr")
+    .action(async (opts) => {
+    let centralDb = null;
+    try {
+        centralDb = GnosysDB.openLocal();
+        if (!centralDb.isAvailable()) {
+            console.error("Central DB not available.");
+            process.exit(1);
+        }
+        const remotePath = centralDb.getMeta("remote_path");
+        if (!remotePath) {
+            console.error("Remote not configured.");
+            process.exit(1);
+        }
+        const { RemoteSync } = await import("./lib/remote.js");
+        const { withHeartbeat } = await import("./lib/heartbeat.js");
+        const { createProgress } = await import("./lib/progress.js");
+        const progress = createProgress(!!opts.verbose);
+        const sync = new RemoteSync(centralDb, remotePath);
+        const runPull = () => sync.pull({
+            strategy: opts.newerWins ? "newer-wins" : "skip-and-flag",
+            onProgress: progress.noop ? undefined : progress.emit.bind(progress),
+        });
+        const result = opts.verbose
+            ? await runPull()
+            : await withHeartbeat("Pulling from remote", runPull);
+        sync.closeRemote();
+        const projParts = (result.projectsPulled || 0) > 0 ? ` | Projects pulled: ${result.projectsPulled}` : "";
+        const auditParts = (result.auditPulled || 0) > 0 ? ` | Audit pulled: ${result.auditPulled}` : "";
+        console.log(`Pulled: ${result.pulled} | Skipped: ${result.skipped} | Conflicts: ${result.conflicts.length}${projParts}${auditParts}`);
+        if (result.errors.length > 0) {
+            console.log("\nErrors:");
+            for (const e of result.errors)
+                console.log(`  ${e}`);
+        }
+    }
+    catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : err}`);
+        process.exit(1);
+    }
+    finally {
+        centralDb?.close();
+    }
+});
+setupRemoteCmd
+    .command("sync")
+    .description("Two-way sync: push local changes then pull remote changes")
+    .option("--auto", "Run silently for cron/LaunchAgent (skip-and-flag for conflicts)")
+    .option("--newer-wins", "Auto-resolve conflicts by taking the newer version")
+    .option("--verbose", "Stream per-memory progress to stderr")
+    .action(async (opts) => {
+    let centralDb = null;
+    try {
+        centralDb = GnosysDB.openLocal();
+        if (!centralDb.isAvailable()) {
+            if (!opts.auto)
+                console.error("Central DB not available.");
+            process.exit(1);
+        }
+        const remotePath = centralDb.getMeta("remote_path");
+        if (!remotePath) {
+            if (!opts.auto)
+                console.error("Remote not configured.");
+            process.exit(opts.auto ? 0 : 1);
+        }
+        const { RemoteSync } = await import("./lib/remote.js");
+        const { withHeartbeat } = await import("./lib/heartbeat.js");
+        const { createProgress } = await import("./lib/progress.js");
+        const progress = createProgress(!!opts.verbose);
+        const sync = new RemoteSync(centralDb, remotePath);
+        const runSync = () => sync.sync({
+            auto: opts.auto,
+            strategy: opts.newerWins ? "newer-wins" : "skip-and-flag",
+            onProgress: progress.noop ? undefined : progress.emit.bind(progress),
+        });
+        // Auto mode + verbose mode both bypass the heartbeat. Auto mode is
+        // for non-interactive runs (no spinner). Verbose streams its own output.
+        const result = opts.auto || opts.verbose
+            ? await runSync()
+            : await withHeartbeat("Syncing with remote", runSync);
+        sync.closeRemote();
+        if (!opts.auto || result.conflicts.length > 0 || result.errors.length > 0) {
+            const pp = result.projectsPushed || 0;
+            const pl = result.projectsPulled || 0;
+            const ap = result.auditPushed || 0;
+            const al = result.auditPulled || 0;
+            const projParts = (pp + pl) > 0 ? ` | Projects: ↑${pp}/↓${pl}` : "";
+            const auditParts = (ap + al) > 0 ? ` | Audit: ↑${ap}/↓${al}` : "";
+            console.log(`Pushed: ${result.pushed} | Pulled: ${result.pulled} | Conflicts: ${result.conflicts.length}${projParts}${auditParts}`);
+            if (result.errors.length > 0) {
+                console.log("\nErrors:");
+                for (const e of result.errors)
+                    console.log(`  ${e}`);
+            }
+            if (result.conflicts.length > 0) {
+                console.log("\nConflicts need resolution (run 'gnosys setup remote status' for details).");
+            }
+        }
+    }
+    catch (err) {
+        if (!opts.auto)
+            console.error(`Error: ${err instanceof Error ? err.message : err}`);
+        process.exit(1);
+    }
+    finally {
+        centralDb?.close();
+    }
+});
+setupRemoteCmd
+    .command("resolve <memoryId>")
+    .description("Resolve a sync conflict by choosing local, remote, or merged content")
+    .option("--keep <choice>", "Choice: local | remote", "local")
+    .action(async (memoryId, opts) => {
+    let centralDb = null;
+    try {
+        centralDb = GnosysDB.openLocal();
+        if (!centralDb.isAvailable()) {
+            console.error("Central DB not available.");
+            process.exit(1);
+        }
+        const remotePath = centralDb.getMeta("remote_path");
+        if (!remotePath) {
+            console.error("Remote not configured.");
+            process.exit(1);
+        }
+        if (opts.keep !== "local" && opts.keep !== "remote") {
+            console.error(`--keep must be 'local' or 'remote' (got: ${opts.keep})`);
+            process.exit(1);
+        }
+        const { RemoteSync } = await import("./lib/remote.js");
+        const sync = new RemoteSync(centralDb, remotePath);
+        const result = await sync.resolve(memoryId, opts.keep);
+        sync.closeRemote();
+        if (result.ok) {
+            console.log(`Resolved ${memoryId}: kept ${opts.keep} version.`);
+        }
+        else {
+            console.error(`Failed to resolve: ${result.error}`);
+            process.exit(1);
+        }
+    }
+    catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : err}`);
+        process.exit(1);
+    }
+    finally {
+        centralDb?.close();
+    }
+});
 // `gnosys setup dream` — configure dream mode (designation, provider, schedule)
 setupCmd
     .command("dream")
@@ -605,6 +910,51 @@ setupCmd
     const { runDreamSetup } = await import("./lib/setup.js");
     await runDreamSetup({ directory: process.cwd() });
 });
+// `gnosys setup ides` — configure IDE / MCP integrations standalone
+setupCmd
+    .command("ides")
+    .description("Configure IDE integrations (Claude Code/Desktop, Cursor, Codex, Gemini CLI, Antigravity)")
+    .action(async () => {
+    const readline = await import("readline/promises");
+    const { runIdesSetup } = await import("./lib/setup/sections/ides.js");
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        await runIdesSetup({ rl, directory: process.cwd() });
+    }
+    finally {
+        rl.close();
+    }
+});
+// `gnosys setup routing` — task-routing wizard standalone
+setupCmd
+    .command("routing")
+    .description("Configure per-task LLM routing (structuring, synthesis, vision, transcription, dream)")
+    .action(async () => {
+    const readline = await import("readline/promises");
+    const { runRoutingSetup } = await import("./lib/setup/sections/routing.js");
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        await runRoutingSetup({ rl, directory: process.cwd() });
+    }
+    finally {
+        rl.close();
+    }
+});
+// `gnosys setup preferences` — review user-scope preferences
+setupCmd
+    .command("preferences")
+    .description("Review and clean up user-scope preferences (incl. legacy imports)")
+    .action(async () => {
+    const readline = await import("readline/promises");
+    const { runPreferencesReview } = await import("./lib/setup/sections/preferences.js");
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        await runPreferencesReview(rl);
+    }
+    finally {
+        rl.close();
+    }
+});
 // v5.4.2 removal: `gnosys models` (top-level shortcut) was removed in favor
 // of the canonical `gnosys setup models` form. The implementation function
 // runModelsCommand() in setup.ts is no longer wired but kept for now in case
@@ -1681,34 +2031,51 @@ program
     .command("timeline")
     .description("Show when memories were created and modified over time")
     .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")
     .action(async (opts) => {
-    const resolver = await getResolver();
-    const allMemories = await resolver.getAllMemories();
-    if (allMemories.length === 0) {
-        console.log("No memories found.");
-        return;
+    const { groupDbByPeriod } = await import("./lib/timeline.js");
+    const centralDb = GnosysDB.openCentral();
+    if (!centralDb.isAvailable()) {
+        console.error("Central DB unavailable.");
+        process.exit(1);
     }
-    const entries = groupByPeriod(allMemories, opts.period);
-    console.log(`Knowledge Timeline (by ${opts.period}):\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 <= 5) {
-            for (const t of entry.titles) {
-                console.log(`    + ${t}`);
+    try {
+        const memories = opts.project
+            ? centralDb.getMemoriesByProject(opts.project)
+            : centralDb.getActiveMemories();
+        if (memories.length === 0) {
+            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}`);
+                }
             }
         }
     }
+    finally {
+        centralDb.close();
+    }
 });
 // ─── gnosys stats ───────────────────────────────────────────────────────
 program
     .command("stats")
-    .description("Show summary statistics for the memory store")
+    .description("Show summary statistics for the memory store. Use --by-project for a per-project breakdown across the central DB.")
     .option("--json", "Output as JSON")
+    .option("--by-project", "Show a per-project breakdown table instead of single-store stats")
+    .option("--all", "Include all projects (don't filter to current project)")
     .action(async (opts) => {
     let centralDb = null;
     try {
@@ -1717,8 +2084,66 @@ program
             console.error("Central DB not available. Run 'gnosys init' first.");
             process.exit(1);
         }
+        // v5.7.0: --by-project shows a per-project breakdown across the entire
+        // central DB (memories, archived, never reinforced, etc.) as a table.
+        if (opts.byProject) {
+            const projects = centralDb.getAllProjects();
+            const all = centralDb.getAllMemories();
+            const rows = projects.map((p) => {
+                const ms = all.filter((m) => m.project_id === p.id);
+                const active = ms.filter((m) => m.tier === "active" && m.status === "active").length;
+                const archived = ms.filter((m) => m.tier === "archive").length;
+                const reinforced = ms.reduce((sum, m) => sum + (m.reinforcement_count ?? 0), 0);
+                const lastTouch = ms.reduce((m, x) => (x.modified > m ? x.modified : m), "0");
+                return { name: p.name, id: p.id, active, archived, reinforced, lastTouch };
+            });
+            // User/global memories (no project_id)
+            const userScope = all.filter((m) => !m.project_id && m.scope === "user");
+            const globalScope = all.filter((m) => !m.project_id && m.scope === "global");
+            if (userScope.length > 0) {
+                rows.push({
+                    name: "(user)",
+                    id: "—",
+                    active: userScope.filter((m) => m.tier === "active" && m.status === "active").length,
+                    archived: userScope.filter((m) => m.tier === "archive").length,
+                    reinforced: userScope.reduce((sum, m) => sum + (m.reinforcement_count ?? 0), 0),
+                    lastTouch: userScope.reduce((m, x) => (x.modified > m ? x.modified : m), "0"),
+                });
+            }
+            if (globalScope.length > 0) {
+                rows.push({
+                    name: "(global)",
+                    id: "—",
+                    active: globalScope.filter((m) => m.tier === "active" && m.status === "active").length,
+                    archived: globalScope.filter((m) => m.tier === "archive").length,
+                    reinforced: globalScope.reduce((sum, m) => sum + (m.reinforcement_count ?? 0), 0),
+                    lastTouch: globalScope.reduce((m, x) => (x.modified > m ? x.modified : m), "0"),
+                });
+            }
+            rows.sort((a, b) => b.active - a.active);
+            if (opts.json) {
+                console.log(JSON.stringify({ rows }, null, 2));
+                return;
+            }
+            const nameW = Math.max(8, ...rows.map((r) => r.name.length));
+            const idW = 12;
+            console.log("");
+            console.log(`  ${"PROJECT".padEnd(nameW)}  ${"ID".padEnd(idW)}  ${"ACTIVE".padStart(7)}  ${"ARCHIVED".padStart(8)}  ${"REINF".padStart(6)}  LAST MODIFIED`);
+            console.log(`  ${"-".repeat(nameW + idW + 7 + 8 + 6 + 19 + 10)}`);
+            for (const r of rows) {
+                const last = r.lastTouch === "0" ? "—" : r.lastTouch.slice(0, 19);
+                const idShort = r.id === "—" ? "—" : r.id.slice(0, idW);
+                console.log(`  ${r.name.padEnd(nameW)}  ${idShort.padEnd(idW)}  ${String(r.active).padStart(7)}  ${String(r.archived).padStart(8)}  ${String(r.reinforced).padStart(6)}  ${last}`);
+            }
+            const totalActive = rows.reduce((s, r) => s + r.active, 0);
+            console.log(`  ${"-".repeat(nameW + idW + 7 + 8 + 6 + 19 + 10)}`);
+            console.log(`  ${"TOTAL".padEnd(nameW)}  ${" ".repeat(idW)}  ${String(totalActive).padStart(7)}`);
+            console.log("");
+            return;
+        }
+        // Default behavior: scoped stats (current project + user/global, OR --all)
         const projIdentity = await findProjectIdentity(process.cwd());
-        const projectId = projIdentity?.identity.projectId || null;
+        const projectId = !opts.all && projIdentity?.identity.projectId || null;
         let dbMemories = centralDb.getActiveMemories();
         if (projectId) {
             dbMemories = dbMemories.filter((m) => m.project_id === projectId || m.scope === "user" || m.scope === "global");
@@ -1821,7 +2246,7 @@ program
 // ─── gnosys graph ───────────────────────────────────────────────────────
 program
     .command("graph")
-    .description("Show the full cross-reference graph across all memories")
+    .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 () => {
     // v5.4.1: Query the central DB directly. Previously this used the
     // filesystem resolver, which returns nothing in v5.x DB-only mode
@@ -2091,7 +2516,7 @@ importCmd
 // ─── gnosys reindex ──────────────────────────────────────────────────────
 program
     .command("reindex")
-    .description("Rebuild all semantic embeddings from every memory file. Downloads the model (~80 MB) on first run.")
+    .description("Rebuild semantic embeddings for every memory in the central DB. Run after bulk imports, schema changes, or if hybrid search starts returning poor matches. Downloads the all-MiniLM-L6-v2 model (~80 MB) on first run.")
     .action(async () => {
     const resolver = await getResolver();
     const stores = resolver.getStores();
@@ -2627,39 +3052,9 @@ program
     console.log("");
     console.log(formatGraphStats(stats));
 });
-// ─── gnosys dashboard ───────────────────────────────────────────────────
-program
-    .command("dashboard")
-    .description("Show system dashboard: memory count, health, graph stats, LLM status")
-    .option("--json", "Output as JSON instead of pretty table")
-    .action(async (opts) => {
-    const { collectDashboardData, formatDashboard, formatDashboardJSON } = await import("./lib/dashboard.js");
-    const resolver = await getResolver();
-    const stores = resolver.getStores();
-    if (stores.length === 0) {
-        console.error("No Gnosys stores found. Run gnosys init first.");
-        process.exit(1);
-    }
-    const cfg = await loadConfig(stores[0].path);
-    // v5.1: Use central DB for dashboard stats
-    let dashDb;
-    try {
-        const db = GnosysDB.openCentral();
-        if (db.isAvailable() && db.isMigrated()) {
-            dashDb = db;
-        }
-    }
-    catch {
-        // Central DB not available — legacy dashboard only
-    }
-    const data = await collectDashboardData(resolver, cfg, pkg.version, dashDb);
-    if (opts.json) {
-        console.log(formatDashboardJSON(data));
-    }
-    else {
-        console.log(formatDashboard(data));
-    }
-});
+// `gnosys dashboard` was removed in v5.7.1.
+// Use `gnosys status --system` instead. Hard removal — commander will emit
+// the standard "unknown command" error.
 // ─── gnosys maintain ─────────────────────────────────────────────────────
 program
     .command("maintain")
@@ -2687,299 +3082,75 @@ program
                 console.log(`→ ${message}`);
             }
             else {
-                console.log(message);
-            }
-        },
-        onProgress: (step, current, total) => {
-            process.stdout.write(`\r[${current}/${total}] ${step}...`);
-            if (current === total)
-                process.stdout.write("\n");
-        },
-    });
-    console.log("");
-    console.log(formatMaintenanceReport(report));
-});
-// ─── gnosys dearchive ───────────────────────────────────────────────────
-program
-    .command("dearchive <query>")
-    .description("Force-dearchive memories matching a query from archive.db back to active")
-    .option("--limit <n>", "Max memories to dearchive", "5")
-    .action(async (query, opts) => {
-    const { GnosysArchive } = await import("./lib/archive.js");
-    const resolver = await getResolver();
-    const stores = resolver.getStores();
-    if (stores.length === 0) {
-        console.error("No Gnosys stores found. Run gnosys init first.");
-        process.exit(1);
-    }
-    const writeTarget = resolver.getWriteTarget();
-    if (!writeTarget) {
-        console.error("No writable store found.");
-        process.exit(1);
-    }
-    const archive = new GnosysArchive(writeTarget.path);
-    if (!archive.isAvailable()) {
-        console.error("Archive not available. Is better-sqlite3 installed?");
-        process.exit(1);
-    }
-    const results = archive.searchArchive(query, parseInt(opts.limit));
-    if (results.length === 0) {
-        console.log(`No archived memories found matching "${query}".`);
-        archive.close();
-        return;
-    }
-    console.log(`Found ${results.length} archived memories matching "${query}":\n`);
-    for (const r of results) {
-        console.log(`  • ${r.title} (${r.id})`);
-    }
-    console.log("");
-    // Dearchive all found
-    const ids = results.map((r) => r.id);
-    const restored = await archive.dearchiveBatch(ids, writeTarget.store);
-    archive.close();
-    console.log(`Dearchived ${restored.length} memories back to active:`);
-    for (const rp of restored) {
-        console.log(`  → ${rp}`);
-    }
-});
-// NOTE: gnosys migrate is defined below (near the end) with --to-central support
-// ─── gnosys remote (multi-machine sync) ────────────────────────────────
-const remoteCmd = program
-    .command("remote")
-    .description("Multi-machine sync — share gnosys.db across machines via NAS or shared drive");
-remoteCmd
-    .command("status")
-    .description("Show remote sync status: pending changes, conflicts, last sync")
-    .option("--json", "Output as JSON")
-    .action(async (opts) => {
-    let centralDb = null;
-    try {
-        // Sync operations need explicit local DB access (not auto-routed remote).
-        centralDb = GnosysDB.openLocal();
-        if (!centralDb.isAvailable()) {
-            console.error("Central DB not available.");
-            process.exit(1);
-        }
-        const remotePath = centralDb.getMeta("remote_path");
-        if (!remotePath) {
-            if (opts.json) {
-                console.log(JSON.stringify({ configured: false, message: "Remote not configured. Run 'gnosys remote configure'." }, null, 2));
-            }
-            else {
-                console.log("Remote sync: not configured.");
-                console.log("Run 'gnosys remote configure' to set up multi-machine sync.");
-            }
-            return;
-        }
-        const { RemoteSync, formatStatus } = await import("./lib/remote.js");
-        const sync = new RemoteSync(centralDb, remotePath);
-        const status = await sync.getStatus();
-        sync.closeRemote();
-        if (opts.json) {
-            console.log(JSON.stringify(status, null, 2));
-        }
-        else {
-            console.log(formatStatus(status));
-            if (status.conflicts.length > 0) {
-                console.log("\nConflicts:");
-                for (const c of status.conflicts) {
-                    console.log(`  ${c.memoryId}: ${c.title}`);
-                    console.log(`    local:  ${c.localModified}`);
-                    console.log(`    remote: ${c.remoteModified}`);
-                }
-                console.log("\nResolve with: gnosys remote resolve <memory-id> --keep <local|remote>");
-            }
-        }
-    }
-    catch (err) {
-        console.error(`Error: ${err instanceof Error ? err.message : err}`);
-        process.exit(1);
-    }
-    finally {
-        centralDb?.close();
-    }
-});
-remoteCmd
-    .command("push")
-    .description("Push local changes to remote")
-    .option("--newer-wins", "Auto-resolve conflicts by taking the newer version")
-    .action(async (opts) => {
-    let centralDb = null;
-    try {
-        centralDb = GnosysDB.openLocal();
-        if (!centralDb.isAvailable()) {
-            console.error("Central DB not available.");
-            process.exit(1);
-        }
-        const remotePath = centralDb.getMeta("remote_path");
-        if (!remotePath) {
-            console.error("Remote not configured.");
-            process.exit(1);
-        }
-        const { RemoteSync } = await import("./lib/remote.js");
-        const sync = new RemoteSync(centralDb, remotePath);
-        const result = await sync.push({ strategy: opts.newerWins ? "newer-wins" : "skip-and-flag" });
-        sync.closeRemote();
-        const projParts = (result.projectsPushed || 0) > 0 ? ` | Projects pushed: ${result.projectsPushed}` : "";
-        console.log(`Pushed: ${result.pushed} | Skipped: ${result.skipped} | Conflicts: ${result.conflicts.length}${projParts}`);
-        if (result.errors.length > 0) {
-            console.log("\nErrors:");
-            for (const e of result.errors)
-                console.log(`  ${e}`);
-        }
-        if (result.conflicts.length > 0) {
-            console.log("\nConflicts flagged (run 'gnosys remote status' for details):");
-            for (const c of result.conflicts)
-                console.log(`  ${c.memoryId} — ${c.title}`);
-        }
-    }
-    catch (err) {
-        console.error(`Error: ${err instanceof Error ? err.message : err}`);
-        process.exit(1);
-    }
-    finally {
-        centralDb?.close();
-    }
-});
-remoteCmd
-    .command("pull")
-    .description("Pull remote changes to local")
-    .option("--newer-wins", "Auto-resolve conflicts by taking the newer version")
-    .action(async (opts) => {
-    let centralDb = null;
-    try {
-        centralDb = GnosysDB.openLocal();
-        if (!centralDb.isAvailable()) {
-            console.error("Central DB not available.");
-            process.exit(1);
-        }
-        const remotePath = centralDb.getMeta("remote_path");
-        if (!remotePath) {
-            console.error("Remote not configured.");
-            process.exit(1);
-        }
-        const { RemoteSync } = await import("./lib/remote.js");
-        const sync = new RemoteSync(centralDb, remotePath);
-        const result = await sync.pull({ strategy: opts.newerWins ? "newer-wins" : "skip-and-flag" });
-        sync.closeRemote();
-        const projParts = (result.projectsPulled || 0) > 0 ? ` | Projects pulled: ${result.projectsPulled}` : "";
-        console.log(`Pulled: ${result.pulled} | Skipped: ${result.skipped} | Conflicts: ${result.conflicts.length}${projParts}`);
-        if (result.errors.length > 0) {
-            console.log("\nErrors:");
-            for (const e of result.errors)
-                console.log(`  ${e}`);
-        }
-    }
-    catch (err) {
-        console.error(`Error: ${err instanceof Error ? err.message : err}`);
-        process.exit(1);
-    }
-    finally {
-        centralDb?.close();
-    }
-});
-remoteCmd
-    .command("sync")
-    .description("Two-way sync: push local changes then pull remote changes")
-    .option("--auto", "Run silently for cron/LaunchAgent (skip-and-flag for conflicts)")
-    .option("--newer-wins", "Auto-resolve conflicts by taking the newer version")
-    .action(async (opts) => {
-    let centralDb = null;
-    try {
-        centralDb = GnosysDB.openLocal();
-        if (!centralDb.isAvailable()) {
-            if (!opts.auto)
-                console.error("Central DB not available.");
-            process.exit(1);
-        }
-        const remotePath = centralDb.getMeta("remote_path");
-        if (!remotePath) {
-            if (!opts.auto)
-                console.error("Remote not configured.");
-            process.exit(opts.auto ? 0 : 1);
-        }
-        const { RemoteSync } = await import("./lib/remote.js");
-        const sync = new RemoteSync(centralDb, remotePath);
-        const result = await sync.sync({
-            auto: opts.auto,
-            strategy: opts.newerWins ? "newer-wins" : "skip-and-flag",
-        });
-        sync.closeRemote();
-        if (!opts.auto || result.conflicts.length > 0 || result.errors.length > 0) {
-            const pp = result.projectsPushed || 0;
-            const pl = result.projectsPulled || 0;
-            const projParts = (pp + pl) > 0 ? ` | Projects: ↑${pp}/↓${pl}` : "";
-            console.log(`Pushed: ${result.pushed} | Pulled: ${result.pulled} | Conflicts: ${result.conflicts.length}${projParts}`);
-            if (result.errors.length > 0) {
-                console.log("\nErrors:");
-                for (const e of result.errors)
-                    console.log(`  ${e}`);
-            }
-            if (result.conflicts.length > 0) {
-                console.log("\nConflicts need resolution (run 'gnosys remote status' for details).");
+                console.log(message);
             }
-        }
+        },
+        onProgress: (step, current, total) => {
+            process.stdout.write(`\r[${current}/${total}] ${step}...`);
+            if (current === total)
+                process.stdout.write("\n");
+        },
+    });
+    console.log("");
+    console.log(formatMaintenanceReport(report));
+});
+// ─── gnosys dearchive ───────────────────────────────────────────────────
+program
+    .command("dearchive <query>")
+    .description("Force-dearchive memories matching a query from archive.db back to active")
+    .option("--limit <n>", "Max memories to dearchive", "5")
+    .action(async (query, opts) => {
+    const { GnosysArchive } = await import("./lib/archive.js");
+    const resolver = await getResolver();
+    const stores = resolver.getStores();
+    if (stores.length === 0) {
+        console.error("No Gnosys stores found. Run gnosys init first.");
+        process.exit(1);
     }
-    catch (err) {
-        if (!opts.auto)
-            console.error(`Error: ${err instanceof Error ? err.message : err}`);
+    const writeTarget = resolver.getWriteTarget();
+    if (!writeTarget) {
+        console.error("No writable store found.");
         process.exit(1);
     }
-    finally {
-        centralDb?.close();
+    const archive = new GnosysArchive(writeTarget.path);
+    if (!archive.isAvailable()) {
+        console.error("Archive not available. Is better-sqlite3 installed?");
+        process.exit(1);
     }
-});
-remoteCmd
-    .command("resolve <memoryId>")
-    .description("Resolve a sync conflict by choosing local, remote, or merged content")
-    .option("--keep <choice>", "Choice: local | remote", "local")
-    .action(async (memoryId, opts) => {
-    let centralDb = null;
-    try {
-        centralDb = GnosysDB.openLocal();
-        if (!centralDb.isAvailable()) {
-            console.error("Central DB not available.");
-            process.exit(1);
-        }
-        const remotePath = centralDb.getMeta("remote_path");
-        if (!remotePath) {
-            console.error("Remote not configured.");
-            process.exit(1);
-        }
-        if (opts.keep !== "local" && opts.keep !== "remote") {
-            console.error(`--keep must be 'local' or 'remote' (got: ${opts.keep})`);
-            process.exit(1);
-        }
-        const { RemoteSync } = await import("./lib/remote.js");
-        const sync = new RemoteSync(centralDb, remotePath);
-        const result = await sync.resolve(memoryId, opts.keep);
-        sync.closeRemote();
-        if (result.ok) {
-            console.log(`Resolved ${memoryId}: kept ${opts.keep} version.`);
-        }
-        else {
-            console.error(`Failed to resolve: ${result.error}`);
-            process.exit(1);
-        }
+    const results = archive.searchArchive(query, parseInt(opts.limit));
+    if (results.length === 0) {
+        console.log(`No archived memories found matching "${query}".`);
+        archive.close();
+        return;
     }
-    catch (err) {
-        console.error(`Error: ${err instanceof Error ? err.message : err}`);
-        process.exit(1);
+    console.log(`Found ${results.length} archived memories matching "${query}":\n`);
+    for (const r of results) {
+        console.log(`  • ${r.title} (${r.id})`);
     }
-    finally {
-        centralDb?.close();
+    console.log("");
+    // Dearchive all found
+    const ids = results.map((r) => r.id);
+    const restored = await archive.dearchiveBatch(ids, writeTarget.store);
+    archive.close();
+    console.log(`Dearchived ${restored.length} memories back to active:`);
+    for (const rp of restored) {
+        console.log(`  → ${rp}`);
     }
 });
-// v5.4.2 removal: `gnosys remote configure` was removed in favor of the
-// canonical `gnosys setup remote` form (which calls the same wizard
-// helpers from lib/remoteWizard.ts). Sync operations like push/pull/sync
-// remain under the `remote` parent.
-// ─── gnosys upgrade ─────────────────────────────────────────────────────
-program
-    .command("upgrade")
-    .description("Re-initialize all registered projects after a Gnosys version upgrade. Updates agent rules, project registry, stamps the central DB, and regenerates the portfolio dashboard.")
-    .option("--skip-dashboard", "Skip regenerating the portfolio dashboard")
-    .action(async (opts) => {
+// NOTE: gnosys migrate is defined below (near the end) with --to-central support
+// ─── gnosys upgrade  +  gnosys setup sync-projects ──────────────────────
+//
+// v5.7.1 (#15) split this command:
+//
+//   gnosys upgrade            — upgrade the gnosys CLI/MCP itself
+//                               (npm install + restart signal to MCPs)
+//   gnosys setup sync-projects — what the old `gnosys upgrade` used to do
+//                               (re-init project identities, agent rules,
+//                                central DB stamp, portfolio dashboard)
+//
+// The body of the legacy command is preserved verbatim below as
+// `syncProjectsAction`, called from the new `setup sync-projects` command.
+async function syncProjectsAction(opts) {
     const currentVersion = pkg.version;
     console.log(`Gnosys v${currentVersion} — upgrading registered projects...\n`);
     // 1. Read registered projects from file registry AND central DB
@@ -3198,12 +3369,83 @@ program
             console.log(`\n  Could not regenerate portfolio dashboard`);
         }
     }
+}
+// `gnosys setup sync-projects` — re-init project identities + agent rules.
+// (This is what `gnosys upgrade` used to do; renamed in v5.7.1.)
+setupCmd
+    .command("sync-projects")
+    .description("Re-initialize all registered projects after upgrading gnosys: refresh agent rules, project registry, central DB stamp, and portfolio dashboard.")
+    .option("--skip-dashboard", "Skip regenerating the portfolio dashboard")
+    .action(syncProjectsAction);
+// `gnosys upgrade` — upgrade the gnosys CLI/MCP itself, then prompt the
+// user to run sync-projects. Writes ~/.gnosys/last-upgrade-at so running
+// MCP servers exit cleanly and the host respawns them against the new
+// 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'.")
+    .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 { execSync } = await import("child_process");
+    try {
+        execSync("npm install -g gnosys@latest", { stdio: "inherit" });
+    }
+    catch (err) {
+        console.error(`\nUpgrade failed: ${err instanceof Error ? err.message : err}`);
+        console.error(`Try running 'npm install -g gnosys@latest' manually.`);
+        process.exit(1);
+    }
+    // Read the newly-installed version (best-effort — we may still be the
+    // old binary in-process; this is purely informational).
+    let newVersion = "(see npm output)";
+    try {
+        const out = execSync("npm ls -g gnosys --depth=0 --json", { encoding: "utf8" });
+        const parsed = JSON.parse(out);
+        newVersion = parsed?.dependencies?.gnosys?.version || newVersion;
+    }
+    catch {
+        // Best-effort lookup only.
+    }
+    // Write the marker so any running MCP servers exit and respawn.
+    const { writeUpgradeMarker } = await import("./lib/upgrade.js");
+    try {
+        writeUpgradeMarker(typeof newVersion === "string" && newVersion !== "(see npm output)"
+            ? newVersion
+            : currentVersion);
+        console.log(`\n✓ Upgrade marker written: ~/.gnosys/last-upgrade-at`);
+        console.log(`  Any running MCP servers will detect this within 10s and restart cleanly.`);
+        console.log(`  (Your MCP client — Claude Code, Cursor, VS Code — will auto-respawn.)`);
+    }
+    catch (err) {
+        console.error(`\nCould not write upgrade marker: ${err instanceof Error ? err.message : err}`);
+        console.error(`Running MCP servers will need to be restarted manually.`);
+    }
+    if (opts.sync === false || opts.yes) {
+        console.log(`\nDone. Run 'gnosys setup sync-projects' when you're ready to refresh registered projects.`);
+        return;
+    }
+    // Prompt for sync-projects.
+    const readline = await import("readline");
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise((resolve) => rl.question(`\nRun 'gnosys setup sync-projects' now to refresh registered projects? [Y/n] `, resolve));
+    rl.close();
+    if (answer.trim().toLowerCase() === "n" || answer.trim().toLowerCase() === "no") {
+        console.log(`Done. You can run 'gnosys setup sync-projects' later.`);
+        return;
+    }
+    console.log(``);
+    await syncProjectsAction({});
 });
 // ─── gnosys doctor ──────────────────────────────────────────────────────
 program
     .command("doctor")
     .description("Check system health: stores, LLM connectivity, embeddings, archive")
-    .action(async () => {
+    .option("--fix", "Offer interactive cleanup of legacy artifacts (e.g. per-store gnosys.db)")
+    .action(async (opts) => {
     const resolver = await getResolver();
     const stores = resolver.getStores();
     console.log("Gnosys Doctor");
@@ -3214,9 +3456,36 @@ program
         const localDbExists = await fs.stat(localDbPath).then(() => true).catch(() => false);
         if (localDbExists) {
             console.log("Local Store (gnosys.db):");
-            console.log("  ⚠ Local gnosys.db found — this is a legacy artifact.");
-            console.log("  All memories should be in the central DB (~/.gnosys/gnosys.db).");
-            console.log(`  Safe to remove: rm "${localDbPath}"`);
+            console.log("  ⚠ Local gnosys.db found — this is a legacy artifact (pre-v2.0 file-based store).");
+            console.log("  All memories live in the central DB now (~/.gnosys/gnosys.db).");
+            console.log(`  Path: ${localDbPath}`);
+            if (opts.fix) {
+                // Interactive cleanup — verify the local DB is safe to delete
+                // (no rows that aren't already in the central DB) before prompting.
+                const safe = await isLegacyStoreSafeToRemove(localDbPath);
+                if (!safe.ok) {
+                    console.log(`  ✗ NOT safe to auto-remove: ${safe.reason}`);
+                    console.log(`  Inspect manually with: sqlite3 ${localDbPath} "SELECT COUNT(*) FROM memories;"`);
+                }
+                else {
+                    const readline = await import("readline/promises");
+                    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+                    const answer = await rl.question(`  Remove "${localDbPath}"? [y/N] `);
+                    rl.close();
+                    if (answer.trim().toLowerCase() === "y") {
+                        await fs.unlink(localDbPath).catch(() => undefined);
+                        await fs.unlink(localDbPath + "-wal").catch(() => undefined);
+                        await fs.unlink(localDbPath + "-shm").catch(() => undefined);
+                        console.log("  ✓ Removed.");
+                    }
+                    else {
+                        console.log("  Skipped.");
+                    }
+                }
+            }
+            else {
+                console.log("  Run 'gnosys doctor --fix' to remove safely (after verifying it's empty).");
+            }
             console.log("");
         }
     }
@@ -3328,31 +3597,110 @@ program
         catch {
             console.log("  Index: not initialized (run gnosys reindex to build)");
         }
-        // Maintenance health
+        // Maintenance health — v5.7.0: queries the central DB directly
+        // (the prior version used GnosysMaintenanceEngine which only sees the
+        // legacy file-based stores, which are empty post-DB-only).
         console.log("");
         console.log("Maintenance Health:");
         try {
-            const { GnosysMaintenanceEngine } = await import("./lib/maintenance.js");
-            const engine = new GnosysMaintenanceEngine(resolver, cfg);
-            const health = await engine.getHealthReport();
-            console.log(`  Active memories: ${health.totalActive}`);
-            console.log(`  Stale (confidence < 0.3): ${health.staleCount}`);
-            console.log(`  Average confidence: ${health.avgConfidence.toFixed(3)} (decayed: ${health.avgDecayedConfidence.toFixed(3)})`);
-            console.log(`  Never reinforced: ${health.neverReinforced}`);
-            console.log(`  Total reinforcements: ${health.totalReinforcements}`);
+            const db2 = GnosysDB.openCentral();
+            if (db2.isAvailable() && db2.isMigrated()) {
+                const memories = db2.getActiveMemories();
+                const now = Date.now();
+                const DECAY_LAMBDA = 0.005;
+                const STALE_THRESHOLD = 0.3;
+                let sumConfidence = 0;
+                let sumDecayed = 0;
+                let staleCount = 0;
+                let neverReinforced = 0;
+                let totalReinforcements = 0;
+                for (const m of memories) {
+                    const baseConfidence = m.confidence ?? 0.8;
+                    const lastIso = m.last_reinforced || m.modified || m.created;
+                    const lastTs = lastIso ? new Date(lastIso).getTime() : NaN;
+                    // Some legacy memories have non-ISO dates that don't parse; treat
+                    // them as "today" rather than NaN-corrupting the average.
+                    const daysSince = Number.isFinite(lastTs)
+                        ? Math.max(0, Math.floor((now - lastTs) / (1000 * 60 * 60 * 24)))
+                        : 0;
+                    const decayed = baseConfidence * Math.exp(-DECAY_LAMBDA * daysSince);
+                    sumConfidence += baseConfidence;
+                    sumDecayed += decayed;
+                    if (decayed < STALE_THRESHOLD)
+                        staleCount++;
+                    const rc = m.reinforcement_count ?? 0;
+                    if (rc === 0)
+                        neverReinforced++;
+                    totalReinforcements += rc;
+                }
+                const n = Math.max(1, memories.length);
+                console.log(`  Active memories: ${memories.length}`);
+                console.log(`  Stale (decayed confidence < ${STALE_THRESHOLD}): ${staleCount}`);
+                console.log(`  Average confidence: ${(sumConfidence / n).toFixed(3)} (decayed: ${(sumDecayed / n).toFixed(3)})`);
+                console.log(`  Never reinforced: ${neverReinforced}`);
+                console.log(`  Total reinforcements: ${totalReinforcements}`);
+            }
+            else {
+                console.log("  — central DB not available");
+            }
+            db2.close();
         }
         catch (err) {
             console.log(`  Error: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
 });
+/**
+ * Check whether a legacy per-store gnosys.db is safe to remove.
+ * Safe = the file is empty OR every memory in it is already represented
+ * in the central DB (matching ID present centrally). This is conservative:
+ * we don't compare hashes or content, just IDs. The legacy DB existed
+ * pre-v2.0; its memories should have all migrated to central DB long ago.
+ */
+async function isLegacyStoreSafeToRemove(localDbPath) {
+    try {
+        const Database = (await import("better-sqlite3")).default;
+        const localDb = new Database(localDbPath, { readonly: true });
+        let localIds = [];
+        try {
+            const rows = localDb.prepare("SELECT id FROM memories").all();
+            localIds = rows.map((r) => r.id);
+        }
+        catch {
+            // Table doesn't exist — file is effectively empty
+            localDb.close();
+            return { ok: true };
+        }
+        localDb.close();
+        if (localIds.length === 0)
+            return { ok: true };
+        const centralDb = GnosysDB.openCentral();
+        if (!centralDb.isAvailable()) {
+            centralDb.close();
+            return { ok: false, reason: "central DB unavailable — cannot verify migration" };
+        }
+        let missing = 0;
+        for (const id of localIds) {
+            if (!centralDb.getMemory(id))
+                missing++;
+        }
+        centralDb.close();
+        if (missing > 0) {
+            return { ok: false, reason: `${missing} of ${localIds.length} local memories not found in central DB` };
+        }
+        return { ok: true };
+    }
+    catch (err) {
+        return { ok: false, reason: `inspection failed: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}
 // ─── gnosys check ─────────────────────────────────────────────────────────
 program
     .command("check")
-    .description("Test LLM connectivity for all 5 task configurations (structuring, synthesis, vision, transcription, dream)")
-    .option("-d, --directory <dir>", "Project directory (default: cwd)")
+    .description("Test LLM connectivity for each configured task (structuring, synthesis, chat, vision, transcription, dream)")
+    .option("-t, --task <name>", "Test only one task (structuring | synthesis | chat | vision | transcription | dream)")
     .action(async (opts) => {
-    const projectDir = opts.directory ? path.resolve(opts.directory) : process.cwd();
+    const projectDir = process.cwd();
     const storePath = path.join(projectDir, ".gnosys");
     const globalStorePath = getGnosysHome();
     // Load config: try project-level first, fall back to global ~/.gnosys/
@@ -3397,6 +3745,13 @@ program
             description: "Q&A answers (gnosys ask)",
             resolve: () => resolveTaskModel(cfg, "synthesis"),
         },
+        {
+            name: "chat",
+            description: "interactive chat (gnosys chat)",
+            // Chat reuses the synthesis task's model — surface it under its own name
+            // so users can see exactly what their TUI will use.
+            resolve: () => resolveTaskModel(cfg, "synthesis"),
+        },
         {
             name: "vision",
             description: "images, PDFs",
@@ -3419,7 +3774,15 @@ program
     let passed = 0;
     let failed = 0;
     let skipped = 0;
-    for (const task of tasks) {
+    // Filter to a single task if --task was given.
+    const filteredTasks = opts.task
+        ? tasks.filter((t) => t.name === opts.task)
+        : tasks;
+    if (opts.task && filteredTasks.length === 0) {
+        console.error(`Unknown task: ${opts.task}. Pick one of: ${tasks.map((t) => t.name).join(", ")}`);
+        process.exit(1);
+    }
+    for (const task of filteredTasks) {
         const { provider, model } = task.resolve();
         const label = `${task.name.padEnd(16)} ${DIM}${provider} / ${model}${RESET}`;
         const desc = `${DIM}(${task.description})${RESET}`;
@@ -3735,7 +4098,7 @@ exportCmd
 // ─── gnosys serve ────────────────────────────────────────────────────────
 program
     .command("serve")
-    .description("Start the MCP server (stdio mode)")
+    .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")
     .action(async (opts) => {
     if (opts.withMaintenance) {
@@ -3890,31 +4253,33 @@ program
 // ─── gnosys audit ────────────────────────────────────────────────────────
 program
     .command("audit")
-    .description("View the structured audit trail of memory operations")
+    .description("View the structured audit trail of memory operations from the central DB")
     .option("--days <n>", "Show entries from the last N days", "7")
-    .option("--operation <op>", "Filter by operation type (read, write, recall, etc.)")
+    .option("--operation <op>", "Filter by operation type (read, write, recall, dream_*, etc.)")
     .option("--limit <n>", "Max entries to show")
     .option("--json", "Output raw JSON instead of formatted timeline")
     .action(async (opts) => {
-    const resolver = new GnosysResolver();
-    await resolver.resolve();
-    const stores = resolver.getStores();
-    if (stores.length === 0) {
-        console.error("No Gnosys stores found. Run 'gnosys init' first.");
+    const { readAuditFromDb, formatAuditTimeline } = await import("./lib/audit.js");
+    const centralDb = GnosysDB.openCentral();
+    if (!centralDb.isAvailable()) {
+        console.error("Central DB unavailable.");
         process.exit(1);
     }
-    const { readAuditLog, formatAuditTimeline } = await import("./lib/audit.js");
-    const storePath = stores[0].path;
-    const entries = readAuditLog(storePath, {
-        days: parseInt(opts.days, 10),
-        operation: opts.operation,
-        limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
-    });
-    if (opts.json) {
-        console.log(JSON.stringify(entries, null, 2));
+    try {
+        const entries = readAuditFromDb(centralDb, {
+            days: parseInt(opts.days, 10),
+            operation: opts.operation,
+            limit: opts.limit ? parseInt(opts.limit, 10) : undefined,
+        });
+        if (opts.json) {
+            console.log(JSON.stringify(entries, null, 2));
+        }
+        else {
+            console.log(formatAuditTimeline(entries));
+        }
     }
-    else {
-        console.log(formatAuditTimeline(entries));
+    finally {
+        centralDb.close();
     }
 });
 // ─── gnosys backup ──────────────────────────────────────────────────────
@@ -4116,8 +4481,10 @@ program
     .command("projects")
     .description("List registered projects from the central DB")
     .option("--json", "Output as JSON")
-    .option("--all", "Include dead projects (deleted directories, /tmp/ paths)")
-    .option("--prune", "Delete registry entries whose directory no longer exists or is a tmp path")
+    .option("--all", "Include dead projects (deleted directories)")
+    .option("--prune", "Delete registry entries whose directory no longer exists (interactive by default)")
+    .option("--dry-run", "With --prune: list what would be deleted, don't actually delete")
+    .option("--yes", "With --prune: skip the confirmation prompt (scripting/automation)")
     .action(async (opts) => {
     let centralDb = null;
     try {
@@ -4128,8 +4495,37 @@ program
         }
         const allProjects = centralDb.getAllProjects();
         if (opts.prune) {
-            // Find and delete dead projects
+            // Find dead projects first — never just delete without showing
+            // them. v5.7.0 adds confirmation by default; --yes skips for
+            // scripted use; --dry-run shows the list without deleting.
             const deadProjects = allProjects.filter((p) => isDeadProjectDir(p.working_directory));
+            if (deadProjects.length === 0) {
+                console.log("No dead projects to prune.");
+                return;
+            }
+            const DIM = "\x1b[2m";
+            const RESET = "\x1b[0m";
+            // Always show what would be removed first.
+            console.log(`Found ${deadProjects.length} dead project(s):\n`);
+            for (const p of deadProjects) {
+                const memCount = centralDb.getMemoriesByProject(p.id, true).length;
+                console.log(`  ${p.name}  ${DIM}${p.working_directory}${RESET}  (${memCount} memorie(s))`);
+            }
+            console.log();
+            if (opts.dryRun) {
+                console.log("[dry-run] No changes made. Re-run without --dry-run to delete.");
+                return;
+            }
+            if (!opts.yes) {
+                const readline = await import("readline/promises");
+                const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+                const answer = (await rl.question(`Delete these ${deadProjects.length} project registry entries? [y/N] `)).trim().toLowerCase();
+                rl.close();
+                if (answer !== "y" && answer !== "yes") {
+                    console.log("Cancelled.");
+                    return;
+                }
+            }
             for (const p of deadProjects) {
                 centralDb.deleteProject(p.id);
             }
@@ -4138,19 +4534,7 @@ program
                 remaining: allProjects.length - deadProjects.length,
                 deletedProjects: deadProjects.map((p) => ({ id: p.id, name: p.name, directory: p.working_directory })),
             }, () => {
-                if (deadProjects.length === 0) {
-                    console.log("No dead projects to prune.");
-                }
-                else {
-                    const DIM = "\x1b[2m";
-                    const RESET = "\x1b[0m";
-                    console.log(`Pruned ${deadProjects.length} dead project(s):\n`);
-                    for (const p of deadProjects) {
-                        console.log(`  ${p.name}  ${DIM}${p.working_directory}${RESET}`);
-                    }
-                    console.log();
-                    console.log(`${allProjects.length - deadProjects.length} project(s) remain.`);
-                }
+                console.log(`✓ Pruned ${deadProjects.length} project(s). ${allProjects.length - deadProjects.length} remain.`);
             });
             return;
         }
@@ -4212,7 +4596,7 @@ program
 // ─── gnosys pref ─────────────────────────────────────────────────────────
 const prefCmd = program
     .command("pref")
-    .description("Manage user preferences (stored in central DB, scope='user')");
+    .description("User preferences — small key-value memories scoped to you (not a project), surfaced into every agent's context. Use for cross-project conventions like 'prefer simple solutions' or 'no emoji in UI'. Subcommands: set, get, delete. Review/clean up with `gnosys setup preferences`.");
 prefCmd
     .command("set <key> <value>")
     .description("Set a user preference. Key should be kebab-case (e.g. 'commit-convention').")
@@ -4471,13 +4855,13 @@ program
 });
 // ─── gnosys briefing ─────────────────────────────────────────────────────
 program
-    .command("briefing")
+    .command("briefing [projectNameOrId]")
     .description("Generate project briefing — memory state summary, categories, recent activity, top tags")
     .option("-p, --project <id>", "Project ID (auto-detects if omitted)")
     .option("-a, --all", "Generate briefings for all projects")
     .option("-d, --directory <dir>", "Project directory for auto-detection")
     .option("--json", "Output as JSON")
-    .action(async (opts) => {
+    .action(async (projectNameOrId, opts) => {
     let centralDb = null;
     try {
         centralDb = GnosysDB.openCentral();
@@ -4503,7 +4887,26 @@ program
             }
             return;
         }
-        let pid = opts.project || null;
+        // v5.7.0: accept project name as positional argument in addition to --project <id>.
+        // Resolution order: positional name → --project flag → cwd auto-detect.
+        let pid = opts.project ?? null;
+        if (!pid && projectNameOrId) {
+            // Try as exact ID first, then by name lookup.
+            const byId = centralDb.getProject(projectNameOrId);
+            if (byId) {
+                pid = byId.id;
+            }
+            else {
+                const all = centralDb.getAllProjects();
+                const byName = all.find((p) => p.name === projectNameOrId);
+                if (byName)
+                    pid = byName.id;
+            }
+            if (!pid) {
+                console.error(`Project not found: "${projectNameOrId}". Run 'gnosys projects' to list registered projects.`);
+                process.exit(1);
+            }
+        }
         if (!pid)
             pid = await detectCurrentProject(centralDb, opts.directory || undefined);
         if (!pid) {
@@ -4545,79 +4948,91 @@ program
         centralDb?.close();
     }
 });
-// ─── gnosys portfolio ───────────────────────────────────────────────────
+// `gnosys portfolio` was removed in v5.7.1.
+// Use `gnosys status --projects` (formerly --global) for the projects
+// overview, or `gnosys status --web` for the HTML dashboard, or
+// `gnosys status --projects --output file.html` to write to disk.
+// ─── gnosys status ──────────────────────────────────────────────────────
+// v5.7.1 (#11): the catch-all status command. Section flags select what to
+// show; output flags control format. Default (no flag) is the current
+// project. `dashboard` and `portfolio` were removed in v5.7.1 — their
+// content lives under `--system` and `--projects` respectively.
 program
-    .command("portfolio")
-    .description("Portfolio dashboard — all projects with status, roadmap, and recent activity")
-    .option("-o, --output <file>", "Write dashboard to a file (auto-detects format from extension)")
-    .option("--html", "Output as HTML dashboard")
+    .command("status")
+    .description("Show status. Sections: --projects (all projects) · --remote (sync) · --system (memory/LLM health) · default: current project. Output: --web · --json. Note: 'gnosys dashboard' and 'gnosys portfolio' were removed in v5.7.1 — use 'gnosys status --system' and 'gnosys status --projects' instead.")
+    .option("-d, --directory <dir>", "Project directory (auto-detects if omitted)")
+    .option("-p, --project <id>", "Project ID")
+    .option("-g, --global", "(deprecated alias for --projects)")
+    .option("--projects", "Show all projects portfolio (replaces the old 'gnosys portfolio')")
+    .option("-r, --remote", "Show remote sync status (alias for 'gnosys setup remote status')")
+    .option("-w, --web", "Open the HTML dashboard in the browser")
+    .option("-s, --system", "Show system health (memory count, LLM connectivity, embeddings, archive)")
     .option("--json", "Output as JSON")
     .action(async (opts) => {
-    let centralDb = null;
-    try {
-        centralDb = GnosysDB.openCentral();
-        if (!centralDb.isAvailable()) {
-            console.error("Central DB not available.");
-            process.exit(1);
-        }
-        const { generatePortfolio, formatPortfolioMarkdown } = await import("./lib/portfolio.js");
-        const report = generatePortfolio(centralDb);
-        // Detect format from output extension if not explicitly set
-        const useHtml = opts.html || (opts.output?.endsWith(".html") ?? false);
-        const useJson = opts.json || (opts.output?.endsWith(".json") ?? false);
-        if (useJson) {
-            const json = JSON.stringify(report, null, 2);
-            if (opts.output) {
-                const { writeFileSync } = await import("fs");
-                writeFileSync(opts.output, json, "utf-8");
-                console.log(`Portfolio written to ${opts.output}`);
+    // v5.7.1: --projects supersedes --global (kept as alias).
+    if (opts.projects)
+        opts.global = true;
+    // v5.7.1: --remote — dispatch to RemoteSync.getStatus()
+    if (opts.remote) {
+        let remoteCentralDb = null;
+        try {
+            remoteCentralDb = GnosysDB.openLocal();
+            if (!remoteCentralDb.isAvailable()) {
+                console.error("Central DB not available.");
+                process.exit(1);
             }
-            else {
-                console.log(json);
+            const remotePath = remoteCentralDb.getMeta("remote_path");
+            if (!remotePath) {
+                if (opts.json) {
+                    console.log(JSON.stringify({ configured: false, message: "Remote not configured. Run 'gnosys setup remote'." }, null, 2));
+                }
+                else {
+                    console.log("Remote sync: not configured. Run 'gnosys setup remote' to set up multi-machine sync.");
+                }
+                return;
             }
-            return;
-        }
-        if (useHtml) {
-            const { generatePortfolioHtml } = await import("./lib/portfolioHtml.js");
-            const html = generatePortfolioHtml(report, opts.output);
-            if (opts.output) {
-                const { writeFileSync } = await import("fs");
-                writeFileSync(opts.output, html, "utf-8");
-                console.log(`Portfolio dashboard written to ${opts.output}`);
+            const { RemoteSync, formatStatus } = await import("./lib/remote.js");
+            const { withHeartbeat } = await import("./lib/heartbeat.js");
+            const sync = new RemoteSync(remoteCentralDb, remotePath);
+            const status = await withHeartbeat("Checking remote sync status", () => sync.getStatus());
+            sync.closeRemote();
+            if (opts.json) {
+                console.log(JSON.stringify(status, null, 2));
             }
             else {
-                console.log(html);
+                console.log(formatStatus(status));
             }
             return;
         }
-        const markdown = formatPortfolioMarkdown(report);
-        if (opts.output) {
-            const { writeFileSync } = await import("fs");
-            writeFileSync(opts.output, markdown, "utf-8");
-            console.log(`Portfolio dashboard written to ${opts.output}`);
+        catch (err) {
+            console.error(`Error: ${err instanceof Error ? err.message : err}`);
+            process.exit(1);
         }
-        else {
-            console.log(markdown);
+        finally {
+            remoteCentralDb?.close();
         }
     }
-    catch (err) {
-        console.error(`Error: ${err instanceof Error ? err.message : err}`);
-        process.exit(1);
-    }
-    finally {
-        centralDb?.close();
+    // --system delegates to the dashboard formatter (formerly `gnosys dashboard`).
+    if (opts.system) {
+        const { collectDashboardData, formatDashboard, formatDashboardJSON } = await import("./lib/dashboard.js");
+        const resolver = await getResolver();
+        const stores = resolver.getStores();
+        if (stores.length === 0) {
+            console.error("No Gnosys stores found. Run gnosys init first.");
+            process.exit(1);
+        }
+        const cfg = await loadConfig(stores[0].path);
+        let dashDb;
+        try {
+            const db = GnosysDB.openCentral();
+            if (db.isAvailable() && db.isMigrated())
+                dashDb = db;
+        }
+        catch { /* non-fatal */ }
+        const data = await collectDashboardData(resolver, cfg, pkg.version, dashDb);
+        console.log(opts.json ? formatDashboardJSON(data) : formatDashboard(data));
+        return;
     }
-});
-// ─── gnosys status ──────────────────────────────────────────────────────
-program
-    .command("status")
-    .description("Show project status. From a project dir: shows that project. With --global: shows all projects. With --web: opens the HTML dashboard.")
-    .option("-d, --directory <dir>", "Project directory (auto-detects if omitted)")
-    .option("-p, --project <id>", "Project ID")
-    .option("-g, --global", "Show all projects")
-    .option("-w, --web", "Open the HTML dashboard in the browser")
-    .option("--json", "Output as JSON")
-    .action(async (opts) => {
     let centralDb = null;
     try {
         centralDb = GnosysDB.openCentral();
@@ -4840,7 +5255,7 @@ program
 // ─── gnosys sandbox start|stop|status ─────────────────────────────────────
 const sandboxCmd = program
     .command("sandbox")
-    .description("Manage the Gnosys sandbox background process");
+    .description("Manage the Gnosys sandbox — a long-lived background process that holds the SQLite handle so agents can call gnosys.add()/recall() through a tiny helper library instead of paying the MCP roundtrip on every call. Lower latency, lower context cost. Most users don't need this; it's for high-throughput agent workflows.");
 sandboxCmd
     .command("start")
     .description("Start the Gnosys sandbox background process")
@@ -4923,7 +5338,7 @@ sandboxCmd
 // ─── gnosys helper generate ───────────────────────────────────────────────
 const helperCmd = program
     .command("helper")
-    .description("Manage the Gnosys helper library for agent integration");
+    .description("Generate a tiny TypeScript helper library that agents import to talk to the gnosys sandbox directly. Pairs with `gnosys sandbox start` — agents call gnosys.add()/recall() like normal code instead of issuing MCP tool calls. Run `gnosys helper generate` in your agent's project to drop in `gnosys-helper.ts`.");
 helperCmd
     .command("generate")
     .description("Generate a gnosys-helper.ts file in the current directory (or specified directory)")