@andespindola/brainlink 0.1.0-beta.1 → 0.1.0-beta.11

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

@@ -0,0 +1,167 @@
+import { doctorVault } from '../../application/analyze-vault.js';
+import { indexVault } from '../../application/index-vault.js';
+import { migrateVaultContent, shouldMigrateDefaultVault } from '../../application/migrate-vault.js';
+import { defaultBrainlinkConfig, detectVaultConfigSource, loadBrainlinkConfig, loadLegacyLocalRawConfig, loadRawConfig, resolveConfigPath, writeRawConfig } from '../../infrastructure/config.js';
+import { assertVaultAllowed } from '../../infrastructure/file-system-vault.js';
+import { print } from '../runtime.js';
+const resolveScope = (globalOption) => globalOption ? 'global' : 'local';
+const normalizeVaultPath = (vault) => assertVaultAllowed(vault, []);
+const uniqueValues = (values) => Array.from(new Set(values));
+const resolveScopeFromSource = (source) => source === 'global' || source === 'default' ? 'global' : 'local';
+export const registerConfigCommands = (program) => {
+    const configCommand = program.command('config').description('read or update Brainlink configuration');
+    configCommand
+        .command('get [key]')
+        .option('--json', 'print machine-readable JSON')
+        .description('read effective Brainlink config values')
+        .action(async (key, options) => {
+        const config = await loadBrainlinkConfig();
+        if (!key) {
+            print(options.json, config, () => JSON.stringify(config, null, 2));
+            return;
+        }
+        if (!(key in config)) {
+            throw new Error(`Unknown config key: ${key}`);
+        }
+        const value = config[key];
+        print(options.json, { key, value }, () => `${key}=${typeof value === 'string' ? value : JSON.stringify(value)}`);
+    });
+    configCommand
+        .command('set-vault <vault>')
+        .option('--global', 'write to global config in $BRAINLINK_HOME/brainlink.config.json')
+        .option('--no-allowlist', 'do not append the vault to allowedVaults in the target config file')
+        .option('--migrate-from <vault>', 'copy existing Markdown memory from another vault into the configured vault')
+        .option('--no-migrate', 'skip migration step')
+        .option('--no-index', 'skip reindex after migration')
+        .option('--json', 'print machine-readable JSON')
+        .description('set the default vault path in Brainlink config')
+        .action(async (vault, options) => {
+        const scope = resolveScope(options.global);
+        const before = await loadBrainlinkConfig();
+        const targetVault = normalizeVaultPath(vault);
+        const rawConfig = await loadRawConfig(scope);
+        const configPath = resolveConfigPath(scope);
+        const shouldAllowlist = options.allowlist !== false;
+        const nextAllowedVaults = shouldAllowlist
+            ? uniqueValues([...(rawConfig.allowedVaults ?? []), targetVault])
+            : rawConfig.allowedVaults;
+        const nextRawConfig = {
+            ...rawConfig,
+            vault: targetVault,
+            ...(nextAllowedVaults ? { allowedVaults: nextAllowedVaults } : {})
+        };
+        await writeRawConfig(scope, nextRawConfig);
+        const shouldMigrate = options.migrate !== false;
+        const explicitSource = options.migrateFrom ? normalizeVaultPath(options.migrateFrom) : undefined;
+        const shouldAutoMigrate = shouldMigrate &&
+            explicitSource === undefined &&
+            (await shouldMigrateDefaultVault(before.vault, targetVault));
+        const migrationSource = shouldMigrate ? explicitSource ?? (shouldAutoMigrate ? before.vault : undefined) : undefined;
+        const migration = migrationSource ? await migrateVaultContent(migrationSource, targetVault) : undefined;
+        const shouldIndex = options.index !== false && migration !== undefined && migration.copied + migration.conflicted > 0;
+        const index = shouldIndex ? await indexVault(targetVault) : undefined;
+        const after = await loadBrainlinkConfig();
+        print(options.json, {
+            scope,
+            configPath,
+            beforeVault: before.vault,
+            vault: targetVault,
+            migration: migration ?? null,
+            index: index ?? null,
+            config: after
+        }, () => {
+            const migrationMessage = migration
+                ? ` 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.`
+                : '';
+            return `Configured ${scope} vault at ${targetVault} in ${configPath}.${migrationMessage}${indexMessage}`;
+        });
+    });
+    configCommand
+        .command('where')
+        .option('--json', 'print machine-readable JSON')
+        .description('show effective vault path and config file locations')
+        .action(async (options) => {
+        const config = await loadBrainlinkConfig();
+        print(options.json, {
+            vault: config.vault,
+            localConfigPath: resolveConfigPath('local'),
+            globalConfigPath: resolveConfigPath('global'),
+            defaultVault: defaultBrainlinkConfig.vault
+        }, () => [
+            `vault=${config.vault}`,
+            `localConfigPath=${resolveConfigPath('local')}`,
+            `globalConfigPath=${resolveConfigPath('global')}`,
+            `defaultVault=${defaultBrainlinkConfig.vault}`
+        ].join('\n'));
+    });
+    configCommand
+        .command('doctor')
+        .option('--fix', 'apply safe config fixes (without this flag, doctor is dry-run)')
+        .option('--json', 'print machine-readable JSON')
+        .description('inspect effective config sources and run vault readiness checks')
+        .action(async (options) => {
+        const config = await loadBrainlinkConfig();
+        const source = await detectVaultConfigSource();
+        const globalConfigPath = resolveConfigPath('global');
+        const localConfigPath = resolveConfigPath('local');
+        const allowedVaultCheck = assertVaultAllowed(config.vault, config.allowedVaults);
+        const vaultDoctor = await doctorVault(config.vault);
+        const targetScope = resolveScopeFromSource(source);
+        const rawConfig = source === 'local-legacy'
+            ? await loadLegacyLocalRawConfig()
+            : await loadRawConfig(targetScope);
+        const normalizedVault = normalizeVaultPath(typeof rawConfig.vault === 'string' ? rawConfig.vault : config.vault);
+        const normalizedAllowedVaults = uniqueValues([
+            ...(Array.isArray(rawConfig.allowedVaults) ? rawConfig.allowedVaults.filter((item) => typeof item === 'string') : []),
+            normalizedVault
+        ].map((value) => normalizeVaultPath(value)));
+        const nextRawConfig = {
+            ...rawConfig,
+            vault: normalizedVault,
+            allowedVaults: normalizedAllowedVaults
+        };
+        const plannedFixes = [
+            `normalize vault path in ${targetScope} config`,
+            `ensure allowedVaults includes ${normalizedVault}`,
+            ...(source === 'local-legacy' ? ['migrate .brainlink.json settings into brainlink.config.json'] : []),
+            ...(source === 'default' ? ['create global brainlink.config.json with explicit vault'] : [])
+        ];
+        let fixApplied = false;
+        let fixedConfigPath = null;
+        if (options.fix) {
+            fixedConfigPath = await writeRawConfig(targetScope, nextRawConfig);
+            fixApplied = true;
+        }
+        const response = {
+            vault: config.vault,
+            vaultSource: source,
+            allowedVaultCheck,
+            localConfigPath,
+            globalConfigPath,
+            doctor: vaultDoctor,
+            fix: {
+                dryRun: options.fix !== true,
+                applied: fixApplied,
+                scope: targetScope,
+                path: fixedConfigPath,
+                plannedFixes
+            }
+        };
+        print(options.json, response, () => [
+            `vault=${response.vault}`,
+            `vaultSource=${response.vaultSource}`,
+            `localConfigPath=${response.localConfigPath}`,
+            `globalConfigPath=${response.globalConfigPath}`,
+            `configFixDryRun=${response.fix.dryRun}`,
+            ...(response.fix.applied && response.fix.path ? [`configFixAppliedAt=${response.fix.path}`] : []),
+            ...(response.fix.plannedFixes.length > 0 ? ['Planned config fixes:', ...response.fix.plannedFixes.map((step) => `- ${step}`)] : []),
+            ...response.doctor.checks.map((check) => `${check.ok ? 'OK' : 'FAIL'} ${check.name}: ${check.message}`),
+            ...(response.doctor.recommendations && response.doctor.recommendations.length > 0
+                ? ['Recommended next steps:', ...response.doctor.recommendations.map((recommendation) => `- ${recommendation}`)]
+                : [])
+        ].join('\n'));
+    });
+};

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

