@salesforce/templates 66.5.5 → 66.6.0

package/lib/templates/project/reactb2x/_r_/skills/_k_/SKILL.md

@@ -1,148 +0,0 @@
----
-name: feature-react-agentforce-conversation-client-embedded-agent
-description: Embed an Agentforce conversation client (chat UI) into a React web application. Use when the user wants to add an employee agent, a chat client, chatbot, chat widget, chat component, conversation client, or conversational interface to their React app. Also applies when the user asks to embed or integrate any Salesforce agent — including employee agent, travel agent, HR agent, or any custom-named agent — or mentions Agentforce, Agentforce widget, Agentforce chat, or agent chat. ALWAYS use this skill instead of building a chat UI from scratch. Do NOT generate custom chat components, use third-party chat libraries, or create WebSocket/REST chat implementations. Do NOT use for non-React contexts or Lightning Web Components without React.
----
-
-# Embedded Agentforce chat (workflow)
-
-When the user wants an embedded Agentforce chat client in a React app, follow this workflow.
-
-## DO NOT build a chat UI from scratch
-
-When the user asks for a chat UI, chat widget, chatbot, conversational interface, agent embed, or anything related to an embedded agent — **always use the `AgentforceConversationClient` component** from `@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental`.
-
-**Never do any of the following:**
-
-- Build a custom chat component from scratch (no custom message bubbles, input boxes, or chat layouts)
-- Use third-party chat libraries (e.g. `react-chat-widget`, `stream-chat`, `chatscope`, or similar)
-- Create WebSocket, polling, or REST-based chat implementations
-- Generate custom HTML/CSS chat UIs
-- Write a wrapper around `embedAgentforceClient` directly — always use the provided React component
-
-If the user asks for chat functionality that goes beyond what `AgentforceConversationClient` supports (e.g. custom message rendering, message history, typing indicators), explain that the embedded Agentforce client handles all of this internally and cannot be customized beyond the supported `agentforceClientConfig` options (`renderingConfig`, `styleTokens`, `agentId`).
-
-## CRITICAL: Agent ID is required
-
-The Agentforce Conversation Client **will not work** without an `agentId`. There is no default agent — the component renders nothing and silently fails if `agentId` is missing. **Always ask the user for their agent ID before writing any code.**
-
-> **Before proceeding:** Ask the user for their Salesforce agent ID (18-character record ID starting with `0Xx`). If they do not have one, direct them to **Setup → Agents** in their Salesforce org to find or create one. Do not generate code without an `agentId`.
-
-## 1. Collect the agent ID
-
-Ask the user:
-
-- "What is your Salesforce agent ID? (You can find it in Setup → Agents → select an agent → copy the ID from the URL. It's an 18-character ID starting with `0Xx`.)"
-
-If the user does not provide one:
-
-- Explain that the conversation client **requires** an agent ID and will not function without it.
-- Direct them to **Setup → Agents** in their org.
-- Do **not** proceed to generate the embed code until an agent ID is provided.
-
-## 2. Install the package
-
-```bash
-npm install @salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental
-```
-
-This single install also brings in `@salesforce/agentforce-conversation-client` (the underlying SDK) automatically.
-
-## 3. Use the shared wrapper
-
-Use the `AgentforceConversationClient` React component. It resolves auth automatically:
-
-- **Dev (localhost)**: fetches `frontdoorUrl` from `/__lo/frontdoor`
-- **Prod (hosted in org)**: uses `salesforceOrigin` from `window.location.origin`
-
-## 4. Embed in the layout
-
-Render `<AgentforceConversationClient />` in the app layout so the chat client loads globally. Keep it alongside the existing layout (do not replace the page shell). **Always pass `agentId`.**
-
-```tsx
-import { Outlet } from "react-router";
-import { AgentforceConversationClient } from "@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental";
-
-export default function AppLayout() {
-  return (
-    <>
-      <Outlet />
-      <AgentforceConversationClient
-        agentforceClientConfig={{
-          agentId: "0Xx000000000000AAA",
-        }}
-      />
-    </>
-  );
-}
-```
-
-Replace `"0Xx000000000000AAA"` with the agent ID provided by the user.
-
-## 5. Configure rendering and theming (optional)
-
-Pass additional options via the `agentforceClientConfig` prop:
-
-| Option                             | Purpose                                                    | Required |
-| ---------------------------------- | ---------------------------------------------------------- | -------- |
-| `agentId`                          | The agent to load — **required, will not work without it** | **Yes**  |
-| `renderingConfig.mode`             | `"floating"` (default) or `"inline"`                       | No       |
-| `renderingConfig.width` / `height` | Inline dimensions (number for px, string for CSS)          | No       |
-| `styleTokens`                      | Theme colors and style overrides                           | No       |
-
-See [embed-examples.md](docs/embed-examples.md) for complete examples of each mode.
-
-## 6. Validate prerequisites
-
-Before the conversation client will work, the user must verify all of the following in their Salesforce org:
-
-1. **Agent is active:** The org must have the agent referenced by `agentId` in an **Active** state and deployed to the correct channel (**Setup → Agents**).
-2. **Trusted domains:** The org must allow `localhost:<PORT>` in **Trusted Domains for Inline Frames** (**Setup → Session Settings → Trusted Domains for Inline Frames**). Required for local development.
-3. **First-party cookies disabled:** **"Require first party use of Salesforce cookies"** must be **unchecked/disabled** in **Setup → My Domain**. If this setting is enabled, the embedded conversation client will fail to authenticate and will not load.
-
-## Quick reference: rendering modes
-
-### Floating (default rendering mode)
-
-A persistent chat widget overlay pinned to the bottom-right corner. Floating is the default rendering mode — but `agentId` is still required.
-
-```tsx
-<AgentforceConversationClient
-  agentforceClientConfig={{
-    agentId: "0Xx000000000000AAA",
-  }}
-/>
-```
-
-### Inline
-
-The chat renders within the page layout at a specific size.
-
-```tsx
-<AgentforceConversationClient
-  agentforceClientConfig={{
-    agentId: "0Xx000000000000AAA",
-    renderingConfig: { mode: "inline", width: 420, height: 600 },
-  }}
-/>
-```
-
-### Theming
-
-Use `styleTokens` to customize the chat appearance.
-
-```tsx
-<AgentforceConversationClient
-  agentforceClientConfig={{
-    agentId: "0Xx000000000000AAA",
-    styleTokens: {
-      headerBlockBackground: "#0176d3",
-      headerBlockTextColor: "#ffffff",
-      messageBlockInboundColor: "#0176d3",
-    },
-  }}
-/>
-```
-
-## Troubleshooting
-
-If the chat widget does not appear, fails to authenticate, or behaves unexpectedly, see [troubleshooting.md](docs/troubleshooting.md).

