@schandlergarcia/sf-web-components 1.9.62 → 1.9.64

package/.a4drules/features/pre-code-checklist.md

@@ -1,215 +1,26 @@
----
-paths:
-  - "**/pages/*.tsx"
-  - "**/components/pages/*.tsx"
----
+# Pre-Code Checklist
 
-# Pre-Code Checklist (MANDATORY)
+This is a reference checklist. For build instructions, use the phase files in `.a4drules/phases/`.
 
-Before writing any code for command center dashboards, verify these requirements from the PRD and skills.
+## Before creating a dashboard file
 
-## FIRST: Read These Files
+- [ ] File path: `src/pages/DashboardName.tsx` (NOT `src/components/pages/`)
+- [ ] File extension: `.tsx` (NOT `.jsx`)
+- [ ] Imports: `@/components/library` only (NOT `@/components/ui/`, NOT `lucide-react`)
+- [ ] Theme hook: `import { useThemeMode } from "@/components/library/theme/AppThemeProvider"`
+- [ ] Data hook: `import useDataSource from "@/components/library/data/useDataSource"` (default export)
 
-**Before writing a single line of code, read these files:**
-1. `.a4drules/skills/component-library/SKILL.md` (lines 15-40) - Import Pattern section
-2. `engine-command-center-prd.md` - Phase 1 Placeholder Rules section
-3. This file - Phase 1 Code Template section
+## Color Reference
 
