From 99b542aff47ba5c69e3e32f702b04a38dcd37740 Mon Sep 17 00:00:00 2001
From: Kris <krzysztof.grajek@googlemail.com>
Date: Thu, 26 Mar 2026 10:30:39 +0100
Subject: [PATCH 1/6] feat: rewrite analytics transcript to chat-bubble style
 matching session page

---
 .../session-detail/SessionTranscript.svelte   | 30 ++++++++++++-------
 1 file changed, 19 insertions(+), 11 deletions(-)

diff --git a/web/src/lib/components/session-detail/SessionTranscript.svelte b/web/src/lib/components/session-detail/SessionTranscript.svelte
index 952cc67..8ac33a5 100644
--- a/web/src/lib/components/session-detail/SessionTranscript.svelte
+++ b/web/src/lib/components/session-detail/SessionTranscript.svelte
@@ -1,6 +1,4 @@
 <script lang="ts">
-	import TranscriptRecord from './TranscriptRecord.svelte';
-
 	interface TranscriptRecordData {
 		record_type: string;
 		timestamp: string | null;
@@ -46,18 +44,16 @@
 
 	function toggleFilter(type: string) {
 		const next = new Set(activeFilters);
-		if (next.has(type)) {
-			next.delete(type);
-		} else {
-			next.add(type);
-		}
+		if (next.has(type)) next.delete(type);
+		else next.add(type);
 		activeFilters = next;
 	}
 
 	let filteredRecords = $derived(
-		activeFilters.size === 0
+		(activeFilters.size === 0
 			? records
 			: records.filter((r) => activeFilters.has(r.record_type))
+		).filter((r) => r.text && r.text.trim().length > 0)
 	);
 </script>
 
@@ -72,7 +68,9 @@
 			{@const isActive = activeFilters.size === 0 || activeFilters.has(type)}
 			<button
 				class="rounded-full border px-2.5 py-1 text-[11px] transition-opacity"
-				style="background: {color}15; color: {color}; border-color: {color}30; opacity: {isActive ? 1 : 0.4}"
+				style="background: {color}15; color: {color}; border-color: {color}30; opacity: {isActive
+					? 1
+					: 0.4}"
 				onclick={() => toggleFilter(type)}
 			>
 				{type} ({count})
@@ -80,9 +78,19 @@
 		{/each}
 	</div>
 