package/lib/templates/project/reactb2x/_r_/skills/_k_/docs/embed-examples.md

@@ -1,192 +0,0 @@
-# Embed examples
-
-Detailed examples for configuring the Agentforce Conversation Client. All examples use the `AgentforceConversationClient` React component; the underlying `embedAgentforceClient` API accepts the same `agentforceClientConfig` shape.
-
-> **Important:** Every example requires an `agentId`. The component will not render without one. There is no default agent. Replace `"0Xx000000000000AAA"` in every example with the user's actual agent ID.
-
----
-
-## Floating mode (default rendering mode)
-
-A floating chat widget appears in the bottom-right corner. It starts minimized and expands when the user clicks it. Floating is the default rendering mode — no `renderingConfig` is needed — but `agentId` is always required.
-
-### Minimal
-
-```tsx
-<AgentforceConversationClient
-  agentforceClientConfig={{
-    agentId: "0Xx000000000000AAA",
-  }}
-/>
-```
-
-### Explicit floating
-
-```tsx
-<AgentforceConversationClient
-  agentforceClientConfig={{
-    agentId: "0Xx000000000000AAA",
-    renderingConfig: { mode: "floating" },
-  }}
-/>
-```
-
-### Floating with theming
-
-```tsx
-<AgentforceConversationClient
-  agentforceClientConfig={{
-    agentId: "0Xx000000000000AAA",
-    renderingConfig: { mode: "floating" },
-    styleTokens: {
-      headerBlockBackground: "#032D60",
-      headerBlockTextColor: "#ffffff",
-    },
-  }}
-/>
-```
-
----
-
-## Inline mode
-
-The chat renders inside the parent container at a specific size. Use this when the chat should be part of the page layout rather than an overlay.
-
-### Fixed pixel dimensions
-
-```tsx
-<AgentforceConversationClient
-  agentforceClientConfig={{
-    agentId: "0Xx000000000000AAA",
-    renderingConfig: { mode: "inline", width: 420, height: 600 },
-  }}
-/>
-```
-
-### CSS string dimensions
-
-```tsx
-<AgentforceConversationClient
-  agentforceClientConfig={{
-    agentId: "0Xx000000000000AAA",
-    renderingConfig: { mode: "inline", width: "100%", height: "80vh" },
-  }}
-/>
-```
-
-### Inline filling a sidebar
-
-```tsx
-<div style={{ display: "flex", height: "100vh" }}>
-  <main style={{ flex: 1 }}>{/* App content */}</main>
-  <aside style={{ width: 400 }}>
-    <AgentforceConversationClient
-      agentforceClientConfig={{
-        agentId: "0Xx000000000000AAA",
-        renderingConfig: { mode: "inline", width: "100%", height: "100%" },
-      }}
-    />
-  </aside>
-</div>
-```
-
----
-
-## Theming
-
-Use `styleTokens` to customize colors. Tokens are passed directly to the Agentforce client.
-
-### Brand-colored header
-
-```tsx
-<AgentforceConversationClient
-  agentforceClientConfig={{
-    agentId: "0Xx000000000000AAA",
-    styleTokens: {
-      headerBlockBackground: "#0176d3",
-      headerBlockTextColor: "#ffffff",
-    },
-  }}
-/>
-```
-
-### Full theme example
-
-```tsx
-<AgentforceConversationClient
-  agentforceClientConfig={{
-    agentId: "0Xx000000000000AAA",
-    styleTokens: {
-      headerBlockBackground: "#0176d3",
-      headerBlockTextColor: "#ffffff",
-      messageBlockInboundColor: "#0176d3",
-    },
-  }}
-/>
-```
-
-### Dark theme example
-
-```tsx
-<AgentforceConversationClient
-  agentforceClientConfig={{
-    agentId: "0Xx000000000000AAA",
-    styleTokens: {
-      headerBlockBackground: "#1a1a2e",
-      headerBlockTextColor: "#e0e0e0",
-      messageBlockInboundColor: "#16213e",
-    },
-  }}
-/>
-```
-
----
-
-## Full layout example
-
-Shows the recommended pattern: agent ID passed directly, single render in the app layout.
-
-```tsx
-import { Outlet } from "react-router";
-import { AgentforceConversationClient } from "@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental";
-
-export default function AppLayout() {
-  return (
-    <>
-      <Outlet />
-      <AgentforceConversationClient
-        agentforceClientConfig={{
-          agentId: "0Xx000000000000AAA",
-          styleTokens: {
-            headerBlockBackground: "#0176d3",
-            headerBlockTextColor: "#ffffff",
-          },
-        }}
-      />
-    </>
-  );
-}
-```
-
----
-
-## Using the low-level `embedAgentforceClient` API
-
-The React component wraps `embedAgentforceClient`. If you need the raw API (e.g. in a non-React context), the config shape is the same — `agentId` is still required:
-
-```ts
-import { embedAgentforceClient } from "@salesforce/agentforce-conversation-client";
-
-const { loApp, chatClientComponent } = embedAgentforceClient({
-  container: "#agentforce-container",
-  salesforceOrigin: "https://myorg.my.salesforce.com",
-  agentforceClientConfig: {
-    agentId: "0Xx000000000000AAA",
-    renderingConfig: { mode: "floating" },
-    styleTokens: {
-      headerBlockBackground: "#0176d3",
-      headerBlockTextColor: "#ffffff",
-    },
-  },
-});
-```

