# Customer Health & Churn Prediction

_AI Features_

Health scores + churn risk for every CUSTOMER and ADVOCATE-stage contact. The same scoring engine as predictive lead scoring, but inverted — measures disengagement signals to flag who's drifting away before they actually churn. Comes with a one-click "Suggest Retention Actions" button for at-risk customers.

## Steps
1. Open the "Customer Health" page in the sidebar (Tools > Insights > Customer Health) for the org-wide dashboard: health distribution chart, at-risk customer table, recently churned list.
2. On any CUSTOMER or ADVOCATE contact, the "Customer Health" card replaces the AI Score card in the right sidebar (those stages are excluded from lead scoring by design).
3. Card shows: health score (0-100, color-coded), churn risk %, confidence, and the top 5 signals weighted by impact ("No email response in 21 days: -15", "Login frequency dropped: -8").
4. For health < 70, an "✨ Suggest Retention Actions" button appears. Click it to make one light-tier model call and get 3-5 specific retention actions (check-in email, QBR, discount offer, etc.) with reasoning + urgency.
5. Nightly worker (2am UTC) refreshes scores for every CUSTOMER/ADVOCATE contact. New customers are scored on demand when first opened.
6. When a customer's churn risk crosses 70 (was below, now above), an automatic notification fires to the contact's assigned owner.

## Tips
- Health scoring is rule-based across email response decay, meeting frequency, payment status, login frequency, NPS/CSAT — no AI on the score itself, only on the retention-action suggestions (one light-tier call per click). Cheap to run at scale on any provider.
- Retention actions are on-demand only (not auto-prefetched) to keep AI cost down. There's a TODO to add an org-level "auto-suggest retention actions for any customer below health 70" toggle — not yet shipped.
- The Customer Health page also lists "Recently Churned" (contacts moved to CHURNED stage in the last 30 days) for retrospective analysis.

## Example
A customer success manager opens the Customer Health page and sees five customers below 50 in the at-risk table. One — a $48K/yr account — flipped from 78 to 42 over two weeks. The signals show "no email response in 28 days, last login 19 days ago, support ticket sentiment turned negative". She clicks Suggest Retention Actions: "Schedule a 30-min QBR this week". She books the meeting, finds out the champion left the buyer's side six weeks ago, and gets reintroduced to the new champion. Account renewed three months later.

## Troubleshooting
- **Customer Health card not showing on a contact** — Contact is not in CUSTOMER or ADVOCATE stage. The lead-scoring AI Score card appears for all other stages instead. Fix: Move the contact to CUSTOMER stage if they're actually a customer. The health card will appear after the next nightly scan or on first open of the contact detail.
- **Score is 100 for everyone** — New CUSTOMER stage with no engagement history yet — the rule engine has nothing negative to subtract from the starting baseline. Fix: Wait. Once you have a few weeks of email / meeting activity logged, the scores will spread out into a useful distribution.
- **Retention actions button does nothing** — You're below health 70 but the button is disabled — usually because the AI usage quota is exhausted, or your role doesn't have ai:use permission. Fix: Check Settings > AI Usage for remaining tokens. Confirm your role has ai:use. Owners/admins always do.

## Plans
Included in every plan. Score computation is free (rule-based). Retention actions use the light tier per click (small per-call cost on any provider). Toggleable per-org under Settings > AI Usage > AI Features (key: churn_prediction).