@schandlergarcia/sf-web-components 1.9.75 → 1.9.77

package/.a4drules/features/command-center-dashboard-rule.md

@@ -8,6 +8,22 @@ paths:
 
 These rules apply to all dashboard files. For Engine-specific rules, see `engine-dashboard-rule.md`.
 
+**Read `.a4drules/skills/command-center-builder/SKILL.md` before building any dashboard.** It has the full conventions, component rules, and wiring steps.
+
+## Wiring — MANDATORY (do not skip)
+
+After creating a dashboard, you MUST update all 3 files or the dashboard will never appear:
+
+1. **`CommandCenter.tsx`** — import and render your dashboard (change only the import line)
+2. **`Home.tsx`** — REWRITE to render `CommandCenter` (it ships as Account Search by default):
+   ```tsx
+   import CommandCenter from "@/components/workspace/CommandCenter";
+   export default function HomePage() { return <CommandCenter />; }
+   ```
+3. **`routes.tsx`** — set `Home` as index route with label "Dashboard", move Search to `/search`
+
+**If you skip this, the user sees the Account Search page instead of your dashboard.**
+
 ## Core Constraints
 
 1. Dashboard files: `.tsx` in `src/pages/` — never `.jsx`, never `src/components/pages/`
@@ -21,13 +37,6 @@ These rules apply to all dashboard files. For Engine-specific rules, see `engine
 9. DO NOT run `npm run dev`, `npm run validate:dashboard`, or `npm run build` during builds
 10. DO NOT `npm install` any packages — everything needed is already installed
 
-## Wiring
-
-After creating a dashboard, update all 3 files:
-1. `CommandCenter.tsx` — import and render your dashboard
-2. `Home.tsx` — render `CommandCenter`
-3. `routes.tsx` — set `Home` as index route
-
 ## Component API
 
 For full component props and data shapes, read `.a4drules/skills/component-library/SKILL.md`.

package/.a4drules/features/engine-dashboard-rule.md

@@ -33,13 +33,19 @@ These rules load automatically when editing Engine dashboard files. For full bui
 
 Complete each phase fully before starting the next. Read the relevant phase file for detailed instructions and code templates.
 
-## Wiring Checklist
+## Wiring Checklist — MANDATORY
 
-After creating or updating `EngineDashboard.tsx`:
+After creating or updating `EngineDashboard.tsx`, update ALL 3 files:
 
-1. `CommandCenter.tsx` imports `EngineDashboard` (not `BlankDashboard`)
-2. `Home.tsx` renders `CommandCenter`
-3. `routes.tsx` has `Home` as index route, `Search` at `/search`
+1. **`CommandCenter.tsx`** — imports `EngineDashboard` (not `BlankDashboard`)
+2. **`Home.tsx`** — REWRITE to render `CommandCenter` (it ships as Account Search by default):
+   ```tsx
+   import CommandCenter from "@/components/workspace/CommandCenter";
+   export default function HomePage() { return <CommandCenter />; }
+   ```
+3. **`routes.tsx`** — has `Home` as index route with label "Dashboard", `Search` at `/search`
+
+**If you skip steps 2-3, the user sees the Account Search page instead of the dashboard.**
 
 ## Component Quick Reference
 

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

@@ -1,6 +1,6 @@
 # Pre-Code Checklist
 
-This is a reference checklist. For build instructions, use the phase files in `.a4drules/phases/`.
+Read `.a4drules/skills/command-center-builder/SKILL.md` before building. It has the full conventions and wiring steps.
 
 ## Before creating a dashboard file
 
@@ -18,9 +18,32 @@ This is a reference checklist. For build instructions, use the phase files in `.
 | `text-black` | `text-slate-900` | Body text (light mode) |
 | `bg-black` | `bg-slate-900` or `bg-black/40` (with opacity) | Backgrounds |
 
-## After creating the dashboard
+## After creating the dashboard — WIRE IT (MANDATORY)
 
-- [ ] `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`
+**All 3 steps are required or the dashboard will never render on screen.**
+
+- [ ] **`CommandCenter.tsx`** — change the import to your dashboard:
+  ```tsx
+  // src/components/workspace/CommandCenter.tsx
+  import MyDashboard from "../../pages/MyDashboard"; // ← your dashboard
+  // ... render <MyDashboard /> inside the existing providers
+  ```
+
+- [ ] **`Home.tsx`** — REPLACE the entire file (it ships as Account Search by default):
+  ```tsx
+  // src/pages/Home.tsx — REPLACE EVERYTHING
+  import CommandCenter from "@/components/workspace/CommandCenter";
+  export default function HomePage() {
+    return <CommandCenter />;
+  }
+  ```
+
+- [ ] **`routes.tsx`** — set Home as the index route with label "Dashboard":
+  ```tsx
+  { index: true, element: <Home />, handle: { showInNavigation: true, showNavBar: true, label: "Dashboard" } },
+  { path: "search", element: <Search />, handle: { showInNavigation: true, showNavBar: true, label: "Search" } },
+  ```
+
+- [ ] DO NOT run `npm run dev` or `npm run validate:dashboard` during builds
+
+**If you skip the wiring steps, the user will see the Account Search page instead of your dashboard.**

