@kolmo/scout 0.1.0

package/dist/api/kolmoApiClient.d.ts

@@ -0,0 +1,2 @@
+import type { ScoutManifest } from '../types.js';
+export declare function sendManifest(manifest: ScoutManifest, apiUrl: string, portfolioName?: string): Promise<unknown>;

package/dist/api/kolmoApiClient.js

@@ -0,0 +1,25 @@
+import { getToken } from '../config/authConfig.js';
+export async function sendManifest(manifest, apiUrl, portfolioName) {
+    const url = `${apiUrl}/api/scout/manifest`;
+    const token = getToken();
+    const headers = { 'Content-Type': 'application/json' };
+    if (token)
+        headers['X-Kolmo-Token'] = token;
+    const payload = portfolioName
+        ? { manifest, portfolio_name: portfolioName }
+        : { manifest };
+    const response = await fetch(url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(payload),
+    });
+    if (response.status === 401) {
+        throw new Error('Not authenticated. Run `kolmo auth --token <your-token>` first.\n' +
+            'Generate a token in the Kolmo web app under Settings → Scout → CLI Tokens.');
+    }
+    if (!response.ok) {
+        const text = await response.text();
+        throw new Error(`Kolmo API error ${response.status}: ${text}`);
+    }
+    return response.json();
+}

package/dist/commands/auth.d.ts

@@ -0,0 +1,6 @@
+export interface AuthOptions {
+    token: string;
+    apiUrl: string;
+}
+export declare function runAuth(options: AuthOptions): Promise<void>;
+export declare function runLogout(): Promise<void>;

package/dist/commands/auth.js

@@ -0,0 +1,41 @@
+import chalk from 'chalk';
+import { readConfig, writeConfig } from '../config/authConfig.js';
+export async function runAuth(options) {
+    const token = options.token.trim();
+    if (!token.startsWith('ksc_')) {
+        console.error(chalk.red('Invalid token format. Kolmo Scout tokens start with ksc_'));
+        console.error(chalk.gray('Generate one at: Settings → Scout → CLI Tokens'));
+        process.exit(1);
+    }
+    // Validate against backend before saving
+    console.log(chalk.gray('Validating token…'));
+    try {
+        const res = await fetch(`${options.apiUrl}/api/scout/sessions?limit=1`, {
+            headers: { 'X-Kolmo-Token': token },
+        });
+        if (res.status === 401) {
+            console.error(chalk.red('Token is invalid or has been revoked.'));
+            process.exit(1);
+        }
+        if (!res.ok) {
+            console.error(chalk.red(`Backend returned ${res.status}. Check --api-url.`));
+            process.exit(1);
+        }
+    }
+    catch (err) {
+        console.error(chalk.red(`Could not reach Kolmo backend at ${options.apiUrl}`));
+        console.error(chalk.gray('Check --api-url or that the backend is running.'));
+        process.exit(1);
+    }
+    const existing = readConfig();
+    writeConfig({ ...existing, token, api_url: options.apiUrl });
+    console.log(chalk.green('✔ Authenticated'));
+    console.log(chalk.bold('Token saved to:'), chalk.cyan('~/.kolmo/config.json'));
+    console.log('');
+    console.log(chalk.gray('You can now run:'), chalk.bold('kolmo scan'));
+}
+export async function runLogout() {
+    const { clearToken } = await import('../config/authConfig.js');
+    clearToken();
+    console.log(chalk.green('✔ Logged out — token removed from ~/.kolmo/config.json'));
+}

package/dist/commands/explain.d.ts

@@ -0,0 +1,2 @@
+import type { ExplainOptions } from '../types.js';
+export declare function runExplain(options: ExplainOptions): Promise<void>;

package/dist/commands/explain.js

