@salesforce/templates 66.3.3 → 66.4.1

package/lib/templates/project/reactb2e/_p_/_m_/_w_/_a_/src/_f_/_gs_/utils/apiUtils.ts

@@ -0,0 +1,59 @@
+/**
+ * API Utilities
+ *
+ * Generic utility functions for API requests, validation, and URL handling.
+ */
+
+import type { ZodSchema } from "zod";
+
+export interface FetchAndValidateOptions<T> {
+	schema: ZodSchema<T>;
+	errorContext: string;
+	extractData?: (data: unknown) => unknown;
+}
+
+export async function fetchAndValidate<T>(
+	fetchFn: () => Promise<Response>,
+	options: FetchAndValidateOptions<T>,
+): Promise<T> {
+	const { schema, errorContext, extractData } = options;
+
+	try {
+		const response = await fetchFn();
+
+		if (!response.ok) {
+			throw new Error(`Failed to fetch ${errorContext}: ${response.status} ${response.statusText}`);
+		}
+
+		const data = await response.json();
+		const dataToValidate = extractData ? extractData(data) : data;
+		const validationResult = schema.safeParse(dataToValidate);
+
+		if (!validationResult.success) {
+			throw new Error(`Invalid ${errorContext} response format: ${validationResult.error.message}`);
+		}
+
+		return validationResult.data;
+	} catch (error) {
+		if (error instanceof Error && error.name === "ZodError") {
+			throw new Error(`Invalid ${errorContext} response format: ${error.message}`);
+		}
+
+		if (
+			error instanceof Error &&
+			(error.message.includes("Failed to fetch") || error.message.includes("Invalid"))
+		) {
+			throw error;
+		}
+
+		throw new Error(
+			`Error fetching ${errorContext}: ${
+				error instanceof Error ? error.message : (error?.toString() ?? "Unknown error")
+			}`,
+		);
+	}
+}
+
+export function safeEncodePath(segment: string): string {
+	return encodeURIComponent(segment);
+}

package/lib/templates/project/reactb2e/_p_/_m_/_w_/_a_/src/_f_/_gs_/utils/graphQLObjectInfoAdapter.ts

@@ -0,0 +1,77 @@
+/**
+ * GraphQL objectInfos → REST-compatible object info and picklist.
+ *
+ * graphQLObjectInfoToObjectInfoResult / graphQLObjectInfosToBatchResponse: used by objectInfoService
+ * after getObjectInfosGraphQL. extractPicklistValuesFromGraphQLObjectInfo: used for getPicklistValues.
+ * Normalizes casing and adds synthetic compound fields (e.g. BillingAddress) for layout/dataType.
+ *
+ * @module utils/graphQLObjectInfoAdapter
+ */
+
+import type {
+	ObjectInfoBatchResponse,
+	GetObjectInfosQueryObjectInfos,
+	GetPicklistValuesQueryObjectInfo,
+	GetPicklistValuesQueryField,
+	GetObjectInfosQueryObjectInfo,
+	ObjectInfoResult,
+	PicklistValue as GraphQLPicklistValue,
+} from "../types/objectInfo/objectInfo";
+import type { PicklistValue } from "../types/filters/picklist";
+
+export function graphQLObjectInfoToObjectInfoResult(
+	objectInfo: GetObjectInfosQueryObjectInfo,
+): ObjectInfoResult {
+	const { fields, ...rest } = objectInfo;
+	const fieldsRecord = Object.fromEntries((fields ?? []).map((field) => [field?.ApiName, field]));
+	return {
+		...rest,
+		fields: fieldsRecord,
+	};
+}
+
+/** Convert GraphQL objectInfos array to ObjectInfoBatchResponse (REST shape). */
+export function graphQLObjectInfosToBatchResponse(
+	objectInfos: GetObjectInfosQueryObjectInfos,
+	_requestedApiNames: string[],
+): ObjectInfoBatchResponse {
+	const results = objectInfos.map((objectInfo) => ({
+		result: graphQLObjectInfoToObjectInfoResult(objectInfo!),
+		statusCode: 200,
+	}));
+	return { results };
+}
+
+/**
+ * Extract picklist values for a field from a GraphQL ObjectInfo node (raw response).
+ * Uses picklistValuesByRecordTypeIDs; prefers the given recordTypeId or first available.
+ */
+export function extractPicklistValuesFromGraphQLObjectInfo(
+	objectInfo: NonNullable<GetPicklistValuesQueryObjectInfo>,
+	fieldName: string,
+	recordTypeId?: string,
+): PicklistValue[] {
+	const fields = objectInfo.fields;
+	if (fields == null) return [];
+	const fieldMap: Record<string, GetPicklistValuesQueryField> = Object.fromEntries(
+		fields.map((field) => {
+			return [field?.ApiName, field];
+		}),
+	);
+	const field = fieldMap[fieldName];
+	if (!field) return [];
+	const picklistData =
+		"picklistValuesByRecordTypeIDs" in field ? field.picklistValuesByRecordTypeIDs : undefined;
+	if (!picklistData) return [];
+	const rtId = recordTypeId ?? "012000000000000AAA";
+	const byRecordType = picklistData.find((p) => p!.recordTypeID === rtId) ?? picklistData[0];
+	return mapPicklistValues(byRecordType?.picklistValues ?? []);
+}
+
+function mapPicklistValues(values: GraphQLPicklistValue[]): PicklistValue[] {
+	return values.map((item) => ({
+		...item,
+		value: item.value ?? "",
+		label: item.label ?? "",
+	}));
+}

