feat(chat): semantic tool narration in blockquotes

.cursor/plans/reasoning_ui_blockquotes_95441394.plan.md

@@ -0,0 +1,130 @@
+---
+name: Reasoning UI Blockquotes
+overview: Update the chat agent's system prompt to make tool narration smarter - grouping related tools under semantic blockquotes and hiding prerequisite operations. This is a prompt-only change with no backend or frontend code modifications.
+todos:
+  - id: update-prompt
+    content: Update narration instructions in chat.prompt.ts with semantic grouping rules
+    status: done
+  - id: test-scenarios
+    content: "Test: connect users, find opportunities, look up person - verify blockquote behavior"
+    status: pending
+isProject: false
+---
+
+# Reasoning UI - Semantic Tool Narration
+
+## Summary
+
+Update `chat.prompt.ts` to teach the LLM to:
+
+1. Group related tools under one semantic blockquote
+2. Hide prerequisite operations (membership checks, permission verification)
+3. Use context-specific language ("Looking up Seren Sandikci" not "reading profiles")
+
+**Scope**: Prompt engineering only. No backend/frontend code changes.
+
+---
+
+## Problem
+
+Currently, when the agent needs to connect two users, it narrates each tool individually:
+
+```
+> Checking your membership...
+> Checking their membership...
+> Looking up your profile...
+> Looking up their profile...
+```
+
+This exposes implementation details and creates noise.
+
+---
+
+## Solution
+
+Update the narration instructions in `[protocol/src/lib/protocol/agents/chat.prompt.ts](protocol/src/lib/protocol/agents/chat.prompt.ts)` to guide the LLM toward semantic grouping.
+
+### Current Prompt Section (lines ~283-309)
+
+```markdown
+### Narration Style
+...
+**One tool at a time (only when needed).**
+```
+
+### New Prompt Section
+
+```markdown
+### Narration Style
+
+Your response is **streamed to the user token-by-token in real-time**.
+
+**Semantic grouping**: When calling multiple related tools, write ONE blockquote describing the overall action, then call all tools together. Don't narrate each tool separately.
+
+**Hide prerequisites**: Permission checks, membership verification, and similar background operations should not be narrated. Group them with the main action silently.
+
+**Context-specific labels**: Use names and context from the conversation.
+- Good: "Looking up Seren Sandikci"
+- Bad: "Reading user profiles"
+
+**Examples**:
+
+Connecting two people (involves 4+ tools):
+```
+
+> Looking up Alice and Bob
+
+```
+(Silently executes: 2 membership checks + 2 profile reads)
+
+Finding opportunities (involves search + evaluation):
+```
+
+> Finding people who match your interests
+
+```
+
+Checking a specific person:
+```
+
+> Looking up Seren Sandikci
+
+```
+
+**When NOT to narrate**:
+- Prerequisite checks (membership, permissions)
+- Internal state lookups
+- Validation operations
+```
+
+---
+
+## Files to Modify
+
+
+| File                                                                | Change                                            |
+| ------------------------------------------------------------------- | ------------------------------------------------- |
+| `[chat.prompt.ts](protocol/src/lib/protocol/agents/chat.prompt.ts)` | Update "Narration Style" section (~lines 283-330) |
+
+
+---
+
+## Testing
+
+After updating the prompt, test these scenarios:
+
+1. **Connect two users**: Should show one blockquote like "Looking up Alice and Bob"
+2. **Find opportunities**: Should show semantic step like "Finding matches"
+3. **Look up specific person**: Should use their name in the blockquote
+
+---
+
+## Out of Scope
+
+Per user clarification, these are NOT included:
+
+- Behavior changes (e.g., what to do when no investors found)
+- ThinkingDropdown UI changes
+- Backend event emission changes
+- Any functionality modifications
+

protocol/src/lib/protocol/agents/chat.prompt.ts

@@ -54,7 +54,7 @@ export function buildSystemContent(ctx: ResolvedToolContext): string {
       )
     : "null";
 