@@ -0,0 +1,95 @@
+import { existsSync } from 'fs';
+import { readFile } from 'fs/promises';
+import path from 'path';
+import chalk from 'chalk';
+import { buildScoutManifest } from '../manifest/buildScoutManifest.js';
+export async function runExplain(options) {
+    try {
+        const { manifest, source } = await loadManifest(options.dir);
+        if (options.json) {
+            console.log(JSON.stringify({ source, manifest, explanations: manifest.explanations }, null, 2));
+            return;
+        }
+        printExplanation(manifest, source);
+    }
+    catch (err) {
+        console.error(chalk.red(`Explain failed: ${String(err)}`));
+        process.exit(1);
+    }
+}
+async function loadManifest(dir) {
+    const cwd = dir ? path.resolve(dir) : process.cwd();
+    const configPath = path.join(cwd, 'kolmo.config.json');
+    if (existsSync(configPath)) {
+        const content = await readFile(configPath, 'utf-8');
+        return { manifest: JSON.parse(content), source: configPath };
+    }
+    const result = await buildScoutManifest({ dir: cwd });
+    return { manifest: result.manifest, source: 'fresh scan (not written)' };
+}
+function printExplanation(manifest, source) {
+    const explanations = manifest.explanations;
+    console.log(chalk.bold('Kolmo Scout explanation'));
+    console.log(chalk.bold('Source:'), chalk.gray(source));
+    console.log(chalk.bold('Project:'), manifest.project_name);
+    console.log(chalk.bold('Type:'), manifest.project_type);
+    console.log(chalk.bold('Summary:'), manifest.repo_summary);
+    console.log(chalk.bold('Summary source:'), manifest.summary_source ?? 'unknown');
+    console.log('');
+    console.log(chalk.bold('Why this project type'));
+    for (const reason of explanations?.project_type_reasons ?? ['No project-type explanation available.']) {
+        console.log(`  ${chalk.cyan('•')} ${reason}`);
+    }
+    console.log('');
+    console.log(chalk.bold('Detected assets'));
+    if ((explanations?.asset_evidence ?? []).length === 0) {
+        console.log(`  ${chalk.gray('none')}`);
+    }
+    else {
+        for (const asset of explanations.asset_evidence) {
+            const meta = [asset.family, asset.exchange, asset.region, asset.hub].filter(Boolean).join(' / ');
+            console.log(`  ${chalk.cyan('•')} ${chalk.bold(asset.symbol)} ${chalk.gray(meta)}`);
+            for (const evidence of asset.evidence.slice(0, 4)) {
+                const file = evidence.file ? `${evidence.file}: ` : '';
+                console.log(`    ${chalk.gray('-')} ${file}${evidence.source} "${evidence.value}" matched "${evidence.pattern}"`);
+            }
+        }
+    }
+    console.log('');
+    console.log(chalk.bold('File classifications'));
+    for (const file of (explanations?.file_type_reasons ?? []).slice(0, 20)) {
+        const evidence = file.evidence.length ? chalk.gray(` (${file.evidence.slice(0, 4).join(', ')})`) : '';
+        console.log(`  ${chalk.cyan('•')} ${file.path}: ${chalk.yellow(file.detected_type)} - ${file.reason}${evidence}`);
+    }
+    console.log('');
+    console.log(chalk.bold('Data quality profile'));
+    const profiledFiles = manifest.detected_files.filter((file) => file.metadata?.profile);
+    if (profiledFiles.length === 0) {
+        console.log(`  ${chalk.gray('No tabular profiles available.')}`);
+    }
+    else {
+        for (const file of profiledFiles.slice(0, 12)) {
+            const profile = file.metadata.profile;
+            const bits = [
+                profile.frequency_guess ? `freq=${profile.frequency_guess}` : '',
+                profile.latest_date ? `latest=${profile.latest_date}` : '',
+                profile.is_stale != null ? `stale=${profile.is_stale}` : '',
+                profile.missingness_estimate != null ? `missing=${profile.missingness_estimate}` : '',
+                Array.isArray(profile.tenor_gaps) && profile.tenor_gaps.length > 0
+                    ? `tenor_gaps=${profile.tenor_gaps.join(',')}`
+                    : '',
+            ].filter(Boolean);
+            console.log(`  ${chalk.cyan('•')} ${file.path}: ${bits.join(' | ') || 'profile captured'}`);
+        }
+    }
+    console.log('');
+    console.log(chalk.bold('Workflow reasons'));
+    for (const reason of explanations?.workflow_reasons ?? []) {
+        console.log(`  ${chalk.cyan('•')} ${reason}`);
+    }
+    console.log('');
+    console.log(chalk.bold('Evidence citations'));
+    for (const citation of explanations?.evidence_citations ?? []) {
+        console.log(`  ${chalk.cyan('•')} ${citation}`);
+    }
+}

