@andespindola/brainlink 0.1.0-beta.8 → 0.1.0-beta.9

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

@@ -1,13 +1,18 @@
 import { readFileSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, relative, resolve } from 'node:path';
 import { addNote } from '../../application/add-note.js';
+import { buildContextPackage } from '../../application/build-context.js';
 import { indexVault } from '../../application/index-vault.js';
-import { migrateVaultContent, shouldMigrateDefaultVault } from '../../application/migrate-vault.js';
+import { migrateVaultContent, planVaultMigration, previewVaultMigration, shouldMigrateDefaultVault } from '../../application/migrate-vault.js';
 import { startServer } from '../../application/start-server.js';
 import { startVaultWatcher } from '../../application/watch-vault.js';
-import { doctorVault } from '../../application/analyze-vault.js';
-import { defaultBrainlinkConfig } from '../../infrastructure/config.js';
+import { doctorVault, getStats, validateVault } from '../../application/analyze-vault.js';
+import { defaultBrainlinkConfig, sanitizeSearchMode } from '../../infrastructure/config.js';
 import { loadBrainlinkConfig } from '../../infrastructure/config.js';
 import { assertVaultAllowed, ensureVault } from '../../infrastructure/file-system-vault.js';
+import { getBootstrapPolicy, getBootstrapSessionStatus, touchBootstrapSession } from '../../infrastructure/session-state.js';
+import { installAgentIntegration } from './agent-commands.js';
 import { parsePositiveInteger, print, resolveOptions } from '../runtime.js';
 const resolveAddContent = (options) => {
     if (options.content != null && options.content.trim().length > 0) {
@@ -43,6 +48,57 @@ export const registerWriteCommands = (program) => {
             return `Initialized Brainlink vault at ${path}.${migrated}`;
         });
     });
+    program
+        .command('migrate-vault')
+        .option('--from <vault>', 'source vault path')
+        .option('--to <vault>', 'target vault path')
+        .option('--dry-run', 'preview migration without writing files')
+        .option('--report <path>', 'write detailed per-file migration report to JSON file')
+        .option('--no-index', 'skip reindexing target vault after migration')
+        .option('--json', 'print machine-readable JSON')
+        .description('copy markdown memory from one vault to another with conflict preservation')
+        .action(async (options) => {
+        const config = await loadBrainlinkConfig();
+        const sourceVault = assertVaultAllowed(options.from ?? config.vault, config.allowedVaults);
+        const targetVault = assertVaultAllowed(options.to ?? defaultBrainlinkConfig.vault, config.allowedVaults);
+        const sourceRoot = await ensureVault(sourceVault);
+        const targetRoot = await ensureVault(targetVault);
+        const preview = await previewVaultMigration(sourceVault, targetVault);
+        const actions = await planVaultMigration(sourceRoot, targetRoot);
+        const reportEntries = actions.map((action) => ({
+            kind: action.kind,
+            sourcePath: action.sourcePath,
+            sourceRelativePath: relative(sourceRoot, action.sourcePath),
+            targetPath: action.targetPath,
+            targetRelativePath: relative(targetRoot, action.targetPath)
+        }));
+        const writeReport = async () => {
+            if (!options.report) {
+                return null;
+            }
+            const reportPath = resolve(options.report);
+            await mkdir(dirname(reportPath), { recursive: true });
+            await writeFile(reportPath, `${JSON.stringify({ source: sourceVault, target: targetVault, summary: preview, entries: reportEntries }, null, 2)}\n`, 'utf8');
+            return reportPath;
+        };
+        if (options.dryRun) {
+            const reportPath = await writeReport();
+            print(options.json, { dryRun: true, ...preview, entries: reportEntries, ...(reportPath ? { reportPath } : {}) }, () => `Dry run migration ${preview.source} -> ${preview.target}: copy=${preview.copied}, conflicts=${preview.conflicted}, unchanged=${preview.unchanged}${reportPath ? ` report=${reportPath}` : ''}`);
+            return;
+        }
+        const migration = await migrateVaultContent(sourceVault, targetVault);
+        const shouldIndex = options.index !== false && migration.copied + migration.conflicted > 0;
+        const index = shouldIndex ? await indexVault(targetVault) : undefined;
+        const reportPath = await writeReport();
+        print(options.json, { dryRun: false, ...migration, entries: reportEntries, ...(index ? { index } : {}), ...(reportPath ? { reportPath } : {}) }, () => {
+            const summary = `Migrated ${migration.copied} files, preserved ${migration.conflicted} conflicts and kept ${migration.unchanged} unchanged files.`;
+            const indexMessage = index
+                ? ` Indexed ${index.documentCount} documents, ${index.chunkCount} chunks and ${index.linkCount} links.`
+                : '';
+            const reportMessage = reportPath ? ` Report written to ${reportPath}.` : '';
+            return `${summary}${indexMessage}${reportMessage}`;
+        });
+    });
     program
         .command('add')
         .argument('<title>', 'note title')
