fix: fallback to highest-similarity chunk when isFirstChunk metadata missing

Documents uploaded before isFirstChunk was added had no chunk marked
as first, causing filterAndFormatContext to return 0 results when all
similarities were below 0.5. Now falls back to the highest-similarity
chunk per document when no isFirstChunk metadata exists.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: NorbertKlockiewicz

__tests__/prepareContext.test.ts

@@ -82,4 +82,44 @@ describe('filterAndFormatContext', () => {
     // 2 first chunks + 2 relevant chunks = 4
     expect(result).toHaveLength(4);
   });
+
+  it('includes highest-similarity chunk per document as fallback when no isFirstChunk metadata', () => {
+    // Documents uploaded before isFirstChunk was added
+    const chunks = [
+      makeChunk('Intro content', 0.35, 1),
+      makeChunk('Middle content', 0.30, 1),
+      makeChunk('End content', 0.20, 1),
+    ];
+    const result = filterAndFormatContext(chunks);
+    // No chunks pass the 0.5 threshold and none are marked isFirstChunk,
+    // but the highest-similarity chunk per document should be included as fallback
+    expect(result).toHaveLength(1);
+    expect(result[0]).toContain('Intro content');
+  });
+
+  it('fallback chunk does not duplicate an already-included first chunk', () => {
+    const chunks = [
+      makeChunk('Real first', 0.35, 1, true),
+      makeChunk('Other', 0.30, 1),
+    ];
+    const result = filterAndFormatContext(chunks);
+    // First chunk is included, no relevant chunks pass threshold,
+    // but fallback should not duplicate — still just 1
+    expect(result).toHaveLength(1);
+    expect(result[0]).toContain('Real first');
+  });
+
+  it('fallback works per-document when multiple documents lack isFirstChunk', () => {
+    const chunks = [
+      makeChunk('Doc1 best', 0.40, 1),
+      makeChunk('Doc1 other', 0.20, 1),
+      makeChunk('Doc2 best', 0.35, 2),
+      makeChunk('Doc2 other', 0.10, 2),
+    ];
+    const result = filterAndFormatContext(chunks);
+    // One fallback per document = 2
+    expect(result).toHaveLength(2);
+    expect(result[0]).toContain('Doc1 best');
+    expect(result[1]).toContain('Doc2 best');
+  });
 });

utils/contextUtils.ts

@@ -14,13 +14,41 @@ interface ContextChunk {
 export const filterAndFormatContext = (chunks: ContextChunk[]): string[] => {
   if (chunks.length === 0) return [];
 
+  // First chunks marked with metadata
   const firstChunks = chunks.filter((c) => c.metadata?.isFirstChunk);
+
+  // For documents without any isFirstChunk metadata, use the highest-similarity
+  // chunk as a fallback (covers documents uploaded before isFirstChunk was added)
+  const documentIds = [...new Set(chunks.map((c) => c.metadata?.documentId))];
+  const fallbackChunks: ContextChunk[] = [];
+  for (const docId of documentIds) {
+    const hasFirst = firstChunks.some(
+      (c) => c.metadata?.documentId === docId
+    );
+    if (!hasFirst) {
+      const docChunks = chunks
+        .filter((c) => c.metadata?.documentId === docId)
+        .sort((a, b) => b.similarity - a.similarity);
+      if (docChunks.length > 0) {
+        fallbackChunks.push(docChunks[0]);
+      }
+    }
+  }
+
+  const alwaysIncluded = [...firstChunks, ...fallbackChunks];
+
+  // Relevant chunks above threshold (excluding already-included ones)
+  const alwaysIncludedSet = new Set(alwaysIncluded);
   const relevantChunks = chunks
-    .filter((c) => !c.metadata?.isFirstChunk && c.similarity >= SIMILARITY_THRESHOLD)
+    .filter(
+      (c) =>
+        !alwaysIncludedSet.has(c) &&
+        c.similarity >= SIMILARITY_THRESHOLD
+    )
     .sort((a, b) => b.similarity - a.similarity)
     .slice(0, MAX_RELEVANT_CHUNKS);
 
-  const selected = [...firstChunks, ...relevantChunks];
+  const selected = [...alwaysIncluded, ...relevantChunks];
 
   return selected.map((item, index) => {
     const documentName =