package/dist/commands/scan.d.ts

@@ -0,0 +1,2 @@
+import type { ScanOptions } from '../types.js';
+export declare function runScan(options: ScanOptions): Promise<void>;

package/dist/commands/scan.js

@@ -0,0 +1,151 @@
+import { createInterface } from 'readline/promises';
+import chalk from 'chalk';
+import ora from 'ora';
+import { buildScoutManifest, normalizeSummary } from '../manifest/buildScoutManifest.js';
+import { writeKolmoConfig } from '../config/writeKolmoConfig.js';
+import { sendManifest } from '../api/kolmoApiClient.js';
+export async function runScan(options) {
+    const spinner = ora('Scanning project...').start();
+    try {
+        const { cwd, allFiles, hasEnv, manifest } = await buildScoutManifest({
+            dir: options.dir,
+            summary: options.summary,
+        });
+        if (options.verbose && hasEnv) {
+            spinner.info('.env detected (contents not read)');
+        }
+        spinner.succeed(`Scanned ${allFiles.length} files`);
+        await maybeReviewRepoSummary(manifest, options);
+        await writeKolmoConfig(manifest, cwd);
+        printScanSummary(manifest, options);
+        if (!options.noUpload) {
+            await uploadManifest(manifest, options, cwd);
+        }
+        else {
+            console.log(chalk.gray('Upload skipped (--no-upload)'));
+        }
+    }
+    catch (err) {
+        spinner.fail('Scan failed');
+        console.error(chalk.red(String(err)));
+        process.exit(1);
+    }
+}
+async function maybeReviewRepoSummary(manifest, options) {
+    console.log('');
+    console.log(chalk.bold('Kolmo understanding:'));
+    console.log(manifest.repo_summary);
+    if (options.summary?.trim() || !shouldReviewSummary(options)) {
+        return;
+    }
+    console.log(chalk.gray('Press Enter to accept, type a corrected summary, or type "edit" for multi-line input.'));
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = (await rl.question(chalk.cyan('Summary override: '))).trim();
+        if (!answer)
+            return;
+        if (answer.toLowerCase() === 'edit') {
+            const multiLineSummary = await readMultiLineSummary(rl);
+            if (!multiLineSummary)
+                return;
+            manifest.repo_summary = multiLineSummary;
+            manifest.summary_source = 'user_edited';
+            return;
+        }
+        manifest.repo_summary = normalizeSummary(answer);
+        manifest.summary_source = 'user_edited';
+    }
+    finally {
+        rl.close();
+    }
+}
+function printScanSummary(manifest, options) {
+    console.log('');
+    console.log(chalk.bold('Project:'), manifest.project_name);
+    console.log(chalk.bold('Type:'), manifest.project_type);
+    console.log(chalk.bold('Repo summary:'), manifest.repo_summary);
+    if (manifest.detailed_assets.length > 0) {
+        const assetLabels = manifest.detailed_assets.map((asset) => asset.inferred ? chalk.yellow(`${asset.symbol}*`) : chalk.green(asset.symbol));
+        console.log(chalk.bold('Assets detected:'), assetLabels.join(', '));
+        for (const asset of manifest.detailed_assets) {
+            if (asset.inferred && asset.inference_note) {
+                console.log(chalk.yellow(`  * ${asset.inference_note}`));
+            }
+        }
+    }
+    else {
+        console.log(chalk.bold('Assets detected:'), chalk.gray('none'));
+    }
+    console.log(chalk.bold('Suggested workflows:'), chalk.yellow(`${manifest.suggested_workflows.length} available`));
+    console.log(chalk.bold('Evidence citations:'), manifest.explanations.evidence_citations.length
+        ? chalk.cyan(String(manifest.explanations.evidence_citations.length))
+        : chalk.gray('none'));
+    console.log(chalk.bold('Config written:'), chalk.cyan('kolmo.config.json'));
+    if (options.verbose) {
+        console.log('');
+        console.log(chalk.bold('Python packages:'), manifest.detected_packages.python.join(', ') || 'none');
+        console.log(chalk.bold('Node packages:'), manifest.detected_packages.node.join(', ') || 'none');
+    }
+}
+async function uploadManifest(manifest, options, cwd) {
+    console.log('');
+    const uploadSpinner = ora('Sending to Kolmo...').start();
+    try {
+        const result = await sendManifest(manifest, options.apiUrl, options.portfolioName);
+        uploadSpinner.succeed('Manifest sent to Kolmo');
+        const res = result;
+        if (res.session_id) {
+            console.log(chalk.bold('Session ID:'), chalk.cyan(String(res.session_id)));
+        }
+        const llm = res.llm_analysis;
+        if (llm?.strategy_type) {
+            console.log('');
+            console.log(chalk.bold('Strategy analysis:'));
+            console.log(`  ${chalk.cyan('Type:')}    ${chalk.bold(String(llm.strategy_type))}`);
+            if (Array.isArray(llm.instruments) && llm.instruments.length > 0) {
+                console.log(`  ${chalk.cyan('Assets:')}  ${llm.instruments.join(', ')}`);
+            }
+            if (llm.logic_summary) {
+                console.log(`  ${chalk.cyan('Logic:')}   ${chalk.gray(String(llm.logic_summary))}`);
+            }
+            if (Array.isArray(llm.risk_flags) && llm.risk_flags.length > 0) {
+                console.log(`  ${chalk.cyan('Risks:')}   ${chalk.yellow(llm.risk_flags.join(' · '))}`);
+            }
+        }
+        if (Array.isArray(res.suggestions) && res.suggestions.length > 0) {
+            console.log(chalk.bold('Kolmo suggestions:'));
+            for (const s of res.suggestions) {
+                const title = String(s.title ?? '');
+                const desc = String(s.description ?? '');
+                const conf = s.confidence != null ? chalk.gray(` [${s.confidence}]`) : '';
+                console.log(`  ${chalk.cyan('•')} ${chalk.bold(title)}${conf}`);
+                if (desc)
+                    console.log(`    ${chalk.gray(desc)}`);
+            }
+        }
+    }
+    catch (err) {
+        uploadSpinner.fail('Failed to send manifest to Kolmo');
+        if (options.verbose) {
+            console.error(chalk.red(String(err)));
+        }
+        else {
+            console.log(chalk.gray('Run with --verbose for error details'));
+        }
+        process.exitCode = 1;
+    }
+}
+function shouldReviewSummary(options) {
+    return Boolean(!options.yes && process.stdin.isTTY && process.stdout.isTTY);
+}
+async function readMultiLineSummary(rl) {
+    const lines = [];
+    console.log(chalk.gray('Enter the corrected summary. Finish with a single "." on its own line.'));
+    while (true) {
+        const line = await rl.question(chalk.cyan('> '));
+        if (line.trim() === '.')
+            break;
+        lines.push(line);
+    }
+    return normalizeSummary(lines.join(' '));
+}

