gnosys 5.10.0 → 5.11.0

package/dist/index.js

@@ -45,7 +45,6 @@ import { GnosysSearch } from "./lib/search.js";
 import { GnosysTagRegistry } from "./lib/tags.js";
 import { GnosysResolver } from "./lib/resolver.js";
 import { applyLens } from "./lib/lensing.js";
-import { getFileHistory, rollbackToCommit, hasGitHistory } from "./lib/history.js";
 import { groupByPeriod, computeStats } from "./lib/timeline.js";
 import { buildLinkGraph, getBacklinks, getOutgoingLinks, formatGraphSummary } from "./lib/wikilinks.js";
 import { loadConfig, DEFAULT_CONFIG } from "./lib/config.js";
@@ -55,7 +54,7 @@ import { initAudit, readAuditLog, formatAuditTimeline } from "./lib/audit.js";
 import { GnosysDB } from "./lib/db.js";
 import { syncMemoryToDb, syncUpdateToDb, syncDearchiveToDb, syncReinforcementToDb, auditToDb } from "./lib/dbWrite.js";
 import { createProjectIdentity, readProjectIdentity } from "./lib/projectIdentity.js";
-import { setPreference, getPreference, getAllPreferences, deletePreference } from "./lib/preferences.js";
+import { setPreference, getPreference, getAllPreferences, deletePreference, KNOWN_PREFERENCE_KEYS, suggestPreferenceKey } from "./lib/preferences.js";
 import { syncRules, generateRulesBlock } from "./lib/rulesGen.js";
 import { federatedSearch, detectAmbiguity, generateBriefing, generateAllBriefings, getWorkingSet, formatWorkingSet, detectCurrentProject } from "./lib/federated.js";
 import { generatePortfolio, formatPortfolioCompact, formatPortfolioMarkdown, generateStatusPrompt } from "./lib/portfolio.js";
@@ -67,6 +66,23 @@ const server = new McpServer({
     name: "gnosys",
     version: "2.0.0",
 });
