umbrella-context 0.1.39 → 0.1.41

package/dist/swarm/runtime.js

@@ -0,0 +1,957 @@
+import { createHash } from "crypto";
+import { promises as fs } from "fs";
+import path from "path";
+import prompts from "prompts";
+import { z } from "zod";
+import { configManager } from "../config.js";
+import { addPendingMemory, buildLocalQueryFingerprint, ensureRepoContext, getPendingMemories, getPulledMemories, getRepoContext, listKnowledgeSources, summarizeLocalMemoryMatches, } from "../repo-state.js";
+const SWARM_DIR = "swarm";
+const SWARM_CONFIG_FILE = "config.json";
+const SWARM_CACHE_FILE = "query-cache.json";
+const DEFAULT_CACHE_TTL_MS = 15_000;
+const DEFAULT_MAX_RESULTS = 8;
+const OBSIDIAN_IGNORE_NAMES = new Set([".git", ".obsidian", ".trash", "templates"]);
+const COMMON_STOP_WORDS = new Set([
+    "a",
+    "an",
+    "and",
+    "are",
+    "do",
+    "does",
+    "for",
+    "how",
+    "implemented",
+    "in",
+    "is",
+    "of",
+    "the",
+    "to",
+    "what",
+    "where",
+    "why",
+]);
+const SwarmFolderSchema = z.object({
+    followWikilinks: z.boolean().optional().default(true),
+    id: z.string(),
+    name: z.string(),
+    path: z.string(),
+    readOnly: z.boolean().optional().default(true),
+});
+const SwarmConfigSchema = z.object({
+    enrichment: z.object({
+        edges: z.array(z.object({ from: z.string(), to: z.string() })).default([]),
+        enabled: z.boolean().default(false),
+    }).default({ enabled: false, edges: [] }),
+    providers: z.object({
+        gbrain: z.object({
+            enabled: z.boolean().default(true),
+            notesPath: z.string(),
+            readOnly: z.boolean().optional().default(false),
+        }).optional(),
+        localMarkdown: z.object({
+            enabled: z.boolean().default(true),
+            folders: z.array(SwarmFolderSchema).default([]),
+        }).optional(),
+        memoryWiki: z.object({
+            enabled: z.boolean().default(true),
+            readOnly: z.boolean().optional().default(false),
+            wikiPath: z.string(),
+        }).optional(),
+        obsidian: z.object({
+            enabled: z.boolean().default(true),
+            readOnly: z.boolean().optional().default(true),
+            vaultPath: z.string(),
+        }).optional(),
+        umbrellaContext: z.object({
+            enabled: z.boolean().default(true),
+        }).default({ enabled: true }),
+    }),
+    routing: z.object({
+        cacheTtlMs: z.number().int().positive().default(DEFAULT_CACHE_TTL_MS),
+        defaultMaxResults: z.number().int().positive().default(DEFAULT_MAX_RESULTS),
+    }).default({ cacheTtlMs: DEFAULT_CACHE_TTL_MS, defaultMaxResults: DEFAULT_MAX_RESULTS }),
+    version: z.literal(1).default(1),
+});
+const SwarmCacheEntrySchema = z.object({
+    cacheKey: z.string(),
+    createdAt: z.string(),
+    query: z.string(),
+    result: z.any(),
+});
+function normalizeText(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^\w\s]/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+function tokenize(value) {
+    return normalizeText(value)
+        .split(/\s+/)
+        .map((token) => token.trim())
+        .filter(Boolean)
+        .filter((token) => !COMMON_STOP_WORDS.has(token));
+}
+function excerptAroundQuery(content, query, limit = 300) {
+    const normalizedContent = normalizeText(content);
+    const normalizedQuery = normalizeText(query);
+    const compact = content.replace(/\s+/g, " ").trim();
+    if (!normalizedQuery || compact.length <= limit) {
+        return compact.slice(0, limit);
+    }
+    const index = normalizedContent.indexOf(normalizedQuery);
+    if (index < 0)
+        return compact.slice(0, limit);
+    const start = Math.max(0, index - Math.floor(limit / 3));
+    const end = Math.min(compact.length, start + limit);
+    return compact.slice(start, end).trim();
+}
+function extractWikilinks(content) {
+    const links = [];
+    const regex = /\[\[([^\]|]+)(?:\|[^\]]+)?\]\]/g;
+    let match;
+    while ((match = regex.exec(content)) !== null) {
+        links.push(match[1].trim());
+    }
+    return links;
+}
+function slugifyFileName(input) {
+    return (input
+        .toLowerCase()
+        .replace(/[^\w-]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 60) || `note-${Date.now()}`);
+}
+async function ensureDir(targetPath) {
+    await fs.mkdir(targetPath, { recursive: true });
+}
+async function fileExists(targetPath) {
+    try {
+        await fs.access(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readJsonFile(targetPath, fallback) {
+    try {
+        const content = await fs.readFile(targetPath, "utf8");
+        return JSON.parse(content);
+    }
+    catch {
+        return fallback;
+    }
+}
+async function writeJsonFile(targetPath, value) {
+    await fs.writeFile(targetPath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+async function getSwarmDir(cwd = process.cwd()) {
+    const { repoRoot } = await getRepoContext(cwd);
+    const dir = path.join(repoRoot, ".um", SWARM_DIR);
+    await ensureDir(dir);
+    return dir;
+}
+export async function getSwarmConfigPath(cwd = process.cwd()) {
+    return path.join(await getSwarmDir(cwd), SWARM_CONFIG_FILE);
+}
+async function getSwarmCachePath(cwd = process.cwd()) {
+    return path.join(await getSwarmDir(cwd), SWARM_CACHE_FILE);
+}
+function buildDefaultSwarmConfig() {
+    return {
+        version: 1,
+        providers: {
+            umbrellaContext: { enabled: true },
+        },
+        enrichment: {
+            enabled: false,
+            edges: [],
+        },
+        routing: {
+            defaultMaxResults: DEFAULT_MAX_RESULTS,
+            cacheTtlMs: DEFAULT_CACHE_TTL_MS,
+        },
+    };
+}
+export async function hasSwarmConfig(cwd = process.cwd()) {
+    return fileExists(await getSwarmConfigPath(cwd));
+}
+export async function loadSwarmConfig(cwd = process.cwd()) {
+    const raw = await readJsonFile(await getSwarmConfigPath(cwd), null);
+    if (!raw)
+        return null;
+    return SwarmConfigSchema.parse(raw);
+}
+export async function saveSwarmConfig(config, cwd = process.cwd()) {
+    await writeJsonFile(await getSwarmConfigPath(cwd), SwarmConfigSchema.parse(config));
+}
+async function loadEffectiveSwarmConfig(cwd = process.cwd()) {
+    const saved = await loadSwarmConfig(cwd);
+    if (saved) {
+        return { config: saved, implicit: false };
+    }
+    const sources = await listKnowledgeSources(cwd);
+    if (sources.length > 0) {
+        return { config: buildDefaultSwarmConfig(), implicit: true };
+    }
+    return { config: null, implicit: false };
+}
+export async function ensureSwarmConfigForLinkedSources(cwd = process.cwd()) {
+    const existing = await loadSwarmConfig(cwd);
+    if (existing) {
+        return { configPath: await getSwarmConfigPath(cwd), created: false, ready: true };
+    }
+    const sources = await listKnowledgeSources(cwd);
+    if (sources.length === 0) {
+        return { configPath: await getSwarmConfigPath(cwd), created: false, ready: false };
+    }
+    const config = buildDefaultSwarmConfig();
+    await saveSwarmConfig(config, cwd);
+    return { config, configPath: await getSwarmConfigPath(cwd), created: true, ready: true };
+}
+async function readSwarmCache(cwd = process.cwd()) {
+    const raw = await readJsonFile(await getSwarmCachePath(cwd), []);
+    return raw
+        .map((entry) => SwarmCacheEntrySchema.safeParse(entry))
+        .filter((result) => result.success)
+        .map((result) => result.data);
+}
+async function writeSwarmCache(entries, cwd = process.cwd()) {
+    await writeJsonFile(await getSwarmCachePath(cwd), entries.slice(0, 20));
+}
+async function getCachedSwarmResult(cacheKey, ttlMs, cwd = process.cwd()) {
+    const now = Date.now();
+    const entries = await readSwarmCache(cwd);
+    const nextEntries = entries.filter((entry) => now - new Date(entry.createdAt).getTime() < ttlMs);
+    if (nextEntries.length !== entries.length) {
+        await writeSwarmCache(nextEntries, cwd);
+    }
+    return nextEntries.find((entry) => entry.cacheKey === cacheKey)?.result;
+}
+async function storeCachedSwarmResult(cacheKey, query, result, cwd = process.cwd()) {
+    const entries = await readSwarmCache(cwd);
+    const nextEntries = [
+        {
+            cacheKey,
+            createdAt: new Date().toISOString(),
+            query,
+            result,
+        },
+        ...entries.filter((entry) => entry.cacheKey !== cacheKey),
+    ];
+    await writeSwarmCache(nextEntries, cwd);
+}
+function buildSwarmCacheKey(query, config, localFingerprint) {
+    const configHash = createHash("sha1")
+        .update(JSON.stringify(config))
+        .digest("hex");
+    return createHash("sha1")
+        .update(`${query.trim().toLowerCase()}::${configHash}::${localFingerprint}`)
+        .digest("hex");
+}
+async function scanMarkdownFiles(rootPath, ignoreNames = new Set()) {
+    const documents = [];
+    async function walk(currentPath) {
+        let entries;
+        try {
+            entries = (await fs.readdir(currentPath, { encoding: "utf8", withFileTypes: true }));
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.name.startsWith(".") && !ignoreNames.has(entry.name)) {
+                continue;
+            }
+            if (ignoreNames.has(entry.name))
+                continue;
+            const fullPath = path.join(currentPath, entry.name);
+            if (entry.isDirectory()) {
+                await walk(fullPath);
+                continue;
+            }
+            if (!entry.name.toLowerCase().endsWith(".md"))
+                continue;
+            try {
+                const content = await fs.readFile(fullPath, "utf8");
+                const relativePath = path.relative(rootPath, fullPath);
+                const firstHeading = content.match(/^#\s+(.+)$/m)?.[1]?.trim();
+                documents.push({
+                    content,
+                    fullPath,
+                    id: relativePath,
+                    relativePath,
+                    title: firstHeading || path.basename(fullPath, ".md"),
+                    wikilinks: extractWikilinks(content),
+                });
+            }
+            catch {
+                // Skip unreadable markdown files.
+            }
+        }
+    }
+    await walk(rootPath);
+    return documents;
+}
+function scoreMarkdownDocument(query, document) {
+    const normalizedQuery = normalizeText(query);
+    const content = `${document.title}\n${document.relativePath}\n${document.content}`;
+    const normalizedContent = normalizeText(content);
+    const queryTokens = tokenize(query);
+    let score = 0;
+    let matched = 0;
+    if (normalizedQuery && normalizedContent.includes(normalizedQuery)) {
+        score += 6;
+    }
+    for (const token of queryTokens) {
+        if (normalizedContent.includes(token)) {
+            matched += 1;
+            score += 2;
+            if (normalizeText(document.title).includes(token)) {
+                score += 1;
+            }
+            if (normalizeText(document.relativePath).includes(token)) {
+                score += 0.5;
+            }
+        }
+    }
+    const coverage = queryTokens.length > 0 ? matched / queryTokens.length : 0;
+    score += coverage * 3;
+    return { coverage, score };
+}
+function dedupeSwarmHits(hits) {
+    const seen = new Set();
+    const result = [];
+    for (const hit of hits) {
+        const key = `${hit.provider}:${normalizeText(hit.content).slice(0, 180)}:${hit.source}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        result.push(hit);
+    }
+    return result;
+}
+class MarkdownSwarmProvider {
+    type;
+    rootPath;
+    id;
+    label;
+    writable;
+    constructor(type, rootPath, label, options) {
+        this.type = type;
+        this.rootPath = rootPath;
+        this.id = options?.providerId ?? `${type}:${label.toLowerCase().replace(/\s+/g, "-")}`;
+        this.label = label;
+        this.writable = options?.writable ?? false;
+        this.ignoreNames = options?.ignoreNames ?? new Set();
+        this.followWikilinks = options?.followWikilinks ?? true;
+    }
+    followWikilinks;
+    ignoreNames;
+    async healthCheck() {
+        const exists = await fileExists(this.rootPath);
+        return {
+            available: exists,
+            detail: exists ? this.rootPath : "Path not found",
+            writable: this.writable,
+        };
+    }
+    async query(query, opts) {
+        const documents = await scanMarkdownFiles(this.rootPath, this.ignoreNames);
+        const scored = documents
+            .map((document) => ({
+            document,
+            ...scoreMarkdownDocument(query, document),
+        }))
+            .filter((entry) => entry.score > 0.9)
+            .sort((a, b) => b.score - a.score);
+        const direct = scored.slice(0, opts?.maxResults ?? DEFAULT_MAX_RESULTS);
+        const hitMap = new Map();
+        for (const entry of direct) {
+            hitMap.set(entry.document.id, {
+                content: excerptAroundQuery(entry.document.content, query),
+                id: `${this.id}:${entry.document.id}`,
+                matchType: "keyword",
+                provider: this.id,
+                providerLabel: this.label,
+                providerType: this.type,
+                score: Number(entry.score.toFixed(4)),
+                source: entry.document.relativePath,
+            });
+        }
+        if (this.followWikilinks) {
+            const byRelativePath = new Map(documents.map((document) => [document.relativePath.toLowerCase(), document]));
+            for (const entry of direct) {
+                for (const link of entry.document.wikilinks) {
+                    const candidates = [
+                        `${link}.md`,
+                        link,
+                        ...documents
+                            .filter((document) => document.relativePath.toLowerCase().endsWith(`${link.toLowerCase()}.md`))
+                            .map((document) => document.relativePath),
+                    ];
+                    const linked = candidates
+                        .map((candidate) => byRelativePath.get(candidate.toLowerCase()))
+                        .find(Boolean);
+                    if (!linked || hitMap.has(linked.id))
+                        continue;
+                    hitMap.set(linked.id, {
+                        content: excerptAroundQuery(linked.content, query),
+                        id: `${this.id}:${linked.id}`,
+                        matchType: "graph",
+                        provider: this.id,
+                        providerLabel: this.label,
+                        providerType: this.type,
+                        score: Number((entry.score * 0.7).toFixed(4)),
+                        source: linked.relativePath,
+                    });
+                }
+            }
+        }
+        return [...hitMap.values()]
+            .sort((a, b) => b.score - a.score)
+            .slice(0, opts?.maxResults ?? DEFAULT_MAX_RESULTS);
+    }
+    async store(content) {
+        if (!this.writable) {
+            throw new Error(`${this.label} is read-only right now.`);
+        }
+        await ensureDir(this.rootPath);
+        const firstLine = content.split(/\r?\n/).find((line) => line.trim()) ?? "swarm-note";
+        const fileName = `${slugifyFileName(firstLine)}.md`;
+        let targetPath = path.join(this.rootPath, fileName);
+        let suffix = 1;
+        while (await fileExists(targetPath)) {
+            targetPath = path.join(this.rootPath, `${slugifyFileName(firstLine)}-${suffix}.md`);
+            suffix += 1;
+        }
+        await fs.writeFile(targetPath, `${content.trim()}\n`, "utf8");
+        return {
+            id: path.basename(targetPath),
+            success: true,
+        };
+    }
+}
+class UmbrellaContextSwarmProvider {
+    id = "umbrella-context";
+    label = "Umbrella Context";
+    type = "umbrella-context";
+    writable = true;
+    async healthCheck() {
+        const config = configManager.config;
+        return {
+            available: Boolean(config),
+            detail: config
+                ? `${config.companyName} / ${config.projectName} via ${config.serverUrl}`
+                : "Run umbrella-context setup first",
+            writable: true,
+        };
+    }
+    async query(query, opts) {
+        const config = configManager.config;
+        if (!config)
+            return [];
+        await ensureRepoContext(config);
+        const localEntries = summarizeLocalMemoryMatches([...(await getPendingMemories()), ...(await getPulledMemories())], query);
+        const localHits = localEntries.map((entry, index) => ({
+            content: excerptAroundQuery(entry.content, query),
+            id: `local:${entry.id}:${index}`,
+            matchType: "keyword",
+            provider: this.id,
+            providerLabel: this.label,
+            providerType: this.type,
+            score: 0.86 - index * 0.03,
+            source: entry.source ?? ".um",
+        }));
+        let remoteHits = [];
+        try {
+            const response = await fetch(`${config.serverUrl}/api/memories/search?query=${encodeURIComponent(query)}`, {
+                headers: { Authorization: `Bearer ${config.apiKey}` },
+            });
+            if (response.ok) {
+                const data = await response.json();
+                remoteHits = (data.results ?? []).map((entry, index) => ({
+                    content: excerptAroundQuery(String(entry.content ?? ""), query),
+                    id: `remote:${String(entry.id ?? index)}`,
+                    matchType: "keyword",
+                    provider: this.id,
+                    providerLabel: this.label,
+                    providerType: this.type,
+                    score: typeof entry.score === "number" ? entry.score : 0.8 - index * 0.03,
+                    source: String(entry.systemType ?? "shared-memory"),
+                }));
+            }
+        }
+        catch {
+            // Keep local results even if the server fetch fails.
+        }
+        return dedupeSwarmHits([...localHits, ...remoteHits]).slice(0, opts?.maxResults ?? DEFAULT_MAX_RESULTS);
+    }
+    async store(content) {
+        const entry = await addPendingMemory({
+            accessLevel: "space",
+            category: null,
+            content,
+            keywords: [],
+            source: "swarm",
+            systemType: "system1_knowledge",
+            tags: ["swarm"],
+        });
+        return { id: entry.id, success: true };
+    }
+}
+class UmbrellaSourceSwarmProvider {
+    alias;
+    sourceRoot;
+    id;
+    label;
+    type = "umbrella-source";
+    writable = false;
+    constructor(alias, sourceRoot) {
+        this.alias = alias;
+        this.sourceRoot = sourceRoot;
+        this.id = `source:${alias}`;
+        this.label = `Source: ${alias}`;
+    }
+    async healthCheck() {
+        const exists = await fileExists(path.join(this.sourceRoot, ".um", "context.json"));
+        return {
+            available: exists,
+            detail: exists ? this.sourceRoot : "Source repo is missing .um/context.json",
+            writable: false,
+        };
+    }
+    async query(query, opts) {
+        const sourcePending = summarizeLocalMemoryMatches(await getPendingMemories(this.sourceRoot), query);
+        const sourcePulled = summarizeLocalMemoryMatches(await getPulledMemories(this.sourceRoot), query);
+        return dedupeSwarmHits([...sourcePending, ...sourcePulled].map((entry, index) => ({
+            content: excerptAroundQuery(entry.content, query),
+            id: `${this.id}:${entry.id}:${index}`,
+            matchType: "keyword",
+            provider: this.id,
+            providerLabel: this.label,
+            providerType: this.type,
+            score: 0.82 - index * 0.03,
+            source: `${this.alias}:${entry.source ?? ".um"}`,
+        }))).slice(0, opts?.maxResults ?? DEFAULT_MAX_RESULTS);
+    }
+}
+async function buildSwarmProviders(config) {
+    const providers = [];
+    providers.push(new UmbrellaContextSwarmProvider());
+    const sources = await listKnowledgeSources();
+    for (const source of sources) {
+        providers.push(new UmbrellaSourceSwarmProvider(source.alias, source.projectRoot));
+    }
+    if (config.providers.obsidian?.enabled) {
+        providers.push(new MarkdownSwarmProvider("obsidian", config.providers.obsidian.vaultPath, "Obsidian vault", {
+            ignoreNames: OBSIDIAN_IGNORE_NAMES,
+            providerId: "obsidian",
+            writable: !config.providers.obsidian.readOnly,
+        }));
+    }
+    if (config.providers.localMarkdown?.enabled) {
+        for (const folder of config.providers.localMarkdown.folders) {
+            providers.push(new MarkdownSwarmProvider("local-markdown", folder.path, folder.name, {
+                followWikilinks: folder.followWikilinks,
+                providerId: `local-markdown:${folder.id}`,
+                writable: !folder.readOnly,
+            }));
+        }
+    }
+    if (config.providers.gbrain?.enabled) {
+        providers.push(new MarkdownSwarmProvider("gbrain", config.providers.gbrain.notesPath, "GBrain", {
+            providerId: "gbrain",
+            writable: !config.providers.gbrain.readOnly,
+        }));
+    }
+    if (config.providers.memoryWiki?.enabled) {
+        providers.push(new MarkdownSwarmProvider("memory-wiki", config.providers.memoryWiki.wikiPath, "Memory Wiki", {
+            providerId: "memory-wiki",
+            writable: !config.providers.memoryWiki.readOnly,
+        }));
+    }
+    return providers;
+}
+function chooseWriteProvider(content, providers, requestedProvider) {
+    if (requestedProvider) {
+        const exact = providers.find((provider) => provider.id === requestedProvider ||
+            provider.label.toLowerCase() === requestedProvider.toLowerCase());
+        if (!exact) {
+            throw new Error(`Swarm provider "${requestedProvider}" was not found.`);
+        }
+        if (!exact.writable) {
+            throw new Error(`Swarm provider "${exact.label}" is read-only.`);
+        }
+        return { fallback: false, provider: exact };
+    }
+    const prefersMarkdown = /[#*\-\[\]]/.test(content) || /\n/.test(content);
+    const writableExternal = providers.filter((provider) => provider.id !== "umbrella-context" && provider.writable);
+    if (prefersMarkdown && writableExternal.length > 0) {
+        return { fallback: false, provider: writableExternal[0] };
+    }
+    if (writableExternal.length > 0) {
+        return { fallback: false, provider: writableExternal[0] };
+    }
+    const umbrella = providers.find((provider) => provider.id === "umbrella-context");
+    if (!umbrella) {
+        throw new Error("Swarm has no writable provider available.");
+    }
+    return { fallback: true, provider: umbrella };
+}
+function sortSwarmHits(hits) {
+    return dedupeSwarmHits(hits).sort((a, b) => b.score - a.score).slice(0, 50);
+}
+function buildSwarmExplainLines(result) {
+    const lines = [];
+    for (const [providerId, meta] of Object.entries(result.meta.providers)) {
+        const selected = meta.selected ? "selected" : "skipped";
+        const enrichment = meta.enrichedBy ? `; enriched by ${meta.enrichedBy}` : "";
+        lines.push(`${providerId}: ${selected}; healthy=${meta.healthy ? "yes" : "no"}; results=${meta.resultCount}; latency=${meta.latencyMs}ms${enrichment}`);
+    }
+    return lines;
+}
+export function formatSwarmQueryText(result, options) {
+    const lines = [
+        `Swarm query: "${result.query}"`,
+        `Providers queried: ${result.meta.providerCount} | Latency: ${result.meta.totalLatencyMs}ms${result.cached ? " | cached" : ""}`,
+        "",
+    ];
+    if (options?.explain) {
+        lines.push("Explain:");
+        lines.push(...buildSwarmExplainLines(result).map((line) => `  - ${line}`));
+        if (result.meta.enrichmentEdges.length > 0) {
+            lines.push("  - enrichment: " + result.meta.enrichmentEdges.map((edge) => `${edge.from} -> ${edge.to}`).join(", "));
+        }
+        lines.push("");
+    }
+    if (result.results.length === 0) {
+        lines.push("No swarm results found.");
+        lines.push('Try `umbrella-context swarm status` to verify which knowledge sources are healthy.');
+        return lines.join("\n");
+    }
+    result.results.forEach((hit, index) => {
+        lines.push(`${index + 1}. [${hit.providerLabel}] ${hit.source} (${hit.matchType}, score ${hit.score.toFixed(3)})`);
+        lines.push(`   ${hit.content}`);
+        lines.push("");
+    });
+    return lines.join("\n").trimEnd();
+}
+export async function getSwarmStatusSummary(cwd = process.cwd()) {
+    const configPath = await getSwarmConfigPath(cwd);
+    const { config } = await loadEffectiveSwarmConfig(cwd);
+    if (!config) {
+        return {
+            configPath,
+            configured: false,
+            healthyProviders: 0,
+            providerCount: 0,
+            writableProviders: 0,
+        };
+    }
+    const providers = await buildSwarmProviders(config);
+    const checks = await Promise.all(providers.map((provider) => provider.healthCheck()));
+    return {
+        configPath,
+        configured: true,
+        healthyProviders: checks.filter((check) => check.available).length,
+        providerCount: providers.length,
+        writableProviders: checks.filter((check) => check.available && check.writable).length,
+    };
+}
+export async function getSwarmStatus(cwd = process.cwd()) {
+    const { config, implicit } = await loadEffectiveSwarmConfig(cwd);
+    if (!config) {
+        return {
+            configured: false,
+            configPath: await getSwarmConfigPath(cwd),
+            enrichmentEdges: [],
+            providers: [],
+            suggestions: [
+                'Run `umbrella-context swarm onboard` to choose which knowledge tools this repo should search together.',
+            ],
+        };
+    }
+    const providers = await buildSwarmProviders(config);
+    const providerStatuses = await Promise.all(providers.map(async (provider) => {
+        const health = await provider.healthCheck();
+        return {
+            id: provider.id,
+            label: provider.label,
+            type: provider.type,
+            available: health.available,
+            detail: health.detail,
+            writable: health.writable,
+        };
+    }));
+    const suggestions = [];
+    if (!providerStatuses.some((provider) => provider.id !== "umbrella-context" && provider.available)) {
+        suggestions.push("Add at least one extra note provider so swarm can search beyond this repo's saved Context.");
+    }
+    if (implicit) {
+        suggestions.push("Swarm is using a basic auto-created config because this repo already has linked knowledge sources. Run `umbrella-context swarm onboard` if you want to add Obsidian, markdown folders, or enrichment rules.");
+    }
+    if (providerStatuses.some((provider) => !provider.available)) {
+        suggestions.push("One or more configured paths do not exist yet. Update the path or re-run swarm onboard.");
+    }
+    return {
+        configured: true,
+        configPath: await getSwarmConfigPath(cwd),
+        enrichmentEdges: config.enrichment.edges,
+        providers: providerStatuses,
+        suggestions,
+    };
+}
+export async function executeSwarmQuery(query, opts = {}, cwd = process.cwd()) {
+    const { config } = await loadEffectiveSwarmConfig(cwd);
+    if (!config) {
+        throw new Error('Swarm is not configured yet. Run "umbrella-context swarm onboard" first.');
+    }
+    const providers = await buildSwarmProviders(config);
+    const selectedProviders = opts.provider
+        ? providers.filter((provider) => provider.id === opts.provider ||
+            provider.label.toLowerCase() === opts.provider?.toLowerCase())
+        : providers;
+    if (selectedProviders.length === 0) {
+        throw new Error(`No swarm provider matched "${opts.provider}".`);
+    }
+    const maxResults = opts.maxResults ?? config.routing.defaultMaxResults;
+    const localFingerprint = await buildLocalQueryFingerprint(cwd);
+    const cacheKey = buildSwarmCacheKey(query, config, localFingerprint);
+    const cached = await getCachedSwarmResult(cacheKey, config.routing.cacheTtlMs, cwd);
+    if (cached) {
+        return { ...cached, cached: true };
+    }
+    const startedAt = Date.now();
+    const meta = {};
+    const hits = [];
+    const providersInOrder = selectedProviders.slice().sort((left, right) => {
+        if (left.id === "umbrella-context")
+            return -1;
+        if (right.id === "umbrella-context")
+            return 1;
+        return left.label.localeCompare(right.label);
+    });
+    const enrichmentEdges = config.enrichment.enabled ? config.enrichment.edges : [];
+    const topUmbrellaHints = [];
+    for (const provider of providersInOrder) {
+        const health = await provider.healthCheck();
+        if (!health.available) {
+            meta[provider.id] = {
+                available: false,
+                detail: health.detail,
+                healthy: false,
+                latencyMs: 0,
+                resultCount: 0,
+                selected: false,
+                writable: health.writable,
+            };
+            continue;
+        }
+        const providerStartedAt = Date.now();
+        const incomingEdge = enrichmentEdges.find((edge) => edge.to === provider.id);
+        const queryText = incomingEdge && topUmbrellaHints.length > 0
+            ? `${query}\n\nContext hints:\n${topUmbrellaHints.join("\n")}`
+            : query;
+        const providerHits = await provider.query(queryText, { maxResults });
+        const latencyMs = Date.now() - providerStartedAt;
+        if (provider.id === "umbrella-context") {
+            topUmbrellaHints.push(...providerHits
+                .slice(0, 3)
+                .map((hit) => hit.content)
+                .filter(Boolean));
+        }
+        hits.push(...providerHits);
+        meta[provider.id] = {
+            available: true,
+            detail: health.detail,
+            enrichedBy: incomingEdge?.from,
+            enrichmentHints: incomingEdge && topUmbrellaHints.length > 0 ? topUmbrellaHints.slice(0, 3) : undefined,
+            healthy: true,
+            latencyMs,
+            resultCount: providerHits.length,
+            selected: true,
+            writable: health.writable,
+        };
+    }
+    const result = {
+        cached: false,
+        cacheTtlMs: config.routing.cacheTtlMs,
+        meta: {
+            enrichmentEdges,
+            providerCount: Object.values(meta).filter((entry) => entry.selected).length,
+            providers: meta,
+            totalLatencyMs: Date.now() - startedAt,
+        },
+        query,
+        results: sortSwarmHits(hits).slice(0, maxResults),
+    };
+    await storeCachedSwarmResult(cacheKey, query, result, cwd);
+    return result;
+}
+export async function executeSwarmCurate(content, opts = {}, cwd = process.cwd()) {
+    const { config } = await loadEffectiveSwarmConfig(cwd);
+    if (!config) {
+        throw new Error('Swarm is not configured yet. Run "umbrella-context swarm onboard" first.');
+    }
+    const providers = await buildSwarmProviders(config);
+    const { fallback, provider } = chooseWriteProvider(content, providers, opts.provider);
+    const result = await provider.store?.(content);
+    if (!result?.success) {
+        throw new Error(`Swarm could not store content in ${provider.label}.`);
+    }
+    return {
+        fallback,
+        id: result.id,
+        provider: provider.label,
+        success: true,
+        targetType: provider.type,
+    };
+}
+async function promptForPath(message) {
+    const answer = await prompts({
+        type: "text",
+        name: "value",
+        message,
+        validate: (value) => (value.trim() ? true : "Please type a path."),
+    });
+    return String(answer.value ?? "").trim();
+}
+export async function runSwarmOnboardWizard(cwd = process.cwd()) {
+    const defaults = buildDefaultSwarmConfig();
+    const selected = await prompts({
+        type: "multiselect",
+        name: "providers",
+        message: "Which extra knowledge tools should this repo's swarm search?",
+        instructions: false,
+        choices: [
+            {
+                title: "Umbrella Context",
+                description: "Always on. Searches this repo's saved Context and shared server memory.",
+                disabled: true,
+                selected: true,
+                value: "umbrella-context",
+            },
+            {
+                title: "Obsidian vault",
+                description: "Search a local Obsidian vault as read-only notes.",
+                value: "obsidian",
+            },
+            {
+                title: "Local markdown folder",
+                description: "Search one or more plain markdown folders on this computer.",
+                value: "local-markdown",
+            },
+            {
+                title: "GBrain-compatible notes folder",
+                description: "Treat a GBrain notes directory as another searchable markdown source.",
+                value: "gbrain",
+            },
+            {
+                title: "Memory Wiki folder",
+                description: "Search and optionally write to a Memory Wiki-style markdown folder.",
+                value: "memory-wiki",
+            },
+        ],
+    });
+    const selectedProviders = new Set(selected.providers ?? []);
+    const nextConfig = {
+        ...defaults,
+        enrichment: { enabled: false, edges: [] },
+        providers: { ...defaults.providers },
+    };
+    if (selectedProviders.has("obsidian")) {
+        const vaultPath = await promptForPath("Path to your Obsidian vault");
+        nextConfig.providers.obsidian = {
+            enabled: true,
+            readOnly: true,
+            vaultPath,
+        };
+    }
+    if (selectedProviders.has("local-markdown")) {
+        const folders = [];
+        let addAnother = true;
+        while (addAnother) {
+            const folderPath = await promptForPath("Path to a markdown folder");
+            const folderNameAnswer = await prompts({
+                type: "text",
+                name: "value",
+                message: "Short name for this folder inside swarm",
+                initial: path.basename(folderPath),
+            });
+            const readOnlyAnswer = await prompts({
+                type: "confirm",
+                name: "value",
+                message: "Should this folder be read-only?",
+                initial: true,
+            });
+            folders.push({
+                followWikilinks: true,
+                id: slugifyFileName(folderNameAnswer.value || path.basename(folderPath)),
+                name: String(folderNameAnswer.value || path.basename(folderPath)),
+                path: folderPath,
+                readOnly: Boolean(readOnlyAnswer.value),
+            });
+            const anotherAnswer = await prompts({
+                type: "confirm",
+                name: "value",
+                message: "Add another markdown folder?",
+                initial: false,
+            });
+            addAnother = Boolean(anotherAnswer.value);
+        }
+        nextConfig.providers.localMarkdown = {
+            enabled: folders.length > 0,
+            folders,
+        };
+    }
+    if (selectedProviders.has("gbrain")) {
+        const notesPath = await promptForPath("Path to the GBrain notes or markdown folder");
+        nextConfig.providers.gbrain = {
+            enabled: true,
+            notesPath,
+            readOnly: false,
+        };
+    }
+    if (selectedProviders.has("memory-wiki")) {
+        const wikiPath = await promptForPath("Path to the Memory Wiki folder");
+        const readOnlyAnswer = await prompts({
+            type: "confirm",
+            name: "value",
+            message: "Should Memory Wiki stay read-only?",
+            initial: false,
+        });
+        nextConfig.providers.memoryWiki = {
+            enabled: true,
+            readOnly: Boolean(readOnlyAnswer.value),
+            wikiPath,
+        };
+    }
+    const enrichmentAnswer = await prompts({
+        type: "confirm",
+        name: "value",
+        message: "Should Umbrella Context feed its top matches into the other providers first?",
+        initial: true,
+    });
+    if (enrichmentAnswer.value) {
+        nextConfig.enrichment = {
+            enabled: true,
+            edges: [
+                ...(nextConfig.providers.obsidian ? [{ from: "umbrella-context", to: "obsidian" }] : []),
+                ...(nextConfig.providers.localMarkdown?.folders ?? []).map((folder) => ({
+                    from: "umbrella-context",
+                    to: `local-markdown:${folder.id}`,
+                })),
+                ...(nextConfig.providers.gbrain ? [{ from: "umbrella-context", to: "gbrain" }] : []),
+                ...(nextConfig.providers.memoryWiki ? [{ from: "umbrella-context", to: "memory-wiki" }] : []),
+            ],
+        };
+    }
+    await saveSwarmConfig(nextConfig, cwd);
+    return {
+        config: nextConfig,
+        configPath: await getSwarmConfigPath(cwd),
+    };
+}