byterover-cli 3.3.0 → 3.5.0

package/dist/oclif/commands/swarm/onboard.js

@@ -0,0 +1,233 @@
+/* eslint-disable camelcase -- wizard builds YAML-shaped config objects (snake_case keys) */
+import { checkbox, confirm, input, select } from '@inquirer/prompts';
+import { Command } from '@oclif/core';
+import chalk from 'chalk';
+import { load } from 'js-yaml';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { safeValidateSwarmConfig } from '../../../agent/infra/swarm/config/swarm-config-schema.js';
+import { scaffoldConfig } from '../../../agent/infra/swarm/wizard/config-scaffolder.js';
+import { detectProviders } from '../../../agent/infra/swarm/wizard/provider-detector.js';
+import { EscBackError, runMemoryWizard, WizardCancelledError } from '../../../agent/infra/swarm/wizard/swarm-wizard.js';
+import { createEscapeSignal, isEscBack, isForceExit, isPromptCancelled, wizardInputTheme, wizardSelectTheme } from '../../lib/prompt-utils.js';
+/**
+ * Wrap a prompt call with ESC back-navigation support.
+ * If the user presses ESC, throws EscBackError so the wizard goes back one step.
+ * If the user presses Ctrl+C, re-throws so the command exits.
+ */
+async function withEscBack(esc, fn) {
+    try {
+        return await fn(esc.signal);
+    }
+    catch (error) {
+        if (isEscBack(error)) {
+            esc.reset();
+            throw new EscBackError();
+        }
+        if (isForceExit(error)) {
+            throw error;
+        }
+        throw error;
+    }
+}
+/**
+ * Create the real wizard prompts backed by @inquirer/prompts.
+ * Wires createEscapeSignal() for ESC back-navigation on every prompt.
+ */
+function createWizardPrompts(esc) {
+    return {
+        async configureBudget() {
+            const amount = await withEscBack(esc, (signal) => input({
+                default: '50',
+                message: 'Monthly budget cap in dollars:',
+                theme: wizardInputTheme,
+            }, { signal }));
+            const cents = Math.round(Number.parseFloat(amount) * 100);
+            return { globalMonthlyCents: cents };
+        },
+        async configureEnrichment(providerIds) {
+            const providerList = providerIds.filter((id) => id !== 'byterover').join(', ');
+            console.log('');
+            console.log(chalk.bold('Enrichment Topology'));
+            console.log(chalk.dim('─'.repeat(50)));
+            console.log('');
+            console.log('The swarm can run providers in two modes:');
+            console.log('');
+            console.log(`  ${chalk.cyan('Parallel')} (enrichment off)`);
+            console.log('    All providers search independently at the same time.');
+            console.log('    Fastest, but each provider only sees your original query.');
+            console.log('');
+            console.log(`  ${chalk.cyan('Chained')} (enrichment on) ${chalk.green('← recommended')}`);
+            console.log(`    ByteRover searches first, then feeds its results to ${providerList}.`);
+            console.log('    Slightly slower, but downstream providers get richer context');
+            console.log('    from ByteRover\'s structured knowledge.');
+            console.log('');
+            console.log(chalk.dim('How routing interacts with enrichment:'));
+            console.log(chalk.dim('  The router decides WHICH providers handle each query type.'));
+            console.log(chalk.dim('  Enrichment decides the ORDER they run in.'));
+            console.log(chalk.dim('  If a provider is excluded by routing, its enrichment edge is skipped.'));
+            console.log('');
+            return withEscBack(esc, (signal) => confirm({
+                default: true,
+                message: 'Enable enrichment (recommended)?',
+            }, { signal }));
+        },
+        async configureProvider(provider) {
+            const config = {};
+            switch (provider.id) {
+                case 'gbrain': {
+                    config.repo_path = await withEscBack(esc, (signal) => input({
+                        message: 'GBrain brain repository path (your notes/data repo, not the CLI checkout):',
+                        theme: wizardInputTheme,
+                    }, { signal }));
+                    config.search_mode = await withEscBack(esc, (signal) => select({
+                        choices: [
+                            { description: 'Vector + keyword + RRF fusion (best recall, needs OPENAI_API_KEY)', name: 'hybrid (recommended)', value: 'hybrid' },
+                            { description: 'Full-text search only (fast, no API key needed)', name: 'keyword', value: 'keyword' },
+                            { description: 'Vector similarity only (needs OPENAI_API_KEY)', name: 'vector', value: 'vector' },
+                        ],
+                        default: 'hybrid',
+                        message: 'Search mode:',
+                        theme: wizardSelectTheme,
+                    }, { signal }));
+                    break;
+                }
+                case 'hindsight': {
+                    config.connection_string = await withEscBack(esc, (signal) => input({
+                        // eslint-disable-next-line no-template-curly-in-string -- literal ${VAR} placeholder for resolveEnvVars
+                        default: '${HINDSIGHT_DB_URL}',
+                        message: 'Hindsight connection string:',
+                        theme: wizardInputTheme,
+                    }, { signal }));
+                    break;
+                }
+                case 'honcho': {
+                    config.api_key = await withEscBack(esc, (signal) => input({
+                        // eslint-disable-next-line no-template-curly-in-string -- literal ${VAR} placeholder for resolveEnvVars
+                        default: '${HONCHO_API_KEY}',
+                        message: 'Honcho API key (or env var reference):',
+                        theme: wizardInputTheme,
+                    }, { signal }));
+                    config.app_id = await withEscBack(esc, (signal) => input({
+                        message: 'Honcho app ID:',
+                        theme: wizardInputTheme,
+                    }, { signal }));
+                    break;
+                }
+                case 'local-markdown': {
+                    const path = await withEscBack(esc, (signal) => input({
+                        default: provider.path,
+                        message: 'Markdown folder path:',
+                        theme: wizardInputTheme,
+                    }, { signal }));
+                    const name = await withEscBack(esc, (signal) => input({
+                        message: 'Human-readable name for this folder:',
+                        theme: wizardInputTheme,
+                    }, { signal }));
+                    config.folders = [{
+                            follow_wikilinks: true,
+                            name,
+                            path,
+                            read_only: true,
+                        }];
+                    break;
+                }
+                case 'obsidian': {
+                    config.vault_path = await withEscBack(esc, (signal) => input({
+                        default: provider.path,
+                        message: 'Obsidian vault path:',
+                        theme: wizardInputTheme,
+                    }, { signal }));
+                    break;
+                }
+            }
+            return config;
+        },
+        async confirmWrite(summary) {
+            console.log('\n' + chalk.bold('Memory Swarm Configuration Summary:'));
+            console.log(summary);
+            console.log('');
+            return withEscBack(esc, (signal) => confirm({
+                default: true,
+                message: 'Write to .brv/swarm/config.yaml?',
+            }, { signal }));
+        },
+        async selectProviders(detected) {
+            const choices = detected.map((p, index) => {
+                const status = p.detected
+                    ? chalk.green('detected')
+                    : chalk.dim('not found');
+                const detail = p.path ? ` — ${p.path}` : p.envVar ? ` (${p.envVar})` : '';
+                const count = p.noteCount ? ` (${p.noteCount} files)` : '';
+                return {
+                    checked: p.detected,
+                    disabled: p.id === 'byterover' ? '(always on)' : false,
+                    name: `${p.id}${detail}${count} [${status}]`,
+                    value: String(index),
+                };
+            });
+            return withEscBack(esc, (signal) => checkbox({
+                choices,
+                message: 'Select providers to enable:',
+                theme: wizardSelectTheme,
+            }, { signal }));
+        },
+    };
+}
+export default class SwarmOnboard extends Command {
+    static description = 'Set up memory swarm with interactive onboarding wizard';
+    static examples = [
+        '<%= config.bin %> swarm onboard',
+    ];
+    async run() {
+        this.log(chalk.bold('\nMemory Swarm Onboarding'));
+        this.log('Scanning for memory providers...\n');
+        const esc = createEscapeSignal();
+        try {
+            // Step 1: Detect providers
+            const detected = await detectProviders();
+            // Step 2: Run wizard
+            const prompts = createWizardPrompts(esc);
+            const answers = await runMemoryWizard(prompts, detected);
+            // Step 3: Scaffold config
+            const { warnings, yaml: configYaml } = scaffoldConfig(answers);
+            // Surface scaffolding warnings (e.g. duplicate vaults dropped)
+            for (const warning of warnings) {
+                this.log(chalk.yellow(`⚠ ${warning}`));
+            }
+            // Step 4: Write config file
+            const configDir = join(process.cwd(), '.brv', 'swarm');
+            if (!existsSync(configDir)) {
+                mkdirSync(configDir, { recursive: true });
+            }
+            const configPath = join(configDir, 'config.yaml');
+            writeFileSync(configPath, configYaml);
+            this.log(chalk.green(`\n✓ Config written to ${configPath}`));
+            // Step 5: Validate roundtrip
+            const parsed = load(configYaml);
+            const validation = safeValidateSwarmConfig(parsed);
+            if (validation.success) {
+                this.log(chalk.green('✓ Config validated successfully'));
+            }
+            else {
+                this.log(chalk.yellow('⚠ Config validation warning — check the generated file.'));
+            }
+            // Step 6: Suggest next step
+            this.log(`\nRun ${chalk.cyan('brv swarm status')} to verify provider health.`);
+        }
+        catch (error) {
+            if (error instanceof WizardCancelledError) {
+                this.log('\nWizard cancelled. No files were written.');
+                return;
+            }
+            if (isPromptCancelled(error)) {
+                this.log('\nWizard cancelled.');
+                return;
+            }
+            throw error;
+        }
+        finally {
+            esc.cleanup();
+        }
+    }
+}

