@lovelybunch/api 1.0.70 → 1.0.71-alpha.1

package/dist/routes/api/v1/ai/route.js

@@ -1,11 +1,13 @@
 import { homedir } from 'os';
 import { join, resolve as pathResolve, basename } from 'path';
-import { existsSync, readFileSync, promises as fs } from 'fs';
+import { existsSync, readFileSync, promises as fs, createReadStream } from 'fs';
 import { fileURLToPath } from 'url';
-import { proposalsTool, listProposalsTool, validateProposalData, knowledgeTool, normalizeKnowledgeMetadata } from '@lovelybunch/mcp';
+import readline from 'readline';
+import { getLogsDir } from '@lovelybunch/core';
+import { proposalsReadOnlyTool, knowledgeTool, normalizeKnowledgeMetadata, eventsTool, projectContextTool, architectureContextTool } from '@lovelybunch/mcp';
 import matter from 'gray-matter';
+import Fuse from 'fuse.js';
 import { FileStorageAdapter } from '../../../../lib/storage/file-storage.js';
-import { getAuthorInfo } from '../../../../lib/user-preferences.js';
 // Function to get global config API key as fallback
 function getGlobalApiKey(provider) {
     try {
@@ -51,18 +53,27 @@ export async function POST(c) {
             ? `${baseSystem}\n\nThe following persona is authoritative and overrides general guidance above. You must strictly follow it.\n\n${agentPersona}`
             : baseSystem;
         // Prepare tools for function calling
+        // Note: proposals is read-only, knowledge/project/architecture are read+write, events is read-only
         const tools = enableTools ? [
             {
                 type: "function",
-                function: listProposalsTool
+                function: proposalsReadOnlyTool
             },
             {
                 type: "function",
-                function: proposalsTool
+                function: knowledgeTool
             },
             {
                 type: "function",
-                function: knowledgeTool
+                function: eventsTool
+            },
+            {
+                type: "function",
+                function: projectContextTool
+            },
+            {
+                type: "function",
+                function: architectureContextTool
             }
         ] : null;
         const contextMessages = Array.isArray(attachedContextFiles)
@@ -70,7 +81,7 @@ export async function POST(c) {
                 .filter((file) => file && typeof file.content === 'string' && file.content.trim().length > 0)
                 .map((file) => ({
                 role: 'system',
-                content: `Context from ${file.name || file.path || 'reference'}:\n${file.content}`
+                content: `[ATTACHED CONTEXT - FULL CONTENT INCLUDED BELOW - DO NOT USE TOOLS TO FETCH THIS FILE]\nDocument: ${file.name || file.path || 'reference'}\nType: ${file.type || 'context'}\n\n--- BEGIN CONTENT ---\n${file.content}\n--- END CONTENT ---`
             }))
             : [];
         // Compose the message list: system + history (preferred) or single message
@@ -121,9 +132,26 @@ export async function POST(c) {
             body: JSON.stringify(requestBody),
         });
         if (!response.ok) {
-            const error = await response.text();
-            console.error("OpenRouter API error:", error);
-            return c.json({ error: "Failed to get AI response" }, 500);
+            const errorText = await response.text();
+            console.error("OpenRouter API error:", {
+                status: response.status,
+                statusText: response.statusText,
+                error: errorText,
+                model: requestBody.model
+            });
+            // Try to parse error for more detail
+            let errorDetail = "Failed to get AI response";
+            try {
+                const errorJson = JSON.parse(errorText);
+                errorDetail = errorJson.error?.message || errorJson.error || errorDetail;
+            }
+            catch {
+                // Use raw text if not JSON
+                if (errorText.length < 200) {
+                    errorDetail = errorText || errorDetail;
+                }
+            }
+            return c.json({ error: errorDetail, status: response.status }, response.status);
         }
         // Handle streaming response
         if (stream === true && response.body) {
@@ -139,7 +167,13 @@ export async function POST(c) {
         const data = await response.json();
         const aiMessage = data.choices?.[0]?.message;
         if (!aiMessage) {
-            return c.json({ error: "No response from AI model" }, 500);
+            console.error("No AI message in response:", {
+                model: requestBody.model,
+                choices: data.choices,
+                error: data.error
+            });
+            const errorDetail = data.error?.message || data.error || "No response from AI model";
+            return c.json({ error: errorDetail }, 500);
         }
         // Handle tool calls
         if (aiMessage.tool_calls && aiMessage.tool_calls.length > 0) {
@@ -198,20 +232,44 @@ async function executeToolCalls(toolCalls) {
         try {
             // Handle both function calling formats
             const functionName = toolCall.function?.name || toolCall.name;
-            const functionArgs = toolCall.function?.arguments ?
-                JSON.parse(toolCall.function.arguments) :
-                toolCall.arguments;
+            let functionArgs;
+            if (toolCall.function?.arguments) {
+                try {
+                    functionArgs = JSON.parse(toolCall.function.arguments);
+                }
+                catch (parseError) {
+                    // LLM may generate invalid JSON with unescaped characters in long content
+                    // Return a helpful error message
+                    const errorMsg = parseError instanceof Error ? parseError.message : 'Unknown parse error';
+                    return {
+                        tool_call_id: toolCall.id,
+                        content: JSON.stringify({
+                            success: false,
+                            error: `Invalid tool arguments: ${errorMsg}. Please retry with simpler content.`
+                        })
+                    };
+                }
+            }
+            else {
+                functionArgs = toolCall.arguments;
+            }
             let result = { success: false, error: 'Unknown tool' };
             // Execute tools directly instead of making HTTP requests
             if (functionName === 'change_proposals') {
                 result = await executeProposalsToolDirect(functionArgs, storage);
             }
-            else if (functionName === 'list_proposals') {
-                result = await executeListProposalsToolDirect(functionArgs, storage);
-            }
             else if (functionName === 'knowledge_documents') {
                 result = await executeKnowledgeToolDirect(functionArgs);
             }
+            else if (functionName === 'activity_events') {
+                result = await executeEventsToolDirect(functionArgs);
+            }
+            else if (functionName === 'project_context') {
+                result = await executeProjectContextToolDirect(functionArgs);
+            }
+            else if (functionName === 'architecture_context') {
+                result = await executeArchitectureContextToolDirect(functionArgs);
+            }
             return {
                 tool_call_id: toolCall.id,
                 content: JSON.stringify({
@@ -234,8 +292,9 @@ async function executeToolCalls(toolCalls) {
     });
     return Promise.all(resultPromises);
 }
+// Proposals tool is READ-ONLY - only list and get operations are supported
 async function executeProposalsToolDirect(args, storage) {
-    const { operation, id, filters, proposal } = args;
+    const { operation, id, filters } = args;
     try {
         switch (operation) {
             case 'list': {
@@ -260,121 +319,8 @@ async function executeProposalsToolDirect(args, storage) {
                     message: `Retrieved proposal ${id}`
                 };
             }
-            case 'create': {
-                if (!proposal) {
-                    return { success: false, error: 'Proposal data is required for create operation' };
-                }
-                // Validate proposal data - check required fields
-                if (!proposal.intent || !proposal.content) {
-                    return { success: false, error: 'Proposal intent and content are required' };
-                }
-                // Get author info
-                const author = await getAuthorInfo();
-                // Normalize and validate incoming proposal
-                const validatedProposal = validateProposalData(proposal);
-                // Normalize plan steps: accept strings or objects
-                const planSteps = (validatedProposal.planSteps || []).map((step, index) => {
-                    if (typeof step === 'string') {
-                        return {
-                            id: `step-${index + 1}`,
-                            description: step,
-                            status: 'pending'
-                        };
-                    }
-                    return {
-                        id: step.id || `step-${index + 1}`,
-                        description: step.description || '',
-                        status: step.status || 'pending',
-                        command: step.command,
-                        expectedOutcome: step.expectedOutcome,
-                        output: step.output,
-                        error: step.error,
-                        executedAt: step.executedAt
-                    };
-                });
-                const now = new Date();
-                const newProposal = {
-                    id: validatedProposal.id || `cp-${Date.now()}`,
-                    intent: validatedProposal.intent || '',
-                    content: validatedProposal.content || '',
-                    author: {
-                        id: validatedProposal.author?.id || 'current-user',
-                        name: validatedProposal.author?.name || author.name || 'Unknown User',
-                        email: validatedProposal.author?.email || author.email || '',
-                        type: validatedProposal.author?.type || 'human'
-                    },
-                    planSteps,
-                    evidence: validatedProposal.evidence || [],
-                    policies: validatedProposal.policies || [],
-                    featureFlags: validatedProposal.featureFlags || [],
-                    experiments: validatedProposal.experiments || [],
-                    telemetryContracts: validatedProposal.telemetryContracts || [],
-                    releasePlan: validatedProposal.releasePlan || { strategy: 'immediate' },
-                    status: validatedProposal.status || 'draft',
-                    metadata: {
-                        createdAt: now,
-                        updatedAt: now,
-                        reviewers: validatedProposal.metadata?.reviewers || [],
-                        aiInteractions: validatedProposal.metadata?.aiInteractions || [],
-                        tags: validatedProposal.metadata?.tags || [],
-                        priority: validatedProposal.metadata?.priority || 'medium'
-                    },
-                    productSpecRef: validatedProposal.productSpecRef
-                };
-                await storage.createCP(newProposal);
-                return {
-                    success: true,
-                    data: newProposal,
-                    message: `Created proposal ${newProposal.id} (${newProposal.intent})`
-                };
-            }
-            case 'update': {
-                if (!id || !proposal) {
-                    return { success: false, error: 'Proposal ID and data are required for update operation' };
-                }
-                // Validate proposal data - check required fields
-                if (!proposal.intent || !proposal.content) {
-                    return { success: false, error: 'Proposal intent and content are required' };
-                }
-                // Get existing proposal to preserve author and creation date
-                const existingProposal = await storage.getCP(id);
-                if (!existingProposal) {
-                    return { success: false, error: 'Proposal not found' };
-                }
-                // Update the proposal
-                const proposalToUpdate = {
-                    ...proposal,
-                    author: existingProposal.author, // Preserve original author
-                    metadata: {
-                        ...existingProposal.metadata,
-                        ...proposal.metadata,
-                        updatedAt: new Date().toISOString()
-                    }
-                };
-                await storage.updateCP(id, proposalToUpdate);
-                return {
-                    success: true,
-                    data: proposalToUpdate,
-                    message: `Updated proposal ${id}`
-                };
-            }
-            case 'delete': {
-                if (!id) {
-                    return { success: false, error: 'Proposal ID is required for delete operation' };
-                }
-                // Check if proposal exists before deleting
-                const existingProposal = await storage.getCP(id);
-                if (!existingProposal) {
-                    return { success: false, error: 'Proposal not found' };
-                }
-                await storage.deleteCP(id);
-                return {
-                    success: true,
-                    message: `Deleted proposal ${id}`
-                };
-            }
             default:
-                return { success: false, error: `Unknown operation: ${operation}` };
+                return { success: false, error: `Proposals are read-only. Only 'list' and 'get' operations are supported. To create proposals, use a coding agent (Claude Code, Cursor, etc.) or the Proposals UI.` };
         }
     }
     catch (error) {
@@ -382,49 +328,21 @@ async function executeProposalsToolDirect(args, storage) {
         return { success: false, error: error.message || 'Tool execution failed' };
     }
 }
-async function executeListProposalsToolDirect(args, storage) {
-    const { filters } = args;
-    try {
-        const proposals = await storage.listCPs(filters || {});
-        // Return only metadata, not full content
-        const metadataOnly = proposals.map(proposal => ({
-            id: proposal.id,
-            intent: proposal.intent,
-            status: proposal.status,
-            priority: proposal.metadata?.priority || 'medium',
-            tags: proposal.metadata?.tags || [],
-            author: {
-                name: proposal.author.name,
-                email: proposal.author.email
-            },
-            createdAt: proposal.metadata.createdAt,
-            updatedAt: proposal.metadata.updatedAt,
-            reviewers: proposal.metadata.reviewers || [],
-            productSpecRef: proposal.productSpecRef
-        }));
-        return {
-            success: true,
-            data: metadataOnly,
-            message: `Found ${metadataOnly.length} proposals`
-        };
-    }
-    catch (error) {
-        console.error('Error executing list proposals tool:', error);
-        return { success: false, error: error.message || 'Failed to list proposals' };
-    }
-}
 async function executeKnowledgeToolDirect(args) {
-    const { operation, filename, title, content, metadata, summary } = args;
+    const { operation, filename, title, content, metadata, summary, query } = args;
     try {
         const knowledgePath = getKnowledgeBasePath();
         await fs.mkdir(knowledgePath, { recursive: true });
         switch (operation) {
             case 'list': {
-                const documents = await listKnowledgeDocuments(knowledgePath);
+                const searchQuery = query && typeof query === 'string' ? query : undefined;
+                const documents = await listKnowledgeDocuments(knowledgePath, searchQuery);
                 return {
                     success: true,
                     data: documents,
-                    message: `Found ${documents.length} knowledge documents`
+                    message: searchQuery
+                        ? `Found ${documents.length} knowledge documents matching "${searchQuery}"`
+                        : `Found ${documents.length} knowledge documents`
                 };
             }
             case 'get': {
@@ -563,6 +481,315 @@ async function executeKnowledgeToolDirect(args) {
         return { success: false, error: error.message || 'Knowledge tool execution failed' };
     }
 }
+// Events tool is READ-ONLY - returns recent activity events
+async function executeEventsToolDirect(args) {
+    const { operation, limit = 20, kind } = args;
+    if (operation !== 'list') {
+        return {
+            success: false,
+            error: `Events are read-only. Only 'list' operation is supported.`
+        };
+    }
+    try {
+        const eventsDir = getLogsDir();
+        const currentFile = join(eventsDir, 'events-current.jsonl');
+        // Check if file exists
+        try {
+            await fs.access(currentFile);
+        }
+        catch {
+            return {
+                success: true,
+                data: [],
+                message: 'No events found'
+            };
+        }
+        // Read all events from file
+        const allEvents = [];
+        const fileStream = createReadStream(currentFile);
+        const rl = readline.createInterface({
+            input: fileStream,
+            crlfDelay: Infinity,
+        });
+        for await (const line of rl) {
+            if (!line.trim())
+                continue;
+            try {
+                const event = JSON.parse(line);
+                // Apply kind filter if specified
+                if (kind && typeof kind === 'string') {
+                    if (!event.kind || !event.kind.startsWith(kind)) {
+                        continue;
+                    }
+                }
+                allEvents.push(event);
+            }
+            catch {
+                // Skip malformed lines
+                continue;
+            }
+        }
+        // Sort by timestamp descending (most recent first) and limit
+        const cappedLimit = Math.min(Math.max(1, limit), 100);
+        const sortedEvents = allEvents
+            .sort((a, b) => {
+            // Sort by seq descending (higher seq = more recent)
+            return (b.seq || 0) - (a.seq || 0);
+        })
+            .slice(0, cappedLimit);
+        // Format events for readability
+        const formattedEvents = sortedEvents.map(event => ({
+            seq: event.seq,
+            kind: event.kind,
+            actor: event.actor,
+            subject: event.subject,
+            timestamp: event.ts,
+            level: event.level,
+            tags: event.tags,
+            summary: event.payload?.summary || event.payload?.message || event.payload?.title || undefined
+        }));
+        return {
+            success: true,
+            data: formattedEvents,
+            message: kind
+                ? `Found ${formattedEvents.length} recent '${kind}' events`
+                : `Found ${formattedEvents.length} recent events`
+        };
+    }
+    catch (error) {
+        console.error('Error executing events tool:', error);
+        return { success: false, error: error.message || 'Events tool execution failed' };
+    }
+}
+// Project context tool - read/write the project definition document
+async function executeProjectContextToolDirect(args) {
+    const { operation, content, old_text, new_text } = args;
+    try {
+        const contextPath = getContextBasePath();
+        const filePath = join(contextPath, 'project.md');
+        switch (operation) {
+            case 'get': {
+                try {
+                    const fileContent = await fs.readFile(filePath, 'utf-8');
+                    const parsed = matter(fileContent);
+                    return {
+                        success: true,
+                        data: {
+                            content: parsed.content,
+                            frontmatter: parsed.data,
+                            raw: fileContent
+                        },
+                        message: 'Retrieved project context'
+                    };
+                }
+                catch (err) {
+                    if (err.code === 'ENOENT') {
+                        return {
+                            success: true,
+                            data: { content: '', frontmatter: {}, raw: '' },
+                            message: 'Project context document does not exist yet. You can create it with an update operation.'
+                        };
+                    }
+                    throw err;
+                }
+            }
+            case 'append': {
+                if (!content) {
+                    return { success: false, error: 'Content is required for append operation' };
+                }
+                await fs.mkdir(contextPath, { recursive: true });
+                // Read existing content if file exists
+                let existingContent = '';
+                try {
+                    existingContent = await fs.readFile(filePath, 'utf-8');
+                }
+                catch (err) {
+                    if (err.code !== 'ENOENT')
+                        throw err;
+                }
+                // Append new content with a newline separator
+                const newContent = existingContent
+                    ? existingContent.trimEnd() + '\n\n' + content
+                    : content;
+                await fs.writeFile(filePath, newContent, 'utf-8');
+                return {
+                    success: true,
+                    message: 'Appended content to project context document'
+                };
+            }
+            case 'replace_section': {
+                if (!old_text || !new_text) {
+                    return { success: false, error: 'Both old_text and new_text are required for replace_section operation' };
+                }
+                // Read existing content
+                let existingContent = '';
+                try {
+                    existingContent = await fs.readFile(filePath, 'utf-8');
+                }
+                catch (err) {
+                    if (err.code === 'ENOENT') {
+                        return { success: false, error: 'Project context document does not exist. Use append or update to create it first.' };
+                    }
+                    throw err;
+                }
+                // Check if old_text exists in the document
+                if (!existingContent.includes(old_text)) {
+                    return {
+                        success: false,
+                        error: 'Could not find the specified text in the document. The text may have been paraphrased or changed.',
+                        fallback_markdown: new_text,
+                        suggestion: 'Here is the replacement text. You can copy it and manually edit the document at /context/project'
+                    };
+                }
+                // Replace the text
+                const updatedContent = existingContent.replace(old_text, new_text);
+                await fs.writeFile(filePath, updatedContent, 'utf-8');
+                return {
+                    success: true,
+                    message: 'Replaced section in project context document'
+                };
+            }
+            case 'update': {
+                if (!content) {
+                    return { success: false, error: 'Content is required for update operation' };
+                }
+                await fs.mkdir(contextPath, { recursive: true });
+                await fs.writeFile(filePath, content, 'utf-8');
+                return {
+                    success: true,
+                    message: 'Updated project context document'
+                };
+            }
+            default:
+                return { success: false, error: `Unknown operation: ${operation}. Use 'get', 'append', 'replace_section', or 'update'.` };
+        }
+    }
+    catch (error) {
+        console.error('Error executing project context tool:', error);
+        return { success: false, error: error.message || 'Project context tool execution failed' };
+    }
+}
+// Architecture context tool - read/write the architecture document
+async function executeArchitectureContextToolDirect(args) {
+    const { operation, content, old_text, new_text } = args;
+    try {
+        const contextPath = getContextBasePath();
+        const filePath = join(contextPath, 'architecture.md');
+        switch (operation) {
+            case 'get': {
+                try {
+                    const fileContent = await fs.readFile(filePath, 'utf-8');
+                    const parsed = matter(fileContent);
+                    return {
+                        success: true,
+                        data: {
+                            content: parsed.content,
+                            frontmatter: parsed.data,
+                            raw: fileContent
+                        },
+                        message: 'Retrieved architecture context'
+                    };
+                }
+                catch (err) {
+                    if (err.code === 'ENOENT') {
+                        return {
+                            success: true,
+                            data: { content: '', frontmatter: {}, raw: '' },
+                            message: 'Architecture context document does not exist yet. You can create it with an update operation.'
+                        };
+                    }
+                    throw err;
+                }
+            }
+            case 'append': {
+                if (!content) {
+                    return { success: false, error: 'Content is required for append operation' };
+                }
+                await fs.mkdir(contextPath, { recursive: true });
+                // Read existing content if file exists
+                let existingContent = '';
+                try {
+                    existingContent = await fs.readFile(filePath, 'utf-8');
+                }
+                catch (err) {
+                    if (err.code !== 'ENOENT')
+                        throw err;
+                }
+                // Append new content with a newline separator
+                const newContent = existingContent
+                    ? existingContent.trimEnd() + '\n\n' + content
+                    : content;
+                await fs.writeFile(filePath, newContent, 'utf-8');
+                return {
+                    success: true,
+                    message: 'Appended content to architecture context document'
+                };
+            }
+            case 'replace_section': {
+                if (!old_text || !new_text) {
+                    return { success: false, error: 'Both old_text and new_text are required for replace_section operation' };
+                }
+                // Read existing content
+                let existingContent = '';
+                try {
+                    existingContent = await fs.readFile(filePath, 'utf-8');
+                }
+                catch (err) {
+                    if (err.code === 'ENOENT') {
+                        return { success: false, error: 'Architecture context document does not exist. Use append or update to create it first.' };
+                    }
+                    throw err;
+                }
+                // Check if old_text exists in the document
+                if (!existingContent.includes(old_text)) {
+                    return {
+                        success: false,
+                        error: 'Could not find the specified text in the document. The text may have been paraphrased or changed.',
+                        fallback_markdown: new_text,
+                        suggestion: 'Here is the replacement text. You can copy it and manually edit the document at /context/architecture'
+                    };
+                }
+                // Replace the text
+                const updatedContent = existingContent.replace(old_text, new_text);
+                await fs.writeFile(filePath, updatedContent, 'utf-8');
+                return {
+                    success: true,
+                    message: 'Replaced section in architecture context document'
+                };
+            }
+            case 'update': {
+                if (!content) {
+                    return { success: false, error: 'Content is required for update operation' };
+                }
+                await fs.mkdir(contextPath, { recursive: true });
+                await fs.writeFile(filePath, content, 'utf-8');
+                return {
+                    success: true,
+                    message: 'Updated architecture context document'
+                };
+            }
+            default:
+                return { success: false, error: `Unknown operation: ${operation}. Use 'get', 'append', 'replace_section', or 'update'.` };
+        }
+    }
+    catch (error) {
+        console.error('Error executing architecture context tool:', error);
+        return { success: false, error: error.message || 'Architecture context tool execution failed' };
+    }
+}
+function getContextBasePath() {
+    let basePath;
+    if (process.env.NODE_ENV === 'development' && process.env.GAIT_DEV_ROOT) {
+        basePath = process.env.GAIT_DEV_ROOT;
+    }
+    else if (process.env.GAIT_DATA_PATH) {
+        basePath = pathResolve(process.env.GAIT_DATA_PATH, '.nut');
+    }
+    else {
+        basePath = pathResolve(process.cwd(), '.nut');
+    }
+    return join(basePath, 'context');
+}
 function getKnowledgeBasePath() {
     let basePath;
     if (process.env.NODE_ENV === 'development' && process.env.GAIT_DEV_ROOT) {
@@ -609,9 +836,14 @@ function extractKnowledgeTitle(content, fallback) {
 async function readKnowledgeDocument(basePath, filename) {
     const actualFilename = resolveKnowledgeFilename(filename, filename);
     const filePath = join(basePath, actualFilename);
-    const raw = await fs.readFile(filePath, 'utf-8');
+    const [raw, stats] = await Promise.all([
+        fs.readFile(filePath, 'utf-8'),
+        fs.stat(filePath)
+    ]);
     const { data, content } = matter(raw);
     const metadata = normalizeKnowledgeMetadata(data);
+    // Use file mtime for updated timestamp instead of frontmatter
+    metadata.updated = stats.mtime.toISOString();
     const title = extractKnowledgeTitle(content, actualFilename);
     return {
         filename: actualFilename,
@@ -620,7 +852,54 @@ async function readKnowledgeDocument(basePath, filename) {
         content
     };
 }
-async function listKnowledgeDocuments(basePath) {
+function extractSnippet(content, query, maxLength = 200) {
+    const lowerContent = content.toLowerCase();
+    const lowerQuery = query.toLowerCase();
+    const terms = lowerQuery.split(/\s+/);
+    // Find the first occurrence of any search term
+    let bestIndex = -1;
+    let matchedTerm = '';
+    for (const term of terms) {
+        const index = lowerContent.indexOf(term);
+        if (index !== -1 && (bestIndex === -1 || index < bestIndex)) {
+            bestIndex = index;
+            matchedTerm = term;
+        }
+    }
+    if (bestIndex === -1) {
+        // No match found, return beginning of content
+        return content.slice(0, maxLength) + (content.length > maxLength ? '...' : '');
+    }
+    // Extract snippet around the match
+    const start = Math.max(0, bestIndex - 60);
+    const end = Math.min(content.length, bestIndex + matchedTerm.length + 140);
+    let snippet = content.slice(start, end);
+    // Add ellipsis if needed
+    if (start > 0)
+        snippet = '...' + snippet;
+    if (end < content.length)
+        snippet = snippet + '...';
+    return snippet;
+}
+function findMatchedFields(doc, query) {
+    const lowerQuery = query.toLowerCase();
+    const terms = lowerQuery.split(/\s+/);
+    const matched = [];
+    const checkField = (value, fieldName) => {
+        if (value && terms.some(term => value.toLowerCase().includes(term))) {
+            matched.push(fieldName);
+        }
+    };
+    checkField(doc.title, 'title');
+    checkField(doc.content, 'content');
+    checkField(doc.metadata?.category, 'category');
+    checkField(doc.metadata?.summary, 'summary');
+    if (doc.metadata?.tags?.some(tag => terms.some(term => tag.toLowerCase().includes(term)))) {
+        matched.push('tags');
+    }
+    return matched;
+}
+async function listKnowledgeDocuments(basePath, query) {
     const files = await fs.readdir(basePath);
     const markdownFiles = files.filter(file => file.endsWith('.md'));
     const documents = await Promise.all(markdownFiles.map(async (file) => {
@@ -632,9 +911,33 @@ async function listKnowledgeDocuments(basePath) {
             return null;
         }
     }));
-    return documents
-        .filter((doc) => doc !== null)
-        .sort((a, b) => a.filename.localeCompare(b.filename));
+    const validDocs = documents.filter((doc) => doc !== null);
+    // If no query, return all documents sorted by filename
+    if (!query?.trim()) {
+        return validDocs.sort((a, b) => a.filename.localeCompare(b.filename));
+    }
+    // Use Fuse.js for fuzzy search
+    const fuse = new Fuse(validDocs, {
+        keys: [
+            { name: 'title', weight: 2 },
+            { name: 'content', weight: 1 },
+            { name: 'metadata.summary', weight: 1.5 },
+            { name: 'metadata.category', weight: 1 },
+            { name: 'metadata.tags', weight: 1.5 }
+        ],
+        threshold: 0.4,
+        includeScore: true,
+        ignoreLocation: true,
+        minMatchCharLength: 2
+    });
+    const results = fuse.search(query);
+    // Enhance results with snippets and matched fields
+    return results.map(result => ({
+        ...result.item,
+        snippet: extractSnippet(result.item.content, query),
+        matchedIn: findMatchedFields(result.item, query),
+        score: result.score
+    }));
 }
 function readSharedPrompt(name) {
     // Try multiple candidate paths depending on cwd when running via Turbo