-**Verify you know:**
-- [ ] Exact import statement for `useThemeMode` hook
-- [ ] What "Phase 1 placeholder" means (data panels ONLY, not entire dashboard)
-- [ ] Which colors are forbidden (`text-white`, `text-black`, `bg-black` without opacity)
-
-## File Creation Checklist
-
-When creating a new dashboard file, confirm:
-
-1. **File path:** `src/pages/DashboardName.tsx` (NOT `src/components/pages/`)
-2. **File extension:** `.tsx` (NOT `.jsx`) — this is a TypeScript project
-3. **Imports:** `@/components/library` ONLY (NOT `@/components/ui/`, NOT `lucide-react`, NOT `recharts`)
-4. **Import names:** Check SKILL.md for exact names — DO NOT guess or invent import names
-   - Theme toggle: `useThemeMode` (NOT `useAppTheme`, NOT `useTheme`)
-   - Data source: `import useDataSource from "..."` (default export, NOT named)
-5. **Colors:** Slate scale ONLY (NOT `text-white`, NOT `text-black`, NOT `bg-black`)
-
-## Phase 1 Code Template
-
-**START WITH THIS EXACT STRUCTURE:**
-
-```tsx
-import { GeoMap, BaseCard } from "@/components/library";
-import { useThemeMode } from "@/components/library/theme/AppThemeProvider";
-import { /* Heroicons */ } from "@heroicons/react/24/outline";
-
-export default function EngineDashboard() {
-  const { mode, toggle } = useThemeMode();
-
-  return (
-    <div className="flex flex-col bg-slate-50 dark:bg-slate-950">
-      {/* Header Bar - h-12, sticky, slate-900 bg */}
-      <header className="sticky top-0 z-50 flex h-12 items-center justify-between border-b border-slate-800 bg-slate-900 px-4">
-        {/* Logo + title with text-slate-50 (NOT text-white) */}
-      </header>
-
-      {/* Hero Map - fixed height h-[520px], GeoMap renders world automatically */}
-      <div className="relative h-[520px]">
-        <GeoMap width={960} height={520} theme={mode === "dark" ? "dark" : "light"} className="h-full w-full" />
-        
-        {/* Glass KPI overlays - positioned absolutely, text-slate-50 */}
-        <div className="absolute left-3 top-3 flex gap-2">
-          {/* 4 KPI divs with border-white/10, bg-black/40, backdrop-blur-md */}
-        </div>
-
-        {/* Flight status strip - positioned absolutely at bottom */}
-        <div className="absolute bottom-3 left-3 right-3 flex gap-2 overflow-x-auto">
-          {/* 4 flight divs with status badges */}
-        </div>
-      </div>
-
-      {/* Data Panels - natural flow, full-page scroll, 4 panels total */}
-      <div className="px-4 py-5">
-        <div className="space-y-6">
-          {/* Row 1: Disruptions (1/3) + Active Travelers (2/3) */}
-          <div className="grid grid-cols-1 items-start gap-4 lg:grid-cols-3">
-            <BaseCard>
-              <div className="flex h-48 items-center justify-center text-slate-400">
-                Disruptions Panel
-              </div>
-            </BaseCard>
-            <div className="lg:col-span-2">
-              <BaseCard>
-                <div className="flex h-48 items-center justify-center text-slate-400">
-                  Active Travelers Panel
-                </div>
-              </BaseCard>
-            </div>
-          </div>
-
-          {/* Row 2: Escalations (1/2) + Monthly Spend Chart (1/2) */}
-          <div className="grid grid-cols-1 items-start gap-4 lg:grid-cols-2">
-            <BaseCard>
-              <div className="flex h-48 items-center justify-center text-slate-400">
-                Escalations Panel
-              </div>
-            </BaseCard>
-            <BaseCard>
-              <div className="flex h-48 items-center justify-center text-slate-400">
-                Travel Spend Panel
-              </div>
-            </BaseCard>
-          </div>
-        </div>
-      </div>
-    </div>
-  );
-}
-```
-
-## During Code Generation Checklist
-
-As you write the dashboard code:
-
-1. **Every card** is a library component (MetricCard, ListCard, WidgetCard, etc.) — NO hand-rolled `<div className="bg-white border rounded...">`
-2. **Every chart** uses `ChartCard` + `D3Chart` or `GeoMap` — NO Recharts, NO Chart.js, NO custom SVG
-3. **Every color** uses semantic classes or slate scale — NO `text-white`, NO `bg-black`, NO hardcoded hex
-4. **Dark mode** on every element — `dark:` variants on all custom styling
-5. **Phase 1 scope - Build COMPLETE layout structure:**
-   - ✅ Outer container: `className="flex flex-col bg-slate-50 dark:bg-slate-950"` (NO `h-screen` - full-page scroll)
-   - ✅ Header bar (logo, title, actions) with slate scale colors (NO text-white)
-   - ✅ Header text: ONLY "ENGINE" + "Travel Command Center" (NO "Powered by..." branding in Phase 1)
-   - ✅ Hero map container: `className="relative h-[520px]"` (fixed height, NOT flex-based)
-   - ✅ Hero map (GeoMap component with NO markers/arcs/overlays PROPS, `className="h-full w-full"`)
-   - ✅ Glass KPI overlays (4 hardcoded KPIs, positioned absolutely over map)
-   - ✅ Flight status strip (4 hardcoded flights, positioned at map bottom)
-   - ✅ Data panels container: `className="px-4 py-5"` (NO `overflow-y-auto`, NO flex constraints - natural flow)
-   - ✅ **4 data panel placeholders** (2 rows: Disruptions/Travelers, Escalations/Destinations) - BaseCard with NO title prop, centered text
-   - ❌ **Phase 1 EXCLUDES:** Salesforce/Data Cloud branding (Phase 4), ChatBar (Phase 4), real data (Phase 2+)
-   - "Placeholder" means data panels below the map, NOT the header/overlays/map
-   - **Full-page scroll:** Entire dashboard scrolls naturally (map scrolls up as user scrolls down)
-
-## After Code Generation Checklist
-
-After writing the dashboard code:
-
-1. **Wiring:**
-   - [ ] `CommandCenter.tsx` imports your dashboard
-   - [ ] `Home.tsx` renders `CommandCenter`
-   - [ ] `routes.tsx` has correct routes
-
-2. **Completion:**
-   - [ ] All files wired correctly
-   - [ ] **DO NOT run `npm run dev` or `npm run validate:dashboard`** - not required for ANY phase completion
-
-## Color Reference (CRITICAL)
-
-**NEVER use these:**
-
-| ❌ FORBIDDEN | ✅ USE INSTEAD | Where |
-|-------------|---------------|-------|
+| Forbidden | Use instead | Where |
+|-----------|------------|-------|
 | `text-white` | `text-slate-50` | Header text, overlay text |
 | `text-black` | `text-slate-900` | Body text (light mode) |
 | `bg-black` | `bg-slate-900` or `bg-black/40` (with opacity) | Backgrounds |
