# RateRight Growth Engine - System Intel

Last Updated: Jan 31, 2026 (P0 Auth Bug Fix - Railway Nixpacks)

## P0 BUG FIX (Jan 31, 2026)

### Authentication Broken in Production - FIXED ✅

**Symptom:** Login page shows "Auth not configured" - users cannot log in to the app.

**Root Cause:** Railway's Nixpacks builder was automatically running `npm run build` on every deploy. Since Railway doesn't have VITE_* environment variables, the frontend was rebuilt without Supabase credentials baked in.

**Investigation Path:**
1. Checked Railway env vars - SUPABASE_URL was truncated (missing `.supabase.co`)
2. Realized that didn't matter - frontend VITE_* vars are baked at build time
3. Rebuilt frontend locally with correct `.env` and pushed to `public/`
4. Production still serving wrong files - different JS hashes
5. Discovered `package.json` has build script Railway was running
6. Found `railway.json` wasn't specifying a build command, so Nixpacks auto-ran `npm run build`

**Fix:** Updated `railway.json` to specify explicit build command:
```json
"build": {
  "builder": "NIXPACKS",
  "buildCommand": "npm install"
}
```

This prevents Railway from rebuilding the frontend. Pre-built `public/` files with correct credentials are now used.

**Commits:** `84365b4`, `29ddc2c`, `591b134`
**Files Modified:** `railway.json`, `docs/LESSONS.md`, `public/*` (fresh build)
**Status:** ✅ FIXED - Fresh build deployed with correct credentials

**Additional Finding:** The old `public/` build was missing the Supabase anon key entirely. Even after fixing railway.json, had to rebuild frontend locally and push fresh build.

**Verification Commands:**
```bash
# Check URL in build
grep "memscjotxrzqnhrvnnkc.supabase.co" public/assets/index-*.js

# Check anon key in build
grep "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9" public/assets/index-*.js
```

**Lessons Added to LESSONS.md:**
1. "Railway Nixpacks Auto-Rebuilds Frontend (P0 Jan 31)"
2. "Verify Frontend Build Has Credentials (Jan 31)"

---

## SESSION 35 (Jan 30, 2026)

### Bug Audit & Verification - 12 BUGS FIXED ✅

**Approach:** Systematic verification using Playwright automated testing + git commit analysis.

**Bugs Verified Fixed (via code inspection + Playwright tests):**
- BUG #14: Screenshot capture broken (upload fallback added)
- BUG #15: Voice assistant timeout (5s → 15s)
- BUG #18: Dark mode message contrast (dark: classes added)
- BUG #19: Mobile padding scripts hidden (pb-32 → pb-56)
- BUG #21: Mobile scroll triggers click (positionDelta detection)
- Call Stats Not Counting (used handled_by instead of created_by)
- Call Transcription Stopped (startListening re-enabled)
- Objection Library API (CRUD endpoints created)
- Inbound SMS not updating leads (phone format fix)
- Call Logging Bug (moved to Done)

**New Bugs Fixed This Session:**
- **Call list showing leads without phone numbers** - Added `.not('phone', 'is', null)` filter to callList.js
- **Tony text not showing in inbox** - Root cause: phone lookup not filtering deleted leads

### Phone Lookup Bug - CRITICAL FIX ✅

**Root Cause:** When a lead is soft-deleted and re-created with same phone, Supabase `maybeSingle()` returns PGRST116 error (multiple rows). This was silently ignored, resulting in `lead_id = null`.

**Fix:** Added `.is('deleted_at', null)` to phone lookup queries in:
- `webhooks.js` (inbound SMS)
- `voice.js` (inbound calls)

**Data Fix:** Backfilled 3 orphaned messages to correct leads.

**Commits:** `9677498`, `ca336e0`, `3a1102e`

### Playwright Testing Setup ✅

Added automated testing framework:
- `playwright.config.js` - Config for Desktop Chrome, Mobile iPhone/Android
- `tests/bug-fixes.spec.js` - 13 tests verifying code fixes
- All tests passing

---

## BUG FIX (Jan 30, 2026)

### SMS Duplicate Prevention - DEPLOYED ✅

**Problem:** Leads enrolled in multiple sequences (e.g., Seq A + Seq B) would receive duplicate SMS messages simultaneously - in one case, messages sent 717ms apart.

**Root Cause:** Enrollment check only prevented same-sequence re-enrollment, not enrollment in multiple different sequences.

**Fix (3-Layer Protection):**

1. **Layer 1 - Enrollment Prevention:**
   - Changed enrollment check from 'same sequence' to 'ANY active sequence'
   - Leads can no longer be in multiple sequences simultaneously
   - Added `skipReasons` to enrollment response for feedback

2. **Layer 2 - Send-Time Throttle (Critical):**
   - Before sending any sequence SMS, checks if lead received SMS in last 30 min
   - If yes, reschedules enrollment for 1 hour later instead of sending
   - Clear logging when throttling occurs

3. **Layer 3 - UI Support:**
   - Added `/api/sequences/check-enrollments` endpoint
   - Allows UI to warn before enrollment if leads already have active sequences

**Files Modified:**
- `src/jobs/sequenceProcessor.js` - Added 30-min throttle check
- `src/routes/sequences.js` - ANY sequence enrollment check + check-enrollments endpoint

**Commit:** `03d6a77`
**Deployed:** ✅ Railway auto-deploy confirmed (API healthy, uptime: 461s)

---

## DOCS (Jan 30, 2026)

### Clawdbot Documentation Consolidation - COMPLETE ✅

**Purpose:** Centralize all Clawdbot system references and remove outdated content.

**Changes:**
1. Created `clawd-scripts/SYSTEM-REFERENCE.md` - Complete reference with:
   - All Notion databases with MCP data_source_ids
   - All scripts (core, briefs, self-improvement, data sync)
   - Integration points (Growth Engine, Git sync, Slack, Telegram)
   - Self-improvement protocol
   - Emergency procedures

2. Updated `clawd-scripts/README.md` - Added new scripts sections

3. Added all clawd-scripts to version control (19 files)

4. Archived on VPS: `RIVET-DEV-SYSTEM.md` → `~/clawd/archive/`

5. Deleted: `HEARTBEAT.md` (empty file)

**Commit:** `e990a6a`
**VPS Sync:** Will sync in 30 min via git pull cron

---

## FEATURE (Jan 30, 2026)

### Call Transcripts & AI Summaries UI - DEPLOYED ✅

**Problem:** Call transcripts were captured and analyzed by AI but not viewable after the call was logged.

**Solution:** Two new UI components to surface transcript data:

1. **TranscriptViewer** - Expandable transcript display in communication history
   - AI Summary section (summary, key points, buying signals, next step)
   - Full transcript (scrollable)
   - Copy to clipboard + Play Recording buttons
   - Dark mode support

2. **CallSummariesCard** - Aggregated call history from lead_dossier
   - Collapsible card with call count indicator
   - Color-coded outcome badges (green=interested, red=not interested, blue=callback)
   - Mood emoji, duration, key points, next steps per call

**Location:** Lead Profile page (`/leads/:id`)
- CallSummariesCard: Main content area (after BusinessIntelCard)
- TranscriptViewer: More Details → History section (under each call)

**Commits:** `dd76196`, `a38fbcc`
**Files Added:** `TranscriptViewer.jsx`, `CallSummariesCard.jsx`
**Files Modified:** `LeadProfile.jsx`
**Deployed:** ✅ Railway auto-deploy successful

**Note:** UI features need manual device testing by Michael.

---

## BUG FIX (Jan 30, 2026)

### Messages UI Scroll + Back Button - FIXED ✅

**Problems:**
1. **Scroll triggers click** - Scrolling through message list would accidentally open conversations
2. **Back button navigation** - Browser back went to dashboard instead of message list

**Root Causes:**
1. useLongPress hook's touchmove scroll detection failed during momentum scrolling (scroll container consumed events)
2. URL and state were one-way synced (state→URL only); `setSearchParams` replaces URL without history entry

**Fixes:**
1. Added position-based scroll detection using `getBoundingClientRect()` - checks if element moved >10px on touchend
2. Added bidirectional URL↔state sync with `searchParams` as source of truth; changed all navigation to use `navigate()` for proper history

**Commits:** `4c42810`, `5d0135c`
**Files:** `admin/src/hooks/useLongPress.js`, `admin/src/pages/Messages.jsx`
**Deployed:** ✅ Railway auto-deploy successful

**Note:** Mobile UI fixes require device testing - Michael to verify on phone.

---

## BUG FIX (Jan 29, 2026)

### Call Stats Showing 0 - FIXED ✅

**Problem:** Team performance endpoints showing 0 calls for all users despite Vena having 30+ calls and 266 XP.

**Root Cause:** Queries in `team.js` and `notion.js` used non-existent `created_by` column. Supabase silently returns empty results (no error) when querying missing columns.

**Fix:** Changed all queries to use correct columns (`handled_by`, `user_id`) with OR conditions.
- Commit: `ff07f45`
- Files: `src/routes/team.js` (7 changes), `src/routes/notion.js` (4 changes)

