@salesforce/templates 66.3.2 → 66.4.0

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",

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

@@ -0,0 +1,51 @@
+# 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/reactb2e/_r_/skills/webapp-csp-trusted-sites/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: webapp-csp-trusted-sites
+description: Creates Salesforce CSP Trusted Site metadata when adding external domains. Use when the user adds an external API, CDN, image host, font provider, map tile server, or any third-party URL that the web application needs to load resources from — or when a browser console shows a CSP violation error.
+---
+
+# CSP Trusted Sites
+
+## When to Use
+
+Use this skill whenever the application references a new external domain that is not already registered as a CSP Trusted Site. This includes:
+
+- Adding images from a new CDN (Unsplash, Pexels, Cloudinary, etc.)
+- Loading fonts from an external provider (Google Fonts, Adobe Fonts)
+- Calling a third-party API (Open-Meteo, Nominatim, Mapbox, etc.)
+- Loading map tiles from a tile server (OpenStreetMap, Mapbox)
+- Embedding iframes from external services (YouTube, Vimeo)
+- Loading external stylesheets or scripts
+
+Salesforce enforces Content Security Policy (CSP) headers on all web applications. Any external domain not registered as a CSP Trusted Site will be blocked by the browser, causing images to not load, API calls to fail, or fonts to be missing.
+
+**Reference:** [Salesforce CspTrustedSite Object Reference](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_csptrustedsite.htm)
+
+---
+
+## Step 1 — Identify external domains
+
+Scan the code for any URLs pointing to external domains. Common patterns:
+
+- `fetch("https://api.example.com/...")` — API calls
+- `<img src="https://images.example.com/..." />` — images
+- `<link href="https://fonts.example.com/..." />` — stylesheets
+- `url="https://tiles.example.com/{z}/{x}/{y}.png"` — map tiles
+- `@import url("https://cdn.example.com/...")` — CSS imports
+
+Extract the **origin** (scheme + host) from each URL. For example:
+- `https://api.open-meteo.com/v1/forecast?lat=...` → `https://api.open-meteo.com`
+- `https://images.unsplash.com/photo-123?w=800` → `https://images.unsplash.com`
+
+---
+
+## Step 2 — Check existing CSP Trusted Sites
+
+Before creating a new file, check if the domain already has a CSP Trusted Site:
+
+```bash
+ls force-app/main/default/cspTrustedSites/
+```
+
+If the domain is already registered, no action is needed.
+
+---
+
+## Step 3 — Determine the CSP directive(s)
+
+Map the resource type to the correct CSP `isApplicableTo*Src` fields. Read `implementation/metadata-format.md` for the full reference.
+
+Quick reference:
+
+| Resource type | CSP directive field(s) to set `true` |
+|--------------|--------------------------------------|
+| Images (img, background-image) | `isApplicableToImgSrc` |
+| API calls (fetch, XMLHttpRequest) | `isApplicableToConnectSrc` |
+| Fonts (.woff, .woff2, .ttf) | `isApplicableToFontSrc` |
+| Stylesheets (CSS) | `isApplicableToStyleSrc` |
+| Video / audio | `isApplicableToMediaSrc` |
+| Iframes | `isApplicableToFrameSrc` |
+
+**Always also set `isApplicableToConnectSrc` to `true`** — most resources also require connect-src for preflight/redirect handling.
+
+---
+
+## Step 4 — Create the metadata file
+
+Read `implementation/metadata-format.md` and follow the instructions to create the `.cspTrustedSite-meta.xml` file.
+
+---
+
+## Step 5 — Verify
+
+1. Confirm the file is valid XML and matches the expected schema.
+2. Confirm the file is placed in `force-app/main/default/cspTrustedSites/`.
+3. Confirm only the necessary `isApplicableTo*Src` fields are set to `true`.
+4. Run from the web app directory:
+
+```bash
+cd force-app/main/default/webapplications/<appName> && npm run lint && npm run build
+```
+
+- **Lint:** MUST result in 0 errors.
+- **Build:** MUST succeed.