@skyhook-io/radar-app 1.12.2 → 1.13.0

package/src/components/cost/ApplicationCostTab.tsx

@@ -25,6 +25,14 @@ import {
 import { isOpenCostWorkloadKind } from './kinds'
 import { CurrentAllocationUse } from './CurrentAllocationUse'
 import { costUnavailableReasonFromError } from './errors'
+import {
+  costFreshnessLabel,
+  costIntegrationUnavailableMessage,
+  costRateLabels,
+  costSourceLabel,
+  isCostDiscoveryPending,
+} from './source'
+import { useNavCustomization } from '../../context/NavCustomization'
 
 type ApplicationCostState =
   | 'loading'
@@ -53,8 +61,9 @@ export function ApplicationCostTab({
   workloads,
   onSelectWorkloadCost,
 }: ApplicationCostTabProps) {
+  const settingsAvailable = !useNavCustomization().embedded
   const [range, setRange] = useState<CostTimeRange>('24h')
-  const [noPrometheusSince, setNoPrometheusSince] = useState<number | null>(null)
+  const [discoverySince, setDiscoverySince] = useState<number | null>(null)
   const supportedWorkloads = useMemo(() => applicationCostWorkloads(workloads), [workloads])
   const unsupportedCount = workloads.length - supportedWorkloads.length
   const queriesEnabled = supportedWorkloads.length > 0
@@ -77,10 +86,10 @@ export function ApplicationCostTab({
   })
 
   useEffect(() => {
-    if (state === 'no_prometheus') {
-      setNoPrometheusSince((prev) => prev ?? Date.now())
+    if (isCostDiscoveryPending(state)) {
+      setDiscoverySince((prev) => prev ?? Date.now())
     } else {
-      setNoPrometheusSince(null)
+      setDiscoverySince(null)
     }
   }, [state])
 
@@ -96,6 +105,7 @@ export function ApplicationCostTab({
       <ApplicationCostUnavailable
         state="no_metrics"
         message="No steady-state workloads in this app are currently cost-attributed."
+        settingsAvailable={settingsAvailable}
       />
     )
   }
@@ -115,22 +125,28 @@ export function ApplicationCostTab({
     state === 'query_error' ||
     state === 'access_denied' ||
     state === 'not_found' ||
+    state === 'no_cost_source' ||
+    state === 'source_unavailable' ||
+    state === 'authentication_error' ||
+    state === 'configuration_mismatch' ||
+    state === 'deployment_configuration_error' ||
+    state === 'history_unsupported' ||
     state === 'load_error'
   ) {
-    const discoveryAgeMs = noPrometheusSince == null ? 0 : Date.now() - noPrometheusSince
-    if (state === 'no_prometheus' && discoveryAgeMs < COST_DISCOVERY_GRACE_MS) {
+    const discoveryAgeMs = discoverySince == null ? 0 : Date.now() - discoverySince
+    if (isCostDiscoveryPending(state) && discoveryAgeMs < COST_DISCOVERY_GRACE_MS) {
       return (
         <ApplicationCostDiscovering
           isFetching={currentQuery.isFetching || trendQuery.isFetching}
           onRetry={() => {
-            setNoPrometheusSince(Date.now())
+            setDiscoverySince(Date.now())
             currentQuery.refetch()
             trendQuery.refetch()
           }}
         />
       )
     }
-    return <ApplicationCostUnavailable state={state} />
+    return <ApplicationCostUnavailable state={state} settingsAvailable={settingsAvailable} />
   }
 
   const current = currentQuery.data
@@ -151,12 +167,16 @@ export function ApplicationCostTab({
   const maxCost = Math.max(...rows.map((row) => row.current?.hourlyCost ?? 0), 0)
   const currentCurrency = current?.currency ?? trend?.currency ?? DEFAULT_COST_CURRENCY
   const trendCurrency = trend?.currency ?? current?.currency ?? DEFAULT_COST_CURRENCY
+  const source = current?.source ?? trend?.source
+  const historyUnsupported = trend?.reason === 'history_unsupported'
+  const currentWindow = current?.window
+  const rateLabels = costRateLabels(currentWindow)
 
   return (
     <div className="mx-auto w-full max-w-[1600px] space-y-4">
       {(current?.partial ||
         trend?.partial ||
-        state === 'partial_missing_history' ||
+        (state === 'partial_missing_history' && !historyUnsupported) ||
         state === 'partial_missing_current' ||
         unsupportedCount > 0) && (
         <div className="flex items-start gap-2 rounded-lg border border-theme-border bg-theme-base px-3 py-2 text-sm text-theme-text-secondary">
@@ -185,61 +205,76 @@ export function ApplicationCostTab({
                 <div className="text-sm font-semibold text-theme-text-primary">
                   Application compute cost
                 </div>
-                <CostInfoTooltip content="Values are based on OpenCost CPU and memory allocation over time, grouped by the workloads in this application. OpenCost allocation uses the greater of requested or observed resources." />
+                <CostInfoTooltip content="Values are based on CPU and memory allocation grouped by the workloads in this application. The cost provider attributes the greater of requested or observed resources." />
               </div>
               <div className="text-xs text-theme-text-tertiary">
-                OpenCost CPU and memory allocation rate ({trendCurrency}/hr) for Deployment,
-                StatefulSet, and DaemonSet workloads
+                CPU and memory allocation rate ({trendCurrency}/hr) for Deployment, StatefulSet,
+                and DaemonSet workloads
               </div>
             </div>
           </div>
-          <CostTimeRangeSelector value={range} onChange={setRange} />
+          {!historyUnsupported && <CostTimeRangeSelector value={range} onChange={setRange} />}
         </div>
 
-        <div className="grid gap-4 p-4 lg:grid-cols-[240px_minmax(0,1fr)]">
-          <div className="space-y-4">
+        {historyUnsupported ? (
+          <div className="grid gap-4 p-4 sm:grid-cols-2">
             <CostMetricBlock
-              label={`Spend over ${range}`}
-              value={formatHistoricalSpend(
-                points.length,
-                trend?.windowTotalCost ?? 0,
-                trendLoading || state === 'partial_missing_history',
-                trendCurrency,
-              )}
-              subvalue={
-                state === 'partial_missing_history'
-                  ? 'Historical data incomplete'
-                  : `${included} of ${total} workloads included`
-              }
+              label={rateLabels.hourly}
+              value={totals ? formatCostPerHour(hourly, currentCurrency) : '—'}
+              subvalue={`${included} of ${total} workloads included`}
             />
             <CostMetricBlock
               label="Projected monthly"
               value={totals ? formatProjectedMonthlyCost(hourly, currentCurrency) : '—'}
-              subvalue={
-                totals
-                  ? `${formatCostPerHour(hourly, currentCurrency)} current rate`
-                  : 'Current allocation unavailable'
-              }
+              subvalue={`${rateLabels.rate} × 730 hours`}
             />
           </div>
-          <div className="min-w-0">
-            {trendLoading ? (
-              <div className="flex h-[240px] items-center justify-center rounded-md border border-dashed border-theme-border bg-theme-base/60 text-sm text-theme-text-tertiary">
-                <Loader2 className="mr-2 h-4 w-4 animate-spin" />
-                Loading historical cost…
-              </div>
-            ) : hasTrend && chartSeries.length > 0 ? (
-              <div className="min-w-0">
-                <StackedAreaChart series={chartSeries} currency={trendCurrency} />
-                <ChartLegend series={chartSeries} />
-              </div>
-            ) : (
-              <div className="flex h-[240px] items-center justify-center rounded-md border border-dashed border-theme-border bg-theme-base/60 text-sm text-theme-text-tertiary">
-                No historical workload owner cost points for this range.
-              </div>
-            )}
+        ) : (
+          <div className="grid gap-4 p-4 lg:grid-cols-[240px_minmax(0,1fr)]">
+            <div className="space-y-4">
+              <CostMetricBlock
+                label={`Spend over ${range}`}
+                value={formatHistoricalSpend(
+                  points.length,
+                  trend?.windowTotalCost ?? 0,
+                  trendLoading || state === 'partial_missing_history',
+                  trendCurrency,
+                )}
+                subvalue={
+                  state === 'partial_missing_history'
+                    ? 'Historical data incomplete'
+                    : `${included} of ${total} workloads included`
+                }
+              />
+              <CostMetricBlock
+                label="Projected monthly"
+                value={totals ? formatProjectedMonthlyCost(hourly, currentCurrency) : '—'}
+                subvalue={
+                  totals
+                    ? `${formatCostPerHour(hourly, currentCurrency)} · ${rateLabels.rate}`
+                    : 'Current allocation unavailable'
+                }
+              />
+            </div>
+            <div className="min-w-0">
+              {trendLoading ? (
+                <div className="flex h-[240px] items-center justify-center rounded-md border border-dashed border-theme-border bg-theme-base/60 text-sm text-theme-text-tertiary">
+                  <Loader2 className="mr-2 h-4 w-4 animate-spin" />
+                  Loading historical cost…
+                </div>
+              ) : hasTrend && chartSeries.length > 0 ? (
+                <div className="min-w-0">
+                  <StackedAreaChart series={chartSeries} currency={trendCurrency} />
+                  <ChartLegend series={chartSeries} />
+                </div>
+              ) : (
+                <div className="flex h-[240px] items-center justify-center rounded-md border border-dashed border-theme-border bg-theme-base/60 text-sm text-theme-text-tertiary">
+                  No historical workload owner cost points for this range.
+                </div>
+              )}
+            </div>
           </div>
-        </div>
+        )}
       </section>
 
       <div className="grid gap-4 md:grid-cols-2">
@@ -257,7 +292,7 @@ export function ApplicationCostTab({
           value={totals ? formatProjectedDailyRate(hourly, currentCurrency) : '—'}
           subvalue={
             totals
-              ? `${formatCostPerHour(hourly, currentCurrency)} current hourly rate`
+              ? `${formatCostPerHour(hourly, currentCurrency)} · ${rateLabels.rate}`
               : 'Current allocation unavailable'
           }
         />
@@ -274,6 +309,7 @@ export function ApplicationCostTab({
         cpuUsageAvailable={totals?.cpuUsageAvailable ?? false}
         memoryUsageAvailable={totals?.memoryUsageAvailable ?? false}
         scopeNote="Included workloads only"
+        window={source === 'kubecost' ? currentWindow : undefined}
       />
 
       <section className="rounded-lg border border-theme-border bg-theme-surface/50">
@@ -283,7 +319,7 @@ export function ApplicationCostTab({
               Workload contributors
             </div>
             <div className="text-xs text-theme-text-tertiary">
-              Projected monthly from current allocation, sorted by spend
+              Projected monthly from the {rateLabels.rate}, sorted by spend
             </div>
           </div>
           <div className="text-xs text-theme-text-tertiary">{rows.length} tracked</div>
@@ -315,13 +351,15 @@ export function ApplicationCostTab({
       </section>
 
       <div className="text-xs text-theme-text-tertiary">
-        Powered by OpenCost via Prometheus.{' '}
+        {costSourceLabel(source)} &middot; {costFreshnessLabel(source, source === 'kubecost' ? currentWindow : '1h', current?.dataThrough)}.{' '}
         {currentCurrency !== DEFAULT_COST_CURRENCY && (
           <>Labeled {currentCurrency}; no conversion. </>
         )}
-        Historical spend uses the selected range; projected monthly values multiply current hourly
-        allocation. Batch/job cost is separate; storage/PVC and network costs remain at namespace
-        and cluster level.
+        {historyUnsupported
+          ? 'Historical application charts are not available for Kubecost yet. '
+          : 'Historical spend uses the selected range. '}
+        Projected monthly values multiply the {rateLabels.rate}. Batch/job cost is separate;
+        storage/PVC and network costs remain at namespace and cluster level.
       </div>
     </div>
   )
@@ -348,14 +386,19 @@ export function getApplicationCostState(
   if (trendHasData) return 'partial_missing_current'
   const reason =
     current?.reason ??
-    trend?.reason ??
     costUnavailableReasonFromError(status.currentError) ??
+    trend?.reason ??
     costUnavailableReasonFromError(status.trendError)
   if (
     reason === 'no_prometheus' ||
+    reason === 'no_cost_source' ||
     reason === 'query_error' ||
     reason === 'access_denied' ||
-    reason === 'not_found'
+    reason === 'not_found' ||
+    reason === 'source_unavailable' ||
+    reason === 'authentication_error' ||
+    reason === 'configuration_mismatch' ||
+    reason === 'deployment_configuration_error'
   )
     return reason
   if (queryError) return 'load_error'
@@ -462,10 +505,13 @@ function applicationCostKey(ref: { kind: string; namespace: string; name: string
 }
 
 function reasonLabel(reason?: CostUnavailableReason) {
-  if (reason === 'no_prometheus') return 'Prometheus not found'
+  if (reason === 'no_prometheus') return 'Metrics backend not found'
+  if (reason === 'no_cost_source') return 'Cost source not found'
   if (reason === 'query_error') return 'Cost query failed'
   if (reason === 'access_denied') return 'No access to this workload'
   if (reason === 'not_found') return 'Workload not found'
+  if (reason === 'configuration_mismatch') return 'Kubecost settings are not valid for this cluster'
+  if (reason === 'deployment_configuration_error') return 'Radar cost deployment is misconfigured'
   return 'No workload cost metrics'
 }
 
@@ -482,11 +528,11 @@ function ApplicationCostDiscovering({
         <Loader2 className="h-8 w-8 animate-spin text-theme-text-tertiary/60" />
         <div>
           <p className="text-sm font-medium text-theme-text-primary">
-            Looking for Prometheus cost data…
+            Looking for cost data…
           </p>
           <p className="mt-1 text-xs text-theme-text-tertiary">
-            First discovery can take a few seconds while Radar checks cluster services and opens a
-            local port-forward.
+            Radar is checking OpenCost metrics in a PromQL-compatible backend and a local Kubecost
+            3 Aggregator. First discovery can take a few seconds.
           </p>
         </div>
         <button
@@ -504,23 +550,28 @@ function ApplicationCostDiscovering({
 function ApplicationCostUnavailable({
   state,
   message,
+  settingsAvailable,
 }: {
   state: CostUnavailableReason | 'load_error'
   message?: string
+  settingsAvailable: boolean
 }) {
   const text =
     message ??
+    costIntegrationUnavailableMessage(state, settingsAvailable) ??
     (state === 'no_prometheus'
-      ? 'Prometheus not found. OpenCost application cost requires Prometheus or VictoriaMetrics.'
+      ? 'No compatible metrics backend was found. OpenCost application cost requires OpenCost metrics in a PromQL-compatible backend.'
       : state === 'query_error'
-        ? 'Cost data is temporarily unavailable. Prometheus was found, but application cost queries failed.'
+        ? 'Cost data is temporarily unavailable. A metrics backend was found, but application cost queries failed.'
+        : state === 'history_unsupported'
+          ? 'Historical application cost is not available for Kubecost yet.'
         : state === 'access_denied'
           ? 'Cost data is unavailable because these workloads are not accessible with your current permissions.'
           : state === 'not_found'
             ? 'Cost data is unavailable because the referenced workloads no longer exist.'
             : state === 'load_error'
               ? 'Could not load application cost data. Check access to these workloads and try again.'
-              : 'OpenCost workload metrics were not found for this application.')
+              : 'No workload cost data was returned for this application by the active cost source.')
   return (
     <div className="flex h-full min-h-[320px] items-center justify-center">
       <div className="flex max-w-md flex-col items-center gap-3 text-center text-theme-text-secondary">

package/src/components/cost/CostTrendChart.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from 'vitest'
+import type { OpenCostTrendSeries } from '../../api/client'
+import { kubecostRetentionNote, kubecostTrendIsStale, kubecostTrendUnavailableMessage } from './CostTrendChart'
+
+const hour = 60 * 60
+
+function series(...timestamps: number[]): OpenCostTrendSeries[] {
+  return [{
+    namespace: 'default',
+    dataPoints: timestamps.map((timestamp) => ({ timestamp, value: 1 })),
+  }]
+}
+
+describe('kubecostRetentionNote', () => {
+  it('describes a material retention gap', () => {
+    const start = 1_000
+    expect(kubecostRetentionNote(series(start + 4 * hour, start + 5 * hour), start, start + 7 * 24 * hour))
+      .toContain('Kubecost history is available from')
+  })
+
+  it('stays quiet when the first hourly bucket follows the requested start', () => {
+    const start = 1_000
+    expect(kubecostRetentionNote(series(start + hour, start + 2 * hour), start, start + 24 * hour)).toBeNull()
+  })
+
+  it('stays quiet when there is only one retained sample', () => {
+    const start = 1_000
+    expect(kubecostRetentionNote(series(start + 4 * hour), start, start + 24 * hour)).toBeNull()
+  })
+
+  it('allows the normal first daily bucket without calling retention partial', () => {
+    const start = 1_000
+    expect(kubecostRetentionNote(series(start + 24 * hour, start + 48 * hour), start, start + 7 * 24 * hour)).toBeNull()
+  })
+})
+
+describe('kubecostTrendIsStale', () => {
+  it('allows normal hourly ingestion lag', () => {
+    const now = Date.parse('2026-08-30T12:00:00Z')
+    expect(kubecostTrendIsStale('2026-08-30T10:00:00Z', '6h', now)).toBe(false)
+  })
+
+  it('flags a source beyond the range lag budget', () => {
+    const now = Date.parse('2026-08-30T12:00:00Z')
+    expect(kubecostTrendIsStale('2026-08-30T02:00:00Z', '24h', now)).toBe(true)
+    expect(kubecostTrendIsStale('2026-08-28T02:00:00Z', '7d', now)).toBe(true)
+  })
+
+  it('stays quiet without a valid retained timestamp', () => {
+    expect(kubecostTrendIsStale(undefined, '6h')).toBe(false)
+    expect(kubecostTrendIsStale('invalid', '6h')).toBe(false)
+  })
+})
+
+describe('kubecostTrendUnavailableMessage', () => {
+  it('distinguishes an empty namespace scope from missing Kubecost history', () => {
+    expect(kubecostTrendUnavailableMessage('no_metrics', true)).toContain('current namespace scope')
+    expect(kubecostTrendUnavailableMessage('no_metrics', false)).toContain('Kubecost has no retained')
+  })
+
+  it('distinguishes insufficient scoped history', () => {
+    expect(kubecostTrendUnavailableMessage('insufficient_history', true)).toContain('namespace scope')
+    expect(kubecostTrendUnavailableMessage('insufficient_history', false)).toContain('two retained samples')
+  })
+})

package/src/components/cost/CostTrendChart.tsx

@@ -1,8 +1,15 @@
 import { useState, useMemo, useRef, useCallback } from 'react'
 import { clsx } from 'clsx'
 import { Loader2, TrendingUp } from 'lucide-react'
-import { useOpenCostTrend, type CostTimeRange, type OpenCostTrendSeries } from '../../api/client'
+import { formatCompactAge } from '@skyhook-io/k8s-ui/utils/format'
+import {
+  useOpenCostTrend,
+  type CostTimeRange,
+  type CostUnavailableReason,
+  type OpenCostTrendSeries,
+} from '../../api/client'
 import { DEFAULT_COST_CURRENCY, formatCostAxis, formatCostPerHour } from './format'
+import { costDataThroughLabel } from './source'
 
 const SERIES_COLORS = [
   '#3b82f6', // blue-500
@@ -22,7 +29,7 @@ const TIME_RANGES: { value: CostTimeRange; label: string }[] = [
   { value: '7d', label: '7d' },
 ]
 
-export function CostTrendChart() {
+export function CostTrendChart({ namespaceScoped = false }: { namespaceScoped?: boolean }) {
   const [timeRange, setTimeRange] = useState<CostTimeRange>('24h')
   const { data, isLoading } = useOpenCostTrend(timeRange)
 
@@ -37,11 +44,16 @@ export function CostTrendChart() {
     )
   }
 
-  if (!data?.available || !data.series?.length) {
+  const showKubecostUnavailable = data?.source === 'kubecost' && data.available === false
+  if ((!data?.available || !data.series?.length) && !showKubecostUnavailable) {
     return null
   }
 
   const currency = data.currency ?? DEFAULT_COST_CURRENCY
+  const retentionNote = data.available ? kubecostRetentionNote(data.series ?? [], data.windowStart, data.windowEnd) : null
+  const dataThrough = data.source === 'kubecost' ? costDataThroughLabel(data.dataThrough) : ''
+  const stale = data.source === 'kubecost' && kubecostTrendIsStale(data.dataThrough, timeRange)
+  const lag = stale ? formatCompactAge(data.dataThrough) : ''
 
   return (
     <div className="rounded-lg border border-theme-border bg-theme-surface/50">
@@ -50,16 +62,32 @@ export function CostTrendChart() {
           <TrendingUp className="w-4 h-4 text-theme-text-tertiary" />
           <div>
             <div className="text-xs font-medium text-theme-text-secondary">Cost rate trend</div>
-            <div className="text-[10px] text-theme-text-tertiary">
-              Historical OpenCost allocation rate ({currency}/hr)
+            <div className={clsx('text-[10px]', stale ? 'text-warning-text' : 'text-theme-text-tertiary')}>
+              {data.source === 'kubecost'
+                ? `Retained Kubecost namespace cost (${currency}/hr)${dataThrough ? ` · data through ${dataThrough}` : ''}${lag ? ` · ${lag} behind` : ''}`
+                : `Historical OpenCost CPU and memory allocation (${currency}/hr)`}
             </div>
           </div>
         </div>
         <CostTimeRangeSelector value={timeRange} onChange={setTimeRange} />
       </div>
-      <div className="p-4">
-        <StackedAreaChart series={data.series} currency={currency} />
-        <ChartLegend series={data.series} />
+      <div className="p-4 min-h-[300px]">
+        {showKubecostUnavailable ? (
+          <div className="min-h-[268px] flex items-center justify-center px-6 text-center text-xs text-theme-text-tertiary">
+            {kubecostTrendUnavailableMessage(data.reason, namespaceScoped)}
+          </div>
+        ) : (
+          <>
+            <StackedAreaChart
+              series={data.series ?? []}
+              currency={currency}
+              windowStart={data.windowStart}
+              windowEnd={data.windowEnd}
+            />
+            <div className="h-4 mt-1 text-[10px] text-theme-text-tertiary">{retentionNote}</div>
+            <ChartLegend series={data.series ?? []} />
+          </>
+        )}
       </div>
     </div>
   )
@@ -68,9 +96,13 @@ export function CostTrendChart() {
 export function StackedAreaChart({
   series,
   currency,
+  windowStart,
+  windowEnd,
 }: {
   series: OpenCostTrendSeries[]
   currency: string
+  windowStart?: number
+  windowEnd?: number
 }) {
   const svgRef = useRef<SVGSVGElement>(null)
   const [hoverX, setHoverX] = useState<number | null>(null)
@@ -98,8 +130,10 @@ export function StackedAreaChart({
     const timestamps = Array.from(tsSet).sort((a, b) => a - b)
     if (timestamps.length < 2) return null
 
-    const minTs = timestamps[0]
-    const maxTs = timestamps[timestamps.length - 1]
+    const dataMinTs = timestamps[0]
+    const dataMaxTs = timestamps[timestamps.length - 1]
+    const minTs = windowStart && windowStart < dataMinTs ? windowStart : dataMinTs
+    const maxTs = windowEnd && windowEnd > dataMaxTs ? windowEnd : dataMaxTs
 
     const seriesLookups = series.map((s) => {
       const map = new Map<number, number>()
@@ -140,7 +174,7 @@ export function StackedAreaChart({
     const xTickCount = 6
     const xTicks = Array.from({ length: xTickCount + 1 }, (_, i) => {
       const ts = minTs + ((maxTs - minTs) / xTickCount) * i
-      return { ts, x: toX(ts), label: formatTimestamp(ts) }
+      return { ts, x: toX(ts), label: formatTimestamp(ts, maxTs - minTs) }
     })
 
     // Build stacked area paths
@@ -185,7 +219,7 @@ export function StackedAreaChart({
       xTicks,
       paths,
     }
-  }, [series, currency, plotHeight, plotWidth])
+  }, [series, currency, plotHeight, plotWidth, windowStart, windowEnd])
 
   // Hover data — depends on hoverX + chartData, must be a separate hook (called unconditionally)
   const hoverData = useMemo(() => {
@@ -417,13 +451,69 @@ function formatCostTooltip(value: number, currency: string): string {
   return formatCostPerHour(value, currency)
 }
 
-function formatTimestamp(unix: number): string {
+function formatTimestamp(unix: number, spanSeconds: number): string {
   const d = new Date(unix * 1000)
-  const now = new Date()
-  const diffHours = (now.getTime() - d.getTime()) / (1000 * 60 * 60)
-  // Show date+time for ranges > 24h, just time otherwise
-  if (diffHours > 36) {
+  if (spanSeconds > 36 * 60 * 60) {
     return d.toLocaleDateString([], { month: 'short', day: 'numeric' })
   }
   return d.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })
 }
+
+export function kubecostRetentionNote(
+  series: OpenCostTrendSeries[],
+  windowStart?: number,
+  windowEnd?: number,
+): string | null {
+  if (!windowStart || !windowEnd) return null
+  const timestamps = Array.from(new Set(series.flatMap((item) => item.dataPoints.map((point) => point.timestamp)))).sort(
+    (a, b) => a - b,
+  )
+  if (timestamps.length < 2) return null
+
+  const intervals = timestamps.slice(1).map((timestamp, index) => timestamp - timestamps[index]).filter((value) => value > 0)
+  const typicalInterval = intervals.sort((a, b) => a - b)[Math.floor(intervals.length / 2)] ?? 0
+  const materialGap = Math.max(2 * 60 * 60, typicalInterval * 1.5)
+  if (timestamps[0] - windowStart <= materialGap) return null
+
+  const start = new Date(timestamps[0] * 1000).toLocaleString([], {
+    month: 'short',
+    day: 'numeric',
+    hour: '2-digit',
+    minute: '2-digit',
+  })
+  return `Kubecost history is available from ${start}.`
+}
+
+export function kubecostTrendIsStale(
+  dataThrough: string | undefined,
+  range: CostTimeRange,
+  now = Date.now(),
+): boolean {
+  if (!dataThrough) return false
+  const timestamp = Date.parse(dataThrough)
+  if (!Number.isFinite(timestamp)) return false
+  const lagBudget = range === '7d' ? 24 * 60 * 60 * 1000 : 6 * 60 * 60 * 1000
+  return now - timestamp > lagBudget
+}
+
+export function kubecostTrendUnavailableMessage(
+  reason?: CostUnavailableReason,
+  namespaceScoped = false,
+): string {
+  switch (reason) {
+    case 'no_metrics':
+      if (namespaceScoped) return 'No allocation history is visible in the current namespace scope.'
+      return 'Kubecost has no retained allocation history for this range.'
+    case 'insufficient_history':
+      if (namespaceScoped) return 'The current namespace scope does not have enough allocation history to draw this range.'
+      return 'Kubecost needs at least two retained samples to draw this range.'
+    case 'authentication_error':
+      return 'Kubecost rejected Radar’s API key. Check Settings → Cost.'
+    case 'source_unavailable':
+      return 'Radar could not reach Kubecost. Check Settings → Cost.'
+    case 'configuration_mismatch':
+      return 'Kubecost returned data for a different cluster. Check the cluster ID in Settings → Cost.'
+    default:
+      return 'Kubecost history could not be loaded.'
+  }
+}

package/src/components/cost/CostView.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from 'vitest'
-import { resourceKindForCostWorkload } from './CostView'
+import { costUnavailableMessage, resourceKindForCostWorkload } from './CostView'
+import { costConfigurationAction } from './source'
 
 describe('resourceKindForCostWorkload', () => {
   it('does not link standalone aggregate rows as pods', () => {
@@ -10,3 +11,37 @@ describe('resourceKindForCostWorkload', () => {
     expect(resourceKindForCostWorkload('staticpod')).toBe('Pod')
   })
 })
+
+describe('costUnavailableMessage', () => {
+  it('gives actionable Kubecost source and authentication guidance', () => {
+    expect(costUnavailableMessage('source_unavailable')).toContain('Settings → Cost')
+    expect(costUnavailableMessage('authentication_error')).toContain('API key')
+    expect(costUnavailableMessage('configuration_mismatch')).toContain('not valid for this cluster')
+    expect(costUnavailableMessage('deployment_configuration_error')).toContain('Helm cost values')
+  })
+
+  it('distinguishes a scoped empty result from missing source data', () => {
+    expect(costUnavailableMessage('no_metrics', { namespaceScoped: true })).toBe(
+      'No allocation data is visible in the current namespace scope',
+    )
+    expect(costUnavailableMessage('no_metrics')).toContain('selected source')
+  })
+
+  it('does not point embedded deployments at standalone Settings', () => {
+    expect(costUnavailableMessage('no_cost_source', { settingsAvailable: false })).toContain('host application')
+    expect(costUnavailableMessage('no_cost_source', { settingsAvailable: false })).not.toContain('Settings')
+  })
+})
+
+describe('costConfigurationAction', () => {
+  it('routes missing Prometheus to Metrics and other source failures to Cost', () => {
+    expect(costConfigurationAction('no_prometheus')).toEqual({
+      section: 'prometheus',
+      label: 'Configure metrics',
+    })
+    expect(costConfigurationAction('no_cost_source')).toEqual({
+      section: 'cost',
+      label: 'Configure cost source',
+    })
+  })
+})