@schandlergarcia/sf-web-components 1.9.74 → 1.9.75

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

@@ -89,9 +89,15 @@ The company logo is at `src/assets/images/engine_logo.png`. Import it as a modul
 ```jsx
 import engineLogo from "@/assets/images/engine_logo.png";
 
-<img src={engineLogo} alt="Engine" className="h-8 w-auto" />
+// On light backgrounds:
+<img src={engineLogo} alt="Engine" className="h-5 w-auto" />
+
+// On dark backgrounds (slate-900 header, dark mode):
+<img src={engineLogo} alt="Engine" className="h-5 w-auto brightness-0 invert" />
 ```
 
+The logo is black — use `brightness-0 invert` to make it white when placed on dark surfaces.
+
 - **Do not use external image URLs** (Unsplash, placeholder services, etc.) unless the user explicitly requests images.
 - **Do not use other asset images** (codey-*.png, etc.) unless the user asks for them.
 - **Preserve aspect ratio** — always use `w-auto` with a fixed height, or `h-auto` with a fixed width. Never set both `w-*` and `h-*` to fixed values on the logo or any image, as this distorts the aspect ratio.
@@ -346,10 +352,17 @@ Define schemas outside component body. Always `required: true` on mandatory fiel
 
 ## AI Chat & Agent
 
-Use `ChatBar` for dashboards, `ChatPanel` for full-page chat.
+Two components for agent integration:
+
+- **`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.
+
+```tsx
+import { AgentforceConversationClient } from "@/components/AgentforceConversationClient";
+
+<AgentforceConversationClient agentId="0Xxa5000000relhCAA" agentLabel="Eva" />
+```
 
-- Place `ChatBar` between the hero map and data panels (full-width, `px-4 pt-4`), NOT in the header
-- Always provide 3–5 `suggestions` for starter prompts
 - Return `components` for structured data — never markdown tables in text
 - Always set height on `ChatPanel`
 - Extract `onSend` handlers to module scope when shared
@@ -513,17 +526,15 @@ Instead, verify correctness by reviewing the code against the Pre-Completion Che
 
 ## Salesforce Metadata Patterns
 
-This is an SFDX project (`force-app/main/default/`). When the build requires metadata changes — permission sets, custom fields, flows, record types — write standard SFDX XML files and deploy with the Salesforce CLI.
+This is an SFDX project (`force-app/main/default/`). When the build requires metadata changes, write standard SFDX XML files and deploy with the Salesforce CLI.
 
 ### File locations
 
 | Metadata type | Path pattern |
 |---|---|
-| Permission Set | `force-app/main/default/permissionsets/{Name}.permissionset-meta.xml` |
 | Custom Field | `force-app/main/default/objects/{Object}/fields/{Field}.field-meta.xml` |
-| Flow | `force-app/main/default/flows/{Name}.flow-meta.xml` |
-| Record Type | `force-app/main/default/objects/{Object}/recordTypes/{Name}.recordType-meta.xml` |
-| Email Template | `force-app/main/default/email/{Folder}/{Name}.email-meta.xml` |
+| Platform Event | `force-app/main/default/objects/{Name}__e/{Name}__e.object-meta.xml` + `fields/` |
+| Apex Class | `force-app/main/default/classes/{Name}.cls` + `{Name}.cls-meta.xml` |
 
 ### Deploy command
 
@@ -531,16 +542,32 @@ This is an SFDX project (`force-app/main/default/`). When the build requires met
 sf project deploy start --source-dir force-app/main/default/permissionsets/MyPermSet.permissionset-meta.xml
 ```
 
-Use `--source-dir` to deploy individual files. For multiple files, point to the parent directory.
+Use `--source-dir` to deploy individual files. For multiple files, point to the parent directory. For Apex, use `--test-level NoTestRun` during development.
+
+### Platform Events
+
+Platform events are structured like custom objects under `objects/{Name}__e/`. The object file defines the event (`eventType: HighVolume`), and each field gets its own file under `fields/`. Deploy the whole directory at once:
+
+```bash
+sf project deploy start --source-dir force-app/main/default/objects/Travel_Disruption_Alert__e
+```
+
+### Apex Classes
+
+Apex classes need two files: the `.cls` source and a `.cls-meta.xml` with API version and status. Always use `with sharing` for security. Deploy with `--test-level NoTestRun` for development:
+
+```bash
+sf project deploy start --source-dir force-app/main/default/classes/TravelDisruptionEventService.cls --test-level NoTestRun
+```
 
 ### When to create metadata
 
