@andespindola/brainlink 0.1.0-alpha.9 → 0.1.0-beta.1

package/dist/infrastructure/file-system-vault.js

@@ -1,6 +1,7 @@
 import { chmod, mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
 import { dirname, extname, isAbsolute, join, relative, resolve } from 'node:path';
 import { resolvePath } from './paths.js';
+import { getBucketVaultCachePath, isBucketVaultUri, parseBucketVaultUri, syncBucketVaultToCache, writeBucketMarkdownFile } from './bucket-vault.js';
 const excludedDirectories = new Set(['.brainlink', '.git', 'node_modules', 'dist']);
 const directoryMode = 0o700;
 const fileMode = 0o600;
@@ -15,30 +16,44 @@ const walkMarkdownFiles = async (directory) => {
     }));
     return nested.flat();
 };
-export const resolveVaultPath = (vaultPath) => resolvePath(vaultPath);
+export const resolveVaultPath = (vaultPath) => isBucketVaultUri(vaultPath) ? getBucketVaultCachePath(vaultPath) : resolvePath(vaultPath);
+export const isBucketVaultPath = (vaultPath) => isBucketVaultUri(vaultPath);
 const isPathInside = (parent, child) => {
     const path = relative(parent, child);
     return path === '' || (!path.startsWith('..') && !isAbsolute(path));
 };