package/.a4drules/skills/command-center-builder/SKILL.md

@@ -13,15 +13,133 @@ description: >-
 
 These rules apply when building dashboards rendered by `CommandCenter.tsx`. For full component API details, read the **component-library** skill.
 
+> **BUILD GUIDE:** The dashboard is built in 3 phases. Read [`getting-started.md`](getting-started.md) for what to build (and what to skip) in each phase. Do NOT build ahead — only build what the current phase asks for.
+
+## WIRING — DO THIS FIRST (before building the dashboard)
+
+**Building a dashboard requires updating 4 files. If you only create the dashboard file, the user will never see it — they'll see the old Account Search page instead.**
+
+Read the existing `Home.tsx`, `CommandCenter.tsx`, and `routes.tsx` BEFORE you start building. Plan all 4 file changes up front:
+
+1. `src/pages/YourDashboard.tsx` — the dashboard component
+2. `src/components/workspace/CommandCenter.tsx` — import and render your dashboard
+3. `src/pages/Home.tsx` — **MUST be rewritten** to render CommandCenter (it ships as Account Search)
+4. `src/routes.tsx` — set Home as index route with label "Dashboard"
+
+**Home.tsx ships as an Account Search page by default.** You MUST replace its entire contents:
+
+```tsx
+// src/pages/Home.tsx — REPLACE the entire file
+import CommandCenter from "@/components/workspace/CommandCenter";
+
+export default function HomePage() {
+  return <CommandCenter />;
+}
+```
+
+**CommandCenter.tsx** — only change the dashboard import. Preserve the `heroui-scope` wrapper and `Toast.Provider`:
+
+```tsx
+// src/components/workspace/CommandCenter.tsx
+import AppThemeProvider from "@/components/library/theme/AppThemeProvider";
+import DataModeProvider from "@/components/library/data/DataModeProvider";
+import { Toast } from "@heroui/react";
+import MyDashboard from "../../pages/MyDashboard";  // ← change ONLY this import
+
+export default function CommandCenter() {
+  return (
+    <div className="heroui-scope">
+      <AppThemeProvider initialMode="light">
+        <DataModeProvider initialMode="sample">
+          <MyDashboard />
+          <Toast.Provider placement="bottom end" />
+        </DataModeProvider>
+      </AppThemeProvider>
+    </div>
+  );
+}
+```
+
+**routes.tsx** — make Home the index route, move Search to `/search`:
+
+```tsx
+{
+  index: true,
+  element: <Home />,
+  handle: { showInNavigation: true, showNavBar: true, label: "Dashboard" }
+},
+{
+  path: "search",
+  element: <Search />,
+  handle: { showInNavigation: true, showNavBar: true, label: "Search" }
+},
+```
+
+**After writing all files, verify:**
+1. Your dashboard `.tsx` file exists in `src/pages/`
+2. `CommandCenter.tsx` imports your dashboard (not `BlankDashboard`)
+3. `Home.tsx` imports and renders `CommandCenter` (NOT the Account Search interface)
+4. `routes.tsx` has `Home` as the index route with label "Dashboard"
+
+**If any of these are missing, the dashboard will not render.** This is the #1 cause of "I built the dashboard but I can't see it."
+
+---
+
+## Quick Import Reference
+
+Use these exact imports. Do NOT read component source files to discover imports — this list is authoritative.
+
+```tsx
+// Library components — named imports from barrel
+import {
+  BaseCard, MetricCard, ChartCard, TableCard, ListCard, ActivityCard,
+  StatusCard, WidgetCard, SectionCard, FeedPanel, CalloutCard, ActionList,
+  MetricsStrip, D3Chart, D3ChartTemplates, GeoMap, Avatar, UIButton,
+  UIChip, UIText, EmptyState, Spinner, ChatBar, FilterBar,
+  FormModal, toast,
+} from "@/components/library";
+
+// Theme — named export
+import { useThemeMode } from "@/components/library/theme/AppThemeProvider";
+
+// Data — DEFAULT export (no braces)
+import useDataSource from "@/components/library/data/useDataSource";
+
+// Icons — Heroicons ONLY (not Lucide) — use 24/outline by default
+import {
+  UsersIcon, BellIcon, SunIcon, MoonIcon, SparklesIcon,
+  CheckCircleIcon, ArrowPathIcon, ClockIcon, BanknotesIcon,
+  ShieldCheckIcon, ChevronDownIcon, ChevronUpIcon,
+  ExclamationTriangleIcon, PaperAirplaneIcon, BuildingOfficeIcon,
+  MapPinIcon, GlobeAltIcon, UserIcon,
+} from "@heroicons/react/24/outline";
+
+// Sample data
+import {
+  MAP_MARKERS, MAP_ARCS, MAP_OVERLAYS, FLIGHT_STATUS_LIST,
+  TRAVELER_CARDS, DISRUPTION_CARDS, ESCALATION_CARDS,
+  MONTHLY_SPEND, METRICS,
+} from "@/data/engine-sample-data.js";
+
+// Logo
+import engineLogo from "@/assets/images/engine_logo.png";
+```
+
+**Common mistakes:** `PlaneIcon` doesn't exist (use `PaperAirplaneIcon`), `HotelIcon` doesn't exist (use `BuildingOfficeIcon`), `import { useDataSource }` fails (it's a default export — no braces).
+
+---
+
 ## Core Conventions
 
 The following conventions apply to all dashboard development in this project.
 
-Before writing any code, read `.a4drules/features/pre-code-checklist.md` and verify all requirements. The most common mistakes are:
+The most common mistakes are:
+- **Forgetting to update Home.tsx and routes.tsx** (dashboard exists but never renders)
 - Creating `.jsx` instead of `.tsx` files
 - Creating files in `src/components/pages/` instead of `src/pages/`
 - Using forbidden colors (`text-white`, `bg-black`)
 - Hand-rolling HTML cards instead of using library components
+- Reading component source files instead of using this skill's documentation
 
 1. **Write `.tsx` files** in `src/pages/` and update `CommandCenter.tsx` to import the dashboard. This is a TypeScript project — all React components use `.tsx` extension.
 
@@ -106,85 +224,12 @@ The logo is black — use `brightness-0 invert` to make it white when placed on
 
 No `<nav>`, header bar, tab bar, or content-swapping via `useState("activeTab")` inside dashboard pages. The app shell handles navigation. Dashboards are single scrollable pages — all content visible by scrolling.
 
-## Where Dashboards Live & How to Wire Them
+## Where Dashboards Live
 
 - Dashboard page files: `src/pages/` (e.g. `EngineDashboard.tsx`, `FleetDashboard.tsx`) — **NOT** `src/components/pages/`
 - File format: `.tsx` (MUST be TypeScript) — this is a TypeScript project, all React components use `.tsx`, NEVER `.jsx`.
 - `CommandCenter.tsx` wraps with `heroui-scope` div + `AppThemeProvider` + `DataModeProvider` + `Toast.Provider` from `@heroui/react`. **Never recreate these providers in dashboard pages.** When wiring a new dashboard, only change the import — preserve the `heroui-scope` wrapper and `Toast.Provider` exactly as-is. For toasts inside dashboards, import `toast` from `@heroui/react` (or `@/components/library`) — NOT from `sonner`.
-
-### Wiring a new dashboard (REQUIRED STEPS)
-
-All three steps are required for the dashboard to render:
-
-**Step 1:** Create the dashboard file in `src/pages/` (NOT `src/components/pages/`):
-```tsx
-// src/pages/MyDashboard.tsx (NOTE: .tsx NOT .jsx, in src/pages/ NOT src/components/pages/)
-import React from "react";
-import { MetricCard, ListCard, ChartCard, D3Chart } from "@/components/library";
-
-export default function MyDashboard() {
-  return (
-    <div className="space-y-6 p-6">
-      {/* dashboard content using library components */}
-    </div>
-  );
-}
-```
-
-**Step 2:** Update `CommandCenter.tsx` to import and render it. Only change the import line — preserve `heroui-scope` and `Toast.Provider`:
-```tsx
-// src/components/workspace/CommandCenter.tsx
-import AppThemeProvider from "@/components/library/theme/AppThemeProvider";
-import DataModeProvider from "@/components/library/data/DataModeProvider";
-import { Toast } from "@heroui/react";
-import MyDashboard from "../../pages/MyDashboard";  // ← change ONLY this import
-
-export default function CommandCenter() {
-  return (
-    <div className="heroui-scope">                   {/* ← preserve this wrapper */}
-      <AppThemeProvider initialMode="light">
-        <DataModeProvider initialMode="sample">
-          <MyDashboard />                             {/* ← change this */}
-          <Toast.Provider placement="bottom end" />   {/* ← preserve this */}
-        </DataModeProvider>
-      </AppThemeProvider>
-    </div>
-  );
-}
-```
-
-**Step 2.5:** Update `Home.tsx` to render `CommandCenter`:
-```tsx
-// src/pages/Home.tsx
-import CommandCenter from "@/components/workspace/CommandCenter";
-
-export default function HomePage() {
-  return <CommandCenter />;
-}
-```
-
-**Step 3:** Update `src/routes.tsx` to make the dashboard the home page. Replace the Search page index route with the Home/CommandCenter route:
-```tsx
-// src/routes.tsx — change the index route
-{
-  index: true,
-  element: <SuspenseWrap><Home /></SuspenseWrap>,
-  handle: { showInNavigation: true, label: 'Dashboard' }
-},
-{
-  path: "search",
-  element: <SuspenseWrap><Search /></SuspenseWrap>,
-  handle: { showInNavigation: true, label: 'Search' }
-},
-```
-
-The `Home` page renders `CommandCenter`, which renders your dashboard. The Search page moves to `/search`.
-
-**Verify:** After writing all files, confirm:
-1. Your dashboard `.tsx` file exists in `src/pages/`
-2. `CommandCenter.tsx` (in `src/components/workspace/`) imports your dashboard (not `BlankDashboard`)
-3. `Home.tsx` (in `src/pages/`) imports and renders `CommandCenter` (not search interface)
-4. `src/routes.tsx` has `Home` as the index route and `Search` at `/search`
+- **Wiring is covered at the top of this file** — see "WIRING — DO THIS FIRST".
 
 ## Page Structure
 

package/.a4drules/skills/command-center-builder/getting-started.md

@@ -1 +1,98 @@
-See SKILL.md — Core Conventions, Library Components, Images, Navigation sections.
+# Engine Travel Command Center — Build Guide
+
+The dashboard is built in **3 phases**, one per user prompt. Each phase adds a layer. Do NOT build ahead — only build what the current phase asks for.
+
+---
+
+## Phase 1 — Build the Dashboard (sample data only)
+
+**What to build:**
+- `src/pages/EngineDashboard.tsx` with:
+  - Sticky header (h-12, Engine logo, "Travel Command Center", "Powered by Agentforce" badge, bell icon, theme toggle)
+  - Hero GeoMap (h-[520px]) with markers, arcs, overlays from sample data
+  - Glass KPI overlays on the map (Active Travelers, Spend MTD, Compliance %, Eva Resolved)
+  - Flight status strip (horizontal scroll, glass pills)
+  - Escalations panel (BaseCard with "Assign to Agent" buttons, toast on click)
+  - Disruptions panel (severity dots, flight info, Eva action lines)
+  - Active Travelers panel (expandable cards with Avatar, details grid, "View in Salesforce" links)
+  - Monthly Spend chart (ChartCard + D3Chart groupedBarChart)
+- All data from `src/data/engine-sample-data.js` via `useDataSource({ sample: SAMPLE_DATA, live: [] })`
+- Brand tokens in `global.css`
+
+**What to wire:**
+- `CommandCenter.tsx` → import EngineDashboard
+- `Home.tsx` → REPLACE with CommandCenter wrapper
+- `routes.tsx` → Home as index route with label "Dashboard"
+
+**What NOT to build (saved for later phases):**
+- No ChatBar or Eva AI chat — that's Phase 3
+- No AgentforceConversationClient — that's Phase 3
+- No `useEngineLiveData` or live data wiring — that's Phase 2
+- No Salesforce metadata (custom fields, platform events, Apex) — that's Phases 2-3
+- Leave `live:` props empty (`live: []` or `live: undefined`) — Phase 2 fills them in
+
+---
+
+## Phase 2 — Connect to Live Data
+
+**What to build:**
+- Import `useEngineLiveData` from `src/hooks/useEngineLiveData.ts`
+- Wire `live` prop on every `useDataSource` call:
+  ```tsx
+  const live = useEngineLiveData();
+  const markers = useDataSource({ sample: MAP_MARKERS, live: live.mapMarkers });
+  const arcs = useDataSource({ sample: MAP_ARCS, live: live.mapArcs });
+  ```
+- Update KPI overlays to use active metrics:
+  ```tsx
+  const activeMetrics = live.loading ? METRICS : live.metrics;
+  ```
+
+**What to do after wiring:**
+- Proactively suggest creating `Flight__c.Weather_Impact__c` custom field
+- If confirmed, create SFDX XML from PRD section 14a and deploy
+
+**What NOT to build:**
+- No ChatBar or Eva — that's Phase 3
+- No platform events or Apex — that's Phase 3
+
+---
+
+## Phase 3 — Add Agentforce
+
+**What to build:**
+- `ChatBar` between the map and data panels:
+  ```tsx
+  <div className="px-4 pt-4">
+    <ChatBar
+      title="Eva"
+      placeholder="Ask Eva anything about travelers, bookings, policy, or spend…"
+      suggestions={CHAT_SUGGESTIONS}
+      onSend={handleChat}
+    />
+  </div>
+  ```
+- Suggestions: weather warning, rebooking policy, notify travelers, create support case
+- `handleChat` mock response at module scope
+- `AgentforceConversationClient` with `agentId="0Xxa5000000relhCAA"` and `agentLabel="Eva"`
+
+**What to do after adding Eva:**
+- Proactively suggest creating `Travel_Disruption_Alert__e` platform event
+- If confirmed, create SFDX XML from PRD section 14b and deploy
+- Then suggest creating `TravelDisruptionEventService` Apex class
+- If confirmed, create from PRD section 14c and deploy
+
+---
+
+## Phase Summary
+
+| | Phase 1 | Phase 2 | Phase 3 |
+|---|---------|---------|---------|
+| Dashboard layout & panels | Build | — | — |
+| Sample data | Wire | — | — |
+| Live data | Skip | Wire | — |
+| Custom field metadata | Skip | Suggest | — |
+| ChatBar (Eva) | Skip | Skip | Build |
+| AgentforceConversationClient | Skip | Skip | Build |
+| Platform event | Skip | Skip | Suggest |
+| Apex service | Skip | Skip | Suggest |

package/.a4drules/skills/command-center-builder/improved-build-process.md

@@ -1 +1,32 @@
-See the PRD (engine-command-center-prd.md) section 13 for the 4-phase build process.
+# Efficient Build Process
+
+## Speed Rules
+
+1. **Load only 2 files before building:** the PRD and this skill (command-center-builder). Do NOT load component-library, command-center-project, or outer-app skills — they add latency and aren't needed for the initial build.
+
+2. **Do NOT read component source files.** The props for every component (GeoMap, BaseCard, Avatar, ChartCard, D3Chart, etc.) are documented in this skill and the PRD. Reading `GeoMap.jsx`, `BaseCard.jsx`, etc. wastes time and produces no new information.
+
+3. **Write the dashboard in one pass.** Plan the full file before writing. Do not write a partial dashboard and iterate — write the complete component with all imports, data, and JSX in a single Write call.
+
+4. **Write all 4 files without stopping.** After the dashboard, immediately write CommandCenter.tsx, Home.tsx, and edit routes.tsx. Do not run build commands between files.
+
+5. **Do NOT run `npm run build`, `npm run dev`, `tsc`, or `npm run validate:dashboard` during the build.** These waste time. The Vite build handles JSX/TSX regardless of TypeScript errors, and pre-existing TS7016 errors (from untyped .jsx library files) are normal.
+
+## File Write Order
+
+```
+1. src/pages/EngineDashboard.tsx     ← full dashboard, one pass
+2. src/components/workspace/CommandCenter.tsx  ← import dashboard
+3. src/pages/Home.tsx                ← REPLACE with CommandCenter wrapper
+4. src/routes.tsx                    ← edit index route label to "Dashboard"
+```
+
+## Common Time Wasters
+
+| Waste | Fix |
+|-------|-----|
+| Loading 4-5 skills before starting | Load only command-center-builder + PRD |
+| Reading GeoMap.jsx, Avatar.jsx, BaseCard.jsx source | Props are in this skill — trust the docs |
+| Running `npm run build` after writing | Don't — Vite handles it, TS errors are pre-existing |
+| Fixing imports iteratively (wrong icon names, wrong exports) | Check the PRD and this skill for exact import names before writing |
+| Writing Home.tsx with Account Search content | REPLACE it with the 3-line CommandCenter wrapper (see WIRING section) |

package/.a4drules/skills/command-center-guide/SKILL.md

@@ -10,37 +10,45 @@ description: >-
 
 # Command Center Development Guide
 
-## Engine Travel Command Center
+## How to Build Efficiently
 
-The product spec is in `engine-command-center-prd.md` at the React app root (`force-app/main/default/uiBundles/reactcursor1/`). It defines the layout, components, data model, and brand tokens for the dashboard.
+**Read these two files, then start building. Do not load other skills or explore component source files.**
 
-Sample data is pre-built in `src/data/engine-sample-data.js` with dashboard-ready exports.
+1. **`.a4drules/skills/command-center-builder/SKILL.md`** — has the wiring steps, conventions, component APIs, and everything you need
+2. **`engine-command-center-prd.md`** — the product spec (layout, data model, brand tokens)
 
-## Skills
+That's it. The builder skill already contains the component API reference inline. Do NOT separately load `component-library`, `command-center-project`, or `outer-app` skills — they add latency and you don't need them for the initial build. Do NOT read individual component source files (GeoMap.jsx, Avatar.jsx, etc.) — the builder skill documents all the props.
 
-| Skill | What it covers |
-|-------|---------------|
-| **component-library** | Component API reference — props, data shapes, import patterns |
-| **command-center-builder** | Dashboard conventions — layout, styling, component selection, dark mode |
-| **command-center-project** | Project structure — routing, file locations, tech stack, wiring |
-| **outer-app** | Outer app — navigation, shadcn/ui, non-dashboard pages |
+## Build Order (write files in this exact order)
 
-## Workflow
+1. **Read** the PRD and builder skill
+2. **Write** `src/pages/EngineDashboard.tsx` (or your dashboard name) — the full dashboard in one pass
+3. **Write** `src/components/workspace/CommandCenter.tsx` — import your dashboard
+4. **Write** `src/pages/Home.tsx` — REPLACE with CommandCenter (it ships as Account Search):
+   ```tsx
+   import CommandCenter from "@/components/workspace/CommandCenter";
+   export default function HomePage() { return <CommandCenter />; }
+   ```
+5. **Edit** `src/routes.tsx` — set Home as index route with label "Dashboard"
+6. **Done** — do NOT run `npm run build`, `npm run dev`, or `tsc`
 
-1. Read the PRD (`engine-command-center-prd.md`) for what to build
-2. Reference **component-library** for component APIs
-3. Follow **command-center-builder** conventions for layout and styling
-4. Reference **command-center-project** for file locations and wiring
+## Other Skills (load only when needed later)
+
+| Skill | When to load |
+|-------|-------------|
+| **component-library** | Only if you need detailed props not covered in the builder skill |
+| **command-center-project** | Only if you need project architecture context |
+| **outer-app** | Only for non-dashboard pages (search, navigation) |
 
 ## Salesforce Data Integration
 
-For live data, use these global skills:
+For live data (prompt 2), use these global skills:
 - **exploring-webapp-graphql-schema** — Look up objects and fields in `schema.graphql`
 - **generating-webapp-graphql-read-query** — Generate typed GraphQL queries
 - **using-webapp-graphql** — Create data hooks with `{ data, loading, error }`
 
 ## Agentforce Integration
 
-For AI agent features, use:
+For AI agent features (prompt 3), use:
 - **managing-webapp-agentforce-conversation-client** — Full Agentforce setup
 - **component-library** (`chat-data.md`) — ChatBar component API

package/CHANGELOG.md

@@ -5,6 +5,31 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.9.77] - 2026-04-04
+
+### Added
+- **Three-phase build guide (`getting-started.md`)** — Replaced one-liner pointer with a full phase-by-phase guide telling the agent exactly what to build and what to skip in each phase. Includes code snippets, explicit "NOT in this phase" callouts, and a summary table
+- **Build guide callout in SKILL.md** — Added a prominent callout at the top of the builder skill pointing to the build guide so agents see it immediately
+
+**Context:** Agent was building everything (including Eva ChatBar) in Phase 1 because there was no guide telling it to stop. The PRD had phase instructions but nothing in the skills enforced it. Now `getting-started.md` defines exactly what belongs in each of the 3 phases.
+
+## [1.9.76] - 2026-04-04
+
+### Fixed
+- **Dashboard wiring failure** — Agent was building the dashboard but not updating Home.tsx and routes.tsx, so users saw the Account Search page instead of their dashboard
+- **Slow builds** — Agent was loading 5 skills and reading component source files before writing anything
+
+### Changed
+- **Builder skill (SKILL.md)** — Moved wiring instructions to the very top as "WIRING — DO THIS FIRST". Added Quick Import Reference with all component, icon, and data imports so the agent doesn't need to read source files
+- **Guide skill (SKILL.md)** — Simplified to "load 2 files, then start building" instead of loading 4-5 skills. Added explicit Build Order (write files 1-2-3-4, done)
+- **improved-build-process.md** — Replaced one-liner with full speed rules, file write order, and Common Time Wasters table
+- **pre-code-checklist.md** — Added explicit code snippets for all 3 wiring files (CommandCenter.tsx, Home.tsx, routes.tsx)
+- **command-center-dashboard-rule.md** — Moved wiring above constraints with Home.tsx code example
+- **engine-dashboard-rule.md** — Expanded wiring checklist with Home.tsx replacement code
+- **PRD build prompts (section 13)** — Rewrote all 3 prompts in natural language. Prompt 1 now says "Make it the home page when you're done". Added agent checklists and common failure notes below each prompt
+
+**Context:** Agent was creating EngineDashboard.tsx and CommandCenter.tsx but leaving Home.tsx as the default Account Search page and not updating routes.tsx. The dashboard existed but never rendered. Root cause: wiring was buried 115 lines deep in the builder skill, the guide skill told the agent to load 5 skills before building, and the prompt didn't mention wiring. Fixed by moving wiring to the top of every skill file, simplifying the skill loading, and rewriting prompts.
+
 ## [1.9.75] - 2026-04-02
 
 ### Updated

