vibn-frontend/TABLE_STAKES_IMPLEMENTATION.md

Table Stakes Features - Implementation Complete ✅

Overview

Implemented all critical "table stakes" features that were planned but not fully built. These features enable the Collector/Extractor flow to work properly and provide a complete user experience.

Implementation Date: November 17, 2025

---

✅ Features Implemented

1. Auto-Transition Between Phases ✅

What: Automatically transition from collector_mode to extraction_review_mode when the AI confirms the user is ready.

Location: app/api/ai/chat/route.ts

Implementation:

• When collectorHandoff.readyForExtraction === true, the system now automatically updates:
  • currentPhase: 'analyzed'
  • phaseStatus: 'in_progress'
  • phaseData.collectorCompletedAt: <timestamp>
• The next message will be processed in extraction_review_mode

Code Snippet:

// Auto-transition to extraction phase if ready
if (handoff.readyForNextPhase) {
  console.log(`[AI Chat] Auto-transitioning project to extraction phase`);
  await adminDb.collection('projects').doc(projectId).update({
    currentPhase: 'analyzed',
    phaseStatus: 'in_progress',
    'phaseData.collectorCompletedAt': new Date().toISOString(),
  }).catch((error) => {
    console.error('[ai/chat] Failed to transition phase', error);
  });
}

---

2. Extraction Chunking API ✅

What: New endpoint for the Extraction AI to save user-confirmed insights as chunked knowledge items.

Location: app/api/projects/[projectId]/knowledge/chunk-insight/route.ts

Implementation:

• New POST endpoint: /api/projects/[projectId]/knowledge/chunk-insight
• Accepts: content, title, importance, tags, sourceKnowledgeItemId, metadata
• Creates a knowledge_item with sourceType: 'extracted_insight'
• Automatically chunks and embeds the content in AlloyDB
• Returns the new knowledgeItemId for tracking

Usage Example:

// In extraction prompt, AI can now:
POST /api/projects/{projectId}/knowledge/chunk-insight
{
  "content": "Users need role-based access control with Admin, Editor, Viewer roles",
  "title": "RBAC Requirement",
  "importance": "primary",
  "tags": ["security", "authentication", "v1-critical"],
  "sourceKnowledgeItemId": "doc_abc123"
}

Key Features:

• User-confirmed insights only (no automatic extraction)
• Semantic chunking by the Extractor AI
• Metadata tracking (importance, tags, source)
• AlloyDB vector embedding for semantic search

---

3. Visual Checklist UI Component ✅

What: Live-updating checklist showing Collector phase progress in the AI chat sidebar.

Location: components/ai/collector-checklist.tsx

Implementation:

• Real-time Firestore listener on projects/{projectId}/phaseData/phaseHandoffs/collector
• Displays:
  • ✅ Documents uploaded (with count)
  • ✅ GitHub connected (with repo name)
  • ✅ Extension linked
• Progress bar showing completion percentage
• Automatically updates as user completes steps
• Integrated into AI chat page as left sidebar

UI Integration: app/[workspace]/project/[projectId]/v_ai_chat/page.tsx

<div className="flex">
  {/* Left Sidebar - Checklist */}
  <div className="w-80 border-r bg-muted/30 p-4 overflow-y-auto">
    <CollectorChecklist projectId={projectId} />
  </div>

  {/* Main Chat Area */}
  <div className="flex-1 flex flex-col overflow-hidden">
    {/* ... chat UI ... */}
  </div>
</div>

User Experience:

• User sees exactly what they've completed
• AI references the checklist in conversation
• Visual feedback on progress toward extraction phase
• No "ghost state" - checklist persists across sessions

---

4. Extension Project Linking Mechanism ✅

What: Explicit project ID linking so the Cursor Monitor extension reliably sends data to the correct Vibn project.

Locations:

• Backend API: app/api/extension/link-project/route.ts
• Frontend UI: components/extension/project-linker.tsx
• Proxy update: Extension/packages/proxy/server.cjs

Implementation:

Backend:

• POST /api/extension/link-project
  • Links a workspace path to a Vibn project ID
  • Stores mapping in extensionWorkspaceLinks collection
  • Updates project with extensionLinked: true