package/lib/templates/project/{reactb2x/force-app/main/default/webapplications/appreacttemplateb2x/src/features/global-search → reactb2e/_p_/_m_/_w_/_a_/src/_f_/_gs_}/utils/recordUtils.ts

@@ -49,13 +49,13 @@ const getFetchableFieldsFromLayoutItem = function (
 
 		// add field: fieldType
 		const fieldMetadata = metadata.fields[comp.apiName];
-		fields[comp.apiName] = fieldMetadata ? fieldMetadata.dataType : "";
+		fields[comp.apiName] = fieldMetadata?.dataType ?? "";
 
 		// add relatedField if one exists (Id field -> add relationship name so we request Owner.Name)
 		if (comp.apiName in metadata.fields) {
 			const relationshipName = fieldMetadata?.relationshipName;
 			if (relationshipName) {
-				fields[relationshipName] = fieldMetadata.dataType;
+				fields[relationshipName] = fieldMetadata.dataType ?? "";
 
 				relationFieldMap[comp.apiName] = relationshipName;
 			}
@@ -65,7 +65,7 @@ const getFetchableFieldsFromLayoutItem = function (
 			const idField = findIdFieldForRelationship(metadata, comp.apiName);
 			if (idField) {
 				const idMeta = metadata.fields[idField];
-				fields[idField] = idMeta ? idMeta.dataType : "";
+				fields[idField] = idMeta?.dataType ?? "";
 				relationFieldMap[idField] = comp.apiName;
 			}
 		}
@@ -137,7 +137,7 @@ export const calculateFieldsToFetch = function (
 	const fields = getFetchableFieldsFromLayout(metadata, layout, relationFieldMap);
 	let fieldsToFetch = Object.keys(fields);
 	if (shouldPrefixedWithEntityName) {
-		fieldsToFetch = fieldsToFetch.map((field) => `${metadata.apiName}.${field}`);
+		fieldsToFetch = fieldsToFetch.map((field) => `${metadata.ApiName}.${field}`);
 	}
 	// populate field types for o11y logging
 	const fieldTypes = Object.values(fields).filter((fieldType) => fieldType !== "");

package/lib/templates/project/reactb2e/_p_/_m_/_w_/_a_/src/index.ts

@@ -0,0 +1,120 @@
+/**
+ * Public API for the Global Search feature package.
+ *
+ * Design goals:
+ * - Export **API services, hooks, types, schemas, and utilities** that customers can import from node_modules.
+ * - Do **not** export UI components or feature constants (customers build their own UI).
+ *
+ * Source implementation lives under `src/features/global-search/**`.
+ */
+
+// ---------------------------------------------------------------------------
+// API layer
+// ---------------------------------------------------------------------------
+
+export { objectInfoService } from "./features/global-search/api/objectInfoService";
+export {
+	objectDetailService,
+	extractFieldsFromLayout,
+} from "./features/global-search/api/objectDetailService";
+export type { RecordDetailResult } from "./features/global-search/api/objectDetailService";
+
+export {
+	getRecordsGraphQL,
+	getRecordByIdGraphQL,
+	buildGetRecordsQuery,
+	buildWhereFromCriteria,
+	buildOrderByFromSort,
+} from "./features/global-search/api/recordListGraphQLService";
+export type {
+	RecordListGraphQLResult,
+	RecordListGraphQLVariables,
+	RecordListGraphQLOptions,
+	GraphQLRecordNode,
+} from "./features/global-search/api/recordListGraphQLService";
+
+// ---------------------------------------------------------------------------
+// Hooks
+// ---------------------------------------------------------------------------
+
+export { useObjectInfoBatch } from "./features/global-search/hooks/useObjectInfoBatch";
+export {
+	useObjectListMetadata,
+	useObjectColumns,
+	useObjectFilters,
+} from "./features/global-search/hooks/useObjectSearchData";
+export { useRecordListGraphQL } from "./features/global-search/hooks/useRecordListGraphQL";
+export { useRecordDetailLayout } from "./features/global-search/hooks/useRecordDetailLayout";
+
+export type { ObjectListMetadata } from "./features/global-search/hooks/useObjectSearchData";
+
+export type {
+	UseRecordListGraphQLOptions,
+	UseRecordListGraphQLReturn,
+} from "./features/global-search/hooks/useRecordListGraphQL";
+
+export type {
+	UseRecordDetailLayoutParams,
+	UseRecordDetailLayoutReturn,
+} from "./features/global-search/hooks/useRecordDetailLayout";
+
+// ---------------------------------------------------------------------------
+// Types + Zod schemas (runtime validation)
+// ---------------------------------------------------------------------------
+
+export {
+	ColumnArraySchema,
+	SearchResultRecordArraySchema,
+	KeywordSearchResultSchema,
+	SearchResultsResponseSchema,
+} from "./features/global-search/types/search/searchResults";
+export type {
+	Column,
+	SearchResultRecord,
+	KeywordSearchResult,
+	SearchResultsResponse,
+} from "./features/global-search/types/search/searchResults";
+
+export {
+	FilterArraySchema,
+	FilterCriteriaArraySchema,
+	FILTER_OPERATORS,
+} from "./features/global-search/types/filters/filters";
+export type {
+	Filter,
+	FilterCriteria,
+	FilterOperator,
+	FiltersResponse,
+} from "./features/global-search/types/filters/filters";
+
+export type { PicklistValue } from "./features/global-search/types/filters/picklist";
+
+export type {
+	ObjectInfoBatchResponse,
+	ObjectInfoResult,
+} from "./features/global-search/types/objectInfo/objectInfo";
+
+export { LayoutResponseSchema } from "./features/global-search/types/recordDetail/recordDetail";
+export type { LayoutResponse } from "./features/global-search/types/recordDetail/recordDetail";
+
+// ---------------------------------------------------------------------------
+// Utilities
+// ---------------------------------------------------------------------------
+
+export { fetchAndValidate, safeEncodePath } from "./features/global-search/utils/apiUtils";
+export { debounce } from "./features/global-search/utils/debounce";
+export { createFiltersKey } from "./features/global-search/utils/cacheUtils";
+export {
+	calculateFieldsToFetch,
+	getSafeKey,
+	isValidSalesforceId,
+} from "./features/global-search/utils/recordUtils";
+export { parseFilterValue } from "./features/global-search/utils/filterUtils";
+export { sanitizeFilterValue } from "./features/global-search/utils/sanitizationUtils";
+export {
+	getGraphQLNodeValue,
+	getDisplayValueForDetailFieldFromNode,
+	getDisplayValueForLayoutItemFromNode,
+	getGraphQLRecordDisplayName,
+} from "./features/global-search/utils/graphQLNodeFieldUtils";
+export { graphQLNodeToSearchResultRecordData } from "./features/global-search/utils/graphQLRecordAdapter";

package/lib/templates/project/{reactb2x/force-app/main/default/webapplications/appreacttemplateb2x → reactb2e/_p_/_m_/_w_/_a_}/webapplication.json

@@ -2,6 +2,6 @@
   "outputDir": "dist",
   "routing": {
     "trailingSlash": "never",
-    "fallback": "/index.html"
+    "fallback": "index.html"
   }
 }

package/lib/templates/project/reactb2e/_r_/features/feature-react-agentforce-conversation-client-embedded-agent-rule.md

@@ -0,0 +1,18 @@
+---
+paths:
+  - "**/*.tsx"
+  - "**/components/**/*.ts"
+---
+
+# Agentforce Conversation Client (standards)
+
+## DO NOT build a chat UI from scratch
+
+When the user asks for a chat UI, chat widget, chatbot, agent, or conversational interface — **always use the existing `AgentforceConversationClient` component** from `@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental`. Never generate a custom chat implementation, third-party chat library, WebSocket/REST chat, or direct calls to `embedAgentforceClient`.
+
+## Hard constraints
+
+- **`agentId` is required.** The component will not work without it. Always ask the user for their agent ID before generating code. Do not proceed without one.
+- **Use the React wrapper only.** Import `AgentforceConversationClient` from the package. Never call `embedAgentforceClient` directly.
+- **One instance per window.** Render in the app layout alongside `<Outlet />`, not on individual pages. The component is a singleton.
+- **No auth hard-coding.** The component resolves `salesforceOrigin` and `frontdoorUrl` automatically.

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

@@ -0,0 +1,148 @@
+---
+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/.a4drules/skills/feature-react-agentforce-conversation-client-embedded-agent → reactb2e/_r_/skills/_k_}/docs/embed-examples.md

@@ -2,16 +2,22 @@
 
 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)