-During the build, proactively check whether the Salesforce org has the metadata needed for the features you're building. If something is missing — a field isn't accessible, a record type doesn't exist, a flow would automate a manual process — tell the user what's missing and ask before creating it. The PRD's build prompts include specific scripted moments for these interactions.
+During the build, proactively create the Salesforce metadata needed for the features you're building. If the dashboard needs field access, create a permission set. If a new field would improve the data model, create it. If automation would enhance a workflow, create a flow. Tell the user what you're creating and ask before doing it. The PRD's build prompts (section 13) include specific instructions for these interactions, with XML templates in section 14.
 
 ### Key rules
 
 - Always use API version `62.0` or higher
-- Permission set field permissions: set `readable` to `true`, `editable` to `false` for read-only dashboard fields
-- Flows: set `status` to `Draft` — the user will activate after review
+- Platform events: use `HighVolume` event type
+- Apex: use `with sharing`, handle `Database.SaveResult` errors when publishing events
 - Never deploy destructive changes without explicit confirmation
 - Never modify standard Salesforce objects' core fields — only add custom fields

package/CHANGELOG.md

@@ -5,6 +5,26 @@ 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.75] - 2026-04-02
+
+### Updated
+- **PRD (engine-command-center-prd.md)** - Metadata and agent integration updates:
+  - Reframed permission set as "creating" not "flagging security" (then removed it entirely)
+  - Moved metadata instructions inside prompt blockquotes so agent executes them
+  - Added AgentforceConversationClient with `agentId="0Xxa5000000relhCAA"` to Section 9 and Prompt 3
+  - Trimmed metadata from 7 items to 3 (custom field, platform event, Apex class)
+  - Removed permission set, flow, record type, email template from prompts and Section 14
+  - Renumbered Section 14 to 14a/14b/14c
+
+- **Builder skill (SKILL.md)** - Agent and metadata pattern updates:
+  - Updated "AI Chat & Agent" section with AgentforceConversationClient pattern and agent ID
+  - Added Platform Event and Apex Class to metadata file locations table
+  - Added deploy patterns for platform events and Apex classes
+  - Trimmed metadata table and key rules to match the 3 remaining types
+  - Removed permission set, flow, record type, email template references
+
+**Context:** Streamlined metadata to 3 core types (custom field, platform event, Apex class) and added explicit AgentforceConversationClient integration with agent ID.
+
 ## [1.9.74] - 2026-04-02
 
 ### Added

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

@@ -107,7 +107,13 @@ Compact `h-12` sticky header (`bg-slate-900 dark:bg-slate-950`). No ChatBar in t
 
 | Left | Right |
 |------|-------|
-| Engine logo (`GlobeAltIcon` in `bg-brand-600` square) + "ENGINE" wordmark + separator + "Travel Command Center" + "Powered by Agentforce" badge (`bg-brand-900/40 text-brand-400 rounded-full text-[10px]`) | Notification bell (badge count) + theme toggle (sun/moon) |
+| Engine logo (`engine_logo.png`, `h-5 w-auto brightness-0 invert` to make it white on the dark header) + "ENGINE" wordmark + separator + "Travel Command Center" + "Powered by Agentforce" badge (`bg-brand-900/40 text-brand-400 rounded-full text-[10px]`) | Notification bell (badge count) + theme toggle (sun/moon) |
+
+```tsx
+import engineLogo from "@/assets/images/engine_logo.png";
+
+<img src={engineLogo} alt="Engine" className="h-5 w-auto brightness-0 invert" />
+```
 
 ---
 