@@ -1,4 +1,4 @@
-import { getBrokenLinksReport, getOrphansReport, getStats, validateVault } from '../../application/analyze-vault.js';
+import { getBrokenLinksReport, getExtendedStats, getOrphansReport, getStats, validateVault } from '../../application/analyze-vault.js';
 import { buildContextPackage } from '../../application/build-context.js';
 import { getGraph } from '../../application/get-graph.js';
 import { listAgents } from '../../application/list-agents.js';
@@ -12,14 +12,14 @@ export const registerReadCommands = (program) => {
         .argument('<query>', 'search query')
         .option('-v, --vault <vault>', 'vault directory')
         .option('-a, --agent <agent>', 'filter by agent memory namespace')
-        .option('-l, --limit <limit>', 'maximum results', '10')
+        .option('-l, --limit <limit>', 'maximum results')
         .option('-m, --mode <mode>', 'search mode: fts, semantic or hybrid')
         .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.config.defaultSearchLimit), resolved.config.defaultSearchLimit);
-        const mode = sanitizeSearchMode(options.mode, resolved.config.defaultSearchMode);
+        const limit = parsePositiveInteger(options.limit ?? String(resolved.defaults.defaultSearchLimit), resolved.defaults.defaultSearchLimit);
+        const mode = sanitizeSearchMode(options.mode, resolved.defaults.defaultSearchMode);
         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'))
