@salesforce/afv-skills 1.5.0 → 1.5.2

package/skills/generating-flexipage/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: generating-flexipage
-description: "Use this skill when users need to create, generate, modify, or validate Salesforce Lightning pages (FlexiPages). Trigger when users mention RecordPage, AppPage, HomePage, Lightning pages, page layouts, adding components to pages, or page customization. Also use when users say things like \"create a Lightning page\", \"add a component to a page\", \"customize the record page\", \"generate a FlexiPage\", or when they're working with FlexiPage XML files and need help with components, regions, or deployment errors. Always use this skill for any FlexiPage-related work, even if they just mention \"page\" in the context of Salesforce."
+description: "Use this skill when users need to create, generate, modify, or validate Salesforce Lightning pages (FlexiPages). Trigger when users mention RecordPage, AppPage, HomePage, Lightning pages, page layouts, adding components to pages, or page customization. Also use when users say things like 'create a Lightning page', 'add a component to a page', 'customize the record page', 'generate a FlexiPage', or when they're working with FlexiPage XML files and need help with components, regions, or deployment errors. Always use this skill for any FlexiPage-related work, even if they just mention 'page' in the context of Salesforce."
 ---
 
 ## When to Use This Skill
@@ -20,6 +20,8 @@ Use this skill when you need to:
 
 ## Overview
 
+**CRITICAL: When creating NEW FlexiPages, you MUST ALWAYS start with the CLI template command.** Never create FlexiPage XML from scratch - the CLI provides valid structure, proper regions, and correct component configuration that prevents deployment errors.
+
 Generate Lightning pages (RecordPage, AppPage, HomePage) using CLI bootstrapping for component discovery and configuration.
 
 ---
@@ -28,6 +30,8 @@ Generate Lightning pages (RecordPage, AppPage, HomePage) using CLI bootstrapping
 
 ### Step 1: Bootstrap with CLI
 
+**MANDATORY FOR NEW PAGES: This step is NOT optional.** Always use the CLI template command when creating a new FlexiPage. The CLI generates valid XML structure, proper regions, and correct metadata that prevents common deployment errors. Only skip this step if you're editing an existing FlexiPage file.
+
 ```bash
 sf template generate flexipage \
   --name <PageName> \
@@ -39,19 +43,38 @@ sf template generate flexipage \
   --output-dir force-app/main/default/flexipages
 ```
 
-**Template-specific requirements:**
-- **RecordPage**: Requires `--sobject` (e.g., Account, Custom_Object__c)
-- **RecordPage**: Requires `--primary-field` and `--secondary-fields` for dynamic highlights, `--detail-fields` for full record details. Use the most important identifying field as primary, e.g. Name. Use the secondary fields (max 12, recommended 4-6) to show a summary of the record. Use detail fields to show the full details of the record.
-- **AppPage**: No additional requirements
-- **HomePage**: No additional requirements
+**CRITICAL:** If the `sf template generate flexipage` command fails, **STOP**.
 
-**Note:** If the `sf template generate flexipage` command fails, recommend users upgrade to the latest version of the Salesforce CLI:
-```bash
-npm install -g @salesforce/cli@latest
-```
+1. Install the templates plugin:
+   ```bash
+   sf plugins install templates
+   ```
+2. Retry the `sf template generate flexipage` command
+3. Verify the FlexiPage XML file was created
+
+Do NOT continue to Step 2 until the template command succeeds. The generated XML is required for the entire workflow.
+
+#### **Template-specific requirements**
+
+**RecordPage:**
+- Requires `--sobject` (e.g., Account, Custom_Object__c)
+- Requires field parameters:
+  - `--primary-field`: Most important identifying field (e.g., Name)
+  - `--secondary-fields`: Record summary (recommended 4-6, max 12)
+  - `--detail-fields`: Full record details, including required fields (e.g., Name)
 
+**AppPage:**
+- No additional requirements
 
-**What you get:**
+**HomePage:**
+- No additional requirements
+
+#### **Field Selection Rules**
+- **Validate fields exist**: Use MCP tools or describe commands to discover available fields for the object before specifying them in the command
+- **Prefer compound fields**: Use `Name` (not `FirstName`/`LastName`), `BillingAddress` (not `BillingStreet`/`BillingCity`/`BillingState`), `MailingAddress`, etc. when available
+- **Include required fields in detail-fields**: Always include object required fields (like `Name`) in the `--detail-fields` parameter, even if they're also used in `--primary-field` or `--secondary-fields`
+
+#### **What you get**
 - Valid FlexiPage XML with correct structure
 - Pre-configured regions and basic components
 - Proper field references and facet structure
@@ -59,17 +82,31 @@ npm install -g @salesforce/cli@latest
 
 ### Step 2: Deploy Base Page
 
+Run a **dry-run** deployment of the entire project to validate the page and dependencies:
 ```bash
-sf project deploy start --source-dir force-app/main/default/flexipages
+sf project deploy start --dry-run -d "force-app/main/default" --test-level NoTestRun --wait 10 --json
 ```
 
-**Deploy early, deploy often.** Start with the bootstrapped page, validate it works, then enhance.
+**Critical:** Fix any deployment errors before proceeding. The page must validate successfully.
+
+### Step 3: **STOP - No Further Modifications**
 
-### Step 3: Update and Redeploy
+**MANDATORY: Stop after Step 2. Do not add components or edit the FlexiPage XML.**
 
-Modify the generated XML, adding components discovered via MCP. Deploy incrementally.
+This applies even if the user requested:
+- Additional components
+- Page customization
+- Component configuration
 