package/lib/templates/project/reactb2x/_r_/skills/_k_/docs/troubleshooting.md

@@ -1,51 +0,0 @@
-# Troubleshooting
-
-Common issues when using the Agentforce Conversation Client.
-
----
-
-### Chat widget does not appear
-
-**Cause:** Missing or invalid `agentId`. The component will not render anything without a valid agent ID.
-
-**Solution:**
-
-1. Verify `agentId` is passed in `agentforceClientConfig` — it is required
-2. Confirm the ID is correct (18-character Salesforce record ID, starts with `0Xx`)
-3. Check that the agent exists and is **Active** in **Setup → Agents**
-
-### Chat loads but shows "agent not available"
-
-**Cause:** The agent exists but is not deployed or is inactive.
-
-**Solution:**
-
-1. In **Setup → Agents**, ensure the agent status is **Active**
-2. Verify the agent is deployed to the correct channel
-
-### Authentication error on localhost
-
-**Cause:** `localhost:<PORT>` is not in the org's trusted domains for inline frames.
-
-**Solution:**
-
-1. Go to **Setup → Session Settings → Trusted Domains for Inline Frames**
-2. Add `localhost:<PORT>` (e.g. `localhost:3000`)
-3. Restart the dev server
-
-### Chat fails to authenticate / blank iframe
-
-**Cause:** "Require first party use of Salesforce cookies" is enabled in the org's session settings. This blocks the embedded client from establishing a session.
-
-**Solution:**
-
-1. Go to **Setup → Session Settings**
-2. Find **"Require first party use of Salesforce cookies"**
-3. **Uncheck / disable** this setting
-4. Save and reload the app
-
-### Multiple chat widgets appear
-
-**Cause:** `AgentforceConversationClient` is rendered in multiple places.
-
-**Solution:** Render it once in the app layout, not on individual pages. The component uses a singleton pattern — only one instance should exist per window.

