@andespindola/brainlink 0.1.0-beta.7 → 0.1.0-beta.71

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

@@ -0,0 +1,419 @@
+import { access, lstat, mkdir, readFile, rm, symlink, writeFile } from 'node:fs/promises';
+import { execFile } from 'node:child_process';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { promisify } from 'node:util';
+import { loadBrainlinkConfig } from '../../infrastructure/config.js';
+import { getBootstrapPolicy, getBootstrapSessionStatus, getContextSessionStatus, getSessionStatePath, setBootstrapPolicy } from '../../infrastructure/session-state.js';
+import { print } from '../runtime.js';
+const getCodexConfigPath = () => join(homedir(), '.codex', 'config.toml');
+const getMarketplacePath = () => join(homedir(), '.agents', 'plugins', 'marketplace.json');
+const getDefaultPluginSourcePath = () => resolve(process.cwd(), 'plugins', 'brainlink');
+const getPluginSymlinkPath = () => join(homedir(), 'plugins', 'brainlink');
+const execFileAsync = promisify(execFile);
+const toTomlValue = (value) => `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+const removeBrainlinkMcpSection = (content) => {
+    const lines = content.split('\n');
+    const output = [];
+    let skip = false;
+    for (const line of lines) {
+        const sectionMatch = line.match(/^\[(.+)\]\s*$/);
+        if (!skip && sectionMatch?.[1] === 'mcp_servers.brainlink') {
+            skip = true;
+            continue;
+        }
+        if (skip && sectionMatch) {
+            skip = false;
+        }
+        if (!skip) {
+            output.push(line);
+        }
+    }
+    return output.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd();
+};
+const buildBrainlinkMcpSection = (options) => {
+    const envEntries = [];
+    if (options.allowedVaults) {
+        envEntries.push(`BRAINLINK_ALLOWED_VAULTS = ${toTomlValue(options.allowedVaults)}`);
+    }
+    if (options.brainlinkHome) {
+        envEntries.push(`BRAINLINK_HOME = ${toTomlValue(options.brainlinkHome)}`);
+    }
+    return [
+        '[mcp_servers.brainlink]',
+        `command = ${toTomlValue('brainlink-mcp')}`,
+        ...(envEntries.length > 0 ? [`env = { ${envEntries.join(', ')} }`] : [])
+    ].join('\n');
+};
+const upsertCodexMcpConfig = async (configPath, options) => {
+    let existing = '';
+    try {
+        existing = await readFile(configPath, 'utf8');
+    }
+    catch (error) {
+        if (!(error instanceof Error) || !('code' in error) || error.code !== 'ENOENT') {
+            throw error;
+        }
+    }
+    const withoutSection = removeBrainlinkMcpSection(existing);
+    const section = buildBrainlinkMcpSection(options);
+    const merged = `${withoutSection}\n\n${section}\n`.replace(/^\n+/, '');
+    await mkdir(dirname(configPath), { recursive: true, mode: 0o700 });
+    await writeFile(configPath, merged, { encoding: 'utf8', mode: 0o600 });
+};
+const ensurePluginSymlink = async (sourcePath, symlinkPath) => {
+    await access(sourcePath);
+    await mkdir(dirname(symlinkPath), { recursive: true, mode: 0o700 });
+    try {
+        const info = await lstat(symlinkPath);
+        if (info.isSymbolicLink()) {
+            await rm(symlinkPath, { force: true });
+        }
+        else {
+            await rm(symlinkPath, { recursive: true, force: true });
+        }
+    }
+    catch (error) {
+        if (!(error instanceof Error) || !('code' in error) || error.code !== 'ENOENT') {
+            throw error;
+        }
+    }
+    await symlink(sourcePath, symlinkPath);
+};
+const loadMarketplace = async (path) => {
+    try {
+        const content = await readFile(path, 'utf8');
+        const parsed = JSON.parse(content);
+        const plugins = Array.isArray(parsed.plugins) ? parsed.plugins : [];
+        return {
+            name: typeof parsed.name === 'string' ? parsed.name : 'local',
+            interface: {
+                displayName: typeof parsed.interface?.displayName === 'string' ? parsed.interface.displayName : 'Local'
+            },
+            plugins: plugins
+        };
+    }
+    catch (error) {
+        if (!(error instanceof Error) || !('code' in error) || error.code !== 'ENOENT') {
+            throw error;
+        }
+        return {
+            name: 'local',
+            interface: {
+                displayName: 'Local'
+            },
+            plugins: []
+        };
+    }
+};
+const upsertMarketplacePlugin = async (marketplacePath) => {
+    const marketplace = await loadMarketplace(marketplacePath);
+    const pluginEntry = {
+        name: 'brainlink',
+        source: {
+            source: 'local',
+            path: './plugins/brainlink'
+        },
+        policy: {
+            installation: 'AVAILABLE',
+            authentication: 'ON_INSTALL'
+        },
+        category: 'Productivity'
+    };
+    const plugins = marketplace.plugins.filter((plugin) => plugin?.name !== 'brainlink');
+    const next = {
+        ...marketplace,
+        plugins: [...plugins, pluginEntry]
+    };
+    await mkdir(dirname(marketplacePath), { recursive: true, mode: 0o700 });
+    await writeFile(marketplacePath, `${JSON.stringify(next, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+};
+const parseAllowedVaults = (value) => {
+    if (!value) {
+        return undefined;
+    }
+    const normalized = value
+        .split(',')
+        .map((item) => item.trim())
+        .filter(Boolean);
+    return normalized.length > 0 ? normalized.join(',') : undefined;
+};
+export const installAgentIntegration = async (input) => {
+    const codexConfigPath = getCodexConfigPath();
+    const allowedVaults = parseAllowedVaults(input.allowedVaults);
+    const bootstrapPolicy = await setBootstrapPolicy({
+        enforceBootstrap: true,
+        enforceContextFirst: true,
+        autoBootstrapOnRead: true,
+        autoBootstrapOnStartup: true
+    });
+    await upsertCodexMcpConfig(codexConfigPath, {
+        allowedVaults,
+        brainlinkHome: input.brainlinkHome
+    });
+    const warnings = [];
+    const pluginSourcePath = input.pluginPath ? resolve(input.pluginPath) : getDefaultPluginSourcePath();
+    const pluginSymlinkPath = getPluginSymlinkPath();
+    const marketplacePath = getMarketplacePath();
+    if (input.mcpOnly !== true) {
+        try {
+            await ensurePluginSymlink(pluginSourcePath, pluginSymlinkPath);
+            await upsertMarketplacePlugin(marketplacePath);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            warnings.push(`Plugin marketplace setup skipped: ${message}. MCP is configured, but install repository plugin files to enable local gallery auto-discovery.`);
+        }
+    }
+    const selfTestResult = input.selfTest
+        ? await (async () => {
+            const codexConfig = await readFile(codexConfigPath, 'utf8');
+            const mcp = isBrainlinkConfigured(codexConfig);
+            const mcpCommandInPath = await hasMcpCommandInPath();
+            const pluginSymlinkExists = input.mcpOnly === true
+                ? null
+                : await (async () => {
+                    try {
+                        return (await lstat(pluginSymlinkPath)).isSymbolicLink();
+                    }
+                    catch {
+                        return false;
+                    }
+                })();
+            const marketplaceEntryExists = input.mcpOnly === true
+                ? null
+                : (await loadMarketplace(marketplacePath)).plugins.some((plugin) => plugin?.name === 'brainlink');
+            return {
+                ok: mcp.hasMcpSection &&
+                    mcp.hasCommand &&
+                    mcpCommandInPath &&
+                    (input.mcpOnly === true || (Boolean(pluginSymlinkExists) && Boolean(marketplaceEntryExists))),
+                mcpCommandInPath,
+                hasMcpSection: mcp.hasMcpSection,
+                hasCommand: mcp.hasCommand,
+                pluginSymlinkExists,
+                marketplaceEntryExists
+            };
+        })()
+        : undefined;
+    return {
+        installed: true,
+        codexConfigPath,
+        mcpServer: 'brainlink',
+        command: 'brainlink-mcp',
+        bootstrapPolicy,
+        ...(input.mcpOnly !== true ? { pluginSourcePath, pluginSymlinkPath, marketplacePath } : {}),
+        ...(selfTestResult ? { selfTest: selfTestResult } : {}),
+        ...(warnings.length > 0 ? { warnings } : {})
+    };
+};
+const hasMcpCommandInPath = async () => {
+    try {
+        const { stdout } = await execFileAsync('sh', ['-lc', 'command -v brainlink-mcp'], { maxBuffer: 1024 * 1024 });
+        return stdout.trim().length > 0;
+    }
+    catch {
+        return false;
+    }
+};
+const isBrainlinkConfigured = (codexConfig) => {
+    const hasMcpSection = codexConfig.includes('[mcp_servers.brainlink]');
+    const hasCommand = /(^|\n)\s*command\s*=\s*"brainlink-mcp"\s*(\n|$)/m.test(codexConfig);
+    return { hasMcpSection, hasCommand };
+};
+const parseBooleanOption = (value, name) => {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value === 'true') {
+        return true;
+    }
+    if (value === 'false') {
+        return false;
+    }
+    throw new Error(`Invalid value for ${name}: ${value}. Use true or false.`);
+};
+const parsePositiveIntegerOption = (value, name) => {
+    if (value === undefined) {
+        return undefined;
+    }
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error(`Invalid value for ${name}: ${value}. Use a positive integer.`);
+    }
+    return parsed;
+};
+const applyPolicyPreset = (preset) => {
+    if (!preset) {
+        return {};
+    }
+    if (preset === 'fully-auto') {
+        return {
+            enforceBootstrap: true,
+            enforceContextFirst: true,
+            autoBootstrapOnRead: true,
+            autoBootstrapOnStartup: true
+        };
+    }
+    if (preset === 'strict') {
+        return {
+            enforceBootstrap: true,
+            enforceContextFirst: true,
+            autoBootstrapOnRead: false,
+            autoBootstrapOnStartup: false
+        };
+    }
+    throw new Error(`Unknown policy preset: ${preset}. Use "fully-auto" or "strict".`);
+};
+export const registerAgentCommands = (program) => {
+    const agent = program.command('agent').description('install or inspect Brainlink agent integration');
+    agent
+        .command('install')
+        .option('--mcp-only', 'only configure MCP server in Codex config')
+        .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('--self-test', 'run post-install checks and include diagnostics in the result')
+        .option('--json', 'print machine-readable JSON')
+        .description('install Brainlink as default MCP memory integration for the local agent')
+        .action(async (options) => {
+        const result = await installAgentIntegration({
+            mcpOnly: options.mcpOnly,
+            pluginPath: options.pluginPath,
+            allowedVaults: options.allowedVaults,
+            brainlinkHome: options.brainlinkHome,
+            selfTest: options.selfTest
+        });
+        print(options.json, result, () => [
+            `Installed Brainlink MCP at ${result.codexConfigPath}`,
+            ...(options.mcpOnly === true ? [] : [`Plugin symlink: ${result.pluginSymlinkPath}`, `Marketplace: ${result.marketplacePath}`]),
+            ...(result.selfTest ? [`Self-test: ${result.selfTest.ok ? 'ok' : 'failed'}`] : []),
+            ...(result.warnings && result.warnings.length > 0 ? ['Warnings:', ...result.warnings.map((warning) => `- ${warning}`)] : [])
+        ].join('\n'));
+    });
+    agent
+        .command('upgrade')
+        .option('--mcp-only', 'only configure MCP server in Codex config')
+        .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('reapply latest Brainlink agent integration defaults for legacy installs')
+        .action(async (options) => {
+        const result = await installAgentIntegration({
+            mcpOnly: options.mcpOnly,
+            pluginPath: options.pluginPath,
+            allowedVaults: options.allowedVaults,
+            brainlinkHome: options.brainlinkHome,
+            selfTest: true
+        });
+        print(options.json, {
+            upgraded: true,
+            ...result
+        }, () => `Upgraded Brainlink agent integration at ${result.codexConfigPath}. Self-test: ${result.selfTest?.ok ? 'ok' : 'failed'}`);
+    });
+    agent
+        .command('policy')
+        .option('--preset <preset>', 'policy preset: fully-auto or strict')
+        .option('--enforce-bootstrap <true|false>', 'override enforceBootstrap')
+        .option('--enforce-context-first <true|false>', 'override enforceContextFirst')
+        .option('--auto-bootstrap-on-read <true|false>', 'override autoBootstrapOnRead')
+        .option('--auto-bootstrap-on-startup <true|false>', 'override autoBootstrapOnStartup')
+        .option('--stale-after-minutes <minutes>', 'override staleAfterMinutes with positive integer')
+        .option('--json', 'print machine-readable JSON')
+        .description('read or update Brainlink MCP bootstrap policy')
+        .action(async (options) => {
+        const presetPatch = applyPolicyPreset(options.preset);
+        const enforceBootstrap = parseBooleanOption(options.enforceBootstrap, '--enforce-bootstrap');
+        const enforceContextFirst = parseBooleanOption(options.enforceContextFirst, '--enforce-context-first');
+        const autoBootstrapOnRead = parseBooleanOption(options.autoBootstrapOnRead, '--auto-bootstrap-on-read');
+        const autoBootstrapOnStartup = parseBooleanOption(options.autoBootstrapOnStartup, '--auto-bootstrap-on-startup');
+        const staleAfterMinutes = parsePositiveIntegerOption(options.staleAfterMinutes, '--stale-after-minutes');
+        const overridePatch = {
+            ...(enforceBootstrap !== undefined ? { enforceBootstrap } : {}),
+            ...(enforceContextFirst !== undefined ? { enforceContextFirst } : {}),
+            ...(autoBootstrapOnRead !== undefined ? { autoBootstrapOnRead } : {}),
+            ...(autoBootstrapOnStartup !== undefined ? { autoBootstrapOnStartup } : {}),
+            ...(staleAfterMinutes !== undefined ? { staleAfterMinutes } : {})
+        };
+        const patch = {
+            ...presetPatch,
+            ...overridePatch
+        };
+        const policy = Object.keys(patch).length === 0 ? await getBootstrapPolicy() : await setBootstrapPolicy(patch);
+        print(options.json, {
+            policy,
+            ...(options.preset ? { presetApplied: options.preset } : {})
+        }, () => [
+            ...(options.preset ? [`presetApplied=${options.preset}`] : []),
+            `enforceBootstrap=${policy.enforceBootstrap}`,
+            `enforceContextFirst=${policy.enforceContextFirst}`,
+            `autoBootstrapOnRead=${policy.autoBootstrapOnRead}`,
+            `autoBootstrapOnStartup=${policy.autoBootstrapOnStartup}`,
+            `staleAfterMinutes=${policy.staleAfterMinutes}`
+        ].join('\n'));
+    });
+    agent
+        .command('status')
+        .option('-a, --agent <agent>', 'agent memory namespace for bootstrap session status')
+        .option('--json', 'print machine-readable JSON')
+        .description('check if Brainlink MCP integration is configured for the local agent')
+        .action(async (options) => {
+        const codexConfigPath = getCodexConfigPath();
+        let codexConfig = '';
+        try {
+            codexConfig = await readFile(codexConfigPath, 'utf8');
+        }
+        catch (error) {
+            if (!(error instanceof Error) || !('code' in error) || error.code !== 'ENOENT') {
+                throw error;
+            }
+        }
+        const { hasMcpSection, hasCommand } = isBrainlinkConfigured(codexConfig);
+        const pluginSymlinkPath = getPluginSymlinkPath();
+        const marketplacePath = getMarketplacePath();
+        let pluginSymlinkExists = false;
+        let marketplaceEntryExists = false;
+        try {
+            pluginSymlinkExists = (await lstat(pluginSymlinkPath)).isSymbolicLink();
+        }
+        catch { }
+        try {
+            const marketplace = await loadMarketplace(marketplacePath);
+            marketplaceEntryExists = marketplace.plugins.some((plugin) => plugin?.name === 'brainlink');
+        }
+        catch { }
+        const config = await loadBrainlinkConfig();
+        const policy = await getBootstrapPolicy();
+        const bootstrapStatus = await getBootstrapSessionStatus(config.vault, options.agent ?? config.defaultAgent);
+        const contextStatus = await getContextSessionStatus(config.vault, options.agent ?? config.defaultAgent);
+        const sessionStatePath = getSessionStatePath();
+        print(options.json, {
+            configured: hasMcpSection && hasCommand,
+            codexConfigPath,
+            hasMcpSection,
+            hasCommand,
+            pluginSymlinkPath,
+            pluginSymlinkExists,
+            marketplacePath,
+            marketplaceEntryExists,
+            sessionStatePath,
+            vault: config.vault,
+            agent: options.agent ?? config.defaultAgent ?? '*',
+            bootstrapPolicy: policy,
+            bootstrapStatus,
+            contextStatus
+        }, () => [
+            `codexConfigPath=${codexConfigPath}`,
+            `configured=${hasMcpSection && hasCommand}`,
+            `pluginSymlinkExists=${pluginSymlinkExists}`,
+            `marketplaceEntryExists=${marketplaceEntryExists}`,
+            `vault=${config.vault}`,
+            `agent=${options.agent ?? config.defaultAgent ?? '*'}`,
+            `bootstrapReady=${bootstrapStatus.ready}`,
+            `bootstrapStale=${bootstrapStatus.stale}`,
+            `contextReady=${contextStatus.ready}`,
+            `contextStale=${contextStatus.stale}`
+        ].join('\n'));
+    });
+};

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}`,