-| `bg-white` | `bg-slate-50` | Page background (light mode) |
-
-**Exception:** `bg-black/40`, `bg-white/10`, `border-white/10` are allowed (opacity variants for glass effect)
-
-## Verification Checklist
-
-After building, you should see:
-- [ ] Header bar with Engine logo and "Travel Command Center" title
-- [ ] **World map visible** (blue/teal land on dark background OR gray land on light background)
-- [ ] 4 glass KPI boxes in top-left of map (semi-transparent with numbers)
-- [ ] 4 flight status boxes at bottom of map (with colored badges)
-- [ ] **4 white/dark cards below map** (2 rows: row 1 has 1/3 + 2/3 split, row 2 has 1/2 + 1/2 split)
-- [ ] Page scrolls when you scroll the data panels section
-- [ ] Theme toggle works (sun/moon icon in header)
-
-## Quick Reference
-
-| Question | Answer |
-|----------|--------|
-| File path? | `src/pages/EngineDashboard.tsx` |
-| Extension? | `.tsx` (TypeScript) |
-| Import from? | `@/components/library` |
-| Hook import? | `import { useThemeMode } from "@/components/library/theme/AppThemeProvider"` |
-| Colors? | Slate scale (`text-slate-50`, `bg-slate-900`) - NEVER `text-white` |
-| Cards? | Library components (MetricCard, ListCard, etc.) |
-| Charts? | `ChartCard` + `D3Chart` or `GeoMap` |
-| After building? | Wire into CommandCenter/Home/routes - DO NOT run dev server |
-
-## Common Mistakes to Avoid
-
-❌ `src/pages/EngineDashboard.tsx` → ✅ `src/pages/EngineDashboard.tsx`
-❌ `EngineDashboard.jsx` → ✅ `EngineDashboard.tsx`
-❌ `text-white` → ✅ `text-slate-50`
-❌ `bg-black` → ✅ `bg-slate-900`
-❌ `<div className="bg-white border rounded-lg p-4">` → ✅ `<BaseCard>` or `<WidgetCard>`
-❌ `import { Button } from '@/components/ui/button'` → ✅ `import { UIButton } from '@/components/library'`
-❌ `import { useAppTheme } from '@/components/library'` → ✅ `import { useThemeMode } from '@/components/library'`
-❌ `"Powered by Salesforce Data Cloud"` in Phase 1 → ✅ This is Phase 4 only (see PRD Section 10)
-❌ Running `npm run dev` after building → ✅ Not needed - validation is sufficient
-
-## Troubleshooting
-
-**If you get TypeScript error about imports:**
-1. ❌ DO NOT follow "did you mean default import?" suggestion
-2. ✅ READ `.a4drules/skills/component-library/SKILL.md` Import Pattern section
-3. ✅ USE the exact import shown in the docs
-
-**If map doesn't render:**
-1. ✅ Verify container has `style={{ flex: "1.15 1 0", minHeight: 0 }}`
-2. ✅ Verify GeoMap has `className="h-full w-full"`
-3. ✅ GeoMap shows world map automatically - no props needed
-
-**If colors look wrong:**
-1. ✅ Search your code for `text-white` - should be `text-slate-50`
-2. ✅ Search your code for `text-black` - should be `text-slate-900`
-3. ✅ Exception: `bg-black/40` and `border-white/10` (with opacity) are OK
-
-**If data panels don't scroll:**
-1. ✅ Verify data panels container has `overflow-y-auto` className
-2. ✅ Verify it has `style={{ flex: "1 1 0" }}`
 