@@ -246,9 +252,11 @@ const spendChartData = useDataSource({
 
 ---
 
-## 9. Eva — ChatBar
+## 9. Eva — Agentforce Integration
 
-Eva renders as a full-width `ChatBar` below the hero map, between the map and the data panels. NOT in the header. NOT a FAB or sliding panel.
+Two components work together:
+
+**ChatBar** — a command-palette strip below the hero map for quick suggested prompts. NOT in the header. NOT a FAB or sliding panel.
 
 ```tsx
 <div className="px-4 pt-4">
@@ -265,6 +273,19 @@ Suggestions: "Storm warning in the Midwest — which travelers are affected?", "
 
 Define `handleChat` and `CHAT_SUGGESTIONS` at module scope.
 
+**AgentforceConversationClient** — the real Salesforce agent. Wire it with the Eva agent ID. Place it at the bottom of the dashboard component (it renders as a floating widget).
+
+```tsx
+import { AgentforceConversationClient } from "@/components/AgentforceConversationClient";
+
+<AgentforceConversationClient
+  agentId="0Xxa5000000relhCAA"
+  agentLabel="Eva"
+/>
+```
+
+The `AgentforceConversationClient` is already in the codebase (commented out in `appLayout.tsx`). Uncomment it or add it directly to the dashboard with the agent ID above.
+
 ---
 
 ## 10. Salesforce Signals
@@ -327,60 +348,31 @@ Build incrementally in 3 prompts. Each prompt builds on the previous result.
 > const activeMetrics = live.loading ? METRICS : live.metrics;
 > ```
 >
-> When the page loads, the audience will see: sample data renders immediately → after 2 seconds components refresh with different travelers, cities, and numbers → proving the data integration works. The layout stays identical — only the data changes.
+> 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`.
 
-**Scripted metadata interaction — Permission Set:**
-After wiring the live data, check the field-level security for the objects being queried. The `External_Travel_Manager` permission set does not have read access to `Disruption__c.Severity__c`. Tell the user:
+**Reference — what the agent should say and do:**
 
-> "I notice the `External_Travel_Manager` permission set doesn't have read access to `Disruption__c.Severity__c`. This field is needed to display disruption severity in the dashboard. Would you like me to update the permission set?"
+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.
 
-When the user confirms, create:
+---
 
-`force-app/main/default/permissionsets/External_Travel_Manager.permissionset-meta.xml`
+### Add Agentforce
 
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<PermissionSet xmlns="http://soap.sforce.com/2006/04/metadata">
-    <label>External Travel Manager</label>
-    <description>Field access for the Engine Travel Command Center dashboard</description>
-    <fieldPermissions>
-        <editable>false</editable>
-        <field>Disruption__c.Severity__c</field>
-        <readable>true</readable>
-    </fieldPermissions>
-    <fieldPermissions>
-        <editable>false</editable>
-        <field>Disruption__c.Affected_Traveler_Count__c</field>
-        <readable>true</readable>
-    </fieldPermissions>
-    <fieldPermissions>
-        <editable>false</editable>
-        <field>Flight__c.Delay_Minutes__c</field>
-        <readable>true</readable>
-    </fieldPermissions>
-    <fieldPermissions>
-        <editable>false</editable>
-        <field>Flight__c.Flight_Status__c</field>
-        <readable>true</readable>
-    </fieldPermissions>
-    <fieldPermissions>
-        <editable>false</editable>
-        <field>Rebooking_Action__c.Status__c</field>
-        <readable>true</readable>
-    </fieldPermissions>
-    <hasActivationRequired>false</hasActivationRequired>
-    <license>Salesforce</license>
-</PermissionSet>
-```
+> 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`.
+
+**Reference — what the agent should say and do:**
 
-Then run: `sf project deploy start --source-dir force-app/main/default/permissionsets/External_Travel_Manager.permissionset-meta.xml`
+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.
+
+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.
+
+---
 
-**Scripted metadata interaction — Custom Field:**
-After fixing the permission set, notice that `Flight__c` has no way to track weather impact on individual flights. Tell the user:
+## 14. Metadata Reference Templates
 
-> "There's no `Weather_Impact__c` field on `Flight__c` to track weather-related disruptions. This would help the dashboard filter storm-affected flights. Want me to create it?"
+Templates for the scripted metadata interactions. The agent should use these exact structures when creating files.
 
-When the user confirms, create:
+### 14a. Custom Field — `Flight__c.Weather_Impact__c`
 
 `force-app/main/default/objects/Flight__c/fields/Weather_Impact__c.field-meta.xml`
 
@@ -404,101 +396,108 @@ When the user confirms, create:
 </CustomField>
 ```
 
-Then run: `sf project deploy start --source-dir force-app/main/default/objects/Flight__c/fields/Weather_Impact__c.field-meta.xml`
-
-Also update the permission set to include read access to the new field.
-
----
-
-### Add Agentforce
-
-> 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.
+Deploy: `sf project deploy start --source-dir force-app/main/default/objects/Flight__c/fields/Weather_Impact__c.field-meta.xml`
 
-**Scripted metadata interaction — Flow for Weather Notifications:**
-After adding the ChatBar, tell the user:
+### 14b. Platform Event — `Travel_Disruption_Alert__e`
 
-> "Since the dashboard handles weather disruptions, I can create a Flow that automatically sends weather delay alerts to affected travelers. It would query `Disruption__c` records where `Disruption_Type__c = 'Weather Event'`, match them to `Contact` records via `Flight__c`, and send a notification email. Want me to build it?"
+Create the event object and its fields:
 
-When the user confirms, create:
-
-`force-app/main/default/flows/Travel_Weather_Alert_Notification.flow-meta.xml`
+`force-app/main/default/objects/Travel_Disruption_Alert__e/Travel_Disruption_Alert__e.object-meta.xml`
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
-<Flow xmlns="http://soap.sforce.com/2006/04/metadata">
-    <apiVersion>62.0</apiVersion>
-    <label>Travel Weather Alert Notification</label>
-    <description>Sends weather delay alerts to travelers affected by disruptions. Triggered when a Disruption__c record is created or updated with Disruption_Type__c = Weather Event.</description>
-    <status>Draft</status>
-    <processType>AutoLaunchedFlow</processType>
-    <start>
-        <object>Disruption__c</object>
-        <triggerType>RecordAfterSave</triggerType>
-        <recordTriggerType>CreateAndUpdate</recordTriggerType>
-        <filterLogic>and</filterLogic>
-        <filters>
-            <field>Disruption_Type__c</field>
-            <operator>EqualTo</operator>
-            <value><stringValue>Weather Event</stringValue></value>
-        </filters>
-    </start>
-    <interviewLabel>Travel Weather Alert {!$Flow.CurrentDateTime}</interviewLabel>
-</Flow>
+<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
+    <label>Travel Disruption Alert</label>
+    <pluralLabel>Travel Disruption Alerts</pluralLabel>
+    <description>Published when a travel disruption is detected. Subscribers can react to real-time flight delays, weather events, and rebooking triggers.</description>
+    <deploymentStatus>Deployed</deploymentStatus>
+    <eventType>HighVolume</eventType>
+</CustomObject>
 ```
 
-Then run: `sf project deploy start --source-dir force-app/main/default/flows/Travel_Weather_Alert_Notification.flow-meta.xml`
-
-**Scripted metadata interaction — Case Record Type:**
-After creating the Flow, tell the user:
-
-> "The 'Create a support case' prompt needs a dedicated record type. The Case object doesn't have a `Travel_Support` record type yet. Should I create it?"
-
-When the user confirms, create:
-
-`force-app/main/default/objects/Case/recordTypes/Travel_Support.recordType-meta.xml`
+`force-app/main/default/objects/Travel_Disruption_Alert__e/fields/Flight_Number__c.field-meta.xml`
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
-<RecordType xmlns="http://soap.sforce.com/2006/04/metadata">
-    <fullName>Travel_Support</fullName>
-    <label>Travel Support</label>
-    <description>Support cases for travel disruptions, rebookings, and weather events</description>
-    <active>true</active>
-</RecordType>
+<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
+    <fullName>Flight_Number__c</fullName>
+    <label>Flight Number</label>
+    <type>Text</type>
+    <length>20</length>
+    <required>false</required>
+</CustomField>
 ```
 
-Then run: `sf project deploy start --source-dir force-app/main/default/objects/Case/recordTypes/Travel_Support.recordType-meta.xml`
-
-**Scripted metadata interaction — Email Template:**
-Finally, tell the user:
+`force-app/main/default/objects/Travel_Disruption_Alert__e/fields/Severity__c.field-meta.xml`
 
-> "I'll also create an email template for weather delay notifications — the Flow can use it to send branded alerts with flight details and alternate routing options."
-
-Create:
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
+    <fullName>Severity__c</fullName>
+    <label>Severity</label>
+    <type>Text</type>
+    <length>20</length>
+    <required>false</required>
+</CustomField>
+```
 
-`force-app/main/default/email/Travel_Alerts/Weather_Delay_Notification.email-meta.xml`
+`force-app/main/default/objects/Travel_Disruption_Alert__e/fields/Description__c.field-meta.xml`
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
-<EmailTemplate xmlns="http://soap.sforce.com/2006/04/metadata">
-    <name>Weather Delay Notification</name>
-    <available>true</available>
-    <description>Sent to travelers when their flight is affected by a weather disruption</description>
-    <encodingKey>UTF-8</encodingKey>
-    <style>freeForm</style>
-    <subject>Weather Alert: Your flight {!Flight__c.Flight_Number__c} is affected</subject>
-    <type>custom</type>
-    <textOnly>Hi {!Contact.FirstName},
-
-Your flight {!Flight__c.Flight_Number__c} ({!Flight__c.Departure_Airport__c} → {!Flight__c.Arrival_Airport__c}) has been affected by severe weather.
+<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
+    <fullName>Description__c</fullName>
+    <label>Description</label>
+    <type>LongTextArea</type>
+    <length>1000</length>
+    <visibleLines>3</visibleLines>
+    <required>false</required>
+</CustomField>
+```
 
-Current delay: {!Disruption__c.Description__c}
-Eva is monitoring the situation and will notify you of any changes.
+Deploy: `sf project deploy start --source-dir force-app/main/default/objects/Travel_Disruption_Alert__e`
+
+### 14c. Apex Class — `TravelDisruptionEventService`
+
+`force-app/main/default/classes/TravelDisruptionEventService.cls`
+
+```apex
+public with sharing class TravelDisruptionEventService {
+
+    public static void publishDisruptionAlerts(List<Disruption__c> disruptions) {
+        List<Travel_Disruption_Alert__e> events = new List<Travel_Disruption_Alert__e>();
+
+        for (Disruption__c d : disruptions) {
+            events.add(new Travel_Disruption_Alert__e(
+                Flight_Number__c = d.Flight_Number__c,
+                Severity__c      = d.Severity__c,
+                Description__c   = d.Description__c
+            ));
+        }
+
+        if (!events.isEmpty()) {
+            List<Database.SaveResult> results = EventBus.publish(events);
+            for (Database.SaveResult sr : results) {
+                if (!sr.isSuccess()) {
+                    for (Database.Error err : sr.getErrors()) {
+                        System.debug(LoggingLevel.ERROR,
+                            'Failed to publish Travel_Disruption_Alert__e: ' + err.getMessage());
+                    }
+                }
+            }
+        }
+    }
+}
+```
 
-If you need immediate assistance, reply to this email or ask Eva in the Engine Travel app.
+`force-app/main/default/classes/TravelDisruptionEventService.cls-meta.xml`
 
-— Engine Travel Team</textOnly>
-</EmailTemplate>
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>62.0</apiVersion>
+    <status>Active</status>
+</ApexClass>
 ```
 
-Then run: `sf project deploy start --source-dir force-app/main/default/email/`
+Deploy: `sf project deploy start --source-dir force-app/main/default/classes/TravelDisruptionEventService.cls --test-level NoTestRun`

package/package.json

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