+const _registrations = [];
+// Typed to the McpServer methods so call-site generic inference (Zod schema →
+// handler arg types) is preserved; the body just collects a replay thunk.
+const regTool = ((...args) => {
+    _registrations.push((s) => s.tool(...args));
+});
+const regPrompt = ((...args) => {
+    _registrations.push((s) => s.prompt(...args));
+});
+const regResource = ((...args) => {
+    _registrations.push((s) => s.resource(...args));
+});
+/** Replay all collected capability registrations onto a server instance. */
+export function registerCapabilities(s) {
+    for (const r of _registrations)
+        r(s);
+}
 /**
  * v5.4.1: Format MCP errors. Detects DB corruption and replaces the raw
  * "database disk image is malformed" with actionable recovery instructions.
@@ -155,7 +171,7 @@ async function resolveToolContext(projectRoot) {
     const scopedWriteTarget = scopedResolver.getWriteTarget();
     const scopedStorePath = scopedWriteTarget?.store.getStorePath() || "";
     let scopedConfig = DEFAULT_CONFIG;
-    let scopedDb = null;
+    const scopedDb = null;
     let scopedSearch = null;
     // v3.0: Read project identity
     const identity = await readProjectIdentity(path.resolve(projectRoot));
@@ -220,7 +236,7 @@ function resolveWriteScope(ctx, targetStore) {
     return { ok: true, scope: "project", projectId: ctx.projectId };
 }
 // ─── Tool: gnosys_discover ──────────────────────────────────────────────
-server.tool("gnosys_discover", "Discover relevant memories by describing what you're working on. Searches relevance keyword clouds across all stores. Returns lightweight metadata (title, path, relevance keywords) — NO file contents. Use gnosys_read to load specific memories you need. Call this FIRST when starting a task to find what Gnosys knows.", {
+regTool("gnosys_discover", "Discover relevant memories by describing what you're working on. Searches relevance keyword clouds across all stores. Returns lightweight metadata (title, path, relevance keywords) — NO file contents. Use gnosys_read to load specific memories you need. Call this FIRST when starting a task to find what Gnosys knows.", {
     query: z
         .string()
         .describe("Describe what you're working on or looking for. Use keywords, not sentences. Example: 'auth JWT session tokens' or 'deployment CI/CD pipeline'"),
@@ -274,7 +290,7 @@ server.tool("gnosys_discover", "Discover relevant memories by describing what yo
     };
 });
 // ─── Tool: gnosys_read ───────────────────────────────────────────────────
-server.tool("gnosys_read", "Read a specific memory. Accepts a memory ID (e.g., 'arch-012') or layer-prefixed path (e.g., 'project:decisions/why-not-rag.md'). Without a prefix, searches all stores in precedence order.", {
+regTool("gnosys_read", "Read a specific memory. Accepts a memory ID (e.g., 'arch-012') or layer-prefixed path (e.g., 'project:decisions/why-not-rag.md'). Without a prefix, searches all stores in precedence order.", {
     path: z.string().describe("Memory ID or path, optionally prefixed with store layer"),
     projectRoot: projectRootParam,
 }, async ({ path: memPath, projectRoot }) => {
@@ -284,7 +300,7 @@ server.tool("gnosys_read", "Read a specific memory. Accepts a memory ID (e.g., '
         const dbMem = ctx.centralDb.getMemory(memPath);
         if (dbMem) {
             const tags = dbMem.tags || "[]";
-            const header = [
+            const headerLines = [
                 `---`,
                 `id: ${dbMem.id}`,
                 `title: '${dbMem.title}'`,
@@ -298,8 +314,14 @@ server.tool("gnosys_read", "Read a specific memory. Accepts a memory ID (e.g., '
                 `tier: ${dbMem.tier}`,
                 `created: '${dbMem.created}'`,
                 `modified: '${dbMem.modified}'`,
-                `---`,
-            ].join("\n");
+            ];
+            if (dbMem.source_file) {
+                headerLines.push(`source_file: ${dbMem.source_file}${dbMem.source_page != null ? ` (page ${Number(dbMem.source_page)})` : ""}`);
+            }
+            if (dbMem.source_path)
+                headerLines.push(`source_path: ${dbMem.source_path}`);
+            headerLines.push(`---`);
+            const header = headerLines.join("\n");
             return {
                 content: [{ type: "text", text: `[Source: gnosys.db]\n\n${header}\n\n${dbMem.content}` }],
             };
@@ -314,7 +336,13 @@ server.tool("gnosys_read", "Read a specific memory. Accepts a memory ID (e.g., '
             isError: true,
         };
     }
-    const raw = await fs.readFile(memory.filePath, "utf-8");
+    let raw;
+    try {
+        raw = await fs.readFile(memory.filePath, "utf-8");
+    }
+    catch (err) {
+        return { content: [{ type: "text", text: formatMcpError("reading memory", err) }], isError: true };
+    }
     return {
         content: [
             {
@@ -325,7 +353,7 @@ server.tool("gnosys_read", "Read a specific memory. Accepts a memory ID (e.g., '
     };
 });
 // ─── Tool: gnosys_search ─────────────────────────────────────────────────
-server.tool("gnosys_search", "Search memories by keyword across all stores. Returns matching file paths with relevance snippets.", {
+regTool("gnosys_search", "Search memories by keyword across all stores. Returns matching file paths with relevance snippets.", {
     query: z.string().describe("Search query (keywords)"),
     limit: z.number().optional().describe("Max results (default 20)"),
     projectRoot: projectRootParam,
@@ -377,7 +405,7 @@ server.tool("gnosys_search", "Search memories by keyword across all stores. Retu
     };
 });
 // ─── Tool: gnosys_list ───────────────────────────────────────────────────
-server.tool("gnosys_list", "List memories across all stores, optionally filtered by category, tag, or store layer.", {
+regTool("gnosys_list", "List memories across all stores, optionally filtered by category, tag, or store layer.", {
     category: z.string().optional().describe("Filter by category"),
     tag: z.string().optional().describe("Filter by tag"),
     store: z.string().optional().describe("Filter by store layer (project/personal/global/optional)"),
@@ -463,7 +491,7 @@ server.tool("gnosys_list", "List memories across all stores, optionally filtered
     };
 });
 // ─── Tool: gnosys_add ────────────────────────────────────────────────────
-server.tool("gnosys_add", "Add a new memory. Accepts raw text — an LLM structures it into an atomic memory. Writes to the project store by default. Use store='personal' for cross-project knowledge, or store='global' to explicitly write to shared org knowledge.", {
+regTool("gnosys_add", "Add a new memory. Accepts raw text — an LLM structures it into an atomic memory. Writes to the project store by default. Use store='personal' for cross-project knowledge, or store='global' to explicitly write to shared org knowledge.", {
     input: z
         .string()
         .describe("Raw text input. Can be a decision, concept, fact, observation, or any knowledge."),
@@ -577,7 +605,7 @@ server.tool("gnosys_add", "Add a new memory. Accepts raw text — an LLM structu
     }
 });
 // ─── Tool: gnosys_add_structured ─────────────────────────────────────────
-server.tool("gnosys_add_structured", "Add a memory with structured input (no LLM needed). Writes to the project store by default. Use store='global' to explicitly write to shared org knowledge.", {
+regTool("gnosys_add_structured", "Add a memory with structured input (no LLM needed). Writes to the project store by default. Use store='global' to explicitly write to shared org knowledge.", {
     title: z.string().describe("Memory title"),
     category: z.string().describe("Category directory name"),
     tags: z
@@ -656,7 +684,7 @@ server.tool("gnosys_add_structured", "Add a memory with structured input (no LLM
     }
 });
 // ─── Tool: gnosys_tags ───────────────────────────────────────────────────
-server.tool("gnosys_tags", "List all tags in the registry, grouped by category.", { projectRoot: projectRootParam }, async ({ projectRoot }) => {
+regTool("gnosys_tags", "List all tags in the registry, grouped by category.", { projectRoot: projectRootParam }, async ({ projectRoot }) => {
     // Tag registry is module-level and shared across projects, projectRoot is for API consistency
     if (!tagRegistry) {
         return { content: [{ type: "text", text: "Tag registry not loaded." }], isError: true };
@@ -671,7 +699,7 @@ server.tool("gnosys_tags", "List all tags in the registry, grouped by category."
     return { content: [{ type: "text", text: lines.join("\n") }] };
 });
 // ─── Tool: gnosys_tags_add ───────────────────────────────────────────────
-server.tool("gnosys_tags_add", "Add a new tag to the registry.", {
+regTool("gnosys_tags_add", "Add a new tag to the registry.", {
     category: z.string().describe("Tag category (domain, type, concern, status_tag)"),
     tag: z.string().describe("The new tag to add"),
     projectRoot: projectRootParam,
@@ -691,7 +719,7 @@ server.tool("gnosys_tags_add", "Add a new tag to the registry.", {
     };
 });
 // ─── Tool: gnosys_reinforce ──────────────────────────────────────────────
-server.tool("gnosys_reinforce", "Signal whether a memory was useful. 'useful' reinforces it (resets decay). 'not_relevant' means routing was wrong, not the memory (memory unchanged). 'outdated' flags for review.", {
+regTool("gnosys_reinforce", "Signal whether a memory was useful. 'useful' reinforces it (resets decay). 'not_relevant' means routing was wrong, not the memory (memory unchanged). 'outdated' flags for review.", {
     memory_id: z.string().describe("The memory ID (from frontmatter)"),
     signal: z
         .enum(["useful", "not_relevant", "outdated"])
@@ -699,46 +727,51 @@ server.tool("gnosys_reinforce", "Signal whether a memory was useful. 'useful' re
     context: z.string().optional().describe("Why this signal was given"),
     projectRoot: projectRootParam,
 }, async ({ memory_id, signal, context, projectRoot }) => {
-    const ctx = await resolveToolContext(projectRoot);
-    // Log to the first writable store's .config directory
-    const writeTarget = ctx.resolver.getWriteTarget();
-    if (writeTarget) {
-        const logPath = path.join(writeTarget.store.getStorePath(), ".config", "reinforcement.log");
-        const entry = JSON.stringify({
-            memory_id,
-            signal,
-            context,
-            timestamp: new Date().toISOString(),
-        });
-        await fs.appendFile(logPath, entry + "\n", "utf-8");
-    }
-    // If 'useful', find the memory across all stores and update if writable
-    if (signal === "useful") {
-        const allMemories = await ctx.resolver.getAllMemories();
-        const memory = allMemories.find((m) => m.frontmatter.id === memory_id);
-        if (memory) {
-            const sourceStore = ctx.resolver
-                .getStores()
-                .find((s) => s.label === memory.sourceLabel);
-            if (sourceStore) {
-                const count = (memory.frontmatter.reinforcement_count || 0) + 1;
-                // Write reinforcement to DB only (SQLite is sole source of truth)
-                if (ctx.centralDb?.isAvailable()) {
-                    syncReinforcementToDb(ctx.centralDb, memory_id, count);
-                    auditToDb(ctx.centralDb, "reinforce", memory_id, { signal, context });
+    try {
+        const ctx = await resolveToolContext(projectRoot);
+        // Log to the first writable store's .config directory
+        const writeTarget = ctx.resolver.getWriteTarget();
+        if (writeTarget) {
+            const logPath = path.join(writeTarget.store.getStorePath(), ".config", "reinforcement.log");
+            const entry = JSON.stringify({
+                memory_id,
+                signal,
+                context,
+                timestamp: new Date().toISOString(),
+            });
+            await fs.appendFile(logPath, entry + "\n", "utf-8");
+        }
+        // If 'useful', find the memory across all stores and update if writable
+        if (signal === "useful") {
+            const allMemories = await ctx.resolver.getAllMemories();
+            const memory = allMemories.find((m) => m.frontmatter.id === memory_id);
+            if (memory) {
+                const sourceStore = ctx.resolver
+                    .getStores()
+                    .find((s) => s.label === memory.sourceLabel);
+                if (sourceStore) {
+                    const count = (memory.frontmatter.reinforcement_count || 0) + 1;
+                    // Write reinforcement to DB only (SQLite is sole source of truth)
+                    if (ctx.centralDb?.isAvailable()) {
+                        syncReinforcementToDb(ctx.centralDb, memory_id, count);
+                        auditToDb(ctx.centralDb, "reinforce", memory_id, { signal, context });
+                    }
                 }
             }
         }
+        const messages = {
+            useful: `Memory ${memory_id} reinforced. Decay clock reset.`,
+            not_relevant: `Routing feedback logged for ${memory_id}. Memory unchanged — consider reviewing its relevance keywords or tags.`,
+            outdated: `Memory ${memory_id} flagged for review as outdated.`,
+        };
+        return { content: [{ type: "text", text: messages[signal] }] };
+    }
+    catch (err) {
+        return { content: [{ type: "text", text: formatMcpError("reinforcing memory", err) }], isError: true };
     }
-    const messages = {
-        useful: `Memory ${memory_id} reinforced. Decay clock reset.`,
-        not_relevant: `Routing feedback logged for ${memory_id}. Memory unchanged — consider reviewing its relevance keywords or tags.`,
-        outdated: `Memory ${memory_id} flagged for review as outdated.`,
-    };
-    return { content: [{ type: "text", text: messages[signal] }] };
 });
 // ─── Tool: gnosys_init ───────────────────────────────────────────────────
-server.tool("gnosys_init", "Initialize Gnosys in a project directory. Creates .gnosys/ with project identity (gnosys.json), registers the project in the central DB (~/.gnosys/gnosys.db), and sets up tag registry. You MUST run this before any other Gnosys tool in a new project. Pass the full absolute path to the project root.", {
+regTool("gnosys_init", "Initialize Gnosys in a project directory. Creates .gnosys/ with project identity (gnosys.json), registers the project in the central DB (~/.gnosys/gnosys.db), and sets up tag registry. You MUST run this before any other Gnosys tool in a new project. Pass the full absolute path to the project root.", {
     directory: z
         .string()
         .describe("Absolute path to the project directory to initialize. Required."),
@@ -812,7 +845,7 @@ server.tool("gnosys_init", "Initialize Gnosys in a project directory. Creates .g
     };
 });
 // ─── Tool: gnosys_migrate ────────────────────────────────────────────────
-server.tool("gnosys_migrate", "Migrate a Gnosys store (.gnosys/) from one directory to another. Updates the project name, working directory, and central DB registration. Use this when a project has moved or you want to consolidate stores.", {
+regTool("gnosys_migrate", "Migrate a Gnosys store (.gnosys/) from one directory to another. Updates the project name, working directory, and central DB registration. Use this when a project has moved or you want to consolidate stores.", {
     sourcePath: z.string().describe("Directory that currently contains .gnosys/ (absolute path)"),
     targetPath: z.string().describe("Directory to move .gnosys/ into (absolute path)"),
     newName: z.string().optional().describe("New project name (default: basename of target directory)"),
@@ -884,7 +917,7 @@ server.tool("gnosys_migrate", "Migrate a Gnosys store (.gnosys/) from one direct
     }
 });
 // ─── Tool: gnosys_update ─────────────────────────────────────────────────
-server.tool("gnosys_update", "Update an existing memory's frontmatter and/or content. Specify the memory path and the fields to change.", {
+regTool("gnosys_update", "Update an existing memory's frontmatter and/or content. Specify the memory path and the fields to change.", {
     path: z
         .string()
         .describe("Path to memory, optionally prefixed with store layer (e.g., 'project:decisions/auth.md')"),
@@ -990,7 +1023,7 @@ server.tool("gnosys_update", "Update an existing memory's frontmatter and/or con
     };
 });
 // ─── Tool: gnosys_stale ─────────────────────────────────────────────────
-server.tool("gnosys_stale", "Find memories that haven't been modified or reviewed within a given number of days. Useful for identifying knowledge that may be outdated.", {
+regTool("gnosys_stale", "Find memories that haven't been modified or reviewed within a given number of days. Useful for identifying knowledge that may be outdated.", {
     days: z
         .number()
         .optional()
@@ -998,46 +1031,51 @@ server.tool("gnosys_stale", "Find memories that haven't been modified or reviewe
     limit: z.number().optional().describe("Max results (default 20)"),
     projectRoot: projectRootParam,
 }, async ({ days, limit, projectRoot }) => {
-    const ctx = await resolveToolContext(projectRoot);
-    const threshold = days || 90;
-    const maxResults = limit || 20;
-    const cutoff = new Date();
-    cutoff.setDate(cutoff.getDate() - threshold);
-    const cutoffStr = cutoff.toISOString().split("T")[0];
-    const allMemories = await ctx.resolver.getAllMemories();
-    const stale = allMemories
-        .filter((m) => {
-        const lastTouched = m.frontmatter.last_reviewed || m.frontmatter.modified;
-        return lastTouched && lastTouched < cutoffStr;
-    })
-        .sort((a, b) => {
-        const aDate = a.frontmatter.last_reviewed || a.frontmatter.modified;
-        const bDate = b.frontmatter.last_reviewed || b.frontmatter.modified;
-        return (aDate || "").localeCompare(bDate || "");
-    })
-        .slice(0, maxResults);
-    if (stale.length === 0) {
+    try {
+        const ctx = await resolveToolContext(projectRoot);
+        const threshold = days || 90;
+        const maxResults = limit || 20;
+        const cutoff = new Date();
+        cutoff.setDate(cutoff.getDate() - threshold);
+        const cutoffStr = cutoff.toISOString().split("T")[0];
+        const allMemories = await ctx.resolver.getAllMemories();
+        const stale = allMemories
+            .filter((m) => {
+            const lastTouched = m.frontmatter.last_reviewed || m.frontmatter.modified;
+            return lastTouched && lastTouched < cutoffStr;
+        })
+            .sort((a, b) => {
+            const aDate = a.frontmatter.last_reviewed || a.frontmatter.modified;
+            const bDate = b.frontmatter.last_reviewed || b.frontmatter.modified;
+            return (aDate || "").localeCompare(bDate || "");
+        })
+            .slice(0, maxResults);
+        if (stale.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `No memories older than ${threshold} days found. Everything is fresh.`,
+                    },
+                ],
+            };
+        }
+        const lines = stale.map((m) => `- **${m.frontmatter.title}** (${m.sourceLabel}:${m.relativePath})\n  Last modified: ${m.frontmatter.modified}${m.frontmatter.last_reviewed ? `, Last reviewed: ${m.frontmatter.last_reviewed}` : ""}`);
         return {
             content: [
                 {
                     type: "text",
-                    text: `No memories older than ${threshold} days found. Everything is fresh.`,
+                    text: `Found ${stale.length} memories not touched in ${threshold}+ days:\n\n${lines.join("\n\n")}\n\nUse gnosys_read to review, then gnosys_update or gnosys_reinforce as needed.`,
                 },
             ],
         };
     }
-    const lines = stale.map((m) => `- **${m.frontmatter.title}** (${m.sourceLabel}:${m.relativePath})\n  Last modified: ${m.frontmatter.modified}${m.frontmatter.last_reviewed ? `, Last reviewed: ${m.frontmatter.last_reviewed}` : ""}`);
-    return {
-        content: [
-            {
-                type: "text",
-                text: `Found ${stale.length} memories not touched in ${threshold}+ days:\n\n${lines.join("\n\n")}\n\nUse gnosys_read to review, then gnosys_update or gnosys_reinforce as needed.`,
-            },
-        ],
-    };
+    catch (err) {
+        return { content: [{ type: "text", text: formatMcpError("finding stale memories", err) }], isError: true };
+    }
 });
 // ─── Tool: gnosys_commit_context ────────────────────────────────────────
-server.tool("gnosys_commit_context", "Pre-compaction memory sweep. Call this before context is lost (e.g., before a long conversation compacts). Extracts important decisions, facts, and insights from the conversation and commits novel ones to memory. Checks existing memories to avoid duplicates — only adds what's genuinely new or augments what's changed.", {
+regTool("gnosys_commit_context", "Pre-compaction memory sweep. Call this before context is lost (e.g., before a long conversation compacts). Extracts important decisions, facts, and insights from the conversation and commits novel ones to memory. Checks existing memories to avoid duplicates — only adds what's genuinely new or augments what's changed.", {
     context: z
         .string()
         .describe("Summary of the conversation or context to extract memories from. Include key decisions, facts, insights, and observations."),
@@ -1199,17 +1237,15 @@ Output ONLY the JSON array, no markdown fences.`,
     };
 });
 // ─── Tool: gnosys_history ────────────────────────────────────────────────
-server.tool("gnosys_history", "View version history for a memory. Shows what changed and when. Every memory write/update creates a git commit, so the full evolution is available.", {
+regTool("gnosys_history", "View audit history for a memory. Shows what changed and when based on the audit log.", {
     path: z.string().describe("Path to memory, optionally layer-prefixed"),
     limit: z.number().optional().describe("Max history entries (default 20)"),
     projectRoot: projectRootParam,
 }, async ({ path: memPath, limit, projectRoot }) => {
     const ctx = await resolveToolContext(projectRoot);
-    // DB-first: resolve memory ID and show timestamps
     if (ctx.centralDb?.isAvailable()) {
         const dbMem = ctx.centralDb.getMemory(memPath);
         if (dbMem) {
-            // Query audit_log for this memory
             const audits = ctx.centralDb.getAuditLog(dbMem.id, limit || 20);
             if (audits.length > 0) {
                 const lines = audits.map((e) => `- ${e.timestamp.split("T")[0]} — ${e.operation}${e.details ? ` (${e.details})` : ""}`);
@@ -1228,60 +1264,10 @@ server.tool("gnosys_history", "View version history for a memory. Shows what cha
             };
         }
     }
-    // Legacy file-based fallback
-    const memory = await ctx.resolver.readMemory(memPath);
-    if (!memory) {
-        return { content: [{ type: "text", text: `Memory not found: ${memPath}` }], isError: true };
-    }
-    const sourceStore = ctx.resolver.getStores().find((s) => s.label === memory.sourceLabel);
-    if (!sourceStore || !hasGitHistory(sourceStore.path)) {
-        return { content: [{ type: "text", text: "No git history available for this store." }], isError: true };
-    }
-    const history = getFileHistory(sourceStore.path, memory.relativePath, limit || 20);
-    if (history.length === 0) {
-        return { content: [{ type: "text", text: "No history found for this memory." }] };
-    }
-    const lines = history.map((e) => `- \`${e.commitHash.substring(0, 7)}\` ${e.date} — ${e.message}`);
-    return {
-        content: [{
-                type: "text",
-                text: `History for **${memory.frontmatter.title}** (${history.length} entries):\n\n${lines.join("\n")}\n\nUse gnosys_rollback with a commit hash to revert to a prior version.`,
-            }],
-    };
-});
-// ─── Tool: gnosys_rollback ──────────────────────────────────────────────
-server.tool("gnosys_rollback", "Rollback a memory to its state at a specific commit. Non-destructive: creates a new commit with the reverted content. Use gnosys_history first to find the target commit hash.", {
-    path: z.string().describe("Path to memory, optionally layer-prefixed"),
-    commitHash: z.string().describe("Git commit hash to revert to (full or abbreviated)"),
-    projectRoot: projectRootParam,
-}, async ({ path: memPath, commitHash, projectRoot }) => {
-    const ctx = await resolveToolContext(projectRoot);
-    const memory = await ctx.resolver.readMemory(memPath);
-    if (!memory) {
-        return { content: [{ type: "text", text: `Memory not found: ${memPath}` }], isError: true };
-    }
-    const sourceStore = ctx.resolver.getStores().find((s) => s.label === memory.sourceLabel);
-    if (!sourceStore?.writable) {
-        return { content: [{ type: "text", text: "Cannot rollback: store is read-only." }], isError: true };
-    }
-    const success = rollbackToCommit(sourceStore.path, memory.relativePath, commitHash);
-    if (!success) {
-        return { content: [{ type: "text", text: `Rollback failed. Verify the commit hash with gnosys_history.` }], isError: true };
-    }
-    // Reindex after rollback
-    if (ctx.search)
-        await reindexAllStores();
-    // Read the reverted memory
-    const reverted = await ctx.resolver.readMemory(memPath);
-    return {
-        content: [{
-                type: "text",
-                text: `Rolled back **${memory.frontmatter.title}** to commit ${commitHash.substring(0, 7)}.\n\nCurrent state: ${reverted?.frontmatter.title} [${reverted?.frontmatter.status}] (confidence: ${reverted?.frontmatter.confidence})`,
-            }],
-    };
+    return { content: [{ type: "text", text: `Memory not found: ${memPath}` }], isError: true };
 });
 // ─── Tool: gnosys_lens ──────────────────────────────────────────────────
-server.tool("gnosys_lens", "Filtered view of memories. Combine criteria to focus on specific subsets — e.g., 'active decisions about auth with confidence > 0.8'. Use AND (default) to require all criteria, or OR to match any.", {
+regTool("gnosys_lens", "Filtered view of memories. Combine criteria to focus on specific subsets — e.g., 'active decisions about auth with confidence > 0.8'. Use AND (default) to require all criteria, or OR to match any.", {
     category: z.string().optional().describe("Filter by category"),
     tags: z.array(z.string()).optional().describe("Filter by tags"),
     tagMatchMode: z.enum(["any", "all"]).optional().describe("'any' = has any listed tag (default), 'all' = must have every listed tag"),
@@ -1297,71 +1283,82 @@ server.tool("gnosys_lens", "Filtered view of memories. Combine criteria to focus
     operator: z.enum(["AND", "OR"]).optional().describe("Compound operator when multiple filter groups are provided (default: AND)"),
     projectRoot: projectRootParam,
 }, async ({ category, tags, tagMatchMode, status, author, authority, minConfidence, maxConfidence, createdAfter, createdBefore, modifiedAfter, modifiedBefore, projectRoot }) => {
-    const ctx = await resolveToolContext(projectRoot);
-    const allMemories = await ctx.resolver.getAllMemories();
-    const lens = {};
-    if (category)
-        lens.category = category;
-    if (tags) {
-        lens.tags = tags;
-        lens.tagMatchMode = tagMatchMode || "any";
-    }
-    if (status)
-        lens.status = status;
-    if (author)
-        lens.author = author;
-    if (authority)
-        lens.authority = authority;
-    if (minConfidence !== undefined)
-        lens.minConfidence = minConfidence;
-    if (maxConfidence !== undefined)
-        lens.maxConfidence = maxConfidence;
-    if (createdAfter)
-        lens.createdAfter = createdAfter;
-    if (createdBefore)
-        lens.createdBefore = createdBefore;
-    if (modifiedAfter)
-        lens.modifiedAfter = modifiedAfter;
-    if (modifiedBefore)
-        lens.modifiedBefore = modifiedBefore;
-    const result = applyLens(allMemories, lens);
-    if (result.length === 0) {
-        return { content: [{ type: "text", text: "No memories match the lens filter." }] };
-    }
-    const lines = result.map((m) => `- **${m.frontmatter.title}** [${m.frontmatter.status}] (${m.frontmatter.confidence})\n  ${m.sourceLabel ? m.sourceLabel + ":" : ""}${m.relativePath}`);
-    return {
-        content: [{ type: "text", text: `${result.length} memories match:\n\n${lines.join("\n\n")}` }],
-    };
+    try {
+        const ctx = await resolveToolContext(projectRoot);
+        const allMemories = await ctx.resolver.getAllMemories();
+        const lens = {};
+        if (category)
+            lens.category = category;
+        if (tags) {
+            lens.tags = tags;
+            lens.tagMatchMode = tagMatchMode || "any";
+        }
+        if (status)
+            lens.status = status;
+        if (author)
+            lens.author = author;
+        if (authority)
+            lens.authority = authority;
+        if (minConfidence !== undefined)
+            lens.minConfidence = minConfidence;
+        if (maxConfidence !== undefined)
+            lens.maxConfidence = maxConfidence;
+        if (createdAfter)
+            lens.createdAfter = createdAfter;
+        if (createdBefore)
+            lens.createdBefore = createdBefore;
+        if (modifiedAfter)
+            lens.modifiedAfter = modifiedAfter;
+        if (modifiedBefore)
+            lens.modifiedBefore = modifiedBefore;
+        const result = applyLens(allMemories, lens);
+        if (result.length === 0) {
+            return { content: [{ type: "text", text: "No memories match the lens filter." }] };
+        }
+        const lines = result.map((m) => `- **${m.frontmatter.title}** [${m.frontmatter.status}] (${m.frontmatter.confidence})\n  ${m.sourceLabel ? m.sourceLabel + ":" : ""}${m.relativePath}`);
+        return {
+            content: [{ type: "text", text: `${result.length} memories match:\n\n${lines.join("\n\n")}` }],
+        };
+    }
+    catch (err) {
+        return { content: [{ type: "text", text: formatMcpError("applying memory lens", err) }], isError: true };
+    }
 });
 // ─── Tool: gnosys_timeline ───────────────────────────────────────────────
-server.tool("gnosys_timeline", "View memory creation and modification activity over time. Shows how knowledge evolves by grouping memories into time periods.", {
+regTool("gnosys_timeline", "View memory creation and modification activity over time. Shows how knowledge evolves by grouping memories into time periods.", {
     period: z.enum(["day", "week", "month", "year"]).optional().describe("Grouping period (default: month)"),
     projectRoot: projectRootParam,
 }, async ({ period, projectRoot }) => {
-    const ctx = await resolveToolContext(projectRoot);
-    const allMemories = await ctx.resolver.getAllMemories();
-    const entries = groupByPeriod(allMemories, period || "month");
-    if (entries.length === 0) {
-        return { content: [{ type: "text", text: "No memories found for timeline." }] };
+    try {
+        const ctx = await resolveToolContext(projectRoot);
+        const allMemories = await ctx.resolver.getAllMemories();
+        const entries = groupByPeriod(allMemories, period || "month");
+        if (entries.length === 0) {
+            return { content: [{ type: "text", text: "No memories found for timeline." }] };
+        }
+        const lines = entries.map((e) => `**${e.period}** — ${e.created} created, ${e.modified} modified\n  ${e.titles.slice(0, 5).join(", ")}${e.titles.length > 5 ? ` (+${e.titles.length - 5} more)` : ""}`);
+        return {
+            content: [{ type: "text", text: `Knowledge Timeline (by ${period || "month"}):\n\n${lines.join("\n\n")}` }],
+        };
+    }
+    catch (err) {
+        return { content: [{ type: "text", text: formatMcpError("building timeline", err) }], isError: true };
     }
-    const lines = entries.map((e) => `**${e.period}** — ${e.created} created, ${e.modified} modified\n  ${e.titles.slice(0, 5).join(", ")}${e.titles.length > 5 ? ` (+${e.titles.length - 5} more)` : ""}`);
-    return {
-        content: [{ type: "text", text: `Knowledge Timeline (by ${period || "month"}):\n\n${lines.join("\n\n")}` }],
-    };
 });
 // ─── Tool: gnosys_stats ─────────────────────────────────────────────────
-server.tool("gnosys_stats", "Summary statistics across all memories — totals by category, status, author, authority, average confidence, and date ranges.", { projectRoot: projectRootParam }, async ({ projectRoot }) => {
-    const ctx = await resolveToolContext(projectRoot);
-    const allMemories = await ctx.resolver.getAllMemories();
-    const stats = computeStats(allMemories);
-    if (stats.totalCount === 0) {
-        return { content: [{ type: "text", text: "No memories found." }] };
-    }
-    const catLines = Object.entries(stats.byCategory).map(([k, v]) => `  ${k}: ${v}`).join("\n");
-    const statusLines = Object.entries(stats.byStatus).map(([k, v]) => `  ${k}: ${v}`).join("\n");
-    const authorLines = Object.entries(stats.byAuthor).map(([k, v]) => `  ${k}: ${v}`).join("\n");
-    const authLines = Object.entries(stats.byAuthority).map(([k, v]) => `  ${k}: ${v}`).join("\n");
-    const text = `Gnosys Memory Statistics
+regTool("gnosys_stats", "Summary statistics across all memories — totals by category, status, author, authority, average confidence, and date ranges.", { projectRoot: projectRootParam }, async ({ projectRoot }) => {
+    try {
+        const ctx = await resolveToolContext(projectRoot);
+        const allMemories = await ctx.resolver.getAllMemories();
+        const stats = computeStats(allMemories);
+        if (stats.totalCount === 0) {
+            return { content: [{ type: "text", text: "No memories found." }] };
+        }
+        const catLines = Object.entries(stats.byCategory).map(([k, v]) => `  ${k}: ${v}`).join("\n");
+        const statusLines = Object.entries(stats.byStatus).map(([k, v]) => `  ${k}: ${v}`).join("\n");
+        const authorLines = Object.entries(stats.byAuthor).map(([k, v]) => `  ${k}: ${v}`).join("\n");
+        const authLines = Object.entries(stats.byAuthority).map(([k, v]) => `  ${k}: ${v}`).join("\n");
+        const text = `Gnosys Memory Statistics
 Total: ${stats.totalCount} memories
 
 By Category:
@@ -1380,10 +1377,14 @@ Average Confidence: ${stats.averageConfidence.toFixed(2)}
 Oldest: ${stats.oldestCreated || "—"}
 Newest: ${stats.newestCreated || "—"}
 Last Modified: ${stats.lastModified || "—"}`;
-    return { content: [{ type: "text", text }] };
+        return { content: [{ type: "text", text }] };
+    }
+    catch (err) {
+        return { content: [{ type: "text", text: formatMcpError("computing statistics", err) }], isError: true };
+    }
 });
 // ─── Tool: gnosys_links ─────────────────────────────────────────────────
-server.tool("gnosys_links", "Show wikilinks for a specific memory — outgoing [[links]] and backlinks from other memories. Obsidian-compatible [[Title]] and [[path|display]] syntax.", {
+regTool("gnosys_links", "Show wikilinks for a specific memory — outgoing [[links]] and backlinks from other memories. Obsidian-compatible [[Title]] and [[path|display]] syntax.", {
     path: z.string().describe("Path to memory, optionally layer-prefixed"),
     projectRoot: projectRootParam,
 }, async ({ path: memPath, projectRoot }) => {
@@ -1447,17 +1448,22 @@ server.tool("gnosys_links", "Show wikilinks for a specific memory — outgoing [
     return { content: [{ type: "text", text: parts.join("\n") }] };
 });
 // ─── Tool: gnosys_graph ─────────────────────────────────────────────────
-server.tool("gnosys_graph", "Show the full cross-reference graph across all memories. Reveals clusters, orphaned links, and the most-connected memories.", { projectRoot: projectRootParam }, async ({ projectRoot }) => {
-    const ctx = await resolveToolContext(projectRoot);
-    const allMemories = await ctx.resolver.getAllMemories();
-    if (allMemories.length === 0) {
-        return { content: [{ type: "text", text: "No memories found." }] };
+regTool("gnosys_graph", "Show the full cross-reference graph across all memories. Reveals clusters, orphaned links, and the most-connected memories.", { projectRoot: projectRootParam }, async ({ projectRoot }) => {
+    try {
+        const ctx = await resolveToolContext(projectRoot);
+        const allMemories = await ctx.resolver.getAllMemories();
+        if (allMemories.length === 0) {
+            return { content: [{ type: "text", text: "No memories found." }] };
+        }
+        const graph = buildLinkGraph(allMemories);
+        return { content: [{ type: "text", text: formatGraphSummary(graph) }] };
+    }
+    catch (err) {
+        return { content: [{ type: "text", text: formatMcpError("building graph", err) }], isError: true };
     }
-    const graph = buildLinkGraph(allMemories);
-    return { content: [{ type: "text", text: formatGraphSummary(graph) }] };
 });
 // ─── Tool: gnosys_bootstrap ─────────────────────────────────────────────
-server.tool("gnosys_bootstrap", "Batch-import existing documents from a directory into the memory store. Scans for markdown files and creates memories. Use dry_run=true to preview.", {
+regTool("gnosys_bootstrap", "Batch-import existing documents from a directory into the memory store. Scans for markdown files and creates memories. Use dry_run=true to preview.", {
     sourceDir: z.string().describe("Absolute path to directory containing documents to import"),
     patterns: z.array(z.string()).optional().describe("File glob patterns (default: ['**/*.md'])"),
     skipExisting: z.boolean().optional().describe("Skip files whose titles already exist (default: false)"),