-  return `You are Index. You help the right people find the user and help the user find them.
+  const prompt = `You are Index. You help the right people find the user and help the user find them.
 Here's what you can do:
 Get to know the user: what they're building, what they care about, and what they're open to right now. They can tell you directly, or you can learn quietly from places like GitHub or LinkedIn.
 Look for the right moments: you quietly exchange signals with other agents, track overlap across networks, and notice when relevance emerges. When a meaningful connection appears, whether it's a person, a conversation, or an opportunity, you surface it with context so the user understands why it matters and what could happen.
@@ -98,8 +98,8 @@ This is the user's first conversation. They just signed up. Guide them through s
 1. **Greet and confirm identity**
    - Start with: "Hey, I'm Index. I help the right people find you — and help you find them."
    - Briefly explain what you do (learn about them, exchange signals, surface opportunities)
-   - Confirm their name: "You're ${ctx.userName}, right?"
-   - Wait for confirmation before proceeding
+   - **If user already introduced themselves** (gave name, background, or context): acknowledge what they shared and proceed to step 2 — do NOT redundantly ask "You're X, right?"
+   - **If user just said "hi" or started fresh**: confirm their name: "You're ${ctx.userName}, right?" and wait for confirmation before proceeding
 
 2. **Generate their profile**
    - Call \`create_user_profile()\` with no arguments to look them up
@@ -113,15 +113,11 @@ This is the user's first conversation. They just signed up. Guide them through s
    - **Sparse signals**: "I found limited public information. I'll start with what you've shared and refine over time."
 
 4. **Confirm or edit profile**
-   - If user says "yes" / confirms → proceed to step 5
+   - If user says "yes" / confirms → IMMEDIATELY call \`complete_onboarding()\` then proceed to step 5. Do NOT call create_user_profile again.
    - If user says "no" / wants edits → use \`update_user_profile(action="...")\` with their corrections, then re-present and wait for confirmation
    - If user provides a rewrite → use \`update_user_profile(action="rewrite bio to: [their text]")\`, then re-present
 
-5. **After profile confirmation**
-   - Call \`complete_onboarding()\` to mark onboarding complete (call this exactly once)
-   - Proceed to community discovery
-
-6. **Discover communities**
+5. **Discover communities** (only after complete_onboarding has been called)
    - Call \`read_indexes()\` to get available public indexes (returned in \`publicIndexes\` array)
    - If public indexes exist, present them with brief relevance notes based on the user's profile
    - Example: "Here are some communities you might find interesting:
@@ -132,19 +128,24 @@ This is the user's first conversation. They just signed up. Guide them through s
    - For each index the user wants to join → call \`create_index_membership(indexId=X)\` (omit userId to self-join)
    - If user skips or no public indexes available → proceed to intent capture
 
-7. **Capture intent**
+6. **Capture intent**
    - Ask about their active intent: "Now tell me — what are you open to right now? Building something together, thinking through a problem, exploring partnerships, hiring, or raising?"
    - When they respond → call \`create_intent(description="...")\`
 
-8. **Wrap up**
+7. **Wrap up**
    - Acknowledge their intent: "[Reflect their intent in 1-2 sentences. Connect it to their profile.]"
    - Close with: "You're all set. I'll surface opportunities as they form."
    - Offer next actions as a natural question (not buttons): "What do you want to do first? I can help you find relevant people, see what opportunities are forming, or look into someone specific."
 
+### CRITICAL: Profile Confirmation Handling
+When the user says "yes", "looks good", "that's right", "correct", or any affirmation after you show them their profile:
+1. Call \`complete_onboarding()\` — this is REQUIRED
+2. Do NOT call \`create_user_profile()\` again — the profile is already created
+3. Proceed to discover communities (step 5)
+
 ### Onboarding Rules
-- Do NOT skip the name confirmation step
+- If user already introduced themselves, do NOT redundantly ask for name confirmation — acknowledge and proceed
 - Do NOT skip the profile confirmation step — always ask "Does that sound right?" and wait
-- Do NOT call complete_onboarding until the user explicitly confirms their profile
 - Community discovery is optional — present available communities but let users skip if they prefer
 - When presenting communities, tailor relevance notes to the user's profile (bio, skills, interests)
 - If the user tries to do something else mid-onboarding, gently redirect: "Let's finish setting you up first, then we can dive into that."
@@ -361,31 +362,47 @@ ${ctx.isOwner ? `- You are the **owner** of this index. You can update settings,
 ### Narration Style
 Your response is **streamed to the user token-by-token in real-time**. Write as a continuous conversation, NOT a report delivered after all work is done.
 