package/dist/commands/sync.d.ts

@@ -0,0 +1,2 @@
+import type { ScanOptions } from '../types.js';
+export declare function runSync(options: ScanOptions): Promise<void>;

package/dist/commands/sync.js

@@ -0,0 +1,50 @@
+import { readFile } from 'fs/promises';
+import path from 'path';
+import chalk from 'chalk';
+import ora from 'ora';
+import { sendManifest } from '../api/kolmoApiClient.js';
+export async function runSync(options) {
+    const configPath = path.join(process.cwd(), 'kolmo.config.json');
+    const spinner = ora('Reading kolmo.config.json...').start();
+    try {
+        const content = await readFile(configPath, 'utf-8');
+        const manifest = JSON.parse(content);
+        spinner.succeed('Config loaded');
+        console.log(chalk.bold('Project:'), manifest.project_name);
+        console.log(chalk.bold('Assets:'), manifest.detected_assets.join(', ') || 'none');
+        if (manifest.repo_summary) {
+            console.log(chalk.bold('Repo summary:'), manifest.repo_summary);
+        }
+        const uploadSpinner = ora('Syncing to Kolmo...').start();
+        try {
+            const result = await sendManifest(manifest, options.apiUrl);
+            uploadSpinner.succeed('Manifest synced to Kolmo');
+            const res = result;
+            if (res.session_id) {
+                console.log(chalk.bold('Session ID:'), chalk.cyan(String(res.session_id)));
+            }
+            if (Array.isArray(res.suggestions) && res.suggestions.length > 0) {
+                console.log(chalk.bold('Kolmo suggestions:'));
+                for (const s of res.suggestions) {
+                    const title = String(s.title ?? '');
+                    const desc = String(s.description ?? '');
+                    const conf = s.confidence != null ? chalk.gray(` [${s.confidence}]`) : '';
+                    console.log(`  ${chalk.cyan('•')} ${chalk.bold(title)}${conf}`);
+                    if (desc)
+                        console.log(`    ${chalk.gray(desc)}`);
+                }
+            }
+        }
+        catch (err) {
+            uploadSpinner.fail('Failed to sync manifest');
+            console.error(chalk.red(String(err)));
+            process.exit(1);
+        }
+    }
+    catch (err) {
+        spinner.fail('Could not read kolmo.config.json');
+        console.error(chalk.red(String(err)));
+        console.log(chalk.gray('Run "kolmo scan" first to generate a config.'));
+        process.exit(1);
+    }
+}

