@andespindola/brainlink 1.0.2 → 1.0.4

package/dist/application/server/routes.js

@@ -1,3 +1,6 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import { getBrokenLinksReport, getOrphansReport, getStats, validateVault } from '../analyze-vault.js';
 import { buildContextPackage } from '../build-context.js';
 import { getGraph } from '../get-graph.js';
@@ -7,8 +10,10 @@ import { getGraphLayout } from '../get-graph-layout.js';
 import { getGraphView } from '../get-graph-view.js';
 import { getGraphStreamChunk } from '../get-graph-stream-chunk.js';
 import { deleteGraphViewState, getGraphViewState, saveGraphViewState } from '../graph-view-state.js';
+import { importFile } from '../import-file.js';
 import { listAgents } from '../list-agents.js';
 import { listBacklinks, listLinks } from '../list-links.js';
+import { suggestContextLinks } from '../memory-suggestions.js';
 import { searchGraphNodeIds } from '../search-graph-node-ids.js';
 import { searchKnowledge } from '../search-knowledge.js';
 import { loadBrainlinkConfig, resolveAgentRuntimeDefaults, sanitizeContextStrategy, sanitizeSearchMode } from '../../infrastructure/config.js';
@@ -18,6 +23,7 @@ import { createClientJs } from '../frontend/client-js.js';
 import { createClientWorkerJs } from '../frontend/client-worker-js.js';
 import { createClientRenderWorkerJs } from '../frontend/client-render-worker-js.js';
 import { contentTypes, createJsonResponse, isReadMethod, parsePositiveInteger } from './http.js';
+import { parseMultipartForm } from './multipart.js';
 const readSearchMode = async (url) => {
     const config = await loadBrainlinkConfig();
     const defaults = resolveAgentRuntimeDefaults(config, readAgentQuery(url));
@@ -95,6 +101,27 @@ const readGraphViewStateInput = (url) => ({
     agentId: readAgentQuery(url),
     context: readContextQuery(url)
 });
+const booleanField = (value) => value === '1' || value === 'true' || value === 'on';
+const writeUploadTempFile = async (filename, data) => {
+    const directory = await mkdtemp(join(tmpdir(), 'brainlink-upload-'));
+    const safeName = filename.replace(/[\\/]/g, '-').trim() || 'upload.bin';
+    const path = join(directory, safeName);
+    await writeFile(path, data);
+    return { directory, path };
+};
+const isSameOriginWrite = (request, url) => {
+    const originHeader = Array.isArray(request.headers.origin) ? request.headers.origin[0] : request.headers.origin;
+    if (!originHeader) {
+        return true;
+    }
+    try {
+        const origin = new URL(originHeader);
+        return origin.protocol === url.protocol && origin.host === url.host;
+    }
+    catch {
+        return false;
+    }
+};
 const compactGraphLayoutThreshold = 12_000;
 const compactGraphLayoutEdgeLimit = 60_000;
 const graphLayoutBodyCacheLimit = 8;
@@ -345,6 +372,34 @@ export const route = async (request, url, vaultPath) => {
         }
         return createResponse(createJsonResponse(await deleteGraphViewState(vaultPath, input)), 200, contentTypes['.json']);
     }
