gnosys 5.5.0 → 5.7.0

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";
@@ -108,6 +108,32 @@ function maybePrintUpgradeNudge() {
     }
 }
 maybePrintUpgradeNudge();
+/**
+ * v5.6.0 back-compat shim: rewrite `gnosys export --to <dir>` →
+ * `gnosys export vault --to <dir>` before commander parses argv. The v5.6.0
+ * restructure made `export` a parent command with `vault` and `project`
+ * subcommands; without this shim, the bare `--to` form prints usage instead
+ * of running the vault export.
+ *
+ * Pattern: argv[2]==="export" AND argv[3] is not a known subcommand AND any
+ * of the v5.5.x flags appear (`--to`, `--all`, `--overwrite`, etc.).
+ */
+function rewriteLegacyExport() {
+    if (process.argv[2] !== "export")
+        return;
+    const next = process.argv[3];
+    if (next === "vault" || next === "project" || next === "--help" || next === "-h")
+        return;
+    // Any v5.5.x-style flag → assume legacy vault invocation
+    const looksLegacy = process.argv.slice(3).some((a) => a === "--to" || a.startsWith("--to=") ||
+        a === "--all" || a === "--overwrite" ||
+        a === "--no-summaries" || a === "--no-reviews" || a === "--no-graph" ||
+        a === "--json");
+    if (looksLegacy) {
+        process.argv.splice(3, 0, "vault");
+    }
+}
+rewriteLegacyExport();
 async function getResolver() {
     const resolver = new GnosysResolver();
     await resolver.resolve();
@@ -137,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 {
@@ -517,13 +560,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,
     });
 });
@@ -543,14 +599,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.");
@@ -571,6 +630,233 @@ 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 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 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")
+    .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}` : "";
+        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")
+    .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}` : "";
+        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")
+    .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 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")
@@ -579,6 +865,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
@@ -1218,21 +1549,60 @@ program
         centralDb?.close();
     }
 });
-// ─── gnosys ingest <file> ─────────────────────────────────────────────────
+// ─── gnosys chat (TUI) ───────────────────────────────────────────────────
 program