-## Enforcement
+## After creating the dashboard
 
-This checklist is MANDATORY. Do not skip any step. Verify each item before moving to the next phase.
+- [ ] `CommandCenter.tsx` imports your dashboard
+- [ ] `Home.tsx` renders `CommandCenter`
+- [ ] `routes.tsx` has correct routes
+- [ ] DO NOT run `npm run dev` or `npm run validate:dashboard`

package/.a4drules/phases/phase-1-layout.md

@@ -0,0 +1,187 @@
+---
+name: engine-phase-1-layout
+description: >-
+  Phase 1 of the Engine Travel Command Center build. Creates the complete layout
+  skeleton with header, hero map, glass overlays, flight strip, and placeholder
+  data panels. Use this when the build prompt says "Phase 1" or "scaffold".
+---
+
+# Phase 1: Layout & Structure
+
+**Source of truth:** `engine-command-center-prd.md` (sections 3–6)
+
+**Goal:** Build the complete layout skeleton in one file. The hero map, glass KPI overlays, and flight status strip are real — only the 4 data panels below are placeholders.
+
+## File Setup
+
+Create `src/pages/EngineDashboard.tsx` (.tsx, NOT .jsx).
+
+## Code Template
+
+Copy this template, then fill in the `{/* TODO */}` sections using the PRD:
+
+```tsx
+import { GeoMap, BaseCard } from "@/components/library";
+import { useThemeMode } from "@/components/library/theme/AppThemeProvider";
+import {
+  GlobeAltIcon,
+  SunIcon,
+  MoonIcon,
+  BellIcon,
+  UsersIcon,
+  BanknotesIcon,
+  ShieldCheckIcon,
+  SparklesIcon,
+} from "@heroicons/react/24/outline";
+
+export default function EngineDashboard() {
+  const { mode, toggle } = useThemeMode();
+
+  return (
+    <div className="flex flex-col bg-slate-50 dark:bg-slate-950">
+      {/* ── HEADER BAR ─────────────────────────────────────────── */}
+      <header className="sticky top-0 z-50 flex h-12 items-center justify-between border-b border-slate-800 bg-slate-900 dark:bg-slate-950 px-4">
+        {/* Left: logo + title */}
+        <div className="flex items-center gap-2">
+          <div className="flex h-7 w-7 items-center justify-center rounded-md bg-brand-600">
+            <GlobeAltIcon className="h-4 w-4 text-slate-50" />
+          </div>
+          <span className="text-sm font-bold tracking-wider text-slate-50">ENGINE</span>
+          <span className="mx-2 h-4 w-px bg-slate-700" />
+          <span className="text-sm font-medium text-slate-300">Travel Command Center</span>
+        </div>
+        {/* Right: actions */}
+        <div className="flex items-center gap-3">
+          {/* ChatBar goes here in Phase 4 */}
+          <button className="relative text-slate-400 hover:text-slate-200">
+            <BellIcon className="h-5 w-5" />
+            <span className="absolute -right-1 -top-1 flex h-4 w-4 items-center justify-center rounded-full bg-rose-500 text-[10px] font-bold text-slate-50">3</span>
+          </button>
+          <button onClick={toggle} className="text-slate-400 hover:text-slate-200">
+            {mode === "dark" ? <SunIcon className="h-5 w-5" /> : <MoonIcon className="h-5 w-5" />}
+          </button>
+        </div>
+      </header>
+
+      {/* ── HERO MAP ───────────────────────────────────────────── */}
+      <div className="relative h-[520px]">
+        <GeoMap
+          width={960}
+          height={520}
+          theme={mode === "dark" ? "dark" : "light"}
+          className="h-full w-full"
+        />
+
+        {/* Glass KPI overlays — 4 pills, absolute top-left */}
+        <div className="absolute left-3 top-3 flex flex-wrap gap-2">
+          {[
+            { icon: UsersIcon, label: "Active Travelers", value: "8" },
+            { icon: BanknotesIcon, label: "Spend MTD", value: "$128.4K" },
+            { icon: ShieldCheckIcon, label: "Compliance", value: "75%" },
+            { icon: SparklesIcon, label: "Eva Resolved", value: "6 resolved" },
+          ].map((kpi) => (
+            <div
+              key={kpi.label}
+              className="flex items-center gap-2 rounded-lg border border-white/10 bg-black/40 px-3 py-1.5 backdrop-blur-md"
+            >
+              <kpi.icon className="h-4 w-4 text-brand-400" />
+              <div>
+                <div className="text-[10px] uppercase tracking-wider text-slate-300">{kpi.label}</div>
+                <div className="text-sm font-semibold text-slate-50">{kpi.value}</div>
+              </div>
+            </div>
+          ))}
+        </div>
+
+        {/* Flight status strip — absolute bottom */}
+        <div className="absolute bottom-3 left-3 right-3 flex gap-2 overflow-x-auto">
+          {[
+            { flight: "BA 286", route: "SFO → LHR", status: "In Air" },
+            { flight: "NH 109", route: "JFK → NRT", status: "In Air" },
+            { flight: "LH 431", route: "ORD → BER", status: "Delayed" },
+            { flight: "SQ 37",  route: "LAX → SIN", status: "Boarding" },
+          ].map((f) => (
+            <div
+              key={f.flight}
+              className="flex shrink-0 items-center gap-2 rounded-lg border border-white/10 bg-black/40 px-3 py-1.5 backdrop-blur-md"
+            >
+              <span className="text-sm font-medium text-slate-50">{f.flight}</span>
+              <span className="text-xs text-slate-400">{f.route}</span>
+              <span
+                className={`rounded-full px-2 py-0.5 text-[10px] font-semibold ${
+                  f.status === "In Air"   ? "bg-green-500/20 text-green-400" :
+                  f.status === "Delayed"  ? "bg-amber-500/20 text-amber-400" :
+                  f.status === "Boarding" ? "bg-sky-500/20 text-sky-400" :
+                                           "bg-slate-500/20 text-slate-400"
+                }`}
+              >
+                {f.status}
+              </span>
+            </div>
+          ))}
+        </div>
+      </div>
+
+      {/* ── DATA PANELS (placeholders) ─────────────────────────── */}
+      <div className="px-4 py-5">
+        <div className="space-y-6">
+          {/* Row 1: Disruptions (1/3) + Active Travelers (2/3) */}
+          <div className="grid grid-cols-1 items-start gap-4 lg:grid-cols-3">
+            <BaseCard>
+              <div className="flex h-48 items-center justify-center text-slate-400">
+                Disruptions Panel
+              </div>
+            </BaseCard>
+            <div className="lg:col-span-2">
+              <BaseCard>
+                <div className="flex h-48 items-center justify-center text-slate-400">
+                  Active Travelers Panel
+                </div>
+              </BaseCard>
+            </div>
+          </div>
+
+          {/* Row 2: Escalations (1/2) + Monthly Spend Chart (1/2) */}
+          <div className="grid grid-cols-1 items-start gap-4 lg:grid-cols-2">
+            <BaseCard>
+              <div className="flex h-48 items-center justify-center text-slate-400">
+                Escalations Panel
+              </div>
+            </BaseCard>
+            <BaseCard>
+              <div className="flex h-48 items-center justify-center text-slate-400">
+                Travel Spend Panel
+              </div>
+            </BaseCard>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+## Brand Tokens
+
+Update `src/styles/global.css` — replace the `--color-brand-*` palette inside the `@theme inline` block with the Engine teal palette from PRD section 3. Also add `--color-engine-savings: #16A34A`.
+
+## Wiring (all 3 required)
+
+1. **CommandCenter.tsx** — import `EngineDashboard` from `"../../pages/EngineDashboard"` and render it
+2. **Home.tsx** — import `CommandCenter` and render it
+3. **routes.tsx** — set `Home` as the index route, move `Search` to `/search`
+
+## Constraints (5 only)
+
+1. File MUST be `.tsx` in `src/pages/`
+2. Import ONLY from `@/components/library` and `@heroicons/react`
+3. Colors: slate scale only — NO `text-white`, `text-black`, `bg-black` (exception: `bg-black/40` with opacity is OK for glass)
+4. Full-page scroll — NO `h-screen` on outer container
+5. DO NOT run `npm run dev` or `npm run validate:dashboard` — phase is complete after wiring
+
+## Phase 1 does NOT include
+
+- Sample data (Phase 2)
+- ChatBar / Eva (Phase 4)
+- Salesforce signals like "Powered by..." (Phase 4)
+- Any `npm install` commands

