feat: per-user plan exhaustion KPI + clickable insights cards

Show plan exhaustion day on user detail page as a KPI card.
Make plan exhaustion bucket cards on insights clickable to filter
the dashboard members table by exhaustion day range.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: ofershap

src/app/dashboard-client.tsx

@@ -70,8 +70,13 @@ export function DashboardClient({ initialData }: DashboardClientProps) {
   const [preBadgeSortCol, setPreBadgeSortCol] = useState<SortColumn | null>(null);
   const [groups, setGroups] = useState<BillingGroupWithMembers[]>([]);
   const [selectedGroup, setSelectedGroup] = useState("all");
+  const [exhaustionFilter, setExhaustionFilter] = useState<{
+    label: string;
+    emails: Set<string>;
+  } | null>(null);
 
   const groupParam = searchParams.get("group");
+  const exhaustionParam = searchParams.get("exhaustion");
   useEffect(() => {
     fetch("/api/groups")
       .then((r) => r.json())
@@ -82,6 +87,27 @@ export function DashboardClient({ initialData }: DashboardClientProps) {
         }
       })
       .catch(() => {});
+    if (exhaustionParam) {
+      const [minStr, maxStr] = exhaustionParam.split("-");
+      const min = parseInt(minStr ?? "0", 10);
+      const max = parseInt(maxStr ?? "999", 10);
+      fetch("/api/analytics")
+        .then((r) => r.json())
+        .then(
+          (analytics: {
+            planExhaustion?: { users: Array<{ email: string; days_to_exhaust: number }> };
+          }) => {
+            const matching = (analytics.planExhaustion?.users ?? []).filter(
+              (u) => u.days_to_exhaust >= min && u.days_to_exhaust <= max,
+            );
+            setExhaustionFilter({
+              label: `Plan exhausted day ${min}–${max}`,
+              emails: new Set(matching.map((u) => u.email)),
+            });
+          },
+        )
+        .catch(() => {});
+    }
     const saved = localStorage.getItem("dashboard-days");
     if (saved) {
       const parsed = parseInt(saved, 10);
@@ -170,6 +196,9 @@ export function DashboardClient({ initialData }: DashboardClientProps) {
     if (groupEmailSet) {
       users = users.filter((u) => groupEmailSet.has(u.email));
     }
+    if (exhaustionFilter) {
+      users = users.filter((u) => exhaustionFilter.emails.has(u.email));
+    }
     if (search.trim()) {
       const q = search.toLowerCase();
       users = users.filter(
@@ -210,7 +239,7 @@ export function DashboardClient({ initialData }: DashboardClientProps) {
       }
     });
     return sorted;
-  }, [stats.rankedUsers, search, sortCol, sortAsc, groupEmailSet, badgeFilter]);
+  }, [stats.rankedUsers, search, sortCol, sortAsc, groupEmailSet, badgeFilter, exhaustionFilter]);
 
   const searchedUser = useMemo(() => {
     if (!search.trim()) return null;
@@ -236,7 +265,11 @@ export function DashboardClient({ initialData }: DashboardClientProps) {
   }
 
   const timeLabel = formatTimeLabel(days);
-  const isSearching = search.trim().length > 0 || selectedGroup !== "all" || badgeFilter !== null;
+  const isSearching =
+    search.trim().length > 0 ||
+    selectedGroup !== "all" ||
+    badgeFilter !== null ||
+    exhaustionFilter !== null;
   const totalLines = stats.dailyTeamActivity.reduce((s, d) => s + d.total_lines_added, 0);
   const effectiveDays = Math.min(days, stats.cycleDays);
   const cycleStartDate = new Date(stats.cycleStart);
@@ -361,6 +394,20 @@ export function DashboardClient({ initialData }: DashboardClientProps) {
           ))}
         </div>
         {loading && <span className="text-[11px] text-zinc-500 animate-pulse">Updating...</span>}
+        {exhaustionFilter && (
+          <span className="inline-flex items-center gap-1.5 bg-orange-600/20 text-orange-300 rounded-md px-2 py-1 text-[11px] font-medium">
+            {exhaustionFilter.label} ({exhaustionFilter.emails.size})
+            <button
+              onClick={() => {
+                setExhaustionFilter(null);
+                window.history.replaceState({}, "", "/");
+              }}
+              className="hover:text-orange-100 cursor-pointer"
+            >
+              ✕
+            </button>
+          </span>
+        )}
         <div className="ml-auto text-[11px] text-zinc-600">
           {isSearching ? `${filteredUsers.length} / ` : ""}
           {stats.totalMembers} members

src/app/insights/insights-client.tsx