package/dist/oclif/commands/swarm/query.d.ts

@@ -0,0 +1,14 @@
+import { Command } from '@oclif/core';
+export default class SwarmQuery extends Command {
+    static args: {
+        query: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        explain: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        format: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'max-results': import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}

package/dist/oclif/commands/swarm/query.js

@@ -0,0 +1,84 @@
+import { Args, Command, Flags } from '@oclif/core';
+import { FileSystemService } from '../../../agent/infra/file-system/file-system-service.js';
+import { formatQueryResults, formatQueryResultsExplain, formatQueryResultsJson } from '../../../agent/infra/swarm/cli/query-renderer.js';
+import { loadSwarmConfig } from '../../../agent/infra/swarm/config/swarm-config-loader.js';
+import { buildProvidersFromConfig } from '../../../agent/infra/swarm/provider-factory.js';
+import { SwarmCoordinator } from '../../../agent/infra/swarm/swarm-coordinator.js';
+import { validateSwarmProviders } from '../../../agent/infra/swarm/validation/config-validator.js';
+import { createSearchKnowledgeService } from '../../../agent/infra/tools/implementations/search-knowledge-service.js';
+export default class SwarmQuery extends Command {
+    static args = {
+        query: Args.string({ description: 'Natural language query to search across memory providers', required: true }),
+    };
+    static description = 'Query the memory swarm across all active providers';
+    static examples = [
+        '<%= config.bin %> swarm query "auth tokens"',
+        '<%= config.bin %> swarm query "what changed yesterday" --format json',
+    ];
+    static flags = {
+        explain: Flags.boolean({
+            description: 'Show classification, routing, and enrichment details (ignored with --format json, which always includes all metadata)',
+        }),
+        format: Flags.string({
+            char: 'f',
+            default: 'text',
+            description: 'Output format',
+            options: ['text', 'json'],
+        }),
+        'max-results': Flags.integer({
+            char: 'n',
+            description: 'Maximum number of results',
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(SwarmQuery);
+        const isJson = flags.format === 'json';
+        try {
+            const config = await loadSwarmConfig(process.cwd());
+            // Build a real SearchKnowledgeService so ByteRover can search the context tree.
+            // FileSystemService is lightweight — safe to construct here for CLI use.
+            const workingDirectory = process.cwd();
+            const fileSystemService = new FileSystemService({ workingDirectory });
+            await fileSystemService.initialize();
+            const searchService = createSearchKnowledgeService(fileSystemService, {
+                baseDirectory: workingDirectory,
+            });
+            // Validate enrichment topology — structural errors block execution.
+            // Provider-specific errors (bad paths, missing API keys) are handled
+            // by health checks at runtime, preserving degraded-mode semantics.
+            const validation = await validateSwarmProviders(config);
+            const topologyErrors = validation.errors.filter((e) => e.provider === 'enrichment');
+            if (topologyErrors.length > 0) {
+                const messages = topologyErrors.map((e) => e.message);
+                throw new Error(`Invalid enrichment topology:\n  ${messages.join('\n  ')}`);
+            }
+            const providers = buildProvidersFromConfig(config, { searchService });
+            const coordinator = new SwarmCoordinator(providers, config);
+            // Run health checks so unhealthy providers are skipped
+            await coordinator.refreshHealth();
+            const result = await coordinator.execute({
+                maxResults: flags['max-results'],
+                query: args.query,
+            });
+            if (isJson) {
+                this.log(formatQueryResultsJson(result));
+            }
+            else if (flags.explain) {
+                this.log(formatQueryResultsExplain(result, args.query));
+            }
+            else {
+                this.log(formatQueryResults(result, args.query));
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (isJson) {
+                this.log(JSON.stringify({ error: message, success: false }));
+            }
+            else {
+                this.logToStderr(`Error: ${message}`);
+                this.exit(2);
+            }
+        }
+    }
+}

package/dist/oclif/commands/swarm/status.d.ts

@@ -0,0 +1,41 @@
+import { Command } from '@oclif/core';
+import { loadSwarmConfig } from '../../../agent/infra/swarm/config/swarm-config-loader.js';
+import { detectProviders } from '../../../agent/infra/swarm/wizard/provider-detector.js';
+type DetectedProviders = Awaited<ReturnType<typeof detectProviders>>;
+type SwarmConfig = Awaited<ReturnType<typeof loadSwarmConfig>>;
+/**
+ * Format enrichment edges for display.
+ */
+export declare function formatEnrichmentEdges(edges: Array<{
+    from: string;
+    to: string;
+}>): string[];
+/**
+ * Collect configured paths for path-based providers so we can detect
+ * newly discovered paths that aren't in the config yet.
+ */
+export declare function getConfiguredSwarmPaths(config: SwarmConfig): Set<string>;
+/**
+ * Build user-facing suggestions for detected providers that are not yet configured.
+ */
+export declare function findSwarmStatusSuggestions(config: SwarmConfig, detected: DetectedProviders): string[];
+export default class SwarmStatus extends Command {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        format: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+    private findSuggestions;
+    private renderCascadeNote;
+    private renderEnrichmentTopology;
+    private renderProviderLine;
+    private renderProviderStatusLines;
+    private renderSuggestionLines;
+    private renderSwarmSummary;
+    private renderTextOutput;
+    private renderValidationErrors;
+    private renderValidationWarnings;
+    private renderWriteTargets;
+}
+export {};

package/dist/oclif/commands/swarm/status.js

@@ -0,0 +1,278 @@
+import { Command, Flags } from '@oclif/core';
+import chalk from 'chalk';
+import { loadSwarmConfig } from '../../../agent/infra/swarm/config/swarm-config-loader.js';
+import { validateSwarmProviders } from '../../../agent/infra/swarm/validation/config-validator.js';
+import { detectProviders } from '../../../agent/infra/swarm/wizard/provider-detector.js';
+/**
+ * Format enrichment edges for display.
+ */
+export function formatEnrichmentEdges(edges) {
+    return edges.map((e) => `${e.from} → ${e.to}`);
+}
+/**
+ * Collect configured paths for path-based providers so we can detect
+ * newly discovered paths that aren't in the config yet.
+ */
+export function getConfiguredSwarmPaths(config) {
+    const paths = new Set();
+    const { providers } = config;
+    if (providers.obsidian?.vaultPath) {
+        paths.add(providers.obsidian.vaultPath);
+    }
+    if (providers.localMarkdown?.folders) {
+        for (const folder of providers.localMarkdown.folders) {
+            paths.add(folder.path);
+        }
+    }
+    // GBrain: repoPath is the brain data repo, not the detected CLI checkout path — do not add here.
+    return paths;
+}
+/**
+ * Build user-facing suggestions for detected providers that are not yet configured.
+ */
+export function findSwarmStatusSuggestions(config, detected) {
+    const suggestions = [];
+    const configuredPaths = getConfiguredSwarmPaths(config);
+    for (const provider of detected) {
+        if (!provider.detected)
+            continue;
+        if (provider.id === 'byterover')
+            continue;
+        // GBrain: `provider.path` is the CLI/source checkout; config uses `repoPath` for brain data — never compare.
+        if (provider.id === 'gbrain') {
+            if (!config.providers.gbrain) {
+                const detail = provider.path ? ` at ${provider.path}` : '';
+                suggestions.push(`Found gbrain${detail} — not in config. Run \`brv swarm onboard\` to add it.`);
+            }
+            continue;
+        }
+        if (provider.path) {
+            if (!configuredPaths.has(provider.path)) {
+                suggestions.push(`Found ${provider.id} at ${provider.path} — not in config. Run \`brv swarm onboard\` to add it.`);
+            }
+            continue;
+        }
+        const providerKey = provider.id === 'local-markdown' ? 'localMarkdown' : provider.id;
+        const configured = config.providers[providerKey];
+        if (!configured) {
+            const detail = provider.envVar ? `(${provider.envVar} is set)` : '';
+            suggestions.push(`Found ${provider.id} ${detail} — not in config. Run \`brv swarm onboard\` to add it.`);
+        }
+    }
+    return suggestions;
+}
+export default class SwarmStatus extends Command {
+    static description = 'Show memory swarm provider health and connection status';
+    static examples = [
+        '<%= config.bin %> swarm status',
+        '<%= config.bin %> swarm status --format json',
+    ];
+    static flags = {
+        format: Flags.string({
+            char: 'f',
+            default: 'text',
+            description: 'Output format',
+            options: ['text', 'json'],
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(SwarmStatus);
+        const isJson = flags.format === 'json';
+        try {
+            // Load config
+            const config = await loadSwarmConfig(process.cwd());
+            // Run runtime validation
+            const validation = await validateSwarmProviders(config);
+            // Detect unconfigured providers (proactive suggestions)
+            const detected = await detectProviders();
+            const suggestions = findSwarmStatusSuggestions(config, detected);
+            if (isJson) {
+                this.logJson({
+                    config: {
+                        enrichment: { edges: config.enrichment?.edges ?? [] },
+                        providers: Object.keys(config.providers).filter((k) => config.providers[k]?.enabled),
+                    },
+                    errors: validation.errors,
+                    suggestions,
+                    warnings: validation.warnings,
+                });
+            }
+            else {
+                this.renderTextOutput(config, validation, suggestions);
+            }
+        }
+        catch (error) {
+            if (isJson) {
+                this.logJson({ error: error.message, success: false });
+            }
+            else {
+                this.log(chalk.red(error.message));
+            }
+        }
+    }
+    findSuggestions(config, detected) {
+        return findSwarmStatusSuggestions(config, detected);
+    }
+    renderCascadeNote(validation) {
+        if (!validation.cascadeNote)
+            return;
+        this.log(`\n${chalk.dim('Note:')} ${validation.cascadeNote}`);
+    }
+    renderEnrichmentTopology(config) {
+        const edges = config.enrichment?.edges ?? [];
+        if (edges.length === 0)
+            return;
+        const lines = formatEnrichmentEdges(edges);
+        this.log(`\n${chalk.cyan('Enrichment Topology')}:`);
+        for (const line of lines) {
+            this.log(`  ${line}`);
+        }
+    }
+    renderProviderLine(name, ok, detail, status) {
+        if (status === 'disabled') {
+            this.log(`  ${chalk.dim('—')} ${name.padEnd(15)} ${chalk.dim(detail)}`);
+        }
+        else if (status === 'warning') {
+            this.log(`  ${chalk.yellow('⚠')} ${name.padEnd(15)} ${detail}`);
+        }
+        else if (ok) {
+            this.log(`  ${chalk.green('✓')} ${name.padEnd(15)} ${detail}`);
+        }
+        else {
+            this.log(`  ${chalk.red('✗')} ${name.padEnd(15)} ${detail}`);
+        }
+    }
+    renderProviderStatusLines(config, validation) {
+        const { providers } = config;
+        this.renderProviderLine('ByteRover', providers.byterover.enabled, 'context-tree (always on)');
+        if (providers.obsidian) {
+            const hasError = validation.errors.some((e) => e.provider === 'obsidian');
+            const hasWarning = validation.warnings.some((w) => w.provider === 'obsidian');
+            this.renderProviderLine('Obsidian', providers.obsidian.enabled && !hasError, providers.obsidian.vaultPath, hasWarning ? 'warning' : undefined);
+        }
+        else {
+            this.renderProviderLine('Obsidian', false, 'not configured', 'disabled');
+        }
+        if (providers.localMarkdown) {
+            const hasError = validation.errors.some((e) => e.provider === 'local-markdown');
+            const folderCount = providers.localMarkdown.folders.length;
+            this.renderProviderLine('Local .md', providers.localMarkdown.enabled && !hasError, `${folderCount} folder(s)`);
+        }
+        else {
+            this.renderProviderLine('Local .md', false, 'not configured', 'disabled');
+        }
+        // Honcho and Hindsight temporarily disabled — adapters coming in Phase 3.
+        // When re-enabled, uncomment these blocks:
+        // if (providers.honcho) {
+        //   const hasError = validation.errors.some((e) => e.provider === 'honcho')
+        //   this.renderProviderLine('Honcho', providers.honcho.enabled && !hasError, 'cloud API')
+        // } else {
+        //   this.renderProviderLine('Honcho', false, 'not configured', 'disabled')
+        // }
+        // if (providers.hindsight) {
+        //   const hasError = validation.errors.some((e) => e.provider === 'hindsight')
+        //   this.renderProviderLine('Hindsight', providers.hindsight.enabled && !hasError, 'Postgres')
+        // } else {
+        //   this.renderProviderLine('Hindsight', false, 'not configured', 'disabled')
+        // }
+        if (providers.gbrain) {
+            const hasError = validation.errors.some((e) => e.provider === 'gbrain');
+            this.renderProviderLine('GBrain', providers.gbrain.enabled && !hasError, providers.gbrain.repoPath);
+        }
+        else {
+            this.renderProviderLine('GBrain', false, 'not configured', 'disabled');
+        }
+        if (providers.memoryWiki) {
+            const hasError = validation.errors.some((e) => e.provider === 'memory-wiki');
+            this.renderProviderLine('Memory Wiki', providers.memoryWiki.enabled && !hasError, providers.memoryWiki.vaultPath);
+        }
+        else {
+            this.renderProviderLine('Memory Wiki', false, 'not configured', 'disabled');
+        }
+    }
+    renderSuggestionLines(suggestions) {
+        if (suggestions.length === 0)
+            return;
+        this.log(`\n${chalk.cyan('Suggestions')}:`);
+        for (const suggestion of suggestions) {
+            this.log(`  • ${suggestion}`);
+        }
+    }
+    renderSwarmSummary(config, validation) {
+        const { providers } = config;
+        const enabledCount = [
+            providers.byterover.enabled,
+            providers.obsidian?.enabled,
+            providers.localMarkdown?.enabled,
+            // Honcho and Hindsight temporarily disabled
+            providers.gbrain?.enabled,
+            providers.memoryWiki?.enabled,
+        ].filter(Boolean).length;
+        const totalProviders = [
+            true, // byterover always counts
+            providers.obsidian !== undefined,
+            providers.localMarkdown !== undefined,
+            providers.gbrain !== undefined,
+            providers.memoryWiki !== undefined,
+        ].filter(Boolean).length;
+        const errorCount = validation.errors.length;
+        const status = errorCount === 0
+            ? chalk.green('operational')
+            : chalk.yellow('degraded');
+        this.log(`\nSwarm is ${status} (${enabledCount}/${totalProviders} providers configured).`);
+    }
+    renderTextOutput(config, validation, suggestions) {
+        this.log(chalk.bold('\nMemory Swarm Health Check'));
+        this.log('═'.repeat(40));
+        this.renderProviderStatusLines(config, validation);
+        this.renderEnrichmentTopology(config);
+        this.renderWriteTargets(config);
+        this.renderValidationErrors(validation);
+        this.renderValidationWarnings(validation);
+        this.renderCascadeNote(validation);
+        this.renderSuggestionLines(suggestions);
+        this.renderSwarmSummary(config, validation);
+    }
+    renderValidationErrors(validation) {
+        if (validation.errors.length === 0)
+            return;
+        this.log(`\n${chalk.red('Errors')} (${validation.errors.length}):`);
+        for (const [i, error] of validation.errors.entries()) {
+            this.log(`  ${i + 1}. ${error.provider ?? 'config'}: ${error.message}`);
+            if (error.suggestion) {
+                this.log(`     ${chalk.dim(error.suggestion)}`);
+            }
+        }
+    }
+    renderValidationWarnings(validation) {
+        if (validation.warnings.length === 0)
+            return;
+        this.log(`\n${chalk.yellow('Warnings')} (${validation.warnings.length}):`);
+        for (const [i, warning] of validation.warnings.entries()) {
+            this.log(`  ${i + 1}. ${warning.provider ?? 'config'}: ${warning.message}`);
+        }
+    }
+    renderWriteTargets(config) {
+        const { providers } = config;
+        const targets = [];
+        if (providers.gbrain?.enabled) {
+            targets.push('gbrain (entity, general)');
+        }
+        if (providers.localMarkdown?.enabled) {
+            for (const folder of providers.localMarkdown.folders) {
+                if (!folder.readOnly) {
+                    targets.push(`local-markdown:${folder.name} (note, general)`);
+                }
+            }
+        }
+        if (providers.memoryWiki?.enabled) {
+            targets.push(`memory-wiki (${providers.memoryWiki.writePageType ?? 'concept'}, entity)`);
+        }
+        if (targets.length === 0)
+            return;
+        this.log(`\n${chalk.cyan('Write Targets')}:`);
+        for (const target of targets) {
+            this.log(`  ${target}`);
+        }
+    }
+}

package/dist/server/constants.d.ts

@@ -66,5 +66,6 @@ export declare const OVERVIEW_EXTENSION = ".overview.md";
 export declare const MANIFEST_FILE = "_manifest.json";
 export declare const ARCHIVE_IMPORTANCE_THRESHOLD = 35;
 export declare const DEFAULT_GHOST_CUE_MAX_TOKENS = 220;
-/** .gitignore content for the context tree — ignore derived artifacts only */
-export declare const CONTEXT_TREE_GITIGNORE = "# Derived artifacts \u2014 do not track\n.gitignore\n.snapshot.json\n_manifest.json\n_index.md\n*.abstract.md\n*.overview.md\n";
+/** Patterns the context-tree .gitignore must contain (derived artifacts only). */
+export declare const CONTEXT_TREE_GITIGNORE_PATTERNS: string[];
+export declare const CONTEXT_TREE_GITIGNORE_HEADER = "# Derived artifacts \u2014 do not track";