@schandlergarcia/sf-web-components 1.9.85 → 1.9.87

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

@@ -398,19 +398,27 @@ Define schemas outside component body. Always `required: true` on mandatory fiel
 
 ## AI Chat & Agent
 
-Two components for agent integration:
+Two pieces for agent integration — a **ChatBar** component and the **`useEvaAgent` hook** (Agent REST API):
 
 - **`ChatBar`** — command-palette strip for suggested prompts. Place between the hero map and data panels (full-width, `px-4 pt-4`), NOT in the header. Always provide 3–5 `suggestions`.
-- **`AgentforceConversationClient`** — the real Salesforce agent. Import from `@/components/AgentforceConversationClient` and pass the agent ID. Renders as a floating widget.
+- **`useEvaAgent`** — pre-installed hook at `src/hooks/useEvaAgent.ts`. Handles OAuth → session → messages → cleanup via the Agentforce Agent REST API. Config is in `src/config/agentApi.ts`. Vite proxy rules in `vite.config.ts` forward requests.
+
+> **Do NOT use `AgentforceConversationClient`** (the iframe widget). We use the Agent REST API via `useEvaAgent`.
+> **Do NOT create wrapper hooks** (useEvaChatAdapter, useDisruptionAlerts, etc.). Use `useEvaAgent` directly.
+> **Do NOT create `.env` or `.env.local` files** — config is hardcoded in `src/config/agentApi.ts`.
 
 ```tsx
-import { AgentforceConversationClient } from "@/components/AgentforceConversationClient";
+import useEvaAgent from "@/hooks/useEvaAgent";
+
+const { messages, isReady, isSending, connect, sendMessage } = useEvaAgent();
+useEffect(() => { connect(); }, [connect]);
 
-<AgentforceConversationClient agentId="0Xxa5000000relhCAA" agentLabel="Eva" />
+const handleChat = (text: string) => {
+  sendMessage(text);
+  return { text: `Looking into: "${text}"…` };
+};
 ```
 
-- Return `components` for structured data — never markdown tables in text
-- Always set height on `ChatPanel`
 - Extract `onSend` handlers to module scope when shared
 
 ## Tables

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

@@ -2,184 +2,212 @@
 
 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.
 
-## General Rules for All Phases
+---
+
+## RULES THAT APPLY TO EVERY PHASE
+
+> **Read these first. Violations of these rules are the #1 cause of failed demos.**
+
+1. **Phase 1 writes new files. Phases 2 and 3 make surgical edits.** Never rewrite `EngineDashboard.tsx` from scratch in Phase 2 or 3. Rewriting a 400+ line file takes 60s, risks losing prior work, and introduces regressions. Surgical edits take seconds.
+
+2. **Do NOT read library component source files.** This means: do NOT read `GeoMap.jsx`, `BaseCard.jsx`, `Avatar.jsx`, `ChatBar.jsx`, `ChartCard.jsx`, `D3Chart.jsx`, `useDataSource.jsx`, `DataModeProvider.jsx`, `DataModeToggle.jsx`, or any file inside `src/components/library/`. All props and patterns are documented in this build guide and the PRD. Reading source files wastes time and produces no new information.
 
-1. **Phase 1 writes new files. Phases 2 and 3 make surgical edits.** Phase 2 and 3 should NEVER rewrite `EngineDashboard.tsx` from scratch — use targeted edits (add imports, update specific lines, insert JSX blocks). Rewriting the entire file risks losing Phase 1 work and takes 60+ seconds vs seconds per edit.
+3. **Do NOT load unnecessary skills.** Phase 1 needs only `command-center-builder`. Do NOT load `outer-app`, `component-library`, `command-center-project`, `agentforce-test`, or `agentforce-observability` — they add latency and aren't needed.
 
