flowseeker 0.1.7 → 0.1.9

package/dist/cli/main.js

@@ -0,0 +1,1810 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const child_process_1 = require("child_process");
+const fsSync = __importStar(require("fs"));
+const fs = __importStar(require("fs/promises"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const module_1 = require("module");
+const loadConfigFromPath_1 = require("../config/loadConfigFromPath");
+const embeddingProviders_1 = require("../gateway/embeddingProviders");
+const mcpTools_1 = require("../mcp/mcpTools");
+const LOCAL_MODEL_PROFILE = {
+    modelId: "sentence-transformers/all-MiniLM-L6-v2",
+    modelSlug: "all-MiniLM-L6-v2",
+    modelAlias: "minilm",
+    dimensions: 384,
+    runtimePackage: "@huggingface/transformers",
+    schemaVersion: 1
+};
+void main().catch((error) => {
+    const message = error instanceof Error ? error.stack ?? error.message : String(error);
+    console.error(message);
+    process.exitCode = 1;
+});
+async function main() {
+    const args = process.argv.slice(2);
+    const command = args[0];
+    if (!command || command === "--help" || command === "-h" || command === "help") {
+        printHelp();
+        return;
+    }
+    if (command === "--version" || command === "-v") {
+        await printVersion();
+        return;
+    }
+    if (command === "mcp") {
+        await runMcpServer(args.slice(1));
+        return;
+    }
+    if (command === "claude") {
+        printClaudeSetup();
+        return;
+    }
+    if (command === "semantic") {
+        await runSemanticCommand(args.slice(1));
+        return;
+    }
+    if (command === "doctor") {
+        await runDoctorCommand(args.slice(1));
+        return;
+    }
+    if (command === "setup") {
+        await runSetupCommand(args.slice(1));
+        return;
+    }
+    if (command === "benchmark") {
+        await runBenchmarkCommand(args.slice(1));
+        return;
+    }
+    if (command === "guide" || command === "auto" || command === "files" || command === "retrieve") {
+        await runFlowCommand(parseFlowArgs(command, args.slice(1)));
+        return;
+    }
+    throw new Error(`Unknown command: ${command}`);
+}
+async function runSemanticCommand(args) {
+    const subcommand = args[0] && !args[0].startsWith("-") ? args[0] : "check";
+    const rest = subcommand === args[0] ? args.slice(1) : args;
+    if (subcommand === "local") {
+        await runLocalCommand(args.slice(1));
+        return;
+    }
+    const { workspace, testProvider, preset } = parseSemanticArgs(rest);
+    if (subcommand === "init") {
+        await initSemanticEnv(workspace, preset);
+        return;
+    }
+    if (subcommand === "check") {
+        await checkSemanticSetup(workspace, testProvider);
+        return;
+    }
+    if (subcommand === "help" || subcommand === "--help" || subcommand === "-h") {
+        printSemanticHelp();
+        return;
+    }
+    throw new Error(`Unknown semantic command: ${subcommand}`);
+}
+function parseSemanticArgs(args) {
+    let workspace = process.cwd();
+    let testProvider = false;
+    let preset = "";
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        const next = args[i + 1];
+        if (arg === "--help" || arg === "-h") {
+            printSemanticHelp();
+            process.exit(0);
+        }
+        if ((arg === "--workspace" || arg === "-w") && next) {
+            workspace = path.resolve(next);
+            i++;
+            continue;
+        }
+        if (arg === "--test") {
+            testProvider = true;
+            continue;
+        }
+        if (arg === "--jina") {
+            preset = "jina";
+            continue;
+        }
+        if (arg === "--openai-compatible") {
+            preset = "openaiCompatible";
+            continue;
+        }
+        if (arg === "--local") {
+            preset = "local";
+            continue;
+        }
+        throw new Error(`Unknown semantic option: ${arg}`);
+    }
+    return { workspace, testProvider, preset };
+}
+async function initSemanticEnv(workspace, preset) {
+    const resolved = path.resolve(workspace);
+    const configPath = path.join(resolved, ".flowseeker", "config.json");
+    const envPath = path.join(resolved, ".env");
+    const effectivePreset = preset || "jina";
+    // Build semantic config based on preset
+    let semanticConfig;
+    if (effectivePreset === "local") {
+        semanticConfig = {
+            semanticEnabled: true,
+            semanticProvider: "local",
+            semanticModel: "local-minilm-v1",
+            semanticBaseUrl: "",
+            semanticApiKeyEnv: "",
+            semanticCache: true,
+            semanticMaxFilesPerRun: 400,
+            semanticTimeoutMs: 120000
+        };
+    }
+    else if (effectivePreset === "openaiCompatible") {
+        semanticConfig = {
+            semanticEnabled: true,
+            semanticProvider: "openaiCompatible",
+            semanticBaseUrl: "",
+            semanticModel: "",
+            semanticApiKeyEnv: "FLOWSEEKER_EMBEDDING_API_KEY",
+            semanticCache: true,
+            semanticMaxFilesPerRun: 800,
+            semanticTimeoutMs: 60000
+        };
+    }
+    else {
+        // jina (default)
+        semanticConfig = {
+            semanticEnabled: true,
+            semanticProvider: "openaiCompatible",
+            semanticBaseUrl: "https://api.jina.ai/v1",
+            semanticModel: "jina-code-embeddings-0.5b",
+            semanticApiKeyEnv: "FLOWSEEKER_EMBEDDING_API_KEY",
+            semanticCache: true,
+            semanticMaxFilesPerRun: 800,
+            semanticTimeoutMs: 60000
+        };
+    }
+    // Merge into existing .flowseeker/config.json
+    let existingConfig = {};
+    try {
+        existingConfig = JSON.parse(await fs.readFile(configPath, "utf8"));
+    }
+    catch {
+        // create below
+    }
+    const existingIndex = existingConfig.index || {};
+    existingConfig.index = { ...existingIndex, ...semanticConfig };
+    await fs.mkdir(path.dirname(configPath), { recursive: true });
+    await fs.writeFile(configPath, JSON.stringify(existingConfig, null, 2) + "\n", "utf8");
+    process.stdout.write(`Semantic config written: ${configPath}\n`);
+    process.stdout.write(`Preset: ${effectivePreset}\n`);
+    // For hosted presets, add API key placeholder to .env
+    if (effectivePreset !== "local") {
+        const keyEnv = semanticConfig.semanticApiKeyEnv;
+        let existingEnv = "";
+        try {
+            existingEnv = await fs.readFile(envPath, "utf8");
+        }
+        catch { /* create below */ }
+        if (!new RegExp(`^${escapeRegExp(keyEnv)}=`, "m").test(existingEnv)) {
+            const block = [
+                existingEnv.trim() ? "\n" : "",
+                "# FlowSeeker semantic retrieval API key",
+                `${keyEnv}=`,
+                ""
+            ].join("\n");
+            await fs.writeFile(envPath, `${existingEnv}${block}`, "utf8");
+            process.stdout.write(`API key placeholder added: ${envPath} (${keyEnv})\n`);
+        }
+        else {
+            process.stdout.write(`API key env already present: ${envPath} (${keyEnv})\n`);
+        }
+    }
+    // Next steps
+    const nextSteps = effectivePreset === "local"
+        ? ["Local semantic config is enabled. Runtime and model remain explicit setup steps.", "Run: flowseeker semantic local setup", "Then run: flowseeker semantic local download"]
+        : effectivePreset === "openaiCompatible"
+            ? ["This preset is provider-neutral and incomplete until configured.", "Before --test, edit .flowseeker/config.json:", "  semanticBaseUrl", "  semanticModel", "  semanticApiKeyEnv", "The model must match the provider/base URL.", "The API key still belongs in .env.", "Run: flowseeker semantic check to confirm configuration."]
+            : ["  1. Fill FLOWSEEKER_EMBEDDING_API_KEY in .env", "  2. Run: flowseeker semantic check --test"];
+    process.stdout.write(nextSteps.join("\n") + "\n");
+}
+async function checkSemanticSetup(workspace, testProvider) {
+    const resolved = path.resolve(workspace);
+    const configPath = path.join(resolved, ".flowseeker", "config.json");
+    const envPath = path.join(resolved, ".env");
+    const config = await (0, loadConfigFromPath_1.loadConfigFromPath)(resolved);
+    const apiKeyEnv = config.index.semanticApiKeyEnv;
+    const apiKey = apiKeyEnv ? process.env[apiKeyEnv] : undefined;
+    const provider = (0, embeddingProviders_1.createConfiguredEmbeddingProvider)({ ...config.index, workspacePath: resolved });
+    const isLocal = config.index.semanticProvider === "local";
+    const lines = [
+        "FlowSeeker semantic status",
+        "",
+        `Workspace: ${resolved}`,
+        `Enabled: ${config.index.semanticEnabled ? "yes" : "no"}`,
+        `Provider: ${config.index.semanticProvider || "(none)"}`,
+        `Model: ${config.index.semanticModel || "(empty)"}`,
+        `Base URL: ${config.index.semanticBaseUrl || "(provider default)"}`,
+        `API key env: ${apiKeyEnv || "(none)"}`,
+        `API key: ${apiKey ? "***configured***" : (isLocal ? "not required" : "missing")}`,
+        `Cache: ${config.index.semanticCache ? "enabled" : "disabled"}`,
+        `Max files/run: ${config.index.semanticMaxFilesPerRun}`,
+        `Timeout: ${config.index.semanticTimeoutMs}ms`,
+        `Config file: ${configPath}${await fileExists(configPath) ? "" : " (not found)"}`,
+        `Env file: ${envPath}${await fileExists(envPath) ? "" : " (not found)"}`
+    ];
+    if (!config.index.semanticEnabled) {
+        lines.push("", "Result: disabled", "Next action: Run flowseeker semantic init --jina (recommended) or --openai-compatible to enable hosted semantic retrieval.");
+        process.stdout.write(`${lines.join("\n")}\n`);
+        return;
+    }
+    if (isLocal) {
+        const readiness = (0, embeddingProviders_1.getLocalProviderReadiness)(resolved, {
+            semanticModel: config.index.semanticModel,
+            semanticLocalModelPath: config.index.semanticLocalModelPath,
+            semanticDimensions: config.index.semanticDimensions
+        });
+        const statusMessages = {
+            local_unavailable_runtime_missing: { note: "Local embedding runtime (@huggingface/transformers) is not installed in this project.", nextAction: readiness.nextAction },
+            local_unavailable_model_missing: { note: "Local embedding model is not downloaded.", nextAction: readiness.nextAction },
+            local_unavailable_model_invalid: { note: "Local embedding model metadata is invalid.", nextAction: readiness.nextAction },
+            local_ready: { note: "Local embedding provider is ready.", nextAction: readiness.nextAction },
+            bundled_package_ready: { note: "Built-in local model package is installed and ready.", nextAction: readiness.nextAction },
+            bundled_package_missing: { note: "Optional local model package (flowseeker-local) is not installed.", nextAction: readiness.nextAction },
+            bundled_package_invalid: { note: "Built-in local model package is installed but invalid.", nextAction: readiness.nextAction }
+        };
+        const msg = statusMessages[readiness.localStatus] || statusMessages.local_unavailable_runtime_missing;
+        const isReady = readiness.localStatus === "local_ready" || readiness.localStatus === "bundled_package_ready";
+        lines.push("", `Result: ${readiness.localStatus}`, `Note: ${msg.note}`, `Next action: ${msg.nextAction}`);
+        if (testProvider && !isReady) {
+            lines.push("Provider test: skipped (local unavailable).");
+            process.exitCode = 1;
+        }
+        if (testProvider && isReady) {
+            const localProvider = (0, embeddingProviders_1.createConfiguredEmbeddingProvider)({ ...config.index, workspacePath: resolved });
+            if (!localProvider) {
+                lines.push("Provider test: local provider not available despite local_ready.");
+                process.exitCode = 1;
+            }
+            else {
+                try {
+                    const [vector] = await localProvider.embedTexts(["flowseeker semantic provider check"]);
+                    lines.push("", "Provider test: passed", `Vector: ${vector.length} dimensions`, `All finite: ${vector.every(v => isFinite(v))}`, "Next action: Local semantic retrieval is ready.");
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    lines.push("", "Provider test failed: " + message, "Next action: Check your local runtime installation and model cache.");
+                    process.exitCode = 1;
+                }
+            }
+        }
+        process.stdout.write(`${lines.join("\n")}\n`);
+        return;
+    }
+    // Provider-neutral openaiCompatible must have a model configured
+    if (config.index.semanticProvider === "openaiCompatible" && !config.index.semanticModel) {
+        lines.push("", "Result: incomplete_config", "Next action: Set semanticModel in .flowseeker/config.json to the embedding model exposed by your provider. Set semanticBaseUrl if your provider needs a custom endpoint. Keep the key in .env.");
+        process.stdout.write(`${lines.join("\n")}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    if (!provider) {
+        lines.push("", "Result: skipped_no_key", `Next action: Set ${apiKeyEnv}=<your embedding API key> in .env.`);
+        process.stdout.write(`${lines.join("\n")}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    if (!testProvider) {
+        lines.push("", "Result: configured", "Next action: Run flowseeker semantic check --test to verify the key with one embedding request.");
+        process.stdout.write(`${lines.join("\n")}\n`);
+        return;
+    }
+    try {
+        const [vector] = await provider.embedTexts(["flowseeker semantic provider check"]);
+        lines.push("", "Result: active", `Provider test: passed (${vector.length} dimensions)`, "Next action: Semantic retrieval is ready. Your MCP/CLI scans will include semantic evidence.");
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        lines.push("", "Result: error", `Provider test failed: ${message}`, "Next action: Check your API key, base URL, and network access.");
+        process.exitCode = 1;
+    }
+    process.stdout.write(`${lines.join("\n")}\n`);
+}
+async function fileExists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// --- Doctor ---
+async function runDoctorCommand(args) {
+    let workspace = process.cwd();
+    let useJson = false;
+    let checkMcp = false;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        const next = args[i + 1];
+        if (arg === "--help" || arg === "-h") {
+            process.stderr.write("Usage: flowseeker doctor [--workspace <path>] [--json] [--mcp]\n");
+            return;
+        }
+        if ((arg === "--workspace" || arg === "-w") && next) {
+            workspace = path.resolve(next);
+            i++;
+            continue;
+        }
+        if (arg === "--json") {
+            useJson = true;
+            continue;
+        }
+        if (arg === "--mcp") {
+            checkMcp = true;
+            continue;
+        }
+        throw new Error(`Unknown doctor option: ${arg}`);
+    }
+    const resolved = path.resolve(workspace);
+    const configPath = path.join(resolved, ".flowseeker", "config.json");
+    const cachePath = path.join(resolved, ".flowseeker", "cache");
+    const envPath = path.join(resolved, ".env");
+    const pkg = JSON.parse(await fs.readFile(path.resolve(__dirname, "../../package.json"), "utf8"));
+    const config = await (0, loadConfigFromPath_1.loadConfigFromPath)(resolved);
+    const nextActions = [];
+    // Semantic status
+    const semEnabled = config.index.semanticEnabled;
+    const semProvider = config.index.semanticProvider || "none";
+    const semModel = config.index.semanticModel || "(empty)";
+    const semBaseUrl = config.index.semanticBaseUrl || "(provider default)";
+    const semKeyEnv = config.index.semanticApiKeyEnv || "(none)";
+    const semKeyOk = semKeyEnv ? !!process.env[semKeyEnv] : false;
+    const semCache = config.index.semanticCache;
+    const semMaxFiles = config.index.semanticMaxFilesPerRun;
+    const semTimeout = config.index.semanticTimeoutMs;
+    let semResult = "disabled";
+    if (!semEnabled)
+        semResult = "disabled";
+    else if (semProvider === "local") {
+        const localReadiness = (0, embeddingProviders_1.getLocalProviderReadiness)(resolved, {
+            semanticModel: config.index.semanticModel || "local-minilm-v1",
+            semanticLocalModelPath: config.index.semanticLocalModelPath,
+            semanticDimensions: config.index.semanticDimensions
+        });
+        semResult = localReadiness.localStatus;
+    }
+    else if (!semKeyOk)
+        semResult = "skipped_no_key";
+    else if (semProvider === "openaiCompatible" && !config.index.semanticModel)
+        semResult = "incomplete_config";
+    else
+        semResult = "configured";
+    if (semResult === "disabled")
+        nextActions.push("Semantic retrieval is optional. Run flowseeker semantic init --openai-compatible for hosted or flowseeker semantic init --local for local no-key path.");
+    else if (semResult === "skipped_no_key")
+        nextActions.push(`Set ${semKeyEnv} in .env and re-run flowseeker semantic check --test`);
+    else if (semResult === "local_unavailable" || semResult === "local_unavailable_runtime_missing")
+        nextActions.push("Run flowseeker semantic local setup, then flowseeker semantic local download.");
+    else if (semResult === "bundled_package_missing")
+        nextActions.push("Install the ready local model package: npm i -g flowseeker flowseeker-local. Then run flowseeker semantic check --test.");
+    else if (semResult === "bundled_package_invalid")
+        nextActions.push("The flowseeker-local package is installed but invalid. Reinstall: npm i -g flowseeker flowseeker-local.");
+    else if (semResult === "bundled_package_ready") { } // no action needed, ready
+    else if (semResult === "incomplete_config")
+        nextActions.push("Set semanticModel in .flowseeker/config.json to the embedding model exposed by your provider. Set semanticBaseUrl if your provider needs a custom endpoint.");
+    // Config/env presence
+    const configExists = await fileExists(configPath);
+    const envExists = await fileExists(envPath);
+    if (!configExists)
+        nextActions.push("No .flowseeker/config.json found. Deterministic/no-embedding retrieval is the default and requires no setup.");
+    // Cache
+    let cacheSummary = "not found";
+    if (await fileExists(cachePath)) {
+        try {
+            const cacheFiles = await fs.readdir(cachePath);
+            cacheSummary = `${cacheFiles.length} file(s)`;
+            if (cacheFiles.length === 0)
+                nextActions.push("Cache directory is empty. Run a scan to populate the index.");
+        }
+        catch {
+            cacheSummary = "unreadable";
+        }
+    }
+    // MCP check
+    let mcpStatus = { checked: false };
+    if (checkMcp) {
+        try {
+            const serverPath = path.join(__dirname, "mcpServer.js");
+            const child = (0, child_process_1.spawn)(process.execPath, [serverPath], { stdio: ["pipe", "pipe", "pipe"], windowsHide: true });
+            const stdoutChunks = [];
+            child.stdout?.on("data", (chunk) => stdoutChunks.push(chunk));
+            // Send initialize
+            const initMsg = JSON.stringify({ jsonrpc: "2.0", id: 0, method: "initialize", params: { protocolVersion: "2024-11-05", capabilities: {}, clientInfo: { name: "flowseeker-doctor", version: "0.0.0" } } }) + "\n";
+            child.stdin?.write(initMsg);
+            // Send tools/list
+            const toolsMsg = JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/list", params: {} }) + "\n";
+            child.stdin?.write(toolsMsg);
+            // Send prompts/list
+            const promptsMsg = JSON.stringify({ jsonrpc: "2.0", id: 2, method: "prompts/list", params: {} }) + "\n";
+            child.stdin?.write(promptsMsg);
+            // Wait briefly then kill
+            await new Promise(r => setTimeout(r, 2000));
+            child.kill();
+            const stdout = Buffer.concat(stdoutChunks).toString("utf8");
+            const hasRetrieve = stdout.includes("flowseeker_retrieve");
+            const hasGuide = stdout.includes("flowseeker_guide");
+            const hasAuto = stdout.includes("flowseeker_auto");
+            const hasFiles = stdout.includes("flowseeker_files");
+            const hasValidatePlan = stdout.includes("flowseeker_validate_plan");
+            const hasContext = stdout.includes("flowseeker_context");
+            const hasInspect = stdout.includes("flowseeker_inspect");
+            const hasExpand = stdout.includes("flowseeker_expand");
+            const hasStatus = stdout.includes("flowseeker_status");
+            const hasIndex = stdout.includes("flowseeker_index");
+            const hasFeedback = stdout.includes("flowseeker_feedback");
+            mcpStatus = {
+                checked: true,
+                initializeOk: stdout.includes('"id":0'),
+                toolsIncludesRetrieve: hasRetrieve,
+                toolsIncludesGuide: hasGuide,
+                toolsIncludesAuto: hasAuto,
+                toolsIncludesFiles: hasFiles,
+                toolsIncludesValidatePlan: hasValidatePlan,
+                toolsIncludesContext: hasContext,
+                toolsIncludesInspect: hasInspect,
+                toolsIncludesExpand: hasExpand,
+                toolsIncludesStatus: hasStatus,
+                toolsIncludesIndex: hasIndex,
+                toolsIncludesFeedback: hasFeedback,
+                promptsIncludeRetrieve: stdout.includes('"retrieve"'),
+                promptsIncludeGuide: stdout.includes('"guide"'),
+                promptsIncludeAuto: stdout.includes('"auto"'),
+                promptsIncludeFiles: stdout.includes('"files"'),
+                promptsIncludeValidatePlan: stdout.includes('"validate-plan"'),
+                promptsIncludeContext: stdout.includes('"context"'),
+            };
+            if (!hasRetrieve)
+                nextActions.push("MCP tools/list missing flowseeker_retrieve. Check MCP server startup.");
+        }
+        catch (e) {
+            mcpStatus = { checked: false, error: e.message };
+            nextActions.push("MCP self-check failed. Verify Node.js and the FlowSeeker installation.");
+        }
+    }
+    // Deterministic/no-embedding is default and always healthy
+    const deterministicStatus = "ok";
+    const isWarningResult = semResult === "skipped_no_key" || semResult === "local_unavailable" || semResult === "local_unavailable_runtime_missing" || semResult === "local_unavailable_model_missing" || semResult === "incomplete_config" || semResult === "bundled_package_missing" || semResult === "bundled_package_invalid";
+    const overall = isWarningResult ? "warn"
+        : (nextActions.filter(a => !a.includes("optional") && !a.includes("deterministic") && !a.includes("default") && !a.includes("No .flowseeker")).length > 0 ? "warn" : "ok");
+    const doctor = {
+        status: overall,
+        version: pkg.version ?? "unknown",
+        node: process.version,
+        platform: `${os.platform()} ${os.arch()}`,
+        workspace: resolved,
+        deterministic: { status: deterministicStatus, retrieval: "available", note: "No embedding required. Code-structure analysis is first-class." },
+        semantic: {
+            enabled: semEnabled, provider: semProvider, model: semModel, baseUrl: semBaseUrl,
+            keyEnv: semKeyEnv, keyConfigured: semKeyOk, cache: semCache, maxFilesPerRun: semMaxFiles,
+            timeoutMs: semTimeout, result: semResult
+        },
+        mcp: mcpStatus,
+        config: { path: configPath, exists: configExists },
+        env: { path: envPath, exists: envExists },
+        cache: { path: cachePath, summary: cacheSummary },
+        nextActions
+    };
+    if (useJson) {
+        process.stdout.write(JSON.stringify(doctor, null, 2) + "\n");
+    }
+    else {
+        const lines = [
+            "FlowSeeker Doctor",
+            "",
+            `Version: ${doctor.version}  Node: ${doctor.node}  Platform: ${doctor.platform}`,
+            `Workspace: ${doctor.workspace}`,
+            "",
+            "Deterministic:",
+            "  Retrieval: available (default, first-class)",
+            "  No embedding, API key, or model required.",
+            "",
+            "Semantic:",
+            `  Enabled: ${semEnabled}  Provider: ${semProvider}  Model: ${semModel}`,
+            `  Base URL: ${semBaseUrl}  Key env: ${semKeyEnv}  Key configured: ${semKeyOk}`,
+            `  Cache: ${semCache}  Max files/run: ${semMaxFiles}  Timeout: ${semTimeout}ms`,
+            `  Result: ${semResult}`,
+            "",
+            `Config: ${configPath} (${configExists ? "exists" : "missing"})`,
+            `Env: ${envPath} (${envExists ? "exists" : "missing"})`,
+            `Cache: ${cachePath} (${cacheSummary})`,
+            ""
+        ];
+        if (checkMcp) {
+            const mcp = mcpStatus;
+            lines.push("MCP:", "");
+            lines.push("  Self-check: " + (mcp.checked ? (mcp.initializeOk ? "pass" : "init failed") : "not run"));
+            if (mcp.checked) {
+                const toolIcons = (name) => mcp[name] ? "present" : "MISSING";
+                lines.push("  Tools: retrieve=" + toolIcons("toolsIncludesRetrieve") + " guide=" + toolIcons("toolsIncludesGuide") + " auto=" + toolIcons("toolsIncludesAuto") + " files=" + toolIcons("toolsIncludesFiles") + " validate_plan=" + toolIcons("toolsIncludesValidatePlan") + " context=" + toolIcons("toolsIncludesContext") + " inspect=" + toolIcons("toolsIncludesInspect") + " expand=" + toolIcons("toolsIncludesExpand") + " status=" + toolIcons("toolsIncludesStatus") + " index=" + toolIcons("toolsIncludesIndex") + " feedback=" + toolIcons("toolsIncludesFeedback"));
+                lines.push("  Prompts: retrieve=" + toolIcons("promptsIncludeRetrieve") + " guide=" + toolIcons("promptsIncludeGuide") + " auto=" + toolIcons("promptsIncludeAuto") + " files=" + toolIcons("promptsIncludeFiles") + " validate-plan=" + toolIcons("promptsIncludeValidatePlan") + " context=" + toolIcons("promptsIncludeContext"));
+            }
+            lines.push("  Server command: flowseeker");
+            lines.push("  Server args: mcp --workspace " + resolved + "");
+            lines.push("");
+            lines.push("Config candidates:");
+            const configCandidates = [
+                { path: path.join(resolved, ".claude", "mcp.json"), label: "Claude Code", method: "external CLI command: claude mcp add" },
+                { path: path.join(resolved, ".codex", "mcp.json"), label: "Codex CLI", method: "external CLI command: codex mcp add" },
+                { path: path.join(resolved, ".cursor", "mcp.json"), label: "Cursor", method: "file merge (flowseeker setup cursor --yes)" },
+                { path: path.join(resolved, ".vscode", "mcp.json"), label: "VS Code", method: "file merge (flowseeker setup vscode --yes)" },
+            ];
+            let anyConfig = false;
+            for (const cc of configCandidates) {
+                const exists = await fileExists(cc.path);
+                if (exists)
+                    anyConfig = true;
+                lines.push("  " + cc.label + ": " + (exists ? cc.path + " (exists)" : cc.method));
+            }
+            // Local package status
+            const localInfo = (0, embeddingProviders_1.detectBundledLocalPackage)(resolved);
+            lines.push("");
+            lines.push("Local model package: " + (localInfo.available ? (localInfo.valid ? "installed and ready" : "installed but invalid") : "not installed (optional: npm i -g flowseeker-local)"));
+            lines.push("");
+            if (!anyConfig) {
+                nextActions.push("No MCP config found. Run: flowseeker setup claude --no-exec to preview, then flowseeker setup claude --yes to apply.");
+            }
+            if (!localInfo.available) {
+                nextActions.push("Optional: npm i -g flowseeker-local for local embeddings (no API key needed)");
+            }
+        }
+        if (nextActions.length > 0) {
+            lines.push("Next actions:");
+            nextActions.forEach(a => lines.push(`  - ${a}`));
+            lines.push("");
+        }
+        lines.push(`Status: ${overall}`);
+        process.stdout.write(lines.join("\n") + "\n");
+    }
+}
+const UTF8_BOM = "";
+function stripBom(text) {
+    return text.startsWith(UTF8_BOM) ? text.slice(1) : text;
+}
+async function readJsonSafely(filePath) {
+    if (!(await fileExists(filePath)))
+        return { data: {} };
+    let raw;
+    try {
+        raw = await fs.readFile(filePath, "utf8");
+    }
+    catch {
+        return { data: {}, error: "cannot read file" };
+    }
+    const cleaned = stripBom(raw);
+    try {
+        const parsed = JSON.parse(cleaned);
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+            return { data: {}, error: "root is not a JSON object" };
+        return { data: parsed };
+    }
+    catch {
+        return { data: {}, error: "invalid JSON" };
+    }
+}
+async function writeMergedConfig(filePath, dir, key, entry) {
+    const safe = await readJsonSafely(filePath);
+    if (safe.error)
+        return { written: false, error: safe.error };
+    const existing = safe.data[key];
+    if (existing === null)
+        return { written: false, error: `"${key}" is null (expected object)` };
+    if (existing !== undefined && (typeof existing !== "object" || Array.isArray(existing)))
+        return { written: false, error: `"${key}" is not an object` };
+    const servers = existing || {};
+    safe.data[key] = { ...servers, flowseeker: entry };
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(filePath, JSON.stringify(safe.data, null, 2) + "\n", "utf8");
+    return { written: true };
+}
+async function runSetupCommand(args) {
+    let workspace = process.cwd();
+    let dryRun = true;
+    let force = false;
+    let noExec = false;
+    const agents = [];
+    // Subcommand-style: flowseeker setup claude, flowseeker setup codex --yes, etc.
+    if (args[0] && !args[0].startsWith("-") && ["claude", "codex", "cursor", "vscode"].includes(args[0])) {
+        agents.push(args[0]);
+        args = args.slice(1); // shift for remaining flag parsing
+    }
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        const next = args[i + 1];
+        if (arg === "--help" || arg === "-h") {
+            process.stdout.write("Usage: flowseeker setup [claude|codex|cursor|vscode] [--workspace <path>] [--dry-run] [--force] [--yes] [--no-exec]\n\n");
+            process.stdout.write("One-command MCP setup for AI coding agents.\n\n");
+            process.stdout.write("Agents:\n");
+            process.stdout.write("  claude    Setup Claude Code MCP (prints external CLI command)\n");
+            process.stdout.write("  codex     Setup Codex CLI MCP (prints external CLI command)\n");
+            process.stdout.write("  cursor    Setup Cursor MCP (writes .cursor/mcp.json)\n");
+            process.stdout.write("  vscode    Setup VS Code MCP (writes .vscode/mcp.json)\n\n");
+            process.stdout.write("Flags:\n");
+            process.stdout.write("  --dry-run      Preview config only (default)\n");
+            process.stdout.write("  --no-exec       Same as --dry-run; preview without writing files\n");
+            process.stdout.write("  --yes / --force Write config files\n");
+            process.stdout.write("  -w, --workspace Target workspace (default: current directory)\n\n");
+            process.stdout.write("Examples:\n");
+            process.stdout.write("  flowseeker setup claude --no-exec     # preview Claude MCP setup\n");
+            process.stdout.write("  flowseeker setup claude --yes         # print Claude MCP add command\n");
+            process.stdout.write("  flowseeker setup vscode --yes         # write VS Code MCP config\n");
+            process.stdout.write("  flowseeker doctor --mcp               # verify MCP setup\n");
+            return;
+        }
+        if ((arg === "--workspace" || arg === "-w") && next) {
+            workspace = path.resolve(next);
+            i++;
+            continue;
+        }
+        if (arg === "--dry-run" || arg === "--no-exec") {
+            dryRun = true;
+            noExec = true;
+            continue;
+        }
+        if (arg === "--force" || arg === "--yes") {
+            force = true;
+            dryRun = false;
+            continue;
+        }
+        if (arg === "--agent" && next) {
+            agents.push(...next.split(",").map(s => s.trim()).filter(Boolean));
+            i++;
+            continue;
+        }
+        throw new Error(`Unknown setup option: ${arg}`);
+    }
+    if (agents.length === 0)
+        agents.push("claude", "codex", "cursor", "vscode");
+    const resolved = path.resolve(workspace);
+    const planned = [];
+    const nextActions = [];
+    const failures = [];
+    const agentDetails = [];
+    for (const agent of agents) {
+        const detail = { target: agent };
+        if (agent === "claude" || agent === "codex") {
+            const cmd = `${agent} mcp add flowseeker -- flowseeker mcp --workspace ${resolved}`;
+            detail.config = "external CLI-managed config (" + agent + " mcp add)";
+            detail.cmd = "flowseeker";
+            detail.args = "mcp --workspace " + resolved;
+            detail.apply = cmd;
+            detail.method = "external CLI command";
+            if (dryRun) {
+                planned.push(`[${agent}] Copy-paste into terminal: ${cmd}`);
+            }
+            else {
+                planned.push(`[${agent}] Copy-paste into terminal: ${cmd}`);
+                nextActions.push(`Run: ${cmd}`);
+            }
+        }
+        else if (agent === "cursor" || agent === "vscode") {
+            const dir = agent === "cursor" ? path.join(resolved, ".cursor") : path.join(resolved, ".vscode");
+            const filePath = path.join(dir, "mcp.json");
+            const key = agent === "cursor" ? "mcpServers" : "servers";
+            const entry = { command: "flowseeker", args: ["mcp", "--workspace", resolved] };
+            detail.config = filePath;
+            detail.configKey = key;
+            detail.cmd = "flowseeker";
+            detail.args = "mcp --workspace " + resolved;
+            detail.apply = "flowseeker setup " + agent + " --yes";
+            detail.method = "file merge";
+            if (dryRun) {
+                planned.push(`Would merge FlowSeeker into ${filePath} [key: ${key}]`);
+            }
+            else if (force) {
+                const result = await writeMergedConfig(filePath, dir, key, entry);
+                if (result.written) {
+                    planned.push(`Merged FlowSeeker into ${filePath} [key: ${key}]`);
+                    nextActions.push("Verify with: flowseeker doctor --mcp");
+                }
+                else {
+                    failures.push(`[${agent}] ${filePath}: ${result.error}`);
+                    nextActions.push(`Fix ${filePath} manually before re-running setup. File was NOT modified.`);
+                }
+            }
+        }
+        else {
+            failures.push(`[${agent}] Unknown agent. Supported: claude, codex, cursor, vscode`);
+        }
+        if (detail)
+            agentDetails.push(detail);
+    }
+    const hasExternalCli = agentDetails.some(d => d.method === "external CLI command");
+    const hasFileWrite = agentDetails.some(d => d.method === "file merge");
+    const mode = dryRun ? "dry-run" : "apply";
+    const lines = [
+        "FlowSeeker setup",
+        `Workspace: ${resolved}`,
+        `Mode: ${mode}`,
+        ""
+    ];
+    // Show local package status
+    const localInfo = (0, embeddingProviders_1.detectBundledLocalPackage)(resolved);
+    if (localInfo.available) {
+        lines.push("Local model package: " + (localInfo.valid ? "flowseeker-local installed and ready" : "installed but invalid"));
+    }
+    else {
+        lines.push("Local model package: not installed (optional)");
+        lines.push("  Install: npm i -g flowseeker-local  (no API key needed)");
+    }
+    lines.push("");
+    // Per-agent schema
+    for (const d of agentDetails) {
+        lines.push("---");
+        lines.push("Target: " + d.target);
+        lines.push("Config: " + d.config);
+        if (d.configKey)
+            lines.push("Config key: " + d.configKey);
+        lines.push("Server command: " + d.cmd);
+        lines.push("Server args: " + d.args);
+        if (dryRun)
+            lines.push("Apply: " + d.apply);
+        lines.push("Verify: flowseeker doctor --mcp");
+        lines.push("");
+    }
+    if (agentDetails.length > 1)
+        lines.push("");
+    // Honest copy per method
+    lines.push("Next actions:");
+    if (dryRun) {
+        if (hasExternalCli)
+            lines.push("  - External CLI targets: run the command shown above to register FlowSeeker.");
+        if (hasFileWrite)
+            lines.push("  - File-merge targets: re-run with --yes to write/merge config files.");
+    }
+    else {
+        if (hasExternalCli)
+            lines.push("  - External CLI targets: run the Apply command shown above. FlowSeeker does not write config files for these targets.");
+        if (hasFileWrite)
+            lines.push("  - File-merge targets: config written. Run: flowseeker doctor --mcp to verify.");
+        if (!hasFileWrite && hasExternalCli)
+            lines.push("  - After running the external CLI command, verify with: flowseeker doctor --mcp");
+    }
+    if (nextActions.length > 0 && !dryRun) {
+        nextActions.forEach(a => lines.push(`  - ${a}`));
+    }
+    lines.push("");
+    lines.push("");
+    process.stdout.write(lines.join("\n"));
+    if (failures.length > 0)
+        process.exitCode = 1;
+}
+// --- Setup end ---
+function detectPackageManager(workspacePath, override) {
+    if (override)
+        return override;
+    const check = (file) => { try {
+        fsSync.accessSync(path.join(workspacePath, file));
+        return true;
+    }
+    catch {
+        return false;
+    } };
+    if (check("pnpm-lock.yaml"))
+        return "pnpm";
+    if (check("yarn.lock"))
+        return "yarn";
+    if (check("bun.lockb") || check("bun.lock"))
+        return "bun";
+    return "npm";
+}
+function pmInstallCommand(pm, pkg) {
+    if (pm === "pnpm")
+        return `pnpm add ${pkg}`;
+    if (pm === "yarn")
+        return `yarn add ${pkg}`;
+    if (pm === "bun")
+        return `bun add ${pkg}`;
+    return `npm install ${pkg}`;
+}
+function pmUninstallCommand(pm, pkg) {
+    if (pm === "pnpm")
+        return `pnpm remove ${pkg}`;
+    if (pm === "yarn")
+        return `yarn remove ${pkg}`;
+    if (pm === "bun")
+        return `bun remove ${pkg}`;
+    return `npm uninstall ${pkg}`;
+}
+function pmInstallArgs(pm, pkg) {
+    if (pm === "pnpm")
+        return ["add", pkg];
+    if (pm === "yarn")
+        return ["add", pkg];
+    if (pm === "bun")
+        return ["add", pkg];
+    return ["install", pkg];
+}
+function pmUninstallArgs(pm, pkg) {
+    if (pm === "pnpm")
+        return ["remove", pkg];
+    if (pm === "yarn")
+        return ["remove", pkg];
+    if (pm === "bun")
+        return ["remove", pkg];
+    return ["uninstall", pkg];
+}
+function buildLaunchPlan(pm, pkg, workspacePath) {
+    const displayCommand = pmInstallCommand(pm, pkg);
+    const pmArgs = pmInstallArgs(pm, pkg);
+    if (os.platform() === "win32") {
+        const cmdLine = [pm, ...pmArgs].join(" ");
+        return { displayCommand, pm, pmArgs, executable: process.env.ComSpec || "cmd.exe", args: ["/d", "/s", "/c", cmdLine], cwd: workspacePath };
+    }
+    return { displayCommand, pm, pmArgs, executable: pm, args: pmArgs, cwd: workspacePath };
+}
+function buildProbePlan(pm, workspacePath) {
+    const displayCommand = pm + " --version";
+    const pmArgs = ["--version"];
+    if (os.platform() === "win32") {
+        const cmdLine = pm + " --version";
+        return { displayCommand, pm, pmArgs, executable: process.env.ComSpec || "cmd.exe", args: ["/d", "/s", "/c", cmdLine], cwd: workspacePath };
+    }
+    return { displayCommand, pm, pmArgs, executable: pm, args: pmArgs, cwd: workspacePath };
+}
+async function runLauncher(plan) {
+    return new Promise((resolve) => {
+        const child = (0, child_process_1.spawn)(plan.executable, plan.args, { cwd: plan.cwd, stdio: "inherit", windowsHide: true });
+        child.on("error", (err) => {
+            process.stderr.write("Setup failed: could not start " + plan.executable + " - " + err.message + "\n");
+            process.stderr.write("Is " + plan.pm + " installed and available on PATH?\n");
+            process.exitCode = 1;
+            resolve(true);
+        });
+        child.on("exit", (code) => {
+            if (code !== 0) {
+                process.stderr.write("Command exited with code " + (code ?? "null") + "\n");
+                process.exitCode = code ?? 1;
+                resolve(true);
+            }
+            else {
+                resolve(false);
+            }
+        });
+    });
+}
+async function downloadArtifacts(workspacePath, modelId, modelDir, offline) {
+    const workspaceRequire = (0, module_1.createRequire)(path.join(workspacePath, "package.json"));
+    const transformers = workspaceRequire("@huggingface/transformers");
+    const pipeline = transformers.pipeline || transformers.default?.pipeline;
+    if (typeof pipeline !== "function")
+        throw new Error("Local runtime does not export pipeline.");
+    const pipelineOpts = { cache_dir: modelDir };
+    if (offline)
+        pipelineOpts.local_files_only = true;
+    const extractor = await pipeline("feature-extraction", modelId, pipelineOpts);
+    const callFn = typeof extractor === "function" ? extractor : extractor?.__call__;
+    if (typeof callFn !== "function")
+        throw new Error("Pipeline extractor is not callable.");
+    // Run a tiny probe to force artifact materialization
+    await callFn("flowseeker model download probe");
+    // Discover artifact files recursively under modelDir
+    const artifacts = {};
+    await collectArtifacts(modelDir, modelDir, artifacts);
+    if (Object.keys(artifacts).length === 0)
+        throw new Error("No artifact files were created under " + modelDir);
+    return artifacts;
+}
+async function collectArtifacts(baseDir, currentDir, out) {
+    let entries;
+    try {
+        entries = fsSync.readdirSync(currentDir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const full = path.join(currentDir, entry.name);
+        if (entry.isDirectory()) {
+            await collectArtifacts(baseDir, full, out);
+        }
+        else if (entry.isFile()) {
+            const rel = path.relative(baseDir, full).replace(/\\/g, "/");
+            if (rel && rel !== "manifest.json")
+                out[rel] = rel;
+        }
+    }
+}
+// --- Local semantic subcommands ---
+// --- Local semantic subcommands ---
+async function runLocalCommand(args) {
+    // --help as first/only arg prints general help; recognized subcommands handle their own --help
+    const knownSubs = ["status", "setup", "download", "remove", "evidence"];
+    const hasHelp = args.some(arg => arg === "--help" || arg === "-h");
+    if (hasHelp && !(args[0] && knownSubs.includes(args[0]))) {
+        process.stdout.write("Usage: flowseeker semantic local [status|setup|download|remove|evidence] [-w <path>]\n\n");
+        process.stdout.write("Ready local package path (no API key, single install):\n");
+        process.stdout.write("  npm i -g flowseeker flowseeker-local\n");
+        process.stdout.write("  flowseeker semantic check --test\n\n");
+        process.stdout.write("Advanced project-level setup (explicit steps):\n");
+        process.stdout.write("  1. flowseeker semantic local setup --yes     # install runtime in project\n");
+        process.stdout.write("  2. flowseeker semantic local download --yes   # fetch/cache model files\n");
+        process.stdout.write("  3. flowseeker semantic check --test           # verify local embeddings\n\n");
+        process.stdout.write("Commands:\n");
+        process.stdout.write("  status    Show local provider readiness (runtime, model, result)\n");
+        process.stdout.write("  setup     Install @huggingface/transformers in your project (use --yes)\n");
+        process.stdout.write("  download  Fetch/cache local model files (use --yes, --offline for pre-cached)\n");
+        process.stdout.write("  remove    Remove local model cache from project\n");
+        process.stdout.write("  evidence  Structured local readiness report (no install/download by default)\n\n");
+        process.stdout.write("Flags:\n");
+        process.stdout.write("  --yes        Confirm action (required for setup/download/remove)\n");
+        process.stdout.write("  --no-exec    Preview the execution plan without installing/downloading\n");
+        process.stdout.write("  --offline    Pre-cached model only, no network (download only)\n");
+        process.stdout.write("  --probe      Test launcher without installing (setup only)\n");
+        process.stdout.write("  --manager    Override package manager: npm|pnpm|yarn|bun (setup only)\n");
+        process.stdout.write("  --print-command  Print install command only (setup only)\n");
+        process.stdout.write("  --force      Overwrite existing manifest (download/remove)\n");
+        process.stdout.write("  --dry-run    Preview only, no changes (default)\n\n");
+        process.stdout.write("Local runtime/model is not bundled with FlowSeeker.\n");
+        process.stdout.write("Setup installs runtime only. Download fetches/caches model files.\n");
+        process.stdout.write("No API key or hosted provider is needed for local mode.\n");
+        return;
+    }
+    const sub = args[0] && !args[0].startsWith("-") ? args[0] : "status";
+    let workspace = process.cwd();
+    let dryRun = true;
+    let yes = false;
+    let force = false;
+    let printCommand = false;
+    let modelAlias = "";
+    let manager = "";
+    let noExec = false;
+    let probe = false;
+    let offline = false;
+    for (let i = 1; i < args.length; i++) {
+        const arg = args[i];
+        const next = args[i + 1];
+        if (arg === "--help" || arg === "-h")
+            continue;
+        if ((arg === "--workspace" || arg === "-w") && next) {
+            workspace = path.resolve(next);
+            i++;
+            continue;
+        }
+        if (arg === "--dry-run") {
+            dryRun = true;
+            continue;
+        }
+        if (arg === "--yes") {
+            yes = true;
+            dryRun = false;
+            continue;
+        }
+        if (arg === "--force") {
+            force = true;
+            continue;
+        }
+        if (arg === "--print-command") {
+            printCommand = true;
+            continue;
+        }
+        if ((arg === "--model" || arg === "-m") && next) {
+            modelAlias = next;
+            i++;
+            continue;
+        }
+        if ((arg === "--manager") && next) {
+            manager = next;
+            i++;
+            continue;
+        }
+        if (arg === "--no-exec") {
+            noExec = true;
+            continue;
+        }
+        if (arg === "--probe") {
+            probe = true;
+            continue;
+        }
+        if (arg === "--offline") {
+            offline = true;
+            continue;
+        }
+        if (arg === "--json") {
+            continue;
+        }
+        if ((arg === "--report" || arg === "-r") && next) {
+            i++;
+            continue;
+        }
+        throw new Error(`Unknown local option: ${arg}`);
+    }
+    const resolved = path.resolve(workspace);
+    const configPath = path.join(resolved, ".flowseeker", "config.json");
+    const modelBasePath = path.join(resolved, ".flowseeker", "models");
+    const modelSlug = modelAlias || LOCAL_MODEL_PROFILE.modelSlug;
+    // Reject unsafe model aliases
+    if (modelAlias && (modelAlias.includes("..") || modelAlias.includes("/") || modelAlias.includes("\\") || modelAlias.length > 200)) {
+        process.stderr.write("Unsafe model alias: " + modelAlias + "\n");
+        process.exitCode = 1;
+        return;
+    }
+    const modelDir = path.join(modelBasePath, modelSlug);
+    const manifestPath = path.join(modelDir, "manifest.json");
+    const configExists = await fileExists(configPath);
+    let provider = "none";
+    if (configExists) {
+        try {
+            const c = JSON.parse(await fs.readFile(configPath, "utf8"));
+            const idx = c.index || {};
+            provider = String(idx.semanticProvider || "none");
+        }
+        catch { /* unreadable */ }
+    }
+    if (sub === "status") {
+        let localModelPath = "";
+        let localDimensions = 0;
+        if (configExists && provider === "local") {
+            try {
+                const c = JSON.parse(await fs.readFile(configPath, "utf8"));
+                const idx = c.index || {};
+                localModelPath = String(idx.semanticLocalModelPath || "");
+                localDimensions = Number(idx.semanticDimensions || 0);
+            }
+            catch { /* unreadable */ }
+        }
+        // If manifest exists, use its model path
+        if (await fileExists(manifestPath)) {
+            try {
+                const m = JSON.parse(await fs.readFile(manifestPath, "utf8"));
+                localModelPath = String(m.modelPath || localModelPath);
+                localDimensions = Number(m.dimensions || localDimensions);
+            }
+            catch { /* unreadable */ }
+        }
+        const readiness = (0, embeddingProviders_1.getLocalProviderReadiness)(resolved, {
+            semanticModel: provider !== "local" ? "" : "local-minilm-v1",
+            semanticLocalModelPath: localModelPath,
+            semanticDimensions: localDimensions
+        });
+        const manifestStatus = await fileExists(manifestPath) ? "exists" : "not found";
+        const lines = ["FlowSeeker local embedding status", "", `Workspace: ${resolved}`, `Config: ${configExists ? "exists" : "not found"}`, `Provider: ${provider}`, `Runtime: ${readiness.runtimeStatus}`, `Model path: ${localModelPath || modelBasePath}`, `Manifest: ${manifestStatus}`, `Models: none downloaded`, "", `Result: ${readiness.localStatus}`, `Next action: ${readiness.nextAction}`];
+        process.stdout.write(lines.join("\n") + "\n");
+    }
+    else if (sub === "setup") {
+        // Validate manager
+        const validManagers = ["npm", "pnpm", "yarn", "bun"];
+        if (manager && !validManagers.includes(manager)) {
+            process.stderr.write("Invalid manager: " + manager + ". Use: " + validManagers.join(", ") + "\n");
+            process.exitCode = 1;
+            return;
+        }
+        const pm = detectPackageManager(resolved, manager);
+        const installCmd = pmInstallCommand(pm, "@huggingface/transformers");
+        const uninstallCmd = pmUninstallCommand(pm, "@huggingface/transformers");
+        const runtimeAvailable = (0, embeddingProviders_1.detectLocalRuntime)(resolved);
+        if (printCommand) {
+            process.stdout.write(installCmd + "\n");
+        }
+        else if (yes) {
+            if (probe) {
+                const plan = buildProbePlan(pm, resolved);
+                if (noExec) {
+                    process.stdout.write("NO-EXEC PROBE: Would run in " + resolved + ":\n");
+                    process.stdout.write("  Command: " + plan.displayCommand + "\n");
+                    process.stdout.write("  Launcher: " + plan.executable + "\n");
+                    process.stdout.write("  Launcher args: " + JSON.stringify(plan.args) + "\n");
+                    process.stdout.write("Execution skipped (--no-exec).\n");
+                }
+                else {
+                    process.stdout.write("Probing launcher: " + plan.executable + " " + plan.args.join(" ") + "\n");
+                    const probeFailed = await runLauncher(plan);
+                    if (!probeFailed) {
+                        process.stdout.write("Launcher probe: OK\n");
+                        process.stdout.write("Next action: Run flowseeker semantic local setup --yes to install the runtime.\n");
+                    }
+                }
+            }
+            else {
+                const plan = buildLaunchPlan(pm, "@huggingface/transformers", resolved);
+                if (noExec) {
+                    process.stdout.write("NO-EXEC: Would run in " + resolved + ":\n");
+                    process.stdout.write("  Command: " + plan.displayCommand + "\n");
+                    process.stdout.write("  Launcher: " + plan.executable + "\n");
+                    process.stdout.write("  Launcher args: " + JSON.stringify(plan.args) + "\n");
+                    process.stdout.write("  CWD: " + plan.cwd + "\n");
+                    process.stdout.write("Execution skipped (--no-exec).\n");
+                    process.stdout.write("Next action: Run flowseeker semantic local status to check runtime readiness.\n");
+                }
+                else {
+                    process.stdout.write("Installing local embedding runtime...\n");
+                    process.stdout.write("Package manager: " + pm + "\n");
+                    process.stdout.write("Command: " + plan.displayCommand + "\n");
+                    const installFailed = await runLauncher(plan);
+                    if (!installFailed) {
+                        process.stdout.write("Setup complete. Next action: Run flowseeker semantic local status.\n");
+                    }
+                }
+            }
+        }
+        else {
+            process.stdout.write("Local embedding runtime setup plan:\n\n");
+            process.stdout.write("The runtime (@huggingface/transformers) will be installed in YOUR project.\n");
+            process.stdout.write("FlowSeeker itself stays lean.\n\n");
+            process.stdout.write("Package manager: " + pm + "\n");
+            process.stdout.write("Install command: " + installCmd + "\n");
+            process.stdout.write("Rollback command: " + uninstallCmd + "\n\n");
+            process.stdout.write("Runtime status: " + (runtimeAvailable ? "available" : "not installed") + "\n\n");
+            process.stdout.write("Use --print-command for machine-readable output.\n");
+            process.stdout.write("Use --manager npm|pnpm|yarn|bun to override auto-detection.\n");
+            process.stdout.write("Use --yes to install the runtime in this project.\n");
+            process.stdout.write("Use --yes --no-exec to preview the execution plan.\n");
+            process.stdout.write("Use --yes --probe to test the launcher (safe, no install).\n");
+            process.stdout.write("setup does NOT download the model. Run semantic local download after setup.\n");
+        }
+    }
+    else if (sub === "download") {
+        const runtimeAvailable = (0, embeddingProviders_1.detectLocalRuntime)(resolved);
+        // Dry-run: always useful, even without runtime
+        if (dryRun) {
+            process.stdout.write("DRY-RUN download plan:\n");
+            process.stdout.write("  Model: " + LOCAL_MODEL_PROFILE.modelId + "\n");
+            process.stdout.write("  Cache dir: " + modelDir + "\n");
+            process.stdout.write("  Manifest path: " + manifestPath + "\n");
+            process.stdout.write("  Runtime: " + (runtimeAvailable ? "available" : "not installed") + "\n");
+            process.stdout.write("  Creates no files.\n");
+            process.stdout.write("  Default: allows fetching/caching model files via project runtime.\n");
+            process.stdout.write("  Use --offline for pre-cached model only (no network).\n");
+            if (!runtimeAvailable)
+                process.stdout.write("  Next action: Run flowseeker semantic local setup to install runtime.\n");
+            else
+                process.stdout.write("  Next action: Use --yes to download the model to " + modelDir + ".\n");
+            return;
+        }
+        if (!runtimeAvailable && !noExec) {
+            process.stdout.write("Local runtime not found. Run flowseeker semantic local setup first.\n");
+            process.exitCode = 1;
+            return;
+        }
+        if (yes) {
+            if (noExec) {
+                process.stdout.write("NO-EXEC: Would download model to " + modelDir + "\n");
+                process.stdout.write("  Model: " + LOCAL_MODEL_PROFILE.modelId + "\n");
+                process.stdout.write("  Runtime: " + (runtimeAvailable ? "available" : "not installed") + "\n");
+                process.stdout.write("  Offline: " + (offline ? "yes (no network)" : "no (may fetch/cache)") + "\n");
+                process.stdout.write("Execution skipped (--no-exec).\n");
+                if (!runtimeAvailable)
+                    process.stdout.write("Next action: Run flowseeker semantic local setup first.\n");
+                return;
+            }
+            const manifestExists = await fileExists(manifestPath);
+            if (manifestExists && !force) {
+                process.stdout.write("Model manifest already exists: " + manifestPath + "\nUse --force to overwrite.\n");
+                return;
+            }
+            try {
+                const artifacts = await downloadArtifacts(resolved, LOCAL_MODEL_PROFILE.modelId, modelDir, offline);
+                const manifest = {
+                    schemaVersion: LOCAL_MODEL_PROFILE.schemaVersion,
+                    provider: "local",
+                    modelId: LOCAL_MODEL_PROFILE.modelId,
+                    modelSlug: LOCAL_MODEL_PROFILE.modelSlug,
+                    dimensions: LOCAL_MODEL_PROFILE.dimensions,
+                    createdAt: new Date().toISOString(),
+                    source: "huggingface",
+                    status: "ready",
+                    runtimePackage: LOCAL_MODEL_PROFILE.runtimePackage,
+                    artifacts
+                };
+                await fs.mkdir(modelDir, { recursive: true });
+                await fs.writeFile(manifestPath, JSON.stringify(manifest, null, 2) + "\n", "utf8");
+                process.stdout.write("Model downloaded: " + modelDir + (offline ? " (offline)" : "") + "\n");
+                process.stdout.write("Manifest written: " + manifestPath + " (status: ready)\n");
+                // Update config
+                if (configExists) {
+                    try {
+                        const c = JSON.parse(await fs.readFile(configPath, "utf8"));
+                        const idx = c.index || {};
+                        idx.semanticProvider = "local";
+                        idx.semanticLocalModelPath = modelDir;
+                        idx.semanticDimensions = LOCAL_MODEL_PROFILE.dimensions;
+                        idx.semanticLocalModelId = LOCAL_MODEL_PROFILE.modelId;
+                        c.index = idx;
+                        await fs.writeFile(configPath, JSON.stringify(c, null, 2) + "\n", "utf8");
+                        process.stdout.write("Config updated: " + configPath + "\n");
+                    }
+                    catch { /* config write non-fatal */ }
+                }
+                process.stdout.write("Next action: Run flowseeker semantic check --test to verify local embeddings.\n");
+            }
+            catch (err) {
+                // Clean up on failure — don't leave partial state
+                try {
+                    await fs.rm(modelDir, { recursive: true, force: true });
+                }
+                catch { /* best effort */ }
+                process.stderr.write("Download failed: " + (err instanceof Error ? err.message : String(err)) + "\n");
+                process.stderr.write("No model artifacts were saved. Re-run with --force to retry.\n");
+                process.exitCode = 1;
+            }
+        }
+        else {
+            process.stdout.write("Local model download plan:\n\n");
+            process.stdout.write("Model: " + LOCAL_MODEL_PROFILE.modelId + " (" + LOCAL_MODEL_PROFILE.dimensions + " dimensions)\n");
+            process.stdout.write("Cache: " + modelDir + "\n\n");
+            process.stdout.write("Default: allows fetching/caching model files via project runtime.\n");
+            process.stdout.write("Use --offline for pre-cached model only (no network).\n");
+            process.stdout.write("Use --dry-run to preview. Use --yes to download.\n");
+            process.stdout.write("Use --yes --no-exec to preview the download plan.\n");
+        }
+    }
+    else if (sub === "remove") {
+        // Path safety: modelDir must be inside modelBasePath
+        const resolvedBase = path.resolve(modelBasePath);
+        const resolvedDir = path.resolve(modelDir);
+        if (!resolvedDir.startsWith(resolvedBase + path.sep) && resolvedDir !== resolvedBase) {
+            process.stderr.write("Path safety: model dir " + resolvedDir + " is outside " + resolvedBase + "\n");
+            process.exitCode = 1;
+            return;
+        }
+        const manifestExists = await fileExists(manifestPath);
+        if (!manifestExists) {
+            process.stdout.write("No model manifest found at " + manifestPath + "\nNothing to remove.\n");
+            return;
+        }
+        if (dryRun) {
+            process.stdout.write("DRY-RUN: Would remove " + modelDir + "\n");
+            process.stdout.write("Use --yes to confirm.\n");
+        }
+        else if (yes) {
+            try {
+                await fs.rm(modelDir, { recursive: true, force: true });
+            }
+            catch { /* already gone */ }
+            process.stdout.write("Removed: " + modelDir + "\n");
+            // Clear model config fields
+            if (configExists) {
+                try {
+                    const c = JSON.parse(await fs.readFile(configPath, "utf8"));
+                    const idx = c.index || {};
+                    delete idx.semanticLocalModelPath;
+                    delete idx.semanticDimensions;
+                    delete idx.semanticLocalModelId;
+                    c.index = idx;
+                    await fs.writeFile(configPath, JSON.stringify(c, null, 2) + "\n", "utf8");
+                    process.stdout.write("Config cleaned: removed semanticLocalModelPath, semanticDimensions, semanticLocalModelId\n");
+                }
+                catch { /* config write failed */ }
+            }
+        }
+        else {
+            process.stdout.write("Local model remove plan:\n\n");
+            process.stdout.write("Would remove: " + modelDir + "\n");
+            process.stdout.write("Use --dry-run to preview. Use --yes to confirm.\n");
+        }
+    }
+    else if (sub === "evidence") {
+        // --help should print help even without other flags
+        if (args.some(arg => arg === "--help" || arg === "-h")) {
+            process.stdout.write("Usage: flowseeker semantic local evidence [--json] [--report <path>] [--workspace <path>]\n\n");
+            process.stdout.write("Produce a structured local embedding readiness/evidence report.\n");
+            process.stdout.write("Report-only by default: no install, no download, no network, no hosted fallback.\n\n");
+            process.stdout.write("Options:\n");
+            process.stdout.write("  --json                   Print JSON report to stdout\n");
+            process.stdout.write("  --report <path>          Write JSON report to file\n");
+            process.stdout.write("  -w, --workspace <path>   Target workspace (default: current directory)\n\n");
+            process.stdout.write("Setup and download are explicit separate commands:\n");
+            process.stdout.write("  flowseeker semantic local setup --yes\n");
+            process.stdout.write("  flowseeker semantic local download --yes\n");
+            return;
+        }
+        let useJson = false;
+        let reportPath = "";
+        for (let i = 1; i < args.length; i++) {
+            if (args[i] === "--json") {
+                useJson = true;
+            }
+            else if ((args[i] === "--report" || args[i] === "-r") && args[i + 1]) {
+                reportPath = args[++i];
+            }
+            else if (args[i] === "--workspace" || args[i] === "-w") {
+                i++;
+            }
+        }
+        const modelPath = await readConfigModelPath(configPath);
+        const effectiveModelPath = modelPath || modelDir;
+        const readiness = (0, embeddingProviders_1.getLocalProviderReadiness)(resolved, {
+            semanticModel: "local-minilm-v1",
+            semanticLocalModelPath: effectiveModelPath,
+            semanticDimensions: 384
+        });
+        const statusMap = {
+            "local_unavailable_runtime_missing": "runtime_missing",
+            "local_unavailable_model_missing": "model_missing",
+            "local_unavailable_model_invalid": "model_invalid",
+            "local_ready": "pass",
+            "bundled_package_ready": "pass",
+            "bundled_package_missing": "model_missing",
+            "bundled_package_invalid": "model_invalid"
+        };
+        const classification = statusMap[readiness.localStatus] || "unknown_error";
+        const evidence = {
+            timestamp: new Date().toISOString(),
+            workspace: resolved,
+            runtimeStatus: readiness.runtimeStatus,
+            modelStatus: readiness.modelStatus,
+            readinessStatus: readiness.localStatus,
+            providerName: "local",
+            modelId: "",
+            dimensions: 0,
+            vectorCount: 0,
+            allFinite: false,
+            embedLatencyMs: 0,
+            classification,
+            nextAction: readiness.nextAction,
+            allowInstall: false,
+            allowDownload: false
+        };
+        const isReady = readiness.localStatus === "local_ready" || readiness.localStatus === "bundled_package_ready";
+        if (isReady && (effectiveModelPath || readiness.localStatus === "bundled_package_ready")) {
+            let modelSrcPath = effectiveModelPath;
+            if (readiness.localStatus === "bundled_package_ready") {
+                // Get model info from bundled package
+                const bundled = (0, embeddingProviders_1.detectBundledLocalPackage)(resolved);
+                if (bundled.valid && bundled.packagePath) {
+                    evidence.modelId = bundled.modelId || evidence.modelId;
+                    evidence.dimensions = bundled.dimensions || evidence.dimensions;
+                    modelSrcPath = path.dirname(bundled.manifestPath || bundled.packagePath);
+                }
+            }
+            evidence.modelId = LOCAL_MODEL_PROFILE.modelId;
+            evidence.dimensions = LOCAL_MODEL_PROFILE.dimensions;
+            try {
+                const mfPath = path.join(effectiveModelPath, "manifest.json");
+                if (await fileExists(mfPath)) {
+                    const mf = JSON.parse(await fs.readFile(mfPath, "utf8"));
+                    if (mf.modelId)
+                        evidence.modelId = mf.modelId;
+                    if (mf.dimensions)
+                        evidence.dimensions = Number(mf.dimensions);
+                }
+            }
+            catch { /* use defaults */ }
+            const provider = (0, embeddingProviders_1.createConfiguredEmbeddingProvider)({
+                semanticProvider: "local", semanticBaseUrl: "", semanticApiKeyEnv: "",
+                semanticModel: String(evidence.modelId), semanticTimeoutMs: 60000,
+                semanticLocalModelPath: effectiveModelPath, semanticDimensions: Number(evidence.dimensions),
+                workspacePath: resolved
+            });
+            if (provider) {
+                const t0 = Date.now();
+                try {
+                    const vectors = await provider.embedTexts(["flowseeker semantic local evidence"]);
+                    evidence.embedLatencyMs = Date.now() - t0;
+                    evidence.vectorCount = vectors.length;
+                    evidence.allFinite = vectors.length > 0 && vectors.every((v) => v.every((x) => isFinite(x)));
+                    evidence.classification = "pass";
+                    evidence.nextAction = "Local embedding provider is ready.";
+                }
+                catch (err) {
+                    evidence.embedLatencyMs = Date.now() - t0;
+                    const msg = err instanceof Error ? err.message : String(err);
+                    evidence.classification = msg.indexOf("dimension") >= 0 || msg.indexOf("non-numeric") >= 0 ? "embedding_shape_invalid"
+                        : msg.indexOf("pipeline") >= 0 || msg.indexOf("export") >= 0 ? "runtime_api_mismatch" : "unknown_error";
+                    evidence.nextAction = msg;
+                }
+            }
+        }
+        // Write report file if requested (before stdout to keep JSON clean)
+        if (reportPath) {
+            const absReport = path.resolve(reportPath);
+            await fs.mkdir(path.dirname(absReport), { recursive: true });
+            await fs.writeFile(absReport, JSON.stringify(evidence, null, 2) + "\n", "utf8");
+        }
+        if (useJson) {
+            // --json: valid JSON only to stdout, no trailing text
+            process.stdout.write(JSON.stringify(evidence, null, 2) + "\n");
+        }
+        else if (reportPath) {
+            // --report without --json: also print JSON to stdout plus confirmation
+            process.stdout.write(JSON.stringify(evidence, null, 2) + "\n");
+            process.stdout.write("Report written: " + path.resolve(reportPath) + "\n");
+        }
+        else {
+            const lines = [
+                "Local embedding evidence report", "",
+                "Workspace: " + evidence.workspace,
+                "Runtime: " + evidence.runtimeStatus,
+                "Model: " + evidence.modelStatus,
+                "Readiness: " + evidence.readinessStatus,
+                "Classification: " + evidence.classification,
+                "Next action: " + evidence.nextAction
+            ];
+            if (evidence.modelId)
+                lines.push("Model ID: " + evidence.modelId);
+            if (Number(evidence.dimensions) > 0)
+                lines.push("Dimensions: " + evidence.dimensions);
+            if (Number(evidence.vectorCount) > 0)
+                lines.push("Vectors: " + evidence.vectorCount + " (all finite: " + evidence.allFinite + ")");
+            if (Number(evidence.embedLatencyMs) > 0)
+                lines.push("Latency: " + evidence.embedLatencyMs + "ms");
+            process.stdout.write(lines.join("\n") + "\n");
+        }
+    }
+    else {
+        throw new Error(`Unknown local subcommand: ${sub}`);
+    }
+}
+async function readConfigModelPath(configPath) {
+    try {
+        const c = JSON.parse(await fs.readFile(configPath, "utf8"));
+        const idx = c.index || {};
+        return String(idx.semanticLocalModelPath || "");
+    }
+    catch {
+        return "";
+    }
+}
+// --- End local ---
+// --- Benchmark ---
+async function runBenchmarkCommand(args) {
+    let workspace = process.cwd();
+    let useJson = false;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        const next = args[i + 1];
+        if (arg === "--help" || arg === "-h") {
+            process.stderr.write("Usage: flowseeker benchmark [--workspace <path>] [--json]\n");
+            return;
+        }
+        if ((arg === "--workspace" || arg === "-w") && next) {
+            workspace = path.resolve(next);
+            i++;
+            continue;
+        }
+        if (arg === "--json") {
+            useJson = true;
+            continue;
+        }
+        throw new Error(`Unknown benchmark option: ${arg}`);
+    }
+    const resolved = path.resolve(workspace);
+    const config = await (0, loadConfigFromPath_1.loadConfigFromPath)(resolved);
+    const localReadiness = (0, embeddingProviders_1.getLocalProviderReadiness)(resolved, {
+        semanticModel: config.index.semanticModel,
+        semanticLocalModelPath: config.index.semanticLocalModelPath,
+        semanticDimensions: config.index.semanticDimensions
+    });
+    const hostedStatus = determineHostedStatus(config.index);
+    const modes = [
+        {
+            mode: "deterministic_no_embedding",
+            status: "first_class",
+            qualityMeasured: true,
+            performanceMeasured: true,
+            reasonWhenSkipped: "",
+            filesScanned: "smoke gate passing, publishable claims verified",
+            runtimeMs: 0,
+            regressionGate: "pass",
+            nextAction: "No action needed. Deterministic retrieval is the default and fully functional."
+        },
+        {
+            mode: "hosted_semantic",
+            status: hostedStatus.status,
+            qualityMeasured: false,
+            performanceMeasured: false,
+            reasonWhenSkipped: hostedStatus.reasonWhenSkipped,
+            filesScanned: 0,
+            runtimeMs: 0,
+            regressionGate: "pass",
+            nextAction: hostedStatus.nextAction
+        },
+        {
+            mode: "local_provider",
+            status: localReadiness.localStatus,
+            qualityMeasured: false,
+            performanceMeasured: true,
+            reasonWhenSkipped: localReadiness.reasonWhenSkipped,
+            filesScanned: 0,
+            runtimeMs: 0,
+            regressionGate: localReadiness.localStatus === "local_unavailable_runtime_missing" || localReadiness.localStatus.indexOf("ready") >= 0 ? "pass" : "warn",
+            nextAction: localReadiness.nextAction
+        }
+    ];
+    if (useJson) {
+        process.stdout.write(JSON.stringify({ workspace: resolved, modes }, null, 2) + "\n");
+    }
+    else {
+        const lines = ["FlowSeeker benchmark report", "", `Workspace: ${resolved}`];
+        for (const m of modes) {
+            lines.push("", `Mode: ${m.mode}`, `Status: ${m.status}`, `Quality measured: ${m.qualityMeasured}`, `Performance measured: ${m.performanceMeasured}`, `Regression gate: ${m.regressionGate}`, `Next action: ${m.nextAction}`);
+            if (m.reasonWhenSkipped)
+                lines.push(`Reason: ${m.reasonWhenSkipped}`);
+        }
+        process.stdout.write(lines.join("\n") + "\n");
+    }
+}
+function determineHostedStatus(idx) {
+    if (!idx.semanticEnabled)
+        return { status: "disabled", reasonWhenSkipped: "Semantic retrieval is disabled. Run flowseeker semantic init --jina or --openai-compatible.", nextAction: "Run flowseeker semantic init --jina or --openai-compatible" };
+    if (idx.semanticProvider === "local")
+        return { status: "not_active", reasonWhenSkipped: "Hosted semantic is not active when provider is local.", nextAction: "" };
+    if (idx.semanticProvider === "openaiCompatible" && !idx.semanticModel)
+        return { status: "incomplete_config", reasonWhenSkipped: "semanticModel is empty. Set it to the embedding model exposed by your provider in .flowseeker/config.json.", nextAction: "Edit .flowseeker/config.json: set semanticModel to your provider's embedding model." };
+    if (!process.env[idx.semanticApiKeyEnv])
+        return { status: "skipped_no_key", reasonWhenSkipped: idx.semanticApiKeyEnv + " is missing or empty.", nextAction: "Set " + idx.semanticApiKeyEnv + " in .env and re-run flowseeker semantic check --test." };
+    return { status: "configured", reasonWhenSkipped: "", nextAction: "Run flowseeker semantic check --test to verify hosted embeddings." };
+}
+async function runFlowCommand(options) {
+    const input = {
+        task: options.task,
+        workspace: options.workspace,
+        maxFiles: options.maxFiles,
+        limit: options.limit
+    };
+    const result = await (0, mcpTools_1.handleToolCall)(modeToToolName(options.mode), input, options.workspace);
+    const text = result.content.map((item) => item.text).join("\n\n");
+    if (options.outFile) {
+        await fs.mkdir(path.dirname(path.resolve(options.outFile)), { recursive: true });
+        await fs.writeFile(options.outFile, text, "utf8");
+    }
+    else {
+        process.stdout.write(`${text}\n`);
+    }
+    if (result.isError) {
+        process.exitCode = 1;
+    }
+}
+async function runMcpServer(args) {
+    const serverPath = path.join(__dirname, "mcpServer.js");
+    await new Promise((resolve, reject) => {
+        const child = (0, child_process_1.spawn)(process.execPath, [serverPath, ...args], {
+            stdio: "inherit",
+            windowsHide: true
+        });
+        child.on("error", reject);
+        child.on("exit", (code, signal) => {
+            if (signal) {
+                process.kill(process.pid, signal);
+                return;
+            }
+            process.exitCode = code ?? 0;
+            resolve();
+        });
+    });
+}
+function parseFlowArgs(mode, args) {
+    let workspace = process.cwd();
+    let maxFiles;
+    let limit;
+    let outFile;
+    const taskParts = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        const next = args[i + 1];
+        if (arg === "--help" || arg === "-h") {
+            printCommandHelp(mode);
+            process.exit(0);
+        }
+        if ((arg === "--workspace" || arg === "-w") && next) {
+            workspace = path.resolve(next);
+            i++;
+            continue;
+        }
+        if (arg === "--max-files" && next) {
+            maxFiles = parsePositiveInt(next, "--max-files");
+            i++;
+            continue;
+        }
+        if ((arg === "--limit" || arg === "-n") && next) {
+            limit = parsePositiveInt(next, "--limit");
+            i++;
+            continue;
+        }
+        if ((arg === "--out" || arg === "-o") && next) {
+            outFile = next;
+            i++;
+            continue;
+        }
+        if (arg.startsWith("-")) {
+            throw new Error(`Unknown option: ${arg}`);
+        }
+        taskParts.push(arg);
+    }
+    const task = taskParts.join(" ").trim();
+    if (!task) {
+        printCommandHelp(mode);
+        throw new Error("Task is required.");
+    }
+    return { mode, workspace, task, maxFiles, limit, outFile };
+}
+function modeToToolName(mode) {
+    switch (mode) {
+        case "auto":
+            return "flowseeker_auto";
+        case "files":
+            return "flowseeker_files";
+        case "retrieve":
+            return "flowseeker_retrieve";
+        case "guide":
+        default:
+            return "flowseeker_guide";
+    }
+}
+function parsePositiveInt(value, option) {
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new Error(`${option} must be a positive integer.`);
+    }
+    return parsed;
+}
+async function printVersion() {
+    const packageJsonPath = path.resolve(__dirname, "../../package.json");
+    const raw = await fs.readFile(packageJsonPath, "utf8");
+    const parsed = JSON.parse(raw);
+    process.stdout.write(`${parsed.version ?? "unknown"}\n`);
+}
+function printHelp() {
+    const lines = [
+        "FlowSeeker",
+        "",
+        "Usage:",
+        "  flowseeker guide \"Fix checkout webhook retry\"",
+        "  flowseeker auto \"Add CSV export with tests\"",
+        "  flowseeker files \"Find auth middleware\"",
+        "  flowseeker retrieve \"Debug login session expiry\"",
+        "  flowseeker mcp --workspace .",
+        "  flowseeker semantic init",
+        "  flowseeker semantic check --test",
+        "",
+        "Commands:",
+        "  guide      Build an agent guidance prompt from retrieved context.",
+        "  auto       Build a reviewable implementation-plan prompt.",
+        "  files      Print top ranked files only.",
+        "  retrieve   Print the full Solve Packet.",
+        "  mcp        Start the FlowSeeker MCP stdio server.",
+        "  semantic   Init or check optional semantic embedding retrieval.",
+        "  doctor     Diagnose install, config, semantic, and MCP status.",
+        "  setup      Configure FlowSeeker MCP for Claude, Codex, Cursor, VS Code.",
+        "  benchmark  Report retrieval mode readiness (offline, no key needed).",
+        "  claude     Print Claude Code MCP setup commands.",
+        "",
+        "Options for guide/auto/files/retrieve:",
+        "  -w, --workspace <path>  Workspace root. Default: current directory.",
+        "  -o, --out <file>        Write output to a file instead of stdout.",
+        "  -n, --limit <count>     File limit for files. Default: 15.",
+        "  --max-files <count>     Scan cap for retrieve.",
+        "",
+        "Aliases:",
+        "  fs-guide, fs-auto, fs-files, fs-retrieve, fs-mcp",
+        ""
+    ];
+    process.stdout.write(lines.join("\n") + "\n");
+}
+function printSemanticHelp() {
+    const lines = [
+        "FlowSeeker semantic retrieval",
+        "",
+        "Usage:",
+        "  flowseeker semantic init --jina",
+        "  flowseeker semantic init --openai-compatible",
+        "  flowseeker semantic init --local",
+        "  flowseeker semantic check",
+        "  flowseeker semantic check --test",
+        "  flowseeker semantic local status",
+        "  flowseeker semantic local setup",
+        "  flowseeker semantic local download",
+        "",
+        "Init presets:",
+        "  --jina              Hosted Jina embeddings preset (recommended quick start)",
+        "  --openai-compatible Generic OpenAI-compatible path; configure model/base URL before testing",
+        "  --local             Local embeddings via explicit project-level runtime setup",
+        "",
+        "Local commands:",
+        "  semantic local status   Show local provider readiness (runtime, model, status)",
+        "  semantic local setup    Install @huggingface/transformers in your project",
+        "  semantic local download Fetch/cache local model files",
+        "",
+        "Ready local package path (no API key, single install):",
+        "  npm i -g flowseeker flowseeker-local",
+        "  flowseeker semantic check --test",
+        "",
+        "Note: Local runtime/model is not bundled with FlowSeeker.",
+        "Setup installs runtime only. Download fetches/caches model files.",
+        "No API key or hosted provider is needed for local mode.",
+        "Run `flowseeker semantic local --help` for the full local command reference.",
+        "",
+        "Options:",
+        "  -w, --workspace <path>  Workspace root. Default: current directory.",
+        "  --test                  Call the embedding provider once to verify key/model/base URL.",
+        "",
+        "Config (stored in .flowseeker/config.json):",
+        "  semanticProvider    e.g. openaiCompatible",
+        "  semanticBaseUrl     Provider endpoint (https://api.jina.ai/v1 or your own)",
+        "  semanticModel       Embedding model name exposed by your provider",
+        "  semanticApiKeyEnv   Env var holding the API key (FLOWSEEKER_EMBEDDING_API_KEY)",
+        "",
+        "Secret (stored in .env only):",
+        "  FLOWSEEKER_EMBEDDING_API_KEY=<your key>",
+        "",
+        "The model must match the provider and base URL.",
+        "",
+        "Fast setup:",
+        "  flowseeker semantic init --jina",
+        "  # fill FLOWSEEKER_EMBEDDING_API_KEY in .env",
+        "  flowseeker semantic check --test",
+        ""
+    ];
+    process.stdout.write(lines.join("\n") + "\n");
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function printCommandHelp(mode) {
+    const lines = [
+        `Usage: flowseeker ${mode} [options] "task description"`,
+        "",
+        "Options:",
+        "  -w, --workspace <path>  Workspace root. Default: current directory.",
+        "  -o, --out <file>        Write output to a file instead of stdout.",
+        "  -n, --limit <count>     File limit for files. Default: 15.",
+        "  --max-files <count>     Scan cap for retrieve.",
+        ""
+    ];
+    console.error(lines.join("\n"));
+}
+function printClaudeSetup() {
+    const lines = [
+        "Claude Code setup",
+        "",
+        "1. Install globally:",
+        "   npm i -g flowseeker",
+        "",
+        "2. Add FlowSeeker as an MCP server from your target repo:",
+        "   claude mcp add flowseeker -- flowseeker mcp --workspace .",
+        "",
+        "3. In Claude Code, ask it to use FlowSeeker:",
+        "   Use FlowSeeker to guide: Fix checkout webhook retry",
+        "",
+        "Direct prompt workflow without MCP:",
+        "   flowseeker auto \"Fix checkout webhook retry\" --out .flowseeker/agent-prompt.md",
+        ""
+    ];
+    process.stdout.write(lines.join("\n"));
+}
+//# sourceMappingURL=main.js.map