**Verification:**
- `/api/team/performance` → Vena shows 31 calls/week ✓
- `/api/team/:userId/stats` → Full stats + 20 leads visible ✓
- `/api/notion/snapshot` → 33 calls, 25 SMS this week ✓

**Lesson Added:** "Supabase silently returns empty on non-existent columns" in LESSONS.md

---

## CODE AUDIT RESULTS (Jan 22, 2026)

**Full Report:** `docs/CODE-AUDIT-REPORT.md`

### Issues by Severity

| Severity | Count | Status |
|----------|-------|--------|
| CRITICAL | 1 | ⚠️ Fix immediately (4 fixed Jan 22) |
| HIGH | 9 | Fix this week (3 fixed Jan 22) |
| MEDIUM | 18 | Fix within 2 weeks |
| LOW | 15+ | When convenient |

### Top 5 Critical/High Issues

1. ~~**Route Shadowing Bug** - `src/routes/leads.js`~~ ✅ FIXED Jan 22
   - `/api/leads/search` and `/api/leads/assignments` never reached (shadowed by `:id`)
   - Fix: Moved specific routes before parameterized routes
   - Commit: ac43870

2. **Hardcoded API Key Fallback** - `src/routes/jobs.js:13`
   - Default key if env var not set = security risk
   - Fix: Remove fallback, require env var
   - Time: 15 min

3. ~~**Missing FK Indexes** - 5 tables~~ ✅ FIXED Jan 22
   - `lead_notes`, `conversions`, `sequence_steps`, `sequence_enrollments`, `voicemail_drops`
   - Fix: Created 10 indexes via migration
   - Migration: `20260122073239_fk_indexes.sql`

4. ~~**user_id Type Inconsistency** - Database~~ ✅ FIXED Jan 22
   - `rep_weekly_snapshots` and `call_quality_scores` use TEXT instead of UUID
   - Fix: Fixed at source - tables created with UUID from start
   - Migration: `20260122074416_rep_performance_tables.sql`

5. ~~**Unprotected Tracking Endpoints** - `src/index.js`~~ ✅ FIXED Jan 22
   - `/api/frontend/*` and `/api/intelligence/*` have no rate limiting
   - Fix: Added rate limiting to tracking endpoints
   - Commit: (Tracking Security fix)

### Audit Scores

| Category | Score |
|----------|-------|
| Architecture | 8/10 |
| Database | 7.2/10 |
| API Design | 7.5/10 |
| Features | 8.5/10 |
| Security | 6/10 |
| Code Quality | 7/10 |

### Estimated Fix Times

- Critical fixes: ~3-4 hours
- High priority: ~10 hours
- Medium priority: ~29 hours

---

## FUTURE: Self-Healing Ops Brain

**Plan:** `docs/self-healing-ops-plan.md`
**Status:** Plan Ready (Build in Month 2-3)
**Effort:** 45-65 hours
**AI Cost:** ~$20-40/mo

Autonomous ops system that detects problems, diagnoses root cause, fixes automatically, verifies, and learns. Features:
- 6 specialized agents (Infra, Data, API, UX, Cost, Security)
- 50+ SOP runbooks (machine-executable)
- GPT-4o-mini for diagnosis, rules for execution
- Decision engine with confidence scoring
- Daily ops report to Slack
- Never auto-fixes: billing, security, schema, user data

---

## RECENT UPDATES (Jan 25, 2026)

### Session 30: Messages Hub Phase 1 & 2 - COMPLETE

**Phase 1 - 3 Features:**

#### 1. Add to Sequence Button ✅
- Purple "📋 Sequence" button on conversation cards
- Dropdown fetches available sequences from `/api/sequences`
- Shows "(Enrolled)" badge for already-enrolled sequences
- Toast confirmation: `✓ Enrolled in "[sequence name]"` (3 sec)
- File: `admin/src/components/inbox/EnhancedConversationCard.jsx`

#### 2. Action Button Tooltips ✅
- Tooltips on all conversation action buttons
- "Add to sequence – start automated follow-up"
- "Archive conversation – mark as handled"
- "Start automated follow-up sequence"
- "Dismiss this suggestion"
- Using Radix UI Tooltip with asChild pattern

#### 3. Filter Tabs with Emoji Labels ✅
- 🔥 Hot (priority 70+, needs reply)
- ⏳ Reply Needed (inbound last, unread)
- 📤 Awaiting Reply (outbound last, 24h+)
- 💰 Buying Intent (buying signals detected)
- 📁 Archived (handled conversations)
- File: `admin/src/components/inbox/InboxFilterTabs.jsx`

**Phase 2 - 2 Features:**

#### 4. Archive/Unarchive Flow ✅
- Archive button (✓) marks conversation as handled
- Archived conversations appear in 📁 Archived filter
- Unarchive button returns conversation to inbox
- Conversations reappear in correct filter based on state
- Commit: `2b86987`

#### 5. Enhanced Conversation Header ✅
- Trade badge (from lead.metadata.trade)
- Location badge (from lead.metadata.location)
- Last call: date + outcome with color coding (green/red/gray)
- "No calls yet" for leads without call history
- Active sequences with step progress badges (Step X/Y)
- File: `admin/src/components/inbox/LeadCardPreview.jsx`
- Commit: `79f9dea`

**Sidebar Nav Fix (Tailwind v4):**
- Changed `space-y-*` to `flex flex-col gap-4` for proper spacing
- Removed unnecessary wrapper divs around NavLink elements
- Radix Tooltip doesn't render DOM, so NavLink is direct flex child
- Commits: `fbbb582`, `46b0254`

**Lessons Added:**
- Tailwind v4: Use `gap-*` not `space-y-*` for flex containers
- Flex Gap: Remove wrapper divs for gap to work correctly

---

## RECENT UPDATES (Jan 22, 2026)

### Session 29: UI Polish - Dark Mode + Skeleton Loading - COMPLETE

**From UI Audit Plan:** `docs/ui-audit-plan.md`

**Dark Mode Implementation:**
- Enabled Tailwind CSS dark mode via `darkMode: 'class'`
- Created `ThemeContext.jsx` with light/dark/system modes + localStorage persistence
- Created `ThemeToggle.jsx` component with sun/moon/monitor icons
- Added `:root.dark` CSS variable overrides for all custom colors
- Updated App.jsx, BottomNav, CommandPalette, ShortcutHelp, Toaster with dark classes
- Added theme toggle to More.jsx settings section (mobile) and sidebar (desktop)

**Skeleton Loading Enhancements:**
- Added `SkeletonMessages` component matching Messages page layout
- Added `SkeletonLeadProfile` component matching LeadProfile page layout
- Updated Messages.jsx to use skeleton instead of spinner
- Updated LeadProfile.jsx to use skeleton instead of spinner
- All existing skeletons updated with dark mode support

**Files Modified:**
- `admin/tailwind.config.js` - Added `darkMode: 'class'`
- `admin/src/context/ThemeContext.jsx` - NEW: Theme state management
- `admin/src/components/ui/ThemeToggle.jsx` - NEW: Toggle button
- `admin/src/components/ui/Toaster.jsx` - Uses theme from context
- `admin/src/components/ui/Skeleton.jsx` - Added SkeletonMessages, SkeletonLeadProfile
- `admin/src/index.css` - Dark mode CSS variable overrides
- `admin/src/App.jsx` - ThemeProvider wrapper + dark classes
- `admin/src/components/BottomNav.jsx` - Dark mode support
- `admin/src/components/CommandPalette.jsx` - Dark mode support
- `admin/src/components/ShortcutHelp.jsx` - Dark mode support
- `admin/src/pages/More.jsx` - Theme toggle in settings
- `admin/src/pages/Messages.jsx` - Skeleton loading
- `admin/src/pages/LeadProfile.jsx` - Skeleton loading

**Expected Impact:**
- User preference persistence across sessions
- System preference detection for auto dark mode
- Reduced perceived loading time with shape-matching skeletons
- Better eye comfort in low-light environments

---

### Session 28: Micro-Optimisation Plan - COMPLETE

**Full Plan:** `docs/micro-optimisation-plan.md`

**43 optimizations across 6 phases - ALL COMPLETE:**

| Phase | Items | Focus | Status |
|-------|-------|-------|--------|
| 1. Critical Fixes | 1-5 | Unbounded queries, indexes, O(N²) fix, WebSocket reconnect, XP atomic | ✅ |
| 2. Performance Quick Wins | 6-10 | React.memo, useCallback, copy delays, React Query | ✅ |
| 3. API Efficiency | 11-14 | N+1 fixes, query parallelization, caching | ✅ |
| 4. Database Optimization | 15-17 | SELECT * fixes, Full-Text Search, metadata denormalization | ✅ |
| 5. UX Polish | 18-22 | Skeleton loaders, optimistic updates, focus trap, ARIA | ✅ |
| 6. Reliability | 23-26 | Promise.allSettled, retry logic, Map cleanup | ✅ |

**Key Improvements:**