@@ -82,7 +138,13 @@ export const registerWriteCommands = (program) => {
         .action(async (options) => {
         const resolved = await resolveOptions(options);
         const report = await doctorVault(resolved.vault);
-        print(options.json, report, () => report.checks.map((check) => `${check.ok ? 'OK' : 'FAIL'} ${check.name}: ${check.message}`).join('\n'));
+        print(options.json, report, () => {
+            const checks = report.checks.map((check) => `${check.ok ? 'OK' : 'FAIL'} ${check.name}: ${check.message}`).join('\n');
+            const recommendations = report.recommendations && report.recommendations.length > 0
+                ? `\n\nRecommended next steps:\n${report.recommendations.map((step) => `- ${step}`).join('\n')}`
+                : '';
+            return `${checks}${recommendations}`;
+        });
         process.exitCode = report.ok ? 0 : 1;
     });
     program
@@ -133,4 +195,95 @@ export const registerWriteCommands = (program) => {
         });
         print(options.json, { url: server.url, watch: Boolean(options.watch), readonly: true }, () => `Brainlink graph server running at ${server.url}`);
     });
+    program
+        .command('quickstart')
+        .option('-v, --vault <vault>', 'vault directory')
+        .option('-a, --agent <agent>', 'agent memory namespace')
+        .option('--query <query>', 'optional task query to return immediate grounded context')
+        .option('--mode <mode>', 'search mode for context (fts|semantic|hybrid)')
+        .option('--limit <limit>', 'maximum context sections')
+        .option('--tokens <tokens>', 'maximum context token budget')
+        .option('--no-install-agent', 'skip agent MCP/plugin installation and upgrade automation')
+        .option('--mcp-only', 'when installing agent integration, only configure MCP section')
+        .option('--plugin-path <path>', 'custom source path for Brainlink plugin files')
+        .option('--allowed-vaults <paths>', 'comma separated vault allowlist to inject in MCP env')
+        .option('--brainlink-home <path>', 'BRAINLINK_HOME value to inject in MCP env')
+        .option('--json', 'print machine-readable JSON')
+        .description('run plug-and-play setup for vault, MCP integration and bootstrap readiness')
+        .action(async (options) => {
+        const resolved = await resolveOptions(options);
+        const limit = parsePositiveInteger(options.limit ?? String(resolved.defaults.defaultSearchLimit), resolved.defaults.defaultSearchLimit);
+        const tokens = parsePositiveInteger(options.tokens ?? String(resolved.defaults.defaultContextTokens), resolved.defaults.defaultContextTokens);
+        const mode = sanitizeSearchMode(options.mode, resolved.defaults.defaultSearchMode);
+        const index = await indexVault(resolved.vault);
+        const stats = await getStats(resolved.vault, resolved.agent);
+        const validation = await validateVault(resolved.vault, resolved.agent);
+        const doctor = await doctorVault(resolved.vault);
+        const session = await touchBootstrapSession(resolved.vault, resolved.agent);
+        const policy = await getBootstrapPolicy();
+        const bootstrapStatus = await getBootstrapSessionStatus(resolved.vault, resolved.agent);
+        const context = options.query
+            ? await buildContextPackage(resolved.vault, options.query, limit, tokens, resolved.agent, mode)
+            : null;
+        const agentIntegration = options.installAgent === false
+            ? null
+            : await installAgentIntegration({
+                mcpOnly: options.mcpOnly,
+                pluginPath: options.pluginPath,
+                allowedVaults: options.allowedVaults,
+                brainlinkHome: options.brainlinkHome,
+                selfTest: true
+            });
+        const nextActions = stats.documentCount === 0
+            ? [
+                {
+                    priority: 'required',
+                    command: `blink add "Architecture" --vault "${resolved.vault}" --content "Durable memory with [[Links]] and #tags."`,
+                    reason: 'Seed your vault with at least one durable Markdown note.'
+                },
+                {
+                    priority: 'required',
+                    command: `blink index --vault "${resolved.vault}"`,
+                    reason: 'Rebuild index after adding notes so retrieval can find new memory.'
+                }
+            ]
+            : options.query
+                ? [
+                    {
+                        priority: 'recommended',
+                        command: `blink add "Task Update" --vault "${resolved.vault}" --agent "${resolved.agent ?? 'shared'}" --content "<durable memory>"`,
+                        reason: 'Persist important findings as Markdown notes after using the returned context.'
+                    }
+                ]
+                : [
+                    {
+                        priority: 'recommended',
+                        command: `blink context "<task>" --vault "${resolved.vault}" --agent "${resolved.agent ?? 'shared'}" --mode ${mode}`,
+                        reason: 'Retrieve grounded context for each task before responding.'
+                    }
+                ];
+        print(options.json, {
+            vault: resolved.vault,
+            agent: resolved.agent ?? 'shared',
+            mode,
+            index,
+            stats,
+            validation,
+            doctor,
+            policy,
+            bootstrapStatus,
+            session,
+            context,
+            agentIntegration,
+            nextActions
+        }, () => [
+            `quickstart vault=${resolved.vault}`,
+            `agent=${resolved.agent ?? 'shared'}`,
+            `documents=${stats.documentCount}`,
+            `links=${stats.linkCount}`,
+            `bootstrapReady=${bootstrapStatus.ready}`,
+            ...(agentIntegration?.selfTest ? [`agentIntegrationSelfTest=${agentIntegration.selfTest.ok}`] : []),
+            ...(nextActions.length > 0 ? ['Next actions:', ...nextActions.map((step) => `- ${step.command}`)] : [])
+        ].join('\n'));
+    });
 };