package/dist/config/authConfig.d.ts

@@ -0,0 +1,8 @@
+export interface KolmoConfig {
+    token?: string;
+    api_url?: string;
+}
+export declare function readConfig(): KolmoConfig;
+export declare function writeConfig(config: KolmoConfig): void;
+export declare function getToken(): string | undefined;
+export declare function clearToken(): void;

package/dist/config/authConfig.js

@@ -0,0 +1,26 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+const CONFIG_DIR = path.join(os.homedir(), '.kolmo');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+export function readConfig() {
+    try {
+        const raw = fs.readFileSync(CONFIG_FILE, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+export function writeConfig(config) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + '\n', 'utf8');
+}
+export function getToken() {
+    return readConfig().token;
+}
+export function clearToken() {
+    const config = readConfig();
+    delete config.token;
+    writeConfig(config);
+}

package/dist/config/writeKolmoConfig.d.ts

@@ -0,0 +1,2 @@
+import type { ScoutManifest } from '../types.js';
+export declare function writeKolmoConfig(manifest: ScoutManifest, dir: string): Promise<void>;

package/dist/config/writeKolmoConfig.js

@@ -0,0 +1,6 @@
+import { writeFile } from 'fs/promises';
+import path from 'path';
+export async function writeKolmoConfig(manifest, dir) {
+    const configPath = path.join(dir, 'kolmo.config.json');
+    await writeFile(configPath, JSON.stringify(manifest, null, 2), 'utf-8');
+}

package/dist/detectors/assetDetector.d.ts

@@ -0,0 +1,8 @@
+import type { ScoutAssetInfo } from '../types.js';
+export declare function detectAssets(filenames: string[], columnNames: string[]): string[];
+export declare function detectAssetDetails(input: {
+    file?: string;
+    filenames?: string[];
+    columnNames?: string[];
+    textValues?: string[];
+}): ScoutAssetInfo[];

package/dist/detectors/assetDetector.js

@@ -0,0 +1,7 @@
+import { detectEnergyAssets } from '../taxonomy/energyTaxonomy.js';
+export function detectAssets(filenames, columnNames) {
+    return detectAssetDetails({ filenames, columnNames }).map((asset) => asset.symbol);
+}
+export function detectAssetDetails(input) {
+    return detectEnergyAssets(input);
+}

package/dist/detectors/fileTypeDetector.d.ts

@@ -0,0 +1 @@
+export declare function detectFileType(filename: string, columns: string[]): string;

package/dist/detectors/fileTypeDetector.js

@@ -0,0 +1,38 @@
+import path from 'path';
+export function detectFileType(filename, columns) {
+    const ext = path.extname(filename).toLowerCase();
+    const base = path.basename(filename).toLowerCase();
+    const cols = columns.map((c) => c.toLowerCase());
+    const hasCol = (...names) => names.some((n) => cols.some((c) => c.includes(n)));
+    // Notebook
+    if (ext === '.ipynb') {
+        return 'notebook';
+    }
+    // Python files
+    if (ext === '.py') {
+        if (/risk|var|pnl/.test(base))
+            return 'risk_model';
+        if (/forecast|predict|model/.test(base))
+            return 'forecast_model';
+    }
+    // CSV / Excel data files — classify by column content
+    if (hasCol('date', 'ts', 'timestamp') && hasCol('close', 'price', 'settle')) {
+        return 'historical_prices';
+    }
+    if (hasCol('maturity', 'expiry', 'contract') && hasCol('price', 'value')) {
+        return 'forward_curve';
+    }
+    if (hasCol('position', 'volume', 'book', 'notional')) {
+        return 'positions';
+    }
+    if (hasCol('var', 'pnl', 'loss', 'returns') || /var|pnl|risk/.test(base)) {
+        return 'risk_results';
+    }
+    if (hasCol('forecast', 'prediction', 'yhat', 'model_output') || /forecast|predict/.test(base)) {
+        return 'forecast_output';
+    }
+    if (hasCol('headline', 'title', 'url', 'source') && hasCol('published', 'date')) {
+        return 'news_events';
+    }
+    return 'unknown';
+}

package/dist/detectors/projectTypeDetector.d.ts

@@ -0,0 +1,4 @@
+export declare function detectProjectType(files: string[], packages: {
+    python: string[];
+    node: string[];
+}): string;

package/dist/detectors/projectTypeDetector.js

@@ -0,0 +1,36 @@
+import path from 'path';
+export function detectProjectType(files, packages) {
+    const basenames = files.map((f) => path.basename(f).toLowerCase());
+    const exts = files.map((f) => path.extname(f).toLowerCase());
+    const hasFile = (name) => basenames.includes(name.toLowerCase());
+    const hasExt = (ext) => exts.includes(ext);
+    const hasPath = (prefix) => files.some((f) => f.replace(/\\/g, '/').startsWith(prefix));
+    // Requirements.txt + any .py → python analytics project
+    if (hasFile('requirements.txt') && hasExt('.py')) {
+        return 'python_analytics_project';
+    }
+    // Any notebook
+    if (hasExt('.ipynb')) {
+        return 'notebook_research_project';
+    }
+    // Frontend project
+    if (hasFile('package.json') &&
+        (packages.node.includes('vite') || packages.node.includes('react'))) {
+        return 'frontend_project';
+    }
+    // FastAPI backend
+    if (hasFile('main.py') && packages.python.includes('fastapi')) {
+        return 'fastapi_backend_project';
+    }
+    // Supabase project
+    if (hasPath('supabase/')) {
+        return 'supabase_project';
+    }
+    // Data folder — >50% csv/xlsx
+    const dataExts = ['.csv', '.xlsx', '.xls'];
+    const dataFileCount = exts.filter((e) => dataExts.includes(e)).length;
+    if (files.length > 0 && dataFileCount / files.length > 0.5) {
+        return 'data_folder_project';
+    }
+    return 'generic_project';
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+import { program } from 'commander';
+import { runAuth, runLogout } from './commands/auth.js';
+import { runExplain } from './commands/explain.js';
+import { runScan } from './commands/scan.js';
+import { runSync } from './commands/sync.js';
+program
+    .name('kolmo')
+    .description('Kolmo Scout — scan and connect local energy projects')
+    .version('0.1.0');
+program
+    .command('auth')
+    .description('Authenticate the CLI with your Kolmo account')
+    .requiredOption('--token <token>', 'Scout CLI token (starts with ksc_)')
+    .option('--api-url <url>', 'Kolmo API URL', process.env['KOLMO_API_URL'] ?? 'http://localhost:8000')
+    .action(async (opts) => {
+    await runAuth({ token: opts.token, apiUrl: opts.apiUrl });
+});
+program
+    .command('logout')
+    .description('Remove stored CLI token')
+    .action(async () => {
+    await runLogout();
+});
+program
+    .command('scan [dir]')
+    .description('Scan a directory (default: current) and send metadata to Kolmo')
+    .option('--api-url <url>', 'Kolmo API URL', process.env['KOLMO_API_URL'] ?? 'http://localhost:8000')
+    .option('--no-upload', 'Create config without uploading')
+    .option('--no-content', 'Send metadata only — do not read file contents')
+    .option('--portfolio <name>', 'Assign scan to a named portfolio')
+    .option('--summary <text>', 'Override the generated natural-language repo summary')
+    .option('-y, --yes', 'Accept generated summary without interactive review')
+    .option('--verbose', 'Verbose output')
+    .action(async (dir, opts) => {
+    await runScan({
+        apiUrl: opts.apiUrl,
+        dir,
+        noUpload: !opts.upload,
+        noContent: !opts.content,
+        portfolioName: opts.portfolio,
+        summary: opts.summary,
+        yes: opts.yes,
+        verbose: opts.verbose,
+    });
+});
+program
+    .command('sync')
+    .description('Re-send existing kolmo.config.json to Kolmo')
+    .option('--api-url <url>', 'Kolmo API URL', process.env['KOLMO_API_URL'] ?? 'http://localhost:8000')
+    .action(async (opts) => {
+    await runSync({ apiUrl: opts.apiUrl });
+});
+program
+    .command('explain [dir]')
+    .description('Explain why Kolmo classified a project the way it did')
+    .option('--json', 'Print machine-readable explanation JSON')
+    .action(async (dir, opts) => {
+    await runExplain({ dir, json: opts.json });
+});
+// Default to scan if no command given
+if (process.argv.length === 2) {
+    process.argv.push('scan');
+}
+program.parse();

package/dist/manifest/buildScoutManifest.d.ts

@@ -0,0 +1,15 @@
+import type { ScoutManifest } from '../types.js';
+export interface BuildScoutManifestOptions {
+    dir?: string;
+    summary?: string;
+    noContent?: boolean;
+    portfolioName?: string;
+}
+export interface BuildScoutManifestResult {
+    cwd: string;
+    allFiles: string[];
+    hasEnv: boolean;
+    manifest: ScoutManifest;
+}
+export declare function buildScoutManifest(options: BuildScoutManifestOptions): Promise<BuildScoutManifestResult>;
+export declare function normalizeSummary(summary: string): string;