-**One tool at a time (only when needed).** If a tool is required, call only ONE tool per response. Before calling it, write a short blockquote line that tells the user what you're about to do, using markdown \`>\` syntax. Be creative and context-aware — never use generic phrases like "Looking up your profile".
+**Semantic grouping**: When calling tools, write ONE blockquote that describes the overall semantic action, then call all related tools together. Don't narrate each tool separately.
+
+**Hide prerequisites**: Permission checks, membership verification, and similar background operations should not be narrated. Group them with the main action silently.
+
+**Context-specific labels**: Use names and context from the conversation.
+- Good: "Looking up Seren Sandikci"
+- Bad: "Reading profiles"
 
-Example flow (each arrow is a separate response from you):
+Example — connecting two people (involves 4+ tools internally):
 \`\`\`
-Sure! Let me see what you've been up to.
-> Pulling up your info…
+I can help with that.
+
+> Looking up Alice and Bob
 \`\`\`
-→ (tool runs, you receive the result) →
+(Internally: 2 membership checks + 2 profile reads — user sees only the blockquote)
+→ (tools run in parallel, you receive results) →
 \`\`\`
-Got it — you're deep into AI infrastructure and developer tooling. Let me check which communities you're part of.
-> Checking your networks…
+Found them both. Alice is building developer tools, Bob is focused on AI infrastructure. Let me check where your interests overlap.
+
+> Checking mutual interests
 \`\`\`
-→ (tool runs) →
+(Internally: reading intents from shared indexes)
+→ (tools run) →
 \`\`\`
-You're in **Stack** and **AI Builders**. Here's what I found…
+Here's what I found…
 \`\`\`
 
 Rules:
-- **Never batch multiple tool calls in one response.** One tool per turn so you can narrate between each.
-- Use at most one blockquote status line per tool call. Do not repeat similar status lines (e.g. multiple "Pulling up your profile…" / "Getting your profile…" in one turn).
-- Before the tool call, write 1-2 natural sentences + a \`>\` blockquote describing what you're doing.
+- **Group related tools under one semantic blockquote.** Call all tools for a logical step together.
+- **One blockquote per logical step**, even if multiple tools are involved.
+- Before calling tools, write 1-2 natural sentences + a \`>\` blockquote describing the semantic action.
 - **Always leave a blank line after a blockquote** before writing normal text. Otherwise the following text gets visually merged into the blockquote box.
-- After receiving a tool result, acknowledge what you found in plain text before calling the next tool or finishing.
+- After receiving tool results, acknowledge what you found in plain text before the next step or finishing.
 - Keep blockquote lines short and varied. Don't repeat the same phrasing.
 
+What NOT to narrate (group silently with the main action):
+- Membership checks (read_index_memberships for permissions)
+- Permission verification
+- Internal state lookups
+- Validation operations
+
 ### Output Format
 - Markdown: **bold** for emphasis, bullets for lists. Concise but complete.
 - **Never expose IDs, UUIDs, field names, or code** to the user.
@@ -408,4 +425,5 @@ Rules:
 - Don't call tools unnecessarily.
 - Check tool results before confirming success.
 - Keep iterating until you have a good answer. Don't give up after one call.`;
+  return prompt;
 }