-**Note:** Warn users to use caution with updates beyond this step when using this command.
+What you CAN do:
+- Suggest what components would be useful
+- Explain what enhancements are possible
+- Document what would need to be added manually
+
+What you CANNOT do:
+- Modify the XML file
+- Add any components
+- Make any enhancements
 
 ---
 
@@ -215,6 +252,10 @@ Every fieldInstance requires:
 
 ## Common Deployment Errors
 
+### "We couldn't retrieve or load the information on the field"
+**Cause:** Invalid field API name - field doesn't exist on the object or has incorrect spelling
+**Fix:** Use MCP tools or describe commands to discover valid fields, then update the field reference (see Field Selection Rules)
+
 ### "Invalid field reference"
 **Cause:** Used `ObjectName.Field` instead of `Record.Field`  
 **Fix:** Change to `Record.{FieldApiName}`
@@ -245,49 +286,6 @@ Every fieldInstance requires:
 
 ---
 
-## Incremental Development Pattern
-
-**Philosophy:** Deploy small, working increments. Don't build entire complex page at once.
-
-**Process:**
-1. **CLI bootstrap** → Deploy base page
-2. **Add one component** → Deploy
-3. **Add another component** → Deploy
-4. **Repeat** until complete
-
-**Benefits:**
-- Isolated errors (know exactly what broke)
-- Faster debugging
-- Build confidence with each success
-- Get user feedback early
-
-**Anti-pattern:** Building entire complex page → one giant error cascade.
-
----
-
-## Adding Components to Existing FlexiPages
-
-### Workflow
-
-When user provides an existing FlexiPage file path:
-
-1. **Read the file** using native file I/O
-2. **Parse XML** to extract:
-   - **ALL existing component identifiers** (search for all `<identifier>` tags)
-   - **ALL existing region/facet names** (search for all `<name>` tags in `<flexiPageRegions>`)
-   - Available regions (parse from file, don't assume names)
-   - Existing facets
-3. **Verify uniqueness** - ensure your new identifiers and names don't conflict with ANY existing ones
-4. **Check if target facet exists** - if adding to a named facet like `detailTabContent` that already exists:
-   - **Add new `<itemInstances>` to existing region** (don't create duplicate region)
-   - **Insert before the closing `</flexiPageRegions>` tag of that region**
-5. **Generate component XML** (apply all rules from "Critical XML Rules" section)
-6. **Insert** into appropriate region or add itemInstances to existing facet
-7. **Write** modified XML back to file
-8. **Deploy**: `sf project deploy start --source-dir force-app/...`
-
----
-
 ### Generating Unique Identifiers
 
 **CRITICAL: Before generating ANY new identifier or facet name, follow the rules in section 5 of "Critical XML Rules" above.**
@@ -474,7 +472,7 @@ Identifier Pattern: flexipage_richText or flexipage_richText_{sequence}
 ## Validation Checklist
 
 Before deploying:
-- [ ] Used CLI to bootstrap (don't start from scratch)
+- [ ] **[NEW PAGES ONLY]** Used CLI to bootstrap - NEVER create FlexiPage XML from scratch
 - [ ] **ALL identifiers are unique** - no duplicate `<identifier>` values anywhere in file
 - [ ] **ALL region/facet names are unique** - no duplicate `<name>` values in `<flexiPageRegions>`
 - [ ] **Multiple components in same facet are combined** - ONE region with multiple `<itemInstances>`, NOT separate regions with same name

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

@@ -0,0 +1,45 @@
+---
+name: generating-ui-bundle-features
+description: "Search and install pre-built features into Salesforce React UI bundles — authentication, shadcn, search, navigation, GraphQL, Agentforce AI, and more. Use whenever searching for or installing features. Always check for an existing feature before building from scratch. Triggers on: install feature, add authentication, add shadcn, add feature, search features, list features."
+---
+
+# UI Bundle Features
+
+## Installing Pre-built Features
+
+Always check for an existing feature before building something from scratch. The features CLI installs pre-built, tested packages into Salesforce UI bundles — from foundational UI libraries (shadcn/ui) to full-stack capabilities (authentication, search, navigation, GraphQL, Agentforce AI).
+
+### Workflow
+
+1. **Search project code first** — check `src/` for existing implementations before installing anything. Scope searches to `src/` to avoid matching `node_modules/` or `dist/`.
+
+2. **Search available features** — use `npx @salesforce/ui-bundle-features list` with `--search <query>` to filter by keyword. Use `--verbose` for full descriptions.
+
+3. **Describe a feature** — use `npx @salesforce/ui-bundle-features describe <feature>` to see components, dependencies, copy operations, and example files.
+
+4. **Install** — use `npx @salesforce/ui-bundle-features install <feature> --ui-bundle-dir <name>`. Key options:
+   - `--dry-run` to preview changes
+   - `--yes` for non-interactive mode (skips conflicts)
+   - `--on-conflict error` to detect conflicts, then `--conflict-resolution <file>` to resolve them
+
+If no matching feature is found, ask the user before building a custom implementation — a relevant feature may exist under a different name.
+
+### Conflict Handling
+
+In non-interactive environments, use the two-pass approach: first run with `--on-conflict error` to detect conflicts, then create a resolution JSON file (`{ "path": "skip" | "overwrite" }`) and re-run with `--conflict-resolution`.
+
+### Post-install: Integrating Example Files
+
+Features may include `__example__` files showing integration patterns. For each:
+
+1. Read the example file to understand the pattern
+2. Read the target file (shown in `describe` output)
+3. Apply the pattern from the example into the target
+4. Delete the example file after successful integration
+
+### Hint Placeholders
+
+Some copy paths use `<descriptive-name>` placeholders (e.g., `<desired-page-with-search-input>`) that the CLI does not resolve. After installation, rename or relocate these files to the intended target, or integrate their patterns into an existing file.
+
+
+

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:**