package/.a4drules/phases/phase-2-components.md

@@ -0,0 +1,176 @@
+---
+name: engine-phase-2-components
+description: >-
+  Phase 2 of the Engine Travel Command Center build. Replaces placeholder panels
+  with library components wired to pre-existing sample data. Adds map data.
+  Use this when the build prompt says "Phase 2" or "components".
+---
+
+# Phase 2: Components & Sample Data
+
+**Source of truth:** `engine-command-center-prd.md` (sections 7–8)
+
+**Goal:** Replace the 4 placeholder data panels with real library components. Add map data (markers, arcs, overlays). The sample data file already exists — just import from it.
+
+## Critical: Data file already exists
+
+`src/data/engine-sample-data.js` is pre-built with ~370 lines of sample data. **DO NOT create a new data file.** Just import from the existing one.
+
+## Imports to add to EngineDashboard.tsx
+
+```tsx
+import {
+  GeoMap,
+  BaseCard,
+  ActivityCard,
+  ChartCard,
+  D3Chart,
+  D3ChartTemplates,
+  Avatar,
+  UIChip,
+} from "@/components/library";
+import useDataSource from "@/components/library/data/useDataSource";
+import {
+  MAP_MARKERS,
+  MAP_ARCS,
+  MAP_OVERLAYS,
+  FLIGHT_STATUS_LIST,
+  TRAVELER_CARDS,
+  DISRUPTION_CARDS,
+  ESCALATION_CARDS,
+  MONTHLY_SPEND,
+  METRICS,
+} from "@/data/engine-sample-data";
+```
+
+## Changes to make
+
+### 1. Hero Map — add data props
+
+```tsx
+<GeoMap
+  width={960}
+  height={520}
+  theme={mode === "dark" ? "dark" : "light"}
+  markers={useDataSource({ sample: MAP_MARKERS, live: [] })}
+  arcs={useDataSource({ sample: MAP_ARCS, live: [] })}
+  overlays={useDataSource({ sample: MAP_OVERLAYS, live: [] })}
+  zoomable
+  className="h-full w-full"
+/>
+```
+
+### 2. Glass KPI overlays — use METRICS
+
+Replace hardcoded KPI values with `METRICS.activeTravelers`, `METRICS.spendMTD`, `METRICS.complianceRate`, `METRICS.evaResolved`.
+
+Use `fmtK()` helper for spend formatting:
+
+```tsx
+function fmtK(n: number) {
+  if (n >= 1e6) return `${(n / 1e6).toFixed(1)}M`;
+  if (n >= 1e3) return `${(n / 1e3).toFixed(1)}K`;
+  return n.toLocaleString();
+}
+```
+
+### 3. Flight status strip — use FLIGHT_STATUS_LIST
+
+Replace hardcoded flights with `FLIGHT_STATUS_LIST.map(...)`.
+
+### 4. Disruptions Panel (1/3 width) — custom inline component
+
+Replace the placeholder BaseCard. Build a custom panel inside a BaseCard showing only disrupted flights. Each disruption card shows severity dot, flight number, route, traveler, reason, and Eva action.
+
+```tsx
+<BaseCard>
+  <div className="space-y-3 p-1">
+    <h3 className="text-sm font-semibold text-slate-900 dark:text-slate-50">Disruptions</h3>
+    {useDataSource({ sample: DISRUPTION_CARDS, live: [] }).map((d) => (
+      <div key={d.id} className="rounded-lg border border-slate-200 p-3 dark:border-slate-800">
+        <div className="flex items-center gap-2">
+          <span className={`h-2 w-2 rounded-full ${d.severity === "grounded" ? "bg-rose-500" : "bg-amber-500"}`} />
+          <span className="text-sm font-medium text-slate-900 dark:text-slate-50">{d.flight}</span>
+          <span className={`text-xs ${d.severity === "grounded" ? "text-rose-500" : "text-amber-500"}`}>
+            {d.severity} · {d.delayMin}min
+          </span>
+        </div>
+        <div className="mt-1 text-xs text-slate-500 dark:text-slate-400">{d.route} · {d.traveler}</div>
+        <div className="mt-1 text-xs text-slate-500 dark:text-slate-400">{d.reason}</div>
+        <div className="mt-2 flex items-center gap-1 text-xs text-brand-600 dark:text-brand-400">
+          <SparklesIcon className="h-3 w-3" />
+          <span>{d.evaAction}</span>
+        </div>
+      </div>
+    ))}
+  </div>
+</BaseCard>
+```
+
+### 5. Active Travelers (2/3 width) — expandable cards
+
+Replace the placeholder. Use BaseCard with `maxBodyHeight={420}` for internal scroll. Build expandable traveler rows using `useState` for the expanded ID.
+
+Each row: Avatar (initials) + name + department + origin → destination + UIChip for policy status. Click to expand shows 4-col detail grid (Flight, Hotel, Return, Destination).
+
+### 6. Escalations (1/2 width) — ActivityCard in BaseCard
+
+**Copy this exactly from the PRD:**
+
+```tsx
+<BaseCard>
+  <ActivityCard
+    title="Escalations"
+    actions={useDataSource({ sample: ESCALATION_CARDS, live: [] })}
+  />
+</BaseCard>
+```
+
+ActivityCard MUST be wrapped in BaseCard for visible card styling.
+
+### 7. Monthly Spend Trend (1/2 width) — ChartCard + D3Chart
+
+**Copy this exactly from the PRD:**
+
+```tsx
+const spendChartData = useDataSource({
+  sample: MONTHLY_SPEND.map(m => ({ x: m.month, spend: m.amount })),
+  live: [],
+});
+
+<ChartCard
+  title="Travel Spend"
+  subtitle="Monthly trend (6 months)"
+  chart={
+    <D3Chart
+      data={spendChartData}
+      renderChart={D3ChartTemplates.groupedBarChart}
+      options={{
+        xKey: "x",
+        groups: ["spend"],
+        colors: ["#5BC8C8"],
+        barRadius: 6,
+        margin: { top: 20, right: 20, bottom: 40, left: 60 },
+        showGrid: true,
+      }}
+      responsive
+      height={320}
+    />
+  }
+/>
+```
+
+## Constraints (5 only)
+
+1. **DO NOT create a new data file** — import from the existing `src/data/engine-sample-data.js`
+2. Import ONLY from `@/components/library` and `@heroicons/react` — no shadcn, no Lucide, no Recharts
+3. Wrap `ActivityCard` in `BaseCard` (ActivityCard has no card styling by default)
+4. Use `useDataSource({ sample: X, live: [] })` for all data — enables Phase 3 swap
+5. DO NOT run `npm run dev` or `npm run validate:dashboard`
+
+## Phase 2 does NOT include
+
+- Live Salesforce data (Phase 3)
+- ChatBar / Eva (Phase 4)
+- Salesforce signals (Phase 4)
+- Any `npm install` commands