+    if (request.method === 'POST' && url.pathname === '/api/import-file') {
+        if (!isSameOriginWrite(request, url)) {
+            return createResponse(createJsonResponse({ error: 'Cross-origin imports are not allowed' }), 403, contentTypes['.json']);
+        }
+        const config = await loadBrainlinkConfig();
+        const form = await parseMultipartForm(request);
+        const file = form.files.find((candidate) => candidate.fieldName === 'file') ?? form.files[0];
+        if (!file || file.data.byteLength === 0) {
+            return createResponse(createJsonResponse({ error: 'Missing uploaded file' }), 400, contentTypes['.json']);
+        }
+        const temp = await writeUploadTempFile(file.filename, file.data);
+        try {
+            const result = await importFile({
+                vaultPath,
+                filePath: temp.path,
+                originalName: file.filename,
+                title: form.fields.title,
+                agentId: readAgentQuery(url) ?? form.fields.agent,
+                allowSensitive: booleanField(form.fields.allowSensitive),
+                autoContextLinks: config.autoCanonicalContextLinks,
+                autoIndex: config.autoIndexOnWrite
+            });
+            return createResponse(createJsonResponse(result), 200, contentTypes['.json']);
+        }
+        finally {
+            await rm(temp.directory, { recursive: true, force: true });
+        }
+    }
     if (isReadMethod(request) && url.pathname === '/api/graph-node') {
         const id = url.searchParams.get('id')?.trim() ?? '';
         if (!id) {
@@ -402,6 +457,13 @@ export const route = async (request, url, vaultPath) => {
         const title = url.searchParams.get('title') ?? '';
         return createResponse(createJsonResponse({ title, backlinks: await listBacklinks(vaultPath, title, readAgentQuery(url)) }), 200, contentTypes['.json']);
     }
+    if (isReadMethod(request) && url.pathname === '/api/suggest-links') {
+        const content = url.searchParams.get('content') ?? '';
+        const limit = parsePositiveInteger(url.searchParams.get('limit'), 5);
+        return createResponse(createJsonResponse({
+            suggestions: await suggestContextLinks(vaultPath, content, readAgentQuery(url), limit)
+        }), 200, contentTypes['.json']);
+    }
     if (isReadMethod(request) && url.pathname === '/api/stats') {
         return createResponse(createJsonResponse(await getStats(vaultPath, readAgentQuery(url))), 200, contentTypes['.json']);
     }

package/dist/cli/commands/practical-commands.js

@@ -0,0 +1,278 @@
+import { resolve } from 'node:path';
+import { addNoteWithMetadata } from '../../application/add-note.js';
+import { indexVault } from '../../application/index-vault.js';
+import { addInboxItem, listInboxItems, processInboxItems } from '../../application/inbox.js';
+import { buildRememberSuggestion, explainSearchResults, readMemoryContentInput, suggestBrokenLinkFixes, suggestContextLinks } from '../../application/memory-suggestions.js';
+import { buildActionableDoctor, closeSession, initializeProjectMemory } from '../../application/operational-workflows.js';
+import { repairBrokenLinks } from '../../application/repair-broken-links.js';
+import { sanitizeSearchMode } from '../../infrastructure/config.js';
+import { parsePositiveInteger, print, resolveOptions } from '../runtime.js';
+const parseBoundedScore = (value, fallback) => {
+    if (value == null)
+        return fallback;
+    const parsed = Number.parseFloat(value);
+    if (!Number.isFinite(parsed) || parsed < 0 || parsed > 1) {
+        throw new Error(`Invalid score value: ${value}. Expected a number between 0 and 1.`);
+    }
+    return parsed;
+};
+const registerRememberCommand = (program) => {
+    program
+        .command('remember')
+        .option('-t, --title <title>', 'note title; inferred when omitted')
+        .option('-c, --content <content>', 'markdown content')
+        .option('-f, --content-file <contentFile>', 'read markdown content from a file')
+        .option('--tag <tag...>', 'extra tags to include')
+        .option('--link <title...>', 'explicit Context Links to include')
+        .option('--link-limit <limit>', 'maximum suggested Context Links', '5')
+        .option('-v, --vault <vault>', 'vault directory')
+        .option('-a, --agent <agent>', 'agent memory namespace')
+        .option('--allow-sensitive', 'allow writing content that looks like a secret')
+        .option('--dry-run', 'preview suggested note without writing it')
+        .option('--no-auto-index', 'skip reindexing after remember')
+        .option('--json', 'print machine-readable JSON')
+        .description('capture memory with inferred title, tags and Context Links')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        const content = await readMemoryContentInput(options);
+        const suggestion = await buildRememberSuggestion({
+            vaultPath: resolved.vault,
+            content,
+            agentId: resolved.agent,
+            title: options.title,
+            tags: options.tag ?? [],
+            links: options.link ?? [],
+            linkLimit: parsePositiveInteger(options.linkLimit ?? '5', 5)
+        });
+        if (options.dryRun) {
+            print(options.json, { dryRun: true, vault: resolved.vault, agent: resolved.agent ?? 'shared', suggestion }, () => suggestion.content);
+            return;
+        }
+        const added = await addNoteWithMetadata(resolved.vault, suggestion.title, suggestion.content, resolved.agent, {
+            allowSensitive: Boolean(options.allowSensitive),
+            autoContextLinks: false
+        });
+        const index = options.autoIndex !== false && resolved.config.autoIndexOnWrite ? await indexVault(resolved.vault) : undefined;
+        print(options.json, { dryRun: false, vault: resolved.vault, agent: resolved.agent ?? 'shared', suggestion, path: added.path, ...(index ? { index } : {}) }, () => `Remembered "${suggestion.title}" at ${added.path}.`);
+    });
+};
+const registerInboxCommands = (program) => {
+    const inboxCommand = program.command('inbox').description('capture and triage quick memory items');
+    inboxCommand
+        .command('add')
+        .option('-c, --content <content>', 'inbox content')
+        .option('-f, --content-file <contentFile>', 'read inbox content from a file')
+        .option('-v, --vault <vault>', 'vault directory')
+        .option('-a, --agent <agent>', 'agent memory namespace')
+        .option('--no-auto-index', 'skip reindexing after add')
+        .option('--json', 'print machine-readable JSON')
+        .description('add a quick untriaged memory item')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        const content = await readMemoryContentInput(options);
+        const result = await addInboxItem({
+            vaultPath: resolved.vault,
+            content,
+            agentId: resolved.agent,
+            autoIndex: options.autoIndex !== false && resolved.config.autoIndexOnWrite
+        });
+        print(options.json, { vault: resolved.vault, agent: resolved.agent ?? 'shared', ...result }, () => `Added inbox item at ${result.item.path}.`);
+    });
+    inboxCommand
+        .command('list')
+        .option('-v, --vault <vault>', 'vault directory')
+        .option('-a, --agent <agent>', 'accepted for consistency; inbox scans vault Markdown')
+        .option('-l, --limit <limit>', 'maximum inbox items', '20')
+        .option('--json', 'print machine-readable JSON')
+        .description('list untriaged inbox memory items')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        const items = await listInboxItems(resolved.vault, parsePositiveInteger(options.limit ?? '20', 20));
+        print(options.json, { vault: resolved.vault, items }, () => items.length === 0 ? 'Inbox is empty.' : items.map((item) => `${item.updatedAt} ${item.path}: ${item.preview}`).join('\n'));
+    });
+    inboxCommand
+        .command('process')
+        .option('-v, --vault <vault>', 'vault directory')
+        .option('-a, --agent <agent>', 'agent memory namespace')
+        .option('-l, --limit <limit>', 'maximum inbox items to inspect', '10')
+        .option('--json', 'print machine-readable JSON')
+        .description('suggest titles, tags and links for inbox items')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        const items = await processInboxItems({
+            vaultPath: resolved.vault,
+            agentId: resolved.agent,
+            limit: parsePositiveInteger(options.limit ?? '10', 10)
+        });
+        print(options.json, { vault: resolved.vault, agent: resolved.agent ?? 'shared', items }, () => items.length === 0
+            ? 'Inbox is empty.'
+            : items
+                .map((item) => [
+                `${item.path}`,
+                `  title: ${item.suggestedTitle}`,
+                `  tags: ${item.suggestedTags.map((tag) => `#${tag}`).join(' ') || 'none'}`,
+                `  links: ${item.suggestedLinks.map((link) => `[[${link}]]`).join(' ') || 'none'}`
+            ].join('\n'))
+                .join('\n\n'));
+    });
+};
+const registerProjectCommands = (program) => {
+    const projectCommand = program.command('project').description('manage project-scoped Brainlink memory');
+    projectCommand
+        .command('init')
+        .option('-p, --path <path>', 'project path to inspect', process.cwd())
+        .option('-v, --vault <vault>', 'vault directory')
+        .option('-a, --agent <agent>', 'agent memory namespace')
+        .option('--json', 'print machine-readable JSON')
+        .description('seed memory from project docs and agent instructions')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        const result = await initializeProjectMemory({
+            vaultPath: resolved.vault,
+            projectPath: resolve(options.path ?? process.cwd()),
+            agentId: resolved.agent
+        });
+        print(options.json, { agent: resolved.agent ?? 'shared', ...result }, () => [
+            `Initialized project memory for ${result.projectPath}`,
+            `vault=${result.vault}`,
+            `notes=${result.notes.length}`,
+            `indexedDocuments=${result.index.documentCount}`
+        ].join('\n'));
+    });
+};
+const registerSuggestionCommands = (program) => {
+    program
+        .command('suggest-links')
+        .option('-v, --vault <vault>', 'vault directory')
+        .option('-a, --agent <agent>', 'agent memory namespace')
+        .option('-c, --content <content>', 'content to inspect for link suggestions')
+        .option('-f, --content-file <contentFile>', 'read content to inspect from a file')
+        .option('-l, --limit <limit>', 'maximum suggestions', '5')
+        .option('--broken', 'suggest fixes for unresolved wiki links')
+        .option('--json', 'print machine-readable JSON')
+        .description('suggest Context Links or fixes for broken wiki links')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        const limit = parsePositiveInteger(options.limit ?? '5', 5);
+        if (options.broken) {
+            const suggestions = await suggestBrokenLinkFixes(resolved.vault, resolved.agent, limit);
+            print(options.json, { vault: resolved.vault, agent: resolved.agent ?? 'shared', suggestions }, () => suggestions.length === 0
+                ? 'No broken links found.'
+                : suggestions.map((item) => {
+                    const candidates = item.candidates.length > 0
+                        ? item.candidates.map((candidate) => `  - [[${candidate.title}]] (${candidate.path}) score=${candidate.score}`).join('\n')
+                        : '  - no close candidate found';
+                    return `${item.fromTitle} (${item.fromPath}) -> [[${item.toTitle}]]\n${candidates}`;
+                }).join('\n\n'));
+            return;
+        }
+        const content = await readMemoryContentInput(options);
+        const suggestions = await suggestContextLinks(resolved.vault, content, resolved.agent, limit);
+        print(options.json, { vault: resolved.vault, agent: resolved.agent ?? 'shared', suggestions }, () => suggestions.map((item) => `[[${item.title}]] (${item.path}) score=${item.score} - ${item.reason}`).join('\n'));
+    });
+    program
+        .command('repair-links')
+        .option('-v, --vault <vault>', 'vault directory')
+        .option('-a, --agent <agent>', 'agent memory namespace')
+        .option('--dry-run', 'preview repairs without writing files')
+        .option('--no-create-missing', 'do not create placeholder notes for unresolved targets')
+        .option('--no-auto-index', 'skip reindexing after repairs')
+        .option('--min-score <score>', 'minimum similarity score for automatic retargeting', '0.88')
+        .option('--margin <score>', 'minimum score gap between first and second candidate', '0.12')
+        .option('--json', 'print machine-readable JSON')
+        .description('repair broken wiki links by retargeting safe matches or creating placeholder targets')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        const result = await repairBrokenLinks(resolved.vault, {
+            agentId: resolved.agent,
+            dryRun: options.dryRun === true,
+            autoIndex: options.autoIndex !== false && resolved.config.autoIndexOnWrite,
+            createMissing: options.createMissing !== false,
+            minScore: parseBoundedScore(options.minScore, 0.88),
+            margin: parseBoundedScore(options.margin, 0.12)
+        });
+        print(options.json, { vault: resolved.vault, agent: resolved.agent ?? 'shared', ...result }, () => [
+            `${result.dryRun ? 'Previewed' : 'Repaired'} broken links: scanned=${result.scanned}, changed=${result.changed}, created=${result.created}, skipped=${result.skipped}`,
+            ...result.entries.map((entry) => `- ${entry.action}: ${entry.fromTitle} -> [[${entry.toTitle}]]${entry.targetTitle ? ` => [[${entry.targetTitle}]]` : ''} (${entry.reason})`)
+        ].join('\n'));
+    });
+    program
+        .command('explain')
+        .argument('<query>', 'search query to explain')
+        .option('-v, --vault <vault>', 'vault directory')
+        .option('-a, --agent <agent>', 'agent memory namespace')
+        .option('-l, --limit <limit>', 'maximum results', '10')
+        .option('-m, --mode <mode>', 'search mode: fts, semantic or hybrid')
+        .option('--json', 'print machine-readable JSON')
+        .description('explain why search results matched a query')
+        .action(async (query, options) => {
+        const resolved = await resolveOptions(options);
+        const mode = sanitizeSearchMode(options.mode, resolved.defaults.defaultSearchMode);
+        const results = await explainSearchResults(resolved.vault, query, parsePositiveInteger(options.limit ?? String(resolved.defaults.defaultSearchLimit), resolved.defaults.defaultSearchLimit), resolved.agent, mode);
+        print(options.json, { query, mode, agent: resolved.agent ?? 'shared', results }, () => results.map((result, index) => [
+            `${index + 1}. ${result.title} (${result.path}) score=${result.score.toFixed(3)}`,
+            ...result.reasons.map((reason) => `  - ${reason}`)
+        ].join('\n')).join('\n\n'));
+    });
+};
+const registerSessionCommands = (program) => {
+    const runSessionClose = async (options) => {
+        const resolved = await resolveOptions(options);
+        const content = options.content || options.contentFile ? await readMemoryContentInput(options) : undefined;
+        const result = await closeSession({
+            vaultPath: resolved.vault,
+            agentId: resolved.agent,
+            cwd: process.cwd(),
+            content,
+            write: options.dryRun !== true,
+            autoIndex: options.autoIndex !== false && resolved.config.autoIndexOnWrite
+        });
+        print(options.json, { vault: resolved.vault, agent: resolved.agent ?? 'shared', dryRun: options.dryRun === true, ...result }, () => options.dryRun ? result.content : `Wrote session handoff "${result.title}" at ${result.writtenPath}.`);
+    };
+    program
+        .command('session-close')
+        .option('-v, --vault <vault>', 'vault directory')
+        .option('-a, --agent <agent>', 'agent memory namespace')
+        .option('-c, --content <content>', 'extra session notes')
+        .option('-f, --content-file <contentFile>', 'read extra session notes from a file')
+        .option('--dry-run', 'preview session handoff without writing it')
+        .option('--no-auto-index', 'skip reindexing after writing handoff')
+        .option('--json', 'print machine-readable JSON')
+        .description('write a session handoff note with vault and git state')
+        .action(runSessionClose);
+    program
+        .command('daily')
+        .option('-v, --vault <vault>', 'vault directory')
+        .option('-a, --agent <agent>', 'agent memory namespace')
+        .option('-c, --content <content>', 'extra daily notes')
+        .option('-f, --content-file <contentFile>', 'read extra daily notes from a file')
+        .option('--dry-run', 'preview daily handoff without writing it')
+        .option('--no-auto-index', 'skip reindexing after writing handoff')
+        .option('--json', 'print machine-readable JSON')
+        .description('alias for session-close')
+        .action(runSessionClose);
+};
+export const registerPracticalCommands = (program) => {
+    registerRememberCommand(program);
+    registerInboxCommands(program);
+    registerProjectCommands(program);
+    registerSuggestionCommands(program);
+    registerSessionCommands(program);
+    program
+        .command('doctor-actions')
+        .option('-v, --vault <vault>', 'vault directory')
+        .option('-a, --agent <agent>', 'accepted for consistency')
+        .option('--json', 'print machine-readable JSON')
+        .description('print actionable vault health commands')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        const report = await buildActionableDoctor(resolved.vault);
+        print(options.json, report, () => [
+            ...report.doctor.checks.map((check) => `${check.ok ? 'OK' : 'FAIL'} ${check.name}: ${check.message}`),
+            '',
+            'Actionable next steps:',
+            ...report.actions.map((action) => `- [${action.severity}] ${action.command} (${action.reason})`)
+        ].join('\n'));
+        process.exitCode = report.doctor.ok ? 0 : 1;
+    });
+};

