feat: bubble review UI, merge overlapping context rules, non-blocking chat

- Show code-scan suggestions as clickable bubbles with rule excerpt preview
- Fold scan proposals into one intent when they overlap existing knowledge or schema notes
- Approve merges into existing entries/docs instead of creating duplicates
- Clarify review is optional; Agent chat shows a non-blocking pending hint

Co-authored-by: Venkat SF <venkatesh.sakamuri@stayflexi.com>

Author: cursoragent

backend/src/main/java/com/dbaagent/service/codescan/CodeScanService.java

@@ -9,6 +9,8 @@
 import com.dbaagent.repository.CodeScanFileHashRepository;
 import com.dbaagent.repository.CodeScanJobRepository;
 import com.dbaagent.repository.CodeScanSourceRepository;
+import com.dbaagent.repository.CompanyKnowledgeEntryRepository;
+import com.dbaagent.repository.SchemaDocumentationRepository;
 import com.dbaagent.service.SchemaScannerService;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
@@ -66,6 +68,8 @@ public class CodeScanService {
     private final CodeSuggestionApplier applier;
     private final SchemaScannerService schemaScannerService;
     private final SchemaAmbiguityService schemaAmbiguityService;
+    private final CompanyKnowledgeEntryRepository companyKnowledgeEntryRepository;
+    private final SchemaDocumentationRepository schemaDocumentationRepository;
 
     @Value("${code-scan.executor.core:2}")
     private int executorCore;
@@ -492,7 +496,14 @@ private void runJob(String jobId, String connectionId, Path workdir, String sour
                 j.setProgress(90);
             });
 
