@littlebearapps/platform-admin-sdk 2.0.0 → 2.1.0

package/README.md

@@ -70,8 +70,8 @@ Creates a `.platform-scaffold.json` manifest for projects scaffolded before v1.1
 | Tier | Workers | What You Get | Est. Cost |
 |------|---------|-------------|-----------|
 | **Minimal** | 1 | Budget enforcement, circuit breakers, usage telemetry | ~$0/mo |
-| **Standard** | 3 | + Error collector (auto GitHub issues), gap detection sentinel | ~$0/mo |
-| **Full** | 8 | + AI pattern discovery, alert router, notifications, search, settings | ~$5/mo |
+| **Standard** | 5 | + Error collector (auto GitHub issues), gap detection sentinel, mapper, test client | ~$0/mo |
+| **Full** | 11 | + AI pattern discovery, alert router, notifications, search, settings, auditor | ~$5/mo |
 
 See [Tier Comparison](../../docs/admin-sdk/tiers.md) for a detailed breakdown of what each tier generates.
 

package/dist/templates.d.ts

@@ -6,7 +6,7 @@
  */
 import type { Tier } from './prompts.js';
 /** Single source of truth for the SDK version. */
-export declare const SDK_VERSION = "2.0.0";
+export declare const SDK_VERSION = "2.1.0";
 /** Returns true if `to` is the same or higher tier than `from`. */
 export declare function isTierUpgradeOrSame(from: Tier, to: Tier): boolean;
 /** Check if a template file is a numbered migration (not seed.sql). */

package/dist/templates.js

@@ -5,7 +5,7 @@
  * All other files are copied verbatim.
  */
 /** Single source of truth for the SDK version. */
-export const SDK_VERSION = '2.0.0';
+export const SDK_VERSION = '2.1.0';
 /** Tier ordering for upgrade validation. */
 const TIER_ORDER = { minimal: 0, standard: 1, full: 2 };
 /** Returns true if `to` is the same or higher tier than `from`. */