• GET /api/extension/link-project?workspacePath=...
  • Retrieves the linked project ID for a workspace
  • Used by extension to auto-configure

Proxy Server:

• Updated extractProjectName(headers) function
• Priority order:
  1. x-vibn-project-id header (explicit, highest priority)
  2. Workspace path extraction (fallback)
  3. Environment variable (default)

Frontend UI:

• <ProjectLinker> component for Context page
• Shows project ID (with copy button)
• User enters workspace path
• One-click linking

Usage Flow:

1. User creates project in Vibn
2. User goes to Context page → "Link Extension"
3. User copies project ID
4. User adds project ID to Cursor Monitor extension settings
5. Extension includes x-vibn-project-id: <projectId> header on all requests
6. Proxy logs all activity to the correct project

Benefits:

• No more workspace path guessing
• Multi-project support (user can switch workspaces)
• Reliable data routing
• Extension "just works" after setup

---

⚠️ Not Implemented (Deferred)

5. Phase Scores & Confidence Tracking (Cancelled)

Why: Already implemented in batch-extract/route.ts and extract-from-chat/route.ts.

The system already tracks:

• overallCompletion
• overallConfidence
• phaseScores object

No additional work needed.

---

📊 Impact

Before:

• ❌ User manually triggered extraction (no auto-transition)
• ❌ Extractor had no API to save confirmed insights
• ❌ User had no visual feedback on setup progress
• ❌ Extension used unreliable workspace path heuristic

After:

• ✅ Smooth automatic transition from Collector → Extraction
• ✅ Extractor can collaboratively chunk user-confirmed insights
• ✅ User sees live checklist of setup progress
• ✅ Extension reliably links to correct project via explicit ID

---

🧪 Testing Checklist

Auto-Transition:

• Start new project
• Upload docs, connect GitHub, link extension
• AI asks "Is that everything?"
• User confirms
• AI should automatically switch to extraction mode (check Firestore currentPhase: 'analyzed')

Chunking API:

• Test POST /api/projects/{projectId}/knowledge/chunk-insight
• Verify knowledge_item created with sourceType: 'extracted_insight'
• Verify AlloyDB chunks created
• Test importance levels: primary, supporting, irrelevant

Visual Checklist:

• Open AI Chat page
• Verify checklist appears in left sidebar
• Upload document → checklist updates in real-time
• Connect GitHub → checklist updates
• Refresh page → checklist persists

Extension Linking:

• Go to Context page
• Click "Link Extension"
• Copy project ID
• Enter workspace path and link
• Verify extensionLinked: true in Firestore
• Verify proxy logs include x-vibn-project-id header

---

🚀 Next Steps (Future Enhancements)

Nice to Have:

1. Analytics Dashboard

   • Track average time in collector phase
   • Identify common drop-off points
   • Show completion rates

2. Smart Reminders

   • Email if checklist incomplete after 24hrs
   • In-app "You're 2/3 done!" notifications

3. Mode Transition UI Feedback

   • Show "Transitioning to Extraction phase..." toast
   • Visual phase indicator in UI (badge or timeline)

4. Extension Auto-Discovery

   • Detect workspace path automatically from extension
   • One-click linking (no manual path entry)

---

📁 Files Changed

New Files:

• app/api/projects/[projectId]/knowledge/chunk-insight/route.ts
• components/ai/collector-checklist.tsx
• app/api/extension/link-project/route.ts
• components/extension/project-linker.tsx
• TABLE_STAKES_IMPLEMENTATION.md (this file)

Modified Files:

• app/api/ai/chat/route.ts (auto-transition logic)
• app/[workspace]/project/[projectId]/v_ai_chat/page.tsx (checklist UI integration)
• Extension/packages/proxy/server.cjs (explicit project ID support)

---

✅ Status

All table stakes features are now complete and ready for testing.

The Collector/Extractor flow is fully functional with:

• ✅ Proactive AI guidance
• ✅ Live checklist tracking
• ✅ Automatic phase transitions
• ✅ Collaborative insight chunking
• ✅ Reliable extension linking

Next: User testing and refinement based on real-world usage.