-    .command("ingest <fileOrGlob>")
-    .description("Ingest a file (PDF, DOCX, TXT, MD) into Gnosys memory. Extracts text, splits into chunks, and creates atomic memories.")
-    .option("--mode <mode>", "Ingestion mode: llm or structured", "llm")
-    .option("-s, --store <store>", "Target store: project, personal, global")
-    .option("-a, --author <author>", "Author", "human")
-    .option("--authority <authority>", "Authority level", "imported")
-    .option("--dry-run", "Preview what would be created without writing")
-    .option("--list-attachments", "List all stored attachments")
-    .option("-d, --directory <dir>", "Project directory")
-    .action(async (fileOrGlob, opts) => {
-    // List attachments mode
-    if (opts.listAttachments) {
-        const { listAttachments } = await import("./lib/attachments.js");
+    .command("chat")
+    .description("Interactive memory-aware terminal chat (TUI)")
+    .option("--resume <sessionId>", "Resume an existing chat session")
+    .option("--list", "List recent chat sessions and exit")
+    .option("--search <query>", "Full-text search across session logs")
+    .option("--provider <name>", "Override LLM provider (anthropic, openai, groq, ollama, …)")
+    .option("--model <name>", "Override LLM model name")
+    .option("--limit <n>", "Limit for --list / --search (default 20)", "20")
+    .action(async (opts) => {
+    const limit = parseInt(opts.limit, 10) || 20;
+    const chat = await import("./lib/chat/index.js");
+    if (opts.list) {
+        chat.printSessionList(limit);
+        return;
+    }
+    if (opts.search) {
+        chat.printSearchResults(opts.search, limit);
+        return;
+    }
+    // Interactive chat
+    const resolver = await getResolver();
+    const stores = resolver.getStores();
+    const storePath = stores[0]?.path ?? process.cwd();
+    let cliConfig;
+    try {
+        cliConfig = await loadConfig(storePath);
+    }
+    catch {
+        cliConfig = (await import("./lib/config.js")).DEFAULT_CONFIG;
+    }
+    await chat.startChat({
+        config: cliConfig,
+        resume: opts.resume,
+        providerName: opts.provider,
+        modelName: opts.model,
+    });
+});
+// ─── gnosys ingest <file> ─────────────────────────────────────────────────
+program
+    .command("ingest <fileOrGlob>")
+    .description("Ingest a file (PDF, DOCX, TXT, MD) into Gnosys memory. Extracts text, splits into chunks, and creates atomic memories.")
+    .option("--mode <mode>", "Ingestion mode: llm or structured", "llm")
+    .option("-s, --store <store>", "Target store: project, personal, global")
+    .option("-a, --author <author>", "Author", "human")
+    .option("--authority <authority>", "Authority level", "imported")
+    .option("--dry-run", "Preview what would be created without writing")
+    .option("--list-attachments", "List all stored attachments")
+    .option("-d, --directory <dir>", "Project directory")
+    .action(async (fileOrGlob, opts) => {
+    // List attachments mode
+    if (opts.listAttachments) {
+        const { listAttachments } = await import("./lib/attachments.js");
         const resolver = await getResolver();
         const writeTarget = resolver.getWriteTarget(opts.store || undefined);
         if (!writeTarget) {
@@ -1616,34 +1986,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 {
@@ -1652,8 +2039,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");
@@ -1756,7 +2201,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
@@ -1876,12 +2321,13 @@ program
         }
     }
 });
-// ─── gnosys import <file> ────────────────────────────────────────────────
-program
-    .command("import <fileOrUrl>")
-    .description("Bulk import structured data (CSV, JSON, JSONL) into Gnosys memories")
-    .requiredOption("--format <format>", "Data format: csv, json, jsonl")
-    .requiredOption("--mapping <json>", 'Field mapping as JSON: \'{"source_field":"gnosys_field"}\'. Valid targets: title, category, content, tags, relevance')
+// ─── gnosys import (parent + subcommands) ───────────────────────────────
+const importCmd = program
+    .command("import [fileOrUrl]")
+    .enablePositionalOptions()
+    .description("Import data into Gnosys (bulk CSV/JSON/JSONL — see also: 'gnosys import project <bundle>')")
+    .option("--format <format>", "Data format: csv, json, jsonl (required for bulk import)")
+    .option("--mapping <json>", 'Field mapping as JSON: \'{"source_field":"gnosys_field"}\'. Valid targets: title, category, content, tags, relevance')
     .option("--mode <mode>", "Processing mode: llm or structured", "structured")
     .option("--limit <n>", "Max records to import", parseInt)
     .option("--offset <n>", "Skip first N records", parseInt)
@@ -1892,6 +2338,17 @@ program
     .option("--dry-run", "Preview without writing")
     .option("--store <store>", "Target store: project, personal, global", "project")
     .action(async (fileOrUrl, opts) => {
+    if (!fileOrUrl) {
+        console.error("Usage:");
+        console.error("  gnosys import <file> --format csv|json|jsonl --mapping '{...}'   (bulk)");
+        console.error("  gnosys import project <bundle.json.gz>                            (project bundle)");
+        process.exit(1);
+    }
+    if (!opts.format || !opts.mapping) {
+        console.error("Error: --format and --mapping are required for bulk imports.");
+        console.error("       For project bundles, use 'gnosys import project <bundle>'.");
+        process.exit(1);
+    }
     // Parse mapping JSON
     let mapping;
     try {
@@ -1966,10 +2423,55 @@ program
         process.exit(1);
     }
 });
+// `gnosys import project <bundle>` — restore a portable .json.gz bundle
+importCmd
+    .command("project <bundlePath>")
+    .description("Import a project bundle (.json.gz) created by 'gnosys export project'")
+    .option("--strategy <strategy>", "Conflict handling: merge (default), replace, new-id", "merge")
+    .option("--working-directory <dir>", "Override the bundle's working_directory (e.g. when restoring on a different machine)")
+    .option("--json", "Output the result as JSON")
+    .action(async (bundlePath, opts) => {
+    const validStrategies = ["merge", "replace", "new-id"];
+    if (!validStrategies.includes(opts.strategy)) {
+        console.error(`Invalid strategy: ${opts.strategy}. Use one of: ${validStrategies.join(", ")}`);
+        process.exit(1);
+    }
+    const { GnosysDB: DbClass } = await import("./lib/db.js");
+    const { importProject } = await import("./lib/importProject.js");
+    const centralDb = DbClass.openCentral();
+    if (!centralDb.isAvailable()) {
+        console.error("Central DB unavailable.");
+        process.exit(1);
+    }
+    try {
+        const result = importProject(centralDb, {
+            bundlePath: path.resolve(bundlePath),
+            strategy: opts.strategy,
+            workingDirectoryOverride: opts.workingDirectory,
+        });
+        if (opts.json) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            console.log(`Imported project ${result.projectName} (${result.projectId})`);
+            console.log(`  Strategy:        ${result.strategy}`);
+            console.log(`  Memories:        ${result.memoriesInserted} inserted, ${result.memoriesSkipped} skipped, ${result.memoriesReplaced} replaced`);
+            console.log(`  Relationships:   ${result.relationshipsInserted}`);
+            console.log(`  Audit entries:   ${result.auditEntriesInserted}`);
+        }
+    }
+    catch (err) {
+        console.error(`Import failed: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+    finally {
+        centralDb.close();
+    }
+});
 // ─── 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();
@@ -2506,9 +3008,11 @@ program
     console.log(formatGraphStats(stats));
 });
 // ─── gnosys dashboard ───────────────────────────────────────────────────
+// v5.7.0: kept as a thin alias of `gnosys status --system`. Will be removed
+// in a future release; use `gnosys status` instead.
 program
     .command("dashboard")
-    .description("Show system dashboard: memory count, health, graph stats, LLM status")
+    .description("(alias) Show system health — equivalent to 'gnosys status --system'")
     .option("--json", "Output as JSON instead of pretty table")
     .action(async (opts) => {
     const { collectDashboardData, formatDashboard, formatDashboardJSON } = await import("./lib/dashboard.js");
@@ -2524,334 +3028,103 @@ program
     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 maintain ─────────────────────────────────────────────────────
-program
-    .command("maintain")
-    .description("Run vault maintenance: detect duplicates, apply confidence decay, consolidate similar memories")
-    .option("--dry-run", "Show what would change without modifying anything")
-    .option("--auto-apply", "Automatically apply all changes (no prompts)")
-    .action(async (opts) => {
-    const { GnosysMaintenanceEngine, formatMaintenanceReport } = await import("./lib/maintenance.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);
-    const engine = new GnosysMaintenanceEngine(resolver, cfg);
-    const report = await engine.maintain({
-        dryRun: opts.dryRun,
-        autoApply: opts.autoApply,
-        onLog: (level, message) => {
-            if (level === "warn") {
-                console.error(`⚠ ${message}`);
-            }
-            else if (level === "action") {
-                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).");
-            }
+            dashDb = db;
         }
     }
-    catch (err) {
-        if (!opts.auto)
-            console.error(`Error: ${err instanceof Error ? err.message : err}`);
-        process.exit(1);
+    catch {
+        // Central DB not available — legacy dashboard only
     }
-    finally {
-        centralDb?.close();
+    const data = await collectDashboardData(resolver, cfg, pkg.version, dashDb);
+    if (opts.json) {
+        console.log(formatDashboardJSON(data));
+    }
+    else {
+        console.log(formatDashboard(data));
     }
 });
-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);
-        }
+// ─── gnosys maintain ─────────────────────────────────────────────────────
+program
+    .command("maintain")
+    .description("Run vault maintenance: detect duplicates, apply confidence decay, consolidate similar memories")
+    .option("--dry-run", "Show what would change without modifying anything")
+    .option("--auto-apply", "Automatically apply all changes (no prompts)")
+    .action(async (opts) => {
+    const { GnosysMaintenanceEngine, formatMaintenanceReport } = await import("./lib/maintenance.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) {
-        console.error(`Error: ${err instanceof Error ? err.message : err}`);
+    const cfg = await loadConfig(stores[0].path);
+    const engine = new GnosysMaintenanceEngine(resolver, cfg);
+    const report = await engine.maintain({
+        dryRun: opts.dryRun,
+        autoApply: opts.autoApply,
+        onLog: (level, message) => {
+            if (level === "warn") {
+                console.error(`⚠ ${message}`);
+            }
+            else if (level === "action") {
+                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);
     }
-    finally {
-        centralDb?.close();
+    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}`);
     }
 });
-// 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.
+// NOTE: gnosys migrate is defined below (near the end) with --to-central support
 // ─── gnosys upgrade ─────────────────────────────────────────────────────
 program
     .command("upgrade")
@@ -3081,7 +3354,8 @@ program
 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");
@@ -3092,9 +3366,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("");
         }
     }
@@ -3206,31 +3507,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/
@@ -3275,6 +3655,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",
@@ -3297,7 +3684,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}`;
@@ -3495,18 +3890,7 @@ dreamCmd
         centralDb?.close();
     }
 });
-// ─── gnosys export ───────────────────────────────────────────────────────
-program
-    .command("export")
-    .description("Export gnosys.db to Obsidian-compatible vault (one-way)")
-    .requiredOption("--to <dir>", "Target directory for export")
-    .option("--all", "Export all memories (active + archived)")
-    .option("--overwrite", "Overwrite existing files")
-    .option("--no-summaries", "Skip category summaries")
-    .option("--no-reviews", "Skip review suggestions")
-    .option("--no-graph", "Skip relationship graph")
-    .option("--json", "Output raw JSON report")
-    .action(async (opts) => {
+async function runVaultExport(opts) {
     const resolver = new GnosysResolver();
     await resolver.resolve();
     const stores = resolver.getStores();
@@ -3545,11 +3929,86 @@ program
         console.log(formatExportReport(report));
     }
     db.close();
+}
+const exportCmd = program
+    .command("export")
+    .description("Export memory to a vault (markdown) or a project bundle (.json.gz)")
+    .enablePositionalOptions();
+// Bare `gnosys export` shows the canonical subcommand forms. Back-compat for
+// the v5.5.x form `gnosys export --to <dir>` is handled in a pre-parse shim
+// at the top of the file (rewrites argv to insert "vault" before "--to").
+exportCmd.action(() => {
+    console.error("Usage: gnosys export vault --to <dir>             # Obsidian vault export");
+    console.error("       gnosys export project [id] --to <bundle>   # portable .json.gz bundle");
+    process.exit(1);
+});
+// `gnosys export vault` — explicit alias for the default behavior
+exportCmd
+    .command("vault")
+    .description("Export gnosys.db to an Obsidian-compatible vault (one-way)")
+    .requiredOption("--to <dir>", "Target directory for export")
+    .option("--all", "Export all memories (active + archived)")
+    .option("--overwrite", "Overwrite existing files")
+    .option("--no-summaries", "Skip category summaries")
+    .option("--no-reviews", "Skip review suggestions")
+    .option("--no-graph", "Skip relationship graph")
+    .option("--json", "Output raw JSON report")
+    .action(runVaultExport);
+// `gnosys export project [id]` — bundle a single project for portability
+exportCmd
+    .command("project [projectId]")
+    .description("Export a single project to a portable .json.gz bundle (round-trips with 'gnosys import project')")
+    .requiredOption("--to <file>", "Output bundle file path (e.g. ./gnosys-public.gnosys.json.gz)")
+    .option("--include-archived", "Include archived and superseded memories (default: active only)")
+    .option("--no-audit", "Skip the audit log")
+    .option("--json", "Output the result as JSON")
+    .action(async (projectIdArg, opts) => {
+    const { GnosysDB: DbClass } = await import("./lib/db.js");
+    const { exportProject } = await import("./lib/exportProject.js");
+    const centralDb = DbClass.openCentral();
+    if (!centralDb.isAvailable()) {
+        console.error("Central DB unavailable.");
+        process.exit(1);
+    }
+    let projectId = projectIdArg;
+    if (!projectId) {
+        // Auto-detect from cwd
+        const proj = centralDb.getProjectByDirectory(process.cwd());
+        if (!proj) {
+            console.error("No project ID given and current directory is not a registered project.");
+            console.error("Usage: gnosys export project <projectId> --to <file>");
+            process.exit(1);
+        }
+        projectId = proj.id;
+    }
+    try {
+        const result = exportProject(centralDb, {
+            projectId,
+            outputPath: path.resolve(opts.to),
+            includeArchived: !!opts.includeArchived,
+            includeAudit: opts.audit !== false,
+        });
+        if (opts.json) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            const ratio = (result.compressedBytes / result.uncompressedBytes * 100).toFixed(1);
+            console.log(`Exported project ${projectId}`);
+            console.log(`  Memories:      ${result.memoryCount}`);
+            console.log(`  Relationships: ${result.relationshipCount}`);
+            console.log(`  Audit entries: ${result.auditEntryCount}`);
+            console.log(`  Bundle:        ${result.outputPath}`);
+            console.log(`  Size:          ${(result.compressedBytes / 1024).toFixed(1)} KB compressed (${ratio}% of ${(result.uncompressedBytes / 1024).toFixed(1)} KB)`);
+        }
+    }
+    finally {
+        centralDb.close();
+    }
 });
 // ─── 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) {
@@ -3704,31 +4163,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 ──────────────────────────────────────────────────────
@@ -3930,8 +4391,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 {
@@ -3942,8 +4405,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);
             }
@@ -3952,19 +4444,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;
         }
@@ -4026,7 +4506,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').")
@@ -4285,13 +4765,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();
@@ -4317,7 +4797,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) {
@@ -4425,13 +4924,35 @@ program
 // ─── 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.")
+    .description("Show project status (--global: all projects, --web: HTML dashboard, --system: memory/LLM health)")
     .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("-s, --system", "Show system health (memory count, LLM connectivity, embeddings, archive)")
     .option("--json", "Output as JSON")
     .action(async (opts) => {
+    // --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;
+    }
     let centralDb = null;
     try {
         centralDb = GnosysDB.openCentral();
@@ -4654,7 +5175,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")
@@ -4737,7 +5258,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)")