package/.a4drules/phases/phase-3-live-data.md

@@ -0,0 +1,85 @@
+---
+name: engine-phase-3-live-data
+description: >-
+  Phase 3 of the Engine Travel Command Center build. Connects the dashboard to
+  live Salesforce Data Cloud via GraphQL. UI stays identical to Phase 2.
+  Use this when the build prompt says "Phase 3" or "real data".
+---
+
+# Phase 3: Real Data Integration
+
+**Source of truth:** `engine-command-center-prd.md` (section 13)
+
+**Goal:** Connect the dashboard to live Salesforce data via GraphQL. The UI stays identical to Phase 2 — only the data source changes.
+
+## Approach
+
+The sample data file (`src/data/engine-sample-data.js`) already uses real Salesforce field names (Trip__c, Flight__c, Contact, etc.). Read the file header to understand the schema.
+
+## Custom objects
+
+| Object | Purpose |
+|--------|---------|
+| Contact | Travelers (with Home_Airport__c, Travel_Policy_Tier__c, etc.) |
+| Trip__c | Origin, destination, dates, cost, policy status |
+| Flight__c | Flight number, airports, status, delay, traveler lookup |
+| Booking__c | Upcoming reservations |
+| Disruption__c | Delays, cancellations, severity |
+| Rebooking_Action__c | Eva activity log |
+| Travel_Policy__c | Policy rules and status |
+
+## Implementation steps
+
+### Step 1: Read the sample data file
+
+Read `src/data/engine-sample-data.js` to understand which Salesforce fields are needed for each object.
+
+### Step 2: Use GraphQL skills to create queries and hooks
+
+For each object, use the Salesforce GraphQL skills:
+
+1. Use the `exploring-webapp-graphql-schema` skill to look up the object in `schema.graphql`
+2. Use the `generating-webapp-graphql-read-query` skill to create a typed query
+3. Use the `using-webapp-graphql` skill to create a data hook (e.g., `useTravelers`, `useFlights`)
+
+Each hook returns `{ data, loading, error }`.
+
+### Step 3: Update useDataSource calls
+
+Change each `useDataSource` call to include live data:
+
+```tsx
+// Phase 2 (sample only)
+const travelers = useDataSource({ sample: TRAVELER_CARDS, live: [] });
+
+// Phase 3 (live with sample fallback)
+const { data: liveTravelers, loading, error } = useTravelers();
+const travelers = useDataSource({
+  sample: TRAVELER_CARDS,
+  live: liveTravelers ?? [],
+});
+```
+
+The `useDataSource` hook automatically uses `live` when available, falling back to `sample` on error.
+
+### Step 4: Add loading and error states
+
+Add `loading` and `error` handling to each section. Library card components accept `loading` and `error` props.
+
+## Data strategy
+
+The app uses a sample data cache (`ENABLE_SAMPLE_DATA_CACHE = true` in `src/lib/dataStrategy.ts`) for instant loading and offline capability. This is production-appropriate — build all GraphQL queries and hooks as normal.
+
+## Constraints (5 only)
+
+1. **DO NOT modify UI components** — only change data sources
+2. **DO NOT add DataModeToggle** — live data only (sample is fallback for errors)
+3. Use exact Salesforce field names from the sample data file
+4. Schema file (`schema.graphql`) is pre-built in the repo — no generation needed
+5. DO NOT run `npm run dev` or `npm run validate:dashboard`
+
+## Phase 3 does NOT include
+
+- ChatBar / Eva (Phase 4)
+- Salesforce signals (Phase 4)
+- UI changes of any kind