-2. **Don't read files you don't need.** The patterns for `useDataSource`, `DataModeProvider`, `DataModeToggle`, and library components are documented in this skill. Only read files that contain project-specific code you need to understand (e.g., the dashboard you're editing, the live data file for its shape).
+4. **Do NOT run `npm run build` or `npm run dev` during the build.** Vite handles JSX/TSX regardless of TypeScript errors. Pre-existing TS7016 errors (from untyped .jsx library files) are normal and expected.
 
-3. **Don't run `npm run build` during the build.** Vite handles JSX/TSX regardless of TypeScript errors. Pre-existing TS7016 errors are normal.
+5. **STOP and ASK before creating Salesforce metadata.** Custom fields, platform events, and Apex classes are scripted demo moments. Suggest them, wait for "yes," then create. Never create them proactively.
 
-4. **STOP and ASK before creating Salesforce metadata.** When the build guide says "suggest" a custom field, platform event, or Apex class — you must present the suggestion to the user and WAIT for confirmation. Do NOT create the file until the user says yes. This is a scripted demo moment.
+6. **Do NOT create extra files not listed in the build guide.** Each phase lists exactly which files to create or edit. Do NOT create wrapper hooks, adapter files, .env files, or any file not explicitly listed.
 
 ---
 
 ## 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
+### FORBIDDEN in Phase 1
+- ❌ ChatBar, Eva, or any Agentforce integration (that's Phase 3)
+- ❌ `useEngineLiveData` or live data wiring (that's Phase 2)
+- ❌ Salesforce metadata — custom fields, platform events, Apex (that's Phases 2-3)
+- ❌ Reading library component source files (GeoMap.jsx, BaseCard.jsx, etc.)
+- ❌ Loading skills other than `command-center-builder`
+
+### Files to read (only these)
+1. `engine-command-center-prd.md` — the full spec
+2. `src/data/engine-sample-data.js` — sample data shape
+
+### Files to create/edit (in order)
+```
+1. WRITE  src/pages/EngineDashboard.tsx     ← full dashboard, one pass
+2. EDIT   src/components/workspace/CommandCenter.tsx  ← import EngineDashboard
+3. WRITE  src/pages/Home.tsx                ← REPLACE with CommandCenter wrapper (3 lines)
+4. EDIT   src/routes.tsx                    ← change index route label to "Dashboard"
+```
+
+### What to build in EngineDashboard.tsx
+- 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 via `useDataSource({ sample: SAMPLE_DATA, live: [] })` — leave `live:` empty
+
+### Wiring
+- `CommandCenter.tsx` → import EngineDashboard instead of BlankDashboard
+- `Home.tsx` → **REPLACE** the Account Search page with a 3-line wrapper that renders `<CommandCenter />`
+- `routes.tsx` → change the index route handle to `{ showInNavigation: false, showNavBar: false, label: "Dashboard" }`
+
+### Write the dashboard in one pass
+Plan the entire 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.
 
 ---
 
 ## Phase 2 — Connect to Live Data
 
-**The point of Phase 2:** The dashboard switches from sample data (8 US travelers: Sarah Chen, Marcus Johnson…) to a completely different live dataset (12 global travelers: Raj Kapoor, Sofia Reyes… with a Midwest storm scenario). The user should see different names, different cities, different metrics, and different disruptions.
+### FORBIDDEN in Phase 2
+- ❌ `DataModeToggle` — do NOT add it to the UI. There is NO UI toggle. The switch is `dataStrategy.ts` on the backend.
+- ❌ Rewriting `EngineDashboard.tsx` from scratch — make 5 targeted edits only
+- ❌ Reading library source files (`useDataSource.jsx`, `DataModeProvider.jsx`, `DataModeToggle.jsx`, `dataStrategy.ts`)
+- ❌ ChatBar, Eva, or Agentforce integration (that's Phase 3)
+- ❌ Platform events or Apex classes (that's Phase 3)
+- ❌ Renaming existing imports (don't add SAMPLE_ prefix — leave existing variable names alone, just fill in the `live:` props)
+- ❌ Creating extra files not listed below
+- ❌ Running `npm run build` between edits
 
-**How the switch works:** `ENABLE_SAMPLE_DATA_CACHE` in `src/lib/dataStrategy.ts` controls which data `useDataSource` returns. `CommandCenter.tsx` reads this flag and passes it to `DataModeProvider`. When the flag is `true` (default), mode is "sample." When `false`, mode is "live" and every `useDataSource` call returns its `live` prop instead.
+### The point of Phase 2
+The dashboard switches from sample data (8 US travelers: Sarah Chen, Marcus Johnson…) to a completely different live dataset (12 global travelers: Raj Kapoor, Sofia Reyes… with a Midwest storm scenario). The user sees different names, different cities, different metrics, and different disruptions.
 
-**How to work:** Make surgical edits to the existing `EngineDashboard.tsx`. Do NOT rewrite the file.
+### How the switch works
+`ENABLE_SAMPLE_DATA_CACHE` in `src/lib/dataStrategy.ts` controls the mode. `CommandCenter.tsx` reads this flag and passes `initialMode` to `DataModeProvider`. When `true` (default) → sample mode. When `false` → live mode, every `useDataSource` returns its `live` prop.
 
-**Files to read first (only these):**
+### Files to read (only these — no others)
 1. `src/pages/EngineDashboard.tsx` — the Phase 1 dashboard you're editing
 2. `src/hooks/useEngineLiveData.ts` — to see the live data shape
 
-**Do NOT read:** `useDataSource.jsx`, `DataModeProvider.jsx`, `dataStrategy.ts`, or any library component source. The patterns are right here.
+### Edits to make (exactly 5, in order)
 
-**Edits to make (in order):**
+**Edit 1 — Add import** at the top of EngineDashboard.tsx:
+```tsx
+import { useEngineLiveData } from "@/hooks/useEngineLiveData";
+```
 
-1. **Add import** at the top of EngineDashboard.tsx:
-   ```tsx
-   import { useEngineLiveData } from "@/hooks/useEngineLiveData";
-   ```
+**Edit 2 — Add hook call** inside the component, near the top:
+```tsx
+const live = useEngineLiveData();
+```
 
-2. **Add hook call** inside the component, near the top:
-   ```tsx
-   const live = useEngineLiveData();
-   ```
+**Edit 3 — Update every `useDataSource` call** to pass live data:
+```tsx
+// Before (Phase 1):
+const markers = useDataSource({ sample: MAP_MARKERS, live: [] });
+// After (Phase 2 — just fill in the live: prop):
+const markers = useDataSource({ sample: MAP_MARKERS, live: live.mapMarkers });
+```
+Do this for ALL useDataSource calls: markers, arcs, travelers, flights, escalations, disruptions, spendData.
 
-3. **Update every `useDataSource` call** to pass live data:
-   ```tsx
-   // Before (Phase 1):
-   const markers = useDataSource({ sample: MAP_MARKERS, live: [] });
-   // After (Phase 2):
-   const markers = useDataSource({ sample: MAP_MARKERS, live: live.mapMarkers });
-   ```
-   Do this for markers, arcs, travelers, flights, escalations, disruptions, spendData — whatever the dashboard uses.
+**Edit 4 — Update KPI derivations** to react to active data:
+```tsx
+const activeMetrics = live.loading ? null : live.metrics;
+// Then use activeMetrics in KPI overlays when available, fall back to sample constants
+```
 
-4. **Update KPI derivations** to react to active data:
-   ```tsx
-   const activeMetrics = live.loading ? SAMPLE_METRICS : live.metrics;
-   ```
-   Then use `activeMetrics` in KPI overlays instead of hardcoded sample constants.
+**Edit 5 — Flip the backend switch** — edit `src/lib/dataStrategy.ts`:
+```tsx
+export const ENABLE_SAMPLE_DATA_CACHE = false;
+```
 
-5. **Flip the backend switch** — change `src/lib/dataStrategy.ts`:
-   ```tsx
-   export const ENABLE_SAMPLE_DATA_CACHE = false;
-   ```
-   This causes `CommandCenter.tsx` to pass `initialMode="live"` to `DataModeProvider`, and every `useDataSource` call now returns the live prop. The dashboard instantly shows the live dataset on next load.
+> ⚠️ **Do NOT skip Edit 5.** This is the most critical step. Without it, the data never switches and the demo fails. The dashboard will still show sample data no matter what you wired in Edits 1-4.
 
-That's 5 targeted edits. Not a full rewrite.
+That's 5 targeted edits, not a full rewrite.
 
-**No UI toggle.** There is no `DataModeToggle` in the dashboard. The switch is `ENABLE_SAMPLE_DATA_CACHE` in `dataStrategy.ts`.
+### After wiring — STOP and suggest (do not create yet)
 
-**After wiring — STOP and suggest (do not create yet):**
+Say: *"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?"*
 
-Say something like: *"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?"*
-
-Only create `Flight__c.Weather_Impact__c` (PRD section 14a) AFTER the user confirms.
-
-**What NOT to build:**
-- No ChatBar or Eva — that's Phase 3
-- No platform events or Apex — that's Phase 3
-- Do NOT rewrite EngineDashboard.tsx from scratch
-- Do NOT add `DataModeToggle` to the UI
-- Do NOT read library component source files
-- Do NOT run `npm run build` between edits
+Only create `Flight__c.Weather_Impact__c` (PRD section 14a) AFTER the user says yes. Suggest ONLY this one field — do not suggest additional fields.
 
 ---
 
 ## Phase 3 — Add Agentforce
 
-**How to work:** Make surgical edits to the existing `EngineDashboard.tsx`. Do NOT rewrite the file.
+### FORBIDDEN in Phase 3
+- ❌ `AgentforceConversationClient` — do NOT use the iframe widget. We use the Agent REST API via `useEvaAgent`.
+- ❌ Wrapper hooks or adapter files — do NOT create `useEvaChatAdapter.ts`, `useDisruptionAlerts.ts`, or any extra hook. Use `useEvaAgent` directly.
+- ❌ `.env` or `.env.local` files — the config is hardcoded in `src/config/agentApi.ts` (pre-installed by the package)
+- ❌ Rewriting `EngineDashboard.tsx` from scratch
+- ❌ Reading library component source files (including `ChatBar.jsx`)
+- ❌ Creating platform events or Apex classes without user confirmation
+- ❌ Loading `agentforce-test`, `agentforce-observability`, or `outer-app` skills
 
-> **Important:** We do NOT use `AgentforceConversationClient` (the iframe widget). All agent communication goes through the REST-based Agent API via the `useEvaAgent` hook. The Vite dev server proxies the requests (`/sf-oauth` and `/sf-agent`) to avoid CORS issues.
+### Pre-installed files (already in the project — do NOT recreate)
+These files are installed by the package and restored by the reset script. They already exist:
+- `src/hooks/useEvaAgent.ts` — the Agent API hook (OAuth → session → messages → cleanup)
+- `src/config/agentApi.ts` — hardcoded credentials and endpoint config
+- `vite.config.ts` — already has `/sf-oauth` and `/sf-agent` proxy rules
 
-**Files to read first (only these):**
+**Do NOT create, rewrite, or modify these files.** Just import and use them.
+
+### Files to read (only these)
 1. `src/pages/EngineDashboard.tsx` — the current dashboard
 
-**Edits to make (in order):**
-
-1. **Add imports:**
-   ```tsx
-   import { ChatBar } from "@/components/library";
-   import useEvaAgent from "@/hooks/useEvaAgent";
-   ```
-
-2. **Add chat suggestions constant** at module scope:
-   ```tsx
-   const CHAT_SUGGESTIONS = [
-     "Are any travelers affected by the Denver weather?",
-     "What's our rebooking policy for weather delays?",
-     "Notify all travelers on disrupted flights",
-     "Create a support case for the SFO→JFK cancellation",
-   ];
-   ```
-
-3. **Add agent hook + handler** inside the component:
-   ```tsx
-   const { messages: evaMessages, isReady, isSending, connect, sendMessage } = useEvaAgent();
-   useEffect(() => { connect(); }, [connect]);
-
-   const handleChat = (text: string) => {
-     sendMessage(text);
-     return { text: `Looking into: "${text}"…` };
-   };
-   ```
-
-4. **Insert ChatBar JSX** between the map section and the 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>
-   ```
-
-5. Do **NOT** add `AgentforceConversationClient` — the `useEvaAgent` hook replaces it entirely.
-
-**After adding Eva — STOP and suggest (do not create yet):**
+### Edits to make (exactly 4, in order)
+
+**Edit 1 — Add imports** at the top of EngineDashboard.tsx:
+```tsx
+import { ChatBar } from "@/components/library";
+import useEvaAgent from "@/hooks/useEvaAgent";
+```
+
+**Edit 2 — Add chat suggestions constant** at module scope (outside the component):
+```tsx
+const CHAT_SUGGESTIONS = [
+  "Are any travelers affected by the Denver weather?",
+  "What's our rebooking policy for weather delays?",
+  "Notify all travelers on disrupted flights",
+  "Create a support case for the SFO→JFK cancellation",
+];
+```
+
+**Edit 3 — Add agent hook + handler** inside the component:
+```tsx
+const { messages: evaMessages, isReady, isSending, connect, sendMessage } = useEvaAgent();
+useEffect(() => { connect(); }, [connect]);
+
+const handleChat = (text: string) => {
+  sendMessage(text);
+  return { text: `Looking into: "${text}"…` };
+};
+```
+
+**Edit 4 — Insert ChatBar JSX** between the map section closing `</div>` and the data panels `<div>`:
+```tsx
+{/* ── EVA CHATBAR ──────────────────────────────────────────────── */}
+<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>
+```
+
+That's 4 targeted edits. Nothing else.
+
+### After adding Eva — STOP and suggest (do not create yet)
 
 Say: *"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. Want me to set it up?"*
 
 Only create the platform event (PRD section 14b) AFTER the user confirms.
 
-**After the platform event — STOP and suggest again:**
+### After the platform event — STOP and suggest again
 
 Say: *"Now I'll write an Apex service class to publish disruption records to that event bus. Want me to create it?"*
 
 Only create `TravelDisruptionEventService` (PRD section 14c) AFTER the user confirms.
 
-**What NOT to build without asking:**
-- Do NOT use `AgentforceConversationClient` — use `useEvaAgent` hook instead
-- Do NOT create platform events or Apex classes without user confirmation
-- Do NOT rewrite EngineDashboard.tsx from scratch
-- Do NOT read library component source files
-
 ---
 
 ## Phase Summary
@@ -188,14 +216,16 @@ Only create `TravelDisruptionEventService` (PRD section 14c) AFTER the user conf
 |---|---------|---------|---------|
 | Dashboard layout & panels | Write new file | — | — |
 | Sample data | Wire (`live: []`) | — | — |
-| Live data wiring | Skip | Surgical edits | — |
-| Flip `dataStrategy.ts` to `false` | Skip | Edit | — |
+| Live data wiring | Skip | 5 surgical edits | — |
+| Flip `dataStrategy.ts` to `false` | Skip | **Edit 5 — don't skip** | — |
+| DataModeToggle in UI | **NO — never** | **NO — never** | **NO — never** |
 | Custom field metadata | Skip | Suggest → wait | — |
-| ChatBar (Eva) | Skip | Skip | Surgical edit |
-| `useEvaAgent` hook (Agent API) | Skip | Skip | Surgical edit |
+| ChatBar (Eva) | Skip | Skip | 4 surgical edits |
+| `useEvaAgent` hook | Skip | Skip | Import (pre-installed) |
+| Wrapper hooks / adapters | **NO — never** | **NO — never** | **NO — never** |
 | Platform event | Skip | Skip | Suggest → wait |
 | Apex service | Skip | Skip | Suggest → wait |
 
-**Data mode control:** `ENABLE_SAMPLE_DATA_CACHE` in `src/lib/dataStrategy.ts` is the backend switch. `CommandCenter.tsx` reads this flag and passes `initialMode` to `DataModeProvider`. Phase 1 leaves it `true` (sample data). Phase 2 flips it to `false` (live data — different travelers, cities, and metrics). There is no UI toggle.
+**Data mode control:** `ENABLE_SAMPLE_DATA_CACHE` in `src/lib/dataStrategy.ts` is the backend switch. Phase 1 leaves it `true`. Phase 2 flips it to `false`. There is NO UI toggle — never add `DataModeToggle`.
 
-**Agent communication:** `useEvaAgent` hook in `src/hooks/useEvaAgent.ts` handles OAuth → session → messages → cleanup via the Agent REST API. Config is in `src/config/agentApi.ts`. Vite proxy rules (`/sf-oauth`, `/sf-agent`) in `vite.config.ts` forward requests to the Salesforce org and Agent API host.
+**Agent communication:** `useEvaAgent` hook in `src/hooks/useEvaAgent.ts` handles OAuth → session → messages → cleanup via the Agent REST API. Config is in `src/config/agentApi.ts`. Vite proxy rules (`/sf-oauth`, `/sf-agent`) in `vite.config.ts` forward requests. All three files are pre-installed — do NOT recreate them.

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

@@ -3,35 +3,37 @@
 ## The #1 Rule: Phase 1 Writes, Phases 2-3 Edit
 
 - **Phase 1** creates `EngineDashboard.tsx` from scratch (Write). Also writes CommandCenter.tsx, Home.tsx, edits routes.tsx.
-- **Phase 2** makes ~5 surgical edits to the existing dashboard (StrReplace / targeted edits). Never rewrites the file.
-- **Phase 3** makes ~4 surgical edits to the existing dashboard (StrReplace / targeted edits). Never rewrites the file.
+- **Phase 2** makes exactly 5 surgical edits. Never rewrites the file.
+- **Phase 3** makes exactly 4 surgical edits. Never rewrites the file.
 
 Rewriting a 400+ line file from scratch takes 60 seconds, risks losing prior work, and can introduce regressions. Surgical edits take seconds each and preserve everything.
 
 ## 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.
+1. **Load only `command-center-builder` skill before building.** Do NOT load component-library, command-center-project, outer-app, agentforce-test, or agentforce-observability — they add latency and aren't needed.
 
-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`, `useDataSource.js`, `DataModeProvider.jsx`, etc. wastes time and produces no new information.
+2. **Do NOT read component source files.** This means ALL files inside `src/components/library/` are off-limits: GeoMap.jsx, BaseCard.jsx, Avatar.jsx, ChatBar.jsx, D3Chart.jsx, useDataSource.jsx, DataModeProvider.jsx, DataModeToggle.jsx, etc. Props/patterns are documented in the build guide and PRD.
 
-3. **Phase 1: 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. Then write all 4 files without stopping.
+3. **Phase 1: Write the dashboard in one pass.** Plan the full file before writing. Write the complete component with all imports, data, and JSX in a single Write call.
 
-4. **Phases 2-3: Make targeted edits only.** Read the existing dashboard, then make specific edits (add imports, update lines, insert JSX blocks). Do NOT use Write to replace the entire file.
+4. **Phases 2-3: Make the exact edits listed in the build guide.** Phase 2 = 5 edits. Phase 3 = 4 edits. No more, no less.
 
-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.
+5. **Do NOT run `npm run build`, `npm run dev`, `tsc`, or `npm run validate:dashboard` during the build.** Vite handles it. TS7016 errors are pre-existing and expected.
 
-6. **STOP and ASK before creating metadata.** Custom fields, platform events, and Apex classes are scripted demo moments. Suggest them, wait for "yes," then create. Never just create them.
+6. **STOP and ASK before creating metadata.** Custom fields, platform events, and Apex classes are scripted demo moments. Suggest, wait, create.
+
+7. **Do NOT create extra files.** No wrapper hooks (useEvaChatAdapter, useDisruptionAlerts), no .env files, no adapter files. The build guide lists every file to create or edit.
 
 ## Phase 1 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"
+1. WRITE  src/pages/EngineDashboard.tsx          ← full dashboard, one pass
+2. EDIT   src/components/workspace/CommandCenter.tsx  ← swap BlankDashboard → EngineDashboard
+3. WRITE  src/pages/Home.tsx                     ← 3-line CommandCenter wrapper
+4. EDIT   src/routes.tsx                         ← change index route label to "Dashboard"
 ```
 
-## Phase 2 Edit Order
+## Phase 2 Edit Order (5 edits)
 
 ```
 1. Add useEngineLiveData import to EngineDashboard.tsx
@@ -42,27 +44,37 @@ Rewriting a 400+ line file from scratch takes 60 seconds, risks losing prior wor
 → STOP — suggest Weather_Impact__c, wait for confirmation
 ```
 
-No UI toggle. The switch is `ENABLE_SAMPLE_DATA_CACHE` in `dataStrategy.ts`. When `false`, `CommandCenter.tsx` passes `initialMode="live"` and every `useDataSource` returns its live prop.
+⚠️ **Edit 5 is the most critical.** Without it, the data never switches and the demo fails.
+
+**NEVER add DataModeToggle to the UI.** The switch is `ENABLE_SAMPLE_DATA_CACHE` in `dataStrategy.ts`.
 
-## Phase 3 Edit Order
+## Phase 3 Edit Order (4 edits)
 
 ```
-1. Add ChatBar import (if not in barrel import)
-2. Add CHAT_SUGGESTIONS constant + handleChat function
-3. Insert <ChatBar /> JSX between map and data panels
-4. Add AgentforceConversationClient
+1. Add ChatBar + useEvaAgent imports to EngineDashboard.tsx
+2. Add CHAT_SUGGESTIONS constant at module scope
+3. Add useEvaAgent hook call + handleChat inside component
+4. Insert <ChatBar /> JSX between map and data panels
 → STOP — suggest platform event, wait for confirmation
 → STOP — suggest Apex class, wait for confirmation
 ```
 
+**useEvaAgent, agentApi.ts, and vite.config.ts proxy rules are pre-installed.** Do NOT recreate them. Just import `useEvaAgent` from `@/hooks/useEvaAgent`.
+
+**NEVER use AgentforceConversationClient.** We use the Agent REST API via `useEvaAgent`.
+
+**NEVER create wrapper hooks** (useEvaChatAdapter, useDisruptionAlerts, etc.). Use `useEvaAgent` directly.
+
 ## Common Time Wasters
 
 | Waste | Fix |
 |-------|-----|
-| Loading 4-5 skills before starting | Load only command-center-builder + PRD |
-| Reading GeoMap.jsx, Avatar.jsx, useDataSource.js source | Props/patterns are in this skill — trust the docs |
-| Rewriting EngineDashboard.tsx from scratch in Phase 2/3 | Make 5 surgical edits, not a 454-line rewrite |
-| Running `npm run build` between edits | 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) |
-| Creating metadata without asking | STOP, suggest, wait for "yes" — it's a scripted demo moment |
+| Loading 4-5 skills before starting | Load only command-center-builder |
+| Reading GeoMap.jsx, ChatBar.jsx, useDataSource.js source | Props are in the build guide — trust the docs |
+| Rewriting EngineDashboard.tsx in Phase 2/3 | Make 5 or 4 targeted edits |
+| Running `npm run build` between edits | Don't — Vite handles it |
+| Adding DataModeToggle to the UI | **NEVER** — the switch is dataStrategy.ts |
+| Creating useEvaChatAdapter or useDisruptionAlerts | **NEVER** — use useEvaAgent directly, no wrappers |
+| Creating .env or .env.local files | **NEVER** — config is hardcoded in src/config/agentApi.ts |
+| Renaming imports with SAMPLE_ prefix | Don't rename — just fill in the `live:` props |
+| Suggesting 3+ custom fields | Suggest only Weather_Impact__c |

package/.a4drules/skills/component-library/SKILL.md

@@ -672,7 +672,7 @@ Dropdown select. Value `"all"` skips filtering.
 ## Data Utilities
 
 ### DataModeToggle
-**When:** Place in the app header to let users switch between sample and live data.
+> ⚠️ **Do NOT use in the Engine Command Center dashboard.** The Engine dashboard controls data mode via `ENABLE_SAMPLE_DATA_CACHE` in `src/lib/dataStrategy.ts` — there is no UI toggle. Only use `DataModeToggle` in non-Engine dashboards that explicitly need a manual toggle.
 
 ```jsx
 <DataModeToggle className="ml-4" />

package/.a4drules/skills/component-library/chat-data.md

@@ -54,7 +54,7 @@ Wraps app. Provides `useDataMode()` → `{ mode, isSample, isLive, toggle, setMo
 ## Data Utilities
 
 ### DataModeToggle
-**When:** Place in the app header to let users switch between sample and live data.
+> ⚠️ **Do NOT use in the Engine Command Center dashboard.** The Engine dashboard controls data mode via `ENABLE_SAMPLE_DATA_CACHE` in `src/lib/dataStrategy.ts` — there is no UI toggle. Only use `DataModeToggle` in non-Engine dashboards that explicitly need a manual toggle.
 
 ```jsx
 <DataModeToggle className="ml-4" />

package/CHANGELOG.md

@@ -5,6 +5,27 @@ 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.87] - 2026-04-07
+
+### Changed
+- **SKILL.md AI Chat section** — replaced `AgentforceConversationClient` instructions with `useEvaAgent` hook usage and explicit prohibitions against iframe widget, wrapper hooks, and .env files.
+- **Component library DataModeToggle docs** — added warning that DataModeToggle must NOT be used in the Engine Command Center dashboard (both SKILL.md and chat-data.md).
+
+## [1.9.86] - 2026-04-07
+
+### Changed
+- **Strengthened build guide and PRD guardrails** — Based on observed agent failures across 3 demo runs:
+  - Every phase now has a prominent **FORBIDDEN** section with ❌ markers listing exact violations
+  - Phase 2: `DataModeToggle` prohibition is now the first forbidden item (agents kept adding it despite the rule existing)
+  - Phase 2: `dataStrategy.ts` flip is marked with ⚠️ CRITICAL and a warning that the demo fails without it
+  - Phase 3: Explicit prohibition of wrapper hooks (`useEvaChatAdapter`, `useDisruptionAlerts`), `.env` files, and recreating pre-installed files
+  - Phase 3: Lists pre-installed files (`useEvaAgent.ts`, `agentApi.ts`, proxy config) with "do NOT recreate" instruction
+  - All phases: Explicit prohibition of reading library source files with full file list
+  - All phases: Explicit prohibition of loading unnecessary skills (only `command-center-builder` needed)
+  - All phases: Edit counts are now exact ("exactly 5 edits", "exactly 4 edits") to prevent scope creep
+  - Phase 2: Explicit prohibition of renaming imports with SAMPLE_ prefix
+  - Phase 2: Limit suggestion to only Weather_Impact__c (agents were suggesting 3+ fields)
+
 ## [1.9.85] - 2026-04-07
 
 ### Fixed

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

@@ -341,6 +341,12 @@ Every element supports light and dark. GeoMap: `theme={mode === "dark" ? "dark"
 
 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.
 
+> **CRITICAL — Rules for ALL prompts:**
+> - Do NOT read any file inside `src/components/library/` (GeoMap.jsx, ChatBar.jsx, BaseCard.jsx, useDataSource.jsx, DataModeProvider.jsx, etc.) — all props/patterns are documented here and in the build guide.
+> - Do NOT load unnecessary skills — only `command-center-builder` is needed.
+> - Do NOT run `npm run build` during the build — Vite handles it.
+> - Do NOT create files not listed in the instructions below.
+
 ---
 
 ### Prompt 1 — Build the Dashboard
@@ -349,19 +355,21 @@ Build incrementally in 3 prompts. Each prompt builds on the previous result. The
 
 **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
+1. Load ONLY the `command-center-builder` skill (no other skills)
+2. Read ONLY the PRD and `src/data/engine-sample-data.js` — no other files before writing
+3. Create `src/pages/EngineDashboard.tsx` with the full dashboard in ONE write
+4. Update `src/components/workspace/CommandCenter.tsx` to import EngineDashboard
+5. **Rewrite `src/pages/Home.tsx`** to render CommandCenter (it ships as Account Search — must be replaced with a 3-line wrapper)
+6. **Update `src/routes.tsx`** to set Home as the index route with label "Dashboard"
 
-**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
+**FORBIDDEN in Prompt 1:**
+- ❌ ChatBar, Eva, or any Agentforce integration (Prompt 3)
+- ❌ `useEngineLiveData` or live data wiring (Prompt 2)
+- ❌ Salesforce metadata — custom fields, platform events, Apex (Prompts 2-3)
+- ❌ Reading library component source files (GeoMap.jsx, BaseCard.jsx, etc.)
+- ❌ Loading `outer-app`, `component-library`, `command-center-project`, or other skills
 
-**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.
+**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.
 
 ---
 
@@ -369,23 +377,25 @@ Build incrementally in 3 prompts. Each prompt builds on the previous result. The
 
 > 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 the dashboard can pull from either dataset depending on the backend config. After that, see if there are any data model improvements we should make for tracking weather disruptions.
 
-**What the agent must do:**
-
-1. Read only `EngineDashboard.tsx` and `src/hooks/useEngineLiveData.ts` — don't read `useDataSource.jsx`, `DataModeProvider.jsx`, or other library source files (the patterns are in the build guide)
-2. Make **surgical edits** to the existing `EngineDashboard.tsx` — do NOT rewrite the entire file
-3. Add `useEngineLiveData` import and hook call
-4. Update every `useDataSource({ sample, live })` call to pass live data
-5. Update KPI overlays to derive from whichever metrics are active
-6. **Flip the backend switch:** change `ENABLE_SAMPLE_DATA_CACHE` from `true` to `false` in `src/lib/dataStrategy.ts` — this makes `CommandCenter.tsx` pass `initialMode="live"` to `DataModeProvider`, so every `useDataSource` call now returns the live prop. The dashboard will show completely different data: 12 global travelers (Raj Kapoor, Sofia Reyes…) instead of 8 US travelers, a Midwest storm scenario, and different metrics.
-7. After wiring is complete, **STOP and suggest** the `Weather_Impact__c` custom field — do NOT create it until the user confirms
-
-**What the agent must NOT do in this prompt:**
-- Do NOT rewrite `EngineDashboard.tsx` from scratch — make targeted edits to the existing Phase 1 file
-- Do NOT read library component source files (`useDataSource.jsx`, `DataModeProvider.jsx`, `dataStrategy.ts`) — the wiring patterns are in the build guide
-- Do NOT add `DataModeToggle` to the UI — there is no UI toggle, the switch is `dataStrategy.ts`
-- Do NOT create the custom field without asking first — suggest it, then wait for "yes"
-- Do NOT add ChatBar, Eva, or any Agentforce integration — that's Prompt 3
-- Do NOT run `npm run build` between edits
+**What the agent must do (exactly 5 edits + 1 suggestion):**
+
+1. Read ONLY `EngineDashboard.tsx` and `src/hooks/useEngineLiveData.ts` — no other files
+2. **Edit 1:** Add `useEngineLiveData` import to EngineDashboard.tsx
+3. **Edit 2:** Add `const live = useEngineLiveData()` hook call
+4. **Edit 3:** Update every `useDataSource({ sample, live: [] })` to pass `live: live.xxx`
+5. **Edit 4:** Update KPI derivations to use reactive metrics
+6. **Edit 5:** ⚠️ **CRITICAL — Flip `ENABLE_SAMPLE_DATA_CACHE` from `true` to `false` in `src/lib/dataStrategy.ts`** — without this, the data never switches and the demo fails
+7. After all edits, **STOP and suggest** ONLY `Weather_Impact__c` — do NOT create it until the user says yes
+
+**FORBIDDEN in Prompt 2:**
+- ❌ **`DataModeToggle`** — do NOT add it to the UI. There is NO UI toggle. The switch is `dataStrategy.ts`. This is the most common agent mistake.
+- ❌ Rewriting `EngineDashboard.tsx` from scratch (make 5 targeted edits)
+- ❌ Renaming existing imports with `SAMPLE_` prefix (leave variable names alone, just fill in `live:` props)
+- ❌ Reading library source files (`useDataSource.jsx`, `DataModeProvider.jsx`, `DataModeToggle.jsx`)
+- ❌ ChatBar, Eva, or Agentforce (Prompt 3)
+- ❌ Running `npm run build` between edits
+- ❌ Suggesting more than one custom field (only `Weather_Impact__c`)
+- ❌ Creating extra files not listed above
 
 **Reference — what the agent should say after wiring:**
 
@@ -397,20 +407,30 @@ Build incrementally in 3 prompts. Each prompt builds on the previous result. The
 
 > 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:**
-
-1. Make **surgical edits** to the existing `EngineDashboard.tsx` — do NOT rewrite the entire file
-2. Add `ChatBar` with suggestions from section 9, placed between map and data panels
-3. Add `useEvaAgent` hook — import from `@/hooks/useEvaAgent`, call `connect()` on mount, wire `sendMessage` to `handleChat`
-4. Do NOT use `AgentforceConversationClient` (the iframe widget) — we use the Agent REST API via the `useEvaAgent` hook
-5. After adding Eva, **STOP and suggest** the platform event — do NOT create it until the user confirms
-6. After user confirms and platform event is created, **STOP and suggest** the Apex class — do NOT create it until the user confirms
-
-**What the agent must NOT do in this prompt:**
-- Do NOT use `AgentforceConversationClient` — use `useEvaAgent` hook instead (Agent REST API)
-- Do NOT rewrite `EngineDashboard.tsx` from scratch — make targeted edits to the existing Phase 2 file
-- Do NOT create platform events or Apex classes without user confirmation — each is a scripted demo moment where you suggest, wait, then create
-- Do NOT read library component source files
+**Pre-installed files (already in the project — do NOT recreate):**
+- `src/hooks/useEvaAgent.ts` — Agent API hook (OAuth → session → messages → cleanup)
+- `src/config/agentApi.ts` — hardcoded credentials and endpoints
+- `vite.config.ts` — already has `/sf-oauth` and `/sf-agent` proxy rules
+
+**What the agent must do (exactly 4 edits + 2 suggestions):**
+
+1. Read ONLY `src/pages/EngineDashboard.tsx` — no other files
+2. **Edit 1:** Add `ChatBar` and `useEvaAgent` imports
+3. **Edit 2:** Add `CHAT_SUGGESTIONS` constant at module scope
+4. **Edit 3:** Add `useEvaAgent` hook call + `handleChat` handler inside component
+5. **Edit 4:** Insert `<ChatBar />` JSX between map and data panels
+6. After adding Eva, **STOP and suggest** the platform event — wait for user confirmation
+7. After platform event, **STOP and suggest** the Apex class — wait for user confirmation
+
+**FORBIDDEN in Prompt 3:**
+- ❌ **`AgentforceConversationClient`** — do NOT use the iframe widget. We use the Agent REST API via `useEvaAgent`.
+- ❌ **Wrapper hooks** — do NOT create `useEvaChatAdapter.ts`, `useDisruptionAlerts.ts`, or any extra hook file. Use `useEvaAgent` directly.
+- ❌ **`.env` or `.env.local` files** — config is hardcoded in `src/config/agentApi.ts`
+- ❌ **Recreating `useEvaAgent.ts`, `agentApi.ts`, or proxy config** — these are pre-installed
+- ❌ Rewriting `EngineDashboard.tsx` from scratch
+- ❌ Reading library source files (including `ChatBar.jsx`)
+- ❌ Creating platform events or Apex without user confirmation
+- ❌ Loading `agentforce-test`, `agentforce-observability`, or `outer-app` skills
 
 **Reference — what the agent should say (in sequence, stopping after each):**
 

package/package.json

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