-            List<CodeKnowledgeSuggestion> aggregated = aggregator.aggregate(connectionId, jobId, raw, schema);
+            List<CodeKnowledgeSuggestion> aggregated = aggregator.aggregate(
+                connectionId,
+                jobId,
+                raw,
+                schema,
+                companyKnowledgeEntryRepository.findByConnectionId(connectionId),
+                schemaDocumentationRepository.findByConnectionId(connectionId)
+            );
             if (!aggregated.isEmpty()) {
                 suggestionRepository.saveAll(aggregated);
                 supersedeStalePending(connectionId, sourceId, jobId, aggregated);

backend/src/main/java/com/dbaagent/service/codescan/CodeSuggestionAggregator.java

@@ -5,6 +5,7 @@
 import com.dbaagent.model.SchemaDocumentation;
 import com.dbaagent.model.code.CodeKnowledgeSuggestion;
 import com.dbaagent.repository.CodeKnowledgeSuggestionRepository;
+import com.dbaagent.repository.CompanyKnowledgeEntryRepository;
 import com.dbaagent.repository.SchemaDocumentationRepository;
 import com.dbaagent.service.CompanyKnowledgeService;
 import com.dbaagent.service.SchemaScannerService;
@@ -15,6 +16,7 @@
 import org.springframework.transaction.annotation.Transactional;
 
 import java.time.LocalDateTime;
+import java.util.ArrayList;
 import java.util.List;
 import java.util.Map;
 import java.util.Optional;
@@ -32,6 +34,7 @@ public class CodeSuggestionApplier {
 
     private final CodeKnowledgeSuggestionRepository suggestionRepository;
     private final SchemaDocumentationRepository schemaDocRepository;
+    private final CompanyKnowledgeEntryRepository companyKnowledgeEntryRepository;
     private final CompanyKnowledgeService companyKnowledgeService;
     private final TrainingService trainingService;
     private final SchemaScannerService schemaScannerService;
@@ -78,6 +81,36 @@ public CodeKnowledgeSuggestion reject(String suggestionId, String decidedBy, Str
     }
 
     private void applySchemaDoc(CodeKnowledgeSuggestion suggestion, String decidedBy) {
+        Map<String, Object> payload = suggestion.getPayload();
+        Object existingDocId = payload == null ? null : payload.get("existingDocId");
+        if (existingDocId != null && !existingDocId.toString().isBlank()) {
+            SchemaDocumentation doc = schemaDocRepository.findById(existingDocId.toString())
+                .orElseThrow(() -> new IllegalArgumentException(
+                    "Existing schema doc not found: " + existingDocId
+                ));
+            doc.setDescription(mergeText(doc.getDescription(), suggestion.getContent()));
+            Object terms = payload.get("businessTerms");
+            if (terms instanceof List<?> list && !list.isEmpty()) {
+                String mergedTerms = mergeCommaSeparated(doc.getBusinessTerms(), list);
+                doc.setBusinessTerms(mergedTerms);
+            }
+            if (doc.getConfidence() == null || (suggestion.getConfidence() != null
+                && suggestion.getConfidence() > doc.getConfidence())) {
+                doc.setConfidence(suggestion.getConfidence());
+            }
+            if (suggestion.getSourceFiles() != null && !suggestion.getSourceFiles().isEmpty()) {
+                doc.setSourceFiles(suggestion.getSourceFiles());
+            }
+            SchemaDocumentation saved = schemaDocRepository.save(doc);
+            suggestion.setAppliedDocId(saved.getId());
+            try {
+                trainingService.upsertDocumentationEmbedding(saved);
+            } catch (Exception e) {
+                log.warn("Failed to embed schema doc {} after approval: {}", saved.getId(), e.getMessage());
+            }
+            return;
+        }
+
         SchemaDocumentation.DocumentationType objectType = resolveObjectType(suggestion);
         String objectName;
         String parentObject = null;
@@ -166,6 +199,27 @@ private void applySchemaDoc(CodeKnowledgeSuggestion suggestion, String decidedBy
     }
 
     private void applyKnowledgeEntry(CodeKnowledgeSuggestion suggestion, String decidedBy) {
+        Map<String, Object> payload = suggestion.getPayload();
+        Object existingId = payload == null ? null : payload.get("existingEntryId");
+        if (existingId != null && !existingId.toString().isBlank()) {
+            CompanyKnowledgeEntry existing = companyKnowledgeEntryRepository.findById(existingId.toString())
+                .orElseThrow(() -> new IllegalArgumentException(
+                    "Existing company knowledge entry not found: " + existingId
+                ));
+            CompanyKnowledgeEntry merged = CompanyKnowledgeEntry.builder()
+                .connectionId(existing.getConnectionId())
+                .title(pickTitle(existing.getTitle(), suggestion.getTitle()))
+                .content(mergeText(existing.getContent(), suggestion.getContent()))
+                .entryType(resolveEntryType(suggestion))
+                .linkedTables(mergeStringLists(existing.getLinkedTables(), suggestion.getLinkedTables()))
+                .linkedColumns(mergeStringLists(existing.getLinkedColumns(), suggestion.getLinkedColumns()))
+                .createdBy(decidedBy)
+                .build();
+            CompanyKnowledgeEntry saved = companyKnowledgeService.updateEntry(existing.getId(), merged);
+            suggestion.setAppliedEntryId(saved.getId());
+            return;
+        }
+
         CompanyKnowledgeEntry entry = CompanyKnowledgeEntry.builder()
             .connectionId(suggestion.getConnectionId())
             .title(suggestion.getTitle())
@@ -220,4 +274,53 @@ private static CompanyKnowledgeEntry.EntryType resolveEntryType(CodeKnowledgeSug
         }
         return CompanyKnowledgeEntry.EntryType.BUSINESS_RULE;
     }
+
+    private static String pickTitle(String existing, String proposed) {
+        if (proposed == null || proposed.isBlank()) return existing;
+        if (existing == null || existing.isBlank()) return proposed;
+        return proposed.length() >= existing.length() ? proposed : existing;
+    }
+
+    private static String mergeText(String existing, String addition) {
+        if (addition == null || addition.isBlank()) {
+            return existing == null ? "" : existing;
+        }
+        if (existing == null || existing.isBlank()) {
+            return addition.trim();
+        }
+        String left = existing.trim();
+        String right = addition.trim();
+        if (left.equalsIgnoreCase(right)) return left;
+        if (left.toLowerCase().contains(right.toLowerCase())) return left;
+        if (right.toLowerCase().contains(left.toLowerCase())) return right;
+        return left + "\n\n" + right;
+    }
+
+    private static List<String> mergeStringLists(List<String> left, List<String> right) {
+        List<String> merged = new ArrayList<>();
+        if (left != null) merged.addAll(left);
+        if (right != null) {
+            for (String value : right) {
+                if (value != null && !value.isBlank() && !merged.contains(value)) {
+                    merged.add(value);
+                }
+            }
+        }
+        return merged;
+    }
+
+    private static String mergeCommaSeparated(String existing, List<?> additions) {
+        List<String> merged = new ArrayList<>();
+        if (existing != null && !existing.isBlank()) {
+            for (String part : existing.split(",")) {
+                String trimmed = part.trim();
+                if (!trimmed.isEmpty() && !merged.contains(trimmed)) merged.add(trimmed);
+            }
+        }
+        for (Object item : additions) {
+            String value = String.valueOf(item).trim();
+            if (!value.isEmpty() && !merged.contains(value)) merged.add(value);
+        }
+        return String.join(", ", merged);
+    }
 }

backend/src/main/java/com/dbaagent/service/codescan/CodeSuggestionApplier.java

@@ -1,6 +1,8 @@
 package com.dbaagent.service.codescan;
 
 import com.dbaagent.model.ColumnMetadata;
+import com.dbaagent.model.CompanyKnowledgeEntry;
+import com.dbaagent.model.SchemaDocumentation;
 import com.dbaagent.model.SchemaMetadata;
 import com.dbaagent.model.TableMetadata;
 import com.dbaagent.model.code.CodeKnowledgeSuggestion;
@@ -89,6 +91,69 @@ void dropsColumnSuggestionWhenColumnUnknown() {
         assertTrue(aggregator.aggregate("c1", "j1", List.of(raw), schemaWithBookings()).isEmpty());
     }
 
+    @Test
+    void mergesWithExistingSchemaDocIntent() {
+        SchemaDocumentation existing = SchemaDocumentation.builder()
+            .id("doc-1")
+            .connectionId("c1")
+            .objectType(SchemaDocumentation.DocumentationType.COLUMN)
+            .objectName("status")
+            .parentObject("analytics_db.bookings")
+            .description("Existing lifecycle note.")
+            .build();
+
+        var raw = new CodeKnowledgeExtractor.RawSuggestion();
+        raw.kind = "SCHEMA_DOC";
+        raw.targetTable = "bookings";
+        raw.targetColumn = "status";
+        raw.title = "Booking status";
+        raw.content = "Reservation state machine from code.";
+        raw.confidence = 0.82;
+
+        var out = aggregator.aggregate(
+            "c1",
+            "j1",
+            List.of(raw),
+            schemaWithBookings(),
+            List.of(),
+            List.of(existing)
+        );
+        assertEquals(1, out.size());
+        assertTrue(Boolean.TRUE.equals(out.get(0).getPayload().get("mergedWithExisting")));
+        assertEquals("doc-1", out.get(0).getPayload().get("existingDocId"));
+        assertEquals("Existing lifecycle note.", out.get(0).getPayload().get("existingExcerpt"));
+    }
+
+    @Test
+    void mergesWithExistingKnowledgeEntryByTitle() {
+        CompanyKnowledgeEntry existing = CompanyKnowledgeEntry.builder()
+            .id("entry-1")
+            .connectionId("c1")
+            .title("Refund policy")
+            .entryType(CompanyKnowledgeEntry.EntryType.BUSINESS_RULE)
+            .content("Refunds are allowed within 30 days.")
+            .build();
+
+        var raw = new CodeKnowledgeExtractor.RawSuggestion();
+        raw.kind = "KNOWLEDGE_ENTRY";
+        raw.title = "Refund policy";
+        raw.content = "Partial refunds require manager approval.";
+        raw.confidence = 0.77;
+        raw.entryType = "BUSINESS_RULE";
+
+        var out = aggregator.aggregate(
+            "c1",
+            "j1",
+            List.of(raw),
+            schemaWithBookings(),
+            List.of(existing),
+            List.of()
+        );
+        assertEquals(1, out.size());
+        assertTrue(Boolean.TRUE.equals(out.get(0).getPayload().get("mergedWithExisting")));
+        assertEquals("entry-1", out.get(0).getPayload().get("existingEntryId"));
+    }
+
     private static ColumnMetadata col(String name, String dataType) {
         ColumnMetadata c = new ColumnMetadata();
         c.setName(name);

backend/src/test/java/com/dbaagent/service/codescan/CodeSuggestionAggregatorTest.java

@@ -1,10 +1,12 @@
 package com.dbaagent.service.codescan;
 
+import com.dbaagent.model.CompanyKnowledgeEntry;
 import com.dbaagent.model.DocumentationSource;
 import com.dbaagent.model.SchemaDocumentation;
 import com.dbaagent.model.SchemaMetadata;
 import com.dbaagent.model.code.CodeKnowledgeSuggestion;
 import com.dbaagent.repository.CodeKnowledgeSuggestionRepository;
+import com.dbaagent.repository.CompanyKnowledgeEntryRepository;
 import com.dbaagent.repository.SchemaDocumentationRepository;
 import com.dbaagent.service.CompanyKnowledgeService;
 import com.dbaagent.service.SchemaScannerService;
@@ -33,6 +35,7 @@ class CodeSuggestionApplierTest {
 
     @Mock private CodeKnowledgeSuggestionRepository suggestionRepository;
     @Mock private SchemaDocumentationRepository schemaDocRepository;
+    @Mock private CompanyKnowledgeEntryRepository companyKnowledgeEntryRepository;
     @Mock private CompanyKnowledgeService companyKnowledgeService;
     @Mock private TrainingService trainingService;
     @Mock private SchemaScannerService schemaScannerService;
@@ -44,6 +47,7 @@ void setUp() {
         applier = new CodeSuggestionApplier(
             suggestionRepository,
             schemaDocRepository,
+            companyKnowledgeEntryRepository,
             companyKnowledgeService,
             trainingService,
             schemaScannerService

backend/src/test/java/com/dbaagent/service/codescan/CodeSuggestionApplierTest.java

@@ -1,7 +1,8 @@
 import { useState, useRef, useEffect, useCallback } from 'react'
-import { ArrowUp, Plus, Square, Loader2, Database, Sparkles, Hash, Table2, Clock, AlertCircle } from 'lucide-react'
+import { ArrowUp, Plus, Square, Loader2, Database, Sparkles, Hash, Table2, Clock, AlertCircle, Inbox } from 'lucide-react'
 import { agentChatAPI, withConnectionContext } from '@/lib/api/agentClient'
 import { agentConversationAPI } from '@/lib/api/client'
+import { useCodeScanSuggestions } from '@/lib/hooks/queries'
 import { useAuth } from '@/hooks/useAuth'
 import AgentMarkdown from './AgentMarkdown'
 import { sanitizeAssistantAnswer } from './sanitizeAssistantAnswer'
@@ -62,6 +63,14 @@ export default function AgentChatPanel({ connectionId, connectionName }) {
   const convIdRef = useRef(null)    // backend conversation id (the per-user index row)
   const restoredRef = useRef(false) // guards the persist effect until boot finishes
 
+  const pendingSuggestionsQuery = useCodeScanSuggestions({
+    connectionId,
+    status: 'PENDING',
+    page: 0,
+    size: 1,
+  })
+  const pendingSuggestionCount = pendingSuggestionsQuery.data?.totalElements ?? 0
+
   const boot = useCallback(async ({ fresh = false } = {}) => {
     setBooting(true); setBootError(null); setAuthBlocked(false)
     restoredRef.current = false
@@ -198,6 +207,16 @@ export default function AgentChatPanel({ connectionId, connectionName }) {
         </div>
       </header>
 
+      {pendingSuggestionCount > 0 && (
+        <div className={styles.reviewHint} role="status">
+          <Inbox size={14} aria-hidden="true" />
+          <span>
+            {pendingSuggestionCount} code-scan suggestion{pendingSuggestionCount === 1 ? '' : 's'} ready for optional review in Brain.
+            Chat keeps working — nothing is blocked.
+          </span>
+        </div>
+      )}
+
       <div className={styles.messages} ref={listRef}>
         {booting && (
           <div className={styles.bootState}>

src/components/AgentChat/AgentChatPanel.jsx

@@ -33,6 +33,20 @@
 }
 .connBadge svg { flex-shrink: 0; color: #534AB7; }
 
+.reviewHint {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  margin: 0;
+  padding: 8px 20px;
+  font-size: 12.5px;
+  line-height: 1.45;
+  color: #5b4b1f;
+  background: #fffbeb;
+  border-bottom: 1px solid #fde68a;
+}
+.reviewHint svg { flex-shrink: 0; color: #b45309; }
+
 .newChat {
   display: inline-flex; align-items: center; gap: 5px;
   height: 30px;

src/components/AgentChat/AgentChatPanel.module.css

@@ -600,7 +600,9 @@ export default function CompanyKnowledgePanel({ connectionId }) {
             )}
           </span>
           <span className={styles.stageMeta}>
-            {pendingSuggestionCount > 0 ? `${pendingSuggestionCount} awaiting sign-off` : 'Accept what fits'}
+            {pendingSuggestionCount > 0
+              ? `${pendingSuggestionCount} optional — review anytime`
+              : 'Accept what fits'}
           </span>
         </button>
 
@@ -623,7 +625,7 @@ export default function CompanyKnowledgePanel({ connectionId }) {
       </div>
 
       <p className={styles.flowCaption}>
-        Knowledge flows left to right — nothing reaches the knowledge base until you review and accept it.
+        Review is optional and never blocks Agent chat — approve suggestions when you want them in the knowledge base.
       </p>
 
       {activeTab === 'schema-context' && <SchemaContextTab connectionId={connectionId} />}