package/dist/cli/main.js

@@ -3,6 +3,8 @@ import { Command } from 'commander';
 import { readFileSync } from 'node:fs';
 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 { registerReadCommands } from './commands/read-commands.js';
 import { registerWriteCommands } from './commands/write-commands.js';
 const readPackageVersion = () => {
@@ -21,6 +23,8 @@ program
     .version(readPackageVersion());
 registerWriteCommands(program);
 registerReadCommands(program);
+registerConfigCommands(program);
+registerAgentCommands(program);
 program.parseAsync().catch((error) => {
     const message = error instanceof Error ? error.message : String(error);
     console.error(message);

package/dist/cli/runtime.js

@@ -1,4 +1,4 @@
-import { loadBrainlinkConfig } from '../infrastructure/config.js';
+import { loadBrainlinkConfig, resolveAgentRuntimeDefaults } from '../infrastructure/config.js';
 import { assertVaultAllowed } from '../infrastructure/file-system-vault.js';
 export const parsePositiveInteger = (value, fallback) => {
     const parsed = Number.parseInt(value, 10);
@@ -8,10 +8,13 @@ export const resolveOptions = async (options) => {
     const config = await loadBrainlinkConfig();
     const vault = options.vault ?? config.vault;
     const allowedVault = assertVaultAllowed(vault, config.allowedVaults);
+    const agent = options.agent ?? config.defaultAgent;
+    const defaults = resolveAgentRuntimeDefaults(config, agent);
     return {
         config,
         vault: allowedVault,
-        agent: options.agent ?? config.defaultAgent
+        agent,
+        defaults
     };
 };
 export const print = (json, value, human) => {

package/dist/domain/markdown.js

@@ -77,11 +77,13 @@ export const extractWikiLinkReferences = (content) => visibleMarkdownLines(conte
     }));
 });
 const priorityFromWeight = (weight) => weight >= 8 ? 'critical' : weight >= 4 ? 'high' : 'normal';
+const normalizeAccumulatedWeight = (weight) => Math.max(1, Math.min(12, weight));
 export const extractWikiLinkWeights = (content) => {
     const weights = extractWikiLinkReferences(content).reduce((state, reference) => {
         const titleKey = reference.title.toLowerCase();
         const current = state.get(titleKey);
-        const weight = (current?.weight ?? 0) + reference.weight;
+        const rawWeight = (current?.weight ?? 0) + reference.weight;
+        const weight = normalizeAccumulatedWeight(rawWeight);
         const explicitPriority = reference.priority
             ? maxPriority(current?.priority ?? reference.priority, reference.priority)
             : current?.priority;
@@ -116,10 +118,38 @@ const normalizeChunkContent = (content) => content
     .join('\n')
     .replace(/\n{3,}/g, '\n\n')
     .trim();
+const splitLongParagraph = (paragraph, maxCharacters) => {
+    if (paragraph.length <= maxCharacters) {
+        return [paragraph];
+    }
+    const sentences = paragraph
+        .split(/(?<=[.!?])\s+/)
+        .map((sentence) => sentence.trim())
+        .filter(Boolean);
+    if (sentences.length <= 1) {
+        const chunks = [];
+        for (let index = 0; index < paragraph.length; index += maxCharacters) {
+            chunks.push(paragraph.slice(index, index + maxCharacters).trim());
+        }
+        return chunks.filter(Boolean);
+    }
+    return sentences.reduce((state, sentence) => {
+        const last = state.at(-1);
+        if (!last) {
+            return [sentence];
+        }
+        const merged = `${last} ${sentence}`;
+        if (merged.length <= maxCharacters) {
+            return [...state.slice(0, -1), merged];
+        }
+        return [...state, sentence];
+    }, []);
+};
 export const splitIntoChunks = (documentId, content, maxCharacters = 1200) => {
     const paragraphs = normalizeChunkContent(stripFrontmatter(content))
         .split(/\n{2,}/)
-        .filter(Boolean);
+        .filter(Boolean)
+        .flatMap((paragraph) => splitLongParagraph(paragraph, maxCharacters));
     const chunks = paragraphs.reduce((state, paragraph) => {
         const lastChunk = state.at(-1);
         if (!lastChunk) {
@@ -162,13 +192,15 @@ export const parseMarkdownDocument = (input) => {
 export const createIndexedDocument = (document, titleToDocumentId, maxChunkCharacters = 1200) => {
     const chunks = splitIntoChunks(document.id, document.content, maxChunkCharacters);
     const linkWeights = new Map(extractWikiLinkWeights(document.content).map((link) => [link.title.toLowerCase(), link]));
-    const links = document.links.map((toTitle) => ({
+    const links = document.links
+        .map((toTitle) => ({
         fromDocumentId: document.id,
         toTitle,
         toDocumentId: titleToDocumentId.get(toTitle.toLowerCase()) ?? null,
         weight: linkWeights.get(toTitle.toLowerCase())?.weight ?? 1,
         priority: linkWeights.get(toTitle.toLowerCase())?.priority ?? 'normal'
-    }));
+    }))
+        .filter((link) => link.toDocumentId !== document.id);
     return {
         document,
         chunks,

package/dist/infrastructure/config.js

@@ -1,7 +1,8 @@
-import { readFile } from 'node:fs/promises';
-import { resolve } from 'node:path';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { homedir } from 'node:os';
 import { sanitizeAgentId } from '../domain/agents.js';
-import { getDefaultVaultPath } from './paths.js';
+import { getBrainlinkHomePath, getDefaultVaultPath } from './paths.js';
 export const defaultBrainlinkConfig = {
     vault: getDefaultVaultPath(),
     host: '127.0.0.1',
@@ -13,15 +14,61 @@ export const defaultBrainlinkConfig = {
     defaultContextTokens: 2000,
     embeddingProvider: 'local',
     defaultSearchMode: 'hybrid',
-    chunkSize: 1200
+    chunkSize: 1200,
+    agentProfiles: {}
 };
 const configFilenames = ['brainlink.config.json', '.brainlink.json'];
+const localConfigFilename = 'brainlink.config.json';
+const globalConfigFilename = 'brainlink.config.json';
+const globalConfigDirectoryMode = 0o700;
+const globalConfigFileMode = 0o600;
+const safeCwd = () => {
+    try {
+        return process.cwd();
+    }
+    catch {
+        return homedir();
+    }
+};
 const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
 const embeddingProviders = new Set(['none', 'local']);
 const searchModes = new Set(['fts', 'semantic', 'hybrid']);
 const sanitizeEmbeddingProvider = (value) => typeof value === 'string' && embeddingProviders.has(value) ? value : defaultBrainlinkConfig.embeddingProvider;
 export const sanitizeSearchMode = (value, fallback = defaultBrainlinkConfig.defaultSearchMode) => typeof value === 'string' && searchModes.has(value) ? value : fallback;
 const sanitizeAllowedVaults = (value) => Array.isArray(value) ? value.filter((item) => typeof item === 'string' && item.trim().length > 0) : [];
+const sanitizePositiveNumber = (value) => typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : undefined;
+const sanitizeAgentProfile = (value) => {
+    if (!isRecord(value)) {
+        return null;
+    }
+    const defaultSearchLimit = sanitizePositiveNumber(value.defaultSearchLimit);
+    const defaultContextTokens = sanitizePositiveNumber(value.defaultContextTokens);
+    const defaultSearchMode = typeof value.defaultSearchMode === 'string' && searchModes.has(value.defaultSearchMode)
+        ? value.defaultSearchMode
+        : undefined;
+    const profile = {
+        ...(defaultSearchLimit ? { defaultSearchLimit } : {}),
+        ...(defaultContextTokens ? { defaultContextTokens } : {}),
+        ...(defaultSearchMode ? { defaultSearchMode } : {})
+    };
+    return Object.keys(profile).length > 0 ? profile : null;
+};
+const sanitizeAgentProfiles = (value) => {
+    if (!isRecord(value)) {
+        return {};
+    }
+    return Object.entries(value).reduce((state, [key, profile]) => {
+        const normalizedKey = key === '*' ? '*' : sanitizeAgentId(key);
+        const sanitizedProfile = sanitizeAgentProfile(profile);
+        if (!sanitizedProfile || normalizedKey.length === 0) {
+            return state;
+        }
+        return {
+            ...state,
+            [normalizedKey]: sanitizedProfile
+        };
+    }, {});
+};
 const readAllowedVaultsFromEnv = () => (process.env.BRAINLINK_ALLOWED_VAULTS ?? '')
     .split(',')
     .map((value) => value.trim())
@@ -39,6 +86,34 @@ const readJsonConfig = async (path) => {
         throw error;
     }
 };
+export const getGlobalConfigPath = () => join(getBrainlinkHomePath(), globalConfigFilename);
+export const getLocalConfigPath = (cwd = safeCwd()) => resolve(cwd, localConfigFilename);
+export const resolveConfigPath = (scope, cwd = safeCwd()) => scope === 'global' ? getGlobalConfigPath() : getLocalConfigPath(cwd);
+export const loadRawConfig = async (scope, cwd = safeCwd()) => readJsonConfig(resolveConfigPath(scope, cwd));
+export const loadLegacyLocalRawConfig = async (cwd = safeCwd()) => readJsonConfig(resolve(cwd, '.brainlink.json'));
+export const detectVaultConfigSource = async (cwd = safeCwd()) => {
+    const [globalConfig, localConfig, legacyLocalConfig] = await Promise.all([
+        loadRawConfig('global', cwd),
+        loadRawConfig('local', cwd),
+        loadLegacyLocalRawConfig(cwd)
+    ]);
+    if (typeof legacyLocalConfig.vault === 'string' && legacyLocalConfig.vault.trim().length > 0) {
+        return 'local-legacy';
+    }
+    if (typeof localConfig.vault === 'string' && localConfig.vault.trim().length > 0) {
+        return 'local';
+    }
+    if (typeof globalConfig.vault === 'string' && globalConfig.vault.trim().length > 0) {
+        return 'global';
+    }
+    return 'default';
+};
+export const writeRawConfig = async (scope, value, cwd = safeCwd()) => {
+    const path = resolveConfigPath(scope, cwd);
+    await mkdir(dirname(path), { recursive: true, mode: globalConfigDirectoryMode });
+    await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode: globalConfigFileMode });
+    return path;
+};
 const sanitizeConfig = (value) => ({
     ...defaultBrainlinkConfig,
     ...value,
@@ -56,11 +131,22 @@ const sanitizeConfig = (value) => ({
     allowedVaults: [...sanitizeAllowedVaults(value.allowedVaults), ...readAllowedVaultsFromEnv()],
     chunkSize: typeof value.chunkSize === 'number' && value.chunkSize > 0 ? value.chunkSize : defaultBrainlinkConfig.chunkSize,
     embeddingProvider: sanitizeEmbeddingProvider(value.embeddingProvider),
-    defaultSearchMode: sanitizeSearchMode(value.defaultSearchMode)
+    defaultSearchMode: sanitizeSearchMode(value.defaultSearchMode),
+    agentProfiles: sanitizeAgentProfiles(value.agentProfiles)
 });
-export const loadBrainlinkConfig = async (cwd = process.cwd()) => {
-    const configs = await Promise.all(configFilenames.map((filename) => readJsonConfig(resolve(cwd, filename))));
-    const merged = configs.reduce((state, config) => ({
+export const resolveAgentRuntimeDefaults = (config, agent) => {
+    const normalizedAgent = agent?.trim().length ? sanitizeAgentId(agent) : undefined;
+    const profile = (normalizedAgent ? config.agentProfiles[normalizedAgent] : undefined) ?? config.agentProfiles['*'];
+    return {
+        defaultSearchLimit: profile?.defaultSearchLimit ?? config.defaultSearchLimit,
+        defaultContextTokens: profile?.defaultContextTokens ?? config.defaultContextTokens,
+        defaultSearchMode: profile?.defaultSearchMode ?? config.defaultSearchMode
+    };
+};
+export const loadBrainlinkConfig = async (cwd = safeCwd()) => {
+    const globalConfig = await readJsonConfig(getGlobalConfigPath());
+    const localConfigs = await Promise.all(configFilenames.map((filename) => readJsonConfig(resolve(cwd, filename))));
+    const merged = [globalConfig, ...localConfigs].reduce((state, config) => ({
         ...state,
         ...config
     }), {});

package/dist/infrastructure/paths.js

@@ -2,8 +2,16 @@ import { homedir } from 'node:os';
 import { isAbsolute, join, resolve } from 'node:path';
 const defaultHomeDirectoryName = '.brainlink';
 const defaultVaultDirectoryName = 'vault';
+const resolveSafeCwd = () => {
+    try {
+        return process.cwd();
+    }
+    catch {
+        return homedir();
+    }
+};
 export const expandHomePath = (path) => path === '~' || path.startsWith('~/') ? join(homedir(), path.slice(2)) : path;
-export const resolvePath = (path, cwd = process.cwd()) => {
+export const resolvePath = (path, cwd = resolveSafeCwd()) => {
     const expandedPath = expandHomePath(path);
     return isAbsolute(expandedPath) ? expandedPath : resolve(cwd, expandedPath);
 };

package/dist/infrastructure/session-state.js

@@ -0,0 +1,117 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { getBrainlinkHomePath } from './paths.js';
+const defaultPolicy = {
+    enforceBootstrap: true,
+    autoBootstrapOnRead: true,
+    autoBootstrapOnStartup: true,
+    staleAfterMinutes: 120
+};
+const defaultState = {
+    policy: defaultPolicy,
+    bootstraps: []
+};
+const sessionStatePath = () => join(getBrainlinkHomePath(), 'session-state.json');
+const normalizeAgent = (agent) => agent?.trim() ? agent.trim() : '*';
+const safePositive = (value, fallback) => typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : fallback;
+const sanitizeState = (value) => {
+    if (typeof value !== 'object' || value === null) {
+        return defaultState;
+    }
+    const record = value;
+    const policyRecord = typeof record.policy === 'object' && record.policy !== null ? record.policy : {};
+    const rawBootstraps = Array.isArray(record.bootstraps) ? record.bootstraps : [];
+    const bootstraps = rawBootstraps.flatMap((entry) => {
+        if (typeof entry !== 'object' || entry === null) {
+            return [];
+        }
+        const row = entry;
+        const vault = typeof row.vault === 'string' && row.vault.trim().length > 0 ? row.vault.trim() : undefined;
+        const agent = typeof row.agent === 'string' && row.agent.trim().length > 0 ? row.agent.trim() : undefined;
+        const lastBootstrappedAt = typeof row.lastBootstrappedAt === 'string' && row.lastBootstrappedAt.trim().length > 0 ? row.lastBootstrappedAt.trim() : undefined;
+        return vault && agent && lastBootstrappedAt ? [{ vault, agent, lastBootstrappedAt }] : [];
+    });
+    return {
+        policy: {
+            enforceBootstrap: typeof policyRecord.enforceBootstrap === 'boolean' ? policyRecord.enforceBootstrap : defaultPolicy.enforceBootstrap,
+            autoBootstrapOnRead: typeof policyRecord.autoBootstrapOnRead === 'boolean'
+                ? policyRecord.autoBootstrapOnRead
+                : defaultPolicy.autoBootstrapOnRead,
+            autoBootstrapOnStartup: typeof policyRecord.autoBootstrapOnStartup === 'boolean'
+                ? policyRecord.autoBootstrapOnStartup
+                : defaultPolicy.autoBootstrapOnStartup,
+            staleAfterMinutes: safePositive(policyRecord.staleAfterMinutes, defaultPolicy.staleAfterMinutes)
+        },
+        bootstraps
+    };
+};
+const readState = async () => {
+    try {
+        const content = await readFile(sessionStatePath(), 'utf8');
+        return sanitizeState(JSON.parse(content));
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            return defaultState;
+        }
+        throw error;
+    }
+};
+const writeState = async (state) => {
+    const path = sessionStatePath();
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    await writeFile(path, `${JSON.stringify(state, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+};
+export const getSessionStatePath = () => sessionStatePath();
+export const getBootstrapPolicy = async () => (await readState()).policy;
+export const setBootstrapPolicy = async (patch) => {
+    const state = await readState();
+    const next = {
+        enforceBootstrap: typeof patch.enforceBootstrap === 'boolean' ? patch.enforceBootstrap : state.policy.enforceBootstrap,
+        autoBootstrapOnRead: typeof patch.autoBootstrapOnRead === 'boolean' ? patch.autoBootstrapOnRead : state.policy.autoBootstrapOnRead,
+        autoBootstrapOnStartup: typeof patch.autoBootstrapOnStartup === 'boolean' ? patch.autoBootstrapOnStartup : state.policy.autoBootstrapOnStartup,
+        staleAfterMinutes: safePositive(patch.staleAfterMinutes, state.policy.staleAfterMinutes)
+    };
+    await writeState({
+        ...state,
+        policy: next
+    });
+    return next;
+};
+export const touchBootstrapSession = async (vault, agent) => {
+    const state = await readState();
+    const normalizedAgent = normalizeAgent(agent);
+    const entry = {
+        vault,
+        agent: normalizedAgent,
+        lastBootstrappedAt: new Date().toISOString()
+    };
+    const bootstraps = [
+        entry,
+        ...state.bootstraps.filter((item) => !(item.vault === entry.vault && item.agent === entry.agent))
+    ].slice(0, 500);
+    await writeState({
+        ...state,
+        bootstraps
+    });
+    return entry;
+};
+export const getBootstrapSessionStatus = async (vault, agent) => {
+    const state = await readState();
+    const normalizedAgent = normalizeAgent(agent);
+    const match = state.bootstraps.find((entry) => entry.vault === vault && entry.agent === normalizedAgent);
+    if (!match) {
+        return {
+            ready: false,
+            stale: true
+        };
+    }
+    const ageMinutes = Math.max(0, (Date.now() - new Date(match.lastBootstrappedAt).getTime()) / 60000);
+    const stale = ageMinutes > state.policy.staleAfterMinutes;
+    return {
+        ready: !stale,
+        stale,
+        lastBootstrappedAt: match.lastBootstrappedAt,
+        ageMinutes
+    };
+};

package/dist/mcp/main.js

@@ -1,9 +1,17 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { createBrainlinkMcpServer } from './server.js';
-const server = createBrainlinkMcpServer();
-const transport = new StdioServerTransport();
-server.connect(transport).catch((error) => {
+import { runStartupBootstrap } from './startup.js';
+const start = async () => {
+    const startup = await runStartupBootstrap();
+    if (startup.error) {
+        console.error(`Brainlink MCP startup bootstrap warning: ${startup.error}`);
+    }
+    const server = createBrainlinkMcpServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+};
+start().catch((error) => {
     const message = error instanceof Error ? error.message : String(error);
     console.error(message);
     process.exitCode = 1;

package/dist/mcp/server.js

@@ -2,7 +2,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { addNoteInputSchema, addFileInputSchema, addFileTool, addNoteTool, brokenLinksInputSchema, brokenLinksTool, contextInputSchema, contextTool, graphInputSchema, graphTool, indexInputSchema, indexTool, orphansInputSchema, orphansTool, searchInputSchema, searchTool, statsInputSchema, statsTool, syncInputSchema, syncTool, validateInputSchema, validateTool } from './tools.js';
+import { addNoteInputSchema, addFileInputSchema, addFileTool, addNoteTool, brokenLinksInputSchema, brokenLinksTool, bootstrapInputSchema, bootstrapTool, contextInputSchema, contextTool, graphInputSchema, graphTool, indexInputSchema, indexTool, orphansInputSchema, orphansTool, policyInputSchema, policyTool, recommendationsInputSchema, recommendationsTool, searchInputSchema, searchTool, statsInputSchema, statsTool, syncInputSchema, syncTool, validateInputSchema, validateTool } from './tools.js';
 const readPackageVersion = () => {
     const packagePath = join(dirname(fileURLToPath(import.meta.url)), '../../package.json');
     const metadata = JSON.parse(readFileSync(packagePath, 'utf8'));
@@ -15,9 +15,24 @@ export const createBrainlinkMcpServer = () => {
         version: readPackageVersion(),
         description: 'Local-first Markdown memory tools for AI agents.'
     });
+    server.registerTool('brainlink_bootstrap', {
+        title: 'Bootstrap Brainlink For A Task (Default Entrypoint)',
+        description: 'Default entrypoint for agents. Run this first to index/check memory state, then optionally retrieve context for the current task query.',
+        inputSchema: bootstrapInputSchema
+    }, bootstrapTool);
+    server.registerTool('brainlink_policy', {
+        title: 'Brainlink Bootstrap Policy',
+        description: 'Read or update bootstrap enforcement policy and inspect bootstrap readiness for the current vault/agent.',
+        inputSchema: policyInputSchema
+    }, policyTool);
+    server.registerTool('brainlink_recommendations', {
+        title: 'Brainlink Recommended MCP Workflow',
+        description: 'Return a plug-and-play action plan for this vault/agent, including policy, bootstrap, context retrieval and durable write guidance.',
+        inputSchema: recommendationsInputSchema
+    }, recommendationsTool);
     server.registerTool('brainlink_context', {
         title: 'Build Brainlink Context',
-        description: 'Read indexed Brainlink memory for a task or question. This is read-only and does not create graph links.',
+        description: 'Read indexed Brainlink memory for a task or question. Usually called after brainlink_bootstrap. This is read-only and does not create graph links.',
         inputSchema: contextInputSchema
     }, contextTool);
     server.registerTool('brainlink_search', {