package/lib/templates/project/reactb2x/_r_/skills/feature-graphql-graphql-data-access/SKILL.md

@@ -1,155 +0,0 @@
----
-name: feature-graphql-graphql-data-access
-description: Add or modify Salesforce GraphQL data access code. Use when the user asks to fetch, query, or mutate Salesforce data, or add a GraphQL operation for an object like Account, Contact, or Opportunity.
----
-
-# GraphQL Data Access
-
-Add or modify Salesforce GraphQL data access code using `getDataSDK()` + `data.graphql?.()` and codegen tooling.
-
-## When to Use
-
-- User asks to "fetch data from Salesforce"
-- User asks to "query" or "mutate" Salesforce records
-- User wants to add a new GraphQL operation (query or mutation)
-- User asks to add data access for a Salesforce object (Account, Contact, Opportunity, etc.)
-
-## Prerequisites
-
-The base React app (`base-react-app`) ships with all GraphQL dependencies and tooling pre-configured:
-
-- `@salesforce/sdk-data` — runtime SDK for `getDataSDK` and `gql`
-- `@graphql-codegen/cli` + plugins — type generation from `.graphql` files and inline `gql` queries
-- `@graphql-eslint/eslint-plugin` — linting for `.graphql` files and `gql` template literals
-- `graphql` — shared by codegen, ESLint, and schema introspection
-
-Before using this skill, ensure:
-
-1. The `@salesforce/sdk-data` package is available (provides `getDataSDK`, `gql`, `NodeOfConnection`)
-2. A `schema.graphql` file exists at the project root. If missing, generate it:
-   ```bash
-   npm run graphql:schema
-   ```
-
-## npm Scripts
-
-The base app provides two npm scripts for GraphQL tooling:
-
-- **`npm run graphql:schema`** — Downloads the full GraphQL schema from a connected Salesforce org via introspection. Outputs `schema.graphql` to the project root.
-- **`npm run graphql:codegen`** — Generates TypeScript types from `.graphql` files and inline `gql` queries. Outputs to `src/api/graphql-operations-types.ts`.
-
-## Workflow
-
-### Step 1: Explore the Schema
-
-Before writing any query, verify the target object and its fields exist in the schema.
-
-See `docs/explore-schema.md` for detailed guidance on exploring the Salesforce GraphQL schema.
-
-Key actions:
-
-- Search `schema.graphql` for `type <ObjectName> implements Record` to find available fields
-- Search for `input <ObjectName>_Filter` for filter options
-- Search for `input <ObjectName>_OrderBy` for sorting options
-- For mutations: search for `input <ObjectName>CreateInput` or `<ObjectName>UpdateInput`
-
-### Step 2: Choose the Query Pattern
-
-**Pattern 1 — External `.graphql` file** (recommended for complex queries):
-
-- Queries with variables, fragments, or shared across files
-- Enables full codegen type generation
-- See example: `api/utils/accounts.ts` + `api/utils/query/highRevenueAccountsQuery.graphql`
-
-**Pattern 2 — Inline `gql` tag** (recommended for simple queries):
-
-- Simple queries without variables
-- Colocated with usage code
-- See example: `api/utils/user.ts`
-
-### Step 3: Write the Query
-
-For **Pattern 1**:
-
-1. Create a `.graphql` file under `src/api/utils/query/`
-2. Follow UIAPI structure: `query { uiapi { query { ObjectName(...) { edges { node { ... } } } } } }`
-3. For mutations, see `docs/generate-mutation-query.md`
-4. For read queries, see `docs/generate-read-query.md`
-
-For **Pattern 2**:
-
-1. Define query inline using the `gql` template tag
-2. Ensure the query name matches what codegen expects
-
-### Step 4: Generate Types
-
-```bash
-npm run graphql:codegen
-```
-
-This updates `src/api/graphql-operations-types.ts` with:
-
-- `<OperationName>Query` or `<OperationName>Mutation` — response type
-- `<OperationName>QueryVariables` or `<OperationName>MutationVariables` — input variables type
-
-### Step 5: Implement the Data Access Function
-
-```typescript
-// Pattern 1
-import { getDataSDK, type NodeOfConnection } from "@salesforce/sdk-data";
-import MY_QUERY from "./query/myQuery.graphql?raw";
-import type { GetMyDataQuery, GetMyDataQueryVariables } from "../graphql-operations-types";
-
-type MyNode = NodeOfConnection<GetMyDataQuery["uiapi"]["query"]["MyObject"]>;
-
-export async function getMyData(variables: GetMyDataQueryVariables): Promise<MyNode[]> {
-  const data = await getDataSDK();
-  const response = await data.graphql?.<GetMyDataQuery, GetMyDataQueryVariables>(
-    MY_QUERY,
-    variables,
-  );
-
-  if (response?.errors?.length) {
-    const errorMessages = response.errors.map((e) => e.message).join("; ");
-    throw new Error(`GraphQL Error: ${errorMessages}`);
-  }
-
-  return response?.data?.uiapi?.query?.MyObject?.edges?.map((edge) => edge?.node) || [];
-}
-```
-
-```typescript
-// Pattern 2
-import { getDataSDK, gql } from "@salesforce/sdk-data";
-import type { MySimpleQuery } from "../graphql-operations-types";
-
-const MY_QUERY = gql`
-  query MySimple {
-    uiapi { ... }
-  }
-`;
-
-export async function getSimpleData(): Promise<SomeType> {
-  const data = await getDataSDK();
-  const response = await data.graphql?.<MySimpleQuery>(MY_QUERY);
-  // check response.errors, then extract response.data
-}
-```
-
-### Step 6: Verify
-
-- [ ] Query field names match the schema exactly (case-sensitive)
-- [ ] Response type generic is provided to `data.graphql?.<T>()`
-- [ ] Optional chaining is used for nested response data
-- [ ] Pattern 1: `.graphql` file imported with `?raw` suffix
-- [ ] Pattern 2: Query uses `gql` tag (not plain string)
-- [ ] Generated types imported from `graphql-operations-types.ts`
-
-## Reference
-
-- Schema exploration: `docs/explore-schema.md`
-- Read query generation: `docs/generate-read-query.md`
-- Mutation query generation: `docs/generate-mutation-query.md`
-- Shared GraphQL schema types: `docs/shared-schema.graphqls`
-- Schema download: `npm run graphql:schema` (in the base app)
-- Type generation: `npm run graphql:codegen` (in the base app)