@@ -1516,7 +1522,7 @@ server.tool("gnosys_bootstrap", "Batch-import existing documents from a director
     }
 });
 // ─── Tool: gnosys_import ─────────────────────────────────────────────────
-server.tool("gnosys_import", "Bulk import structured data (CSV, JSON, JSONL) into Gnosys memories. Map source fields to title/category/content/tags/relevance. Use mode='llm' for smart ingestion with keyword clouds, or 'structured' for fast direct mapping. For large datasets (>100 records with LLM), the CLI is recommended: gnosys import <file>", {
+regTool("gnosys_import", "Bulk import structured data (CSV, JSON, JSONL) into Gnosys memories. Map source fields to title/category/content/tags/relevance. Use mode='llm' for smart ingestion with keyword clouds, or 'structured' for fast direct mapping. For large datasets (>100 records with LLM), the CLI is recommended: gnosys import <file>", {
     format: z.enum(["csv", "json", "jsonl"]).describe("Data format"),
     data: z.string().describe("File path, URL, or inline data"),
     mapping: z
@@ -1597,7 +1603,7 @@ server.tool("gnosys_import", "Bulk import structured data (CSV, JSON, JSONL) int
     }
 });
 // ─── Tool: gnosys_hybrid_search ──────────────────────────────────────────
-server.tool("gnosys_hybrid_search", "Search memories using hybrid keyword + semantic search with Reciprocal Rank Fusion. Combines FTS5 keyword matching with embedding-based semantic similarity for best results. Run gnosys_reindex first if embeddings don't exist yet.", {
+regTool("gnosys_hybrid_search", "Search memories using hybrid keyword + semantic search with Reciprocal Rank Fusion. Combines FTS5 keyword matching with embedding-based semantic similarity for best results. Run gnosys_reindex first if embeddings don't exist yet.", {
     query: z.string().describe("Natural language search query"),
     limit: z.number().optional().describe("Max results (default 15)"),
     mode: z.enum(["keyword", "semantic", "hybrid"]).optional().describe("Search mode (default: hybrid)"),
@@ -1649,7 +1655,7 @@ server.tool("gnosys_hybrid_search", "Search memories using hybrid keyword + sema
     }
 });
 // ─── Tool: gnosys_semantic_search ────────────────────────────────────────
-server.tool("gnosys_semantic_search", "Search memories using semantic similarity only (no keyword matching). Finds conceptually related memories even without exact keyword matches. Requires embeddings — run gnosys_reindex first.", {
+regTool("gnosys_semantic_search", "Search memories using semantic similarity only (no keyword matching). Finds conceptually related memories even without exact keyword matches. Requires embeddings — run gnosys_reindex first.", {
     query: z.string().describe("Natural language search query"),
     limit: z.number().optional().describe("Max results (default 15)"),
     projectRoot: projectRootParam,
@@ -1685,7 +1691,7 @@ server.tool("gnosys_semantic_search", "Search memories using semantic similarity
     }
 });
 // ─── Tool: gnosys_reindex ────────────────────────────────────────────────
-server.tool("gnosys_reindex", "Rebuild all semantic embeddings from every memory file. Downloads the embedding model (~80 MB) on first run. Required before hybrid/semantic search can be used. Safe to re-run — fully regenerates the index.", { projectRoot: projectRootParam }, async ({ projectRoot }) => {
+regTool("gnosys_reindex", "Rebuild all semantic embeddings from every memory file. Downloads the embedding model (~80 MB) on first run. Required before hybrid/semantic search can be used. Safe to re-run — fully regenerates the index.", { projectRoot: projectRootParam }, async ({ projectRoot }) => {
     // Note: reindex operates on all stores, projectRoot is for API consistency
     (projectRoot); // quiets unused warning if any
     await ensureHeavyDeps();
@@ -1716,7 +1722,7 @@ server.tool("gnosys_reindex", "Rebuild all semantic embeddings from every memory
     }
 });
 // ─── Tool: gnosys_ask ────────────────────────────────────────────────────
-server.tool("gnosys_ask", "Ask a natural-language question and get a synthesized answer with citations from the entire vault. Uses hybrid search to find relevant memories, then LLM to synthesize a cited response. Citations are Obsidian wikilinks [[filename.md]]. Requires an LLM provider (Anthropic or Ollama) and embeddings (run gnosys_reindex first).", {
+regTool("gnosys_ask", "Ask a natural-language question and get a synthesized answer with citations from the entire vault. Uses hybrid search to find relevant memories, then LLM to synthesize a cited response. Citations are Obsidian wikilinks [[filename.md]]. Requires an LLM provider (Anthropic or Ollama) and embeddings (run gnosys_reindex first).", {
     question: z.string().describe("Natural language question to answer from the vault"),
     limit: z.number().optional().describe("Max memories to retrieve (default 15)"),
     mode: z.enum(["keyword", "semantic", "hybrid"]).optional().describe("Search mode (default: hybrid)"),
@@ -1773,7 +1779,7 @@ server.tool("gnosys_ask", "Ask a natural-language question and get a synthesized
     }
 });
 // ─── Tool: gnosys_maintain ────────────────────────────────────────────────
-server.tool("gnosys_maintain", "Run vault maintenance: detect duplicate memories, apply confidence decay, consolidate similar memories. Use --dry-run mode first to see what would change. Requires embeddings (run gnosys_reindex first).", {
+regTool("gnosys_maintain", "Run vault maintenance: detect duplicate memories, apply confidence decay, consolidate similar memories. Use --dry-run mode first to see what would change. Requires embeddings (run gnosys_reindex first).", {
     dryRun: z.boolean().optional().describe("Show what would change without modifying anything (default: true)"),
     autoApply: z.boolean().optional().describe("Automatically apply all changes (default: false)"),
     projectRoot: projectRootParam,
@@ -1808,7 +1814,7 @@ server.tool("gnosys_maintain", "Run vault maintenance: detect duplicate memories
     }
 });
 // ─── Tool: gnosys_dearchive ──────────────────────────────────────────────
-server.tool("gnosys_dearchive", "Force-dearchive memories from archive.db back to active. Search the archive for memories matching a query, then restore them to the active layer. Used when you need specific archived knowledge that wasn't auto-dearchived by search/ask.", {
+regTool("gnosys_dearchive", "Force-dearchive memories from archive.db back to active. Search the archive for memories matching a query, then restore them to the active layer. Used when you need specific archived knowledge that wasn't auto-dearchived by search/ask.", {
     query: z.string().describe("Search query to find archived memories to restore"),
     limit: z.number().optional().describe("Max memories to dearchive (default 5)"),
     projectRoot: projectRootParam,
@@ -1826,7 +1832,7 @@ server.tool("gnosys_dearchive", "Force-dearchive memories from archive.db back t
         const archive = new GnosysArchive(writeTarget.path);
         if (!archive.isAvailable()) {
             return {
-                content: [{ type: "text", text: "Archive not available. Is better-sqlite3 installed?" }],
+                content: [{ type: "text", text: "Archive not available. Install it with: npm install better-sqlite3" }],
                 isError: true,
             };
         }
@@ -1863,7 +1869,7 @@ server.tool("gnosys_dearchive", "Force-dearchive memories from archive.db back t
     }
 });
 // ─── Tool: gnosys_reindex_graph ──────────────────────────────────────────
-server.tool("gnosys_reindex_graph", "Build or rebuild the wikilink graph (.gnosys/graph.json). Parses all [[wikilinks]] across memories and generates a persistent JSON graph with nodes, edges, and stats.", { projectRoot: projectRootParam }, async ({ projectRoot }) => {
+regTool("gnosys_reindex_graph", "Build or rebuild the wikilink graph (.gnosys/graph.json). Parses all [[wikilinks]] across memories and generates a persistent JSON graph with nodes, edges, and stats.", { projectRoot: projectRootParam }, async ({ projectRoot }) => {
     const ctx = await resolveToolContext(projectRoot);
     try {
         const { reindexGraph, formatGraphStats } = await import("./lib/graph.js");
@@ -1880,54 +1886,59 @@ server.tool("gnosys_reindex_graph", "Build or rebuild the wikilink graph (.gnosy
     }
 });
 // ─── Tool: gnosys_dream ──────────────────────────────────────────────────
-server.tool("gnosys_dream", "Run a Dream Mode cycle — idle-time consolidation that decays confidence, generates category summaries, discovers relationships, and creates review suggestions. NEVER deletes memories. Safe to run anytime.", {
+regTool("gnosys_dream", "Run a Dream Mode cycle — idle-time consolidation that decays confidence, generates category summaries, discovers relationships, and creates review suggestions. NEVER deletes memories. Safe to run anytime.", {
     maxRuntimeMinutes: z.number().int().min(1).max(120).default(30).optional().describe("Max runtime in minutes"),
     selfCritique: z.boolean().default(true).optional().describe("Enable self-critique scoring"),
     generateSummaries: z.boolean().default(true).optional().describe("Generate category summaries"),
     discoverRelationships: z.boolean().default(true).optional().describe("Discover relationships between memories"),
     projectRoot: projectRootParam,
 }, async (params) => {
-    const ctx = await resolveToolContext(params.projectRoot);
-    if (!ctx.centralDb || !ctx.centralDb.isAvailable() || !ctx.centralDb.isMigrated()) {
+    try {
+        const ctx = await resolveToolContext(params.projectRoot);
+        if (!ctx.centralDb || !ctx.centralDb.isAvailable() || !ctx.centralDb.isMigrated()) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Dream Mode requires gnosys.db (v2.0). Run `gnosys migrate` first.",
+                    },
+                ],
+            };
+        }
+        // Record activity to reset idle timer (if scheduler is running)
+        dreamScheduler?.recordActivity();
+        const dreamConfig = {
+            enabled: true,
+            idleMinutes: 0, // Run immediately (manual trigger)
+            maxRuntimeMinutes: params.maxRuntimeMinutes ?? 30,
+            selfCritique: params.selfCritique ?? true,
+            generateSummaries: params.generateSummaries ?? true,
+            discoverRelationships: params.discoverRelationships ?? true,
+            minMemories: 1, // No minimum for manual trigger
+            provider: ctx.config?.dream?.provider || "ollama",
+            model: ctx.config?.dream?.model,
+        };
+        // v5.9.1 (#100): dream engine pulls LLM provider machinery — load lazily.
+        const { GnosysDreamEngine, formatDreamReport } = await import("./lib/dream.js");
+        const engine = new GnosysDreamEngine(ctx.centralDb, ctx.config || DEFAULT_CONFIG, dreamConfig);
+        const report = await engine.dream((phase, detail) => {
+            console.error(`[dream:${phase}] ${detail}`);
+        });
         return {
             content: [
                 {
                     type: "text",
-                    text: "Dream Mode requires gnosys.db (v2.0). Run `gnosys migrate` first.",
+                    text: formatDreamReport(report),
                 },
             ],
         };
     }
-    // Record activity to reset idle timer (if scheduler is running)
-    dreamScheduler?.recordActivity();
-    const dreamConfig = {
-        enabled: true,
-        idleMinutes: 0, // Run immediately (manual trigger)
-        maxRuntimeMinutes: params.maxRuntimeMinutes ?? 30,
-        selfCritique: params.selfCritique ?? true,
-        generateSummaries: params.generateSummaries ?? true,
-        discoverRelationships: params.discoverRelationships ?? true,
-        minMemories: 1, // No minimum for manual trigger
-        provider: ctx.config?.dream?.provider || "ollama",
-        model: ctx.config?.dream?.model,
-    };
-    // v5.9.1 (#100): dream engine pulls LLM provider machinery — load lazily.
-    const { GnosysDreamEngine, formatDreamReport } = await import("./lib/dream.js");
-    const engine = new GnosysDreamEngine(ctx.centralDb, ctx.config || DEFAULT_CONFIG, dreamConfig);
-    const report = await engine.dream((phase, detail) => {
-        console.error(`[dream:${phase}] ${detail}`);
-    });
-    return {
-        content: [
-            {
-                type: "text",
-                text: formatDreamReport(report),
-            },
-        ],
-    };
+    catch (err) {
+        return { content: [{ type: "text", text: formatMcpError("running dream mode", err) }], isError: true };
+    }
 });
 // ─── Tool: gnosys_export ─────────────────────────────────────────────────
-server.tool("gnosys_export", "Export gnosys.db to Obsidian-compatible vault — atomic Markdown files with YAML frontmatter, [[wikilinks]], category summaries, and relationship graph. One-way export, never modifies gnosys.db.", {
+regTool("gnosys_export", "Export gnosys.db to Obsidian-compatible vault — atomic Markdown files with YAML frontmatter, [[wikilinks]], category summaries, and relationship graph. One-way export, never modifies gnosys.db.", {
     targetDir: z.string().describe("Target directory path for export"),
     activeOnly: z.boolean().default(true).optional().describe("Only export active memories (default: true)"),
     overwrite: z.boolean().default(false).optional().describe("Overwrite existing files"),
@@ -1936,39 +1947,44 @@ server.tool("gnosys_export", "Export gnosys.db to Obsidian-compatible vault —
     includeGraph: z.boolean().default(true).optional().describe("Include relationship graph"),
     projectRoot: projectRootParam,
 }, async (params) => {
-    const ctx = await resolveToolContext(params.projectRoot);
-    if (!ctx.centralDb || !ctx.centralDb.isAvailable() || !ctx.centralDb.isMigrated()) {
+    try {
+        const ctx = await resolveToolContext(params.projectRoot);
+        if (!ctx.centralDb || !ctx.centralDb.isAvailable() || !ctx.centralDb.isMigrated()) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Export requires gnosys.db (v2.0). Run `gnosys migrate` first.",
+                    },
+                ],
+            };
+        }
+        // v5.9.1 (#100): exporter pulls obsidian-flavored markdown gen — lazy.
+        const { GnosysExporter, formatExportReport } = await import("./lib/export.js");
+        const exporter = new GnosysExporter(ctx.centralDb);
+        const report = await exporter.export({
+            targetDir: params.targetDir,
+            activeOnly: params.activeOnly ?? true,
+            overwrite: params.overwrite ?? false,
+            includeSummaries: params.includeSummaries ?? true,
+            includeReviews: params.includeReviews ?? true,
+            includeGraph: params.includeGraph ?? true,
+        });
         return {
             content: [
                 {
                     type: "text",
-                    text: "Export requires gnosys.db (v2.0). Run `gnosys migrate` first.",
+                    text: formatExportReport(report),
                 },
             ],
         };
     }
-    // v5.9.1 (#100): exporter pulls obsidian-flavored markdown gen — lazy.
-    const { GnosysExporter, formatExportReport } = await import("./lib/export.js");
-    const exporter = new GnosysExporter(ctx.centralDb);
-    const report = await exporter.export({
-        targetDir: params.targetDir,
-        activeOnly: params.activeOnly ?? true,
-        overwrite: params.overwrite ?? false,
-        includeSummaries: params.includeSummaries ?? true,
-        includeReviews: params.includeReviews ?? true,
-        includeGraph: params.includeGraph ?? true,
-    });
-    return {
-        content: [
-            {
-                type: "text",
-                text: formatExportReport(report),
-            },
-        ],
-    };
+    catch (err) {
+        return { content: [{ type: "text", text: formatMcpError("exporting vault", err) }], isError: true };
+    }
 });
 // ─── Tool: gnosys_dashboard ──────────────────────────────────────────────
-server.tool("gnosys_dashboard", "Show the Gnosys system dashboard: memory counts, maintenance health, graph stats, LLM provider status. Returns structured JSON.", { projectRoot: projectRootParam }, async ({ projectRoot }) => {
+regTool("gnosys_dashboard", "Show the Gnosys system dashboard: memory counts, maintenance health, graph stats, LLM provider status. Returns structured JSON.", { projectRoot: projectRootParam }, async ({ projectRoot }) => {
     const ctx = await resolveToolContext(projectRoot);
     try {
         const { collectDashboardData, formatDashboardJSON } = await import("./lib/dashboard.js");
@@ -1985,40 +2001,45 @@ server.tool("gnosys_dashboard", "Show the Gnosys system dashboard: memory counts
     }
 });
 // ─── Tool: gnosys_stores ─────────────────────────────────────────────────
-server.tool("gnosys_stores", "Debug tool — lists all detected Gnosys stores across registered projects, MCP workspace roots, cwd, and environment variables. Shows which store is active and helps diagnose multi-project routing.", {}, async () => {
-    const lines = [];
-    lines.push("GNOSYS STORES — Multi-Project Overview");
-    lines.push("=".repeat(45));
-    lines.push("");
-    // Active stores
-    lines.push("ACTIVE STORES:");
-    lines.push(resolver.getSummary());
-    lines.push("");
-    // MCP roots
-    const mcpRoots = GnosysResolver.getMcpRoots();
-    lines.push(`MCP WORKSPACE ROOTS (${mcpRoots.length}):`);
-    if (mcpRoots.length === 0) {
-        lines.push("  (none — host may not support roots/list)");
+regTool("gnosys_stores", "Debug tool — lists all detected Gnosys stores across registered projects, MCP workspace roots, cwd, and environment variables. Shows which store is active and helps diagnose multi-project routing.", {}, async () => {
+    try {
+        const lines = [];
+        lines.push("GNOSYS STORES — Multi-Project Overview");
+        lines.push("=".repeat(45));
+        lines.push("");
+        // Active stores
+        lines.push("ACTIVE STORES:");
+        lines.push(resolver.getSummary());
+        lines.push("");
+        // MCP roots
+        const mcpRoots = GnosysResolver.getMcpRoots();
+        lines.push(`MCP WORKSPACE ROOTS (${mcpRoots.length}):`);
+        if (mcpRoots.length === 0) {
+            lines.push("  (none — host may not support roots/list)");
+        }
+        else {
+            for (const root of mcpRoots) {
+                lines.push(`  ${root}`);
+            }
+        }
+        lines.push("");
+        // All detected stores
+        const detected = await resolver.detectAllStores();
+        lines.push(`ALL DETECTED STORES (${detected.length}):`);
+        for (const d of detected) {
+            const status = d.isActive ? "✓ ACTIVE" : d.hasGnosys ? "available" : "no .gnosys";
+            lines.push(`  [${d.source}] ${d.path} — ${status}`);
+        }
+        lines.push("");
+        // Usage hint
+        lines.push("USAGE:");
+        lines.push("  Pass projectRoot to any tool to target a specific project:");
+        lines.push('  e.g. gnosys_add({ projectRoot: "/path/to/my-project", ... })');
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+    catch (err) {
+        return { content: [{ type: "text", text: formatMcpError("listing stores", err) }], isError: true };
     }
-    else {
-        for (const root of mcpRoots) {
-            lines.push(`  ${root}`);
-        }
-    }
-    lines.push("");
-    // All detected stores
-    const detected = await resolver.detectAllStores();
-    lines.push(`ALL DETECTED STORES (${detected.length}):`);
-    for (const d of detected) {
-        const status = d.isActive ? "✓ ACTIVE" : d.hasGnosys ? "available" : "no .gnosys";
-        lines.push(`  [${d.source}] ${d.path} — ${status}`);
-    }
-    lines.push("");
-    // Usage hint
-    lines.push("USAGE:");
-    lines.push("  Pass projectRoot to any tool to target a specific project:");
-    lines.push('  e.g. gnosys_add({ projectRoot: "/path/to/my-project", ... })');
-    return { content: [{ type: "text", text: lines.join("\n") }] };
 });
 // ─── Helper: reindex search across all stores ────────────────────────────
 async function reindexAllStores() {
@@ -2043,7 +2064,7 @@ async function reindexAllStores() {
 // injecting relevant memories into the model context — no tool call needed.
 //
 // Priority 1 + audience: assistant = hosts inject this before every message.
-server.resource("gnosys_recall", "gnosys://recall", {
+regResource("gnosys_recall", "gnosys://recall", {
     description: "Automatic memory injection. Hosts read this resource on every turn to inject the most relevant memories as context. Returns a <gnosys-recall> block with [[wikilinks]] and relevance scores. Priority 1 (highest) — designed for always-on context injection without any tool call. Configure aggressiveness in gnosys.json: recall.aggressive (default: true).",
     mimeType: "text/markdown",
     annotations: {
@@ -2086,7 +2107,7 @@ server.resource("gnosys_recall", "gnosys://recall", {
 // ─── Tool: gnosys_recall (query-specific fallback) ──────────────────────
 // For hosts that don't support MCP Resources, or when the agent wants to
 // recall memories for a specific query. The resource above is preferred.
-server.tool("gnosys_recall", "Fast memory recall — inject relevant memories as context. Returns <gnosys-recall> block. In aggressive mode (default), always returns top memories even at medium relevance. Prefer the gnosys://recall MCP Resource for automatic injection (no tool call needed).", {
+regTool("gnosys_recall", "Fast memory recall — inject relevant memories as context. Returns <gnosys-recall> block. In aggressive mode (default), always returns top memories even at medium relevance. Prefer the gnosys://recall MCP Resource for automatic injection (no tool call needed).", {
     query: z
         .string()
         .describe("What the agent is currently working on. Use keywords. Example: 'auth JWT middleware' or 'database migration schema'"),
@@ -2095,32 +2116,37 @@ server.tool("gnosys_recall", "Fast memory recall — inject relevant memories as
     aggressive: z.boolean().optional().describe("Override aggressive mode for this call. Default: from gnosys.json (true)"),
     projectRoot: projectRootParam,
 }, async ({ query, limit, traceId, aggressive, projectRoot }) => {
-    const ctx = await resolveToolContext(projectRoot);
-    if (!ctx.search) {
+    try {
+        const ctx = await resolveToolContext(projectRoot);
+        if (!ctx.search) {
+            return {
+                content: [{ type: "text", text: "<gnosys: no-strong-recall-needed>" }],
+            };
+        }
+        const storePath = ctx.resolver.getWriteTarget()?.store.getStorePath() || "";
+        const recallConfig = {
+            ...ctx.config.recall,
+            ...(aggressive !== undefined ? { aggressive } : {}),
+        };
+        const result = await recall(query, {
+            limit: Math.min(limit || recallConfig.maxMemories, 15),
+            search: ctx.search,
+            resolver: ctx.resolver,
+            storePath,
+            traceId,
+            recallConfig,
+            gnosysDb: ctx.centralDb || undefined,
+        });
         return {
-            content: [{ type: "text", text: "<gnosys: no-strong-recall-needed>" }],
+            content: [{ type: "text", text: formatRecall(result) }],
         };
     }
-    const storePath = ctx.resolver.getWriteTarget()?.store.getStorePath() || "";
-    const recallConfig = {
-        ...ctx.config.recall,
-        ...(aggressive !== undefined ? { aggressive } : {}),
-    };
-    const result = await recall(query, {
-        limit: Math.min(limit || recallConfig.maxMemories, 15),
-        search: ctx.search,
-        resolver: ctx.resolver,
-        storePath,
-        traceId,
-        recallConfig,
-        gnosysDb: ctx.centralDb || undefined,
-    });
-    return {
-        content: [{ type: "text", text: formatRecall(result) }],
-    };
+    catch (err) {
+        return { content: [{ type: "text", text: formatMcpError("recalling memories", err) }], isError: true };
+    }
 });
 // ─── Tool: gnosys_audit ──────────────────────────────────────────────────
-server.tool("gnosys_audit", "View the audit trail of all memory operations (reads, writes, reinforcements, dearchives, maintenance). Shows a timeline of what happened and when. Useful for debugging 'why did the agent forget X?'", {
+regTool("gnosys_audit", "View the audit trail of all memory operations (reads, writes, reinforcements, dearchives, maintenance). Shows a timeline of what happened and when. Useful for debugging 'why did the agent forget X?'", {
     days: z.number().optional().describe("Number of days to look back (default 7)"),
     operation: z.string().optional().describe("Filter by operation type: read, write, reinforce, dearchive, archive, maintain, search, ask, recall"),
     limit: z.number().optional().describe("Max entries to return (default 100)"),
@@ -2144,7 +2170,7 @@ server.tool("gnosys_audit", "View the audit trail of all memory operations (read
     };
 });
 // ─── Tool: gnosys_preference_set ─────────────────────────────────────────
-server.tool("gnosys_preference_set", "Set a user preference. Preferences are stored in the central DB as user-scoped memories. They persist across all projects and are injected into agent rules files on `gnosys sync`. Use this to record workflow conventions, coding standards, tool preferences, etc.", {
+regTool("gnosys_preference_set", "Set a user preference. Preferences are stored in the central DB as user-scoped memories. They persist across all projects and are injected into agent rules files on `gnosys sync`. Use this to record workflow conventions, coding standards, tool preferences, etc.", {
     key: z.string().describe("Preference key, kebab-case. Examples: 'commit-convention', 'code-style', 'llm-provider', 'testing-approach', 'naming-convention'"),
     value: z.string().describe("The preference value. Can be a sentence or paragraph describing the convention."),
     title: z.string().optional().describe("Human-readable title. Auto-generated from key if omitted."),
@@ -2158,6 +2184,18 @@ server.tool("gnosys_preference_set", "Set a user preference. Preferences are sto
         };
     }
     try {
+        if (!KNOWN_PREFERENCE_KEYS.includes(key)) {
+            const suggestion = suggestPreferenceKey(key);
+            if (suggestion) {
+                return {
+                    isError: true,
+                    content: [{
+                            type: "text",
+                            text: `Unknown preference key \`${key}\` — did you mean \`${suggestion}\`?`,
+                        }],
+                };
+            }
+        }
         const pref = setPreference(centralDb, key, value, { title, tags });
         return {
             content: [{
@@ -2178,7 +2216,7 @@ server.tool("gnosys_preference_set", "Set a user preference. Preferences are sto
     }
 });
 // ─── Tool: gnosys_preference_get ─────────────────────────────────────────
-server.tool("gnosys_preference_get", "Get a user preference by key, or list all preferences.", {
+regTool("gnosys_preference_get", "Get a user preference by key, or list all preferences.", {
     key: z.string().optional().describe("Preference key to retrieve. Omit to list all preferences."),
     projectRoot: projectRootParam,
 }, async ({ key }) => {
@@ -2220,7 +2258,7 @@ server.tool("gnosys_preference_get", "Get a user preference by key, or list all
     };
 });
 // ─── Tool: gnosys_preference_delete ──────────────────────────────────────
-server.tool("gnosys_preference_delete", "Delete a user preference by key.", {
+regTool("gnosys_preference_delete", "Delete a user preference by key.", {
     key: z.string().describe("Preference key to delete."),
     projectRoot: projectRootParam,
 }, async ({ key }) => {
@@ -2257,7 +2295,7 @@ server.tool("gnosys_preference_delete", "Delete a user preference by key.", {
 //
 // Routine in-session context flows through the SessionStart hook
 // (`gnosys recall`), not through this tool.
-server.tool("gnosys_sync", "Get the current user preferences + project conventions formatted as a GNOSYS:START/GNOSYS:END block. By default returns the block as text only (no disk write). Pass commit_to_disk=true to write it into the detected agent rules file (CLAUDE.md, .cursor/rules/gnosys.mdc) — only do this if the user has explicitly asked to refresh the rules file. Routine session context is already injected via the SessionStart hook (`gnosys recall`); do NOT call this tool after every preference change.", {
+regTool("gnosys_sync", "Get the current user preferences + project conventions formatted as a GNOSYS:START/GNOSYS:END block. By default returns the block as text only (no disk write). Pass commit_to_disk=true to write it into the detected agent rules file (CLAUDE.md, .cursor/rules/gnosys.mdc) — only do this if the user has explicitly asked to refresh the rules file. Routine session context is already injected via the SessionStart hook (`gnosys recall`); do NOT call this tool after every preference change.", {
     projectRoot: projectRootParam,
     commit_to_disk: z
         .boolean()
@@ -2339,7 +2377,7 @@ server.tool("gnosys_sync", "Get the current user preferences + project conventio
     };
 });
 // ─── Tool: gnosys_federated_search ───────────────────────────────────────
-server.tool("gnosys_federated_search", "Search across all scopes (project → user → global) with tier boosting. Results from the current project rank highest. Returns score breakdown showing which boosts were applied.", {
+regTool("gnosys_federated_search", "Search across all scopes (project → user → global) with tier boosting. Results from the current project rank highest. Returns score breakdown showing which boosts were applied.", {
     query: z.string().describe("Search query"),
     limit: z.number().optional().describe("Max results (default: 20)"),
     projectRoot: z.string().optional().describe("Project root directory for context detection"),
@@ -2369,7 +2407,7 @@ server.tool("gnosys_federated_search", "Search across all scopes (project → us
     };
 });
 // ─── Tool: gnosys_detect_ambiguity ──────────────────────────────────────
-server.tool("gnosys_detect_ambiguity", "Check if a query matches memories in multiple projects. Use before write operations to confirm the target project when ambiguity exists.", {
+regTool("gnosys_detect_ambiguity", "Check if a query matches memories in multiple projects. Use before write operations to confirm the target project when ambiguity exists.", {
     query: z.string().describe("Query to check for cross-project ambiguity"),
 }, async ({ query }) => {
     if (!centralDb?.isAvailable()) {
@@ -2388,7 +2426,7 @@ server.tool("gnosys_detect_ambiguity", "Check if a query matches memories in mul
     };
 });
 // ─── Tool: gnosys_briefing ──────────────────────────────────────────────
-server.tool("gnosys_briefing", "Generate a project briefing — a summary of memory state, categories, recent activity, and top tags. Use for dream mode pre-computation or quick project status.", {
+regTool("gnosys_briefing", "Generate a project briefing — a summary of memory state, categories, recent activity, and top tags. Use for dream mode pre-computation or quick project status.", {
     projectId: z.string().optional().describe("Project ID (auto-detects from cwd if omitted)"),
     all: z.boolean().optional().describe("Generate briefings for ALL projects"),
     projectRoot: z.string().optional().describe("Project root for auto-detection"),
@@ -2439,7 +2477,7 @@ server.tool("gnosys_briefing", "Generate a project briefing — a summary of mem
     return { content: [{ type: "text", text }] };
 });
 // ─── Tool: gnosys_portfolio ─────────────────────────────────────────────
-server.tool("gnosys_portfolio", "Portfolio dashboard — shows all registered projects with memory counts, categories, status snapshots, roadmap items, and recent activity. Use for cross-project status overview.", {
+regTool("gnosys_portfolio", "Portfolio dashboard — shows all registered projects with memory counts, categories, status snapshots, roadmap items, and recent activity. Use for cross-project status overview.", {
     format: z.enum(["compact", "full"]).optional().describe("Output format: compact (default) or full markdown"),
 }, async ({ format }) => {
     if (!centralDb?.isAvailable()) {
@@ -2455,7 +2493,7 @@ server.tool("gnosys_portfolio", "Portfolio dashboard — shows all registered pr
     return { content: [{ type: "text", text }] };
 });
 // ─── Remote sync tools (v5.3.0) ─────────────────────────────────────────
-server.tool("gnosys_remote_status", "Check the status of remote sync (multi-machine). Returns pending pushes, pulls, conflicts, and reachability. Agents should surface this to the user when there are pending changes or conflicts.", {}, async () => {
+regTool("gnosys_remote_status", "Check the status of remote sync (multi-machine). Returns pending pushes, pulls, conflicts, and reachability. Agents should surface this to the user when there are pending changes or conflicts.", {}, async () => {
     // Sync operations need explicit local DB access (not auto-routed remote).
     const localDb = GnosysDB.openLocal();
     try {
@@ -2483,7 +2521,7 @@ server.tool("gnosys_remote_status", "Check the status of remote sync (multi-mach
         localDb.close();
     }
 });
-server.tool("gnosys_remote_push", "Push local memory changes to the remote (NAS) database. Uses skip-and-flag for conflicts by default. Call this when the user has approved pushing local changes.", {
+regTool("gnosys_remote_push", "Push local memory changes to the remote (NAS) database. Uses skip-and-flag for conflicts by default. Call this when the user has approved pushing local changes.", {
     newerWins: z.boolean().optional().describe("Auto-resolve conflicts by taking the newer version"),
 }, async ({ newerWins }) => {
     const localDb = GnosysDB.openLocal();
@@ -2507,7 +2545,7 @@ server.tool("gnosys_remote_push", "Push local memory changes to the remote (NAS)
         localDb.close();
     }
 });
-server.tool("gnosys_remote_pull", "Pull remote memory changes to the local database. Uses skip-and-flag for conflicts by default. Call this when the user wants the latest from the remote.", {
+regTool("gnosys_remote_pull", "Pull remote memory changes to the local database. Uses skip-and-flag for conflicts by default. Call this when the user wants the latest from the remote.", {
     newerWins: z.boolean().optional().describe("Auto-resolve conflicts by taking the newer version"),
 }, async ({ newerWins }) => {
     const localDb = GnosysDB.openLocal();
@@ -2531,7 +2569,7 @@ server.tool("gnosys_remote_pull", "Pull remote memory changes to the local datab
         localDb.close();
     }
 });
-server.tool("gnosys_remote_resolve", "Resolve a sync conflict by choosing which version to keep. Use after gnosys_remote_status reveals conflicts. The agent should present the local and remote versions to the user and call this with their choice.", {
+regTool("gnosys_remote_resolve", "Resolve a sync conflict by choosing which version to keep. Use after gnosys_remote_status reveals conflicts. The agent should present the local and remote versions to the user and call this with their choice.", {
     memoryId: z.string().describe("Memory ID with the conflict"),
     choice: z.enum(["local", "remote"]).describe("Which version to keep"),
 }, async ({ memoryId, choice }) => {
@@ -2558,7 +2596,7 @@ server.tool("gnosys_remote_resolve", "Resolve a sync conflict by choosing which
     }
 });
 // ─── Tool: gnosys_update_status ─────────────────────────────────────────
-server.tool("gnosys_update_status", "Get the prompt/template for writing a dashboard-compatible status memory for this project. Returns instructions for creating a landscape memory with the correct heading format so the portfolio dashboard can parse it. Run this, then follow the instructions to analyze and write the status.", {
+regTool("gnosys_update_status", "Get the prompt/template for writing a dashboard-compatible status memory for this project. Returns instructions for creating a landscape memory with the correct heading format so the portfolio dashboard can parse it. Run this, then follow the instructions to analyze and write the status.", {
     projectRoot: z.string().optional().describe("Project root for auto-detection"),
 }, async ({ projectRoot }) => {
     if (!centralDb?.isAvailable()) {
@@ -2576,7 +2614,7 @@ server.tool("gnosys_update_status", "Get the prompt/template for writing a dashb
     return { content: [{ type: "text", text: prompt }] };
 });
 // ─── Tool: gnosys_working_set ───────────────────────────────────────────
-server.tool("gnosys_working_set", "Get the implicit working set — recently modified memories for the current project. These represent the active context and get boosted in federated search.", {
+regTool("gnosys_working_set", "Get the implicit working set — recently modified memories for the current project. These represent the active context and get boosted in federated search.", {
     projectRoot: z.string().optional().describe("Project root for auto-detection"),
     windowHours: z.number().optional().describe("Lookback window in hours (default: 24)"),
 }, async ({ projectRoot, windowHours }) => {
@@ -2594,7 +2632,7 @@ server.tool("gnosys_working_set", "Get the implicit working set — recently mod
     return { content: [{ type: "text", text: formatted }] };
 });
 // ─── Tool: gnosys_ingest_file ────────────────────────────────────────────
-server.tool("gnosys_ingest_file", "Ingest a file (PDF, DOCX, TXT, MD) into Gnosys memory. Extracts text, splits into chunks, and creates atomic memories. Supports LLM-powered structuring or fast structured mode.", {
+regTool("gnosys_ingest_file", "Ingest a file (PDF, DOCX, TXT, MD) into Gnosys memory. Extracts text, splits into chunks, and creates atomic memories. Supports LLM-powered structuring or fast structured mode.", {
     filePath: z.string().describe("Absolute path to the file to ingest"),
     mode: z.enum(["llm", "structured"]).default("llm").optional()
         .describe("Ingestion mode: 'llm' uses AI to structure each chunk, 'structured' uses keyword extraction (faster, no LLM needed)"),
@@ -2644,6 +2682,13 @@ server.tool("gnosys_ingest_file", "Ingest a file (PDF, DOCX, TXT, MD) into Gnosy
                 lines.push(`- Chunk ${e.chunk}: ${e.error}`);
             }
         }
+        if (!dryRun && ctx.centralDb?.isAvailable()) {
+            auditToDb(ctx.centralDb, "ingest", undefined, {
+                source_file: result.attachment.originalName,
+                fileType: result.fileType,
+                count: result.memories.length,
+            }, result.duration);
+        }
         if (dryRun) {
             lines.unshift("(dry run — no files were written)\n");
         }
@@ -2661,7 +2706,7 @@ server.tool("gnosys_ingest_file", "Ingest a file (PDF, DOCX, TXT, MD) into Gnosy
 // ─── MCP Prompts (slash commands) ────────────────────────────────────────
 // These appear as /gnosys-recall, /gnosys-discover, /gnosys-memorize in
 // Cursor, Claude Code, and Codex.
-server.prompt("gnosys-recall", "Inject top Gnosys memories for the current project into context. Use this at the start of any task to load relevant knowledge.", async () => {
+regPrompt("gnosys-recall", "Inject top Gnosys memories for the current project into context. Use this at the start of any task to load relevant knowledge.", async () => {
     if (!centralDb?.isAvailable()) {
         return {
             messages: [
@@ -2706,7 +2751,7 @@ server.prompt("gnosys-recall", "Inject top Gnosys memories for the current proje
         ],
     };
 });
-server.prompt("gnosys-discover", "Search Gnosys memories on a specific topic and inject results into context.", { topic: z.string().describe("Topic or keywords to search for") }, async ({ topic }) => {
+regPrompt("gnosys-discover", "Search Gnosys memories on a specific topic and inject results into context.", { topic: z.string().describe("Topic or keywords to search for") }, async ({ topic }) => {
     if (!centralDb?.isAvailable() || !centralDb?.isMigrated()) {
         return {
             messages: [
@@ -2745,7 +2790,7 @@ server.prompt("gnosys-discover", "Search Gnosys memories on a specific topic and
         ],
     };
 });
-server.prompt("gnosys-memorize", "Analyze the current conversation and save new decisions, findings, and context as Gnosys memories. Checks for duplicates automatically.", async () => {
+regPrompt("gnosys-memorize", "Analyze the current conversation and save new decisions, findings, and context as Gnosys memories. Checks for duplicates automatically.", async () => {
     // Check for last memorized timestamp from preferences
     let lastMemorizedInfo = "This is the first time /gnosys-memorize has been run — analyze all conversation content.";
     if (centralDb?.isAvailable()) {
@@ -2971,6 +3016,38 @@ async function main() {
     // heavy module initialization in the background. Handlers that use the
     // module-level `ingestion` / `hybridSearch` / `askEngine` vars guard
     // against null and either await readiness or surface a clear error.
+    // v5.12: HTTP transport (central-server topology) — opt-in via env, set by
+    // `gnosys serve --transport http`. Each session gets its own McpServer
+    // (registrations replayed); all share the module-global brain/search.
+    if (process.env.GNOSYS_TRANSPORT === "http") {
+        const { startMcpHttpServer } = await import("./lib/mcpHttp.js");
+        const host = process.env.GNOSYS_HTTP_HOST || "127.0.0.1";
+        const port = parseInt(process.env.GNOSYS_HTTP_PORT || "7777", 10);
+        const authToken = process.env.GNOSYS_SERVE_TOKEN || undefined;
+        try {
+            await startMcpHttpServer({
+                host,
+                port,
+                authToken,
+                log: (m) => console.error(`Gnosys MCP[http]: ${m}`),
+                makeServer: () => {
+                    const s = new McpServer({ name: "gnosys", version: "2.0.0" });
+                    registerCapabilities(s);
+                    return s;
+                },
+            });
+        }
+        catch (err) {
+            console.error(`Gnosys MCP: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+        console.error(`Gnosys MCP: HTTP transport ready on http://${host}:${port}/mcp${authToken ? " (bearer auth required)" : ""}`);
+        void initHeavyDeps().catch((err) => {
+            console.error(`Gnosys MCP: heavy-init failed — ${err instanceof Error ? err.message : err}`);
+        });
+        return;
+    }
+    registerCapabilities(server);
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error("Gnosys MCP: handshake ready (heavy modules still loading)");
@@ -3014,8 +3091,10 @@ async function main() {
         // Notification handler setup failed — non-critical
     }
 }
-main().catch((err) => {
-    console.error("Fatal error:", err);
-    process.exit(1);
-});
-//# sourceMappingURL=index.js.map
+const invokedAsScript = !!process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1]);
+if (invokedAsScript) {
+    main().catch((err) => {
+        console.error("Fatal error:", err);
+        process.exit(1);
+    });
+}