@@ -58,15 +58,15 @@ export const registerReadCommands = (program) => {
         .argument('<query>', 'context query')
         .option('-v, --vault <vault>', 'vault directory')
         .option('-a, --agent <agent>', 'filter by agent memory namespace')
-        .option('-l, --limit <limit>', 'maximum search results before context selection', '12')
-        .option('-t, --tokens <tokens>', 'maximum estimated context tokens', '2000')
+        .option('-l, --limit <limit>', 'maximum search results before context selection')
+        .option('-t, --tokens <tokens>', 'maximum estimated context tokens')
         .option('-m, --mode <mode>', 'search mode: fts, semantic or hybrid')
         .option('--json', 'print machine-readable JSON')
         .description('build a compact context package for an agent')
         .action(async (query, options) => {
         const resolved = await resolveOptions(options);
-        const mode = sanitizeSearchMode(options.mode, resolved.config.defaultSearchMode);
-        const contextPackage = await buildContextPackage(resolved.vault, query, parsePositiveInteger(options.limit ?? '12', 12), parsePositiveInteger(options.tokens ?? String(resolved.config.defaultContextTokens), resolved.config.defaultContextTokens), resolved.agent, mode);
+        const mode = sanitizeSearchMode(options.mode, resolved.defaults.defaultSearchMode);
+        const contextPackage = await buildContextPackage(resolved.vault, query, parsePositiveInteger(options.limit ?? String(resolved.defaults.defaultSearchLimit), resolved.defaults.defaultSearchLimit), parsePositiveInteger(options.tokens ?? String(resolved.defaults.defaultContextTokens), resolved.defaults.defaultContextTokens), resolved.agent, mode);
         print(options.json, contextPackage, () => contextPackage.content);
     });
     program
@@ -94,10 +94,27 @@ export const registerReadCommands = (program) => {
         .command('stats')
         .option('-v, --vault <vault>', 'vault directory')
         .option('-a, --agent <agent>', 'filter by agent memory namespace')
+        .option('--extended', 'include storage, quality and latency observability probes')
         .option('--json', 'print machine-readable JSON')
         .description('print indexed vault statistics')
         .action(async (options) => {
         const resolved = await resolveOptions(options);
+        if (options.extended) {
+            const stats = await getExtendedStats(resolved.vault, resolved.agent);
+            print(options.json, stats, () => [
+                `Documents: ${stats.stats.documentCount}`,
+                `Links: ${stats.stats.linkCount}`,
+                `Resolved links: ${stats.stats.resolvedLinkCount}`,
+                `Broken links: ${stats.stats.brokenLinkCount}`,
+                `Orphans: ${stats.stats.orphanCount}`,
+                `Tags: ${stats.stats.tagCount}`,
+                `Total files: ${stats.storage.totalFileCount}`,
+                `Markdown files: ${stats.storage.markdownFileCount}`,
+                `Vault bytes: ${stats.storage.totalBytes}`,
+                `Latency index/search/context (ms): ${stats.observability.latenciesMs.index}/${stats.observability.latenciesMs.search}/${stats.observability.latenciesMs.context}`
+            ].join('\n'));
+            return;
+        }
         const stats = await getStats(resolved.vault, resolved.agent);
         print(options.json, stats, () => [
             `Documents: ${stats.documentCount}`,

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

@@ -1,11 +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, 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 { 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) {
@@ -20,12 +27,77 @@ export const registerWriteCommands = (program) => {
     program
         .command('init')
         .argument('[vault]', 'vault directory')
+        .option('--migrate-from <vault>', 'copy existing vault content into the initialized vault')
+        .option('--no-migrate-existing', 'skip automatic migration from the default Brainlink vault into an empty custom vault')
         .option('--json', 'print machine-readable JSON')
         .description('initialize a Brainlink vault')
         .action(async (vault, options) => {
         const config = await loadBrainlinkConfig();
-        const path = await ensureVault(assertVaultAllowed(vault ?? config.vault, config.allowedVaults));
-        print(options.json, { path }, () => `Initialized Brainlink vault at ${path}`);
+        const targetVault = assertVaultAllowed(vault ?? config.vault, config.allowedVaults);
+        const path = await ensureVault(targetVault);
+        const explicitSource = options.migrateFrom ? assertVaultAllowed(options.migrateFrom, config.allowedVaults) : undefined;
+        const shouldAutoMigrate = explicitSource === undefined &&
+            options.migrateExisting !== false &&
+            (await shouldMigrateDefaultVault(defaultBrainlinkConfig.vault, targetVault));
+        const migration = explicitSource || shouldAutoMigrate ? await migrateVaultContent(explicitSource ?? defaultBrainlinkConfig.vault, targetVault) : undefined;
+        const index = migration && migration.copied + migration.conflicted > 0 ? await indexVault(targetVault) : undefined;
+        print(options.json, { path, ...(migration ? { migration } : {}), ...(index ? { index } : {}) }, () => {
+            const migrated = migration
+                ? ` Migrated ${migration.copied} files, preserved ${migration.conflicted} conflicts and kept ${migration.unchanged} unchanged files.`
+                : '';
+            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')
@@ -66,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
@@ -117,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/embeddings.js

@@ -58,7 +58,8 @@ const tokenize = (input) => input
     .match(tokenPattern)
     ?.map(normalizeToken)
     .filter((token) => token.length > 1 && !stopWords.has(token)) ?? [];
-const expandTokens = (tokens) => tokens.flatMap((token) => [token, ...(aliases[token] ?? [])]);
+const getAliasesForToken = (token) => Object.hasOwn(aliases, token) ? aliases[token] ?? [] : [];
+const expandTokens = (tokens) => tokens.flatMap((token) => [token, ...getAliasesForToken(token)]);
 const hash = (value) => Array.from(value).reduce((state, char) => Math.imul(state ^ char.charCodeAt(0), 16777619), 2166136261) >>> 0;
 const featureHash = (feature) => {
     const value = hash(feature);

package/dist/domain/graph-layout.js

@@ -45,20 +45,17 @@ const countDegrees = (edges) => edges.reduce((degrees, edge) => {
         ? incrementDegreeBy(incrementDegreeBy(degrees, edge.source, weight), edge.target, weight)
         : incrementDegreeBy(degrees, edge.source, weight);
 }, new Map());
-const uniqueIds = (ids) => Array.from(new Set(ids));
 const createAdjacency = (nodes, edges) => {
     const nodeIds = new Set(nodes.map((node) => node.id));
-    const emptyAdjacency = new Map(nodes.map((node) => [node.id, []]));
-    return edges.reduce((adjacency, edge) => {
+    const adjacency = new Map(nodes.map((node) => [node.id, new Set()]));
+    edges.forEach((edge) => {
         if (!edge.target || !nodeIds.has(edge.source) || !nodeIds.has(edge.target)) {
-            return adjacency;
+            return;
         }
-        return new Map([
-            ...adjacency,
-            [edge.source, uniqueIds([...(adjacency.get(edge.source) ?? []), edge.target])],
-            [edge.target, uniqueIds([...(adjacency.get(edge.target) ?? []), edge.source])]
-        ]);
-    }, emptyAdjacency);
+        adjacency.get(edge.source)?.add(edge.target);
+        adjacency.get(edge.target)?.add(edge.source);
+    });
+    return new Map(Array.from(adjacency.entries(), ([id, neighbors]) => [id, Array.from(neighbors)]));
 };
 const byTitle = (left, right) => left.title.localeCompare(right.title);
 const byDegreeThenTitle = (degrees) => (left, right) => {
@@ -117,10 +114,19 @@ const assignSegments = (nodes, edges, degrees) => {
     }
     return new Map(nodes.map((node) => [node.id, assignments.get(node.id) ?? groupLabel(groupKey(node))]));
 };
-const groupNodesBySegment = (nodes, segments) => nodes.reduce((groups, node) => {
-    const segment = segments.get(node.id) ?? groupLabel(groupKey(node));
-    return new Map([...groups, [segment, [...(groups.get(segment) ?? []), node]]]);
-}, new Map());
+const groupNodesBySegment = (nodes, segments) => {
+    const groups = new Map();
+    nodes.forEach((node) => {
+        const segment = segments.get(node.id) ?? groupLabel(groupKey(node));
+        const bucket = groups.get(segment);
+        if (bucket) {
+            bucket.push(node);
+            return;
+        }
+        groups.set(segment, [node]);
+    });
+    return new Map(groups);
+};
 const segmentAngle = (segment, index, count) => segmentAngles[segment] ?? (Math.PI * 2 * index) / Math.max(count, 1) - Math.PI / 2;
 const createSegmentNodes = (segments, degrees, segmentCount) => ([segment, nodes], segmentIndex) => {
     const sortedNodes = [...nodes].sort(byDegreeThenTitle(degrees));

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,