package/data/engine-command-center-prd.md

@@ -320,51 +320,65 @@ Every element supports light and dark. GeoMap: `theme={mode === "dark" ? "dark"
 
 ## 13. Build Prompts
 
-Build incrementally in 3 prompts. Each prompt builds on the previous result.
+Build incrementally in 3 prompts. Each prompt builds on the previous result. The user prompt (blockquote) is what you copy-paste. The agent instructions below each prompt are guidance for the AI — not shown to the user.
 
 ---
 
-### Build the Dashboard
+### Prompt 1 — Build the Dashboard
 
-> Build the Engine Travel Command Center dashboard. Read the PRD for the full spec. Create the visualization-hero layout with the sticky header, hero GeoMap, glass KPI overlays, flight status strip, and all 4 data panels — Escalations, Disruptions, Active Travelers, and Monthly Spend Trend. Wire up the sample data from `src/data/engine-sample-data.js` so we can see real travelers, flights, and map markers. Include the "Assign to Agent" buttons on open escalations, the "View in Salesforce" links in traveler details, the "Powered by Agentforce" badge in the header, and the Salesforce signal toasts. Skip the Eva ChatBar for now — we'll add that after we connect to live data.
+> Build me a travel command center for Engine. There's a PRD with the full spec. I want the big hero map showing where all our travelers are with flight arcs, glass KPI overlays on top of the map, a flight status ticker, and then below that the main panels — escalations that need attention, active disruptions, our traveler roster with expandable details, and a spend trend chart. Hook it all up to the sample data so it looks real. Don't worry about the AI assistant or live data yet — we'll layer those on after. Make it the home page when you're done — I want to see it when I open the app.
+
+**What the agent must do:**
+
+1. Read the PRD and the `command-center-builder` skill for conventions
+2. Create `src/pages/EngineDashboard.tsx` with the full dashboard
+3. Update `src/components/workspace/CommandCenter.tsx` to import EngineDashboard
+4. **Rewrite `src/pages/Home.tsx`** to render CommandCenter (it ships as Account Search — must be replaced)
+5. **Update `src/routes.tsx`** to set Home as the index route with label "Dashboard"
+6. Add Engine brand tokens to `global.css` if not already present
+
+**What the agent must NOT do in this prompt:**
+- Do NOT add the ChatBar or any Eva/Agentforce integration — that's Prompt 3
+- Do NOT wire up live data or `useEngineLiveData` — that's Prompt 2
+- Do NOT create Salesforce metadata (custom fields, platform events, Apex) — that's Prompts 2 and 3
+
+**Common failure:** The agent creates the dashboard file but forgets to update `Home.tsx` and `routes.tsx`, so the user still sees the Account Search page. The wiring section at the top of `.a4drules/skills/command-center-builder/SKILL.md` explains all required file changes.
 
 ---
 
-### Connect to Salesforce Data
-
-> Connect the dashboard to live Salesforce data. A second dataset already exists in `src/data/engine-live-data.js` with 12 travelers across global routes and different KPIs (distinct from the 8-traveler sample data). A hook already exists at `src/hooks/useEngineLiveData.ts` — it imports the live data, simulates a 2-second loading delay, then calls `setMode("live")` to flip the global data mode.
->
-> Import `useEngineLiveData` in the dashboard and populate the `live` prop on each `useDataSource` call:
->
-> ```tsx
-> const live = useEngineLiveData();
-> const markers = useDataSource({ sample: MAP_MARKERS, live: live.mapMarkers });
-> const arcs = useDataSource({ sample: MAP_ARCS, live: live.mapArcs });
-> ```
->
-> Also update the KPI overlays to re-derive from whichever metrics are active:
->
-> ```tsx
-> const activeMetrics = live.loading ? METRICS : live.metrics;
-> ```
->
-> After wiring the data, check if `Flight__c` has a `Weather_Impact__c` field for tracking weather disruptions — if it doesn't exist, ask me before creating it. Use the SFDX XML template from section 14a below and deploy with `sf project deploy start`.
-
-**Reference — what the agent should say and do:**
-
-1. After wiring the live data, tell the user: *"I notice `Flight__c` doesn't have a field to track weather impact on individual flights. A `Weather_Impact__c` picklist would help the dashboard filter storm-affected flights. Want me to create it?"* — When confirmed, create the custom field XML from section 14a and deploy it.
+### Prompt 2 — Connect to Salesforce Data
+
+> Now let's connect this to real data. There's a second dataset with different travelers and metrics — hook that up as the "live" data source so when someone toggles from sample to live mode, everything refreshes with the new data. After that, see if there are any data model improvements we should make for tracking weather disruptions.
+
+**What the agent must do:**
+
+1. Find and use `src/data/engine-live-data.js` and `src/hooks/useEngineLiveData.ts`
+2. Import `useEngineLiveData` and wire each `useDataSource({ sample, live })` call
+3. Update KPI overlays to derive from whichever metrics are active
+4. After wiring, proactively offer to create the `Weather_Impact__c` custom field (section 14a)
+
+**Reference — what the agent should say:**
+
+After wiring the live data: *"I notice `Flight__c` doesn't have a field to track weather impact on individual flights. A `Weather_Impact__c` picklist would help the dashboard filter storm-affected flights. Want me to create it?"* — When confirmed, create the custom field XML from section 14a and deploy it.
 
 ---
 
-### Add Agentforce
+### Prompt 3 — Add Agentforce
+
+> Last piece — let's add Eva, the AI travel assistant. I want a chat bar right below the map where people can ask her questions about travelers and disruptions. Also hook up the real Agentforce agent so she can actually do things. Then let's set up the backend so disruption alerts can flow through the platform in real time.
+
+**What the agent must do:**
 
-> Add Eva to the dashboard. Place the ChatBar between the map and data panels using the suggestions from section 9. Wire up the `handleChat` mock response. Then add the `AgentforceConversationClient` component with `agentId="0Xxa5000000relhCAA"` and `agentLabel="Eva"` — this connects the real Salesforce agent. After adding Eva, create a `Travel_Disruption_Alert__e` platform event so disruptions can be published to the event bus in real time — ask me before creating it. Then write an Apex class `TravelDisruptionEventService` that publishes disruption records to that event — ask me before creating it. Use the SFDX templates from section 14b and 14c and deploy each with `sf project deploy start`.
+1. Add `ChatBar` with suggestions from section 9, placed between map and data panels
+2. Add `AgentforceConversationClient` with `agentId="0Xxa5000000relhCAA"` and `agentLabel="Eva"`
+3. Proactively offer to create `Travel_Disruption_Alert__e` platform event (section 14b)
+4. After the event, proactively offer to create `TravelDisruptionEventService` Apex class (section 14c)
 
-**Reference — what the agent should say and do:**
+**Reference — what the agent should say:**
 
-1. After adding Eva, tell the user: *"The dashboard tracks disruptions in real time. I can create a `Travel_Disruption_Alert__e` platform event so disruption data can be published to the Salesforce event bus — other systems and automation can subscribe to it. Want me to set it up?"* — When confirmed, create the platform event and its fields from section 14b and deploy.
+1. After adding Eva: *"The dashboard tracks disruptions in real time. I can create a `Travel_Disruption_Alert__e` platform event so disruption data can be published to the Salesforce event bus — other systems and automation can subscribe to it. Want me to set it up?"* — When confirmed, create the platform event and its fields from section 14b and deploy.
 
-2. After the platform event, tell the user: *"Now I'll write an Apex service class to publish disruption records to that event bus. `TravelDisruptionEventService` will take a list of disruptions and fire platform events with the flight number, severity, and description. Want me to create it?"* — When confirmed, create the Apex class from section 14c and deploy.
+2. After the platform event: *"Now I'll write an Apex service class to publish disruption records to that event bus. `TravelDisruptionEventService` will take a list of disruptions and fire platform events with the flight number, severity, and description. Want me to create it?"* — When confirmed, create the Apex class from section 14c and deploy.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schandlergarcia/sf-web-components",
-  "version": "1.9.75",
+  "version": "1.9.77",
   "description": "Reusable Salesforce web components library with Tailwind CSS v4 and shadcn/ui",
   "type": "module",
   "main": "./dist/index.js",