package/dist/cli/commands/read-commands.js

@@ -3,6 +3,7 @@ import { buildContextPackage, readContextDataSignature } from '../../application
 import { getGraph } from '../../application/get-graph.js';
 import { listAgents } from '../../application/list-agents.js';
 import { listBacklinks, listLinks } from '../../application/list-links.js';
+import { explainSearchResults } from '../../application/memory-suggestions.js';
 import { searchKnowledge } from '../../application/search-knowledge.js';
 import { sanitizeContextStrategy, sanitizeSearchMode } from '../../infrastructure/config.js';
 import { clearContextPacks, listContextPacks } from '../../infrastructure/context-packs.js';
@@ -15,12 +16,24 @@ export const registerReadCommands = (program) => {
         .option('-a, --agent <agent>', 'filter by agent memory namespace')
         .option('-l, --limit <limit>', 'maximum results')
         .option('-m, --mode <mode>', 'search mode: fts, semantic or hybrid')
+        .option('--explain', 'include match reasons and score components')
         .option('--json', 'print machine-readable JSON')
         .description('search indexed knowledge')
         .action(async (query, options) => {
         const resolved = await resolveOptions(options);
         const limit = parsePositiveInteger(options.limit ?? String(resolved.defaults.defaultSearchLimit), resolved.defaults.defaultSearchLimit);
         const mode = sanitizeSearchMode(options.mode, resolved.defaults.defaultSearchMode);
+        if (options.explain) {
+            const results = await explainSearchResults(resolved.vault, query, limit, resolved.agent, mode);
+            print(options.json, { query, agent: resolved.agent, limit, mode, results }, () => results
+                .map((result, index) => [
+                `${index + 1}. ${result.title} (${result.path}) score=${result.score.toFixed(3)} mode=${result.searchMode}`,
+                ...result.reasons.map((reason) => `  - ${reason}`),
+                result.content
+            ].join('\n'))
+                .join('\n\n'));
+            return;
+        }
         const results = await searchKnowledge(resolved.vault, query, limit, resolved.agent, mode);
         print(options.json, { query, agent: resolved.agent, limit, mode, results }, () => results
             .map((result, index) => [`${index + 1}. ${result.title} (${result.path}) score=${result.score.toFixed(3)} mode=${result.searchMode}`, result.content].join('\n'))

package/dist/cli/commands/write-commands.js

@@ -8,6 +8,7 @@ import { buildContextPackage } from '../../application/build-context.js';
 import { deleteNote } from '../../application/delete-note.js';
 import { resolveDuplicateNotes, scanDuplicateNotes } from '../../application/dedupe-notes.js';
 import { importLegacySqliteDatabase } from '../../application/import-legacy-sqlite.js';
+import { importFile } from '../../application/import-file.js';
 import { indexVault, indexVaultWithOptions } from '../../application/index-vault.js';
 import { migrateContextLinks } from '../../application/migrate-context-links.js';
 import { canonicalizeContextLinks } from '../../application/canonical-context-links.js';
@@ -16,6 +17,7 @@ import { createOfflinePackBackup } from '../../application/offline-pack-backup.j
 import { startServer } from '../../application/start-server.js';
 import { startVaultWatcher } from '../../application/watch-vault.js';
 import { doctorVault, getStats, validateVault } from '../../application/analyze-vault.js';
+import { buildActionableDoctor } from '../../application/operational-workflows.js';
 import { defaultBrainlinkConfig, sanitizeContextStrategy, sanitizeSearchMode } from '../../infrastructure/config.js';
 import { loadBrainlinkConfig } from '../../infrastructure/config.js';
 import { assertVaultAllowed, ensureVault, isBucketVaultPath } from '../../infrastructure/file-system-vault.js';
@@ -874,6 +876,38 @@ export const registerWriteCommands = (program) => {
             return `Created note at ${added.path}.${linkMessage}${duplicateMessage}`;
         });
     });
+    program
+        .command('import-file')
+        .argument('<file>', 'file to convert and import into the vault')
+        .option('-t, --title <title>', 'note title; defaults to the source filename')
+        .option('-v, --vault <vault>', 'vault directory')
+        .option('-a, --agent <agent>', 'agent memory namespace')
+        .option('--allow-sensitive', 'allow writing converted content that looks like a secret')
+        .option('--no-auto-context-links', 'skip canonical Context Links for this imported note')
+        .option('--no-auto-index', 'skip reindexing after import')
+        .option('--json', 'print machine-readable JSON')
+        .description('convert a document with Docling and import it as a Markdown note')
+        .action(async (file, options) => {
+        const resolved = await resolveOptions(options);
+        const result = await importFile({
+            vaultPath: resolved.vault,
+            filePath: resolve(file),
+            title: options.title,
+            agentId: resolved.agent,
+            allowSensitive: Boolean(options.allowSensitive),
+            autoContextLinks: options.autoContextLinks !== false && resolved.config.autoCanonicalContextLinks,
+            autoIndex: options.autoIndex !== false && resolved.config.autoIndexOnWrite
+        });
+        print(options.json, {
+            vault: resolved.vault,
+            agent: resolved.agent ?? 'shared',
+            ...result
+        }, () => {
+            const linkMessage = result.writeConnectivity.autoLinked ? ` Linked to [[${result.writeConnectivity.linkTarget}]].` : '';
+            const indexMessage = result.index ? ` Indexed ${result.index.documentCount} documents.` : '';
+            return `Imported ${result.sourceName} as "${result.title}" at ${result.path}.${linkMessage}${indexMessage}`;
+        });
+    });
     program
         .command('delete-note')
         .option('-v, --vault <vault>', 'vault directory')
@@ -1027,10 +1061,22 @@ export const registerWriteCommands = (program) => {
     program
         .command('doctor')
         .option('-v, --vault <vault>', 'vault directory')
+        .option('--actionable', 'include prioritized commands for fixing or improving vault health')
         .option('--json', 'print machine-readable JSON')
         .description('run Brainlink environment and vault checks')
         .action(async (options) => {
         const resolved = await resolveOptions(options);
+        if (options.actionable) {
+            const report = await buildActionableDoctor(resolved.vault);
+            print(options.json, report, () => [
+                ...report.doctor.checks.map((check) => `${check.ok ? 'OK' : 'FAIL'} ${check.name}: ${check.message}`),
+                '',
+                'Actionable next steps:',
+                ...report.actions.map((action) => `- [${action.severity}] ${action.command} (${action.reason})`)
+            ].join('\n'));
+            process.exitCode = report.doctor.ok ? 0 : 1;
+            return;
+        }
         const report = await doctorVault(resolved.vault);
         print(options.json, report, () => {
             const checks = report.checks.map((check) => `${check.ok ? 'OK' : 'FAIL'} ${check.name}: ${check.message}`).join('\n');

package/dist/cli/main.js

@@ -5,6 +5,7 @@ import { basename, dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { registerAgentCommands } from './commands/agent-commands.js';
 import { registerConfigCommands } from './commands/config-commands.js';
+import { registerPracticalCommands } from './commands/practical-commands.js';
 import { registerReadCommands } from './commands/read-commands.js';
 import { registerVaultCommands } from './commands/vault-commands.js';
 import { registerWriteCommands } from './commands/write-commands.js';
@@ -24,6 +25,7 @@ program
     .version(readPackageVersion());
 registerWriteCommands(program);
 registerReadCommands(program);
+registerPracticalCommands(program);
 registerConfigCommands(program);
 registerVaultCommands(program);
 registerAgentCommands(program);

package/dist/infrastructure/docling.js

@@ -0,0 +1,40 @@
+import { execFile } from 'node:child_process';
+import { mkdtemp, readFile, readdir, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, extname, join } from 'node:path';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+const readConvertedMarkdown = async (outputDirectory, sourcePath) => {
+    const sourceName = basename(sourcePath, extname(sourcePath));
+    const files = await readdir(outputDirectory);
+    const exact = files.find((file) => file === `${sourceName}.md`);
+    const fallback = files.find((file) => extname(file).toLowerCase() === '.md');
+    const markdownFile = exact ?? fallback;
+    if (!markdownFile) {
+        throw new Error('Docling did not produce a Markdown output file.');
+    }
+    return readFile(join(outputDirectory, markdownFile), 'utf8');
+};
+const toDoclingError = (error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    const notFound = 'code' in Object(error) && Object(error).code === 'ENOENT';
+    return new Error(notFound
+        ? 'Docling executable not found. Install the Python package and make the `docling` command available in PATH.'
+        : `Docling conversion failed: ${message}`);
+};
+export const convertDocumentWithDocling = async (input) => {
+    const outputDirectory = await mkdtemp(join(tmpdir(), 'brainlink-docling-'));
+    try {
+        await execFileAsync('docling', ['--to', 'md', '--output', outputDirectory, input.path], {
+            maxBuffer: 1024 * 1024 * 50
+        });
+        const markdown = await readConvertedMarkdown(outputDirectory, input.path);
+        return { markdown };
+    }
+    catch (error) {
+        throw toDoclingError(error);
+    }
+    finally {
+        await rm(outputDirectory, { recursive: true, force: true });
+    }
+};

package/dist/mcp/server.js

@@ -1,5 +1,5 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { addNoteInputSchema, addFileInputSchema, addFileTool, addNoteTool, deleteNoteInputSchema, deleteNoteTool, volatileAddInputSchema, volatileAddTool, volatileClearInputSchema, volatileClearTool, dedupeInputSchema, dedupeResolveInputSchema, dedupeResolveTool, dedupeTool, brokenLinksInputSchema, brokenLinksTool, bootstrapInputSchema, bootstrapTool, canonicalizeContextLinksInputSchema, canonicalizeContextLinksTool, contextInputSchema, contextPacksInputSchema, contextPacksTool, contextTool, graphContextsInputSchema, graphContextsTool, graphInputSchema, graphTool, indexInputSchema, indexTool, orphansInputSchema, orphansTool, policyInputSchema, policyTool, recommendationsInputSchema, recommendationsTool, searchInputSchema, searchTool, statsInputSchema, statsTool, syncInputSchema, syncTool, validateInputSchema, validateTool, versionInputSchema, versionTool } from './tools.js';
+import { addNoteInputSchema, addFileInputSchema, addFileTool, addNoteTool, deleteNoteInputSchema, deleteNoteTool, volatileAddInputSchema, volatileAddTool, volatileClearInputSchema, volatileClearTool, dedupeInputSchema, dedupeResolveInputSchema, dedupeResolveTool, dedupeTool, brokenLinksInputSchema, brokenLinksTool, bootstrapInputSchema, bootstrapTool, canonicalizeContextLinksInputSchema, canonicalizeContextLinksTool, contextInputSchema, contextPacksInputSchema, contextPacksTool, contextTool, doctorActionsInputSchema, doctorActionsTool, graphContextsInputSchema, graphContextsTool, graphInputSchema, graphTool, explainInputSchema, explainTool, indexInputSchema, indexTool, inboxAddInputSchema, inboxAddTool, inboxListInputSchema, inboxListTool, inboxProcessInputSchema, inboxProcessTool, orphansInputSchema, orphansTool, policyInputSchema, policyTool, projectInitInputSchema, projectInitTool, recommendationsInputSchema, recommendationsTool, rememberInputSchema, rememberTool, repairLinksInputSchema, repairLinksTool, searchInputSchema, searchTool, sessionCloseInputSchema, sessionCloseTool, statsInputSchema, statsTool, suggestLinksInputSchema, suggestLinksTool, syncInputSchema, syncTool, validateInputSchema, validateTool, versionInputSchema, versionTool } from './tools.js';
 import { getRuntimeVersion } from './runtime.js';
 export const createBrainlinkMcpServer = () => {
     const server = new McpServer({
@@ -43,6 +43,11 @@ export const createBrainlinkMcpServer = () => {
         description: 'Search indexed Brainlink notes with FTS, semantic or hybrid retrieval.',
         inputSchema: searchInputSchema
     }, searchTool);
+    server.registerTool('brainlink_explain', {
+        title: 'Explain Brainlink Search Results',
+        description: 'Explain why indexed notes matched a query, including score components and match reasons.',
+        inputSchema: explainInputSchema
+    }, explainTool);
     server.registerTool('brainlink_dedupe', {
         title: 'Detect Duplicate Notes',
         description: 'Detect possible duplicate notes using exact content hash and semantic similarity scoring.',
@@ -58,6 +63,26 @@ export const createBrainlinkMcpServer = () => {
         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_remember', {
+        title: 'Capture Assisted Brainlink Memory',
+        description: 'Capture durable memory with inferred title, tags and Context Links. Supports dry-run preview before writing.',
+        inputSchema: rememberInputSchema
+    }, rememberTool);
+    server.registerTool('brainlink_inbox_add', {
+        title: 'Add Brainlink Inbox Item',
+        description: 'Capture a quick untriaged memory item tagged for later processing.',
+        inputSchema: inboxAddInputSchema
+    }, inboxAddTool);
+    server.registerTool('brainlink_inbox_list', {
+        title: 'List Brainlink Inbox Items',
+        description: 'List quick untriaged memory items from the vault.',
+        inputSchema: inboxListInputSchema
+    }, inboxListTool);
+    server.registerTool('brainlink_inbox_process', {
+        title: 'Process Brainlink Inbox Items',
+        description: 'Suggest titles, tags and Context Links for untriaged inbox items.',
+        inputSchema: inboxProcessInputSchema
+    }, inboxProcessTool);
     server.registerTool('brainlink_delete_note', {
         title: 'Delete Brainlink Note',
         description: 'Delete a durable Markdown note from the vault after explicit confirmation. Select by title or path; reindexes by default.',
@@ -93,6 +118,11 @@ export const createBrainlinkMcpServer = () => {
         description: 'Read indexed vault statistics, including node, edge and tag totals.',
         inputSchema: statsInputSchema
     }, statsTool);
+    server.registerTool('brainlink_doctor_actions', {
+        title: 'Get Actionable Brainlink Doctor Plan',
+        description: 'Run vault readiness checks and return prioritized executable next actions.',
+        inputSchema: doctorActionsInputSchema
+    }, doctorActionsTool);
     server.registerTool('brainlink_validate', {
         title: 'Validate Brainlink Vault',
         description: 'Validate indexed graph health, including broken links and orphan notes.',
@@ -118,10 +148,30 @@ export const createBrainlinkMcpServer = () => {
         description: 'List unresolved indexed wiki links.',
         inputSchema: brokenLinksInputSchema
     }, brokenLinksTool);
+    server.registerTool('brainlink_suggest_links', {
+        title: 'Suggest Brainlink Links',
+        description: 'Suggest Context Links for content or likely fixes for unresolved wiki links.',
+        inputSchema: suggestLinksInputSchema
+    }, suggestLinksTool);
+    server.registerTool('brainlink_repair_links', {
+        title: 'Repair Brainlink Broken Links',
+        description: 'Repair unresolved wiki links by retargeting safe high-confidence matches or creating placeholder target notes.',
+        inputSchema: repairLinksInputSchema
+    }, repairLinksTool);
     server.registerTool('brainlink_orphans', {
         title: 'List Brainlink Orphans',
         description: 'List indexed notes without incoming or outgoing graph links.',
         inputSchema: orphansInputSchema
     }, orphansTool);
+    server.registerTool('brainlink_session_close', {
+        title: 'Write Brainlink Session Handoff',
+        description: 'Write or preview a session handoff note with vault health and workspace git status.',
+        inputSchema: sessionCloseInputSchema
+    }, sessionCloseTool);
+    server.registerTool('brainlink_project_init', {
+        title: 'Initialize Project Memory',
+        description: 'Seed Brainlink memory from project documents such as AGENTS.md, README.md and architecture docs.',
+        inputSchema: projectInitInputSchema
+    }, projectInitTool);
     return server;
 };