| Category | Before | After |
|----------|--------|-------|
| Dashboard queries | Unbounded | `.limit(10000)` |
| Call list ranking | O(N²) callbacks | O(1) Map lookup |
| WebSocket drops | No reconnect | 3x retry with backoff |
| Search performance | LIKE `%term%` | Full-Text Search GIN |
| Outcome/duration access | `metadata->>` JSONB | Top-level indexed columns |
| Parallel query failures | All-or-nothing | Graceful partial (allSettled) |
| SMS job failures | Immediate fail | 3 retries (1m, 5m, 15m backoff) |
| Alert Map memory | Never cleaned | Hourly cleanup interval |

**Database Migrations Applied:**
- `20260122081452_micro_optimisation_indexes.sql` - 7 performance indexes
- `20260122082559_xp_atomic_increment.sql` - Race condition fix
- `20260122200300_fulltext_search_leads.sql` - tsvector + GIN index
- `20260122200500_denormalize_comm_metadata.sql` - outcome/duration columns

**Files Modified (Backend):**
- `src/routes/dashboard.js` - Query limits + Promise.allSettled
- `src/routes/callList.js` - Use denormalized columns
- `src/routes/analytics.js` - Use denormalized columns
- `src/routes/leads.js` - Full-Text Search
- `src/routes/calls.js` - Write to denormalized columns
- `src/routes/ai.js` - Promise.allSettled for intel
- `src/routes/sequences.js` - N+1 fix
- `src/routes/voice.js` - N+1 fix (3→1 query)
- `src/routes/manager.js` - Use denormalized columns
- `src/services/learning.js` - Promise.allSettled + parallel queries
- `src/services/callListRanker.js` - O(1) callback Map + caching
- `src/services/criticalAlerts.js` - Periodic Map cleanup
- `src/jobs/scheduledSms.js` - Exponential backoff retries

**Files Modified (Frontend):**
- `admin/src/components/StatCard.jsx` - React.memo
- `admin/src/components/LeadCard.jsx` - useCallback + aria-label
- `admin/src/components/CallOutcomeSheet.jsx` - useCallback
- `admin/src/components/LiveCopilot.jsx` - WebSocket reconnect + useCallback
- `admin/src/pages/ManagerDashboard.jsx` - React Query
- `admin/src/components/dealIntelligence/DealIntelDashboard.jsx` - React Query
- `admin/src/components/ui/Skeleton.jsx` - NEW skeleton loader components
- `admin/src/hooks/useFocusTrap.js` - NEW accessibility hook
- `admin/src/pages/Messages.jsx` - Optimistic updates
- `admin/src/components/inbox/NewMessageModal.jsx` - Focus trap
- `admin/src/components/WorkerReferralCapture.jsx` - Phone formatting
- 8+ components - Copy feedback delay 2000ms→500ms

**Expected Impact:**
- Dashboard load: ~3s → <1s
- Call list generation: ~2s → <500ms
- WebSocket reliability: 0% → 100% (3x auto-retry)
- Search: Full table scan → Index-only scan
- Scalability ceiling: 50k → 500k leads

---

### Session 27: Bug Fixes from Code Audit - COMPLETE

**9 fixes from comprehensive code audit:**

| # | Bug | Type | Fix | Status |
|---|-----|------|-----|--------|
| 1 | Route Shadowing | Backend | Moved `/assignments` before `/:id` in leads.js | ✅ LIVE |
| 2 | Voice Assistant timeout | Frontend | SILENCE_TIMEOUT 5s→15s, "Tap to Talk" label | ✅ LIVE |
| 3 | Leads page scroll | Frontend | Bottom padding pb-24→pb-32 | ✅ LIVE |
| 4 | Feature Request fallback | Backend | Slack fallback if DB insert fails | ✅ LIVE |
| 5 | FK Indexes | Migration | 10 indexes on FK columns for performance | ✅ Applied |
| 6 | user_id Type | Schema | Fixed at source - UUID not TEXT | ✅ Applied |
| 7 | Tracking Security | Backend | Rate limiting on `/api/frontend/*` and `/api/intelligence/*` | ✅ LIVE |
| 8 | Rep Performance | Migration | Created `rep_weekly_snapshots` + `call_quality_scores` tables | ✅ Applied |
| 9 | API Timeout Protection | Backend | Added timeouts to all external API calls (OpenAI 60s, Perplexity 45s, Slack 10s, Platform 30s) | ✅ LIVE |

**Files Changed:**
- `src/routes/leads.js` - Route order fix (line 168)
- `admin/src/components/VoiceAssistant.jsx` - Timeout + label fix
- `admin/src/pages/Leads.jsx` - Bottom padding fix
- `src/routes/dev.js` - Slack fallback for bug/feature endpoints
- `src/index.js` - Rate limiting on tracking endpoints
- `src/middleware/rateLimiter.js` - New tracking rate limiter
- `src/utils/fetchWithTimeout.js` - NEW: Timeout wrapper with AbortController
- `src/services/ai.js` - OpenAI client: 60s timeout, 2 retries
- `src/services/perplexity.js` - 45s timeout for research queries
- `src/services/slack.js` - 10s timeout for webhook calls
- `src/services/platformSync.js` - 30s timeout for platform API
- `src/services/qualityAudit.js` - 5s timeout for health checks

**Migrations Applied:**
- `20260122073239_fk_indexes.sql` - 10 FK indexes
- `20260122074416_rep_performance_tables.sql` - Rep performance tables with UUID user_id

**Lessons Added:**
- Route shadowing pattern documented in `docs/LESSONS.md`

---

## RECENT UPDATES (Jan 21, 2026)

### Session 25: Analytics & Scoring Features - COMPLETE

**Three new analytics features built autonomously:**

#### 1. Deal Intelligence
Track objections to outcomes, predict stalling deals, capture loss reasons.

| File | Purpose |
|------|---------|
| `src/services/dealIntelligence.js` | Stall prediction, objection analysis, win/loss recording |
| `src/routes/dealIntelligence.js` | API: `/api/deals/*` endpoints |
| `admin/src/components/dealIntelligence/` | StallWarning, WinLossModal, ObjectionInsightCard, DealIntelDashboard |

**API Endpoints:**
- `GET /api/deals/intelligence/stall/:leadId` - Get stall risk prediction
- `GET /api/deals/intelligence/objection-insights` - Get objection conversion rates
- `POST /api/deals/outcomes` - Record win/loss with reason
- `GET /api/deals/outcomes/stats` - Get win/loss statistics
- `GET /api/deals/dashboard` - Dashboard data

#### 2. Call Analytics Deep
Talk ratio, filler words, questions asked, sentiment analysis, quality scoring.

| File | Purpose |
|------|---------|
| `src/services/callAnalytics.js` | Full call analytics with 0-100 quality score |
| `src/routes/callAnalytics.js` | API: `/api/call-analytics/*` endpoints |
| `admin/src/components/analytics/CallQualityDashboard.jsx` | Team trends dashboard |
| `admin/src/components/analytics/CallQualityCard.jsx` | Individual call quality |

**Metrics Calculated:**
- Talk ratio (rep vs lead speaking time)
- Filler word count (um, uh, like, you know, etc.)
- Questions asked (by both parties)
- Silence percentage
- Words per minute
- Sentiment analysis (positive/neutral/negative)
- Quality score (0-100 weighted)

**API Endpoints:**
- `POST /api/call-analytics/analyze` - Analyze a call transcript
- `GET /api/call-analytics/:communicationId` - Get call analytics
- `GET /api/call-analytics/user/:userId` - Get user's call analytics
- `GET /api/call-analytics/team/trends` - Get team trends

#### 3. AI Call Scoring
GPT-4 powered 6-dimension call scoring with grades A+ to F.

| File | Purpose |
|------|---------|
| `src/services/aiCallScoring.js` | GPT-4 scoring + heuristic fallback |
| `src/routes/callScoring.js` | API: `/api/call-scoring/*` endpoints |
| `admin/src/components/coaching/AICallScoreCard.jsx` | Score display with expand/collapse |

**Scoring Dimensions (weighted):**
- Rapport (15%) - Personal connection, warmth, listening
- Discovery (20%) - Questions asked, needs uncovered
- Value Prop (20%) - Benefits explained, differentiation
- Objection Handling (20%) - Responses to concerns
- Close (15%) - Asked for commitment, next steps
- Professionalism (10%) - Tone, confidence, language

**Grade Scale:**
| Grade | Score | Label |
|-------|-------|-------|
| A+ | 9.5-10 | Exceptional |
| A | 8.5-9.4 | Excellent |
| B+ | 7.5-8.4 | Good |
| B | 6.5-7.4 | Solid |
| C+ | 5.5-6.4 | Needs Work |
| C | 4.5-5.4 | Below Average |
| D | 3.0-4.4 | Poor |
| F | <3.0 | Coaching Required |

**API Endpoints:**
- `POST /api/call-scoring/:communicationId/score` - Score a call
- `GET /api/call-scoring/:communicationId` - Get call score
- `GET /api/call-scoring/user/:userId` - Get user's scores
- `GET /api/call-scoring/team/stats` - Team score statistics
- `GET /api/call-scoring/needs-coaching` - Calls needing review

---

## RECENT UPDATES (Jan 20, 2026)

### Session 24: Lead Assignment System - COMPLETE