@@ -665,14 +665,17 @@ function PlanExhaustionSection({ data }: { data: PlanExhaustionData }) {
           label="Exceeded"
           value={`${summary.users_exhausted}/${summary.total_active}`}
           sub={`${summary.pct_exhausted}% of active`}
+          href="/?exhaustion=1-999"
         />
         <MiniKpi label="Avg Days" value={summary.avg_days.toFixed(1)} sub="to exceed" />
         <MiniKpi label="Median" value={summary.median_days.toString()} sub="days" />
         <div className="w-px bg-zinc-800 shrink-0 my-1" />
         {buckets.map((b) => (
-          <div
+          <a
             key={b.label}
-            className="bg-zinc-900 border border-zinc-800 rounded-md px-3 py-2 min-w-0 flex-1"
+            href={`/?exhaustion=${b.min}-${b.max}`}
+            className="bg-zinc-900 border border-zinc-800 rounded-md px-3 py-2 min-w-0 flex-1 hover:border-zinc-600 transition-colors cursor-pointer"
+            title={`View users who exhausted plan on ${b.label}`}
           >
             <div className="flex items-center gap-1.5">
               <span
@@ -685,7 +688,7 @@ function PlanExhaustionSection({ data }: { data: PlanExhaustionData }) {
               {b.count}
             </div>
             <div className="text-[10px] text-zinc-400">users</div>
-          </div>
+          </a>
         ))}
       </div>
 
@@ -1039,12 +1042,31 @@ function ChartCard({ title, children }: { title: string; children: React.ReactNo
   );
 }
 
-function MiniKpi({ label, value, sub }: { label: string; value: string; sub?: string }) {
-  return (
-    <div className="bg-zinc-900 border border-zinc-800 rounded-md px-3 py-2 min-w-0 flex-1">
+function MiniKpi({
+  label,
+  value,
+  sub,
+  href,
+}: {
+  label: string;
+  value: string;
+  sub?: string;
+  href?: string;
+}) {
+  const content = (
+    <>
       <div className="text-[10px] text-zinc-400 truncate">{label}</div>
       <div className="text-lg font-bold tracking-tight leading-tight text-zinc-100">{value}</div>
       {sub && <div className="text-[10px] text-zinc-400 truncate">{sub}</div>}
-    </div>
+    </>
   );
+  const className = `bg-zinc-900 border border-zinc-800 rounded-md px-3 py-2 min-w-0 flex-1${href ? " hover:border-zinc-600 transition-colors cursor-pointer" : ""}`;
+  if (href) {
+    return (
+      <a href={href} className={className}>
+        {content}
+      </a>
+    );
+  }
+  return <div className={className}>{content}</div>;
 }

src/app/users/[email]/user-detail-client.tsx

@@ -85,6 +85,11 @@ interface UserStats {
       aiPercent: number;
     } | null;
   } | null;
+  planExhaustion: {
+    daysToExhaust: number;
+    usageBasedReqs: number;
+    cycleDay: number;
+  } | null;
 }
 
 interface UserDetailClientProps {
@@ -265,6 +270,16 @@ export function UserDetailClient({ email, stats }: UserDetailClientProps) {
           }
           href={stats.group ? `/?group=${stats.group.id}` : "/"}
         />
+        <KpiCard
+          label="Plan Exhausted"
+          value={stats.planExhaustion ? `Day ${stats.planExhaustion.daysToExhaust}` : "Not yet"}
+          sub={
+            stats.planExhaustion
+              ? `${stats.planExhaustion.usageBasedReqs.toLocaleString()} extra reqs (day ${stats.planExhaustion.cycleDay} of cycle)`
+              : "Still within included plan"
+          }
+          alert={stats.planExhaustion != null && stats.planExhaustion.daysToExhaust <= 7}
+        />
       </div>
 
       <div className="grid grid-cols-1 lg:grid-cols-2 gap-3">

src/lib/db.ts

@@ -1611,6 +1611,37 @@ export function getUserStats(email: string, days: number = 7) {
     )
     .get(email) as { id: string; name: string } | undefined;
 
+  const cycleRow = db.prepare("SELECT MAX(cycle_start) as cs FROM spending").get() as {
+    cs: string | null;
+  };
+  const cycleStart = cycleRow?.cs;
+  let planExhaustion: { daysToExhaust: number; usageBasedReqs: number; cycleDay: number } | null =
+    null;
+  if (cycleStart) {
+    const exhaustRow = db
+      .prepare(
+        `SELECT CAST(julianday(MIN(du.date)) - julianday(?) + 1 AS INT) as days_to_exhaust,
+            SUM(du.usage_based_reqs) as usage_based_reqs
+         FROM daily_usage du
+         WHERE du.email = ? AND du.date >= ? AND du.usage_based_reqs > 0`,
+      )
+      .get(cycleStart, email, cycleStart) as
+      | {
+          days_to_exhaust: number | null;
+          usage_based_reqs: number | null;
+        }
+      | undefined;
+    if (exhaustRow?.days_to_exhaust != null) {
+      const cycleDayNum =
+        Math.floor((Date.now() - new Date(cycleStart).getTime()) / (24 * 60 * 60 * 1000)) + 1;
+      planExhaustion = {
+        daysToExhaust: exhaustRow.days_to_exhaust,
+        usageBasedReqs: exhaustRow.usage_based_reqs ?? 0,
+        cycleDay: cycleDayNum,
+      };
+    }
+  }
+
   return {
     member,
     spending,
@@ -1632,6 +1663,7 @@ export function getUserStats(email: string, days: number = 7) {
     contextMetrics,
     badges,
     aiAdoption,
+    planExhaustion,
   };
 }