oh-my-second-brain 0.2.0 → 0.6.1

package/dist/mcp/server.js

@@ -2,24 +2,27 @@ import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, ListResourceTemplatesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
-import { parseNote } from "../conventions/frontmatter.js";
-import { validateFrontmatter } from "../conventions/validate.js";
-import { lintVault } from "../engine/conventions/vault-lint.js";
-import { safeVaultNotePath, writeNote, } from "../capture/safe.js";
-import { buildGraphCache, graphCacheStatus, graphCachePath, lazyLoadNoteBody, } from "../graph/cache.js";
-import { readBundledPackageVersion } from "../core/runtime/assets.js";
-import { resolveActiveOntology } from "../ontology/active.js";
-import { resolveConcept } from "../core/ontology/resolver.js";
-import { retrieveMorningContext } from "../retrieve/morning.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { parseNote } from "../kernel/conventions/frontmatter.js";
+import { validateFrontmatter } from "../kernel/conventions/validate.js";
+import { lintVault } from "../kernel/engine/conventions/vault-lint.js";
+import { safeVaultNotePath, writeNote, } from "../kernel/capture/safe.js";
+import { graphCacheStatus, lazyLoadNoteBody, } from "../kernel/graph/cache.js";
+import { readBundledPackageVersion } from "../kernel/runtime/assets.js";
+import { resolveActiveOntology } from "../kernel/ontology/active.js";
+import { resolveConcept } from "../kernel/ontology/resolver.js";
+import { retrieveMorningContext } from "../kernel/search/morning.js";
+import { repairDoctor } from "../kernel/doctor/service.js";
 import { makeEngineMorningBackend } from "./engine-morning-backend.js";
-import { handleSemanticTool, isEngineSemanticOp, isEngineDocumentOp, isModelOptionalSemanticQueryOp, semanticMcpTools, semanticOptionsFromArgs, retrieveContextSemanticInputProperties, } from "./semantic-retrieve.js";
-import { assembleCoreSemanticEngine, assembleGraphOnlyEngine } from "../engine/assemble.js";
-import { assembleFullSemanticEngine, embeddingConfigPresent } from "./semantic-engine.js";
+import { handleSemanticTool, isEngineSemanticOp, isEngineDocumentOp, isModelOptionalSemanticQueryOp, semanticOptionsFromArgs, } from "../kernel/semantic/semantic-retrieve.js";
+import { semanticQueryOptionsFromArgs } from "../kernel/semantic/semantic-retrieve-args.js";
+import { assembleEphemeralCoreSemanticEngine, assembleCoreSemanticEngineReadOnly, assembleCoreSemanticEngine, assembleEngineReadOnly, assembleGraphOnlyEngine, } from "../kernel/engine/assemble.js";
+import { assembleFullSemanticEngine, embeddingConfigPresent, } from "../kernel/semantic/semantic-engine.js";
 import { applyLinksForNote, linkApplyPayload, suggestLinksForNote } from "./link-tools.js";
+import { EngineSearchBackend, requiresEmbeddings } from "../kernel/searchbackend/engine-search-backend.js";
 import { buildServerInstructions, cachedUpdateNotice, scheduleUpdateNoticeRefresh, } from "./update-notice.js";
 const SERVER_VERSION = readBundledPackageVersion();
-export const BASE_SERVER_INSTRUCTIONS = "Oh My Second Brain exposes ontology/status/cache/retrieval tools and the write tool. write is gated by a verified vault target (a vault inferred from the current directory is refused), vault confinement, and contract validation.";
+export const BASE_SERVER_INSTRUCTIONS = "Oh My Second Brain exposes write, search, link, status, and doctor tools. oms_write and doctor repair operations are gated by a verified vault target (a vault inferred from the current directory is refused); oms_write also enforces vault confinement and contract validation.";
 function jsonText(value) {
     return {
         content: [
@@ -41,6 +44,11 @@ function errorText(message) {
         ],
     };
 }
+class SemanticIndexUnavailableError extends Error {
+    constructor() {
+        super("The semantic index has not been built yet. Run `oms semantic sync` to build it.");
+    }
+}
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -66,246 +74,89 @@ function conceptSummary(concept) {
         })),
     };
 }
