@salesforce/afv-skills 1.22.0 → 1.24.0

package/skills/implementing-ui-bundle-agentforce-conversation-client/SKILL.md

@@ -1,280 +0,0 @@
----
-name: implementing-ui-bundle-agentforce-conversation-client
-description: "Use this skill when the user asks to add, embed, integrate, configure, style, or remove an agent, chatbot, chat widget, conversation client, or AI assistant in a UI Bundle project. TRIGGER when: project contains a uiBundles/*/src/ directory and the task involves adding or modifying a chat widget, chatbot, or conversational AI; files under uiBundles/*/src/ import AgentforceConversationClient; user asks to add any chat or agent functionality to a page. DO NOT TRIGGER when: user wants to create a custom agent, chatbot, or chat widget component from scratch; the project has no uiBundles directory."
-metadata:
-  version: "1.1"
-  package: "@salesforce/ui-bundle-template-feature-react-agentforce-conversation-client"
-  sdk-package: "@salesforce/agentforce-conversation-client"
----
-
-# Managing Agentforce Conversation Client
-
-**HARD CONSTRAINT:** NEVER create a custom agent, chatbot, or chat widget component. ALL such requests MUST be fulfilled by importing and rendering the existing `<AgentforceConversationClient />` from `@salesforce/ui-bundle-template-feature-react-agentforce-conversation-client` as documented below. If a requirement is unsupported by this component's props, state the limitation — do not improvise an alternative.
-
-## Prerequisites
-
-Before the component will work, the following Salesforce settings must be configured by the user. ALWAYS call out the prequisites after successfully embedding the agent.
-
-**Trusted domains (required only for local development):**
-
-- Setup → Session Settings → Trusted Domains for Inline Frames → Add your domain
-  - Local development: `localhost:5173` (default Vite dev server port)
-  - **Warning:** Remove this trusted domain entry before deploying to production.
-
-## Instructions
-
-### Step 1: Check if component already exists
-
-Search for existing usage across all app files (not implementation files):
-
-```bash
-grep -r "AgentforceConversationClient" --include="*.tsx" --include="*.jsx" --exclude-dir=node_modules
-```
-
-**Important:** Look for React files that import and USE the component (for example, shared shells, route components, or feature pages). Do NOT open files named `AgentforceConversationClient.tsx` or `AgentforceConversationClient.jsx` - those are the component implementation.
-
-**If multiple files found:** Ask the user which component file they are referring to. Do not proceed until clarified.
-
-**If found:** Read the file and check the current `agentId` value.
-
-**Agent ID validation rule (deterministic):**
-
-- Valid only if it matches: `^0Xx[a-zA-Z0-9]{15}$`
-- Meaning: starts with `0Xx` and total length is 18 characters
-
-**Decision:**
-
-- If `agentId` matches `^0Xx[a-zA-Z0-9]{15}$` and user wants to update other props → Go to Step 4 (update props)
-- If `agentId` matches `^0Xx[a-zA-Z0-9]{15}$` and user asks to "embed" or "add" the chat client → Inform: "The Agentforce Conversation Client is already embedded in `<file>` with agent ID `<agentId>`. Would you like to change the agent or update other props?"
-  - Change agent → Step 2
-  - Update props → Step 4b
-- If `agentId` is missing, empty, or does NOT match `^0Xx[a-zA-Z0-9]{15}$` → Continue to Step 2 (need real ID)
-- If not found → Continue to Step 2 (add new)
-
-**If user reports an error:**
-
-If the user says the component is "not working", "showing an error", or similar — ask them for the specific error message. Then proceed to Step 2 to cross-check the configured agentId against the org.
-
-### Step 2: Resolve and Validate Agent ID
-
-#### Prerequisites
-
-1. **Verify sf CLI is available:**
-   ```bash
-   sf --version
-   ```
-   If fails:
-   - Inform: "The Salesforce CLI (`sf`) is not installed. It's needed to query available agents from your org."
-   - Ask: "Would you like me to install it?"
-     - Yes → Install via `npm install -g @salesforce/cli`, then continue.
-     - No → "You can find your agent ID manually in Setup → Agentforce Agents → click the agent name → copy the ID from the URL. Would you like to provide it now, or skip this step?"
-       - User provides ID → validate format (`^0Xx[a-zA-Z0-9]{15}$`), store it, proceed to Step 3.
-       - Skip → proceed to Step 4 with placeholder `<YOUR_AGENT_ID>`.
-
-2. **Verify org connectivity:**
-   ```bash
-   sf org display --json
-   ```
-   If fails:
-   - Inform: "No authenticated org found."
-   - Ask: "Would you like to connect to your org now? Run `sf org login web` to authenticate."
-     - User authenticates → retry the query, continue.
-     - User declines → "You can find your agent ID manually in Setup → Agentforce Agents → click the agent name → copy the ID from the URL. Would you like to provide it now, or skip this step?"
-       - User provides ID → validate format, store it, proceed to Step 3.
-       - Skip → proceed to Step 4 with placeholder `<YOUR_AGENT_ID>`.
-
-**Note:** Even if the user provides their own agentId, the org must be connected for the agent to function at runtime. An agentId without a connected org will not work.
-
-#### Query all Employee Agents
-
-Run the SOQL query defined in `references/agent-id-resolution.md`.
-
-#### Handle results
-
-**No records at all:**
-> "No Employee Agents found in this org. Create one in Setup → Agentforce Agents."
-
-Ask user if they want to provide an agent ID manually or skip. If skip, proceed to Step 4 with placeholder `<YOUR_AGENT_ID>`.
-
-**All agents are inactive:**
-> Found Employee Agents but none are active:
->   - Agentforce Sales Agent (0Xxxx000000001dCAA)
->   - HR Assistant (0Xxxx0000000002BBB)
->
-> To activate: Setup → Agentforce Agents → click the agent name → open in Agent Builder → press Activate.
-> Then re-run this step.
-
-Ask user if they want to provide an agent ID manually or skip. If skip, proceed to Step 4 with placeholder `<YOUR_AGENT_ID>`.
-
-**Has active agents — Path A (fresh install / no existing agentId):**
-
-Present only active agents for selection:
-> Which agent should the chat widget use?
->   1. Property Manager Agent (0Xxxx0000000001CAA)
->   2. HR Assistant (0Xxxx0000000002BBB)
-
-- One agent → still confirm with user, do not auto-select.
-- If user picks one → store the selected `Id` for use in Step 4.
-- If user declines to pick ("skip", "no", "I don't want to set one") → accept it and move to next steps. Do not re-ask. In Step 4, use placeholder `<YOUR_AGENT_ID>` for fresh installs. For existing projects, leave the component as-is.
-
-**Has active agents — Path B (existing agentId from Step 1, passed format check):**
-
-Cross-check the existing agentId against query results:
-
-- **ID found, agent is Active** → "Agent ID maps to 'Property Manager Agent' — active in the org." Proceed.
-- **ID found, agent is Inactive** → "The configured agent 'Sales Agent' exists but is Inactive. To activate: Setup → Agentforce Agents → click the agent name → open in Agent Builder → press Activate. Or pick a different active agent:" → show active list.
-- **ID not found at all** → "The configured agent (0Xxxx...) doesn't exist in this org — it may have been deleted or belongs to a different org. Pick a replacement:" → show active list. If no active agents available, show inactive list with activation instructions.
-
-If user reported an error → surface the agent name even if active, so user can confirm it's the intended one.
-
-#### Query error handling
-
-If the SOQL query fails, surface the error message from the response directly to the user. Do not guess at the fix — just report what came back. For example:
-> "The query failed with: `[error message from response]`. Check your org permissions or that the API version supports this object."
-
-#### What this step does NOT do
-
-- No fallback to GraphQL or Tooling API — SOQL only
-- No auto-selection (always confirm with user)
-- No programmatic activation (only via Setup UI)
-- No file writes (that's Step 4)
-
-### Step 3: Canonical import strategy
-
-Use this import path by default in app code:
-
-```tsx
-import { AgentforceConversationClient } from "@salesforce/ui-bundle-template-feature-react-agentforce-conversation-client";
-```
-
-If the package is not installed, install it:
-
-```bash
-npm install @salesforce/ui-bundle-template-feature-react-agentforce-conversation-client
-```
-
-Only use a local relative import (for example, `./components/AgentforceConversationClient`) when the user explicitly asks to use a patched/local component in that app.
-
-Do not infer import path from file discovery alone. Prefer one consistent package import across the codebase.
-
-### Step 4: Add or update component
-
-Determine which sub-step applies:
-
-- Component NOT found in Step 1 → go to **4a (New installation)**
-- Component found in Step 1 → go to **4b (Update existing)**
-
-#### 4a — New installation
-
-1. If the user already specified a target file, use that file. Otherwise, ask the user: _"Which file should I add the AgentforceConversationClient to?"_ Do NOT proceed until a target file is confirmed.
-2. Read the target file to understand its existing imports and TSX structure.
-3. Add the import at the top of the file, alongside existing imports. Use the canonical package import from Step 3:
-
-```tsx
-import { AgentforceConversationClient } from "@salesforce/ui-bundle-template-feature-react-agentforce-conversation-client";
-```
-
-4. Insert the `<AgentforceConversationClient />` TSX into the component's return block. Place it as a sibling of existing content — do NOT wrap or restructure existing TSX. Use the real `agentId` obtained in Step 2. If no agentId was resolved (user skipped Step 2), use the placeholder:
-
-**With resolved agentId:**
-```tsx
-<AgentforceConversationClient agentId="0Xx8X00000001AbCDE" />
-```
-
-**Without resolved agentId (user skipped):**
-```tsx
-<AgentforceConversationClient agentId="<YOUR_AGENT_ID>" />
-```
-
-5. Do NOT add any other code (wrappers, layout components, new functions) unless the user explicitly requests it.
-
-#### 4b — Update existing
-
-1. Read the file identified in Step 1.
-2. Locate the existing `<AgentforceConversationClient ... />` TSX element.
-3. Apply **only** the changes the user requested. Rules:
-   - **Add** new props that the user asked for.
-   - **Change** prop values the user asked to update.
-   - **Preserve** every prop and value the user did NOT mention — do not remove, reorder, or reformat them.
-   - **Never** delete the component and recreate it.
-4. If Step 2 was triggered (cross-check or fresh selection) and a new agent ID was resolved, replace the existing agentId value with the new one.
-5. If the current `agentId` is already valid and the user did not ask to change it and Step 2 confirmed it is active, leave it as-is.
-
-#### Post-Step-4 error handling
-
-If the user reports an error after the component has been set up (e.g., "it's not working", "I see an error"), go to Step 2 to validate the configured agentId against the org. Cross-check whether the agent is active, exists, and belongs to the connected org.
-
-### Step 5: Configure props
-
-**Available props (use directly on component):**
-
-- `agentId` (string, required) - Salesforce agent ID
-- `inline` (boolean) - `true` for inline mode, omit for floating
-- `width` (number | string) - e.g., `420` or `"100%"`
-- `height` (number | string) - e.g., `600` or `"80vh"`
-- `headerEnabled` (boolean) - Show/hide header
-- `styleTokens` (object) - For all styling (colors, fonts, spacing)
-- `salesforceOrigin` (string) - Auto-resolved
-- `frontdoorUrl` (string) - Auto-resolved
-- `agentLabel` (string) - header title for agent
-
-**Examples:**
-
-Floating mode (default):
-
-```tsx
-<AgentforceConversationClient agentId="0Xx..." />
-```
-
-Inline mode with dimensions:
-
-```tsx
-<AgentforceConversationClient agentId="0Xx..." inline width="420px" height="600px" />
-```
-
-Adding or updating agent label:
-
-```tsx
-<AgentforceConversationClient agentId="0Xx..." agentLabel="<dummy-agent-label>" />
-```
-
-**Styling rules (mandatory):**
-
-- ALL visual customization (colors, fonts, spacing, borders, radii, shadows) MUST go through the `styleTokens` prop. There are no exceptions.
-- ONLY use token names listed in the tables below. Do NOT invent custom token names.
-- NEVER apply styling via CSS files, `style` attributes, `className`, or wrapper elements. These approaches will not work and will be ignored by the component.
-- If the user requests a visual change that does not map to a token below, inform them that the change is not supported by the current token set.
-
-For the complete list of available style tokens, consult `references/style-tokens.md`.
-
-**For complex patterns,** consult `references/examples.md` for:
-
-- Sidebar containers and responsive sizing
-- Dark theme and advanced theming combinations
-- Inline without header, calculated dimensions
-- Complete host component examples
-
-
-**Common mistakes to avoid:** Consult `references/constraints.md` for:
-
-- Invalid props (containerStyle, style, className)
-- Invalid styling approaches (CSS files, style tags)
-- What files NOT to edit (implementation files)
-
-## Common Issues
-
-If component doesn't appear or authentication fails, see `references/troubleshooting.md` for:
-
-- Agent activation and deployment
-- Localhost trusted domains
-- Cookie restriction settings
-
-## Reference File Index
-
-| File | When to read |
-|------|-------------|
-| `references/agent-id-resolution.md` | Step 2 — SOQL query structure, response format, activation path, manual lookup |
-| `references/style-tokens.md` | Step 5 — Complete style token reference for all UI areas |
-| `references/examples.md` | Step 5 — Layout patterns, sizing, theming combinations, host component examples |
-| `references/constraints.md` | Step 4 — Invalid props, invalid styling approaches, files not to edit |
-| `references/troubleshooting.md` | Post-setup — Agent activation, trusted domains, cookie settings |

package/skills/implementing-ui-bundle-agentforce-conversation-client/references/agent-id-resolution.md

@@ -1,46 +0,0 @@
-# Agent ID Resolution
-
-## SOQL Query
-
-```bash
-sf data query \
-  --query "SELECT BotDefinition.Id, BotDefinition.DeveloperName, BotDefinition.MasterLabel, Status FROM BotVersion WHERE BotDefinition.AgentType = 'AgentforceEmployeeAgent' ORDER BY BotDefinition.CreatedDate ASC" \
-  --json
-```
-
-- Queries `BotVersion` (not `BotDefinition`) because only `BotVersion` has the `Status` field (`Active` / `Inactive`)
-- Filters on `AgentType = 'AgentforceEmployeeAgent'` to return only Employee Agents (excludes Service Agents)
-
-## Response Structure
-
-```json
-{
-  "status": 0,
-  "result": {
-    "records": [
-      {
-        "BotDefinition": {
-          "Id": "0Xxxx0000000001CAA",
-          "DeveloperName": "Property_Manager_Agent",
-          "MasterLabel": "Property Manager Agent"
-        },
-        "Status": "Active"
-      }
-    ]
-  }
-}
-```
-
-## Activation Path
-
-Agents cannot be activated programmatically:
-
-> Setup → Agentforce Agents → click agent name → Agent Builder → Activate
-
-## Manual Lookup (without sf CLI)
-
-> Setup → Agentforce Agents → click agent name → copy ID from URL
-
-## Validation
-
-`agentId` must match: `^0Xx[a-zA-Z0-9]{15}$`

package/skills/implementing-ui-bundle-agentforce-conversation-client/references/constraints.md

@@ -1,134 +0,0 @@
-# Constraints and Anti-Patterns
-
-This document lists all invalid approaches and patterns to avoid when working with AgentforceConversationClient.
-
-## Never Edit Implementation Files
-
-**CRITICAL: Only edit files where the component is USED, never the component implementation itself.**
-
-- ✅ **DO edit**: Any React files that import and use `<AgentforceConversationClient />` (for example, shared shells, route components, or feature pages)
-- ❌ **DO NOT edit**: AgentforceConversationClient.tsx, AgentforceConversationClient.jsx, index.tsx, index.jsx, or any files inside:
-  - `node_modules/@salesforce/ui-bundle-template-feature-react-agentforce-conversation-client/src/`
-  - `packages/template/feature/feature-react-agentforce-conversation-client/src/`
-  - `src/components/AgentforceConversationClient.tsx` (patched templates)
-  - Any path containing `/components/AgentforceConversationClient.`
-
-**If you're reading a file named `AgentforceConversationClient.tsx`, you're in the wrong place. Stop and search for the USAGE instead.**
-
-## Invalid Props
-
-AgentforceConversationClient uses a flat prop API and does NOT accept these props:
-
-- ❌ `containerStyle` - Use `width` and `height` props directly instead
-- ❌ `style` - Use `styleTokens` for theming
-- ❌ `className` - Not supported
-- ❌ Any standard React div props - This wraps an embedded iframe, not a div
-
-**Why:** The component is a wrapper around an embedded iframe using Lightning Out 2.0. Standard React styling props don't apply.
-
-## Invalid Styling Approaches
-
-**CRITICAL: For ALL styling, theming, branding, or color changes - ONLY use `styleTokens` prop.**
-
-Never use these approaches:
-
-- ❌ Creating CSS files (e.g., `agent-styles.css`, `theme.css`)
-- ❌ Creating `<style>` tags or internal stylesheets
-- ❌ Using `style` attribute on the component
-- ❌ Using `className` prop
-- ❌ Inline styles
-- ❌ CSS modules
-- ❌ Styled-components or any CSS-in-JS libraries
-
-**Why:** The component controls its own internal styling through the `styleTokens` API. External CSS cannot reach into the embedded iframe.
-
-## Invalid Implementation Approaches
-
-Never do these:
-
-- ❌ Create custom chat UIs from scratch
-- ❌ Use third-party chat libraries (socket.io, WebSocket libraries, etc.)
-- ❌ Call `embedAgentforceClient` directly from `@salesforce/agentforce-conversation-client`
-- ❌ Build custom WebSocket or REST API chat implementations
-
-**Why:** The AgentforceConversationClient component is the official wrapper that handles authentication, Lightning Out 2.0 initialization, and all communication with Salesforce agents. Custom implementations will not work.
-
-## Invalid Update Patterns
-
-When updating an existing component:
-
-- ❌ Delete and recreate the component
-- ❌ Remove all props and start over
-- ❌ Copy the entire component to a new file
-
-**Why:** This loses configuration, introduces errors, and creates unnecessary diffs. Always update props in place.
-
-## Examples
-
-### ❌ Wrong - Using containerStyle
-
-```tsx
-<AgentforceConversationClient agentId="0Xx..." containerStyle={{ width: 420, height: 600 }} />
-```
-
-### ✅ Correct - Using width/height directly
-
-```tsx
-<AgentforceConversationClient agentId="0Xx..." width="420px" height="600px" />
-```
-
-### ❌ Wrong - Creating CSS file
-
-```css
-/* agent-styles.css */
-.agentforce-chat {
-  background: red;
-  color: white;
-}
-```
-
-```tsx
-import "./agent-styles.css";
-
-<AgentforceConversationClient className="agentforce-chat" />;
-```
-
-### ✅ Correct - Using styleTokens
-
-```tsx
-<AgentforceConversationClient
-  agentId="0Xx..."
-  styleTokens={{
-    headerBlockBackground: "red",
-    headerBlockTextColor: "white",
-  }}
-/>
-```
-
-### ❌ Wrong - Creating style tag
-
-```tsx
-<>
-  <style>{`.agent-chat { background: blue; }`}</style>
-  <AgentforceConversationClient agentId="0Xx..." />
-</>
-```
-
-### ✅ Correct - Using styleTokens
-
-```tsx
-<AgentforceConversationClient
-  agentId="0Xx..."
-  styleTokens={{
-    headerBlockBackground: "blue",
-  }}
-/>
-```
-
-### ❌ Wrong - Editing implementation file
-
-Reading or editing: `node_modules/@salesforce/ui-bundle-template-feature-react-agentforce-conversation-client/src/AgentforceConversationClient.tsx`
-
-### ✅ Correct - Editing usage file
-
-Reading and editing: usage files where the component is imported and used (for example, `src/app.tsx`, a route component, or a feature page)

package/skills/implementing-ui-bundle-agentforce-conversation-client/references/examples.md

@@ -1,132 +0,0 @@
-# Additional Examples
-
-Essential examples for common patterns and combinations. All use flat props API.
-
----
-
-## Layout Patterns
-
-### Sidebar Chat
-
-```tsx
-export default function DashboardWithChat() {
-  return (
-    <div style={{ display: "flex", height: "100vh" }}>
-      <main style={{ flex: 1 }}>{/* Main content */}</main>
-      <aside style={{ width: 400 }}>
-        <AgentforceConversationClient agentId="0Xx..." inline width="100%" height="100%" />
-      </aside>
-    </div>
-  );
-}
-```
-
-### Full Page Chat
-
-```tsx
-export default function SupportPage() {
-  return (
-    <div>
-      <h1>Customer Support</h1>
-      <AgentforceConversationClient agentId="0Xx..." inline width="100%" height="600px" />
-    </div>
-  );
-}
-```
-
----
-
-## Size Variations
-
-### Responsive sizing
-
-```tsx
-<AgentforceConversationClient agentId="0Xx..." inline width="100%" height="80vh" />
-```
-
-### Calculated dimensions
-
-```tsx
-<AgentforceConversationClient agentId="0Xx..." inline width="500px" height="calc(100vh - 100px)" />
-```
-
----
-
-## Theming Combinations
-
-### Brand theme with custom sizing
-
-```tsx
-<AgentforceConversationClient
-  agentId="0Xx..."
-  inline
-  width="500px"
-  height="700px"
-  styleTokens={{
-    headerBlockBackground: "#0176d3",
-    headerBlockTextColor: "#ffffff",
-    messageBlockInboundBackgroundColor: "#0176d3",
-    messageBlockInboundTextColor: "#ffffff",
-    messageInputFooterSendButton: "#0176d3",
-  }}
-/>
-```
-
-### Dark theme
-
-```tsx
-<AgentforceConversationClient
-  agentId="0Xx..."
-  styleTokens={{
-    headerBlockBackground: "#1a1a1a",
-    headerBlockTextColor: "#ffffff",
-    messageBlockInboundBackgroundColor: "#2d2d2d",
-    messageBlockInboundTextColor: "#ffffff",
-    messageBlockOutboundBackgroundColor: "#3a3a3a",
-    messageBlockOutboundTextColor: "#f0f0f0",
-  }}
-/>
-```
-
-### Inline without header
-
-```tsx
-<AgentforceConversationClient
-  agentId="0Xx..."
-  inline
-  width="100%"
-  height="600px"
-  headerEnabled={false}
-  styleTokens={{
-    messageBlockBorderRadius: "12px",
-  }}
-/>
-```
-
----
-
-## Complete Host Component Example
-
-```tsx
-import { Outlet } from "react-router";
-import { AgentforceConversationClient } from "@salesforce/ui-bundle-template-feature-react-agentforce-conversation-client";
-
-export default function AgentChatHost() {
-  return (
-    <>
-      <Outlet />
-      <AgentforceConversationClient
-        agentId="0Xx..."
-        styleTokens={{
-          headerBlockBackground: "#0176d3",
-          headerBlockTextColor: "#ffffff",
-        }}
-      />
-    </>
-  );
-}
-```
-
----
-
-For complete style token reference, see `references/style-tokens.md` or `node_modules/@salesforce/agentforce-conversation-client/README.md`.