@andespindola/brainlink 1.0.3 → 1.0.5

package/dist/application/operational-workflows.js

@@ -0,0 +1,153 @@
+import { execFile } from 'node:child_process';
+import { access, readFile } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { promisify } from 'node:util';
+import { addNoteWithMetadata } from './add-note.js';
+import { doctorVault, getStats, validateVault } from './analyze-vault.js';
+import { indexVault } from './index-vault.js';
+import { buildRememberSuggestion } from './memory-suggestions.js';
+import { ensureVault } from '../infrastructure/file-system-vault.js';
+const execFileAsync = promisify(execFile);
+const readIfExists = async (path) => {
+    try {
+        await access(path);
+        return readFile(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+};
+const tryGitStatus = async (cwd) => {
+    try {
+        const { stdout } = await execFileAsync('git', ['status', '--short'], { cwd });
+        return stdout.trim();
+    }
+    catch {
+        return '';
+    }
+};
+export const buildActionableDoctor = async (vaultPath) => {
+    const [doctor, validation] = await Promise.all([
+        doctorVault(vaultPath),
+        validateVault(vaultPath)
+    ]);
+    const actions = [
+        ...(doctor.recommendations ?? []).map((recommendation) => ({
+            severity: 'warning',
+            command: recommendation.startsWith('Vault is empty') ? recommendation.replace(/^Vault is empty\. Add your first note: /, '') : recommendation,
+            reason: 'doctor recommendation'
+        })),
+        ...(validation.brokenLinks.length > 0
+            ? [{
+                    severity: 'warning',
+                    command: `blink repair-links --vault "${vaultPath}"`,
+                    reason: `${validation.brokenLinks.length} unresolved wiki links can be safely repaired or materialized as placeholder targets`
+                }]
+            : []),
+        ...(validation.orphans.length > 0
+            ? [{
+                    severity: 'info',
+                    command: `blink suggest-links --vault "${vaultPath}"`,
+                    reason: `${validation.orphans.length} notes have no incoming or outgoing links`
+                }]
+            : []),
+        {
+            severity: doctor.ok ? 'info' : 'critical',
+            command: `blink index --vault "${vaultPath}"`,
+            reason: 'keep derived index synchronized with Markdown source'
+        }
+    ];
+    return {
+        doctor,
+        validation,
+        actions
+    };
+};
+export const closeSession = async (input) => {
+    const [stats, validation, gitStatus] = await Promise.all([
+        getStats(input.vaultPath, input.agentId),
+        validateVault(input.vaultPath, input.agentId),
+        tryGitStatus(input.cwd)
+    ]);
+    const date = new Date().toISOString().slice(0, 10);
+    const title = `Session Close ${basename(input.cwd)} ${date}`;
+    const content = [
+        input.content?.trim() ? `## Notes\n\n${input.content.trim()}` : null,
+        '## Vault State',
+        `- Documents: ${stats.documentCount}`,
+        `- Links: ${stats.linkCount}`,
+        `- Broken links: ${stats.brokenLinkCount}`,
+        `- Orphans: ${stats.orphanCount}`,
+        gitStatus ? `\n## Git Status\n\n\`\`\`txt\n${gitStatus}\n\`\`\`` : null,
+        validation.brokenLinks.length > 0
+            ? `\n## Follow Up\n\n- Review unresolved links with \`blink suggest-links --broken\`.`
+            : null,
+        '\n#session #handoff'
+    ].filter((part) => Boolean(part)).join('\n');
+    const suggestion = await buildRememberSuggestion({
+        vaultPath: input.vaultPath,
+        content,
+        agentId: input.agentId,
+        title,
+        tags: ['session', 'handoff'],
+        linkLimit: 5
+    });
+    if (input.write === false) {
+        return {
+            title,
+            content: suggestion.content,
+            writtenPath: null,
+            index: null
+        };
+    }
+    const note = await addNoteWithMetadata(input.vaultPath, title, suggestion.content, input.agentId, {
+        autoContextLinks: false
+    });
+    const index = input.autoIndex === false ? null : await indexVault(input.vaultPath);
+    return {
+        title,
+        content: suggestion.content,
+        writtenPath: note.path,
+        index
+    };
+};
+export const initializeProjectMemory = async (input) => {
+    const vault = await ensureVault(input.vaultPath);
+    const candidates = ['AGENTS.md', 'README.md', 'docs/ARCHITECTURE.md', 'docs/QUICKSTART.md'];
+    const contents = await Promise.all(candidates.map(async (relativePath) => ({
+        relativePath,
+        content: await readIfExists(join(input.projectPath, relativePath))
+    })));
+    const available = contents.filter((item) => item.content !== null);
+    const fallback = available.length > 0
+        ? []
+        : [{
+                relativePath: 'Project Overview',
+                content: `Project path: ${input.projectPath}\n\n#project #memory`
+            }];
+    const notes = await Promise.all([...available, ...fallback].map(async (item) => {
+        const title = `Project ${basename(input.projectPath)} ${item.relativePath.replace(/\.md$/i, '').replace(/[\\/]/g, ' ')}`;
+        const suggestion = await buildRememberSuggestion({
+            vaultPath: input.vaultPath,
+            content: `${item.content.trim()}\n\n#project #memory`,
+            agentId: input.agentId,
+            title,
+            tags: ['project', 'memory'],
+            linkLimit: 5
+        });
+        const note = await addNoteWithMetadata(input.vaultPath, title, suggestion.content, input.agentId, {
+            autoContextLinks: false
+        });
+        return {
+            title,
+            path: note.path
+        };
+    }));
+    const index = await indexVault(input.vaultPath);
+    return {
+        projectPath: input.projectPath,
+        vault,
+        notes,
+        index
+    };
+};

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';
@@ -23,19 +24,20 @@ 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 readRuntimeDefaults = async (url) => {
     const config = await loadBrainlinkConfig();
-    const defaults = resolveAgentRuntimeDefaults(config, readAgentQuery(url));
+    return resolveAgentRuntimeDefaults(config, readAgentQuery(url));
+};
+const readSearchMode = async (url) => {
+    const defaults = await readRuntimeDefaults(url);
     return sanitizeSearchMode(url.searchParams.get('mode'), defaults.defaultSearchMode);
 };
 const readContextStrategy = async (url) => {
-    const config = await loadBrainlinkConfig();
-    const defaults = resolveAgentRuntimeDefaults(config, readAgentQuery(url));
+    const defaults = await readRuntimeDefaults(url);
     return sanitizeContextStrategy(url.searchParams.get('strategy'), defaults.defaultContextStrategy);
 };
 const readContextCacheTtlMs = async (url) => {
-    const config = await loadBrainlinkConfig();
-    const defaults = resolveAgentRuntimeDefaults(config, readAgentQuery(url));
+    const defaults = await readRuntimeDefaults(url);
     return defaults.defaultContextCacheTtlMs;
 };
 const hasInvalidSearchMode = (url) => {
@@ -427,7 +429,8 @@ export const route = async (request, url, vaultPath) => {
     }
     if (isReadMethod(request) && url.pathname === '/api/search') {
         const query = url.searchParams.get('q') ?? '';
-        const limit = parsePositiveInteger(url.searchParams.get('limit'), 10);
+        const defaults = await readRuntimeDefaults(url);
+        const limit = parsePositiveInteger(url.searchParams.get('limit'), defaults.defaultSearchLimit);
         const mode = await readSearchMode(url);
         if (hasInvalidSearchMode(url)) {
             return createResponse(createJsonResponse({ error: 'Invalid mode. Use fts, semantic or hybrid.' }), 400, contentTypes['.json']);
@@ -436,8 +439,9 @@ export const route = async (request, url, vaultPath) => {
     }
     if (isReadMethod(request) && url.pathname === '/api/context') {
         const query = url.searchParams.get('q') ?? '';
-        const limit = parsePositiveInteger(url.searchParams.get('limit'), 12);
-        const tokens = parsePositiveInteger(url.searchParams.get('tokens'), 2000);
+        const defaults = await readRuntimeDefaults(url);
+        const limit = parsePositiveInteger(url.searchParams.get('limit'), defaults.defaultSearchLimit);
+        const tokens = parsePositiveInteger(url.searchParams.get('tokens'), defaults.defaultContextTokens);
         const mode = await readSearchMode(url);
         const strategy = await readContextStrategy(url);
         const contextCacheTtlMs = await readContextCacheTtlMs(url);
@@ -456,6 +460,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;
+    });
+};