-export const omsMcpTools = [
-    {
-        name: "oms_graph_status",
-        title: "Oh My Second Brain graph/status",
-        description: "Read-only status for the active Oh My Second Brain ontology, graph/search cache phase, and gated write-tool posture.",
-        inputSchema: {
-            type: "object",
-            properties: {},
-        },
-        annotations: {
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-    },
-    {
-        name: "oms_graph_build",
-        title: "Oh My Second Brain graph build",
-        description: "Build the derived graph/search cache from markdown, frontmatter, folders, and wikilinks.",
-        inputSchema: {
-            type: "object",
-            properties: {},
-        },
-        annotations: {
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-    },
-    {
-        name: "oms_list_concepts",
-        title: "Oh My Second Brain list concepts",
-        description: "Read the active ontology concepts, frontmatter axes, folder bindings, and retrieval views.",
-        inputSchema: {
-            type: "object",
-            properties: {},
-        },
-        annotations: {
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-    },
-    {
-        name: "oms_retrieve_by_axis",
-        title: "Oh My Second Brain retrieve by axis",
-        description: "Axis-first retrieval over the derived cache; optional lexical query only ranks inside the narrowed candidate set.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                concept: { type: "string" },
-                folder: { type: "string" },
-                property: { type: "string" },
-                value: { type: "string" },
-                wikilink: { type: "string" },
-                query: { type: "string" },
-                limit: { type: "number" },
-            },
-        },
-        annotations: {
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-    },
-    {
-        name: "oms_retrieve_context",
-        title: "Oh My Second Brain retrieve context",
-        description: "Live local graph retrieval with axis seeds, frontmatter/wikilink neighbors, optional OMS semantic candidates, and no warm-cache requirement.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                concept: { type: "string" },
-                folder: { type: "string" },
-                property: { type: "string" },
-                value: { type: "string" },
-                wikilink: { type: "string" },
-                query: { type: "string" },
-                limit: { type: "number" },
-                maxNeighbors: { type: "number" },
-                useCache: { type: "boolean" },
-                ...retrieveContextSemanticInputProperties,
-            },
-        },
-        annotations: {
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-    },
-    ...semanticMcpTools,
-    {
-        name: "oms_lazy_load_note",
-        title: "Oh My Second Brain lazy-load note body",
-        description: "Load a selected note body only after axis/search narrowing has selected the note.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                notePath: {
-                    type: "string",
-                    description: "Vault-relative markdown note path.",
-                },
-            },
-            required: ["notePath"],
-        },
-        annotations: {
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-    },
-    {
-        name: "oms_validate_contract",
-        title: "Oh My Second Brain validate contract",
-        description: "Read one vault note and validate its frontmatter against the active folder/concept contract.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                notePath: {
-                    type: "string",
-                    description: "Vault-relative markdown note path, for example references/book.md.",
-                },
-            },
-            required: ["notePath"],
-        },
-        annotations: {
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-    },
-    {
-        name: "oms_vault_audit",
-        title: "Oh My Second Brain vault audit",
-        description: "Scan vault notes against the active ontology and return a structured violation report. Read-only; the CLI counterpart is `oms audit`.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                folder: {
-                    type: "string",
-                    description: "Restrict the scan to one top-level vault folder, for example \"references\".",
-                },
-            },
-        },
-        annotations: {
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-    },
-    {
-        name: "oms_link_suggest",
-        title: "Oh My Second Brain link suggest",
-        description: "Propose [[wikilink]] insertions for one note against the vault's term notes. Read-only: returns ranked candidates plus the baseContentHash oms_link_apply requires.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                notePath: {
-                    type: "string",
-                    description: "Vault-relative markdown note path to linkify, for example notes/sage.md.",
-                },
-                folder: {
-                    type: "string",
-                    description: "Restrict the term-note candidate universe to one top-level vault folder.",
-                },
-            },
-            required: ["notePath"],
-        },
-        annotations: {
-            readOnlyHint: true,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
+const string = { type: "string" };
+const number = { type: "number" };
+const boolean = { type: "boolean" };
+const stringArray = { type: "array", items: string };
+const axisScalar = { anyOf: [string, number, boolean] };
+const axisValue = { anyOf: [axisScalar, { type: "array", items: axisScalar }] };
+const fieldPredicate = {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+        contains: axisValue,
+        containsAll: { type: "array", items: axisScalar },
+        in: { type: "array", items: axisScalar },
+        between: { type: "array", items: axisScalar, minItems: 2, maxItems: 2 },
+        gte: axisScalar,
+        gt: axisScalar,
+        lte: axisScalar,
+        lt: axisScalar,
+        from: axisScalar,
+        to: axisScalar,
     },
-    {
-        name: "oms_link_apply",
-        title: "Oh My Second Brain link apply",
-        description: "Splice accepted oms_link_suggest candidates into a note and persist through the write kernel. Refuses without writing when baseContentHash no longer matches the note.",
-        inputSchema: {
+};
+const queryAxes = {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+        folder: axisValue,
+        field: {
             type: "object",
-            properties: {
-                notePath: {
-                    type: "string",
-                    description: "Vault-relative markdown note path returned by oms_link_suggest.",
-                },
-                baseContentHash: {
-                    type: "string",
-                    description: "The baseContentHash from the oms_link_suggest call the candidates came from.",
-                },
-                candidateIds: {
-                    type: "array",
-                    items: { type: "string" },
-                    description: "Ids of the accepted candidates from that same oms_link_suggest call.",
-                },
-                folder: {
-                    type: "string",
-                    description: "Same candidate-universe folder scope used for the suggest call.",
-                },
-            },
-            required: ["notePath", "baseContentHash", "candidateIds"],
-        },
-        annotations: {
-            readOnlyHint: false,
-            destructiveHint: true,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-    },
-    {
-        name: "write",
-        title: "Oh My Second Brain write",
-        description: "Write a vault note through the kernel-owned .oms contract. Modes: create, append, update. Returns ask, inbox, written, or rejected.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                mode: { type: "string", enum: ["create", "append", "update"] },
-                notePath: { type: "string" },
-                concept: { type: "string" },
-                folder: { type: "string" },
-                filename: { type: "string" },
-                frontmatter: { type: "object" },
-                body: { type: "string" },
-            },
-        },
-        annotations: {
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: false,
+            additionalProperties: { anyOf: [axisValue, fieldPredicate] },
         },
+        link: axisValue,
     },
+};
+const searchProperties = {
+    query: string, searches: { type: "array", maxItems: 10, items: { type: "object", properties: { type: { ...string, enum: ["lex", "vec", "hyde"] }, query: string }, required: ["type", "query"] } },
+    collection: string, collections: stringArray, mode: { ...string, enum: ["query", "search", "vsearch"] }, limit: { ...number, minimum: 0, default: 10 }, candidateLimit: { ...number, minimum: 1 }, rerank: { ...boolean, default: false }, minScore: { ...number, default: 0 }, cursor: string, axes: queryAxes, intent: string, lex: string, vec: string, hyde: string, index: string,
+    target: string, targets: stringArray, fromLine: number, lineCount: number, lineLimit: number, maxBytes: number, lineNumbers: boolean, fullPath: boolean,
+};
+const contextProperties = { concept: string, folder: string, property: string, value: string, wikilink: string, query: string, limit: number, maxNeighbors: number, useCache: boolean,
+    semanticEnabled: boolean, semanticCollection: string, semanticLimit: number, semanticScope: { ...string, enum: ["global", "graph"] }, semanticMode: searchProperties.mode, semanticIntent: string, semanticSearches: searchProperties.searches, semanticLex: string, semanticVec: string, semanticHyde: string, semanticMinScore: number, semanticAll: boolean, semanticFormat: { ...string, enum: ["json", "files"] }, semanticFull: boolean, semanticLineNumbers: boolean, semanticFullPath: boolean, semanticIndex: string, semanticChunkStrategy: string, semanticCandidateLimit: number, semanticNoRerank: boolean, semanticHydrate: { ...string, enum: ["none", "top", "all", "targets"] }, semanticHydrateTargets: stringArray, semanticHydrateLineLimit: number, semanticHydrateMaxBytes: number, semanticHydrateFromLine: number, semanticHydrateLineCount: number };
+// `folder` + `filename` is a supported addressing form that writeNote still
+// accepts. With `additionalProperties: false` a strict schema is only as
+// complete as its property list, so omitting them silently removed a real
+// capability from every schema-driven client while raw SDK calls kept working.
+const writeProperties = {
+    notePath: string,
+    folder: string,
+    filename: string,
+    concept: string,
+    frontmatter: { type: "object" },
+    body: string,
+};
+const operations = {
+    oms_write: [
+        { op: "create", name: "write", properties: writeProperties },
+        { op: "append", name: "write", properties: writeProperties },
+        { op: "update", name: "write", properties: writeProperties },
+    ],
+    oms_search: [{ op: "context", name: "oms_retrieve_context", properties: contextProperties }, { op: "lazy-load", name: "oms_lazy_load_note", properties: { notePath: string }, required: ["notePath"] }, { op: "concepts", name: "oms_list_concepts" }, { op: "query", name: "oms_semantic_query", properties: searchProperties }, { op: "collections", name: "oms_semantic_collections", properties: { index: string } }, { op: "contexts", name: "oms_semantic_contexts", properties: { index: string } }, { op: "status", name: "oms_semantic_status", properties: { index: string } }, { op: "get-document", name: "oms_get_document", properties: searchProperties, required: ["target"] }, { op: "multi-get-documents", name: "oms_multi_get_documents", properties: searchProperties }],
+    oms_link: [{ op: "suggest", name: "oms_link_suggest", properties: { notePath: string, folder: string }, required: ["notePath"] }, { op: "apply", name: "oms_link_apply", properties: { notePath: string, folder: string, baseContentHash: string, candidateIds: stringArray }, required: ["notePath", "baseContentHash", "candidateIds"] }],
+    oms_status: [{ name: "oms_graph_status", direct: true }],
+    oms_doctor: [{ op: "audit", name: "oms_vault_audit", properties: { folder: string } }, { op: "validate", name: "oms_validate_contract", properties: { notePath: string }, required: ["notePath"] }, { op: "build-graph", name: "oms_graph_build" }, { op: "cleanup", name: "oms_semantic_cleanup", properties: { collection: string, index: string } }, { op: "sync-embeddings", name: "oms_sync_embeddings", properties: { collection: string, ensureCollection: boolean, update: boolean, embed: boolean, force: boolean, pull: boolean, index: string, chunkStrategy: string, maxDocsPerBatch: number, maxBatchMb: number } }],
+};
+function operationSchema(tool) {
+    const toolOperations = operations[tool];
+    if (!toolOperations)
+        throw new Error(`Missing MCP operation definition for ${tool}.`);
+    if (toolOperations.length === 1 && toolOperations[0]?.direct) {
+        const { properties = {}, required = [] } = toolOperations[0];
+        return { type: "object", additionalProperties: false, properties, required: [...required] };
+    }
+    return { type: "object", oneOf: toolOperations.map(({ op, properties = {}, required = [] }) => ({ additionalProperties: false, properties: { op: { ...string, const: op }, ...properties }, required: ["op", ...required] })) };
+}
+function resolveOperation(tool, op) {
+    return operations[tool]?.find((operation) => operation.direct || operation.op === op)?.name;
+}
+export const omsMcpTools = [
+    { name: "oms_write", title: "Oh My Second Brain write", description: "Write a vault note through the kernel-owned .oms contract.", inputSchema: operationSchema("oms_write"), annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false } },
+    { name: "oms_search", title: "Oh My Second Brain search", description: "Retrieve vault context, semantic search, ontology, and selected documents. `op` selects the operation.", inputSchema: operationSchema("oms_search"), annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: false } },
+    { name: "oms_link", title: "Oh My Second Brain link", description: "Suggest or apply wikilinks; `op` selects the operation.", inputSchema: operationSchema("oms_link"), annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false } },
+    { name: "oms_status", title: "Oh My Second Brain status", description: "Read-only health and statistics for the active vault.", inputSchema: operationSchema("oms_status"), annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false } },
+    { name: "oms_doctor", title: "Oh My Second Brain doctor", description: "Diagnose or repair the vault; `op` selects the operation.", inputSchema: operationSchema("oms_doctor"), annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false } },
 ];
 export function createOMSMcpServer(opts) {
     const vault = path.resolve(opts.vault);
@@ -315,17 +166,12 @@ export function createOMSMcpServer(opts) {
     // graph cache status scan the vault off the filesystem and need no model.
     // No model load, no SQLite store, no watcher: side-effect-free per boot (R2).
     const engine = assembleGraphOnlyEngine({ vault });
-    // Native engine — semantic layer (lazy): assembled on the FIRST semantic op,
-    // not at boot, so boot stays stateless (R2). The vec-capable engine opens the
-    // engine SQLite store on construction and loads the embedding model on first
-    // embed(). Embedding selection is canonical and explicit: OMS_EMBEDDING_PROVIDER
-    // (e.g. gguf | upstage) + OMS_EMBEDDING_MODEL (path or model id). Absent either,
-    // assembleFullSemanticEngine throws a loud, actionable error (ADR-007: no
-    // hash/fake fallback, no auto-detect) that surfaces via the dispatch catch.
+    // Creating semantic engines are shared by all non-search tools, including
+    // doctor repairs which must initialize a missing store.
     let semanticEngine = null;
     const getSemanticEngine = () => {
         if (semanticEngine === null) {
-            semanticEngine = assembleFullSemanticEngine(vault);
+            semanticEngine = assembleFullSemanticEngine(vault, opts.reranker);
         }
         return semanticEngine;
     };
@@ -335,10 +181,47 @@ export function createOMSMcpServer(opts) {
     let coreSemanticEngine = null;
     const getCoreSemanticEngine = () => {
         if (coreSemanticEngine === null) {
-            coreSemanticEngine = assembleCoreSemanticEngine({ vault });
+            coreSemanticEngine = assembleCoreSemanticEngine({ vault, reranker: opts.reranker });
         }
         return coreSemanticEngine;
     };
+    // Search owns independent read-only slots so it cannot poison doctor repair.
+    let readOnlySemanticEngine;
+    const getReadOnlySemanticEngine = () => {
+        if (readOnlySemanticEngine === undefined) {
+            readOnlySemanticEngine = assembleEngineReadOnly({
+                vault,
+                embeddingProvider: process.env["OMS_EMBEDDING_PROVIDER"],
+                embeddingModel: process.env["OMS_EMBEDDING_MODEL"],
+                reranker: opts.reranker,
+            });
+        }
+        return readOnlySemanticEngine;
+    };
+    let readOnlyCoreSemanticEngine;
+    const getReadOnlyCoreSemanticEngine = () => {
+        if (readOnlyCoreSemanticEngine === undefined) {
+            readOnlyCoreSemanticEngine = assembleCoreSemanticEngineReadOnly({ vault, reranker: opts.reranker });
+        }
+        return readOnlyCoreSemanticEngine;
+    };
+    let ephemeralCoreSemanticEngine = null;
+    let ephemeralCoreSemanticEnginePromise = null;
+    const getEphemeralCoreSemanticEngine = async () => {
+        if (ephemeralCoreSemanticEngine !== null)
+            return ephemeralCoreSemanticEngine;
+        if (ephemeralCoreSemanticEnginePromise === null) {
+            ephemeralCoreSemanticEnginePromise = (async () => {
+                const assembled = assembleEphemeralCoreSemanticEngine({ vault, reranker: opts.reranker });
+                ephemeralCoreSemanticEngine = assembled;
+                return assembled;
+            })().catch((error) => {
+                ephemeralCoreSemanticEnginePromise = null;
+                throw error;
+            });
+        }
+        return ephemeralCoreSemanticEnginePromise;
+    };
     // A real embedding provider is configured iff the canonical pair is set
     // (ADR-007). The engine's model-OPTIONAL surface (document reads,
     // retrieve_context's semantic leg, ReadResource) keys off this to decide
@@ -355,7 +238,51 @@ export function createOMSMcpServer(opts) {
     // missing auth, store-open failure) must surface its error loudly rather than
     // silently masquerade as a model-less host (ADR-007). The core fallback is
     // strictly for the absent-config case.
-    const resolveDocumentAdapter = () => hasEmbeddingModel() ? getSemanticEngine().adapter : getCoreSemanticEngine().adapter;
+    const resolveCreatingDocumentAdapter = () => hasEmbeddingModel() ? getSemanticEngine().adapter : getCoreSemanticEngine().adapter;
+    const resolveReadOnlyDocumentAdapter = () => hasEmbeddingModel()
+        ? getReadOnlySemanticEngine()?.adapter ?? engine.adapter
+        : getReadOnlyCoreSemanticEngine()?.adapter ?? engine.adapter;
+    const resolveDocumentAdapter = (publicName) => {
+        if (publicName === "oms_search")
+            return resolveReadOnlyDocumentAdapter();
+        return resolveCreatingDocumentAdapter();
+    };
+    const resolveReadOnlyIndexAdapter = () => {
+        const adapter = hasEmbeddingModel()
+            ? getReadOnlySemanticEngine()?.adapter
+            : getReadOnlyCoreSemanticEngine()?.adapter;
+        if (adapter === undefined || adapter === null)
+            throw new SemanticIndexUnavailableError();
+        return adapter;
+    };
+    const resolveReadOnlyLexicalAdapter = async () => {
+        const adapter = hasEmbeddingModel()
+            ? getReadOnlySemanticEngine()?.adapter
+            : getReadOnlyCoreSemanticEngine()?.adapter;
+        return adapter ?? (await getEphemeralCoreSemanticEngine()).adapter;
+    };
+    const hasExplicitEmbeddingIntent = (args) => requiresEmbeddings({
+        mode: args?.["mode"] === "vsearch" ? "vsearch" : undefined,
+        vec: stringArg(args, "vec"),
+        hyde: stringArg(args, "hyde"),
+        searches: Array.isArray(args?.["searches"])
+            ? args["searches"].flatMap((search) => isRecord(search) &&
+                (search["type"] === "lex" || search["type"] === "vec" || search["type"] === "hyde") &&
+                typeof search["query"] === "string"
+                ? [{ type: search["type"], query: search["query"] }]
+                : [])
+            : undefined,
+    });
+    const searchBackend = new EngineSearchBackend((requiresEmbeddings) => requiresEmbeddings
+        ? (() => {
+            // Validate ADR-007 configuration before probing the read-only store:
+            // vector intent is actionable only after its required provider/model
+            // pair is present, regardless of whether an index exists yet.
+            if (!hasEmbeddingModel())
+                return getSemanticEngine().adapter;
+            return resolveReadOnlyIndexAdapter();
+        })()
+        : resolveReadOnlyIndexAdapter(), vault);
     const server = new Server({ name: "oms", version: SERVER_VERSION }, {
         capabilities: { tools: {}, resources: {} },
         // Cache read only: construction must never touch the network. The
@@ -370,43 +297,35 @@ export function createOMSMcpServer(opts) {
         if (coreSemanticEngine !== null) {
             void coreSemanticEngine.dispose().catch(() => undefined);
         }
+        if (readOnlySemanticEngine !== null && readOnlySemanticEngine !== undefined) {
+            void readOnlySemanticEngine.dispose().catch(() => undefined);
+        }
+        if (readOnlyCoreSemanticEngine !== null && readOnlyCoreSemanticEngine !== undefined) {
+            void readOnlyCoreSemanticEngine.dispose().catch(() => undefined);
+        }
+        if (ephemeralCoreSemanticEngine !== null) {
+            void ephemeralCoreSemanticEngine.dispose().catch(() => undefined);
+        }
     };
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools: omsMcpTools,
     }));
-    server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => ({
-        resourceTemplates: [
-            {
-                uriTemplate: "qmd://{path}",
-                name: "QMD-compatible OMS semantic document",
-                description: "Read a native OMS semantic-index document by qmd:// vault-relative path.",
-                mimeType: "text/markdown",
-            },
-        ],
-    }));
-    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
-        const uri = request.params.uri;
-        // Resource reads hydrate on the SAME backend the semantic ops use: the engine
-        // (file-based, qmd:// / oms:// scheme aware), vec-capable when a model is
-        // configured and core (lex + file reads) otherwise — so a retrieve_context
-        // docid resolves through the URI surface regardless of which backend produced it.
-        const result = await resolveDocumentAdapter().getDocument({ vault, target: uri });
-        if (!result.available || !result.documents[0]) {
-            throw new Error(!result.available && result.reason ? result.reason : "OMS semantic resource not found.");
-        }
-        return {
-            contents: [
-                {
-                    uri,
-                    mimeType: "text/markdown",
-                    text: result.documents[0].content,
-                },
-            ],
-        };
-    });
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
-        const args = isRecord(request.params.arguments) ? request.params.arguments : undefined;
-        if (request.params.name === "oms_graph_status") {
+        let args = isRecord(request.params.arguments) ? request.params.arguments : undefined;
+        const publicName = request.params.name;
+        const op = publicName === "oms_write" ? stringArg(args, "op") ?? "create" : stringArg(args, "op");
+        const name = resolveOperation(publicName, op);
+        if (!name)
+            return errorText(`Unknown operation "${op ?? "(missing)"}" for ${publicName}.`);
+        if (publicName === "oms_write")
+            args = { ...args, mode: op };
+        if (publicName === "oms_search" && op === "query") {
+            const searches = args?.["searches"];
+            if (typeof args?.["query"] === "string" && Array.isArray(searches)) {
+                return errorText('Provide exactly one of "query" or "searches" for query.');
+            }
+        }
+        if (name === "oms_graph_status") {
             // The src/graph derived-cache ledger (M3 5-state staleness) is the source
             // of truth for retrieve_context's optional warm cache and stays intact.
             // engineGraph is additive: it surfaces the native engine's axis cache that
@@ -429,8 +348,8 @@ export function createOMSMcpServer(opts) {
                     derivedState: cacheStatus,
                     engineGraph,
                     writeTools: source === "cwd"
-                        ? "write-disabled-target-unverified"
-                        : "write-gated-by-verified-target-and-contract",
+                        ? "oms_write-disabled-target-unverified"
+                        : "oms_write-gated-by-verified-target-and-contract",
                     readTools: omsMcpTools.map((tool) => tool.name),
                 });
             }