-	<div class="border-border overflow-hidden rounded-lg border">
+	<div class="space-y-2 rounded-lg border border-border p-4">
 		{#each filteredRecords as record}
-			<TranscriptRecord {record} />
+			<div
+				class="max-w-[85%] rounded-lg px-3 py-2 text-xs
+					{record.record_type === 'user'
+					? 'bg-primary/10 mr-auto'
+					: record.record_type === 'assistant'
+						? 'bg-muted ml-auto'
+						: 'bg-muted/50 mr-auto'}"
+			>
+				<div class="text-muted-foreground mb-1 text-[10px] font-medium uppercase">{record.record_type}</div>
+				<div class="whitespace-pre-wrap break-words">{record.text?.trim()}</div>
+			</div>
 		{/each}
 
 		{#if filteredRecords.length === 0}

From 34bd5721dad4ff43fc57d9e52fc381ff564bd0d0 Mon Sep 17 00:00:00 2001
From: Kris <krzysztof.grajek@googlemail.com>
Date: Thu, 26 Mar 2026 10:39:21 +0100
Subject: [PATCH 2/6] feat: collapsible transcript in analytics, add type
 filters to session page transcript

---
 .../session-detail/SessionDetailPanel.svelte  | 41 +++++++++++++------
 .../[slug]/traces/sessions/[id]/+page.svelte  | 29 ++++++++++++-
 2 files changed, 57 insertions(+), 13 deletions(-)

diff --git a/web/src/lib/components/session-detail/SessionDetailPanel.svelte b/web/src/lib/components/session-detail/SessionDetailPanel.svelte
index 2ea9bc1..c179b03 100644
--- a/web/src/lib/components/session-detail/SessionDetailPanel.svelte
+++ b/web/src/lib/components/session-detail/SessionDetailPanel.svelte
@@ -16,7 +16,8 @@
 	let data: any = $state(null);
 	let loading = $state(true);
 	let error = $state('');
-	let showDetail = $state(false);
+	let showCharts = $state(false);
+	let showTranscript = $state(false);
 
 	async function fetchDetail() {
 		loading = true;
@@ -56,21 +57,37 @@
 			costBreakdown={data.cost_breakdown}
 		/>
 
-		{#if !showDetail}
-			<div class="mt-4 text-center">
+		<div class="mt-4 space-y-3">
+			<div class="border-border overflow-hidden rounded-lg border">
 				<button
-					class="bg-muted hover:bg-muted/80 border-border rounded-md border px-5 py-2 text-sm transition-colors"
-					style="color: #4f6ef7"
-					onclick={() => (showDetail = true)}
+					class="hover:bg-muted/40 flex w-full items-center gap-3 px-4 py-3 text-left transition-colors"
+					onclick={() => (showCharts = !showCharts)}
 				>
-					Show detailed charts & transcript ▼
+					<span class="text-muted-foreground/50 text-xs">{showCharts ? '▼' : '▶'}</span>
+					<span class="text-sm font-semibold">Charts</span>
 				</button>
+				{#if showCharts}
+					<div class="border-border border-t px-4 py-4">
+						<SessionCharts perCall={data.per_call} tokenDistribution={data.token_distribution} />
+					</div>
+				{/if}
 			</div>
-		{:else}
-			<div class="mt-4 space-y-6">
-				<SessionCharts perCall={data.per_call} tokenDistribution={data.token_distribution} />
-				<SessionTranscript records={data.transcript_records} />
+
+			<div class="border-border overflow-hidden rounded-lg border">
+				<button
+					class="hover:bg-muted/40 flex w-full items-center gap-3 px-4 py-3 text-left transition-colors"
+					onclick={() => (showTranscript = !showTranscript)}
+				>
+					<span class="text-muted-foreground/50 text-xs">{showTranscript ? '▼' : '▶'}</span>
+					<span class="text-sm font-semibold">Transcript</span>
+					<span class="text-muted-foreground ml-auto text-xs">{data.transcript_records.length} records</span>
+				</button>
+				{#if showTranscript}
+					<div class="border-border border-t px-4 py-4">
+						<SessionTranscript records={data.transcript_records} />
+					</div>
+				{/if}
 			</div>
-		{/if}
+		</div>
 	{/if}
 </div>
diff --git a/web/src/routes/orgs/[slug]/traces/sessions/[id]/+page.svelte b/web/src/routes/orgs/[slug]/traces/sessions/[id]/+page.svelte
index 74bf17a..c653926 100644
--- a/web/src/routes/orgs/[slug]/traces/sessions/[id]/+page.svelte
+++ b/web/src/routes/orgs/[slug]/traces/sessions/[id]/+page.svelte
@@ -65,6 +65,7 @@
 
 	let expandedEvents = $state(new Set<string>());
 	let expandedFiles = $state(new Set<string>());
+	let transcriptFilters = $state(new Set<string>());
 	let sectionsOpen = $state({
 		events: true,
 		files: false,
@@ -195,6 +196,18 @@
 		expandedFiles = next;
 	}
 
+	function toggleTranscriptFilter(role: string) {
+		const next = new Set(transcriptFilters);
+		if (next.has(role)) next.delete(role);
+		else next.add(role);
+		transcriptFilters = next;
+	}
+
+	const ROLE_COLORS: Record<string, string> = {
+		user: '#3ecf8e',
+		assistant: '#a78bfa'
+	};
+
 	interface DiffLine {
 		type: 'add' | 'remove' | 'header';
 		content: string;
@@ -551,6 +564,7 @@
 							<p class="text-muted-foreground px-4 py-4 text-sm">No transcript data.</p>
 						{:else}
 							{@const turns = extractTurns(data.transcript_chunks)}
+							{@const roleCounts = turns.reduce((acc, t) => { acc[t.role] = (acc[t.role] || 0) + 1; return acc; }, {} as Record<string, number>)}
 							{#if turns.length === 0}
 								<div class="divide-border divide-y">
 									{#each data.transcript_chunks as chunk (chunk.chunk_index)}
@@ -558,8 +572,21 @@
 									{/each}
 								</div>
 							{:else}
+								<div class="flex flex-wrap gap-2 px-4 pt-3">
+									{#each Object.entries(roleCounts) as [role, count]}
+										{@const color = ROLE_COLORS[role] || '#6b7594'}
+										{@const isActive = transcriptFilters.size === 0 || transcriptFilters.has(role)}
+										<button
+											class="rounded-full border px-2.5 py-1 text-[11px] transition-opacity"
+											style="background: {color}15; color: {color}; border-color: {color}30; opacity: {isActive ? 1 : 0.4}"
+											onclick={() => toggleTranscriptFilter(role)}
+										>
+											{role} ({count})
+										</button>
+									{/each}
+								</div>
 								<div class="space-y-2 p-4">
-									{#each turns as turn, i}
+									{#each turns.filter(t => transcriptFilters.size === 0 || transcriptFilters.has(t.role)) as turn}
 										<div
 											class="max-w-[85%] rounded-lg px-3 py-2 text-xs
 												{turn.role === 'user'

From 1968f65abe70810a8cab6b841d1e0484e24ef337 Mon Sep 17 00:00:00 2001
From: Kris <krzysztof.grajek@googlemail.com>
Date: Thu, 26 Mar 2026 10:41:20 +0100
Subject: [PATCH 3/6] fix: expand charts by default in analytics session panel

---
 web/src/lib/components/session-detail/SessionDetailPanel.svelte | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/web/src/lib/components/session-detail/SessionDetailPanel.svelte b/web/src/lib/components/session-detail/SessionDetailPanel.svelte
index c179b03..4e79226 100644
--- a/web/src/lib/components/session-detail/SessionDetailPanel.svelte
+++ b/web/src/lib/components/session-detail/SessionDetailPanel.svelte
@@ -16,7 +16,7 @@
 	let data: any = $state(null);
 	let loading = $state(true);
 	let error = $state('');
-	let showCharts = $state(false);
+	let showCharts = $state(true);
 	let showTranscript = $state(false);
 
 	async function fetchDetail() {

From 9e4694d2e460bc4590f28e397aea679605ec3352 Mon Sep 17 00:00:00 2001
From: Kris <krzysztof.grajek@googlemail.com>
Date: Thu, 26 Mar 2026 12:36:05 +0100
Subject: [PATCH 4/6] fix: double-counting cached tokens in cost calculation

input_tokens from Anthropic API includes cache_read and cache_write tokens.
Subtract them to get fresh (non-cached) input before calculating cost,
otherwise cached tokens are charged at both input rate and cache rate.
---
 crates/tracevault-server/src/api/session_detail.rs | 9 ++++++---
 crates/tracevault-server/src/api/stream.rs         | 7 +++++--
 2 files changed, 11 insertions(+), 5 deletions(-)

diff --git a/crates/tracevault-server/src/api/session_detail.rs b/crates/tracevault-server/src/api/session_detail.rs
index 02b76f5..099d0bd 100644
--- a/crates/tracevault-server/src/api/session_detail.rs
+++ b/crates/tracevault-server/src/api/session_detail.rs
@@ -134,7 +134,7 @@ fn parse_record(record: &serde_json::Value, pricing: &ModelPricing) -> Option<Tr
             }
 
             let usage = msg.get("usage").map(|u| {
-                let input = u.get("input_tokens").and_then(|v| v.as_i64()).unwrap_or(0);
+                let total_input = u.get("input_tokens").and_then(|v| v.as_i64()).unwrap_or(0);
                 let output = u.get("output_tokens").and_then(|v| v.as_i64()).unwrap_or(0);
                 let cache_read = u
                     .get("cache_read_input_tokens")
@@ -144,15 +144,18 @@ fn parse_record(record: &serde_json::Value, pricing: &ModelPricing) -> Option<Tr
                     .get("cache_creation_input_tokens")
                     .and_then(|v| v.as_i64())
                     .unwrap_or(0);
+                // input_tokens from the API includes cache_read and cache_write tokens,
+                // so subtract them to get fresh (non-cached) input tokens only
+                let fresh_input = (total_input - cache_read - cache_write).max(0);
                 let cost = pricing::estimate_cost_with_pricing(
                     pricing,
-                    input,
+                    fresh_input,
                     output,
                     cache_read,
                     cache_write,
                 );
                 RecordUsage {
-                    input_tokens: input,
+                    input_tokens: fresh_input,
                     output_tokens: output,
                     cache_read_tokens: cache_read,
                     cache_write_tokens: cache_write,
diff --git a/crates/tracevault-server/src/api/stream.rs b/crates/tracevault-server/src/api/stream.rs
index cf25a02..8566162 100644
--- a/crates/tracevault-server/src/api/stream.rs
+++ b/crates/tracevault-server/src/api/stream.rs
@@ -113,9 +113,12 @@ pub async fn handle_stream(
                 || batch_cache_write > 0;
             if has_tokens {
                 let model_name = detected_model.as_deref().unwrap_or("unknown");
+                // input_tokens from the API includes cache_read and cache_write,
+                // subtract to get fresh (non-cached) input only
+                let fresh_input = (batch_input - batch_cache_read - batch_cache_write).max(0);
                 let batch_cost = crate::pricing::estimate_cost(
                     model_name,
-                    batch_input,
+                    fresh_input,
                     batch_output,
                     batch_cache_read,
                     batch_cache_write,
@@ -134,7 +137,7 @@ pub async fn handle_stream(
                      WHERE id = $1",
                 )
                 .bind(session_db_id)
-                .bind(batch_input)
+                .bind(fresh_input)
                 .bind(batch_output)
                 .bind(batch_cache_read)
                 .bind(batch_cache_write)

From a74c45dfdc905955f455161ac0133d83d71a148a Mon Sep 17 00:00:00 2001
From: Kris <krzysztof.grajek@googlemail.com>
Date: Thu, 26 Mar 2026 12:41:04 +0100
Subject: [PATCH 5/6] fix: use whole dollar format on cumulative cost chart,
 fix double-counted input tokens

---
 .../008_fix_double_counted_input_tokens.sql        | 14 ++++++++++++++
 .../components/session-detail/SessionCharts.svelte |  2 +-
 2 files changed, 15 insertions(+), 1 deletion(-)
 create mode 100644 crates/tracevault-server/migrations/008_fix_double_counted_input_tokens.sql

diff --git a/crates/tracevault-server/migrations/008_fix_double_counted_input_tokens.sql b/crates/tracevault-server/migrations/008_fix_double_counted_input_tokens.sql
new file mode 100644
index 0000000..fe86f95
--- /dev/null
+++ b/crates/tracevault-server/migrations/008_fix_double_counted_input_tokens.sql
@@ -0,0 +1,14 @@
+-- Fix input_tokens that were double-counted (included cache_read + cache_write tokens).
+-- Subtract cache tokens to get fresh (non-cached) input only.
+UPDATE sessions_v2
+SET input_tokens = GREATEST(input_tokens - cache_read_tokens - cache_write_tokens, 0),
+    total_tokens = GREATEST(input_tokens - cache_read_tokens - cache_write_tokens, 0)
+                   + output_tokens + cache_read_tokens + cache_write_tokens
+WHERE input_tokens > 0
+  AND (cache_read_tokens > 0 OR cache_write_tokens > 0);
+
+-- Reset estimated_cost_usd to 0 so it gets recalculated by the pricing sync.
+-- The pricing sync runs on startup and will recalculate all affected sessions.
+UPDATE sessions_v2
+SET estimated_cost_usd = 0
+WHERE estimated_cost_usd > 0;
diff --git a/web/src/lib/components/session-detail/SessionCharts.svelte b/web/src/lib/components/session-detail/SessionCharts.svelte
index b723f72..d4f8c3d 100644
--- a/web/src/lib/components/session-detail/SessionCharts.svelte
+++ b/web/src/lib/components/session-detail/SessionCharts.svelte
@@ -133,7 +133,7 @@
 		scales: {
 			y: {
 				ticks: {
-					callback: (value: string | number) => `$${Number(value).toFixed(3)}`
+					callback: (value: string | number) => `$${Math.round(Number(value))}`
 				}
 			}
 		},

From 519408470f1c057e6d4aa99496056f515dfd2b9a Mon Sep 17 00:00:00 2001
From: Kris <krzysztof.grajek@googlemail.com>
Date: Thu, 26 Mar 2026 12:51:55 +0100
Subject: [PATCH 6/6] feat: add help tooltips with descriptions to all charts
 and stat cards

---
 web/src/lib/components/HelpTip.svelte         | 20 ++++++
 web/src/lib/components/StatCard.svelte        | 16 ++++-
 .../dashboard/CacheSavingsCard.svelte         |  4 +-
 .../dashboard/ComplianceCard.svelte           |  4 +-
 .../lib/components/dashboard/KpiCard.svelte   |  7 +-
 .../dashboard/SessionQualityBar.svelte        |  8 ++-
 .../session-detail/SessionCharts.svelte       |  7 +-
 .../session-detail/SessionSummaryStats.svelte | 70 +++++++++++++++++--
 .../routes/orgs/[slug]/analytics/+page.svelte | 24 ++++---
 .../[slug]/analytics/attribution/+page.svelte | 13 ++--
 .../orgs/[slug]/analytics/cost/+page.svelte   | 15 ++--
 .../orgs/[slug]/analytics/models/+page.svelte |  7 +-
 .../[slug]/analytics/sessions/+page.svelte    | 12 ++--
 .../orgs/[slug]/analytics/tokens/+page.svelte |  8 ++-
 .../routes/orgs/[slug]/dashboard/+page.svelte |  4 ++
 15 files changed, 172 insertions(+), 47 deletions(-)
 create mode 100644 web/src/lib/components/HelpTip.svelte

diff --git a/web/src/lib/components/HelpTip.svelte b/web/src/lib/components/HelpTip.svelte
new file mode 100644
index 0000000..915e9ba
--- /dev/null
+++ b/web/src/lib/components/HelpTip.svelte
@@ -0,0 +1,20 @@
+<script lang="ts">
+	import * as Tooltip from '$lib/components/ui/tooltip/index.js';
+
+	interface Props {
+		text: string;
+	}
+
+	let { text }: Props = $props();
+</script>
+
+<Tooltip.Root>
+	<Tooltip.Trigger>
+		<span class="ml-1 cursor-help text-xs font-normal" style="color: #4f6ef7">?</span>
+	</Tooltip.Trigger>
+	<Tooltip.Portal>
+		<Tooltip.Content class="max-w-xs text-xs">
+			{text}
+		</Tooltip.Content>
+	</Tooltip.Portal>
+</Tooltip.Root>
diff --git a/web/src/lib/components/StatCard.svelte b/web/src/lib/components/StatCard.svelte
index 2da472f..cbac94e 100644
--- a/web/src/lib/components/StatCard.svelte
+++ b/web/src/lib/components/StatCard.svelte
@@ -1,5 +1,6 @@
 <script lang="ts">
 	import type { Component } from 'svelte';
+	import * as Tooltip from '$lib/components/ui/tooltip/index.js';
 
 	interface Props {
 		label: string;
@@ -7,9 +8,10 @@
 		icon: Component;
 		color?: string;
 		secondary?: string;
+		tooltip?: string;
 	}
 
-	let { label, value, icon: Icon, color = '#3b82f6', secondary }: Props = $props();
+	let { label, value, icon: Icon, color = '#3b82f6', secondary, tooltip }: Props = $props();
 </script>
 
 <div class="bg-background rounded-lg border border-border p-4">
@@ -23,6 +25,18 @@
 		<div class="min-w-0">
 			<div class="text-muted-foreground text-[10px] font-semibold uppercase tracking-wider">
 				{label}
+				{#if tooltip}
+					<Tooltip.Root>
+						<Tooltip.Trigger>
+							<span class="ml-1 cursor-help" style="color: #4f6ef7">?</span>
+						</Tooltip.Trigger>
+						<Tooltip.Portal>
+							<Tooltip.Content class="max-w-xs text-xs font-normal normal-case tracking-normal">
+								{tooltip}
+							</Tooltip.Content>
+						</Tooltip.Portal>
+					</Tooltip.Root>
+				{/if}
 			</div>
 			<div class="text-xl font-bold leading-tight">{value}</div>
 			{#if secondary}
diff --git a/web/src/lib/components/dashboard/CacheSavingsCard.svelte b/web/src/lib/components/dashboard/CacheSavingsCard.svelte
index 251d1c6..724e329 100644
--- a/web/src/lib/components/dashboard/CacheSavingsCard.svelte
+++ b/web/src/lib/components/dashboard/CacheSavingsCard.svelte
@@ -1,4 +1,6 @@
 <script lang="ts">
+	import HelpTip from '$lib/components/HelpTip.svelte';
+
 	interface Props {
 		savingsUsd: number;
 		savingsPct: number;
@@ -10,7 +12,7 @@
 
 <a {href} class="bg-background hover:bg-muted/50 block rounded-lg border p-4 transition-colors">
 	<div class="text-muted-foreground text-[11px] font-medium uppercase tracking-wide">
-		Cache Savings
+		Cache Savings<HelpTip text="Money saved by reusing cached prompt tokens instead of re-processing them at full input rate." />
 	</div>
 	<div class="mt-1 text-2xl font-bold text-green-500">
 		${savingsUsd.toLocaleString(undefined, { minimumFractionDigits: 2, maximumFractionDigits: 2 })}
diff --git a/web/src/lib/components/dashboard/ComplianceCard.svelte b/web/src/lib/components/dashboard/ComplianceCard.svelte
index 66b3ebe..68a7e62 100644
--- a/web/src/lib/components/dashboard/ComplianceCard.svelte
+++ b/web/src/lib/components/dashboard/ComplianceCard.svelte
@@ -1,4 +1,6 @@
 <script lang="ts">
+	import HelpTip from '$lib/components/HelpTip.svelte';
+
 	interface Props {
 		score: number;
 		trend: number;
@@ -19,7 +21,7 @@
 
 <a {href} class="bg-background hover:bg-muted/50 block rounded-lg border p-4 transition-colors">
 	<div class="text-muted-foreground text-[11px] font-medium uppercase tracking-wide">
-		Compliance
+		Compliance<HelpTip text="Percentage of sessions with valid cryptographic signatures, ensuring AI-generated code is properly attributed." />
 	</div>
 	<div class="mt-1 text-3xl font-bold {scoreColor}">{score.toFixed(0)}%</div>
 	<div class="mt-0.5 text-xs font-medium {trend >= 0 ? 'text-green-500' : 'text-amber-500'}">
diff --git a/web/src/lib/components/dashboard/KpiCard.svelte b/web/src/lib/components/dashboard/KpiCard.svelte
index 5743b48..fb7d69c 100644
--- a/web/src/lib/components/dashboard/KpiCard.svelte
+++ b/web/src/lib/components/dashboard/KpiCard.svelte
@@ -1,4 +1,6 @@
 <script lang="ts">
+	import HelpTip from '$lib/components/HelpTip.svelte';
+
 	interface Props {
 		label: string;
 		value: string;
@@ -7,6 +9,7 @@
 		sparkline: number[];
 		href: string;
 		color?: string;
+		tooltip?: string;
 	}
 
 	let {
@@ -16,7 +19,8 @@
 		trendLabel,
 		sparkline,
 		href,
-		color = '#3b82f6'
+		color = '#3b82f6',
+		tooltip
 	}: Props = $props();
 
 	const trendPositive = $derived(trend >= 0);
@@ -48,6 +52,7 @@
 >
 	<div class="text-muted-foreground text-[11px] font-medium uppercase tracking-wide">
 		{label}
+		{#if tooltip}<HelpTip text={tooltip} />{/if}
 	</div>
 	<div class="mt-1 text-2xl font-semibold">{value}</div>
 	<div class="mt-0.5 text-xs font-medium {trendPositive ? 'text-green-500' : 'text-amber-500'}">
diff --git a/web/src/lib/components/dashboard/SessionQualityBar.svelte b/web/src/lib/components/dashboard/SessionQualityBar.svelte
index f79b01b..74b2afe 100644
--- a/web/src/lib/components/dashboard/SessionQualityBar.svelte
+++ b/web/src/lib/components/dashboard/SessionQualityBar.svelte
@@ -1,4 +1,6 @@
 <script lang="ts">
+	import HelpTip from '$lib/components/HelpTip.svelte';
+
 	interface Props {
 		avgDurationMs: number;
 		avgToolCalls: number;
@@ -17,15 +19,15 @@
 
 <div class="bg-background flex items-center gap-8 rounded-lg border px-4 py-3">
 	<div>
-		<div class="text-muted-foreground text-[11px] uppercase tracking-wide">Avg Duration</div>
+		<div class="text-muted-foreground text-[11px] uppercase tracking-wide">Avg Duration<HelpTip text="Average wall-clock duration of sessions in this period." /></div>
 		<div class="mt-0.5 text-sm font-semibold">{formatDuration(avgDurationMs)}</div>
 	</div>
 	<div>
-		<div class="text-muted-foreground text-[11px] uppercase tracking-wide">Tool Calls / Session</div>
+		<div class="text-muted-foreground text-[11px] uppercase tracking-wide">Tool Calls / Session<HelpTip text="Average number of tool invocations (file edits, reads, bash commands, etc.) per session." /></div>
 		<div class="mt-0.5 text-sm font-semibold">{avgToolCalls.toFixed(1)}</div>
 	</div>
 	<div>
-		<div class="text-muted-foreground text-[11px] uppercase tracking-wide">Compactions / Session</div>
+		<div class="text-muted-foreground text-[11px] uppercase tracking-wide">Compactions / Session<HelpTip text="Average number of context window compactions per session. High values indicate long sessions that exceeded the context limit." /></div>
 		<div class="mt-0.5 text-sm font-semibold">{avgCompactions.toFixed(1)}</div>
 	</div>
 </div>
diff --git a/web/src/lib/components/session-detail/SessionCharts.svelte b/web/src/lib/components/session-detail/SessionCharts.svelte
index d4f8c3d..1d782c0 100644
--- a/web/src/lib/components/session-detail/SessionCharts.svelte
+++ b/web/src/lib/components/session-detail/SessionCharts.svelte
@@ -1,5 +1,6 @@
 <script lang="ts">
 	import Chart from '$lib/components/chart.svelte';
+	import HelpTip from '$lib/components/HelpTip.svelte';
 
 	interface PerCallUsage {
 		index: number;
@@ -154,21 +155,21 @@
 
 <div class="grid grid-cols-1 gap-4 md:grid-cols-3">
 	<div class="border-border rounded-lg border p-3">
-		<h4 class="mb-2 text-sm font-semibold">Tokens per API Call</h4>
+		<h4 class="mb-2 text-sm font-semibold">Tokens per API Call<HelpTip text="Token breakdown for each API call in the session. Shows how token usage varies across the conversation." /></h4>
 		<div style="height: 200px">
 			<Chart type="bar" data={stackedBarData()} options={stackedOptions} />
 		</div>
 	</div>
 
 	<div class="border-border rounded-lg border p-3">
-		<h4 class="mb-2 text-sm font-semibold">Cumulative Cost</h4>
+		<h4 class="mb-2 text-sm font-semibold">Cumulative Cost<HelpTip text="Running total cost across all API calls. Steep sections indicate expensive calls." /></h4>
 		<div style="height: 200px">
 			<Chart type="line" data={cumulativeCostData()} options={costOptions} />
 		</div>
 	</div>
 
 	<div class="border-border rounded-lg border p-3">
-		<h4 class="mb-2 text-sm font-semibold">Token Distribution</h4>
+		<h4 class="mb-2 text-sm font-semibold">Token Distribution<HelpTip text="Overall proportion of token types. Large cache read slice indicates good cache efficiency." /></h4>
 		<div style="height: 200px">
 			<Chart type="doughnut" data={doughnutData()} options={doughnutOptions} />
 		</div>
diff --git a/web/src/lib/components/session-detail/SessionSummaryStats.svelte b/web/src/lib/components/session-detail/SessionSummaryStats.svelte
index 5b80c19..8079b94 100644
--- a/web/src/lib/components/session-detail/SessionSummaryStats.svelte
+++ b/web/src/lib/components/session-detail/SessionSummaryStats.svelte
@@ -51,22 +51,70 @@
 <div class="space-y-3">
 	<div class="grid grid-cols-2 gap-3 md:grid-cols-3 lg:grid-cols-6">
 		<Card.Root class="p-3">
-			<div class="text-muted-foreground text-xs uppercase tracking-wide">Total Tokens</div>
+			<div class="text-muted-foreground text-xs uppercase tracking-wide">
+				Total Tokens
+				<Tooltip.Root>
+					<Tooltip.Trigger>
+						<span class="ml-1 cursor-help text-xs" style="color: #4f6ef7">?</span>
+					</Tooltip.Trigger>
+					<Tooltip.Portal>
+						<Tooltip.Content class="max-w-xs">
+							Total tokens processed in this session across all API calls.
+						</Tooltip.Content>
+					</Tooltip.Portal>
+				</Tooltip.Root>
+			</div>
 			<div class="mt-1 text-xl font-semibold">{fmtNum(totalTokens)}</div>
 		</Card.Root>
 
 		<Card.Root class="p-3">
-			<div class="text-muted-foreground text-xs uppercase tracking-wide">Total Cost</div>
+			<div class="text-muted-foreground text-xs uppercase tracking-wide">
+				Total Cost
+				<Tooltip.Root>
+					<Tooltip.Trigger>
+						<span class="ml-1 cursor-help text-xs" style="color: #4f6ef7">?</span>
+					</Tooltip.Trigger>
+					<Tooltip.Portal>
+						<Tooltip.Content class="max-w-xs">
+							Estimated session cost based on token usage and model pricing.
+						</Tooltip.Content>
+					</Tooltip.Portal>
+				</Tooltip.Root>
+			</div>
 			<div class="mt-1 text-xl font-semibold" style="color: #3ecf8e">{fmtCost(estimatedCostUsd)}</div>
 		</Card.Root>
 
 		<Card.Root class="p-3">
-			<div class="text-muted-foreground text-xs uppercase tracking-wide">Output Tokens</div>
+			<div class="text-muted-foreground text-xs uppercase tracking-wide">
+				Output Tokens
+				<Tooltip.Root>
+					<Tooltip.Trigger>
+						<span class="ml-1 cursor-help text-xs" style="color: #4f6ef7">?</span>
+					</Tooltip.Trigger>
+					<Tooltip.Portal>
+						<Tooltip.Content class="max-w-xs">
+							Tokens generated by the AI model in this session.
+						</Tooltip.Content>
+					</Tooltip.Portal>
+				</Tooltip.Root>
+			</div>
 			<div class="mt-1 text-xl font-semibold" style="color: #a78bfa">{fmtNum(outputTokens)}</div>
 		</Card.Root>
 
 		<Card.Root class="p-3">
-			<div class="text-muted-foreground text-xs uppercase tracking-wide">API Calls</div>
+			<div class="text-muted-foreground text-xs uppercase tracking-wide">
+				API Calls
+				<Tooltip.Root>
+					<Tooltip.Trigger>
+						<span class="ml-1 cursor-help text-xs" style="color: #4f6ef7">?</span>
+					</Tooltip.Trigger>
+					<Tooltip.Portal>
+						<Tooltip.Content class="max-w-xs">
+							Number of API roundtrips (assistant responses) in this session.
+						</Tooltip.Content>
+					</Tooltip.Portal>
+				</Tooltip.Root>
+			</div>
 			<div class="mt-1 text-xl font-semibold">{apiCalls}</div>
 		</Card.Root>
 
@@ -113,7 +161,19 @@
 		</Card.Root>
 
 		<Card.Root class="p-3">
-			<div class="text-muted-foreground text-xs uppercase tracking-wide">Compactions</div>
+			<div class="text-muted-foreground text-xs uppercase tracking-wide">
+				Compactions
+				<Tooltip.Root>
+					<Tooltip.Trigger>
+						<span class="ml-1 cursor-help text-xs" style="color: #4f6ef7">?</span>
+					</Tooltip.Trigger>
+					<Tooltip.Portal>
+						<Tooltip.Content class="max-w-xs">
+							Number of times the context window was compacted to fit within limits.
+						</Tooltip.Content>
+					</Tooltip.Portal>
+				</Tooltip.Root>
+			</div>
 			<div class="mt-1 text-xl font-semibold">{compactions}</div>
 		</Card.Root>
 	</div>
diff --git a/web/src/routes/orgs/[slug]/analytics/+page.svelte b/web/src/routes/orgs/[slug]/analytics/+page.svelte
index d2a6c96..daaa0c3 100644
--- a/web/src/routes/orgs/[slug]/analytics/+page.svelte
+++ b/web/src/routes/orgs/[slug]/analytics/+page.svelte
@@ -2,6 +2,7 @@
 	import { page } from '$app/stores';
 	import { api } from '$lib/api';
 	import StatCard from '$lib/components/StatCard.svelte';
+	import HelpTip from '$lib/components/HelpTip.svelte';
 	import DataTable from '$lib/components/DataTable.svelte';
 	import Chart from '$lib/components/chart.svelte';
 	import GitCommitHorizontalIcon from '@lucide/svelte/icons/git-commit-horizontal';
@@ -258,21 +259,22 @@
 		<p class="text-destructive">{error}</p>
 	{:else if data}
 		<div class="grid grid-cols-2 gap-3 md:grid-cols-3 lg:grid-cols-3 xl:grid-cols-3">
-			<StatCard label="Total Commits" value={fmtNum(data.total_commits)} icon={GitCommitHorizontalIcon} color="#3b82f6" />
-			<StatCard label="Sessions" value={fmtNum(data.total_sessions)} icon={MonitorPlayIcon} color="#10b981" />
-			<StatCard label="Total Tokens" value={fmtNum(data.total_tokens)} icon={CoinsIcon} color="#f59e0b" secondary={tokensSecondary} />
-			<StatCard label="Active Authors" value={String(data.active_authors)} icon={UsersIcon} color="#8b5cf6" />
-			<StatCard label="AI %" value={data.ai_percentage != null ? `${data.ai_percentage.toFixed(1)}%` : 'N/A'} icon={PercentIcon} color="#ec4899" />
-			<StatCard label="Estimated Cost" value={fmtCost(data.estimated_cost_usd)} icon={DollarSignIcon} color="#dc2626" secondary={costSecondary} />
-			<StatCard label="Avg Session Duration" value={fmtDuration(data.avg_session_duration_ms)} icon={ClockIcon} color="#06b6d4" />
-			<StatCard label="Total Tool Calls" value={fmtNum(data.total_tool_calls)} icon={WrenchIcon} color="#f59e0b" />
-			<StatCard label="Cache Savings" value={fmtCost(data.cache_savings_usd)} icon={PiggyBankIcon} color="#10b981" />
+			<StatCard label="Total Commits" value={fmtNum(data.total_commits)} icon={GitCommitHorizontalIcon} color="#3b82f6" tooltip="Total git commits linked to AI sessions in the selected period." />
+			<StatCard label="Sessions" value={fmtNum(data.total_sessions)} icon={MonitorPlayIcon} color="#10b981" tooltip="Total AI coding sessions in the selected period." />
+			<StatCard label="Total Tokens" value={fmtNum(data.total_tokens)} icon={CoinsIcon} color="#f59e0b" secondary={tokensSecondary} tooltip="Total tokens processed, including input, output, and cached tokens." />
+			<StatCard label="Active Authors" value={String(data.active_authors)} icon={UsersIcon} color="#8b5cf6" tooltip="Number of unique developers with AI sessions." />
+			<StatCard label="AI %" value={data.ai_percentage != null ? `${data.ai_percentage.toFixed(1)}%` : 'N/A'} icon={PercentIcon} color="#ec4899" tooltip="Percentage of code lines attributed to AI across all commits." />
+			<StatCard label="Estimated Cost" value={fmtCost(data.estimated_cost_usd)} icon={DollarSignIcon} color="#dc2626" secondary={costSecondary} tooltip="Estimated total cost based on token usage and model pricing." />
+			<StatCard label="Avg Session Duration" value={fmtDuration(data.avg_session_duration_ms)} icon={ClockIcon} color="#06b6d4" tooltip="Average wall-clock time of completed sessions." />
+			<StatCard label="Total Tool Calls" value={fmtNum(data.total_tool_calls)} icon={WrenchIcon} color="#f59e0b" tooltip="Total tool invocations across all sessions (edits, reads, bash, etc.)." />
+			<StatCard label="Cache Savings" value={fmtCost(data.cache_savings_usd)} icon={PiggyBankIcon} color="#10b981" tooltip="Money saved by reusing cached tokens at reduced rates." />
 		</div>
 
 		<div class="grid gap-6 lg:grid-cols-2">
 			<div class="border-border rounded-lg border p-3">
 				<h4 class="mb-2 text-sm font-semibold">
 					<a href="/orgs/{slug}/analytics/tokens" class="hover:underline">Tokens Over Time</a>
+					<HelpTip text="Input and output token usage per day over the selected period." />
 				</h4>
 				{#if data.tokens_over_time.length > 0}
 					<Chart
@@ -288,6 +290,7 @@
 			<div class="border-border rounded-lg border p-3">
 				<h4 class="mb-2 text-sm font-semibold">
 					<a href="/orgs/{slug}/analytics/tokens" class="hover:underline">Top Repos by Tokens</a>
+					<HelpTip text="Repositories ranked by total token consumption." />
 				</h4>
 				{#if data.top_repos.length > 0}
 					<Chart
@@ -305,6 +308,7 @@
 			<div class="border-border rounded-lg border p-3">
 				<h4 class="mb-2 text-sm font-semibold">
 					<a href="/orgs/{slug}/analytics/sessions" class="hover:underline">Hourly Activity</a>
+					<HelpTip text="Distribution of sessions by hour of day (UTC), showing peak coding times." />
 				</h4>
 				{#if data.hourly_activity.length > 0}
 					<Chart
@@ -324,6 +328,7 @@
 			<div class="border-border rounded-lg border p-3">
 				<h4 class="mb-2 text-sm font-semibold">
 					<a href="/orgs/{slug}/analytics/sessions" class="hover:underline">Sessions Over Time</a>
+					<HelpTip text="Number of sessions started per day." />
 				</h4>
 				{#if data.sessions_over_time.length > 0}
 					<Chart
@@ -341,6 +346,7 @@
 			<div class="border-border rounded-lg border p-3">
 				<h4 class="mb-2 text-sm font-semibold">
 					<a href="/orgs/{slug}/analytics/models" class="hover:underline">Model Distribution</a>
+					<HelpTip text="Breakdown of sessions by AI model used." />
 				</h4>
 				<div class="flex justify-center">
 					{#if data.model_distribution.length > 0}
diff --git a/web/src/routes/orgs/[slug]/analytics/attribution/+page.svelte b/web/src/routes/orgs/[slug]/analytics/attribution/+page.svelte
index 279f9b8..e4b7db8 100644
--- a/web/src/routes/orgs/[slug]/analytics/attribution/+page.svelte
+++ b/web/src/routes/orgs/[slug]/analytics/attribution/+page.svelte
@@ -2,6 +2,7 @@
 	import { page } from '$app/stores';
 	import { api } from '$lib/api';
 	import Chart from '$lib/components/chart.svelte';
+	import HelpTip from '$lib/components/HelpTip.svelte';
 	import {
 		Chart as ChartJS,
 		CategoryScale,
@@ -165,22 +166,22 @@
 		<div class="border-border overflow-hidden rounded-lg border">
 			<div class="grid grid-cols-3 gap-px">
 				<div class="bg-background p-3 text-center">
-					<div class="text-muted-foreground text-[11px] uppercase tracking-wide">AI Lines</div>
+					<div class="text-muted-foreground text-[11px] uppercase tracking-wide">AI Lines<HelpTip text="Total lines of code attributed to AI across all commits." /></div>
 					<div class="mt-1 text-lg font-semibold" style="color: {AI_COLOR}">{fmtNum(data.totals.ai_lines)}</div>
 				</div>
 				<div class="bg-background p-3 text-center">
-					<div class="text-muted-foreground text-[11px] uppercase tracking-wide">Human Lines</div>
+					<div class="text-muted-foreground text-[11px] uppercase tracking-wide">Human Lines<HelpTip text="Total lines of code written by humans." /></div>
 					<div class="mt-1 text-lg font-semibold" style="color: {HUMAN_COLOR}">{fmtNum(data.totals.human_lines)}</div>
 				</div>
 				<div class="bg-background p-3 text-center">
-					<div class="text-muted-foreground text-[11px] uppercase tracking-wide">Overall AI %</div>
+					<div class="text-muted-foreground text-[11px] uppercase tracking-wide">Overall AI %<HelpTip text="Percentage of all code lines attributed to AI assistance." /></div>
 					<div class="mt-1 text-lg font-semibold">{data.totals.ai_pct.toFixed(1)}%</div>
 				</div>
 			</div>
 		</div>
 
 		<div class="border-border rounded-lg border p-3">
-			<h4 class="mb-2 text-sm font-semibold">AI vs Human Trend</h4>
+			<h4 class="mb-2 text-sm font-semibold">AI vs Human Trend<HelpTip text="How the ratio of AI-generated vs human-written code has changed over time." /></h4>
 			{#if data.trend.length > 0}
 				<Chart
 					type="line"
@@ -198,7 +199,7 @@
 
 		<div class="grid gap-6 lg:grid-cols-2">
 			<div class="border-border rounded-lg border p-3">
-				<h4 class="mb-2 text-sm font-semibold">By Repository</h4>
+				<h4 class="mb-2 text-sm font-semibold">By Repository<HelpTip text="AI vs human code ratio per repository." /></h4>
 				{#if data.by_repo.length > 0}
 					<Chart
 						type="bar"
@@ -216,7 +217,7 @@
 			</div>
 
 			<div class="border-border rounded-lg border p-3">
-				<h4 class="mb-2 text-sm font-semibold">By Author</h4>
+				<h4 class="mb-2 text-sm font-semibold">By Author<HelpTip text="AI vs human code ratio per developer." /></h4>
 				{#if data.by_author.length > 0}
 					<Chart
 						type="bar"
diff --git a/web/src/routes/orgs/[slug]/analytics/cost/+page.svelte b/web/src/routes/orgs/[slug]/analytics/cost/+page.svelte
index 01fcd80..7cbabce 100644
--- a/web/src/routes/orgs/[slug]/analytics/cost/+page.svelte
+++ b/web/src/routes/orgs/[slug]/analytics/cost/+page.svelte
@@ -5,6 +5,7 @@
 	import EnterpriseUpgrade from '$lib/components/enterprise-upgrade.svelte';
 	import Chart from '$lib/components/chart.svelte';
 	import StatCard from '$lib/components/StatCard.svelte';
+	import HelpTip from '$lib/components/HelpTip.svelte';
 	import DollarSign from '@lucide/svelte/icons/dollar-sign';
 	import PiggyBank from '@lucide/svelte/icons/piggy-bank';
 	import Calculator from '@lucide/svelte/icons/calculator';
@@ -169,13 +170,13 @@
 		<p class="text-destructive">{error}</p>
 	{:else if data}
 		<div class="grid grid-cols-1 gap-4 md:grid-cols-3">
-			<StatCard label="Total Cost" value={fmtCost(data.total_cost)} icon={DollarSign} color="#dc2626" />
-			<StatCard label="Cache Savings" value={fmtCost(data.cache_savings_usd)} icon={PiggyBank} color="#10b981" />
-			<StatCard label="Avg Cost/Session" value={fmtCost(data.avg_cost_per_session)} icon={Calculator} color="#3b82f6" />
+			<StatCard label="Total Cost" value={fmtCost(data.total_cost)} icon={DollarSign} color="#dc2626" tooltip="Total estimated cost based on token usage and model pricing rates." />
+			<StatCard label="Cache Savings" value={fmtCost(data.cache_savings_usd)} icon={PiggyBank} color="#10b981" tooltip="Net savings from prompt caching — tokens served from cache at reduced rates." />
+			<StatCard label="Avg Cost/Session" value={fmtCost(data.avg_cost_per_session)} icon={Calculator} color="#3b82f6" tooltip="Average estimated cost per session." />
 		</div>
 
 		<div class="border-border rounded-lg border p-3">
-			<h4 class="mb-2 text-sm font-semibold">Cost Over Time</h4>
+			<h4 class="mb-2 text-sm font-semibold">Cost Over Time<HelpTip text="Daily cost trend over the selected period." /></h4>
 			{#if data.cost_over_time.length > 0}
 				<Chart
 					type="line"
@@ -189,7 +190,7 @@
 
 		<div class="grid gap-6 lg:grid-cols-2">
 			<div class="border-border rounded-lg border p-3">
-				<h4 class="mb-2 text-sm font-semibold">Cost by Model</h4>
+				<h4 class="mb-2 text-sm font-semibold">Cost by Model<HelpTip text="Cost distribution across different AI models." /></h4>
 				{#if data.cost_by_model.length > 0}
 					<div class="flex justify-center">
 						<div class="max-w-[300px]">
@@ -206,7 +207,7 @@
 			</div>
 
 			<div class="border-border rounded-lg border p-3">
-				<h4 class="mb-2 text-sm font-semibold">Cost by Repository</h4>
+				<h4 class="mb-2 text-sm font-semibold">Cost by Repository<HelpTip text="Cost breakdown by repository." /></h4>
 				{#if data.cost_by_repo.length > 0}
 					<Chart
 						type="bar"
@@ -220,7 +221,7 @@
 		</div>
 
 		<div class="border-border rounded-lg border p-3">
-			<h4 class="mb-2 text-sm font-semibold">Cost by Author</h4>
+			<h4 class="mb-2 text-sm font-semibold">Cost by Author<HelpTip text="Cost breakdown by developer." /></h4>
 			{#if data.cost_by_author.length > 0}
 				<Chart
 					type="bar"
diff --git a/web/src/routes/orgs/[slug]/analytics/models/+page.svelte b/web/src/routes/orgs/[slug]/analytics/models/+page.svelte
index cc19915..5b5bc7f 100644
--- a/web/src/routes/orgs/[slug]/analytics/models/+page.svelte
+++ b/web/src/routes/orgs/[slug]/analytics/models/+page.svelte
@@ -3,6 +3,7 @@
 	import { api } from '$lib/api';
 	import * as Table from '$lib/components/ui/table/index.js';
 	import Chart from '$lib/components/chart.svelte';
+	import HelpTip from '$lib/components/HelpTip.svelte';
 	import {
 		Chart as ChartJS,
 		CategoryScale,
@@ -162,7 +163,7 @@
 	{:else if data}
 		<div class="grid gap-6 lg:grid-cols-2">
 			<div class="border-border rounded-lg border p-3">
-				<h4 class="mb-2 text-sm font-semibold">Model Distribution</h4>
+				<h4 class="mb-2 text-sm font-semibold">Model Distribution<HelpTip text="Number of sessions using each AI model." /></h4>
 				{#if data.distribution.length > 0}
 					<div class="flex justify-center">
 						<div class="max-w-[300px]">
@@ -179,7 +180,7 @@
 			</div>
 
 			<div class="border-border rounded-lg border p-3">
-				<h4 class="mb-2 text-sm font-semibold">Model Trends</h4>
+				<h4 class="mb-2 text-sm font-semibold">Model Trends<HelpTip text="How model usage has changed over time." /></h4>
 				{#if data.trends.length > 0}
 					<Chart
 						type="line"
@@ -227,7 +228,7 @@
 		</div>
 
 		<div class="border-border overflow-hidden rounded-lg border">
-			<h2 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground p-3">Model Comparison</h2>
+			<h2 class="text-sm font-semibold uppercase tracking-wide text-muted-foreground p-3">Model Comparison<HelpTip text="Average token consumption per session for each model." /></h2>
 			{#if data.comparison.length > 0}
 				<div class="p-3 pt-0">
 					<Chart
diff --git a/web/src/routes/orgs/[slug]/analytics/sessions/+page.svelte b/web/src/routes/orgs/[slug]/analytics/sessions/+page.svelte
index ba8b48d..baef056 100644
--- a/web/src/routes/orgs/[slug]/analytics/sessions/+page.svelte
+++ b/web/src/routes/orgs/[slug]/analytics/sessions/+page.svelte
@@ -3,6 +3,7 @@
 	import { api } from '$lib/api';
 	import DataTable from '$lib/components/DataTable.svelte';
 	import StatCard from '$lib/components/StatCard.svelte';
+	import HelpTip from '$lib/components/HelpTip.svelte';
 	import SessionDetailPanel from '$lib/components/session-detail/SessionDetailPanel.svelte';
 	import MonitorPlayIcon from '@lucide/svelte/icons/monitor-play';
 	import ClockIcon from '@lucide/svelte/icons/clock';
@@ -174,21 +175,22 @@
 	{:else if data}
 		<!-- Stat cards -->
 		<div class="grid grid-cols-2 gap-4 md:grid-cols-3 lg:grid-cols-5">
-			<StatCard label="Total Sessions" value={fmtNum(data.total_sessions)} icon={MonitorPlayIcon} color="#3b82f6" />
-			<StatCard label="Avg Duration" value={fmtDuration(data.avg_duration_ms)} icon={ClockIcon} color="#10b981" />
+			<StatCard label="Total Sessions" value={fmtNum(data.total_sessions)} icon={MonitorPlayIcon} color="#3b82f6" tooltip="Total AI coding sessions in the selected period." />
+			<StatCard label="Avg Duration" value={fmtDuration(data.avg_duration_ms)} icon={ClockIcon} color="#10b981" tooltip="Average wall-clock duration of completed sessions." />
 			<StatCard
 				label="Avg Messages/Session"
 				value={data.avg_messages_per_session != null ? data.avg_messages_per_session.toFixed(1) : '-'}
 				icon={MessageSquareIcon}
 				color="#f59e0b"
+				tooltip="Average number of user + assistant messages per session."
 			/>
-			<StatCard label="Total Cost" value={fmtCost(totalCost)} icon={DollarSignIcon} color="#dc2626" />
-			<StatCard label="Top Model" value={topModel} icon={CpuIcon} color="#8b5cf6" />
+			<StatCard label="Total Cost" value={fmtCost(totalCost)} icon={DollarSignIcon} color="#dc2626" tooltip="Total estimated cost across all sessions." />
+			<StatCard label="Top Model" value={topModel} icon={CpuIcon} color="#8b5cf6" tooltip="Most frequently used AI model." />
 		</div>
 
 		<!-- Tool Frequency chart -->
 		<div class="border-border rounded-lg border p-3">
-			<h4 class="mb-2 text-sm font-semibold">Tool Frequency</h4>
+			<h4 class="mb-2 text-sm font-semibold">Tool Frequency<HelpTip text="Distribution of tool usage across all sessions. Shows which tools are used most frequently." /></h4>
 			{#if Object.keys(data.tool_frequency).length > 0}
 				{@const entries = toolFrequencyEntries(data)}
 				{@const total = toolFrequencyTotal(data)}
diff --git a/web/src/routes/orgs/[slug]/analytics/tokens/+page.svelte b/web/src/routes/orgs/[slug]/analytics/tokens/+page.svelte
index f466220..f47d676 100644
--- a/web/src/routes/orgs/[slug]/analytics/tokens/+page.svelte
+++ b/web/src/routes/orgs/[slug]/analytics/tokens/+page.svelte
@@ -2,6 +2,7 @@
 	import { page } from '$app/stores';
 	import { api } from '$lib/api';
 	import StatCard from '$lib/components/StatCard.svelte';
+	import HelpTip from '$lib/components/HelpTip.svelte';
 	import DataTable from '$lib/components/DataTable.svelte';
 	import Chart from '$lib/components/chart.svelte';
 	import BookOpenIcon from '@lucide/svelte/icons/book-open';
@@ -165,23 +166,26 @@
 				value={fmtNum(data.cache_read_tokens)}
 				icon={BookOpenIcon}
 				color="#3b82f6"
+				tooltip="Tokens served from the prompt cache at reduced cost."
 			/>
 			<StatCard
 				label="Cache Write Tokens"
 				value={fmtNum(data.cache_write_tokens)}
 				icon={BookMarkedIcon}
 				color="#8b5cf6"
+				tooltip="Tokens written to the prompt cache for future reuse. Writing costs more than regular input."
 			/>
 			<StatCard
 				label="Cache Savings"
 				value={'$' + data.cache_savings_usd.toFixed(2)}
 				icon={PiggyBankIcon}
 				color="#10b981"
+				tooltip="Net money saved through prompt caching."
 			/>
 		</div>
 
 		<div class="border-border rounded-lg border p-3">
-			<h4 class="mb-2 text-sm font-semibold">Tokens Over Time</h4>
+			<h4 class="mb-2 text-sm font-semibold">Tokens Over Time<HelpTip text="Daily input and output token usage." /></h4>
 			{#if data.time_series.length > 0}
 				<Chart
 					type="line"
@@ -210,7 +214,7 @@
 		</DataTable>
 
 		<div class="border-border rounded-lg border p-3">
-			<h4 class="mb-2 text-sm font-semibold">By Author</h4>
+			<h4 class="mb-2 text-sm font-semibold">By Author<HelpTip text="Total token consumption by developer." /></h4>
 			{#if data.by_author.length > 0}
 				<Chart
 					type="bar"
diff --git a/web/src/routes/orgs/[slug]/dashboard/+page.svelte b/web/src/routes/orgs/[slug]/dashboard/+page.svelte
index 937c1cb..cf25e6f 100644
--- a/web/src/routes/orgs/[slug]/dashboard/+page.svelte
+++ b/web/src/routes/orgs/[slug]/dashboard/+page.svelte
@@ -89,6 +89,7 @@
 						sparkline={data.cost_sparkline}
 						href="/orgs/{slug}/analytics/cost"
 						color="#3b82f6"
+						tooltip="Total estimated cost across all sessions in the selected period, based on model pricing rates."
 					/>
 					<KpiCard
 						label="Active Devs"
@@ -100,6 +101,7 @@
 						sparkline={data.authors_sparkline}
 						href="/orgs/{slug}/analytics/authors"
 						color="#8b5cf6"
+						tooltip="Number of unique developers who had AI coding sessions in the selected period."
 					/>
 					<KpiCard
 						label="Sessions"
@@ -108,6 +110,7 @@
 						sparkline={data.sessions_sparkline}
 						href="/orgs/{slug}/analytics/sessions"
 						color="#22c55e"
+						tooltip="Total AI coding sessions started in the selected period."
 					/>
 					<KpiCard
 						label="Total Tokens"
@@ -116,6 +119,7 @@
 						sparkline={data.tokens_sparkline}
 						href="/orgs/{slug}/analytics/tokens"
 						color="#f59e0b"
+						tooltip="Total tokens processed across all sessions, including input, output, and cached tokens."
 					/>
 				</div>
 				<SessionQualityBar