+## 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. This is the default — no `renderingConfig` is required.
+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 (no config)
+### Minimal
 
 ```tsx
-<AgentforceConversationClient />
+<AgentforceConversationClient
+  agentforceClientConfig={{
+    agentId: "0Xx000000000000AAA",
+  }}
+/>
 ```
 
 ### Explicit floating
@@ -19,18 +25,19 @@ A floating chat widget appears in the bottom-right corner. It starts minimized a
 ```tsx
 <AgentforceConversationClient
   agentforceClientConfig={{
+    agentId: "0Xx000000000000AAA",
     renderingConfig: { mode: "floating" },
   }}
 />
 ```
 
-### Floating with a specific agent and theme
+### Floating with theming
 
 ```tsx
 <AgentforceConversationClient
   agentforceClientConfig={{
+    agentId: "0Xx000000000000AAA",
     renderingConfig: { mode: "floating" },
-    agentId: "0Xx000000000000",
     styleTokens: {
       headerBlockBackground: "#032D60",
       headerBlockTextColor: "#ffffff",
@@ -50,6 +57,7 @@ The chat renders inside the parent container at a specific size. Use this when t
 ```tsx
 <AgentforceConversationClient
   agentforceClientConfig={{
+    agentId: "0Xx000000000000AAA",
     renderingConfig: { mode: "inline", width: 420, height: 600 },
   }}
 />
