feat: show non-blocking brain-note suggestion bubbles

After an Agent turn, admins see a chip they can open for the excerpt of
the shared note that would be created. Overlaps with existing notes or
business rules merge into one intent; identical intent is not offered.
Propose/accept never blocks the composer.

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

Author: cursoragent

CLAUDE.md

@@ -275,7 +275,9 @@ The Agent tab must not inherit the admin MCP token. `/api/agent/session` mints a
    without `canManageContent` and then 403'd. `get_brain_context` now stamps
    `callerCapabilities`; if `doNotOffer` includes `save_brain_note`, the
    agent must not mention it. MCP `save_brain_note` also fail-closes before
-   the POST.
+   the POST. Admins get a non-blocking suggestion bubble under the answer
+   (`POST /brain/notes/propose` + accept); overlaps with existing notes or
+   business rules merge into one intent.
 
 ### Verification Anti-Patterns (do not repeat)
 

agent/SOUL.md

@@ -28,7 +28,8 @@ After the answer you may offer **one short follow-up question** (a single line)
    `list_connections` carry `callerCapabilities`. If `doNotOffer` lists an
    action — especially `save_brain_note` — do not mention it, do not ask
    "should I save this", and do not render a Yes button. Answering a metric
-   is not a request to persist it. Offering a write that 403s is a broken UX.
+   is not a request to persist it. The product UI may show a non-blocking
+   save bubble after your answer for admins; leave that to the UI.
 
 ## Remembering things — two different places
 

backend/src/main/java/com/dbaagent/controller/BrainController.java

@@ -28,6 +28,9 @@
 import com.dbaagent.service.brain.core.BrainNoteService;
 import com.dbaagent.service.brain.core.BrainTaskService;
 import com.dbaagent.service.brain.core.NoteSuggestionService;
+import com.dbaagent.service.brain.core.BrainNoteProposalService;
+import com.dbaagent.dto.BrainNoteProposalRequest;
+import com.dbaagent.dto.BrainNoteProposalResponse;
 import com.dbaagent.service.QueryExecutorService;
 import com.dbaagent.service.SchemaSnapshotService;
 import com.dbaagent.service.brain.analysis.ColumnDisambiguationService;
@@ -94,6 +97,7 @@ public class BrainController {
     private final BrainNoteService brainNoteService;
     private final BrainTaskService brainTaskService;
     private final NoteSuggestionService noteSuggestionService;
+    private final BrainNoteProposalService brainNoteProposalService;
     private final ColumnProfilingService columnProfilingService;
     private final ColumnDisambiguationService columnDisambiguationService;
     private final SchemaSnapshotService schemaSnapshotService;
@@ -240,6 +244,51 @@ public ResponseEntity<NoteSuggestionDTO.Response> getNoteSuggestions(
         }
     }
 
+    /**
+     * Draft a shared-brain note from an Agent turn. Overlaps with existing notes
+     * or business rules are merged into one intent. Read-only — does not persist.
+     */
+    @PostMapping("/notes/propose")
+    public ResponseEntity<BrainNoteProposalResponse> proposeNoteFromTurn(
+        @org.springframework.web.bind.annotation.RequestBody BrainNoteProposalRequest request
+    ) {
+        try {
+            if (request == null || request.getConnectionId() == null || request.getConnectionId().isBlank()) {
+                return ResponseEntity.badRequest().build();
+            }
+            accessControlService.assertCanReadConnectionContent(request.getConnectionId());
+            return brainNoteProposalService.proposeFromTurn(request)
+                .map(ResponseEntity::ok)
+                .orElseGet(() -> ResponseEntity.noContent().build());
+        } catch (ResponseStatusException e) {
+            throw e;
+        } catch (Exception e) {
+            log.error("Error proposing a brain note from an agent turn", e);
+            return ResponseEntity.internalServerError().build();
+        }
+    }
+
+    /**
+     * Accept a proposed note. If it overlaps existing documentation, update that
+     * row instead of creating a second copy of the same intent.
+     */
+    @PostMapping("/notes/accept")
+    public ResponseEntity<BrainNoteResponse> acceptNote(
+        @org.springframework.web.bind.annotation.RequestBody BrainNoteRequest request
+    ) {
+        try {
+            accessControlService.assertCanManageConnectionContent(request.getConnectionId());
+            return ResponseEntity.ok(brainNoteProposalService.accept(request));
+        } catch (IllegalArgumentException e) {
+            return ResponseEntity.badRequest().build();
+        } catch (ResponseStatusException e) {
+            throw e;
+        } catch (Exception e) {
+            log.error("Error accepting a brain note proposal", e);
+            return ResponseEntity.internalServerError().build();
+        }
+    }
+
     @GetMapping("/notes/{connectionId}")
     public ResponseEntity<List<BrainNoteResponse>> getNotes(
         @PathVariable String connectionId,

backend/src/main/java/com/dbaagent/dto/BrainNoteProposalRequest.java

@@ -0,0 +1,14 @@
+package com.dbaagent.dto;
+
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+public class BrainNoteProposalRequest {
+    private String connectionId;
+    private String question;
+    private String answer;
+}

backend/src/main/java/com/dbaagent/dto/BrainNoteProposalResponse.java

@@ -0,0 +1,24 @@
+package com.dbaagent.dto;
+
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+@Data
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+public class BrainNoteProposalResponse {
+    private String scopeType;
+    private String tableName;
+    private String columnName;
+    private String bubbleLabel;
+    private String excerpt;
+    private String proposedNoteText;
+    /** NEW, MERGE, or SKIP (SKIP is omitted from the Agent UI). */
+    private String action;
+    private String existingNoteId;
+    private String existingNoteText;
+    private String overlapReason;
+}