@andespindola/brainlink 1.0.3 → 1.0.4

package/dist/application/repair-broken-links.js

@@ -0,0 +1,157 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { sanitizeAgentId, sharedAgentId } from '../domain/agents.js';
+import { parseMarkdownDocument } from '../domain/markdown.js';
+import { ensureVault, readMarkdownFileSummaries, writeMarkdownFile } from '../infrastructure/file-system-vault.js';
+import { indexVault } from './index-vault.js';
+import { suggestBrokenLinkFixes } from './memory-suggestions.js';
+const slugify = (title) => title
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'untitled';
+const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const replaceWikiLinkTitle = (content, fromTitle, toTitle) => {
+    const pattern = new RegExp(`\\[\\[${escapeRegExp(fromTitle)}((?:#[^\\]|]+)?(?:\\|[^\\]]+)?)\\]\\]`, 'g');
+    return content.replace(pattern, `[[${toTitle}$1]]`);
+};
+const buildPlaceholderNote = (title, sources, agentId) => [
+    '---',
+    `title: "${title.replaceAll('"', '\\"')}"`,
+    `agent: "${sanitizeAgentId(agentId)}"`,
+    '---',
+    '',
+    `# ${title}`,
+    '',
+    'Auto-created target for unresolved Brainlink wiki links. Replace this placeholder with durable context when the concept is clarified. #triage',
+    '',
+    '## Referenced By',
+    '',
+    ...sources.map((source) => `- [[${source}]]`),
+    ''
+].join('\n');
+const readNotes = async (vaultPath) => {
+    const absoluteVaultPath = await ensureVault(vaultPath);
+    const summaries = await readMarkdownFileSummaries(absoluteVaultPath);
+    return Promise.all(summaries.map(async (summary) => {
+        const content = await readFile(summary.absolutePath, 'utf8');
+        const document = parseMarkdownDocument({
+            absolutePath: summary.absolutePath,
+            vaultPath: absoluteVaultPath,
+            content,
+            createdAt: summary.createdAt,
+            updatedAt: summary.updatedAt
+        });
+        return {
+            relativePath: summary.relativePath,
+            title: document.title,
+            agentId: document.agentId,
+            content
+        };
+    }));
+};
+const isConfident = (candidates, minScore, margin) => {
+    const [best, second] = candidates;
+    if (!best || best.score < minScore)
+        return false;
+    if (!second)
+        return true;
+    return best.score - second.score >= margin;
+};
+export const repairBrokenLinks = async (vaultPath, options = {}) => {
+    const minScore = options.minScore ?? 0.88;
+    const margin = options.margin ?? 0.12;
+    const createMissing = options.createMissing !== false;
+    const suggestions = await suggestBrokenLinkFixes(vaultPath, options.agentId, 5);
+    const notes = await readNotes(vaultPath);
+    const notesByPath = new Map(notes.map((note) => [note.relativePath, note]));
+    const nextContentByPath = new Map();
+    const placeholderSources = new Map();
+    const entries = [];
+    for (const brokenLink of suggestions) {
+        const candidates = brokenLink.candidates;
+        const best = candidates[0];
+        const source = notesByPath.get(brokenLink.fromPath);
+        if (best && isConfident(candidates, minScore, margin)) {
+            const currentContent = nextContentByPath.get(brokenLink.fromPath) ?? source?.content;
+            if (!source || currentContent == null) {
+                entries.push({
+                    ...brokenLink,
+                    action: 'skipped',
+                    targetTitle: null,
+                    targetPath: null,
+                    score: best.score,
+                    reason: 'source note was not found'
+                });
+                continue;
+            }
+            const nextContent = replaceWikiLinkTitle(currentContent, brokenLink.toTitle, best.title);
+            if (nextContent !== currentContent) {
+                nextContentByPath.set(brokenLink.fromPath, nextContent);
+            }
+            entries.push({
+                ...brokenLink,
+                action: 'retargeted',
+                targetTitle: best.title,
+                targetPath: best.path,
+                score: best.score,
+                reason: 'single high-confidence existing title match'
+            });
+            continue;
+        }
+        if (createMissing) {
+            const sourceTitles = placeholderSources.get(brokenLink.toTitle) ?? new Set();
+            sourceTitles.add(brokenLink.fromTitle);
+            placeholderSources.set(brokenLink.toTitle, sourceTitles);
+            entries.push({
+                ...brokenLink,
+                action: 'created-target',
+                targetTitle: brokenLink.toTitle,
+                targetPath: null,
+                score: best?.score ?? null,
+                reason: best ? 'no unambiguous existing target; placeholder target will be created' : 'no existing target candidate; placeholder target will be created'
+            });
+            continue;
+        }
+        entries.push({
+            ...brokenLink,
+            action: 'skipped',
+            targetTitle: null,
+            targetPath: null,
+            score: best?.score ?? null,
+            reason: best ? 'candidate score or margin was too low' : 'no candidate found'
+        });
+    }
+    if (!options.dryRun) {
+        await Promise.all(Array.from(nextContentByPath.entries()).map(([relativePath, content]) => writeMarkdownFile(vaultPath, relativePath, content)));
+        await Promise.all(Array.from(placeholderSources.entries()).map(([title, sources]) => {
+            const agentId = sanitizeAgentId(options.agentId ?? sharedAgentId);
+            const path = join('agents', agentId, 'unresolved-links', `${slugify(title)}.md`).replaceAll('\\', '/');
+            return writeMarkdownFile(vaultPath, path, buildPlaceholderNote(title, Array.from(sources), agentId));
+        }));
+    }
+    const changed = nextContentByPath.size;
+    const created = placeholderSources.size;
+    const index = !options.dryRun && options.autoIndex !== false && (changed > 0 || created > 0)
+        ? await indexVault(vaultPath)
+        : undefined;
+    return {
+        dryRun: options.dryRun === true,
+        scanned: suggestions.length,
+        changed,
+        created,
+        skipped: entries.filter((entry) => entry.action === 'skipped').length,
+        entries: entries.map((entry) => {
+            if (entry.action !== 'created-target' || entry.targetPath) {
+                return entry;
+            }
+            const agentId = sanitizeAgentId(options.agentId ?? sharedAgentId);
+            return {
+                ...entry,
+                targetPath: join('agents', agentId, 'unresolved-links', `${slugify(entry.toTitle)}.md`).replaceAll('\\', '/')
+            };
+        }),
+        ...(index ? { index } : {})
+    };
+};

package/dist/application/server/routes.js

@@ -13,6 +13,7 @@ import { deleteGraphViewState, getGraphViewState, saveGraphViewState } from '../
 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';
@@ -456,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

@@ -17,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';
@@ -1060,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/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;
 };