**Lead Assignment System for Team Collaboration:**

A scalable lead assignment system that allows reps to claim leads, see who's working what, and auto-releases stale assignments. Designed to scale to 20+ users.

**Database Changes:**
- Extended `user_xp` table with: `email`, `role`, `is_active` columns
- Added `assigned_at` timestamp to `leads` table
- Added `user_id` column to `communications` table

**Backend (NEW):**
| File | Purpose |
|------|---------|
| `src/routes/users.js` | User management API (list, sync, check, map) |
| `src/jobs/releaseStaleAssignments.js` | Auto-release leads after 24h inactivity |

**API Endpoints (NEW):**
| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/api/users` | GET | List all active users with roles |
| `/api/users/me` | GET | Get current user profile |
| `/api/users/map` | GET | Get userId → displayName mapping |
| `/api/leads/:id/claim` | POST | Claim a lead (assign to self) |
| `/api/leads/:id/release` | POST | Release a lead (remove assignment) |
| `/api/leads/assignments` | GET | Get assignment summary stats |
| `/api/call-list?filter=` | GET | Filter: mine, available, all |

**Frontend Changes:**
| Component | Changes |
|-----------|---------|
| `AuthContext.jsx` | Database-driven user lookup, role support, getAssigneeName() |
| `CallList.jsx` | Filter toggle (My Leads / Available / All), assignee badges |
| `LeadProfileHeader.jsx` | Claim/Release buttons, assignee display |
| `client.js` | Added leadsApi.claim(), .release(), .assignments() |

**User Roles:**
- `admin` - Can see all leads, release anyone's leads
- `closer` - Can see available + own leads, release own leads
- `caller` - Same as closer (default)

**Auto-Release Job:**
- Runs hourly
- Releases leads assigned > 24h with no communications activity
- If activity found, refreshes assignment timestamp

**Initial Users Seeded:**
- Tony (tonymccabe53@gmail.com) → role: closer
- Michael (admin@rateright.com.au) → role: admin

**Scaling to 20+ Users:**
To add new users, just INSERT into user_xp:
```sql
INSERT INTO user_xp (user_id, display_name, email, role, level, total_xp, is_active)
SELECT id, 'New User Name', 'email@example.com', 'caller', 1, 0, true
FROM auth.users WHERE email = 'email@example.com';
```

---

### Session 23: Self-Improving Intelligence System Complete

**0.1% Self-Improving Intelligence System:**

A comprehensive self-improving system that tracks user behavior, detects friction, generates AI suggestions, and automatically evolves its own prompts based on outcomes.

**Jobs Created:**
| Job | Schedule | Purpose |
|-----|----------|---------|
| dailyMetricsAggregation | 1am AEST | Aggregates usage_events into intelligence_daily_metrics |
| frictionDetection | Weekly/Manual | Analyzes abandonment, errors, rage clicks, usage trends |
| weeklyExcellenceReport | Monday 7:15am AEST | Weekly friction analysis + AI suggestions |
| monthlyDeepDive | 1st of month 8am AEST | Month-over-month trends + AI strategic insights |
| promptEvolution | 15th of month 9am AEST | Auto-evolves underperforming prompts using AI |
| impactMeasurement | Daily | Measures impact of implemented suggestions |

**Services Created:**
- `src/services/promptManagement.js` - Prompt versioning, A/B testing, performance tracking
- `src/services/criticalAlerts.js` - Real-time Slack alerts for rage clicks, error spikes, abandonment

**Database Tables (via migrations):**
- `usage_events` - Raw user behavior tracking (90-day retention)
- `intelligence_daily_metrics` - Aggregated metrics (kept forever)
- `intelligence_suggestions` - AI-generated improvement suggestions
- `weekly_excellence_reports` - Weekly analysis archives
- `detected_friction` - Friction points found by analysis
- `prompt_versions` - Prompt templates with versioning
- `prompt_outcomes` - Individual prompt usage outcomes

**Frontend:**
- `IntelligenceDashboard.jsx` - System health, friction, suggestions, prompts tabs
- Route: `/intelligence` (accessible from More > Analytics & AI)

**Self-Improvement Loop:**
1. System tracks user behavior (clicks, errors, rage clicks, flow completions)
2. Daily aggregation computes metrics
3. Weekly/Monthly reports analyze patterns and generate AI suggestions
4. When suggestions are implemented, baseline metrics are captured
5. After 7 days, impact is automatically measured
6. Success/failure verdicts update prompt outcome records
7. Monthly prompt evolution analyzes underperforming prompts (<60% success)
8. AI generates improved prompt versions for A/B testing
9. Better-performing versions are promoted, worse ones rolled back

**Files Created:**
- `src/jobs/dailyMetricsAggregation.js`
- `src/jobs/frictionDetection.js`
- `src/jobs/monthlyDeepDive.js`
- `src/jobs/promptEvolution.js`
- `src/jobs/impactMeasurement.js`
- `src/services/promptManagement.js`
- `src/services/criticalAlerts.js`
- `admin/src/pages/IntelligenceDashboard.jsx`
- `admin/src/hooks/useIntelligenceTracking.js`
- `supabase/migrations/20260120084845_intelligence_system_mvp.sql`
- `supabase/migrations/20260120100000_prompt_evolution.sql`

**API Endpoints Tested (Jan 20, 2026):**
| Endpoint | Status | Notes |
|----------|--------|-------|
| POST /api/intelligence/track | ✅ | Single event tracking works |
| POST /api/intelligence/track-batch | ✅ | Batch tracking works |
| GET /api/intelligence/dashboard | ✅ | Returns system health, trends |
| GET /api/intelligence/friction | ✅ | Returns friction points |
| GET /api/intelligence/page-stats | ✅ | Returns per-page analytics |
| GET /api/intelligence/suggestions | ✅ | Returns AI suggestions |
| GET /api/intelligence/metrics | ✅ | Returns daily metrics |

---

### Session 22: Quality Audit Upgrade - COMPLETE (All 4 Phases)

**0.1% Quality Audit System Upgrade:**

Comprehensive monitoring upgrade from basic DB checks to full-stack observability.

**Test Categories (10 total):**
| Category | Weight | Tests | Frequency |
|----------|--------|-------|-----------|
| 🚨 Critical | 3x | 5 | 15-min |
| 🔌 API | 2x | 5 | 15-min |
| 🌐 External | 3x | 7 | Hourly |
| ⚡ Core | 2x | 7 | Daily |
| 🤖 AI | 2x | 6 | Daily |
| 📊 Business | 2x | 6 | Daily |
| 🧪 Journeys | 2x | 5 | Daily |
| ✨ Quality | 1x | 5 | Daily |
| 🚀 Performance | 1x | 5 | Daily |
| 📱 Frontend | 1x | 5 | Daily |

**Frequent Monitoring:**
- 15-min: Critical + API tests (DB health, auth, endpoints)
- Hourly: External services (Twilio, OpenAI, Deepgram, Supabase Realtime)
- Daily 6am: Full audit (all 10 categories)

**Unified Alerting:**
- Failed tests create alerts in `intelligence_alerts` table
- Severity mapping by category (critical→critical, api/external→high, etc.)
- 30-min deduplication cooldown
- Auto-resolution when tests pass again
- Slack notifications for critical/high severity

**Frontend Quality Tracking:**
- Web Vitals: LCP, INP, CLS, FCP, TTFB via `web-vitals` package
- Error tracking: Uncaught errors, React boundary errors, unhandled rejections
- Data flows to `web_vitals` and `frontend_errors` tables

**New API Endpoints:**
- `GET /api/jobs/audit-history?days=7` - Audit trend analysis
- `GET /api/jobs/audit-latest` - Most recent audit result
- `POST /api/analytics/vitals` - Store web vital metrics
- `POST /api/analytics/error` - Store frontend errors
- `GET /api/analytics/vitals/summary` - Vitals summary stats

**Files Created:**
- `src/jobs/frequentAudit.js` - 15-min and hourly scheduler with alerting
- `admin/src/utils/webVitals.js` - Web vitals collection
- `admin/src/utils/errorTracking.js` - Error tracking utility
- `supabase/quality-audit-upgrade-schema.sql` - New tables

**Files Modified:**
- `src/services/qualityAudit.js` - Added business, journeys, frontend test categories
- `src/jobs/index.js` - Added frequent audit intervals
- `src/routes/jobs.js` - Added audit history endpoints
- `src/routes/analytics.js` - Added vitals and error endpoints
- `admin/src/main.jsx` - Initialize vitals + error tracking
- `admin/src/components/ErrorBoundary.jsx` - Report errors to backend

**Migration Required:** `supabase/quality-audit-upgrade-schema.sql`

---

### Session 21: Critical Bug Fixes + Auto-Enrollment

**Bugs Fixed from Slack #growth-alerts:**
1. `leads.name` column doesn't exist - Fixed in 6+ files (use `first_name, last_name`)
2. `leads.trade` column doesn't exist - Fixed (use `metadata.trade`)
3. Phone double-prefix bug (+6161...) - Fixed in webhooks.js
4. Touch scroll triggering click - Fixed in useLongPress.js
5. Sequence toggle missing in PostCallSummarySheet - Added (parity with CallOutcomeSheet)
6. Dossier RLS blocking reads - Fixed with supabaseAdmin
7. Sequences API RLS blocking - Fixed with supabaseAdmin
8. No auto-enroll on no-answer - Added to calls.js backend
9. Dossier duplicate key race condition - Handle error code 23505

**New Features:**
- **Manual Start Sequence Button** - Lead Profile now has "Start SMS Sequence" button
- **Auto-Enroll on No-Answer** - Backend automatically enrolls leads in sequence when call logged as no_answer
- **Better Error Logging** - Sequence enrollment shows which sequence was selected

**Files Modified:**
- `src/routes/calls.js` - Auto-enroll + supabaseAdmin
- `src/routes/sequences.js` - supabaseAdmin for all queries
- `src/routes/dossier.js` - supabaseAdmin + race condition fix
- `src/jobs/sequenceProcessor.js` - Fixed column references
- `src/services/qualityAudit.js` - Fixed leads.name queries
- `admin/src/pages/LeadProfile.jsx` - Start Sequence button
- `admin/src/components/PostCallSummarySheet.jsx` - Sequence toggle
- `admin/src/hooks/useLongPress.js` - Touch scroll fix

**Key Lesson:** RLS blocks ALL backend operations (reads AND writes). Always use `supabaseAdmin || supabase` pattern.

---

### Session 20: SMS Sequences v1 + v2 Complete

**SMS Sequences v1 (Basic):**
- **Sequence Processor Job** - Runs every 60s, respects AEST business hours (8am-6pm)
- **Auto-Pause on Reply** - Sequences stop when lead responds
- **Enrollment API** - Full CRUD + pause/resume/skip/send-now
- **Seed Sequences** - "New Worker Outreach" + "New Contractor Outreach" (4 steps, 7 days)
- **CallOutcomeSheet Toggle** - Auto-enrolls leads on "No Answer" outcome
- **SequenceQueue Component** - View/manage active enrollments on SalesPlaybook
- **Lead Profile Status** - Shows sequence enrollment with pause/resume buttons

**SMS Sequences v2 (Stage-Based + Randomized):**
- **12 Stage-Based Sequences** - 7 worker stages, 5 contractor stages
- **Randomized Timing** - delay_days_min/max for human-like variability
- **Send Windows** - Morning (6-7:30am), lunch (12-1pm), knockoff (3-6pm)
- **Auto-Enrollment on Stage Change** - Leads auto-enroll when stage progresses
- **Opt-Out Toggle** - Leads can opt out of auto-sequences (UI in Lead Profile)
- **Stage-Specific Templates** - 24 templates tailored to each funnel stage

**Files Created/Modified:**
- `src/jobs/sequenceProcessor.js` - Core sequence processor with randomized timing
- `src/routes/sequences.js` - Enrollment API + opt-out endpoints
- `src/services/stageCalculator.js` - Auto-enrollment on stage change
- `admin/src/components/playbook/SequenceQueue.jsx` - Queue UI
- `admin/src/pages/LeadProfile.jsx` - SequenceStatusCard with opt-out toggle

**Migrations:**
- `20260119115108_sequence_v2_enhancements.sql` - stage, lead_type, randomized timing columns
- `20260119115515_seed_stage_sequences_v2.sql` - 12 sequences + 24 templates

**System Status: 100% Ready**
Full sequence automation system deployed and operational.

### Session 19: Playbook System 95% Complete

**Features Built:**
- **Worker Referral Capture UI** - Modal in CallOutcomeSheet for capturing tradies referrals
- **Business Intel Display** - Cards in LeadProfile + CallPrepPage showing pain points, competitors, hiring needs

**Comprehensive Bug Audit + Fixes:**
- Phone validation with error messages in WorkerReferralCapture
- Promise.allSettled for batch operations (partial success supported)
- Rate limiting on /draft-message endpoint
- Database error handling on communications insert
- Array key fixes (content-based keys instead of index)
- Null safety improvements across components

### Session 18: AI Guardrails + Bug Fixes
- **Call briefs & conversation starters** now focus on WORK/BUSINESS topics only
- Personal topics (family, hobbies, trips) only surfaced if lead shared them first
- Addresses feedback: "Personal questions feel too intrusive for leads we don't know"
- Philosophy: "AI guides, humans personalize" - respect professional boundaries
- **Today's Play messages** now appear in chat history (fixed silent DB insert)
- **Today's Play messages** now show in Inbox (fixed category mismatch)
- **Voicemail Drop storage bucket** created (was missing, blocking uploads)

## FEATURE STATUS TRACKER

| Feature | Rating | Status | Last Updated |
|---------|--------|--------|--------------|
| Time-aware sections | Good | Complete | Jan 16 |
| AI wisdom coach | 0.1% | Complete | Jan 16 |
| Today's Mission / Strategy Modal | 0.1% | Complete | Jan 16 |
| Live stats | Good | Complete | Jan 16 |
| Urgent actions | 0.1% | Complete | Jan 16 |
| Recent wins | Good | Complete | Jan 16 |
| Notification bell | Good | Complete | Jan 16 |
| Quick actions | Good | Complete | Jan 16 |
| Streak tracking | Good | Complete | Jan 16 |
| Level/gamification | 0.1% | Complete (user ID fix Jan 18) | Jan 18 |
| Call list smart prioritization | 0.1% | Complete | Jan 16 |
| Click to call | 0.1% | Complete | Jan 16 |
| Live copilot / transcription | Good | Disabled (post-call works) | Jan 18 |
| Objection handling | 0.1% | Complete | Jan 16 |
| Voice commands | 0.1% | Complete | Jan 16 |
| Callbacks | Good | Complete | Jan 16 |
| Call logging | 0.1% | Complete (save bug fixed Jan 18) | Jan 18 |
| Inbound call handling | 0.1% | Complete (outcome logging fixed Jan 18) | Jan 18 |
| Missed call handling | 0.1% | Complete | Jan 16 |
| Voicemail | Good | Complete | Jan 16 |
| Real-time intel during calls | 0.1% | Complete | Jan 16 |
| Objection responses live | 0.1% | Complete | Jan 16 |
| Company intel surfaced | 0.1% | Complete | Jan 16 |
| Person intel surfaced | 0.1% | Complete | Jan 16 |
| Talking points / prompts | Good | Complete | Jan 16 |
| Competitor mentions detection | Basic | Needs Upgrade | - |
| Buying signals detection | 0.1% | Complete | Jan 16 |
| Lead profiles | 0.1% | Complete | Jan 16 |
| Lead scoring / predictive | 0.1% | Complete | Jan 16 |
| Intel briefs | 0.1% | Complete (4hr cache + refresh btn Jan 18) | Jan 18 |
| Perplexity research (company) | 0.1% | Complete | Jan 16 |
| Perplexity research (person) | 0.1% | Complete | Jan 16 |
| Worker → contractor extraction | Good | Complete | Jan 16 |
| Worker referral capture UI | 0.1% | Complete | Jan 19 |
| Business intel display | 0.1% | Complete | Jan 19 |
| Request contact SMS | Good | Complete | Jan 16 |
| Lead notes | Good | Complete | Jan 16 |
| Lead status/pipeline | Good | Complete | Jan 16 |
| Lead tiers | Good | Complete | Jan 16 |
| Lead activity history | Good | Complete | Jan 16 |
| Company intel caching | Good | Complete | Jan 16 |
| Person intel caching | Good | Complete | Jan 16 |
| Intel refresh/staleness | Basic | Needs Upgrade | - |
| Intel search across leads | Planned | Plan Ready | [intel-search-plan.md](intel-search-plan.md) |
| Intel tagging | Planned | Plan Ready | [intel-tagging-plan.md](intel-tagging-plan.md) |
| Competitor intel database | Planned | Plan Ready | [competitor-intel-plan.md](competitor-intel-plan.md) |
| Industry intel / trends | Planned | Plan Ready | [industry-intel-plan.md](industry-intel-plan.md) |
| SMS sending | 0.1% | Complete | Jan 16 |
| SMS templates | Good | Complete | Jan 16 |
| SMS Sequences automation | 0.1% | Complete | Jan 19 |
| Messages Hub | 0.1% | Complete | Jan 17 |
| SMS reply handling | 0.1% | Complete | Jan 16 |
| SMS triage/prioritisation | 0.1% | Complete | Jan 17 |
| SMS sentiment analysis | Basic | Needs Upgrade | - |
| Pattern detection | 0.1% | Complete | Jan 16 |
| Winning patterns storage | Good | Complete | Jan 16 |
| AI insights | 0.1% | Complete | Jan 16 |
| Weekly insights generation | 0.1% | Complete | Jan 16 |
| What's working / not working | Good | Complete | Jan 16 |
| Best time to call analysis | 0.1% | Complete | Jan 16 |
| Best approach analysis | Good | Complete | Jan 16 |
| OpenAI integration | 0.1% | Complete | Jan 16 |
| Perplexity integration | 0.1% | Complete | Jan 16 |
| Deepgram integration | Good | Complete | Jan 16 |
| AI message drafting | Good | Complete | Jan 16 |
| AI post-call summaries | 0.1% | Complete | Jan 16 |
| AI transcript intel extraction | Good | Complete | Jan 16 |
| AI lead prioritisation | 0.1% | Complete | Jan 16 |
| Supabase | 0.1% | Complete | Jan 16 |
| Twilio (SMS) | 0.1% | Complete | Jan 16 |
| Twilio (Voice) | 0.1% | Complete | Jan 16 |
| Slack notifications | 0.1% | Complete | Jan 16 |
| Google Sheets import | Basic | Needs Upgrade | - |
| Authentication | Good | Complete | Jan 16 |
| Error handling | Basic | Needs Upgrade | - |
| Rate limiting | 0.1% | Complete | Jan 16 |
| Logging | Good | Complete | Jan 16 |
| Database schema | Good | Complete | Jan 16 |
| API structure | Good | Complete | Jan 16 |
| Frontend routing | Good | Complete | Jan 16 |
| Mobile responsiveness | Good | Complete | Jan 16 |
| SMS notifications | 0.1% | Complete | Jan 16 |
| Call events | 0.1% | Complete | Jan 16 |
| Dashboard updates | Basic | Needs Upgrade | - |
| Live lead updates | 0.1% | Complete | Jan 16 |
| Call stats | Good | Complete | Jan 16 |
| Conversion tracking | Good | Complete | Jan 16 |
| Pipeline value | 0.1% | Complete | Jan 16 |
| Activity reports | Good | Complete | Jan 16 |
| Team performance | Planned | Plan Ready | [team-performance-plan.md](team-performance-plan.md) |
| Bug report system | Good | Complete | Jan 16 |
| Tooltip system | 0.1% | Complete | Jan 18 |
| Power Features Guide | 0.1% | Complete | Jan 18 |
| Voice assistant | 0.1% | Complete | Jan 16 |
| AI insights widget | 0.1% | Complete | Jan 16 |
| High intent tracking | 0.1% | Complete | Jan 16 |
| Worker referral detection | Good | Complete | Jan 16 |
| Similar wins matching | 0.1% | Complete | Jan 16 |
| Effective responses lookup | 0.1% | Complete | Jan 16 |
| Platform user sync | 0.1% | Complete | Jan 16 |
| Call recording playback | 0.1% | Complete | Jan 18 |
| Manager dashboard | 0.1% | Complete | Jan 18 |
| Power dialer | 0.1% | Complete | Jan 18 |
| XP Duels (Battleground V2) | 0.1% | Complete | Jan 19 |
| Sound Celebrations | 0.1% | Complete | Jan 19 |
| Manager Challenges | 0.1% | Complete | Jan 19 |
| Battleground Simplified UI | 0.1% | Complete | Jan 19 |
| Actionable Playbook (Today's Plays) | 0.1% | Complete | Jan 18 |
| Bulk Personalized Outreach | 0.1% | Complete | Jan 18 |
| Inbound Intel Mining (SMS) | 0.1% | Complete | Jan 18 |
| Inbound Intel Mining (Voicemail) | 0.1% | Complete | Jan 18 |
| Inbound Intel Mining (Calls) | 0.1% | Complete | Jan 18 |
| Voicemail Drop | 0.1% | Complete | Jan 18 |
| AI Sequence Suggestions | 0.1% | Complete | Jan 19 |
| Call List Search | Good | Complete | Jan 19 |
| Ice Breakers UI | 0.1% | Complete | Jan 18 |
| Sales Funnel Panel | 0.1% | Complete | Jan 18 |
| Send to Similar Leads | 0.1% | Complete | Jan 18 |

## SUMMARY

| Rating | Count | % |
|--------|-------|---|
| 0.1% | 64 | 57% |
| Good | 35 | 31% |
| Basic | 6 | 5% |
| Planned | 5 | 4% |
| Missing | 2 | 2% |

**Note:** All previously "Missing" features now have detailed plans ready for implementation.

## PRIORITY QUEUE

1. [x] Call list smart prioritization (Basic → 0.1%) ✅ DONE Jan 16
2. [x] Voice commands (Missing → 0.1%) ✅ DONE Jan 16
3. [x] Live intel during calls (Missing → 0.1%) ✅ DONE Jan 16
4. [x] Buying signals detection (Missing → 0.1%) ✅ DONE Jan 16
5. [x] Rate limiting (Missing → 0.1%) ✅ DONE Jan 16
6. [x] Pipeline value (Missing → 0.1%) ✅ DONE Jan 16
7. [x] Gamification (Basic → 0.1%) ✅ DONE Jan 17
8. [x] Messages Hub (Good → 0.1%) ✅ DONE Jan 17
9. [x] Scripts Command Center (Missing → 0.1%) ✅ DONE Jan 17
10. [x] Messages UI Overhaul (Search, New Message, Done) ✅ DONE Jan 17
11. [x] Pre-Call Briefing 0.1% (AI script + intel prep) ✅ DONE Jan 17
12. [x] Call Recording Playback ✅ DONE Jan 18
13. [x] Manager Dashboard ✅ DONE Jan 18
14. [x] Power Dialer (auto-advance with study timer) ✅ DONE Jan 18
15. [x] **Actionable Playbook** (Today's Plays + Bulk Outreach) ✅ DONE Jan 18
    - Top 3 leads with 3 AI-generated messages each (one-tap send)
    - Bulk personalized outreach to leads in same funnel stage
    - Integrated into Strategy Modal with tabs
16. [~] **STABILITY CHECK** - Deferred, testing in daily use
17. [x] **Inbound Intel Mining** (Auto-extract from SMS/VM/Calls) ✅ DONE Jan 18
    - extractQuickIntel() for lightweight single-message extraction
    - extractInboundIntel() orchestrates quick + full extraction when significant intel found
    - Hooked into: SMS webhook, voicemail transcription, call recordings
    - Auto-extracts: locations, headcount, timelines, objections, questions, decision makers
18. [x] **Voicemail Drop** ⭐ HIGH VALUE ✅ DONE Jan 18
    - Pre-recorded VMs, one-click drop during calls
    - Amber button in TwilioCall with picker modal
    - VoicemailSettings in More → Settings
    - Guide: docs/voicemail-drop-guide.md
19. [ ] **Email Sequences** ⭐ CRITICAL GAP - Plan: docs/email-sequences-plan.md
    - SendGrid integration + templates + sequence builder
    - Multi-step automated outreach cadences
    - Open/click/reply tracking
    - Est: 18-23 hours | Ongoing: $15-50/mo
20. [ ] **Call Analytics Deep** - Plan: docs/call-analytics-plan.md ✅
    - Talk ratio, filler words, questions, AI scoring
    - Gong-like features at no extra cost
    - Est: 8-12 hours | Ongoing: $25-60/mo
21. [x] **PWA Mobile App** - ✅ DONE Jan 18
    - Install prompt (auto-hides after install), offline page
    - Service worker auto-updates, offline indicator
    - Est: 5-8 hours | Ongoing: $0
22. [x] Tooltip System + Power Features Guide ✅ DONE Jan 18
    - Training Wheels toggle in Settings (localStorage)
    - Tooltips on all nav items + major action buttons
    - Power Features Guide with 10 high-value features explained
    - Each feature has how-to-use steps + "Try it now" button
23. [x] **Messages 0.1% Upgrade** (Smart Auto-Reply + Intent Badges) ✅ DONE Jan 18
    - Killed generic auto-replies - only opt-out confirmation remains
    - Intel extraction runs FIRST (before any response decision)
    - High/medium buying signals → NO auto-reply, urgent Slack notification
    - Added 5-minute deduplication to prevent Twilio retry spam (3x messages fixed)
    - Enhanced Slack notifications with buying signal level + CALL NOW buttons
    - Inbox badges: 🔥 HIGH INTENT (red pulsing), ⚡ BUYING SIGNAL (amber), 💬 NEEDS REPLY (blue)
    - Lead Profile shows Recent Intel section (auto-extracted from conversations)
    - Fixed the Liam incident: "we need good men" now = urgent notification, not 3 generic replies
24. [x] **Battleground V2** (XP Duels + Real Gamification) ✅ DONE Jan 19
    - XP Duels, Manager Challenges, Sound Celebrations
    - Simplified UI with tabs
25. [x] **Stability Fixes** ✅ DONE Jan 18
    - Fixed Battleground user ID pattern (17 occurrences in 7 files using wrong header)
    - Added 2-hour cache to Intel Brief and Script Recommendation endpoints
    - Fixed inbound call outcome logging (CallOutcomeSheet now shows after inbound calls)
    - Fixed Twilio device re-registration error (only re-register if not destroyed)

26. [ ] **Sales Tools & Operations APIs** ⭐ MAJOR - Plan: `~/.claude/plans/scalable-purring-kettle.md`
    - **Already Built:** Objections API, Scripts API, SMS Sequences API, Webhooks (inbound)
    - **To Build (8 APIs):**
      1. Sales Playbook API - openers, discovery, value props, closes, voicemails
      2. Trade Tags API - tag CRUD + lead-tag assignments + filtering
      3. Competitor Tracking API - battle cards + intel notes
      4. Bulk Import/Export API - CSV/JSON leads import/export
      5. Apollo Enrichment API - decision-maker data from Apollo.io
      6. Outbound Webhooks API - event notifications to external services
      7. Team & Permissions API - roles (admin/manager/caller) + RBAC
      8. Analytics Export API - custom date ranges + CSV export
    - 7 database migrations, 6 new route files, 3 new services
    - Est: ~8 days implementation

## PARKED QUEUE

Features planned but not prioritized yet. Pull into Priority Queue when ready.

| Feature | Effort | Value | Plan |
|---------|--------|-------|------|
| **Push Notifications** | 2-4 hours | High | [push-notifications-plan.md](push-notifications-plan.md) |
| **AI Call Scoring** | 8-12 hours | High | [ai-call-scoring-plan.md](ai-call-scoring-plan.md) |
| **Deal Intelligence** | 8-12 hours | High | [deal-intelligence-plan.md](deal-intelligence-plan.md) |
| **Weekly Email Report** | 2-4 hours | Medium | [weekly-email-report-plan.md](weekly-email-report-plan.md) |
| **Team Leaderboard Sharing** | 1-2 days | Low | Not needed for 3-person team |

## KNOWN ISSUES

**Full Bug Investigation:** `docs/bugs-investigation-plan.md` (Jan 23, 2026)

| Issue | Impact | Fix |
|-------|--------|-----|
| **Bug #7** - Leads scroll triggers call | HIGH | SwipeableLeadCard needs vertical scroll detection |
| **Bug #18** - Dark mode contrast on CallList | MEDIUM | Add dark: variants to message boxes |
| **Bug #13** - Lead Profile dark mode gaps | MEDIUM | Check nested component dark classes |
| **Bug #19** - Script hidden on mobile CallList | MEDIUM | Test visibility at 384px viewport |
| **Bug #6** - "No active sequences" shown | MEDIUM | Check default filter (due_today vs all) |
| **Bug #14/#8** - Screenshot capture fails | LOW | html2canvas compatibility issue |
| SMS Templates not loading | HIGH | Missing `category` column - run SQL in Supabase |
| Template variables leave blanks | MEDIUM | Frontend shows empty for missing vars |
| Intel not loading (unconfirmed) | MEDIUM | Check OPENAI_API_KEY in Railway |

**Bugs Already Fixed (close in dev_queue):** #15, #11, #10, #9, #5, #4, #3

## LESSONS LEARNED

### What Works
- Parallel agent auditing for codebase review
- Small batches (4-5 fixes) to avoid context loss
- Plan files for context recovery
- Time-aware UI components
- AI contextual coaching (knows user stats)

### What to Avoid
- Big prompts with 8+ fixes at once (context risk)
- Dynamic Tailwind classes (won't compile)
- Hardcoded URLs without env var fallbacks
- Missing error handling on database ops

### Code Patterns to Reuse
- Wisdom system triggers (src/services/wisdom.js)
- Strategy modal pattern (StrategyModal.jsx)
- Perplexity caching (30-day cache in company_intel)
- Realtime subscriptions (RealtimeContext.jsx)
- Call list ranker with weighted factors (src/services/callListRanker.js)
- Priority badge with config function for styling (CallList.jsx)
- Voice command fast-path patterns with GPT fallback (src/services/ai.js)
- Context-aware voice commands via leadId injection

## BUILD HISTORY

### Jan 18, 2026 (Session 17) - Call Outcome & Intel Fixes

- **Call Outcome Save Fix** ⭐ CRITICAL
  - Fixed variable shadowing bug (callDuration declared twice)
  - ReferenceError: "Cannot access 'ne' before initialization"
  - Call outcomes now save properly to database
  - File: admin/src/components/CallOutcomeSheet.jsx

- **Intel Caching (4 hours)**
  - Perplexity intel cached in localStorage per lead
  - Shows "Intel cached Xm ago" indicator
  - "Refresh Intel" button for manual refresh anytime
  - Saves API costs, faster CallPrepPage loads
  - File: admin/src/pages/CallPrepPage.jsx

- **Ice Breakers Sync Fix**
  - Fixed race condition with preloaded intel
  - useEffect now syncs intel when context updates (React batching)
  - Ice Breakers should display during calls now
  - File: admin/src/components/LiveCopilot.jsx

- **Close Confirmation on Outcome Sheet**
  - Warns "Discard call data?" if closing without saving
  - Prevents accidental data loss from X or backdrop click

- **Leaderboard Table Fix**
  - getTodaysCallCount was using non-existent call_log table
  - Changed to use communications table with type='call_outbound'
  - File: src/services/leaderboardService.js

### Jan 18, 2026 (Session 14)

- **Tooltip System (0.1%)**
  - Radix UI Tooltip with TooltipProvider + TooltipProviderWrapper pattern
  - Training Wheels toggle in Settings (localStorage-persisted)
  - TrainingWheelsPrompt shows after 7 days asking to disable
  - Tooltips on all nav items (mobile + desktop)
  - Actionable tips mentioning key features (Power Dialer, AI sparkle, etc.)
  - CSS fadeIn animation with scale transform

- **Power Features Guide (0.1%)** ⭐ TEAM EDUCATION
  - FeatureEducation component in More → Settings (blue gradient button)
  - 10 high-value features with descriptions + step-by-step how-to-use
  - Features: Power Dialer, Voicemail Drop, Call Transcription, Pre-Call Briefing,
    Voice Commands, AI Message Writer, Today's Plays, Smart Call List,
    Buying Signals Detection, Intel Briefs
  - Each feature has "Try it now" button linking to relevant page
  - Helps team discover and learn app capabilities

- **Live Copilot Disabled**
  - Real-time transcription was causing issues (microphone conflicts, timeouts)
  - Set `showCopilot` default to false in CallContext.jsx
  - Twilio post-call transcription still works (both sides captured)
  - Can re-enable later: change useState(false) to useState(true) on line 20

### Jan 18, 2026 (Session 11-12)

- **Voicemail Drop** ⭐ NEW
  - Pre-recorded voicemails with one-click drop during calls
  - Backend: src/routes/voicemail.js (CRUD + drop endpoint)
  - Twilio call modification plays audio then auto-hangs up
  - Frontend: Amber VM button in TwilioCall.jsx with picker modal
  - VoicemailSettings component for recording management
  - Access via: More → Settings → Voicemail Recordings
  - Database: voicemail_recordings + voicemail_drops tables
  - Analytics: Track usage count, callback rates
  - User Guide: docs/voicemail-drop-guide.md
  - Requires: Supabase storage bucket `voicemail-recordings` (public)

### Jan 18, 2026 (Session 8-10)
- **Call Recording Playback**
  - Twilio recordings now stored with URL in communications metadata
  - Proxy endpoint with Basic Auth: GET /api/calls/recording/:communicationId
  - Play/Pause button on call history items in Lead Profile
  - Audio element with proper controls

- **Manager Dashboard**
  - Dark-themed full-screen dashboard at /manager route
  - Team overview: calls, conversions, talk time with period comparison
  - Rep breakdown with individual performance metrics
  - Coaching insights: who needs help, who's crushing it
  - Filter by today/week/month
  - API: GET /api/manager/dashboard, GET /api/manager/rep/:userId

- **Power Dialer**
  - Auto-advance call system with configurable study time
  - PowerDialerContext for timer, queue, and session management
  - Study time options: 30s, 1m, 2m (default), 3m, 5m
  - Call Prep page shows countdown timer with auto-dial at 0
  - Pause/Resume and "Call Now" controls
  - Session stats: calls made, conversions, talk time
  - Progress indicator showing position in queue
  - Auto-advance to next lead after logging outcome
  - **Bug Fix:** Race condition where auto-dial fired immediately on lead change
    - Added timerWasRunningRef to ensure timer actually counted down

### Jan 17, 2026 (Session 7)
- **Pre-Call Briefing 0.1%**
  - Full-screen /call-prep/:leadId page with AI-powered preparation
  - AI script recommendation endpoint: GET /api/scripts/ai-recommend/:leadId
  - GPT-4o-mini analyzes lead context, comms, objections, similar wins
  - Two-panel layout: Intel Brief (left) + Script Recommendation (right)
  - 30-second summary with opening line and talking points
  - Predicted objections with suggested responses
  - Similar wins display for proven patterns
  - All 5 script stages visible with expandable content (opener, discovery, value, objection, close)
  - Script confidence score (high/medium) with AI reasoning
  - Call strategy and customizations per lead
  - Main Call button now navigates to prep page (vs direct dial)
  - Quick Call option to bypass prep for returning to known leads
  - CallPrepPage.jsx (~500 lines), API client update, routing updates
  - Backend: recommendScriptForLead() in ai.js with full context analysis

### Jan 17, 2026 (Session 6)
- **Messages UI Overhaul**
  - SearchBar component with debounced filtering (300ms)
  - NewMessageModal with lead search + recent leads
  - "+ New Message" blue button in Messages header
  - Lead search API endpoint: GET /api/leads/search
  - Handle conversation API: PATCH /api/sms/conversation/:leadId/handle
  - Done action (checkmark) on conversation cards
  - Filters exclude handled conversations (except All)
  - Unknown numbers shown with "Unknown" badge + Create Lead option
  - 2 new components, 2 new API endpoints, 6 modified files
  - Build deployed to public/ folder

### Jan 17, 2026 (Session 5)
- **Messages Mobile Fix** (CRITICAL)
  - Input area was completely blocked on mobile by BottomNav + floating buttons
  - Added `pb-28 md:pb-4` to input container (clears 80px nav + 32px buffer)
  - Changed `100vh` to `100dvh` for dynamic viewport (mobile browser chrome)
  - Hide VoiceAssistant on /inbox route (Messages has its own voice features)
  - Users can now see and use the message input on mobile

### Jan 17, 2026 (Session 4)
- **Desktop UI Fix**
  - Desktop sidebar: Replaced `<a>` tags with `<NavLink>` for SPA navigation
  - Active state styling on current page (blue background)
  - DesktopMoreMenu dropdown component for secondary nav items
  - Added Battleground to desktop nav (was missing)
  - Responsive bottom padding: `pb-24 md:pb-6` on all pages (no wasted space on desktop)
  - Scripts link now clickable in desktop sidebar
  - 15 page files updated for responsive padding

### Jan 17, 2026 (Session 3)
- **Scripts Command Center (0.1%)**
  - Unified Scripts Library with 30 seed scripts (10 SMS, 10 Call, 8 Objection, 2 Email)
  - Brand Guidelines Editor with tone, keywords, banned words/phrases
  - Compliance Checker service with auto-fix suggestions
  - AI guardrails integration - brand voice rules in draftMessage() prompt
  - Compliance Queue for flagged messages (approve/reject/edit workflow)
  - Real-time compliance testing via "Test Message" modal
  - Script cards with compliance status badges (approved/pending/needs_review)
  - Category filters: SMS, Call, Email, Objection with counts
  - Variables support with {first_name}, {sender_name}, etc.
  - Usage tracking and reply rate stats per script
  - Guidelines versioning with change history
  - 4 new tables: brand_guidelines, brand_guideline_history, scripts (extended), compliance_queue
  - Backend: complianceService, scripts routes with 25+ endpoints
  - Frontend: ScriptsCommandCenter.jsx with integrated modals
  - 30 seed scripts with correct fee messaging (Contractors FREE, Workers 9.9%)
  - SMS opt-out only on re-engagement messages (gone_cold, inactive_30d)

### Jan 17, 2026 (Session 2)
- **Messages Hub 0.1%**
  - Renamed Inbox → Messages throughout app
  - Smart filters: Hot, Waiting on Me, Waiting on Them, Buying Signals, Needs Rescue
  - Lead Card Preview at top of conversation thread
  - Long-press context menu on messages (AI Explain, Copy, Extract Phone, Flag)
  - useLongPress hook for touch interactions
  - SmartMessageContent with entity detection (phone, email, date linking)
  - AIExplainModal for AI-powered message analysis
  - MiniLeadPopup on contact long-press
  - Response time tracking (response_time_seconds column)
  - Speed Demon badge integration
  - AI Message Writer with tone selector (Professional/Friendly/Urgent)
  - 3 AI suggestions on modal open with one-tap Send
  - POST /api/ai/explain-message endpoint
  - extracted_entities table for detected data
  - 7 new components, 1 new hook, 6 modified files

### Jan 17, 2026 (Session 1)
- **Gamification Battleground (0.1%)**
  - Full competitive sales team system with 5 major features
  - Live leaderboard (today/week/month/all-time with position tracking)
  - Hall of Fame (permanent records: most calls/day, biggest deal, longest streak)
  - Daily challenges (individual + team with XP rewards)
  - Team Pulse feed (real-time activity: conversions, overtakes, records)
  - Streak Wars (bronze 3d, silver 7d, gold 14d, diamond 30d tiers)
  - Weekly badges (Closer, Dialer, Sniper, Consistent, Early Bird, Night Owl)
  - User stats modal (tap leaderboard row for full profile)
  - Auto-triggers on call log (challenge progress, record checks, pulse events)
  - Weekly badge cron (Friday 3pm AEST)
  - Hourly leaderboard snapshots for position change tracking
  - New nav: Battle icon replaces Prompts in bottom bar
  - Dark gradient theme with purple/amber accents
  - Backend: leaderboardService, challengesService, badgesService
  - Frontend: 6 new gamification components
  - Migration: 5 new tables + user_xp column extensions

### Jan 16, 2026 (Session 8)
- **Platform User Sync (0.1%)**
  - Connects to RateRight Admin API to sync users as leads
  - X-API-Key authentication with configurable endpoint
  - Worker signups → worker leads, Contractor signups → contractor leads
  - Dedupe by email/phone - existing leads get +50 score boost
  - Re-engaged flag and timestamp tracking
  - Manual sync UI in More → Admin Tools
  - Sync recent (24h) or full sync options
  - Config: RATERIGHT_API_URL, RATERIGHT_ADMIN_API_KEY

### Jan 16, 2026 (Session 7)
- **Pipeline Value Tracking (0.1%)**
  - New `estimated_value` field on leads table for deal value tracking
  - Dashboard calculates total/hot/warm pipeline values in real-time
  - New PipelineValue component with green gradient card
  - Shows: total pipeline, converted this month, breakdown by tier (hot/warm)
  - Lead Profile displays and allows editing of deal value
  - Migration: supabase/pipeline-value-migration.sql
  - Pipeline metrics tracked in daily_metrics for historical analysis

### Jan 16, 2026 (Session 6)
- **Rate Limiting (0.1%)**
  - express-rate-limit middleware for all API endpoints
  - Tiered rate limits: global, AI, SMS, webhook, dashboard
  - Cost control: expensive AI ops limited to 5/min (transcribe, research)
  - SMS limited to 100/hour, batch SMS to 10/hour
  - Webhooks: 500/min for Twilio callbacks
  - Write ops: 60/min, deletes: 10/min
  - Import operations: 5/hour
  - User-based limiting for authenticated routes
  - IP-based limiting for public/webhook routes

- **Bug Fix: Call Transcripts**
  - Fixed /api/ai/copilot-session to call generatePostCallSummary()
  - Added extractTranscriptIntel() for intel extraction
  - Now saves to communications table with full metadata
  - Added CallHistoryItem with expandable transcript view
  - Shows AI summary, buying signals, coaching tips

### Jan 16, 2026 (Session 5)
- **Buying Signals Detection (0.1%)**
  - SMS intent classification now includes buying signal detection (high/medium/low)
  - BUYING_SIGNAL_PATTERNS in src/utils/intent.js with detectBuyingSignal()
  - Real-time detection during LiveCopilot calls with green suggestion cards
  - BUYING_SIGNAL_KEYWORDS + BUYING_SIGNAL_RESPONSES for live coaching
  - Post-call AI extraction of buying signals from transcripts
  - Lead scoring boost: high +30, medium +15, low +5 points
  - Call list priority ranking factors in recent buying signals
  - UI badges on lead cards showing buying signal count
  - Buying signals stored in leads.metadata.buying_signals array

### Jan 16, 2026 (Session 4)
- **Live Intel During Calls (0.1%)**
  - New `/api/ai/live-intel/:leadId` endpoint consolidates all intel
  - LiveIntelPanel.jsx component for real-time call display
  - Shows company: industry, size, location, hiring signals
  - Shows person: job title, tenure, previous companies
  - Sales angle prominently displayed for tailored pitch
  - Similar wins from same industry shown
  - Previous objections from this lead flagged
  - Collapsible panel to save screen space

### Jan 16, 2026 (Session 3)
- **Voice Commands (0.1%)**
  - Context-aware commands: "Mark hot" works without saying lead name
  - 8 fast-path regex patterns for quick actions
  - parseCallbackTime() for natural language: "callback tomorrow at 2pm"
  - In-call commands via LiveCopilot: "Hey system, mark hot"
  - frontendAction response for UI callbacks (skip, call, open_sms, refresh)
  - VoiceAssistant shows "Commands for: [Lead Name]" context
  - Intent-specific result styling (colors per action type)

### Jan 16, 2026 (Session 2)
- **Smart Call List Prioritization (0.1%)**
  - AI-powered priority scoring (urgency 35%, intent 25%, timing 20%, pattern 15%, base 5%)
  - "Why This Lead" badge on every card
  - Color-coded by type: urgency (red), intent (green), timing (blue), pattern (purple)
  - Pulsing warnings for stale hot leads (48hrs+) and overdue callbacks
  - Event triggers refresh priority on SMS/call inbound
  - New service: src/services/callListRanker.js

### Jan 16, 2026 (Session 1)
- Built entire Growth Engine CRM from scratch
- Full codebase audit: 8 critical, 10 high, 15 medium issues fixed
- 0.1% Dashboard with AI wisdom coach + Strategy Modal
- Live copilot with transcription + objection handling
- Perplexity integration (company + person research)
- Worker → contractor extraction pipeline
- All features tested and working