@@ -169,6 +169,15 @@ const SHARED_FILES = [
     { src: 'shared/dashboard/src/pages/api/user/identity.ts', dest: 'dashboard/src/pages/api/user/identity.ts', template: false },
     // Dashboard — shared tier: cloudflare lib (v1.6.0)
     { src: 'shared/dashboard/src/lib/cloudflare/costs.ts', dest: 'dashboard/src/lib/cloudflare/costs.ts', template: false },
+    // Dashboard — shared tier: cloudflare lib (v2.1.0)
+    { src: 'shared/dashboard/src/lib/cloudflare/index.ts.hbs', dest: 'dashboard/src/lib/cloudflare/index.ts', template: true },
+    { src: 'shared/dashboard/src/lib/cloudflare/d1.ts', dest: 'dashboard/src/lib/cloudflare/d1.ts', template: false },
+    { src: 'shared/dashboard/src/lib/cloudflare/analytics.ts', dest: 'dashboard/src/lib/cloudflare/analytics.ts', template: false },
+    // Dashboard — shared tier: usage lib (v2.1.0)
+    { src: 'shared/dashboard/src/lib/usage/index.ts.hbs', dest: 'dashboard/src/lib/usage/index.ts', template: true },
+    { src: 'shared/dashboard/src/lib/usage/fetchWithDedup.ts', dest: 'dashboard/src/lib/usage/fetchWithDedup.ts', template: false },
+    // Dashboard — shared tier: infrastructure lib (v2.1.0)
+    { src: 'shared/dashboard/src/lib/infrastructure/types.ts', dest: 'dashboard/src/lib/infrastructure/types.ts', template: false },
     // Dashboard — shared tier: infrastructure components (v1.6.0)
     { src: 'shared/dashboard/src/components/infrastructure/InfrastructureStats.tsx', dest: 'dashboard/src/components/infrastructure/InfrastructureStats.tsx', template: false },
     { src: 'shared/dashboard/src/components/infrastructure/index.ts', dest: 'dashboard/src/components/infrastructure/index.ts', template: false },
@@ -206,6 +215,38 @@ const SHARED_FILES = [
     // Dashboard — shared tier: additional UI components (v2.0.0)
     { src: 'shared/dashboard/src/components/ui/ErrorBoundary.tsx', dest: 'dashboard/src/components/ui/ErrorBoundary.tsx', template: false },
     { src: 'shared/dashboard/src/components/ui/PageShell.tsx', dest: 'dashboard/src/components/ui/PageShell.tsx', template: false },
+    // Dashboard — shared tier: usage/unified components (v2.1.0)
+    { src: 'shared/dashboard/src/components/usage/unified/UnifiedShell.tsx', dest: 'dashboard/src/components/usage/unified/UnifiedShell.tsx', template: false },
+    { src: 'shared/dashboard/src/components/usage/unified/HeroCardsRow.tsx', dest: 'dashboard/src/components/usage/unified/HeroCardsRow.tsx', template: false },
+    { src: 'shared/dashboard/src/components/usage/unified/ResourceBreakdown.tsx', dest: 'dashboard/src/components/usage/unified/ResourceBreakdown.tsx', template: false },
+    { src: 'shared/dashboard/src/components/usage/unified/LiveHeader.tsx', dest: 'dashboard/src/components/usage/unified/LiveHeader.tsx', template: false },
+    { src: 'shared/dashboard/src/components/usage/unified/AlertBanner.tsx', dest: 'dashboard/src/components/usage/unified/AlertBanner.tsx', template: false },
+    { src: 'shared/dashboard/src/components/usage/unified/Sparkline.tsx', dest: 'dashboard/src/components/usage/unified/Sparkline.tsx', template: false },
+    { src: 'shared/dashboard/src/components/usage/unified/ProjectsTable.tsx', dest: 'dashboard/src/components/usage/unified/ProjectsTable.tsx', template: false },
+    { src: 'shared/dashboard/src/components/usage/unified/types.ts', dest: 'dashboard/src/components/usage/unified/types.ts', template: false },
+    { src: 'shared/dashboard/src/components/usage/unified/index.ts.hbs', dest: 'dashboard/src/components/usage/unified/index.ts', template: true },
+    // Dashboard — shared tier: usage/react components (v2.1.0)
+    { src: 'shared/dashboard/src/components/usage/react/StatusBadge.tsx', dest: 'dashboard/src/components/usage/react/StatusBadge.tsx', template: false },
+    { src: 'shared/dashboard/src/components/usage/react/UsageChart.tsx', dest: 'dashboard/src/components/usage/react/UsageChart.tsx', template: false },
+    { src: 'shared/dashboard/src/components/usage/react/DashboardShell.tsx', dest: 'dashboard/src/components/usage/react/DashboardShell.tsx', template: false },
+    { src: 'shared/dashboard/src/components/usage/react/types.ts', dest: 'dashboard/src/components/usage/react/types.ts', template: false },
+    { src: 'shared/dashboard/src/components/usage/react/index.ts.hbs', dest: 'dashboard/src/components/usage/react/index.ts', template: true },
+    // Dashboard — shared tier: usage utilities (v2.1.0)
+    { src: 'shared/dashboard/src/components/usage/transformers.ts', dest: 'dashboard/src/components/usage/transformers.ts', template: false },
+    // Dashboard — shared tier: reports components (v2.1.0)
+    { src: 'shared/dashboard/src/components/reports/ReportInfoButton.tsx', dest: 'dashboard/src/components/reports/ReportInfoButton.tsx', template: false },
+    // Tests — shared tier (v2.1.0)
+    { src: 'shared/tests/helpers/mock-storage.ts', dest: 'tests/helpers/mock-storage.ts', template: false },
+    { src: 'shared/tests/unit/billing.test.ts', dest: 'tests/unit/billing.test.ts', template: false },
+    { src: 'shared/tests/unit/economics.test.ts', dest: 'tests/unit/economics.test.ts', template: false },
+    { src: 'shared/tests/unit/control.test.ts', dest: 'tests/unit/control.test.ts', template: false },
+    { src: 'shared/tests/unit/cost-calculator.test.ts', dest: 'tests/unit/cost-calculator.test.ts', template: false },
+    { src: 'shared/tests/unit/telemetry-sampling.test.ts', dest: 'tests/unit/telemetry-sampling.test.ts', template: false },
+    { src: 'shared/tests/unit/cloudflare/graphql.test.ts', dest: 'tests/unit/cloudflare/graphql.test.ts', template: false },
+    { src: 'shared/tests/unit/components/usage-transformers.test.ts', dest: 'tests/unit/components/usage-transformers.test.ts', template: false },
+    { src: 'shared/tests/integration/platform-usage.test.ts', dest: 'tests/integration/platform-usage.test.ts', template: false },
+    { src: 'shared/tests/integration/kv-cache.test.ts', dest: 'tests/integration/kv-cache.test.ts', template: false },
+    { src: 'shared/tests/e2e/usage-api.test.ts', dest: 'tests/e2e/usage-api.test.ts', template: false },
     // CI — contract check + security workflows (v2.0.0)
     { src: 'shared/.github/workflows/contract-check.yml.hbs', dest: '.github/workflows/contract-check.yml', template: true },
     { src: 'shared/.github/workflows/security.yml', dest: '.github/workflows/security.yml', template: false },
@@ -255,7 +296,14 @@ const STANDARD_FILES = [
     { src: 'standard/dashboard/src/components/errors/ErrorsTable.tsx', dest: 'dashboard/src/components/errors/ErrorsTable.tsx', template: false },
     { src: 'standard/dashboard/src/components/errors/ErrorStats.tsx', dest: 'dashboard/src/components/errors/ErrorStats.tsx', template: false },
     { src: 'standard/dashboard/src/components/errors/index.ts', dest: 'dashboard/src/components/errors/index.ts', template: false },
-    { src: 'standard/dashboard/src/lib/errors.ts', dest: 'dashboard/src/lib/errors.ts', template: false },
+    // Dashboard — standard tier: lib modules (v2.1.0) — replaces old errors.ts
+    { src: 'standard/dashboard/src/lib/errors/types.ts', dest: 'dashboard/src/lib/errors/types.ts', template: false },
+    { src: 'standard/dashboard/src/lib/errors/api.ts', dest: 'dashboard/src/lib/errors/api.ts', template: false },
+    { src: 'standard/dashboard/src/lib/infrastructure/api.ts', dest: 'dashboard/src/lib/infrastructure/api.ts', template: false },
+    { src: 'standard/dashboard/src/lib/infrastructure/gatus.ts.hbs', dest: 'dashboard/src/lib/infrastructure/gatus.ts', template: true },
+    { src: 'standard/dashboard/src/lib/services/proxy/types.ts', dest: 'dashboard/src/lib/services/proxy/types.ts', template: false },
+    { src: 'standard/dashboard/src/lib/services/proxy/proxy.ts', dest: 'dashboard/src/lib/services/proxy/proxy.ts', template: false },
+    { src: 'standard/dashboard/src/lib/services/proxy/index.ts', dest: 'dashboard/src/lib/services/proxy/index.ts', template: false },
     // Dashboard — standard tier: error detail API routes (v1.6.0)
     { src: 'standard/dashboard/src/pages/api/errors/[fingerprint].ts', dest: 'dashboard/src/pages/api/errors/[fingerprint].ts', template: false },
     { src: 'standard/dashboard/src/pages/api/errors/[fingerprint]/mute.ts', dest: 'dashboard/src/pages/api/errors/[fingerprint]/mute.ts', template: false },
@@ -270,6 +318,21 @@ const STANDARD_FILES = [
     { src: 'standard/tests/unit/error-collector/capture.test.ts', dest: 'tests/unit/error-collector/capture.test.ts', template: false },
     // Dashboard — standard tier: audit history API route (v2.0.0)
     { src: 'standard/dashboard/src/pages/api/health/audit-history.ts', dest: 'dashboard/src/pages/api/health/audit-history.ts', template: false },
+    // Dashboard — standard tier: usage components (v2.1.0)
+    { src: 'standard/dashboard/src/components/usage/react/UsageTable.tsx', dest: 'dashboard/src/components/usage/react/UsageTable.tsx', template: false },
+    { src: 'standard/dashboard/src/components/usage/unified/FeatureBudgets.tsx', dest: 'dashboard/src/components/usage/unified/FeatureBudgets.tsx', template: false },
+    { src: 'standard/dashboard/src/components/usage/unified/CircuitBreakerEvents.tsx', dest: 'dashboard/src/components/usage/unified/CircuitBreakerEvents.tsx', template: false },
+    // Dashboard — standard tier: reports components (v2.1.0)
+    { src: 'standard/dashboard/src/components/reports/CircuitBreakerReport.tsx', dest: 'dashboard/src/components/reports/CircuitBreakerReport.tsx', template: false },
+    { src: 'standard/dashboard/src/components/reports/ErrorTrendsReport.tsx', dest: 'dashboard/src/components/reports/ErrorTrendsReport.tsx', template: false },
+    { src: 'standard/dashboard/src/components/reports/ProjectHealthTable.tsx', dest: 'dashboard/src/components/reports/ProjectHealthTable.tsx', template: false },
+    { src: 'standard/dashboard/src/components/reports/CostTrendsReport.tsx', dest: 'dashboard/src/components/reports/CostTrendsReport.tsx', template: false },
+    { src: 'standard/dashboard/src/components/reports/WarningDigestsTable.tsx', dest: 'dashboard/src/components/reports/WarningDigestsTable.tsx', template: false },
+    // Tests — standard tier (v2.1.0)
+    { src: 'standard/tests/unit/cloudflare/alerting.test.ts', dest: 'tests/unit/cloudflare/alerting.test.ts', template: false },
+    { src: 'standard/tests/unit/error-collector/dedup.test.ts', dest: 'tests/unit/error-collector/dedup.test.ts', template: false },
+    { src: 'standard/tests/unit/error-collector/github.test.ts', dest: 'tests/unit/error-collector/github.test.ts', template: false },
+    { src: 'standard/tests/integration/platform-sentinel.test.ts', dest: 'tests/integration/platform-sentinel.test.ts', template: false },
 ];
 const FULL_FILES = [
     // Additional migrations
@@ -363,6 +426,27 @@ const FULL_FILES = [
     { src: 'full/dashboard/src/components/reports/SdkAuditReport.tsx', dest: 'dashboard/src/components/reports/SdkAuditReport.tsx', template: false },
     { src: 'full/dashboard/src/components/reports/GapDetectionReport.tsx', dest: 'dashboard/src/components/reports/GapDetectionReport.tsx', template: false },
     { src: 'full/dashboard/src/components/reports/index.ts', dest: 'dashboard/src/components/reports/index.ts', template: false },
+    // Dashboard — full tier: lib modules (v2.1.0)
+    { src: 'full/dashboard/src/lib/cloudflare/graphql.ts', dest: 'dashboard/src/lib/cloudflare/graphql.ts', template: false },
+    { src: 'full/dashboard/src/lib/cloudflare/alerting.ts', dest: 'dashboard/src/lib/cloudflare/alerting.ts', template: false },
+    { src: 'full/dashboard/src/lib/cloudflare/project-registry.ts', dest: 'dashboard/src/lib/cloudflare/project-registry.ts', template: false },
+    { src: 'full/dashboard/src/lib/usage/allowance-config.ts.hbs', dest: 'dashboard/src/lib/usage/allowance-config.ts', template: true },
+    { src: 'full/dashboard/src/lib/usage/providers.ts', dest: 'dashboard/src/lib/usage/providers.ts', template: false },
+    { src: 'full/dashboard/src/lib/patterns/api.ts', dest: 'dashboard/src/lib/patterns/api.ts', template: false },
+    { src: 'full/dashboard/src/lib/patterns/types.ts', dest: 'dashboard/src/lib/patterns/types.ts', template: false },
+    { src: 'full/dashboard/src/lib/notifications/api.ts', dest: 'dashboard/src/lib/notifications/api.ts', template: false },
+    { src: 'full/dashboard/src/lib/notifications/types.ts.hbs', dest: 'dashboard/src/lib/notifications/types.ts', template: true },
+    { src: 'full/dashboard/src/lib/search/api.ts', dest: 'dashboard/src/lib/search/api.ts', template: false },
+    { src: 'full/dashboard/src/lib/search/types.ts.hbs', dest: 'dashboard/src/lib/search/types.ts', template: true },
+    { src: 'full/dashboard/src/lib/settings/api.ts.hbs', dest: 'dashboard/src/lib/settings/api.ts', template: true },
+    { src: 'full/dashboard/src/lib/settings/types.ts.hbs', dest: 'dashboard/src/lib/settings/types.ts', template: true },
+    { src: 'full/dashboard/src/lib/reports/types.ts', dest: 'dashboard/src/lib/reports/types.ts', template: false },
+    // Dashboard — full tier: usage components (v2.1.0)
+    { src: 'full/dashboard/src/components/usage/AIModelBreakdown.tsx', dest: 'dashboard/src/components/usage/AIModelBreakdown.tsx', template: false },
+    { src: 'full/dashboard/src/components/usage/unified/Recommendations.tsx', dest: 'dashboard/src/components/usage/unified/Recommendations.tsx', template: false },
+    // Dashboard — full tier: reports components (v2.1.0)
+    { src: 'full/dashboard/src/components/reports/HealthTrendsReport.tsx', dest: 'dashboard/src/components/reports/HealthTrendsReport.tsx', template: false },
+    { src: 'full/dashboard/src/components/reports/DigestStats.tsx', dest: 'dashboard/src/components/reports/DigestStats.tsx', template: false },
 ];
 export function getFilesForTier(tier) {
     const files = [...SHARED_FILES];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@littlebearapps/platform-admin-sdk",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Platform Admin SDK — scaffold backend infrastructure with workers, circuit breakers, and cost protection for Cloudflare",
   "type": "module",
   "bin": {

package/templates/full/dashboard/src/components/reports/DigestStats.tsx

@@ -0,0 +1,151 @@
+/**
+ * Digest Statistics Cards Component
+ * Shows warning digest summary stats and trends
+ */
+import { useState, useEffect } from 'react';
+import type { DigestStats as DigestStatsType } from '../../lib/reports/types';
+
+interface StatCardProps {
+  label: string;
+  value: number | string;
+  subValue?: string;
+  colour: string;
+  icon: string;
+}
+
+function StatCard({ label, value, subValue, colour, icon }: StatCardProps) {
+  return (
+    <div className={`bg-white dark:bg-gray-800 rounded-lg border border-gray-200 dark:border-gray-700 p-4 ${colour}`}>
+      <div className="flex items-center justify-between">
+        <div>
+          <p className="text-sm font-medium text-gray-600 dark:text-gray-400">{label}</p>
+          <p className="text-2xl font-bold mt-1">{value}</p>
+          {subValue && (
+            <p className="text-xs text-gray-500 dark:text-gray-400 mt-0.5">{subValue}</p>
+          )}
+        </div>
+        <span className="text-2xl">{icon}</span>
+      </div>
+    </div>
+  );
+}
+
+export function DigestStats() {
+  const [stats, setStats] = useState<DigestStatsType | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    async function fetchStats() {
+      try {
+        const response = await fetch('/api/reports/digests/stats');
+        if (!response.ok) throw new Error('Failed to fetch stats');
+        const data = await response.json();
+        setStats(data);
+      } catch (e) {
+        setError(e instanceof Error ? e.message : 'Unknown error');
+      } finally {
+        setLoading(false);
+      }
+    }
+    fetchStats();
+  }, []);
+
+  if (loading) {
+    return (
+      <div className="grid grid-cols-2 md:grid-cols-4 lg:grid-cols-6 gap-4">
+        {[...Array(6)].map((_, i) => (
+          <div key={i} className="bg-white dark:bg-gray-800 rounded-lg border border-gray-200 dark:border-gray-700 p-4 animate-pulse">
+            <div className="h-4 bg-gray-200 dark:bg-gray-700 rounded w-16 mb-2"></div>
+            <div className="h-8 bg-gray-200 dark:bg-gray-700 rounded w-12"></div>
+          </div>
+        ))}
+      </div>
+    );
+  }
+
+  if (error) {
+    return (
+      <div className="bg-red-50 dark:bg-red-900/20 border border-red-200 dark:border-red-800 rounded-lg p-4 text-red-700 dark:text-red-300">
+        Error loading stats: {error}
+      </div>
+    );
+  }
+
+  if (!stats) return null;
+
+  // Calculate trend (comparing today vs yesterday)
+  const todayOcc = stats.todayDigests.occurrences;
+  const yesterdayOcc = stats.yesterdayDigests.occurrences;
+  const trend = yesterdayOcc > 0
+    ? Math.round(((todayOcc - yesterdayOcc) / yesterdayOcc) * 100)
+    : todayOcc > 0 ? 100 : 0;
+  const trendText = trend > 0 ? `+${trend}%` : trend < 0 ? `${trend}%` : 'Same';
+
+  return (
+    <div className="space-y-4">
+      {/* Main Stats */}
+      <div className="grid grid-cols-2 md:grid-cols-4 lg:grid-cols-6 gap-4">
+        <StatCard
+          label="Today's Warnings"
+          value={stats.todayDigests.occurrences}
+          subValue={`${stats.todayDigests.count} digest(s)`}
+          colour="border-l-4 border-l-yellow-500"
+          icon="⚠️"
+        />
+        <StatCard
+          label="Yesterday"
+          value={stats.yesterdayDigests.occurrences}
+          subValue={`${stats.yesterdayDigests.count} digest(s)`}
+          colour="border-l-4 border-l-gray-400"
+          icon="📅"
+        />
+        <StatCard
+          label="Daily Trend"
+          value={trendText}
+          subValue={trend > 0 ? 'Increase' : trend < 0 ? 'Decrease' : 'No change'}
+          colour={`border-l-4 ${trend > 20 ? 'border-l-red-500' : trend < -20 ? 'border-l-green-500' : 'border-l-blue-500'}`}
+          icon={trend > 0 ? '📈' : trend < 0 ? '📉' : '➡️'}
+        />
+        <StatCard
+          label="Total Digests"
+          value={stats.totalDigests}
+          colour="border-l-4 border-l-purple-500"
+          icon="📊"
+        />
+        <StatCard
+          label="Total Occurrences"
+          value={stats.totalOccurrences.toLocaleString()}
+          colour="border-l-4 border-l-indigo-500"
+          icon="🔢"
+        />
+        <StatCard
+          label="Active Scripts"
+          value={stats.byScript.length}
+          colour="border-l-4 border-l-teal-500"
+          icon="📜"
+        />
+      </div>
+
+      {/* Top Warnings Summary */}
+      {stats.topWarnings.length > 0 && (
+        <div className="bg-white dark:bg-gray-800 rounded-lg border border-gray-200 dark:border-gray-700 p-4">
+          <h3 className="text-sm font-semibold text-gray-700 dark:text-gray-300 mb-3">Top Warning Types</h3>
+          <div className="space-y-2">
+            {stats.topWarnings.slice(0, 3).map((warning, i) => (
+              <div key={i} className="flex items-center justify-between text-sm">
+                <span className="text-gray-600 dark:text-gray-400 truncate max-w-md">
+                  {warning.normalized_message.slice(0, 60)}
+                  {warning.normalized_message.length > 60 && '...'}
+                </span>
+                <span className="text-gray-900 dark:text-white font-medium ml-2">
+                  {warning.occurrences.toLocaleString()} ({warning.days_occurred}d)
+                </span>
+              </div>
+            ))}
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}

package/templates/full/dashboard/src/components/reports/HealthTrendsReport.tsx

@@ -0,0 +1,192 @@
+/**
+ * Health Trends Report Component
+ * Shows project health score trends over time
+ */
+import { useState, useEffect } from 'react';
+
+interface HealthTrend {
+  project: string;
+  audit_date: string;
+  composite_score: number;
+  sdk_score: number;
+  observability_score: number;
+  cost_score: number;
+  security_score: number;
+  trend: 'improving' | 'stable' | 'declining';
+  score_delta: number;
+}
+
+function StatCard({ label, value, colour, subValue }: { label: string; value: number | string; colour: string; subValue?: string }) {
+  return (
+    <div className={`bg-white dark:bg-gray-800 rounded-lg border border-gray-200 dark:border-gray-700 p-4 ${colour}`}>
+      <p className="text-sm font-medium text-gray-600 dark:text-gray-400">{label}</p>
+      <p className="text-2xl font-bold mt-1">{value}</p>
+      {subValue && <p className="text-xs text-gray-500 dark:text-gray-400 mt-0.5">{subValue}</p>}
+    </div>
+  );
+}
+
+function TrendBadge({ trend, delta }: { trend: string; delta: number }) {
+  const config: Record<string, { colour: string; icon: string }> = {
+    improving: { colour: 'bg-green-100 text-green-800 dark:bg-green-900/30 dark:text-green-300', icon: '↑' },
+    stable: { colour: 'bg-gray-100 text-gray-800 dark:bg-gray-900/30 dark:text-gray-300', icon: '→' },
+    declining: { colour: 'bg-red-100 text-red-800 dark:bg-red-900/30 dark:text-red-300', icon: '↓' },
+  };
+  const { colour, icon } = config[trend] || config.stable;
+  return (
+    <span className={`px-2 py-0.5 text-xs font-semibold rounded inline-flex items-center gap-1 ${colour}`}>
+      {icon} {delta > 0 ? '+' : ''}{delta}
+    </span>
+  );
+}
+
+function ScoreBar({ score, max = 5, label }: { score: number; max?: number; label: string }) {
+  const percentage = (score / max) * 100;
+  const colour = percentage >= 80 ? 'bg-green-500' : percentage >= 60 ? 'bg-yellow-500' : 'bg-red-500';
+  return (
+    <div className="flex items-center gap-2">
+      <span className="w-24 text-xs text-gray-600 dark:text-gray-400">{label}</span>
+      <div className="flex-1 h-2 bg-gray-200 dark:bg-gray-700 rounded-full overflow-hidden">
+        <div className={`h-full ${colour}`} style={{ width: `${percentage}%` }} />
+      </div>
+      <span className="w-8 text-xs text-gray-900 dark:text-white text-right">{score}/{max}</span>
+    </div>
+  );
+}
+
+export function HealthTrendsReport() {
+  const [trends, setTrends] = useState<HealthTrend[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [days, setDays] = useState(30);
+
+  useEffect(() => {
+    async function fetchData() {
+      try {
+        setLoading(true);
+        const response = await fetch(`/api/usage/health-trends?days=${days}`);
+        if (!response.ok) throw new Error('Failed to fetch health trends');
+        const data = await response.json();
+
+        // API returns { success, data: [{ project, trends: [{ date, compositeScore, rubricScores, trend, delta }] }] }
+        // Flatten nested project→trends structure into flat array
+        const apiData = data.data || [];
+        const flatTrends: HealthTrend[] = [];
+        for (const proj of apiData) {
+          for (const t of proj.trends || []) {
+            flatTrends.push({
+              project: proj.project,
+              audit_date: t.date,
+              composite_score: t.compositeScore,
+              sdk_score: t.rubricScores?.sdk ?? 0,
+              observability_score: t.rubricScores?.observability ?? 0,
+              cost_score: t.rubricScores?.cost ?? 0,
+              security_score: t.rubricScores?.security ?? 0,
+              trend: t.trend,
+              score_delta: t.delta,
+            });
+          }
+        }
+        setTrends(flatTrends);
+      } catch (e) {
+        setError(e instanceof Error ? e.message : 'Unknown error');
+      } finally {
+        setLoading(false);
+      }
+    }
+    fetchData();
+  }, [days]);
+
+  if (loading) {
+    return (
+      <div className="space-y-4">
+        <div className="grid grid-cols-2 md:grid-cols-4 gap-4">
+          {[...Array(4)].map((_, i) => (
+            <div key={i} className="bg-white dark:bg-gray-800 rounded-lg border p-4 animate-pulse">
+              <div className="h-4 bg-gray-200 dark:bg-gray-700 rounded w-16 mb-2"></div>
+              <div className="h-8 bg-gray-200 dark:bg-gray-700 rounded w-12"></div>
+            </div>
+          ))}
+        </div>
+      </div>
+    );
+  }
+
+  if (error) {
+    return (
+      <div className="bg-red-50 dark:bg-red-900/20 border border-red-200 dark:border-red-800 rounded-lg p-4 text-red-700 dark:text-red-300">
+        Error loading health trends: {error}
+      </div>
+    );
+  }
+
+  const improving = trends.filter(t => t.trend === 'improving').length;
+  const stable = trends.filter(t => t.trend === 'stable').length;
+  const declining = trends.filter(t => t.trend === 'declining').length;
+  const avgScore = trends.length > 0
+    ? Math.round(trends.reduce((sum, t) => sum + t.composite_score, 0) / trends.length)
+    : 0;
+
+  // Group by project for latest trends
+  const latestByProject = new Map<string, HealthTrend>();
+  trends.forEach(t => {
+    if (!latestByProject.has(t.project) || t.audit_date > latestByProject.get(t.project)!.audit_date) {
+      latestByProject.set(t.project, t);
+    }
+  });
+  const latestTrends = Array.from(latestByProject.values()).sort((a, b) => b.composite_score - a.composite_score);
+
+  return (
+    <div className="space-y-6">
+      {/* Filter */}
+      <div className="flex items-center gap-4">
+        <label className="text-sm text-gray-600 dark:text-gray-400">Time range:</label>
+        <select
+          value={days}
+          onChange={(e) => setDays(Number(e.target.value))}
+          className="px-3 py-1.5 border border-gray-300 dark:border-gray-600 rounded-lg bg-white dark:bg-gray-800 text-sm"
+        >
+          <option value={7}>Last 7 days</option>
+          <option value={30}>Last 30 days</option>
+          <option value={90}>Last 90 days</option>
+        </select>
+      </div>
+
+      {/* Stats */}
+      <div className="grid grid-cols-2 md:grid-cols-4 gap-4">
+        <StatCard label="Improving" value={improving} colour="border-l-4 border-l-green-500" />
+        <StatCard label="Stable" value={stable} colour="border-l-4 border-l-gray-400" />
+        <StatCard label="Declining" value={declining} colour="border-l-4 border-l-red-500" />
+        <StatCard label="Avg Score" value={avgScore} colour="border-l-4 border-l-purple-500" />
+      </div>
+
+      {/* Project Health Cards */}
+      <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
+        {latestTrends.map((t) => (
+          <div key={t.project} className="bg-white dark:bg-gray-800 rounded-lg border border-gray-200 dark:border-gray-700 p-4">
+            <div className="flex items-center justify-between mb-3">
+              <h3 className="font-semibold text-gray-900 dark:text-white">{t.project}</h3>
+              <TrendBadge trend={t.trend} delta={t.score_delta} />
+            </div>
+            <div className="text-3xl font-bold text-gray-900 dark:text-white mb-4">
+              {t.composite_score}<span className="text-sm font-normal text-gray-500">/100</span>
+            </div>
+            <div className="space-y-2">
+              <ScoreBar score={t.sdk_score} label="SDK" />
+              <ScoreBar score={t.observability_score} label="Observability" />
+              <ScoreBar score={t.cost_score} label="Cost" />
+              <ScoreBar score={t.security_score} label="Security" />
+            </div>
+            <p className="text-xs text-gray-500 dark:text-gray-400 mt-3">Last audit: {t.audit_date}</p>
+          </div>
+        ))}
+      </div>
+
+      {latestTrends.length === 0 && (
+        <div className="bg-gray-50 dark:bg-gray-800 rounded-lg border p-8 text-center text-gray-500 dark:text-gray-400">
+          No health trend data available. Run the platform auditor to generate health scores.
+        </div>
+      )}
+    </div>
+  );
+}