+const isBucketPrefixInside = (parent, child) => parent === '' || child === parent || child.startsWith(`${parent}/`);
 const secureDirectory = async (path) => {
     await mkdir(path, { recursive: true, mode: directoryMode });
     await chmod(path, directoryMode);
 };
 export const assertVaultAllowed = (vaultPath, allowedVaults) => {
+    if (isBucketVaultUri(vaultPath)) {
+        const vault = parseBucketVaultUri(vaultPath);
+        const allowed = allowedVaults.filter(isBucketVaultUri).map(parseBucketVaultUri);
+        if (allowedVaults.length > 0 &&
+            !allowed.some((allowedVault) => vault.bucket === allowedVault.bucket && isBucketPrefixInside(allowedVault.prefix, vault.prefix))) {
+            throw new Error(`Vault path is not allowed: ${vault.uri}. Configure BRAINLINK_ALLOWED_VAULTS or allowedVaults.`);
+        }
+        return vault.uri;
+    }
     const absoluteVaultPath = resolveVaultPath(vaultPath);
-    const allowed = allowedVaults.map(resolveVaultPath);
+    const allowed = allowedVaults.filter((allowedVault) => !isBucketVaultUri(allowedVault)).map(resolveVaultPath);
     if (allowed.length > 0 && !allowed.some((allowedPath) => isPathInside(allowedPath, absoluteVaultPath))) {
         throw new Error(`Vault path is not allowed: ${absoluteVaultPath}. Configure BRAINLINK_ALLOWED_VAULTS or allowedVaults.`);
     }
     return absoluteVaultPath;
 };
 export const ensureVault = async (vaultPath) => {
+    if (isBucketVaultUri(vaultPath)) {
+        return syncBucketVaultToCache(vaultPath);
+    }
     const absoluteVaultPath = resolveVaultPath(vaultPath);
     await secureDirectory(join(absoluteVaultPath, '.brainlink'));
     return absoluteVaultPath;
 };
 export const readMarkdownFiles = async (vaultPath) => {
-    const absoluteVaultPath = resolveVaultPath(vaultPath);
+    const absoluteVaultPath = await ensureVault(vaultPath);
     const paths = await walkMarkdownFiles(absoluteVaultPath);
     return Promise.all(paths.map(async (absolutePath) => {
         const [content, stats] = await Promise.all([readFile(absolutePath, 'utf8'), stat(absolutePath)]);
@@ -51,6 +66,9 @@ export const readMarkdownFiles = async (vaultPath) => {
     }));
 };
 export const writeMarkdownFile = async (vaultPath, filename, content) => {
+    if (isBucketVaultUri(vaultPath)) {
+        return writeBucketMarkdownFile(vaultPath, filename, content);
+    }
     const absoluteVaultPath = await ensureVault(vaultPath);
     const absolutePath = resolve(absoluteVaultPath, filename.endsWith('.md') ? filename : `${filename}.md`);
     if (!isPathInside(absoluteVaultPath, absolutePath)) {

package/dist/infrastructure/sqlite/document-writer.js

@@ -1,4 +1,5 @@
 import { createEmbeddingBuckets } from '../../domain/embeddings.js';
+const toTitleKey = (title) => title.toLowerCase();
 export const createIndexWriter = (database) => ({
     reset: () => {
         database.exec(`
@@ -27,8 +28,8 @@ export const createIndexWriter = (database) => ({
       VALUES (?, ?)
     `);
         const insertLink = database.prepare(`
-      INSERT INTO links (from_document_id, to_title, to_document_id)
-      VALUES (?, ?, ?)
+      INSERT INTO links (from_document_id, to_title, to_title_key, to_document_id, weight, priority)
+      VALUES (?, ?, ?, ?, ?, ?)
     `);
         const transaction = database.transaction(() => {
             documents.forEach(({ document, chunks, links }) => {
@@ -41,7 +42,7 @@ export const createIndexWriter = (database) => ({
             });
             documents.forEach(({ links }) => {
                 links.forEach((link) => {
-                    insertLink.run(link.fromDocumentId, link.toTitle, link.toDocumentId);
+                    insertLink.run(link.fromDocumentId, link.toTitle, toTitleKey(link.toTitle), link.toDocumentId, link.weight, link.priority);
                 });
             });
         });

package/dist/infrastructure/sqlite/graph-reader.js

@@ -4,9 +4,12 @@ const toGraphLink = (row) => ({
     fromTitle: row.from_title,
     fromPath: row.from_path,
     toTitle: row.to_title,
-    toPath: row.to_path
+    toPath: row.to_path,
+    weight: row.weight,
+    priority: row.priority
 });
 const normalizeAgentFilter = (agentId) => agentId ? sanitizeAgentId(agentId) : undefined;
+const toTitleKey = (title) => title.toLowerCase();
 export const createGraphReader = (database) => ({
     listLinks: (agentId) => {
         const normalizedAgentId = normalizeAgentFilter(agentId);
@@ -18,12 +21,14 @@ export const createGraphReader = (database) => ({
             source.title AS from_title,
             source.path AS from_path,
             COALESCE(target.title, links.to_title) AS to_title,
-            target.path AS to_path
+            target.path AS to_path,
+            links.weight AS weight,
+            links.priority AS priority
           FROM links
           JOIN documents source ON source.id = links.from_document_id
           LEFT JOIN documents target ON target.id = links.to_document_id
           ${agentFilter}
-          ORDER BY source.title, to_title
+          ORDER BY source.title, links.weight DESC, to_title
         `)
             .all(...(normalizedAgentId ? [normalizedAgentId] : []));
         return rows.map(toGraphLink);
@@ -31,6 +36,7 @@ export const createGraphReader = (database) => ({
     listBacklinks: (title, agentId) => {
         const normalizedAgentId = normalizeAgentFilter(agentId);
         const agentFilter = normalizedAgentId ? 'AND source.agent_id = ?' : '';
+        const titleKey = toTitleKey(title);
         const rows = database
             .prepare(`
           SELECT
@@ -38,15 +44,17 @@ export const createGraphReader = (database) => ({
             source.title AS from_title,
             source.path AS from_path,
             COALESCE(target.title, links.to_title) AS to_title,
-            target.path AS to_path
+            target.path AS to_path,
+            links.weight AS weight,
+            links.priority AS priority
           FROM links
           JOIN documents source ON source.id = links.from_document_id
           LEFT JOIN documents target ON target.id = links.to_document_id
-          WHERE (lower(links.to_title) = lower(?) OR lower(target.title) = lower(?))
+          WHERE links.to_title_key = ?
           ${agentFilter}
-          ORDER BY source.title
+          ORDER BY links.weight DESC, source.title
         `)
-            .all(...(normalizedAgentId ? [title, title, normalizedAgentId] : [title, title]));
+            .all(...(normalizedAgentId ? [titleKey, normalizedAgentId] : [titleKey]));
         return rows.map(toGraphLink);
     },
     getGraph: (agentId) => {
@@ -66,11 +74,13 @@ export const createGraphReader = (database) => ({
           SELECT
             links.from_document_id AS source,
             links.to_document_id AS target,
-            links.to_title AS target_title
+            links.to_title AS target_title,
+            links.weight AS weight,
+            links.priority AS priority
           FROM links
           JOIN documents source ON source.id = links.from_document_id
           ${edgeAgentFilter}
-          ORDER BY links.from_document_id, links.to_title
+          ORDER BY links.from_document_id, links.weight DESC, links.to_title
         `)
             .all(...(normalizedAgentId ? [normalizedAgentId] : []));
         const nodes = nodeRows.map((row) => ({
@@ -84,7 +94,9 @@ export const createGraphReader = (database) => ({
         const edges = edgeRows.map((row) => ({
             source: row.source,
             target: row.target,
-            targetTitle: row.target_title
+            targetTitle: row.target_title,
+            weight: row.weight,
+            priority: row.priority
         }));
         return {
             nodes,

package/dist/infrastructure/sqlite/schema.js

@@ -1,7 +1,8 @@
-const schemaVersion = 4;
+const schemaVersion = 5;
 const requiredTableColumns = {
     documents: ['id', 'agent_id', 'title', 'path', 'content', 'tags_json', 'frontmatter_json', 'created_at', 'updated_at'],
     chunks: ['id', 'document_id', 'ordinal', 'content', 'token_count', 'embedding_provider', 'embedding_json'],
+    links: ['from_document_id', 'to_title', 'to_title_key', 'to_document_id', 'weight', 'priority'],
     chunks_fts: ['chunk_id', 'document_id', 'agent_id', 'title', 'content']
 };
 const getStoredSchemaVersion = (database) => {
@@ -65,6 +66,9 @@ export const createSchema = (database) => {
       FOREIGN KEY (document_id) REFERENCES documents(id) ON DELETE CASCADE
     );
 
+    CREATE INDEX IF NOT EXISTS idx_documents_agent_title ON documents(agent_id, title);
+    CREATE INDEX IF NOT EXISTS idx_chunks_document_ordinal ON chunks(document_id, ordinal);
+
     CREATE TABLE IF NOT EXISTS embedding_buckets (
       bucket TEXT NOT NULL,
       chunk_id TEXT NOT NULL,
@@ -77,11 +81,18 @@ export const createSchema = (database) => {
     CREATE TABLE IF NOT EXISTS links (
       from_document_id TEXT NOT NULL,
       to_title TEXT NOT NULL,
+      to_title_key TEXT NOT NULL,
       to_document_id TEXT,
+      weight INTEGER NOT NULL,
+      priority TEXT NOT NULL,
+      PRIMARY KEY (from_document_id, to_title_key),
       FOREIGN KEY (from_document_id) REFERENCES documents(id) ON DELETE CASCADE,
       FOREIGN KEY (to_document_id) REFERENCES documents(id) ON DELETE SET NULL
     );
 
+    CREATE INDEX IF NOT EXISTS idx_links_to_document_id ON links(to_document_id);
+    CREATE INDEX IF NOT EXISTS idx_links_to_title_key ON links(to_title_key);
+
     CREATE VIRTUAL TABLE IF NOT EXISTS chunks_fts USING fts5(
       chunk_id UNINDEXED,
       document_id UNINDEXED,

package/dist/infrastructure/sqlite-index.js

@@ -9,7 +9,12 @@ export const openSqliteIndex = (vaultPath) => {
     const databasePath = join(vaultPath, '.brainlink', 'brainlink.db');
     const database = new Database(databasePath);
     chmodSync(databasePath, 0o600);
-    database.exec('PRAGMA foreign_keys = ON;');
+    database.exec(`
+    PRAGMA foreign_keys = ON;
+    PRAGMA journal_mode = WAL;
+    PRAGMA synchronous = NORMAL;
+    PRAGMA temp_store = MEMORY;
+  `);
     createSchema(database);
     return {
         ...createIndexWriter(database),

package/dist/mcp/server.js

@@ -2,7 +2,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { addNoteInputSchema, addNoteTool, brokenLinksInputSchema, brokenLinksTool, contextInputSchema, contextTool, graphInputSchema, graphTool, indexInputSchema, indexTool, orphansInputSchema, orphansTool, searchInputSchema, searchTool, validateInputSchema, validateTool } from './tools.js';
+import { addNoteInputSchema, addFileInputSchema, addFileTool, addNoteTool, brokenLinksInputSchema, brokenLinksTool, contextInputSchema, contextTool, graphInputSchema, graphTool, indexInputSchema, indexTool, orphansInputSchema, orphansTool, searchInputSchema, searchTool, statsInputSchema, statsTool, syncInputSchema, syncTool, validateInputSchema, validateTool } from './tools.js';
 const readPackageVersion = () => {
     const packagePath = join(dirname(fileURLToPath(import.meta.url)), '../../package.json');
     const metadata = JSON.parse(readFileSync(packagePath, 'utf8'));
@@ -27,22 +27,37 @@ export const createBrainlinkMcpServer = () => {
     }, searchTool);
     server.registerTool('brainlink_add_note', {
         title: 'Add Brainlink Note',
-        description: 'Write durable Markdown memory, then reindex the vault. Include explicit [[wiki links]] for connected graph memory.',
+        description: 'Write durable Markdown memory, then reindex the vault. Include explicit [[wiki links]] for connected graph memory. Add priority markers near links, such as priority: high, #important or #critical, when a relationship should be weighted higher.',
         inputSchema: addNoteInputSchema
     }, addNoteTool);
+    server.registerTool('brainlink_add_file', {
+        title: 'Ingest Markdown File',
+        description: 'Read a local markdown/text file and ingest it as a Brainlink note. Reindex defaults to true.',
+        inputSchema: addFileInputSchema
+    }, addFileTool);
     server.registerTool('brainlink_index', {
         title: 'Index Brainlink Vault',
         description: 'Rebuild the local Brainlink index from Markdown notes.',
         inputSchema: indexInputSchema
     }, indexTool);
+    server.registerTool('brainlink_stats', {
+        title: 'Get Brainlink Vault Stats',
+        description: 'Read indexed vault statistics, including node, edge and tag totals.',
+        inputSchema: statsInputSchema
+    }, statsTool);
     server.registerTool('brainlink_validate', {
         title: 'Validate Brainlink Vault',
         description: 'Validate indexed graph health, including broken links and orphan notes.',
         inputSchema: validateInputSchema
     }, validateTool);
+    server.registerTool('brainlink_sync', {
+        title: 'Run Brainlink Sync Flow',
+        description: 'Run index, stats, validate, broken-links and orphans checks in one call. Optionally run context probe.',
+        inputSchema: syncInputSchema
+    }, syncTool);
     server.registerTool('brainlink_graph', {
         title: 'Read Brainlink Graph',
-        description: 'Read indexed graph nodes and wiki-link edges.',
+        description: 'Read indexed graph nodes and wiki-link edges. Edges include weight and priority fields so agents can rank importance and priority.',
         inputSchema: graphInputSchema
     }, graphTool);
     server.registerTool('brainlink_broken_links', {

package/dist/mcp/tools.js

@@ -1,5 +1,7 @@
+import { readFile } from 'node:fs/promises';
+import { basename, extname } from 'node:path';
 import { z } from 'zod';
-import { getBrokenLinksReport, getOrphansReport, validateVault } from '../application/analyze-vault.js';
+import { getBrokenLinksReport, getOrphansReport, getStats, validateVault } from '../application/analyze-vault.js';
 import { addNote } from '../application/add-note.js';
 import { buildContextPackage } from '../application/build-context.js';
 import { getGraph } from '../application/get-graph.js';
@@ -18,15 +20,35 @@ const vaultInput = {
     vault: z.string().min(1).optional().describe('Vault directory. Omit to use the configured Brainlink default vault.')
 };
 const agentInput = {
-    agent: z.string().min(1).optional().describe('Agent memory namespace. Omit to read shared/default indexed memory.')
+    agent: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Agent memory namespace. Omit to use Brainlink.config defaultAgent, otherwise read all agent namespaces.')
 };
 const searchModeInput = {
     mode: z.enum(['fts', 'semantic', 'hybrid']).optional().describe('Search mode. Defaults to the Brainlink config value.')
 };
-const resolveVault = async (vault) => {
+const resolveExecutionContext = async (input) => {
     const config = await loadBrainlinkConfig();
-    return assertVaultAllowed(vault ?? config.vault, config.allowedVaults);
+    const vault = await assertVaultAllowed(input.vault ?? config.vault, config.allowedVaults);
+    const agent = input.agent ?? config.defaultAgent;
+    return {
+        config,
+        vault,
+        agent
+    };
 };
+const inferTitleFromPath = (filePath) => {
+    const extension = extname(filePath);
+    const fromFileName = basename(filePath, extension);
+    return fromFileName
+        .trim()
+        .replace(/[-_]+/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+};
+const isTruthy = (value) => value !== false;
 const jsonResult = (value) => ({
     content: [
         {
@@ -57,8 +79,17 @@ export const addNoteInputSchema = {
     content: z
         .string()
         .min(1)
-        .describe('Durable Markdown memory. Include explicit [[wiki links]] and #tags when the memory should be connected.'),
-    agent: z.string().min(1).optional().default('shared').describe('Agent memory namespace. Defaults to shared.'),
+        .describe('Durable Markdown memory. Include explicit [[wiki links]] and #tags when the memory should be connected. Put priority markers near important links, for example priority: high, #important or #critical.'),
+    ...agentInput,
+    allowSensitive: z.boolean().optional().default(false).describe('Allow content that looks like a secret.'),
+    autoIndex: z.boolean().optional().default(true).describe('Reindex vault after writing note.')
+};
+export const addFileInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    title: z.string().min(1).optional().describe('Optional note title override. If omitted, uses file name.'),
+    filePath: z.string().min(1).describe('Filesystem path to markdown or text file to ingest.'),
+    autoIndex: z.boolean().optional().default(true).describe('Reindex vault after ingesting file.'),
     allowSensitive: z.boolean().optional().default(false).describe('Allow content that looks like a secret.')
 };
 export const indexInputSchema = {
@@ -80,26 +111,36 @@ export const orphansInputSchema = {
     ...vaultInput,
     ...agentInput
 };
+export const statsInputSchema = {
+    ...vaultInput,
+    ...agentInput
+};
+export const syncInputSchema = {
+    ...vaultInput,
+    ...agentInput,
+    contextQuery: z.string().min(1).optional().describe('Optional context smoke query. Omit to skip context probe.'),
+    mode: z.enum(['fts', 'semantic', 'hybrid']).optional().describe('Search mode for the optional context probe. Defaults to config value.'),
+    contextLimit: positiveInteger(12).describe('Context smoke result limit when contextQuery is provided.'),
+    contextTokens: positiveInteger(2000).describe('Context smoke token target when contextQuery is provided.')
+};
 export const contextTool = async (input) => {
-    const vault = await resolveVault(input.vault);
-    const config = await loadBrainlinkConfig();
-    const mode = sanitizeSearchMode(input.mode, config.defaultSearchMode);
-    const contextPackage = await buildContextPackage(vault, input.query, input.limit, input.tokens, input.agent, mode);
+    const context = await resolveExecutionContext(input);
+    const mode = sanitizeSearchMode(input.mode, context.config.defaultSearchMode);
+    const contextPackage = await buildContextPackage(context.vault, input.query, input.limit, input.tokens, context.agent, mode);
     return jsonResult({
-        vault,
-        agent: input.agent,
+        vault: context.vault,
+        agent: context.agent,
         mode,
         ...contextPackage
     });
 };
 export const searchTool = async (input) => {
-    const vault = await resolveVault(input.vault);
-    const config = await loadBrainlinkConfig();
-    const mode = sanitizeSearchMode(input.mode, config.defaultSearchMode);
-    const results = await searchKnowledge(vault, input.query, input.limit, input.agent, mode);
+    const context = await resolveExecutionContext(input);
+    const mode = sanitizeSearchMode(input.mode, context.config.defaultSearchMode);
+    const results = await searchKnowledge(context.vault, input.query, input.limit, context.agent, mode);
     return jsonResult({
-        vault,
-        agent: input.agent,
+        vault: context.vault,
+        agent: context.agent,
         query: input.query,
         limit: input.limit,
         mode,
@@ -107,60 +148,121 @@ export const searchTool = async (input) => {
     });
 };
 export const addNoteTool = async (input) => {
-    const vault = await resolveVault(input.vault);
-    const path = await addNote(vault, input.title, input.content, input.agent, {
+    const context = await resolveExecutionContext(input);
+    const shouldIndex = isTruthy(input.autoIndex);
+    const path = await addNote(context.vault, input.title, input.content, context.agent, {
         allowSensitive: input.allowSensitive
     });
-    const index = await indexVault(vault);
+    const index = shouldIndex ? await indexVault(context.vault) : undefined;
     return jsonResult({
-        vault,
+        vault: context.vault,
         title: input.title,
-        agent: input.agent,
+        agent: context.agent,
         path,
-        index
+        ...(index ? { index } : {})
+    });
+};
+export const addFileTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const content = await readFile(input.filePath, 'utf8');
+    const inferredTitle = inferTitleFromPath(input.filePath);
+    const title = input.title ?? inferredTitle;
+    if (title == null || title.length === 0) {
+        throw new Error('Cannot infer note title from file path. Provide a title explicitly.');
+    }
+    const shouldIndex = isTruthy(input.autoIndex);
+    const path = await addNote(context.vault, title, content, context.agent, {
+        allowSensitive: input.allowSensitive
+    });
+    const index = shouldIndex ? await indexVault(context.vault) : undefined;
+    return jsonResult({
+        vault: context.vault,
+        title,
+        agent: context.agent,
+        filePath: input.filePath,
+        path,
+        ...(index ? { index } : {})
     });
 };
 export const indexTool = async (input) => {
-    const vault = await resolveVault(input.vault);
-    const result = await indexVault(vault);
+    const context = await resolveExecutionContext(input);
+    const result = await indexVault(context.vault);
     return jsonResult({
-        vault,
+        vault: context.vault,
         ...result
     });
 };
 export const validateTool = async (input) => {
-    const vault = await resolveVault(input.vault);
-    const validation = await validateVault(vault, input.agent);
+    const context = await resolveExecutionContext(input);
+    const validation = await validateVault(context.vault, context.agent);
     return jsonResult({
-        vault,
-        agent: input.agent,
+        vault: context.vault,
+        agent: context.agent,
         ...validation
     });
 };
 export const graphTool = async (input) => {
-    const vault = await resolveVault(input.vault);
-    const graph = await getGraph(vault, input.agent);
+    const context = await resolveExecutionContext(input);
+    const graph = await getGraph(context.vault, context.agent);
     return jsonResult({
-        vault,
-        agent: input.agent,
+        vault: context.vault,
+        agent: context.agent,
         ...graph
     });
 };
 export const brokenLinksTool = async (input) => {
-    const vault = await resolveVault(input.vault);
-    const brokenLinks = await getBrokenLinksReport(vault, input.agent);
+    const context = await resolveExecutionContext(input);
+    const brokenLinks = await getBrokenLinksReport(context.vault, context.agent);
     return jsonResult({
-        vault,
-        agent: input.agent,
+        vault: context.vault,
+        agent: context.agent,
         brokenLinks
     });
 };
 export const orphansTool = async (input) => {
-    const vault = await resolveVault(input.vault);
-    const orphans = await getOrphansReport(vault, input.agent);
+    const context = await resolveExecutionContext(input);
+    const orphans = await getOrphansReport(context.vault, context.agent);
     return jsonResult({
-        vault,
-        agent: input.agent,
+        vault: context.vault,
+        agent: context.agent,
         orphans
     });
 };
+export const statsTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const stats = await getStats(context.vault, context.agent);
+    return jsonResult({
+        vault: context.vault,
+        agent: context.agent,
+        stats
+    });
+};
+export const syncTool = async (input) => {
+    const context = await resolveExecutionContext(input);
+    const index = await indexVault(context.vault);
+    const stats = await getStats(context.vault, context.agent);
+    const validation = await validateVault(context.vault, context.agent);
+    const brokenLinks = await getBrokenLinksReport(context.vault, context.agent);
+    const orphans = await getOrphansReport(context.vault, context.agent);
+    const response = {
+        vault: context.vault,
+        agent: context.agent,
+        index,
+        stats,
+        validation,
+        brokenLinks,
+        orphans
+    };
+    if (!input.contextQuery) {
+        return jsonResult(response);
+    }
+    const mode = sanitizeSearchMode(input.mode, context.config.defaultSearchMode);
+    const contextPackage = await buildContextPackage(context.vault, input.contextQuery, input.contextLimit, input.contextTokens, context.agent, mode);
+    return jsonResult({
+        ...response,
+        context: {
+            mode,
+            ...contextPackage
+        }
+    });
+};