umbrella-context 0.1.37 → 0.1.39

package/dist/commands/search.js

@@ -1,15 +1,794 @@
 import chalk from "chalk";
 import { configManager } from "../config.js";
-import { addTaskReasoningContent, addTaskToolCall, appendTaskStreamingContent, completeTask, createTask, getPendingMemories, getPulledMemories, patchTaskLifecycle, recordSessionEvent, recordSessionQuery, setSessionPanel, summarizeLocalMemoryMatches, } from "../repo-state.js";
-export async function searchCommandAction(query) {
+import { getProviderReadinessSummary } from "./providers.js";
+import { addTaskReasoningContent, addTaskToolCall, appendTaskStreamingContent, buildLocalQueryFingerprint, completeTask, createTask, getQueryCacheEntry, getPendingMemories, getPulledMemories, markQueryCacheHit, patchTaskLifecycle, removeTask, recordSessionEvent, recordSessionQuery, setSessionPanel, storeQueryCacheEntry, summarizeLocalMemoryMatches, } from "../repo-state.js";
+const DIRECT_RESPONSE_SCORE_THRESHOLD = 0.85;
+const DIRECT_RESPONSE_HIGH_CONFIDENCE_THRESHOLD = 0.93;
+const DIRECT_RESPONSE_MIN_GAP = 0.08;
+const SYNTHESIS_CONTEXT_LIMIT = 6;
+function printJson(payload) {
+    console.log(JSON.stringify(payload, null, 2));
+}
+function trimMatchingQuotes(value) {
+    const trimmed = value.trim();
+    if ((trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+        (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+        return trimmed.slice(1, -1).trim();
+    }
+    return trimmed;
+}
+function normalizeQuery(query) {
+    return trimMatchingQuotes(query).toLowerCase();
+}
+function stripQuestionPunctuation(query) {
+    return trimMatchingQuotes(query).replace(/[?!.]+$/g, "");
+}
+function extractTopicHint(query) {
+    const cleaned = stripQuestionPunctuation(query).trim();
+    if (!cleaned)
+        return "the topic";
+    const questionPrefixes = [
+        /^how is /i,
+        /^how are /i,
+        /^how does /i,
+        /^how do /i,
+        /^what is /i,
+        /^what are /i,
+        /^where is /i,
+        /^where are /i,
+        /^why is /i,
+        /^why are /i,
+    ];
+    for (const prefix of questionPrefixes) {
+        if (prefix.test(cleaned)) {
+            return cleaned.replace(prefix, "").trim() || "the topic";
+        }
+    }
+    return cleaned;
+}
+function isVagueQuery(query) {
+    const normalized = normalizeQuery(query);
+    if (!normalized)
+        return true;
+    const words = normalized.split(/\s+/).filter(Boolean);
+    if (words.length <= 1)
+        return true;
+    const vaguePatterns = new Set([
+        "auth",
+        "authentication",
+        "rate limiting",
+        "rate limit",
+        "rate limits",
+        "show me code",
+        "bug",
+        "error",
+        "setup",
+    ]);
+    return vaguePatterns.has(normalized);
+}
+function extractMeaningfulQueryWords(query) {
+    return normalizeQuery(query)
+        .replace(/[?!.:,;()[\]{}]/g, " ")
+        .split(/\s+/)
+        .map((word) => word.trim())
+        .filter(Boolean)
+        .filter((word) => !new Set([
+        "a",
+        "an",
+        "and",
+        "are",
+        "do",
+        "does",
+        "how",
+        "implemented",
+        "is",
+        "the",
+        "what",
+        "where",
+        "why",
+    ]).has(word));
+}
+function expandQueryWord(word) {
+    const synonymMap = {
+        auth: ["authentication", "signin", "sign-in", "jwt", "token", "cookie", "cookies"],
+        authentication: ["auth", "signin", "sign-in", "jwt", "token", "cookie", "cookies"],
+        rate: ["throttle", "limit", "limits", "limiting"],
+        limits: ["limit", "rate", "throttle", "limiting"],
+    };
+    return [word, ...(synonymMap[word] ?? [])];
+}
+function buildQueryCoverage(content, query) {
+    const queryWords = extractMeaningfulQueryWords(query);
+    if (queryWords.length === 0) {
+        return { ratio: 0, matchedWords: [], missingWords: [] };
+    }
+    const haystack = normalizeComparableContent(content);
+    const matchedWords = queryWords.filter((word) => {
+        const variants = expandQueryWord(word);
+        return variants.some((variant) => haystack.includes(normalizeComparableContent(variant)));
+    });
+    const uniqueMatchedWords = [...new Set(matchedWords)];
+    const missingWords = queryWords.filter((word) => !uniqueMatchedWords.includes(word));
+    return {
+        ratio: uniqueMatchedWords.length / queryWords.length,
+        matchedWords: uniqueMatchedWords,
+        missingWords,
+    };
+}
+function scoreLocalMatch(entry, query) {
+    const normalizedQuery = normalizeQuery(query);
+    const haystack = [entry.content, ...entry.tags, ...(entry.keywords ?? [])].join(" ").toLowerCase();
+    let score = 0;
+    if (haystack.includes(normalizedQuery))
+        score += 4;
+    const queryWords = extractMeaningfulQueryWords(query);
+    for (const word of queryWords) {
+        const variants = expandQueryWord(word);
+        if (variants.some((variant) => haystack.includes(variant))) {
+            score += 3;
+        }
+    }
+    return score;
+}
+function rankLocalMatches(entries, query) {
+    return [...entries]
+        .map((entry) => ({ entry, score: scoreLocalMatch(entry, query) }))
+        .sort((a, b) => b.score - a.score || b.entry.createdAt.localeCompare(a.entry.createdAt))
+        .map(({ entry, score }) => ({ entry, score }));
+}
+function buildHelpfulSuggestions(query) {
+    const normalized = normalizeQuery(query);
+    if (!normalized) {
+        return [
+            'Try a full question like "How is authentication implemented?"',
+            'Try something specific like "What rate limits do we enforce and where?"',
+        ];
+    }
+    const words = normalized.split(/\s+/).filter(Boolean);
+    const alreadySpecific = words.length >= 4 && /[?]/.test(query);
+    if (alreadySpecific) {
+        return [
+            "Try pulling the latest shared context with `umbrella-context pull` and then query again.",
+            "If the answer only exists in your working tree, save it locally with `umbrella-context curate \"...\"` and then run `umbrella-context push`.",
+            "Try a nearby question that names a file, module, or subsystem you expect to contain the answer.",
+        ];
+    }
+    if (normalized === "rate limits" || normalized === "rate limit" || normalized === "rate limiting") {
+        return [
+            'Try a fuller question, for example: "What are the API rate limits and where are they enforced?"',
+            'Try something implementation-focused, for example: "How is rate limiting implemented?"',
+            'If you already learned the answer locally, save it with `umbrella-context curate "..."` and then run `umbrella-context push`.',
+        ];
+    }
+    if (normalized === "auth" || normalized === "authentication") {
+        return [
+            'Try a fuller question, for example: "How is authentication implemented?"',
+            'Try a configuration question, for example: "Where is authentication configured and enforced?"',
+            'If you already learned the answer locally, save it with `umbrella-context curate "..."` and then run `umbrella-context push`.',
+        ];
+    }
+    const topic = extractTopicHint(query);
+    return [
+        `Try a fuller question, for example: "How is ${topic} implemented?"`,
+        `Try adding what you need, for example: "Where is ${topic} configured and enforced?"`,
+        'If you already learned the answer locally, save it with `umbrella-context curate "..."` and then run `umbrella-context push`.',
+    ];
+}
+function normalizeLocalScore(score, query) {
+    const wordCount = normalizeQuery(query).split(/\s+/).filter(Boolean).length || 1;
+    const maxReasonableScore = Math.max(5, wordCount * 4);
+    return Math.min(score / maxReasonableScore, 1);
+}
+function normalizeServerScore(rawScore) {
+    if (typeof rawScore !== "number" || Number.isNaN(rawScore))
+        return 0;
+    return rawScore <= 1 ? rawScore : Math.min(rawScore / 10, 1);
+}
+function truncateSentence(value, maxLength = 260) {
+    const cleaned = value.replace(/\s+/g, " ").trim();
+    if (cleaned.length <= maxLength)
+        return cleaned;
+    return `${cleaned.slice(0, maxLength).trim()}...`;
+}
+function compactTimestamp(value) {
+    return new Date(value).toLocaleDateString();
+}
+function normalizeComparableContent(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^\w\s]/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+function areNearDuplicateCandidates(a, b) {
+    const left = normalizeComparableContent(a.content);
+    const right = normalizeComparableContent(b.content);
+    if (!left || !right)
+        return false;
+    return left.includes(right) || right.includes(left);
+}
+function shareLocalSignals(left, right) {
+    const leftSignals = new Set([...(left.tags ?? []), ...(left.keywords ?? [])]
+        .map((value) => value.trim().toLowerCase())
+        .filter(Boolean));
+    const rightSignals = new Set([...(right.tags ?? []), ...(right.keywords ?? [])]
+        .map((value) => value.trim().toLowerCase())
+        .filter(Boolean));
+    let overlap = 0;
+    for (const signal of leftSignals) {
+        if (rightSignals.has(signal)) {
+            overlap += 1;
+        }
+    }
+    return overlap >= 1;
+}
+function buildDirectCandidates(query, localMatches, serverMatches) {
+    const localCandidates = localMatches.map(({ entry, score }) => ({
+        content: entry.content,
+        label: "local memory",
+        score: normalizeLocalScore(score, query),
+        source: entry.source ?? "local",
+        createdAt: entry.createdAt,
+    }));
+    const sharedCandidates = serverMatches.map((entry) => ({
+        content: typeof entry.content === "string" ? entry.content : "",
+        label: typeof entry.systemType === "string" ? entry.systemType : "shared memory",
+        score: normalizeServerScore(entry.score),
+        source: typeof entry.source === "string" ? entry.source : "server",
+        createdAt: typeof entry.createdAt === "string" ? entry.createdAt : new Date().toISOString(),
+    }));
+    return [...localCandidates, ...sharedCandidates]
+        .filter((entry) => entry.content.trim())
+        .sort((a, b) => b.score - a.score || b.createdAt.localeCompare(a.createdAt));
+}
+function hasStrongLocalDirectAnswer(localMatches) {
+    if (localMatches.length === 0)
+        return false;
+    const top = localMatches[0];
+    const second = localMatches[1];
+    if (top.score >= 3 && !second)
+        return true;
+    if (top.score >= 3 && second && areNearDuplicateCandidates({
+        content: top.entry.content,
+        label: "local memory",
+        score: top.score,
+        source: top.entry.source ?? "local",
+        createdAt: top.entry.createdAt,
+    }, {
+        content: second.entry.content,
+        label: "local memory",
+        score: second.score,
+        source: second.entry.source ?? "local",
+        createdAt: second.entry.createdAt,
+    })) {
+        return true;
+    }
+    if (top.score >= 3 && second && shareLocalSignals(top.entry, second.entry)) {
+        return true;
+    }
+    if (top.score >= 3 && second && top.score - second.score >= 1)
+        return true;
+    return false;
+}
+function buildDirectAnswer(query, localMatches, serverMatches) {
+    const candidates = buildDirectCandidates(query, localMatches, serverMatches);
+    if (candidates.length === 0)
+        return null;
+    const top = candidates[0];
+    const allowStrongLocalFallback = top.label === "local memory" && hasStrongLocalDirectAnswer(localMatches);
+    if (top.score < DIRECT_RESPONSE_SCORE_THRESHOLD && !allowStrongLocalFallback)
+        return null;
+    const second = candidates[1];
+    const dominant = allowStrongLocalFallback ||
+        !second ||
+        top.score >= DIRECT_RESPONSE_HIGH_CONFIDENCE_THRESHOLD ||
+        top.score - second.score >= DIRECT_RESPONSE_MIN_GAP ||
+        (areNearDuplicateCandidates(top, second) && top.content.length >= second.content.length);
+    if (!dominant)
+        return null;
+    const coverage = buildQueryCoverage(top.content, query);
+    const requiresBroaderCoverage = extractMeaningfulQueryWords(query).length >= 3;
+    const coverageThreshold = requiresBroaderCoverage ? 0.6 : 0.5;
+    if (coverage.ratio < coverageThreshold) {
+        return null;
+    }
+    return {
+        summary: `Based on the strongest saved context, here is the best direct answer for "${query}".`,
+        details: truncateSentence(top.content),
+        sources: [`${top.source} (${top.label})`],
+        confidence: top.score >= DIRECT_RESPONSE_HIGH_CONFIDENCE_THRESHOLD ? "high" : "medium",
+        gaps: top.score >= DIRECT_RESPONSE_HIGH_CONFIDENCE_THRESHOLD
+            ? "No major gaps were detected in the strongest saved context."
+            : "The saved context is good, but it may still be missing implementation details or edge cases.",
+    };
+}
+function buildSynthesisContext(localMatches, serverMatches) {
+    return [
+        ...localMatches.slice(0, 3).map((entry, index) => ({
+            index: index + 1,
+            source: `local:${entry.source ?? "cli"}:${compactTimestamp(entry.createdAt)}`,
+            content: entry.content,
+            tags: entry.tags ?? [],
+            keywords: entry.keywords ?? [],
+        })),
+        ...serverMatches.slice(0, 3).map((entry, index) => ({
+            index: localMatches.slice(0, 3).length + index + 1,
+            source: `shared:${typeof entry.source === "string" ? entry.source : "server"}:${typeof entry.createdAt === "string" ? compactTimestamp(entry.createdAt) : "unknown"}`,
+            content: typeof entry.content === "string" ? entry.content : "",
+            tags: Array.isArray(entry.tags) ? entry.tags : [],
+            keywords: Array.isArray(entry.keywords) ? entry.keywords : [],
+        })),
+    ]
+        .filter((entry) => entry.content.trim())
+        .slice(0, SYNTHESIS_CONTEXT_LIMIT);
+}
+function buildOpenAiStyleUrl(baseUrl, fallback) {
+    const trimmed = (baseUrl ?? fallback).replace(/\/+$/, "");
+    if (trimmed.endsWith("/v1")) {
+        return `${trimmed}/chat/completions`;
+    }
+    if (trimmed.endsWith("/chat/completions")) {
+        return trimmed;
+    }
+    return `${trimmed}/v1/chat/completions`;
+}
+function extractOpenAiStyleText(data) {
+    return (data?.choices?.[0]?.message?.content
+        ?? data?.choices?.[0]?.text
+        ?? null);
+}
+function extractAnthropicText(data) {
+    const blocks = Array.isArray(data?.content)
+        ? data.content
+        : [];
+    return blocks
+        .filter((block) => block?.type === "text" && typeof block?.text === "string")
+        .map((block) => block.text)
+        .join("\n")
+        .trim();
+}
+function extractGoogleText(data) {
+    const parts = data?.candidates?.[0]?.content?.parts;
+    if (!Array.isArray(parts))
+        return null;
+    return parts
+        .map((part) => (typeof part?.text === "string" ? part.text : ""))
+        .join("\n")
+        .trim();
+}
+function inferAnswerGaps(details, query, fallback) {
+    const normalized = details.toLowerCase();
+    if (normalized.includes("not enough") ||
+        normalized.includes("missing") ||
+        normalized.includes("unclear") ||
+        normalized.includes("incomplete") ||
+        normalized.includes("do not know") ||
+        normalized.includes("unknown")) {
+        return truncateSentence(details, 220);
+    }
+    const meaningfulWords = extractMeaningfulQueryWords(query);
+    if (meaningfulWords.length >= 4) {
+        return fallback;
+    }
+    return "No major gaps were detected in the saved context used for this answer.";
+}
+function parseStructuredProviderAnswer(rawText) {
+    const trimmed = rawText.trim();
+    if (!trimmed)
+        return null;
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (typeof parsed.summary !== "string" || typeof parsed.details !== "string") {
+            return null;
+        }
+        return {
+            summary: truncateSentence(parsed.summary.trim(), 240),
+            details: truncateSentence(parsed.details.trim(), 420),
+            sources: Array.isArray(parsed.sources)
+                ? parsed.sources.filter((entry) => typeof entry === "string" && entry.trim().length > 0)
+                : [],
+            gaps: typeof parsed.gaps === "string" && parsed.gaps.trim().length > 0
+                ? truncateSentence(parsed.gaps.trim(), 240)
+                : "No major gaps were detected in the saved context used for this answer.",
+        };
+    }
+    catch {
+        return null;
+    }
+}
+async function synthesizeAnswerFromProvider(query, localMatches, serverMatches) {
+    const config = configManager.config;
+    if (!config?.activeProvider || !config.activeModel)
+        return null;
+    const provider = configManager.providers.find((entry) => entry.id === config.activeProvider) ?? null;
+    if (!provider?.apiKey)
+        return null;
+    const contextEntries = buildSynthesisContext(localMatches, serverMatches);
+    if (contextEntries.length === 0)
+        return null;
+    const userPrompt = [
+        `Question: ${query}`,
+        "",
+        "Saved context:",
+        ...contextEntries.map((entry) => `[${entry.index}] ${entry.source}\nContent: ${entry.content}\nTags: ${entry.tags.join(", ") || "none"}\nKeywords: ${entry.keywords.join(", ") || "none"}`),
+        "",
+        "Answer using only the saved context above.",
+        "If the context is related but still incomplete, say exactly what is known and what is still missing.",
+        "Return only JSON with this exact shape:",
+        '{ "summary": "short answer", "details": "2 short paragraphs max", "sources": ["source label"], "gaps": "what is still missing" }',
+        "Do not add markdown fences or extra commentary.",
+    ].join("\n");
+    let responseText = null;
+    if (provider.kind === "anthropic") {
+        const res = await fetch(provider.baseUrl?.replace(/\/+$/, "") || "https://api.anthropic.com/v1/messages", {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                "x-api-key": provider.apiKey,
+                "anthropic-version": "2023-06-01",
+            },
+            body: JSON.stringify({
+                model: config.activeModel,
+                max_tokens: 220,
+                system: "You answer engineering questions using only the provided saved context. Be concise and do not invent facts.",
+                messages: [{ role: "user", content: userPrompt }],
+            }),
+        });
+        if (!res.ok)
+            return null;
+        responseText = extractAnthropicText(await res.json());
+    }
+    else if (provider.kind === "google") {
+        const model = encodeURIComponent(config.activeModel);
+        const res = await fetch(`https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent?key=${encodeURIComponent(provider.apiKey)}`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                contents: [{ role: "user", parts: [{ text: userPrompt }] }],
+                systemInstruction: {
+                    parts: [
+                        {
+                            text: "You answer engineering questions using only the provided saved context. Be concise and do not invent facts.",
+                        },
+                    ],
+                },
+                generationConfig: {
+                    temperature: 0.2,
+                    maxOutputTokens: 220,
+                },
+            }),
+        });
+        if (!res.ok)
+            return null;
+        responseText = extractGoogleText(await res.json());
+    }
+    else {
+        const endpoint = buildOpenAiStyleUrl(provider.baseUrl, provider.kind === "openrouter" ? "https://openrouter.ai/api" : "https://api.openai.com");
+        const headers = {
+            "content-type": "application/json",
+            authorization: `Bearer ${provider.apiKey}`,
+        };
+        if (provider.kind === "openrouter") {
+            headers["HTTP-Referer"] = "https://github.com/buildingwithai/Umbrella";
+            headers["X-Title"] = "Umbrella Context CLI";
+        }
+        const res = await fetch(endpoint, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({
+                model: config.activeModel,
+                temperature: 0.2,
+                max_tokens: 220,
+                messages: [
+                    {
+                        role: "system",
+                        content: "You answer engineering questions using only the provided saved context. Be concise and do not invent facts.",
+                    },
+                    {
+                        role: "user",
+                        content: userPrompt,
+                    },
+                ],
+            }),
+        });
+        if (!res.ok)
+            return null;
+        responseText = extractOpenAiStyleText(await res.json());
+    }
+    const responseTextValue = responseText ?? "";
+    const structured = parseStructuredProviderAnswer(responseTextValue);
+    const details = truncateSentence(responseTextValue, 400);
+    if (!structured && !details)
+        return null;
+    return {
+        summary: structured?.summary
+            ?? `This answer was synthesized from the strongest saved context for "${query}".`,
+        details: structured?.details ?? details,
+        sources: structured?.sources.length
+            ? structured.sources
+            : contextEntries.map((entry) => entry.source),
+        confidence: "medium",
+        gaps: structured?.gaps
+            ?? inferAnswerGaps(details, query, "The saved context is related, but it may still be missing exact implementation details or the final policy decision."),
+        provider: provider.name,
+        model: config.activeModel,
+    };
+}
+function printAnswerSections(answer, opts = {}) {
+    if (opts.heading) {
+        console.log(chalk.cyan(` ${opts.heading}:\n`));
+    }
+    console.log(chalk.cyan(" Summary:\n"));
+    console.log(`     ${answer.summary}`);
+    console.log("");
+    console.log(chalk.cyan(" Details:\n"));
+    console.log(`     ${answer.details}`);
+    console.log("");
+    console.log(chalk.cyan(" Sources:\n"));
+    if (answer.sources.length === 0) {
+        console.log("     None");
+    }
+    else {
+        answer.sources.forEach((source, index) => {
+            console.log(chalk.gray(`  ${index + 1}. ${source}`));
+        });
+    }
+    console.log("");
+    console.log(chalk.cyan(" Gaps:\n"));
+    console.log(`     ${answer.gaps ?? "No major gaps were detected in the saved context used for this answer."}`);
+    console.log("");
+    if (answer.provider || answer.model) {
+        console.log(chalk.gray(`     Confidence: ${answer.confidence}${answer.provider ? ` | Provider: ${answer.provider}` : ""}${answer.model ? ` | Model: ${answer.model}` : ""}`));
+        console.log("");
+        return;
+    }
+    console.log(chalk.gray(`     Confidence: ${answer.confidence}`));
+    console.log("");
+}
+function printMatchMeta(result) {
+    const meta = [];
+    if ("accessLevel" in result && result.accessLevel) {
+        meta.push(`Access: ${result.accessLevel}`);
+    }
+    if ("category" in result && result.category) {
+        meta.push(`Category: ${result.category}`);
+    }
+    if ("tags" in result && Array.isArray(result.tags) && result.tags.length > 0) {
+        meta.push(`Tags: ${result.tags.slice(0, 4).join(", ")}`);
+    }
+    if ("keywords" in result && Array.isArray(result.keywords) && result.keywords.length > 0) {
+        meta.push(`Keywords: ${result.keywords.slice(0, 4).join(", ")}`);
+    }
+    return meta;
+}
+function printSupportingMatches(localMatches, serverMatches) {
+    const support = [
+        ...localMatches.slice(0, 2).map((result) => ({
+            kind: "local",
+            content: result.content,
+            source: `Saved ${compactTimestamp(result.createdAt)}`,
+            meta: printMatchMeta(result),
+        })),
+        ...serverMatches.slice(0, 2).map((result) => ({
+            kind: typeof result.systemType === "string" ? result.systemType : "shared",
+            content: typeof result.content === "string" ? result.content : "",
+            source: typeof result.createdAt === "string"
+                ? `Shared ${compactTimestamp(result.createdAt)}`
+                : "Shared memory",
+            meta: printMatchMeta(result),
+        })),
+    ].filter((result) => result.content.trim());
+    if (support.length === 0)
+        return;
+    console.log(chalk.cyan(" Supporting context:\n"));
+    support.forEach((result, index) => {
+        console.log(chalk.cyan(`  ${index + 1}. [${result.kind}] ${truncateSentence(result.content, 140)}`));
+        console.log(chalk.gray(`     ${result.source}`));
+        if (result.meta.length > 0) {
+            console.log(chalk.gray(`     ${result.meta.join(" | ")}`));
+        }
+        console.log("");
+    });
+}
+function printPartialMatches(localMatches, serverMatches) {
+    const support = [
+        ...localMatches.slice(0, 3).map((result) => ({
+            kind: "local",
+            content: result.content,
+            source: `Saved ${compactTimestamp(result.createdAt)}`,
+            meta: printMatchMeta(result),
+        })),
+        ...serverMatches.slice(0, 3).map((result) => ({
+            kind: typeof result.systemType === "string" ? result.systemType : "shared",
+            content: typeof result.content === "string" ? result.content : "",
+            source: typeof result.createdAt === "string"
+                ? `Shared ${compactTimestamp(result.createdAt)}`
+                : "Shared memory",
+            meta: printMatchMeta(result),
+        })),
+    ].filter((result) => result.content.trim());
+    if (support.length === 0)
+        return;
+    console.log(chalk.cyan(" Top context:\n"));
+    support.forEach((result, index) => {
+        console.log(chalk.cyan(`  ${index + 1}. [${result.kind}] ${truncateSentence(result.content, 140)}`));
+        console.log(chalk.gray(`     ${result.source}`));
+        if (result.meta.length > 0) {
+            console.log(chalk.gray(`     ${result.meta.join(" | ")}`));
+        }
+        console.log("");
+    });
+}
+function printTextResults(payload, cached = false) {
+    if (payload.total === 0) {
+        console.log(chalk.bold(`\n Context answer for ${payload.companyName} / ${payload.spaceName}\n`));
+        console.log(chalk.cyan(" Summary:\n"));
+        console.log(`     ${cached ? "No cached context matched this question yet." : "No matching context was found for this question yet."}`);
+        console.log("");
+        console.log(chalk.cyan(" Details:\n"));
+        console.log(`     I checked both your local .um workspace and the shared server memory for "${payload.query}", but neither one had a strong saved answer.`);
+        console.log("");
+        console.log(chalk.cyan(" Sources:\n"));
+        console.log("     None");
+        console.log("");
+        console.log(chalk.cyan(" Next step:\n"));
+        payload.suggestions.forEach((suggestion, index) => {
+            console.log(chalk.gray(`  ${index + 1}. ${suggestion}`));
+        });
+        console.log("");
+        return;
+    }
+    const cacheBanner = cached ? chalk.gray(" (cached)") : "";
+    console.log(chalk.bold(`\n Context answer for ${payload.companyName} / ${payload.spaceName}${cacheBanner}\n`));
+    if (payload.directAnswer) {
+        printAnswerSections(payload.directAnswer, { heading: "Direct answer" });
+        printSupportingMatches(payload.localMatches, payload.serverMatches);
+        return;
+    }
+    if (payload.synthesizedAnswer) {
+        printAnswerSections(payload.synthesizedAnswer, { heading: "Synthesized answer" });
+        printPartialMatches(payload.localMatches, payload.serverMatches);
+        return;
+    }
+    console.log(chalk.cyan(" Summary:\n"));
+    console.log(`     I found ${payload.total} related context entr${payload.total === 1 ? "y" : "ies"}, but there is not one strong enough match to give a single direct answer yet.`);
+    console.log("");
+    console.log(chalk.cyan(" Details:\n"));
+    console.log(`     There ${payload.total === 1 ? "is" : "are"} ${payload.localMatches.length} local and ${payload.serverMatches.length} shared match${payload.total === 1 ? "" : "es"} for "${payload.query}". The best next move is to review the strongest saved context below or ask a more specific question.`);
+    console.log("");
+    printPartialMatches(payload.localMatches, payload.serverMatches);
+    console.log(chalk.cyan(" Sources:\n"));
+    console.log(`     Local .um: ${payload.localMatches.length} | Shared server memory: ${payload.serverMatches.length}`);
+    console.log("");
+    console.log(chalk.cyan(" Next step:\n"));
+    buildHelpfulSuggestions(payload.query).forEach((suggestion, index) => {
+        console.log(chalk.gray(`  ${index + 1}. ${suggestion}`));
+    });
+    if (payload.providerRequiredForSynthesis) {
+        console.log(chalk.yellow(`\n Provider note: ${payload.providerReady
+            ? "A provider is connected, so this question is ready for a richer synthesized answer in a later pass."
+            : 'Connect a provider with "umbrella-context providers setup" if you want the CLI to turn these partial matches into one cleaner answer.'}`));
+    }
+    console.log("");
+}
+function printSearchPayload(format, payload, cached = false) {
+    if (format === "json") {
+        printJson({
+            ok: true,
+            action: "query",
+            cached,
+            ...payload,
+        });
+        return;
+    }
+    printTextResults(payload, cached);
+}
+async function enrichCachedPayload(query, payload, providerReady) {
+    if (payload.total === 0) {
+        return payload;
+    }
+    const rankedLocalMatches = rankLocalMatches(payload.localMatches, query);
+    const directAnswer = buildDirectAnswer(query, rankedLocalMatches, payload.serverMatches);
+    const synthesizedAnswer = !directAnswer && providerReady
+        ? (payload.synthesizedAnswer
+            ?? await synthesizeAnswerFromProvider(query, payload.localMatches, payload.serverMatches))
+        : null;
+    const nextProviderRequiredForSynthesis = !directAnswer && payload.total > 0;
+    const nextSuggestions = !directAnswer && nextProviderRequiredForSynthesis && !providerReady
+        ? Array.from(new Set([
+            ...buildHelpfulSuggestions(query),
+            'Run "umbrella-context providers setup" to connect a provider and model for richer synthesized answers.',
+        ]))
+        : payload.suggestions.filter((suggestion) => suggestion !==
+            'Run "umbrella-context providers setup" to connect a provider and model for richer synthesized answers.');
+    const changed = JSON.stringify(payload.directAnswer ?? null) !== JSON.stringify(directAnswer ?? null) ||
+        JSON.stringify(payload.synthesizedAnswer ?? null) !== JSON.stringify(synthesizedAnswer ?? null) ||
+        payload.providerReady !== providerReady ||
+        payload.providerRequiredForSynthesis !== nextProviderRequiredForSynthesis ||
+        JSON.stringify(payload.suggestions) !== JSON.stringify(nextSuggestions);
+    if (!changed) {
+        return payload;
+    }
+    return {
+        ...payload,
+        providerReady,
+        directAnswer,
+        synthesizedAnswer,
+        providerRequiredForSynthesis: nextProviderRequiredForSynthesis,
+        suggestions: nextSuggestions,
+    };
+}
+export async function searchCommandAction(query, opts = {}) {
     const config = configManager.config;
+    const format = opts.format === "json" ? "json" : "text";
+    const providerReadiness = getProviderReadinessSummary();
+    const providerReady = providerReadiness.providerReady && providerReadiness.modelReady;
     if (!config) {
+        if (format === "json") {
+            printJson({ ok: false, action: "query", error: "Not configured. Run: umbrella-context setup" });
+            return;
+        }
         console.log(chalk.red("Not configured. Run: umbrella-context setup"));
         return;
     }
+    if (!query?.trim()) {
+        if (format === "json") {
+            printJson({
+                ok: false,
+                action: "query",
+                error: 'Query argument is required. Example: umbrella-context query "How does auth work?"',
+            });
+            return;
+        }
+        console.log(chalk.red('\n Query argument is required.'));
+        console.log(chalk.gray(' Usage: umbrella-context query "How does auth work?"'));
+        return;
+    }
+    if (isVagueQuery(query)) {
+        const suggestions = buildHelpfulSuggestions(query);
+        if (format === "json") {
+            printJson({
+                ok: false,
+                action: "query",
+                error: "The query is too vague. Ask a fuller natural-language question.",
+                suggestions,
+            });
+            return;
+        }
+        console.log(chalk.yellow('\n That question is too vague.'));
+        console.log(chalk.gray(" Ask a fuller natural-language question so Context can search more usefully."));
+        suggestions.forEach((suggestion) => {
+            console.log(chalk.gray(` - ${suggestion}`));
+        });
+        return;
+    }
     try {
         await setSessionPanel("query", query);
         await recordSessionQuery(query);
+        const fingerprint = await buildLocalQueryFingerprint();
+        const cached = await getQueryCacheEntry(query, fingerprint);
+        if (cached) {
+            const enrichedPayload = await enrichCachedPayload(query, cached.payload, providerReady);
+            if (enrichedPayload !== cached.payload) {
+                await storeQueryCacheEntry({
+                    query,
+                    normalizedQuery: normalizeQuery(query),
+                    fingerprint,
+                    payload: enrichedPayload,
+                });
+            }
+            await markQueryCacheHit(cached.id);
+            await recordSessionEvent({
+                kind: "query",
+                title: `Answered cached query for "${query}"`,
+                detail: `Reused a cached answer for ${enrichedPayload.companyName} / ${enrichedPayload.spaceName}.`,
+                panel: "query",
+                focus: query,
+                status: "success",
+            });
+            printSearchPayload(format, enrichedPayload, true);
+            return;
+        }
         const task = await createTask({
             kind: "query",
             title: `Query: ${query}`,
@@ -18,7 +797,8 @@ export async function searchCommandAction(query) {
             panel: "query",
             focus: query,
         });
-        const localMatches = summarizeLocalMemoryMatches([...(await getPendingMemories()), ...(await getPulledMemories())], query);
+        const rankedLocalMatches = rankLocalMatches(summarizeLocalMemoryMatches([...(await getPendingMemories()), ...(await getPulledMemories())], query), query);
+        const localMatches = rankedLocalMatches.map(({ entry }) => entry);
         await addTaskReasoningContent(task.id, `Checked local repo context first and found ${localMatches.length} candidate match${localMatches.length === 1 ? "" : "es"}.`);
         await addTaskToolCall(task.id, {
             toolName: "server.memory.search",
@@ -43,6 +823,10 @@ export async function searchCommandAction(query) {
                 error: err.error,
             });
             await completeTask(task.id, "failed", err.error || "Search failed.");
+            if (format === "json") {
+                printJson({ ok: false, action: "query", error: err.error || "Search failed." });
+                return;
+            }
             console.log(chalk.red(`\n Failed: ${err.error}`));
             return;
         }
@@ -55,20 +839,56 @@ export async function searchCommandAction(query) {
         });
         await appendTaskStreamingContent(task.id, `server=${data.results.length};`);
         await addTaskReasoningContent(task.id, `Shared search returned ${data.results.length} match${data.results.length === 1 ? "" : "es"}.`);
+        const payload = {
+            companyName: config.companyName,
+            spaceName: config.projectName,
+            query,
+            localMatches,
+            serverMatches: data.results,
+            total: localMatches.length + data.results.length,
+            suggestions: [],
+            providerReady,
+            providerRequiredForSynthesis: false,
+            directAnswer: buildDirectAnswer(query, rankedLocalMatches, data.results),
+            synthesizedAnswer: null,
+        };
         if (data.results.length === 0 && localMatches.length === 0) {
-            await completeTask(task.id, "completed", "No local or shared context matched this question.");
-            await recordSessionEvent({
-                kind: "query",
-                title: `No context found for "${query}"`,
-                detail: "The query did not match local drafts or server context.",
-                panel: "query",
-                focus: query,
-                status: "warning",
+            await removeTask(task.id);
+            const suggestions = buildHelpfulSuggestions(query);
+            payload.suggestions = suggestions;
+            await storeQueryCacheEntry({
+                query,
+                normalizedQuery: normalizeQuery(query),
+                fingerprint,
+                payload,
             });
-            console.log(chalk.yellow(`\n No context found for "${query}"`));
+            if (format === "json") {
+                printSearchPayload(format, payload);
+                return;
+            }
+            printSearchPayload(format, payload);
             return;
         }
+        if (!payload.directAnswer && payload.total > 0) {
+            payload.providerRequiredForSynthesis = true;
+            if (!providerReady) {
+                payload.suggestions = [
+                    ...buildHelpfulSuggestions(query),
+                    'Run "umbrella-context providers setup" to connect a provider and model for richer synthesized answers.',
+                ];
+                await addTaskReasoningContent(task.id, "Partial context exists, but there is no provider/model ready for a richer synthesized answer yet.");
+            }
+            else {
+                payload.synthesizedAnswer = await synthesizeAnswerFromProvider(query, localMatches, data.results);
+                await addTaskReasoningContent(task.id, payload.synthesizedAnswer
+                    ? "Partial context existed, and the connected provider synthesized one cleaner answer from the saved matches."
+                    : "Partial context exists and a provider is ready, so this query can support richer synthesis in a later pass.");
+            }
+        }
         await completeTask(task.id, "completed", `Found ${localMatches.length} local match${localMatches.length === 1 ? "" : "es"} and ${data.results.length} shared match${data.results.length === 1 ? "" : "es"}.`);
+        if (payload.directAnswer) {
+            await addTaskReasoningContent(task.id, `A direct answer was possible because one match clearly dominated the others.`);
+        }
         await recordSessionEvent({
             kind: "query",
             title: `Searched Context for "${query}"`,
@@ -77,29 +897,13 @@ export async function searchCommandAction(query) {
             focus: query,
             status: "success",
         });
-        console.log(chalk.bold(`\n Found context for ${config.companyName} / ${config.projectName}:\n`));
-        if (localMatches.length > 0) {
-            console.log(chalk.cyan(" Local .um matches:\n"));
-            localMatches.forEach((result, index) => {
-                console.log(chalk.cyan(`  ${index + 1}. [local]`));
-                console.log(`     ${result.content}`);
-                if (result.tags?.length)
-                    console.log(chalk.gray(`     Tags: ${result.tags.join(", ")}`));
-                console.log(chalk.gray(`     Saved: ${new Date(result.createdAt).toLocaleString()}`));
-                console.log("");
-            });
-        }
-        if (data.results.length > 0) {
-            console.log(chalk.cyan(" Server matches:\n"));
-        }
-        data.results.forEach((result, index) => {
-            console.log(chalk.cyan(`  ${index + 1}. [${result.systemType}]`));
-            console.log(`     ${result.content}`);
-            if (result.tags?.length)
-                console.log(chalk.gray(`     Tags: ${result.tags.join(", ")}`));
-            console.log(chalk.gray(`     Source: ${result.source} | ${new Date(result.createdAt).toLocaleDateString()}`));
-            console.log("");
+        await storeQueryCacheEntry({
+            query,
+            normalizedQuery: normalizeQuery(query),
+            fingerprint,
+            payload,
         });
+        printSearchPayload(format, payload);
     }
     catch (err) {
         const failedTask = await createTask({
@@ -111,11 +915,28 @@ export async function searchCommandAction(query) {
             focus: query,
         });
         await completeTask(failedTask.id, "failed", err.message);
+        if (format === "json") {
+            printJson({ ok: false, action: "query", error: err.message });
+            return;
+        }
         console.log(chalk.red(`\n Error: ${err.message}`));
     }
 }
 export function searchCommand(cli) {
-    cli.command("search <query>", "Search saved context by keyword").action(async (query) => {
-        await searchCommandAction(query);
+    cli
+        .command("search <query>", `Query and retrieve information from saved context.
+
+Good:
+- "How is authentication implemented?"
+- "What are the API rate limits and where are they enforced?"
+Bad:
+- "auth"
+- "authentication"
+- "show me code"`)
+        .option("--format <format>", "Output format (text or json)")
+        .example('search "How is authentication implemented?"')
+        .example('search "How does auth work?" --format json')
+        .action(async (query, opts) => {
+        await searchCommandAction(query, opts);
     });
 }