@salesforce/afv-skills 1.5.1 → 1.5.2

package/skills/generating-ui-bundle-metadata/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: generating-ui-bundle-metadata
+description: "Scaffold new Salesforce UI bundles and configure their metadata — sf ui-bundle generate, UIBundle bundles (meta XML, ui-bundle.json with routing/headers/outputDir), and CSP Trusted Sites for external domains. Use whenever creating a new UI bundle, setting up UI bundle metadata structure, configuring routing or headers, setting outputDir, adding external domains that need CSP registration, or editing bundle configuration. Triggers on: create UI bundle, create ui-bundle, new app, sf ui-bundle generate, metadata, ui-bundle.json, CSP, trusted site, bundle configuration, meta XML, routing config, external domain, headers config, outputDir."
+---
+
+# UI Bundle Metadata
+
+## Scaffolding a New UI Bundle
+
+Use `sf ui-bundle generate` to create new apps — not create-react-app, Vite, or other generic scaffolds.
+
+**UI bundle name (`-n`):** Alphanumerical only — no spaces, hyphens, underscores, or special characters. Example: `CoffeeBoutique` (not `Coffee Boutique`).
+
+After generation:
+1. Replace all default boilerplate — "React App", "Vite + React", default `<title>`, placeholder text
+2. Populate the home page with real content (landing section, banners, hero, navigation)
+3. Update navigation and placeholders (see the `building-ui-bundle-frontend` skill)
+
+Always install dependencies before running any scripts in the UI bundle directory.
+
+---
+
+## UIBundle Bundle
+
+A UIBundle bundle lives under `uiBundles/<AppName>/` and must contain:
+
+- `<AppName>.uibundle-meta.xml` — filename must exactly match the folder name
+- A build output directory (default: `dist/`) with at least one file
+
+### Meta XML
+
+Required fields: `masterLabel`, `version` (max 20 chars), `isActive` (boolean).
+Optional: `description` (max 255 chars).
+
+### ui-bundle.json
+
+Optional file. Allowed top-level keys: `outputDir`, `routing`, `headers`.
+
+**Constraints:**
+- Valid UTF-8 JSON, max 100 KB
+- Root must be a non-empty object (never `{}`, arrays, or primitives)
+
+**Path safety** (applies to `outputDir` and `routing.fallback`): Reject backslashes, leading `/` or `\`, `..` segments, null/control characters, globs (`*`, `?`, `**`), and `%`. All resolved paths must stay within the bundle.
+
+#### outputDir
+Non-empty string referencing a subdirectory (not `.` or `./`). Directory must exist and contain at least one file.
+
+#### routing
+If present, must be a non-empty object. Allowed keys: `rewrites`, `redirects`, `fallback`, `trailingSlash`, `fileBasedRouting`.
+
+- **trailingSlash**: `"always"`, `"never"`, or `"auto"`
+- **fileBasedRouting**: boolean
+- **fallback**: non-empty string satisfying path safety; target file must exist
+- **rewrites**: non-empty array of `{ route?, rewrite }` objects — e.g., `{ "route": "/app/:path*", "rewrite": "/index.html" }`
+- **redirects**: non-empty array of `{ route?, redirect, statusCode? }` objects — statusCode must be 301, 302, 307, or 308
+
+#### headers
+Non-empty array of `{ source, headers: [{ key, value }] }` objects.
+
+**Example:**
+```json
+{
+  "routing": {
+    "rewrites": [{ "route": "/app/:path*", "rewrite": "/index.html" }],
+    "trailingSlash": "never"
+  },
+  "headers": [
+    {
+      "source": "/assets/**",
+      "headers": [{ "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }]
+    }
+  ]
+}
+```
+
+**Never suggest:** `{}` as root, empty `"routing": {}`, empty arrays, `[{}]`, `"outputDir": "."`, `"outputDir": "./"`.
+
+---
+
+## CSP Trusted Sites
+
+Salesforce enforces Content Security Policy headers. Any external domain not registered as a CSP Trusted Site will be blocked (images won't load, API calls fail, fonts missing).
+
+### When to Create
+
+Whenever the app references a new external domain: CDN images, external fonts, third-party APIs, map tiles, iframes, external stylesheets.
+
+### Steps
+
+1. **Identify external domains** — extract the origin (scheme + host) from each external URL in the code
+2. **Check existing registrations** — look in `force-app/main/default/cspTrustedSites/`
+3. **Map resource type to CSP directive:**
+
+| Resource Type | Directive Field |
+|--------------|----------------|
+| Images | `isApplicableToImgSrc` |
+| API calls (fetch, XHR) | `isApplicableToConnectSrc` |
+| Fonts | `isApplicableToFontSrc` |
+| Stylesheets | `isApplicableToStyleSrc` |
+| Video / audio | `isApplicableToMediaSrc` |
+| Iframes | `isApplicableToFrameSrc` |
+
+Always also set `isApplicableToConnectSrc` to `true` for preflight/redirect handling.
+
+4. **Create the metadata file** — follow `implementation/csp-metadata-format.md` for the `.cspTrustedSite-meta.xml` format. Place in `force-app/main/default/cspTrustedSites/`.
+

package/skills/{managing-webapp-agentforce-conversation-client → implementing-ui-bundle-agentforce-conversation-client}/SKILL.md

@@ -1,10 +1,10 @@
 ---
-name: managing-webapp-agentforce-conversation-client
+name: implementing-ui-bundle-agentforce-conversation-client
 description: "Adds or modifies AgentforceConversationClient in React apps (.tsx or .jsx files). Use when user says \"add chat widget\", \"embed agentforce\", \"add agent\", \"add chatbot\", \"integrate conversational AI\", or asks to change colors, dimensions, styling, or configure agentId, width, height, inline mode, or styleTokens for travel agent, HR agent, employee agent, or any Salesforce agent chat."
 metadata:
   author: ACC Components
   version: 1.0.0
-  package: "@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental"
+  package: "@salesforce/ui-bundle-template-feature-react-agentforce-conversation-client"
   sdk-package: "@salesforce/agentforce-conversation-client"
   last-updated: 2025-03-18
 ---
@@ -58,13 +58,13 @@ Skip this step if:
 Use this import path by default in app code:
 
 ```tsx
-import { AgentforceConversationClient } from "@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental";
+import { AgentforceConversationClient } from "@salesforce/ui-bundle-template-feature-react-agentforce-conversation-client";
 ```
 
 If the package is not installed, install it:
 
 ```bash
-npm install @salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental
+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.
@@ -79,7 +79,7 @@ Add to the target React component file using the canonical package import:
 
 ```tsx
 import { Outlet } from "react-router";
-import { AgentforceConversationClient } from "@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental";
+import { AgentforceConversationClient } from "@salesforce/ui-bundle-template-feature-react-agentforce-conversation-client";
 
 export default function AgentChatHost() {
   return (

package/skills/{managing-webapp-agentforce-conversation-client → implementing-ui-bundle-agentforce-conversation-client}/references/constraints.md

@@ -8,7 +8,7 @@ This document lists all invalid approaches and patterns to avoid when working wi
 
 - ✅ **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/webapp-template-feature-react-agentforce-conversation-client-experimental/src/`
+  - `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.`
@@ -127,7 +127,7 @@ import "./agent-styles.css";
 
 ### ❌ Wrong - Editing implementation file
 
-Reading or editing: `node_modules/@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental/src/AgentforceConversationClient.tsx`
+Reading or editing: `node_modules/@salesforce/ui-bundle-template-feature-react-agentforce-conversation-client/src/AgentforceConversationClient.tsx`
 
 ### ✅ Correct - Editing usage file
 

package/skills/{managing-webapp-agentforce-conversation-client → implementing-ui-bundle-agentforce-conversation-client}/references/examples.md

@@ -109,7 +109,7 @@ export default function SupportPage() {
 
 ```tsx
 import { Outlet } from "react-router";
-import { AgentforceConversationClient } from "@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental";
+import { AgentforceConversationClient } from "@salesforce/ui-bundle-template-feature-react-agentforce-conversation-client";
 
 export default function AgentChatHost() {
   return (

package/skills/{implementing-webapp-file-upload → implementing-ui-bundle-file-upload}/SKILL.md

@@ -1,11 +1,11 @@
 ---
-name: implementing-webapp-file-upload
-description: "Add file upload functionality to React webapps with progress tracking and Salesforce ContentVersion integration. Use when the user wants to upload files, attach documents, handle file input, create file dropzones, track upload progress, or link files to Salesforce records. This feature provides programmatic APIs ONLY — no components or hooks are exported. Build your own custom UI using the upload() API. ALWAYS use this feature instead of building file upload from scratch with FormData or XHR."
+name: implementing-ui-bundle-file-upload
+description: "Add file upload functionality to React UI bundles with progress tracking and Salesforce ContentVersion integration. Use when the user wants to upload files, attach documents, handle file input, create file dropzones, track upload progress, or link files to Salesforce records. This feature provides programmatic APIs ONLY — no components or hooks are exported. Build your own custom UI using the upload() API. ALWAYS use this feature instead of building file upload from scratch with FormData or XHR."
 ---
 
 # File Upload API (workflow)
 
-When the user wants file upload functionality in a React webapp, follow this workflow. This feature provides **APIs only** — you must build the UI components yourself using the provided APIs.
+When the user wants file upload functionality in a React UI bundle, follow this workflow. This feature provides **APIs only** — you must build the UI components yourself using the provided APIs.
 
 ## CRITICAL: This is an API-only package
 
@@ -26,12 +26,12 @@ The source code contains reference components for demonstration, but they are **
 ## 1. Install the package
 
 ```bash
-npm install @salesforce/webapp-template-feature-react-file-upload-experimental
+npm install @salesforce/ui-bundle-template-feature-react-file-upload
 ```
 
 Dependencies are automatically installed:
 
-- `@salesforce/webapp-experimental` (API client)
+- `@salesforce/ui-bundle` (API client)
 - `@salesforce/sdk-data` (data SDK)
 
 ## 2. Understand the three upload patterns
@@ -47,7 +47,7 @@ Upload files to Salesforce and get back `contentBodyId` for each file. No Conten
 - Deferred record linking scenarios
 
 ```tsx
-import { upload } from "@salesforce/webapp-template-feature-react-file-upload-experimental";
+import { upload } from "@salesforce/ui-bundle-template-feature-react-file-upload";
 
 const results = await upload({
   files: [file1, file2],
@@ -71,7 +71,7 @@ Upload files and immediately link them to an existing Salesforce record by creat
 - Direct upload-and-attach scenarios
 
 ```tsx
-import { upload } from "@salesforce/webapp-template-feature-react-file-upload-experimental";
+import { upload } from "@salesforce/ui-bundle-template-feature-react-file-upload";
 
 const results = await upload({
   files: [file1, file2],
@@ -99,7 +99,7 @@ Upload files without a record, then link them after the record is created.
 import {
   upload,
   createContentVersion,
-} from "@salesforce/webapp-template-feature-react-file-upload-experimental";
+} from "@salesforce/ui-bundle-template-feature-react-file-upload";
 
 // Step 1: Upload files (no recordId)
 const uploadResults = await upload({
@@ -128,7 +128,7 @@ The package provides the backend — you build the frontend. Here's a minimal ex
 import {
   upload,
   type FileUploadProgress,
-} from "@salesforce/webapp-template-feature-react-file-upload-experimental";
+} from "@salesforce/ui-bundle-template-feature-react-file-upload";
 import { useState } from "react";
 
 function CustomFileUpload({ recordId }: { recordId?: string }) {
@@ -212,7 +212,7 @@ If the user wants to upload files to their own profile or personal library:
 import {
   upload,
   getCurrentUserId,
-} from "@salesforce/webapp-template-feature-react-file-upload-experimental";
+} from "@salesforce/ui-bundle-template-feature-react-file-upload";
 
 const userId = await getCurrentUserId();
 await upload({ files, recordId: userId });
@@ -366,7 +366,7 @@ The package includes a reference implementation in `src/features/fileupload/` wi
 
 **Upload fails with CORS error:**
 
-- Ensure the webapp is properly deployed to Salesforce or running on `localhost`
+- Ensure the UI bundle is properly deployed to Salesforce or running on `localhost`
 - Check that the org allows the origin in CORS settings
 
 **No progress updates:**

package/skills/searching-media/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: searching-media
-description: "Searches for and retrieves existing visual media (images, logos, icons, photos, graphics, banners, thumbnails, hero images, backgrounds) from any source. Use this skill ANY TIME a user request involves finding, searching, getting, fetching, retrieving, grabbing, looking up, or locating media. Takes PRIORITY and activates FIRST when ANY media search/retrieval is mentioned, regardless of what else happens with the media afterward. Triggers for requests like \"search for logo\", \"find hero image\", \"get company logo\", \"locate icons\", \"fetch background image\", \"retrieve product photos\". Handles the search and source selection workflow. Does not apply when the request is to generate NEW images with AI, design custom graphics from scratch, or edit existing images."
+description: "Searches for and retrieves existing visual media (images, logos, icons, photos, graphics, banners, thumbnails, hero images, backgrounds) from sources such as Salesforce CMS, Data 360 or any other source. Use this skill ANY TIME a user request involves finding, searching, getting, fetching, retrieving, grabbing, looking up, or locating media. Takes PRIORITY and activates FIRST when ANY media search/retrieval is mentioned, regardless of what else happens with the media afterward. Triggers for requests like \"search for logo\", \"find hero image\", \"get company logo\", \"locate icons\", \"fetch background image\", \"retrieve product photos\". Handles the search and source selection workflow. Does not apply when the request is about brand search, to generate NEW images with AI, design custom graphics from scratch, or edit existing images."
 compatibility: "Requires search_media_cms_channels and/or search_electronic_media MCP tools"
 metadata:
   version: "1.0"

package/skills/{using-webapp-salesforce-data → using-ui-bundle-salesforce-data}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: using-webapp-salesforce-data
-description: "Salesforce data access for reading, writing, and querying records via REST, GraphQL, Apex, or Platform SDK. Use when the user wants to fetch, search, filter, sort, display, create, update, delete, or attach files to Salesforce records (standard objects like Accounts, Contacts, Opportunities, Cases, Quotes, or any custom object) in a web app or UI component (React, Angular, Vue, etc.); call Chatter, Connect, or Apex REST APIs; or invoke AuraEnabled Apex methods from an external app. Does not apply to authentication/OAuth setup, schema changes (adding fields, relationships), Bulk/Tooling/Metadata API usage, declarative automation (Flows, Process Builder), general LWC/Apex coding guidance without a specific data operation, or Salesforce admin/configuration tasks."
+name: using-ui-bundle-salesforce-data
+description: "Salesforce data access for reading, writing, and querying records via REST, GraphQL, Apex, or Platform SDK. Use when the user wants to fetch, search, filter, sort, display, create, update, delete, or attach files to Salesforce records (standard objects like Accounts, Contacts, Opportunities, Cases, Quotes, or any custom object) in a UI bundle or UI component (React, Angular, Vue, etc.); call Chatter, Connect, or Apex REST APIs; or invoke AuraEnabled Apex methods from an external app. Does not apply to authentication/OAuth setup, schema changes (adding fields, relationships), Bulk/Tooling/Metadata API usage, declarative automation (Flows, Process Builder), general LWC/Apex coding guidance without a specific data operation, or Salesforce admin/configuration tasks."
 ---
 
 # Salesforce Data Access
@@ -17,7 +17,7 @@ Use this skill when the user wants to:
 
 ## Data SDK Requirement
 
-> **All Salesforce data access MUST use the Data SDK** (`@salesforce/sdk-data`). The SDK handles authentication, CSRF, and base URL resolution. Never use `fetch()` or `axios` directly.
+> **All Salesforce data access MUST use the Data SDK** (`@salesforce/sdk-data`). The SDK handles authentication, CSRF, and base URL resolution.
 
 ```typescript
 import { createDataSDK, gql } from "@salesforce/sdk-data";
@@ -48,7 +48,7 @@ const res = await sdk.fetch?.("/services/apexrest/my-resource");
 **Not supported:**
 
 - **Enterprise REST query endpoint** (`/services/data/v*/query` with SOQL) — blocked at the proxy level. Use GraphQL for record reads; use Apex REST if server-side SOQL aggregates are required.
-- **Aura-enabled Apex** (`@AuraEnabled`) — an LWC/Aura pattern with no invocation path from React webapps.
+- **Aura-enabled Apex** (`@AuraEnabled`) — an LWC/Aura pattern with no invocation path from React UI bundles.
 - **Chatter API** (`/chatter/users/me`) — use `uiapi { currentUser { ... } }` in a GraphQL query instead.
 - **Any other Salesforce REST endpoint** not listed in the supported table above.
 
@@ -67,6 +67,24 @@ const res = await sdk.fetch?.("/services/apexrest/my-resource");
 
 ---
 
+## GraphQL Non-Negotiable Rules
+
+These rules exist because Salesforce GraphQL has platform-specific behaviors that differ from standard GraphQL. Violations cause silent runtime failures.
+
+1. **Schema is the single source of truth** — Every entity name, field name, and type must be confirmed via the schema search script before use in a query. Never guess — Salesforce field names are case-sensitive, relationships may be polymorphic, and custom objects use suffixes (`__c`, `__e`). See [Schema Introspection](references/schema-introspection.md) for entity identification and iterative lookup procedures.
+
+2. **`@optional` on all record fields** (read queries) — Salesforce field-level security (FLS) causes queries to fail entirely if the user lacks access to even one field. The `@optional` directive (v65+) tells the server to omit inaccessible fields instead of failing. Apply it to every scalar field, parent relationship, and child relationship. Consuming code must use optional chaining (`?.`) and nullish coalescing (`??`).
+
+3. **Correct mutation syntax** — Mutations wrap under `uiapi(input: { allOrNone: true/false })`, not bare `uiapi { ... }`. Always set `allOrNone` explicitly. Output fields cannot include child relationships or navigated reference fields. See [Mutation Query Generation](references/mutation-query-generation.md).
+
+4. **Explicit pagination** — Always include `first:` in every query. If omitted, the server silently defaults to 10 records. Include `pageInfo { hasNextPage endCursor }` for any query that may need pagination.
+
+5. **SOQL-derived execution limits** — Max 10 subqueries per request, max 5 levels of child-to-parent traversal, max 1 level of parent-to-child (no grandchildren), max 2,000 records per subquery. If a query would exceed these, split into multiple requests.
+
+6. **HTTP 200 does not mean success** — Salesforce returns HTTP 200 even when operations fail. Always parse the `errors` array in the response body.
+
+---
+
 ## GraphQL Workflow
 
 ### Step 1: Acquire Schema
@@ -74,7 +92,7 @@ const res = await sdk.fetch?.("/services/apexrest/my-resource");
 The `schema.graphql` file (265K+ lines) is the source of truth. **Never open or parse it directly.**
 
 1. Check if `schema.graphql` exists at the SFDX project root
-2. If missing, run from the **webapp dir**: `npm run graphql:schema`
+2. If missing, run from the **UI bundle dir**: `npm run graphql:schema`
 3. Custom objects appear only after metadata is deployed
 
 ### Step 2: Look Up Entity Schema
@@ -82,11 +100,11 @@ The `schema.graphql` file (265K+ lines) is the source of truth. **Never open or
 Map user intent to PascalCase names ("accounts" → `Account`), then **run the search script from the project root**:
 
 ```bash
-# From project root — look up all relevant schema info for one or more entities
-bash .a4drules/skills/using-salesforce-data/graphql-search.sh Account
+# Look up all relevant schema info for one or more entities
+bash scripts/graphql-search.sh Account
 
 # Multiple entities at once
-bash .a4drules/skills/using-salesforce-data/graphql-search.sh Account Contact Opportunity
+bash scripts/graphql-search.sh Account Contact Opportunity
 ```
 
 The script outputs five sections per entity:
@@ -96,11 +114,11 @@ The script outputs five sections per entity:
 4. **Create input** — fields accepted by create mutations
 5. **Update input** — fields accepted by update mutations
 
-Use this output to determine exact field names before writing any query or mutation. **Maximum 2 script runs.** If the entity still can't be found, ask the user — the object may not be deployed.
+Use this output to determine exact field names before writing any query or mutation. **Maximum 2 script runs.** If the entity still can't be found, ask the user — the object may not be deployed. For entity identification procedures (`_Record` suffix, `__c` conventions) and iterative introspection cycles, see [Schema Introspection](references/schema-introspection.md).
 
 ### Step 3: Generate Query
 
-Use the templates below. Every field name **must** be verified from the script output in Step 2.
+Use the templates below. Every field name **must** be verified from the script output in Step 2. For detailed generation rules, filtering, pagination, ordering, semi-joins, and field value wrappers, see [Read Query Generation](references/read-query-generation.md). For mutation chaining, input/output constraints, and transactional semantics, see [Mutation Query Generation](references/mutation-query-generation.md).
 
 #### Read Query Template
 
@@ -138,7 +156,7 @@ const name = node.Name?.value ?? "";
 
 ```graphql
 mutation CreateAccount($input: AccountCreateInput!) {
-  uiapi {
+  uiapi(input: { allOrNone: true }) {
     AccountCreate(input: $input) {
       Record { Id Name { value } }
     }
@@ -215,21 +233,26 @@ const fields = response?.data?.uiapi?.objectInfos?.[0]?.fields ?? [];
 
 ### Step 4: Validate & Test
 
-1. **Lint**: `npx eslint <file>` from webapp dir
+1. **Lint**: `npx eslint <file>` from UI bundle dir
 2. **Test**: Ask user before testing. For mutations, request input values — never fabricate data.
 
 **If ESLint reports a GraphQL error** (e.g. `Cannot query field`, `Unknown type`, `Unknown argument`), the field or type name is wrong. Re-run the schema search script to find the correct name — do not guess:
 
 ```bash
 # From project root — re-check the entity that caused the error
-bash .a4drules/skills/using-salesforce-data/graphql-search.sh <EntityName>
+bash scripts/graphql-search.sh <EntityName>
 ```
 
-Then fix the query using the exact names from the script output.
+Then fix the query using the exact names from the script output. For detailed error categories, status handling, and retry strategy, see [Query Testing](references/query-testing.md).
 
 ---
 
-## Webapp Integration (React)
+## UI Bundle Integration (React)
+
+Two integration patterns are available:
+
+- **Pattern 1 — External `.graphql` file** (recommended for complex queries): Create a `.graphql` file, run `npm run graphql:codegen`, import with `?raw` suffix
+- **Pattern 2 — Inline `gql` tag** (for simple queries): Use the `gql` template tag from `@salesforce/sdk-data`. **Must use `gql`** — plain template strings bypass ESLint schema validation.
 
 ```typescript
 import { createDataSDK, gql } from "@salesforce/sdk-data";
@@ -242,8 +265,9 @@ const GET_ACCOUNTS = gql`
           edges {
             node {
               Id
-              Name @optional { value }
-              Industry @optional { value }
+              Name @optional {
+                value
+              }
             }
           }
         }
@@ -254,14 +278,14 @@ const GET_ACCOUNTS = gql`
 
 const sdk = await createDataSDK();
 const response = await sdk.graphql?.(GET_ACCOUNTS);
-
 if (response?.errors?.length) {
   throw new Error(response.errors.map(e => e.message).join("; "));
 }
-
 const accounts = response?.data?.uiapi?.query?.Account?.edges?.map(e => e.node) ?? [];
 ```
 
+For detailed patterns (external .graphql files, codegen, error handling strategies, quality checklists), see [UI Bundle Integration](references/ui-bundle-integration.md).
+
 ---
 
 ## REST API Patterns
@@ -311,16 +335,16 @@ const response = await sdk.graphql?.(GET_CURRENT_USER);
 <project-root>/                              ← SFDX project root
 ├── schema.graphql                           ← grep target (lives here)
 ├── sfdx-project.json
-└── force-app/main/default/webapplications/<app-name>/  ← webapp dir
+└── force-app/main/default/uiBundles/<app-name>/  ← UI bundle dir
     ├── package.json                         ← npm scripts
     └── src/
 ```
 
 | Command | Run From | Why |
 |---------|----------|-----|
-| `npm run graphql:schema` | webapp dir | Script in webapp's package.json |
-| `npx eslint <file>` | webapp dir | Reads eslint.config.js |
-| `bash .a4drules/skills/using-salesforce-data/graphql-search.sh <Entity>` | project root | Schema lookup |
+| `npm run graphql:schema` | UI bundle dir | Script in UI bundle's package.json |
+| `npx eslint <file>` | UI bundle dir | Reads eslint.config.js |
+| `bash scripts/graphql-search.sh <Entity>` | project root | Schema lookup |
 | `sf api request rest` | project root | Needs sfdx-project.json |
 
 ---
@@ -332,7 +356,7 @@ const response = await sdk.graphql?.(GET_CURRENT_USER);
 Run the search script to get all relevant schema info in one step:
 
 ```bash
-bash .a4drules/skills/using-salesforce-data/graphql-search.sh <EntityName>
+bash scripts/graphql-search.sh <EntityName>
 ```
 
 | Script Output Section | Used For |
@@ -358,6 +382,9 @@ bash .a4drules/skills/using-salesforce-data/graphql-search.sh <EntityName>
 ### Checklist
 
 - [ ] All field names verified via search script (Step 2)
-- [ ] `@optional` applied to record fields (reads)
+- [ ] `@optional` applied to all record fields (reads)
+- [ ] Mutations use `uiapi(input: { allOrNone: ... })` wrapper
+- [ ] `first:` specified in every query
 - [ ] Optional chaining in consuming code
+- [ ] `errors` array checked in response handling
 - [ ] Lint passes: `npx eslint <file>`

package/skills/using-ui-bundle-salesforce-data/references/mutation-query-generation.md

@@ -0,0 +1,140 @@
+# Mutation Query Generation
+
+## Mutation Types
+
+The GraphQL engine supports three mutation operations:
+
+- **Create** — Insert a new record
+- **Update** — Modify an existing record (Id-based)
+- **Delete** — Remove an existing record (Id-based)
+
+Mutations are GA in API v66+. They live under `mutation { uiapi { ... } }` and only support UI API-available objects.
+
+## Generation Rules
+
+1. **Input fields validation** — Validate that input fields satisfy the constraints for the operation type
+2. **Output fields validation** — Validate that output fields satisfy the constraints for the operation type
+3. **Type consistency** — Variables used as query arguments and their related fields must share the same GraphQL type. Verify types via the schema search script — do NOT assume types
+4. **Input arguments** — `input` is the default argument name unless otherwise specified
+5. **Output field** — For `Create` and `Update`, the output field is always named `Record` (type: EntityName)
+6. **Field name validation** — Every field name in the generated mutation **MUST** match a field confirmed via the schema search script. Do NOT guess or assume field names exist
+7. **Raw input values** — Numeric values must be raw numbers without commas, currency symbols, or locale formatting (e.g., `80000` not `"80,000"` or `"$80,000"`). Compound fields (like addresses) require constituent fields (e.g., `BillingCity`, `BillingStreet`) — do not attempt to set the compound wrapper itself.
+
+## Transactional Semantics: `allOrNone`
+
+The `uiapi` mutation input accepts an `allOrNone` argument that controls rollback behavior:
+
+- **`allOrNone: true` (default)** — If any operation fails, all operations in the request are rolled back. Use when operations must succeed or fail together.
+- **`allOrNone: false`** — Independent operations can succeed individually. However, dependent operations (those using `@{alias}` references) still roll back together with their dependencies.
+
+Always set `allOrNone` explicitly to make transactional intent clear.
+
+## Mutation Schema Patterns
+
+Replace `EntityName` with the actual entity name (e.g., Account, Case). `Delete` operations use generic `Record` types.
+
+```graphql
+input EntityNameCreateRepresentation {
+  # Subset of EntityName fields
+}
+input EntityNameCreateInput { EntityName: EntityNameCreateRepresentation! }
+type EntityNameCreatePayload { Record: EntityName! }
+
+input EntityNameUpdateRepresentation {
+  # Subset of EntityName fields
+}
+input EntityNameUpdateInput { Id: IdOrRef! EntityName: EntityNameUpdateRepresentation! }
+type EntityNameUpdatePayload { Record: EntityName! }
+
+input RecordDeleteInput { Id: IdOrRef! }
+type RecordDeletePayload { Id: ID }
+
+type UIAPIMutations {
+  EntityNameCreate(input: EntityNameCreateInput!): EntityNameCreatePayload
+  EntityNameDelete(input: RecordDeleteInput!): RecordDeletePayload
+  EntityNameUpdate(input: EntityNameUpdateInput!): EntityNameUpdatePayload
+}
+```
+
+## Input Field Constraints
+
+### Create
+
+- **Must** include all required fields (unless `defaultedOnCreate` is `true` and not explicitly requested)
+- **Must** only include `createable` fields
+- Child relationships cannot be set — exclude them
+- Reference fields (`REFERENCE` type) can only be assigned IDs through their `ApiName` name
+- **No nested child creates** — Creating a record with child relationships in a single create operation is not supported. To create a parent and child together, use separate operations with `IdOrRef` chaining (see [Mutation Chaining](#mutation-chaining)).
+
+### Update
+
+- **Must** include the `Id` of the entity to update
+- **Must** only include `updateable` fields
+- Child relationships cannot be set — exclude them
+- Reference fields (`REFERENCE` type) can only be assigned IDs through their `ApiName` name
+
+### Delete
+
+- **Must** include the `Id` of the entity to delete
+
+## Output Field Constraints
+
+### Create and Update
+
+- **Must** exclude all child relationships (child relationships cannot be queried in mutations)
+- **Must** exclude all `REFERENCE` fields unless accessed through their `ApiName` member (no navigation to referenced entity, no sub fields)
+- Inaccessible fields are reported in the `errors` attribute of the returned payload
+
+### Delete
+
+- **Must** only include the `Id` field
+
+## Mutation Chaining
+
+Chain related mutations in a single request using references to `Id` values from previous mutations. This is the required approach for creating parent-child records together, since nested child creates are not supported.
+
+1. **Ordering** — Mutation `B` can reference mutation `A` only if `A` comes first in the query
+2. **Notation** — Use `SomeId: "@{A}"` in mutation `B` to set a field to the `Id` produced by mutation `A`
+3. **IDs only** — `@{A}` is always interpreted as the `Id` from mutation `A`
+4. **Restrictions** — `A` must be a `Create` or `Delete` mutation (chaining from `Update` will fail)
+
+### Chaining Example
+
+```graphql
+mutation CreateAccountAndContact {
+  uiapi(input: { allOrNone: true }) {
+    AccountCreate(input: { Account: { Name: "Acme" } }) {
+      Record { Id }
+    }
+    ContactCreate(input: { Contact: { LastName: "Smith", AccountId: "@{AccountCreate}" } }) {
+      Record { Id }
+    }
+  }
+}
+```
+
+## Mutation Query Template
+
+```graphql
+mutation mutateEntityName(
+  # arguments
+) {
+  uiapi(input: { allOrNone: true }) {
+    EntityNameOperation(input: {
+      # For Create and Update only:
+      EntityName: {
+        # Input fields — use raw values, no formatting
+      }
+      # For Update and Delete only:
+      Id: ... # id here
+    }) {
+      # For Create and Update only:
+      Record {
+        # Output fields
+      }
+      # For Delete only:
+      Id
+    }
+  }
+}
+```