@@ -60,6 +68,7 @@ The chat renders inside the parent container at a specific size. Use this when t
 ```tsx
 <AgentforceConversationClient
   agentforceClientConfig={{
+    agentId: "0Xx000000000000AAA",
     renderingConfig: { mode: "inline", width: "100%", height: "80vh" },
   }}
 />
@@ -73,6 +82,7 @@ The chat renders inside the parent container at a specific size. Use this when t
   <aside style={{ width: 400 }}>
     <AgentforceConversationClient
       agentforceClientConfig={{
+        agentId: "0Xx000000000000AAA",
         renderingConfig: { mode: "inline", width: "100%", height: "100%" },
       }}
     />
@@ -91,6 +101,7 @@ Use `styleTokens` to customize colors. Tokens are passed directly to the Agentfo
 ```tsx
 <AgentforceConversationClient
   agentforceClientConfig={{
+    agentId: "0Xx000000000000AAA",
     styleTokens: {
       headerBlockBackground: "#0176d3",
       headerBlockTextColor: "#ffffff",
@@ -104,6 +115,7 @@ Use `styleTokens` to customize colors. Tokens are passed directly to the Agentfo
 ```tsx
 <AgentforceConversationClient
   agentforceClientConfig={{
+    agentId: "0Xx000000000000AAA",
     styleTokens: {
       headerBlockBackground: "#0176d3",
       headerBlockTextColor: "#ffffff",
@@ -118,6 +130,7 @@ Use `styleTokens` to customize colors. Tokens are passed directly to the Agentfo
 ```tsx
 <AgentforceConversationClient
   agentforceClientConfig={{
+    agentId: "0Xx000000000000AAA",
     styleTokens: {
       headerBlockBackground: "#1a1a2e",
       headerBlockTextColor: "#e0e0e0",
@@ -129,40 +142,37 @@ Use `styleTokens` to customize colors. Tokens are passed directly to the Agentfo
 
 ---
 
-## Agent selection
-
-Use `agentId` to load a specific agent from the org. If omitted, the org's default employee agent is used.
-
-### Specific agent by ID
-
-```tsx
-<AgentforceConversationClient
-  agentforceClientConfig={{
-    agentId: "0Xx000000000000",
-  }}
-/>
-```
+## Full layout example
 
-### Agent with inline mode and theming
+Shows the recommended pattern: agent ID passed directly, single render in the app layout.
 
 ```tsx
-<AgentforceConversationClient
-  agentforceClientConfig={{
-    agentId: "0Xx000000000000",
-    renderingConfig: { mode: "inline", width: 400, height: 700 },
-    styleTokens: {
-      headerBlockBackground: "#0176d3",
-      headerBlockTextColor: "#ffffff",
-    },
-  }}
-/>
+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:
+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";
@@ -171,7 +181,7 @@ const { loApp, chatClientComponent } = embedAgentforceClient({
   container: "#agentforce-container",
   salesforceOrigin: "https://myorg.my.salesforce.com",
   agentforceClientConfig: {
-    agentId: "0Xx000000000000",
+    agentId: "0Xx000000000000AAA",
     renderingConfig: { mode: "floating" },
     styleTokens: {
       headerBlockBackground: "#0176d3",