@@ -453,27 +372,41 @@ export function createOMSMcpServer(opts) {
                         },
                     },
                     engineGraph,
-                    writeTools: "disabled-invalid-ontology",
+                    writeTools: "oms_write-disabled-invalid-ontology",
                     readTools: ["oms_graph_status"],
                 });
             }
         }
         try {
-            if (request.params.name === "oms_graph_build") {
-                const { ontology, source } = await resolveActiveOntology(vault);
-                const cache = await buildGraphCache({ vault, ontology, write: true });
-                return jsonText({
+            if (name === "oms_graph_build" || name === "oms_semantic_cleanup" || name === "oms_sync_embeddings") {
+                const operation = name === "oms_graph_build" ? "build-graph" : name === "oms_semantic_cleanup" ? "semantic-cleanup" : "sync-embeddings";
+                // A FACTORY, not a value. JavaScript evaluates an argument expression
+                // before entering the callee, so passing a constructed adapter here would
+                // open - and therefore create - `<vault>/.oms/engine-store.sqlite` before
+                // repairDoctor got the chance to run admission. On an invalid global
+                // target that means mutating a directory we are about to reject, which
+                // breaks the verified-target contract's requirement that admission
+                // precede ANY disk mutation. The kernel calls this only after admitting.
+                //
+                // Deliberately NOT re-checking admission here: two policy paths is how
+                // the check drifts. One authoritative decision, deferred dependency.
+                const resolveRepairAdapter = operation === "build-graph"
+                    ? undefined
+                    : () => publicName === "oms_search"
+                        ? resolveReadOnlyDocumentAdapter()
+                        : operation === "semantic-cleanup" || (operation === "sync-embeddings" && args?.["embed"] === false)
+                            ? resolveCreatingDocumentAdapter()
+                            : getSemanticEngine().adapter;
+                const repair = await repairDoctor({
+                    operation,
                     vault,
-                    ontologySource: source,
-                    cachePath: graphCachePath(vault),
-                    generatedAt: cache.generatedAt,
-                    notes: cache.notes.length,
-                    edges: cache.edges.length,
-                    searchDocuments: cache.search.length,
-                    sourceOfTruth: cache.sourceOfTruth,
+                    source,
+                    args,
+                    resolveAdapter: resolveRepairAdapter,
                 });
+                return repair.kind === "error" ? errorText(repair.message) : jsonText(repair.value);
             }
-            if (request.params.name === "oms_list_concepts") {
+            if (name === "oms_list_concepts") {
                 const { ontology, source } = await resolveActiveOntology(vault);
                 return jsonText({
                     vault,
@@ -482,7 +415,7 @@ export function createOMSMcpServer(opts) {
                     concepts: Array.from(ontology.concepts.values()).map(conceptSummary),
                 });
             }
-            if (request.params.name === "oms_retrieve_by_axis") {
+            if (name === "oms_retrieve_by_axis") {
                 // Engine-owned (graph-only swap): axis-first retrieval over the native
                 // node index, built lazily off the filesystem — no embedding model needed.
                 const limitValue = args?.["limit"];
@@ -504,13 +437,24 @@ export function createOMSMcpServer(opts) {
                     ...result,
                 });
             }
-            if (request.params.name === "oms_retrieve_context") {
+            if (name === "oms_retrieve_context") {
                 // Graph + semantic fusion. The graph leg stays on the src/graph warm cache;
                 // the semantic leg routes to the native engine: vec-capable when a model is
                 // configured (parity ranking, real-path docids) and core (lex; vec/HyDE fail
                 // fast) otherwise. get/multi_get and ReadResource make the SAME choice, so a
                 // docid emitted here always hydrates on the backend that produced it.
-                const semanticBackend = makeEngineMorningBackend(resolveDocumentAdapter(), vault);
+                const semantic = semanticOptionsFromArgs(args);
+                let contextAdapter = engine.adapter;
+                if (semantic?.enabled !== false) {
+                    try {
+                        contextAdapter = resolveDocumentAdapter(publicName);
+                    }
+                    catch (error) {
+                        if (!(error instanceof SemanticIndexUnavailableError))
+                            throw error;
+                    }
+                }
+                const semanticBackend = makeEngineMorningBackend(contextAdapter, vault);
                 const { ontology, source } = await resolveActiveOntology(vault);
                 const limitValue = args?.["limit"];
                 const maxNeighborsValue = args?.["maxNeighbors"];
@@ -527,7 +471,7 @@ export function createOMSMcpServer(opts) {
                     limit: typeof limitValue === "number" ? limitValue : undefined,
                     maxNeighbors: typeof maxNeighborsValue === "number" ? maxNeighborsValue : undefined,
                     useCache: typeof useCacheValue === "boolean" ? useCacheValue : undefined,
-                    semantic: semanticOptionsFromArgs(args),
+                    semantic,
                 }, semanticBackend);
                 return jsonText({
                     vault,
@@ -543,23 +487,112 @@ export function createOMSMcpServer(opts) {
             //     engine when a model is configured, else the core engine. Lex is a real
             //     model-free BM25/FTS feature, not an ADR-007 fake vector fallback.
             // Every other tool never touches the engine here.
-            if (isEngineSemanticOp(request.params.name) || isEngineDocumentOp(request.params.name)) {
-                const semanticAdapter = isEngineSemanticOp(request.params.name) && !isModelOptionalSemanticQueryOp(request.params.name, args, vault)
-                    ? getSemanticEngine().adapter
-                    : resolveDocumentAdapter();
-                const semanticToolResult = await handleSemanticTool(request.params.name, args, vault, semanticAdapter);
+            if (isEngineSemanticOp(name) || isEngineDocumentOp(name)) {
+                if (name === "oms_semantic_query") {
+                    const hasQueryAxes = isRecord(args?.["axes"]) ||
+                        args?.["folder"] !== undefined ||
+                        args?.["field"] !== undefined ||
+                        args?.["link"] !== undefined;
+                    if (hasQueryAxes) {
+                        const axisAdapter = hasExplicitEmbeddingIntent(args)
+                            ? resolveReadOnlyIndexAdapter()
+                            : await resolveReadOnlyLexicalAdapter();
+                        const axisOptions = semanticQueryOptionsFromArgs(vault, args);
+                        const axisResult = await new EngineSearchBackend(axisAdapter, vault).search({
+                            ...axisOptions,
+                            query: axisOptions.lex !== undefined ||
+                                axisOptions.vec !== undefined ||
+                                axisOptions.hyde !== undefined
+                                ? undefined
+                                : axisOptions.query ?? "",
+                        });
+                        return jsonText(axisResult);
+                    }
+                    const query = stringArg(args, "query");
+                    const vec = stringArg(args, "vec");
+                    const hyde = stringArg(args, "hyde");
+                    const queryOptions = semanticQueryOptionsFromArgs(vault, args);
+                    const noPersistentReadOnlyIndex = hasEmbeddingModel()
+                        ? getReadOnlySemanticEngine() === null
+                        : getReadOnlyCoreSemanticEngine() === null;
+                    const hasExplicitLexicalIntent = query !== undefined ||
+                        stringArg(args, "lex") !== undefined ||
+                        (queryOptions.searches ?? []).some((search) => search.type === "lex");
+                    const isOverviewRequest = query === undefined &&
+                        (queryOptions.searches ?? []).length === 0 &&
+                        queryOptions.lex === undefined &&
+                        queryOptions.vec === undefined &&
+                        queryOptions.hyde === undefined &&
+                        queryOptions.axes === undefined;
+                    if (!hasExplicitEmbeddingIntent(args) && noPersistentReadOnlyIndex && (hasExplicitLexicalIntent || isOverviewRequest)) {
+                        // Reuse the SearchBackend seam for model-free fallback as well. This
+                        // keeps overview, cursor, axes, and collection aggregation semantics
+                        // identical to the indexed path; its normalized default is lexical,
+                        // so no vector intent is fabricated when the model is absent.
+                        const fallbackBackend = new EngineSearchBackend(await resolveReadOnlyLexicalAdapter(), vault);
+                        const result = await fallbackBackend.search({
+                            ...queryOptions,
+                            // `lex` is an explicit lexical representation. Do not send it
+                            // alongside `query`, which would make the two equivalent forms
+                            // look contradictory to the SearchBackend normalizer.
+                            query: queryOptions.lex === undefined ? query ?? "" : undefined,
+                        });
+                        return jsonText(result);
+                    }
+                    const requestOptions = {
+                        ...queryOptions,
+                        collections: queryOptions.collections,
+                    };
+                    const result = await searchBackend.search({
+                        ...requestOptions,
+                        // `query` is the default lexical representation. An explicit vector
+                        // or HyDE shorthand selects its own representation instead; only
+                        // `query` plus typed `searches` is contradictory.
+                        query: vec !== undefined || hyde !== undefined || queryOptions.lex !== undefined
+                            ? undefined
+                            : query ?? "",
+                        searches: queryOptions.searches,
+                    });
+                    return jsonText(result);
+                }
+                const useEphemeralLexicalFallback = name === "oms_semantic_query" &&
+                    publicName === "oms_search" &&
+                    !hasExplicitEmbeddingIntent(args) &&
+                    (hasEmbeddingModel()
+                        ? getReadOnlySemanticEngine() === null
+                        : getReadOnlyCoreSemanticEngine() === null);
+                const semanticAdapter = useEphemeralLexicalFallback
+                    ? await resolveReadOnlyLexicalAdapter()
+                    :
+                        isEngineSemanticOp(name) &&
+                            name !== "oms_semantic_cleanup" &&
+                            !(name === "oms_sync_embeddings" && args?.["embed"] === false) &&
+                            !isModelOptionalSemanticQueryOp(name, args, vault)
+                            ? publicName === "oms_search"
+                                ? resolveReadOnlyIndexAdapter()
+                                : getSemanticEngine().adapter
+                            : isEngineDocumentOp(name)
+                                ? resolveDocumentAdapter(publicName)
+                                : publicName === "oms_search"
+                                    ? resolveReadOnlyIndexAdapter()
+                                    : resolveDocumentAdapter(publicName);
+                const semanticToolResult = await handleSemanticTool(name, useEphemeralLexicalFallback
+                    ? { ...args, lex: stringArg(args, "query") }
+                    : args, vault, semanticAdapter);
                 if (semanticToolResult) {
-                    return semanticToolResult.ok ? jsonText(semanticToolResult.value) : errorText(semanticToolResult.message);
+                    if (!semanticToolResult.ok)
+                        return errorText(semanticToolResult.message);
+                    return jsonText(semanticToolResult.value);
                 }
             }
-            if (request.params.name === "oms_lazy_load_note") {
+            if (name === "oms_lazy_load_note") {
                 const notePath = stringArg(args, "notePath");
                 if (!notePath) {
                     return errorText('Missing required string argument "notePath".');
                 }
                 return jsonText(await lazyLoadNoteBody(vault, notePath));
             }
-            if (request.params.name === "oms_validate_contract") {
+            if (name === "oms_validate_contract") {
                 const notePath = stringArg(args, "notePath");
                 if (!notePath) {
                     return errorText('Missing required string argument "notePath".');
@@ -603,7 +636,7 @@ export function createOMSMcpServer(opts) {
                     violations: result.violations,
                 });
             }
-            if (request.params.name === "oms_vault_audit") {
+            if (name === "oms_vault_audit") {
                 if (args !== undefined &&
                     Object.prototype.hasOwnProperty.call(args, "folder") &&
                     typeof args["folder"] !== "string") {
@@ -622,7 +655,7 @@ export function createOMSMcpServer(opts) {
                     violations: report.violations,
                 });
             }
-            if (request.params.name === "oms_link_suggest") {
+            if (name === "oms_link_suggest") {
                 const notePath = stringArg(args, "notePath");
                 if (!notePath) {
                     return errorText('Missing required string argument "notePath".');
@@ -631,7 +664,7 @@ export function createOMSMcpServer(opts) {
                 const suggestion = await suggestLinksForNote({ vault, source, ontology, notePath }, { folder: stringArg(args, "folder") });
                 return jsonText({ vault, ontologySource, ...suggestion });
             }
-            if (request.params.name === "oms_link_apply") {
+            if (name === "oms_link_apply") {
                 const notePath = stringArg(args, "notePath");
                 if (!notePath) {
                     return errorText('Missing required string argument "notePath".');
@@ -648,10 +681,20 @@ export function createOMSMcpServer(opts) {
                 const outcome = await applyLinksForNote({ vault, source, ontology, notePath }, { baseContentHash, candidateIds: idsArg.filter((id) => typeof id === "string") }, { folder: stringArg(args, "folder") });
                 return jsonText({ vault, ontologySource, ...linkApplyPayload(outcome) });
             }
-            if (request.params.name === "write") {
+            if (name === "write") {
                 const { ontology, source: ontologySource } = await resolveActiveOntology(vault);
                 const modeArg = stringArg(args, "mode");
                 const mode = isWriteMode(modeArg) ? modeArg : "create";
+                // `notePath` and `folder`/`filename` are two ways to address the same
+                // note. Supplying both is a contradiction the caller should hear about:
+                // silently preferring one produced a response that reported the concept
+                // implied by one form and the folder implied by the other, which reads as
+                // corruption rather than as the input error it is.
+                const hasNotePath = stringArg(args, "notePath") !== undefined;
+                const hasFolderForm = stringArg(args, "folder") !== undefined || stringArg(args, "filename") !== undefined;
+                if (hasNotePath && hasFolderForm) {
+                    return errorText('Provide either "notePath" or "folder"/"filename" to address the note, not both.');
+                }
                 const frontmatterArg = args?.["frontmatter"];
                 const result = await writeNote({
                     target: { vault, source },
@@ -673,9 +716,15 @@ export function createOMSMcpServer(opts) {
                     resolutionSource: source,
                 });
             }
-            return errorText(`Unknown Oh My Second Brain tool: ${request.params.name}`);
+            return errorText(`Unknown Oh My Second Brain tool: ${publicName}`);
         }
         catch (error) {
+            if (error instanceof SemanticIndexUnavailableError) {
+                return jsonText({
+                    available: false,
+                    reason: error.message,
+                });
+            }
             return errorText(`Oh My Second Brain MCP error: ${error instanceof Error ? error.message : String(error)}`);
         }
     });