@salesforce/afv-skills 1.5.1 → 1.5.3

package/skills/generating-apex-test/references/mocking-patterns.md

@@ -4,7 +4,7 @@
 
 Apex doesn't allow real HTTP callouts in tests. Use `HttpCalloutMock` interface.
 
-### Basic Mock Implementation
+### Basic Mock
 
 ```apex
 @isTest
@@ -33,34 +33,28 @@ public class MockHttpResponse implements HttpCalloutMock {
 ```apex
 @isTest
 static void shouldProcessApiResponse_WhenCalloutSucceeds() {
-    // Given
     String mockResponse = '{"status": "success", "data": [{"id": "123"}]}';
     Test.setMock(HttpCalloutMock.class, new MockHttpResponse(200, mockResponse));
-    
-    // When
+
     Test.startTest();
     List<ExternalRecord> results = MyIntegrationService.fetchRecords();
     Test.stopTest();
-    
-    // Then
-    System.assertEquals(1, results.size(), 'Should parse one record from response');
-    System.assertEquals('123', results[0].externalId, 'Should extract correct ID');
+
+    Assert.areEqual(1, results.size(), 'Should parse one record from response');
+    Assert.areEqual('123', results[0].externalId, 'Should extract correct ID');
 }
 
 @isTest
 static void shouldHandleError_WhenCalloutFails() {
-    // Given
     String errorResponse = '{"error": "Unauthorized"}';
     Test.setMock(HttpCalloutMock.class, new MockHttpResponse(401, errorResponse));
-    
-    // When
+
     Test.startTest();
     CalloutResult result = MyIntegrationService.fetchRecords();
     Test.stopTest();
-    
-    // Then
-    System.assertEquals(false, result.isSuccess, 'Should indicate failure');
-    System.assert(result.errorMessage.contains('Unauthorized'), 'Should capture error');
+
+    Assert.areEqual(false, result.isSuccess, 'Should indicate failure');
+    Assert.isTrue(result.errorMessage.contains('Unauthorized'), 'Should capture error');
 }
 ```
 
@@ -71,83 +65,101 @@ For services making multiple callouts:
 ```apex
 @isTest
 public class MultiRequestMock implements HttpCalloutMock {
-    
+
     private Map<String, HttpResponse> endpointResponses;
-    
+
     public MultiRequestMock(Map<String, HttpResponse> responses) {
         this.endpointResponses = responses;
     }
-    
+
     public HTTPResponse respond(HTTPRequest req) {
         String endpoint = req.getEndpoint();
-        
         for (String key : endpointResponses.keySet()) {
             if (endpoint.contains(key)) {
                 return endpointResponses.get(key);
             }
         }
-        
-        // Default 404 if no match
         HttpResponse res = new HttpResponse();
         res.setStatusCode(404);
         res.setBody('{"error": "Not found"}');
         return res;
     }
 }
-
-// Usage:
-Map<String, HttpResponse> mocks = new Map<String, HttpResponse>();
-
-HttpResponse authResponse = new HttpResponse();
-authResponse.setStatusCode(200);
-authResponse.setBody('{"token": "abc123"}');
-mocks.put('/oauth/token', authResponse);
-
-HttpResponse dataResponse = new HttpResponse();
-dataResponse.setStatusCode(200);
-dataResponse.setBody('{"records": []}');
-mocks.put('/api/records', dataResponse);
-
-Test.setMock(HttpCalloutMock.class, new MultiRequestMock(mocks));
 ```
 
-## StaticResourceCalloutMock
+### StaticResourceCalloutMock
 
-For complex response bodies, store JSON in Static Resources:
+Use when response JSON is large or complex:
 
 ```apex
 @isTest
 static void shouldParseComplexResponse() {
     StaticResourceCalloutMock mock = new StaticResourceCalloutMock();
-    mock.setStaticResource('TestApiResponse'); // Static Resource name
+    mock.setStaticResource('TestApiResponse');
     mock.setStatusCode(200);
     mock.setHeader('Content-Type', 'application/json');
-    
     Test.setMock(HttpCalloutMock.class, mock);
-    
+
     Test.startTest();
     Result r = MyService.callExternalApi();
     Test.stopTest();
-    
-    System.assertNotEquals(null, r, 'Should parse response');
+
+    Assert.isNotNull(r, 'Should parse response');
+}
+```
+
+## SOSL Mocking
+
+SOSL returns empty results in tests by default. Call `Test.setFixedSearchResults(List<Id>)` before the search:
+
+```apex
+@isTest
+static void shouldReturnSearchResults() {
+    Account acc = TestDataFactory.createAccount(true);
+    Test.setFixedSearchResults(new List<Id>{ acc.Id });
+
+    Test.startTest();
+    List<Account> results = MyService.searchAccounts('Test');
+    Test.stopTest();
+
+    Assert.areEqual(1, results.size(), 'Should return mocked search result');
+}
+```
+
+## DML Mocking (Constructor Injection)
+
+Design for testability — use a public constructor for production and a `@TestVisible private` constructor that accepts mock interfaces:
+
+```apex
+public class MyService {
+    private IDML dmlHandler;
+
+    public MyService() {
+        this.dmlHandler = new DMLHandler();
+    }
+
+    @TestVisible
+    private MyService(IDML dmlHandler) {
+        this.dmlHandler = dmlHandler;
+    }
+
+    public void createRecords(List<Account> accounts) {
+        dmlHandler.doInsert(accounts);
+    }
 }
 ```
 
-## Stub API (Enterprise Pattern)
+## Stub API (System.StubProvider)
 
-For mocking Apex class dependencies using `System.StubProvider`:
+For mocking Apex class dependencies:
 
 ```apex
 @isTest
 public class MyServiceMock implements System.StubProvider {
-    
+
     public Object handleMethodCall(
-        Object stubbedObject,
-        String stubbedMethodName,
-        Type returnType,
-        List<Type> paramTypes,
-        List<String> paramNames,
-        List<Object> args
+        Object stubbedObject, String stubbedMethodName, Type returnType,
+        List<Type> paramTypes, List<String> paramNames, List<Object> args
     ) {
         if (stubbedMethodName == 'getAccountData') {
             return new AccountData('Mock Account', 'Active');
@@ -156,42 +168,36 @@ public class MyServiceMock implements System.StubProvider {
     }
 }
 
-// Usage in test:
 @isTest
 static void shouldUseAccountData() {
     MyServiceMock mockProvider = new MyServiceMock();
-    IMyService mockService = (IMyService)Test.createStub(IMyService.class, mockProvider);
-    
-    // Inject mock into class under test
+    IMyService mockService = (IMyService) Test.createStub(IMyService.class, mockProvider);
+
     MyController controller = new MyController(mockService);
-    
+
     Test.startTest();
     String result = controller.displayAccountInfo();
     Test.stopTest();
-    
-    System.assert(result.contains('Mock Account'), 'Should use mocked data');
+
+    Assert.isTrue(result.contains('Mock Account'), 'Should use mocked data');
 }
 ```
 
-## Email Mocking
+## Email Testing
 
-Apex sends real emails by default. Use limits to verify:
+Apex doesn't actually send emails in tests. Use limits to verify:
 
 ```apex
 @isTest
 static void shouldSendEmail_WhenTriggered() {
     Integer emailsBefore = Limits.getEmailInvocations();
-    
+
     Test.startTest();
     MyService.sendNotification(testContact);
     Test.stopTest();
-    
-    // Verify email was queued (not actually sent in tests)
-    System.assertEquals(
-        emailsBefore + 1, 
-        Limits.getEmailInvocations(), 
-        'One email should be sent'
-    );
+
+    Assert.areEqual(emailsBefore + 1, Limits.getEmailInvocations(),
+        'One email should be sent');
 }
 ```
 
@@ -201,19 +207,14 @@ static void shouldSendEmail_WhenTriggered() {
 @isTest
 static void shouldPublishEvent_WhenRecordCreated() {
     Test.startTest();
-    
-    // Enable event delivery in test context
     Test.enableChangeDataCapture();
-    
+
     Account acc = TestDataFactory.createAccount(true);
-    
-    // Deliver events
     Test.getEventBus().deliver();
-    
     Test.stopTest();
     
     // Query platform event trigger results
     List<EventLog__c> logs = [SELECT Id FROM EventLog__c WHERE AccountId__c = :acc.Id];
-    System.assertEquals(1, logs.size(), 'Event handler should create log record');
+    Assert.areEqual(1, logs.size(), 'Event handler should create log record');
 }
 ```

package/skills/generating-apex-test/references/test-data-factory.md

@@ -1,113 +1,18 @@
 # TestDataFactory Patterns
 
-## Overview
+For the base class template, see [assets/test-data-factory-template.cls](../assets/test-data-factory-template.cls).
 
-TestDataFactory is a centralized utility class for creating test records with sensible defaults. It ensures consistent test data across all test classes and reduces duplication.
+## Design Rules
 
-## Base Template
-
-```apex
-@isTest
-public class TestDataFactory {
-    
-    // ============ ACCOUNTS ============
-    
-    public static List<Account> createAccounts(Integer count, Boolean doInsert) {
-        List<Account> accounts = new List<Account>();
-        for (Integer i = 0; i < count; i++) {
-            accounts.add(new Account(
-                Name = 'Test Account ' + i,
-                BillingStreet = '123 Test St',
-                BillingCity = 'San Francisco',
-                BillingState = 'CA',
-                BillingPostalCode = '94105',
-                BillingCountry = 'USA',
-                Industry = 'Technology',
-                Type = 'Customer'
-            ));
-        }
-        if (doInsert) insert accounts;
-        return accounts;
-    }
-    
-    public static Account createAccount(Boolean doInsert) {
-        return createAccounts(1, doInsert)[0];
-    }
-    
-    // ============ CONTACTS ============
-    
-    public static List<Contact> createContacts(List<Account> accounts, Integer countPerAccount, Boolean doInsert) {
-        List<Contact> contacts = new List<Contact>();
-        Integer index = 0;
-        for (Account acc : accounts) {
-            for (Integer i = 0; i < countPerAccount; i++) {
-                contacts.add(new Contact(
-                    FirstName = 'Test',
-                    LastName = 'Contact ' + index,
-                    Email = 'test.contact' + index + '@example.com',
-                    Phone = '555-000-' + String.valueOf(index).leftPad(4, '0'),
-                    AccountId = acc.Id
-                ));
-                index++;
-            }
-        }
-        if (doInsert) insert contacts;
-        return contacts;
-    }
-    
-    // ============ OPPORTUNITIES ============
-    
-    public static List<Opportunity> createOpportunities(List<Account> accounts, Integer countPerAccount, Boolean doInsert) {
-        List<Opportunity> opps = new List<Opportunity>();
-        Integer index = 0;
-        for (Account acc : accounts) {
-            for (Integer i = 0; i < countPerAccount; i++) {
-                opps.add(new Opportunity(
-                    Name = 'Test Opportunity ' + index,
-                    AccountId = acc.Id,
-                    StageName = 'Prospecting',
-                    CloseDate = Date.today().addDays(30),
-                    Amount = 10000 + (index * 1000)
-                ));
-                index++;
-            }
-        }
-        if (doInsert) insert opps;
-        return opps;
-    }
-    
-    // ============ USERS ============
-    
-    public static User createUser(String profileName, Boolean doInsert) {
-        Profile p = [SELECT Id FROM Profile WHERE Name = :profileName LIMIT 1];
-        String uniqueKey = String.valueOf(DateTime.now().getTime());
-        
-        User u = new User(
-            FirstName = 'Test',
-            LastName = 'User ' + uniqueKey,
-            Email = 'testuser' + uniqueKey + '@example.com',
-            Username = 'testuser' + uniqueKey + '@example.com.test',
-            Alias = 'tuser',
-            TimeZoneSidKey = 'America/Los_Angeles',
-            LocaleSidKey = 'en_US',
-            EmailEncodingKey = 'UTF-8',
-            LanguageLocaleKey = 'en_US',
-            ProfileId = p.Id
-        );
-        if (doInsert) insert u;
-        return u;
-    }
-    
-    // ============ CUSTOM OBJECTS ============
-    
-    // Add methods for your custom objects following the same pattern:
-    // public static List<MyObject__c> createMyObjects(Integer count, Boolean doInsert) { ... }
-}
-```
+1. **Always accept a `doInsert` flag** — lets callers modify records before insert
+2. **Append loop index to all fields that participate in matching rules** — prevents `DUPLICATES_DETECTED` errors from active Duplicate Rules
+3. **Single-record methods delegate to bulk** — e.g., `createAccount(doInsert)` calls `createAccounts(1, doInsert)[0]`
+4. **Return created records** — enables chaining and further manipulation
+5. **Set all required fields** — include fields enforced by validation rules, not just schema-required fields
 
 ## Field Override Pattern
 
-Allow callers to override default values:
+Allow callers to override default values without creating new factory methods:
 
 ```apex
 public static Account createAccount(Map<String, Object> fieldOverrides, Boolean doInsert) {
@@ -115,12 +20,9 @@ public static Account createAccount(Map<String, Object> fieldOverrides, Boolean
         Name = 'Test Account',
         Industry = 'Technology'
     );
-    
-    // Apply overrides
     for (String fieldName : fieldOverrides.keySet()) {
         acc.put(fieldName, fieldOverrides.get(fieldName));
     }
-    
     if (doInsert) insert acc;
     return acc;
 }
@@ -132,23 +34,6 @@ Account acc = TestDataFactory.createAccount(new Map<String, Object>{
 }, true);
 ```
 
-## Handling Required Fields and Validation Rules
-
-```apex
-public static Account createAccountWithRequiredFields(Boolean doInsert) {
-    Account acc = new Account(
-        Name = 'Test Account',
-        // Required custom fields
-        External_Id__c = 'EXT-' + String.valueOf(DateTime.now().getTime()),
-        // Fields required by validation rules
-        Phone = '555-123-4567',
-        Website = 'https://example.com'
-    );
-    if (doInsert) insert acc;
-    return acc;
-}
-```
-
 ## Record Type Support
 
 ```apex
@@ -157,7 +42,7 @@ public static Account createAccountByRecordType(String recordTypeName, Boolean d
         .getRecordTypeInfosByDeveloperName()
         .get(recordTypeName)
         .getRecordTypeId();
-    
+
     Account acc = new Account(
         Name = 'Test Account',
         RecordTypeId = recordTypeId
@@ -167,10 +52,24 @@ public static Account createAccountByRecordType(String recordTypeName, Boolean d
 }
 ```
 
-## Best Practices
+## Handling Duplicate Rules
 
-1. **Always include doInsert parameter** - Allows flexibility for tests that need to modify records before insert
-2. **Use unique identifiers** - Include index or timestamp in Name/Email fields to avoid duplicates
-3. **Set all required fields** - Include all fields required by validation rules
-4. **Return the created records** - Enables chaining and further manipulation
-5. **Create bulk methods first** - Single record methods should call bulk methods with count=1
+When unique field values alone are not sufficient, use `Database.insert()` with a `DuplicateRuleHeader`:
+
+```apex
+public static List<Account> createAccountsAllowDuplicates(Integer count, Boolean doInsert) {
+    List<Account> accounts = new List<Account>();
+    for (Integer i = 0; i < count; i++) {
+        accounts.add(new Account(
+            Name = 'Test Account ' + i,
+            Phone = '555-000-' + String.valueOf(i).leftPad(4, '0')
+        ));
+    }
+    if (doInsert) {
+        Database.DMLOptions dml = new Database.DMLOptions();
+        dml.DuplicateRuleHeader.allowSave = true;
+        Database.insert(accounts, dml);
+    }
+    return accounts;
+}
+```

package/skills/generating-experience-react-site/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: generating-experience-react-site
-description: "Use this skill when users need to create or configure a Salesforce Digital Experience Site specifically for hosting a React web application. Trigger when users mention creating an Experience site for a React app, setting up a React site on Salesforce, configuring Network/CustomSite/DigitalExperience metadata for a web app, or deploying site infrastructure for a React application. Also trigger when users mention site URL path prefixes, app namespaces, appDevName, guest access configuration, DigitalExperienceConfig, DigitalExperienceBundle, or sfdc_cms__site content types in the context of React apps. Always use this skill for any React web application site creation or site infrastructure configuration work, even if the user just says \"create a site for my React app\" or \"set up the site for my web application.\""
+description: "Use this skill when users need to create or configure a Salesforce Digital Experience Site specifically for hosting a React UI bundle. Trigger when users mention creating an Experience site for a React app, setting up a React site on Salesforce, configuring Network/CustomSite/DigitalExperience metadata for a UI bundle, or deploying site infrastructure for a React application. Also trigger when users mention site URL path prefixes, app namespaces, appDevName, guest access configuration, DigitalExperienceConfig, DigitalExperienceBundle, or sfdc_cms__site content types in the context of React apps. Always use this skill for any React UI bundle site creation or site infrastructure configuration work, even if the user just says \"create a site for my React app\" or \"set up the site for my UI bundle.\""
 ---
 
-# Digital Experience Site for React Web Applications
-Create and configure Digital Experience Sites that host React web applications on Salesforce. This skill generates the minimum necessary site infrastructure — Network, CustomSite, DigitalExperienceConfig, DigitalExperienceBundle, and the `sfdc_cms__site` content type — so a React app can be served from Salesforce.
+# Digital Experience Site for React UI Bundles
+Create and configure Digital Experience Sites that host React UI bundles on Salesforce. This skill generates the minimum necessary site infrastructure — Network, CustomSite, DigitalExperienceConfig, DigitalExperienceBundle, and the `sfdc_cms__site` content type — so a React app can be served from Salesforce.
 
-React sites differ from standard LWR sites: they don't need routes, views, theme layouts, or branding sets. The site acts as a thin container (`appContainer: true`) that delegates rendering to the React application referenced by `appSpace`.
+React sites differ from standard LWR sites: they don't need routes, views, theme layouts, or branding sets. The site acts as a thin container (`appContainer: true`) that delegates rendering to the React UI bundle referenced by `appSpace`.
 
 ## Required Properties
 Resolve all five properties before generating any metadata. Each has a fallback chain — work through each option in order until a value is found.
@@ -14,9 +14,9 @@ Resolve all five properties before generating any metadata. Each has a fallback
 | Property | Format | How to Resolve |
 |----------|--------|----------------|
 | **siteName** | `UpperCamelCase` (e.g., `MyCommunity`) | Ask user or derive from context |
-| **siteUrlPathPrefix** | `kebab-case` (e.g., `my-community`) | User-provided, or convert siteName to kebab-case |
+| **siteUrlPathPrefix** | `All lowercase` (e.g., `mycommunity`) | User-provided, or convert siteName to all lowercase with alphanumeric characters only |
 | **appNamespace** | String | `namespace` in `sfdx-project.json` → `sf data query -q "SELECT NamespacePrefix FROM Organization" --target-org ${usernameOrAlias}` → default `c` |
-| **appDevName** | String | `webApplication` metadata in the project → `sf data query -q "SELECT DeveloperName FROM WebApplication" --target-org ${usernameOrAlias}` → default to siteName |
+| **appDevName** | String | `UIBundle` metadata in the project → `sf data query -q "SELECT DeveloperName FROM UIBundle" --target-org ${usernameOrAlias}` → default to siteName |
 | **enableGuestAccess** | Boolean | Ask user whether unauthenticated guest users can access site APIs → default `false` |
 
 The `appNamespace` and `appDevName` properties connect the site to the correct React application. Getting these wrong means the site deploys but shows a blank page, so take care to resolve them from real project data.
@@ -26,7 +26,7 @@ The `appNamespace` and `appDevName` properties connect the site to the correct R
 Determine values for all five properties before constructing anything. Use the resolution strategies in the table above, falling through each option until a value is found.
 
 ### Step 2: Create the Project Structure
-Call the `get_metadata_api_context` MCP tool to retrieve schemas for `Network`, `CustomSite`, `DigitalExperienceConfig`, and `DigitalExperienceBundle` metadata types. These schemas define the valid XML structure for each file.
+Use available Salesforce metadata schema and field context for `Network`, `CustomSite`, `DigitalExperienceConfig`, and `DigitalExperienceBundle` to ensure each file uses valid structure.
 
 Create any files and directories that don't already exist, using these paths:
 
@@ -63,7 +63,7 @@ Use the default templates in the docs below. Values in `{braces}` are resolved p
 - Read entire file contents, replace placeholders (e.g. `{siteName}`) with the resolved values, then use the expanded templates to populate the metadata XML/JSON content.
   
 ### Step 4: Resolve Additional Configurations
-Address any extra configurations the user requests. Use the schemas returned by `get_metadata_api_context` in Step 2 to understand each field's purpose, and update only the minimum necessary fields.
+Address any extra configurations the user requests. Use the metadata sections and field context identified in Step 2 to understand each field’s purpose and constraints, then update only the minimum necessary fields.
 
 ## Verification Checklist
 Before deploying, confirm:
@@ -71,7 +71,7 @@ Before deploying, confirm:
 - [ ] All five required properties are resolved
 - [ ] All metadata directories and files exist per the project structure
 - [ ] All metadata fields are populated per the templates and user requests
-- [ ] `appSpace` in `content.json` matches an existing `WebApplication` metadata record
+- [ ] `appSpace` in `content.json` matches an existing `UIBundle` metadata record
 - [ ] Deployment validates successfully:
 ```bash
 sf project deploy validate --metadata Network CustomSite DigitalExperienceConfig DigitalExperienceBundle DigitalExperience --target-org ${usernameOrAlias}

package/skills/generating-experience-react-site/docs/configure-metadata-digital-experience.md

@@ -3,7 +3,7 @@
 ## Purpose
 These configuration files create **net-new, default** DigitalExperience content records (`sfdc_cms__site` type) for a Digital Experience React Site. They are not intended to edit or modify existing DigitalExperience content. Use these templates only when provisioning a brand-new React site.
 
-The `appContainer: true` and `appSpace` fields in `content.json` are what make this a React site rather than a standard LWR site. The `appSpace` value follows the format `{namespace}__{developerName}` and must match a deployed `WebApplication` metadata record.
+The `appContainer: true` and `appSpace` fields in `content.json` are what make this a React site rather than a standard LWR site. The `appSpace` value follows the format `{namespace}__{developerName}` and must match a deployed `UIBundle` metadata record.
 
 ## File Location
 The DigitalExperience directory contains only `_meta.json` and `content.json`. Do not create any directories other than `sfdc_cms__site` inside the bundle.

package/skills/generating-flexipage/SKILL.md

@@ -43,20 +43,36 @@ sf template generate flexipage \
   --output-dir force-app/main/default/flexipages
 ```
 
-**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
-```
+**CRITICAL:** If the `sf template generate flexipage` command fails, **STOP**.
 
-#### **Field Selection Guidelines**
-- **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
+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)
-- **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
+
+**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
+
+**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
@@ -238,7 +254,7 @@ Every fieldInstance requires:
 
 ### "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 Guidelines)
+**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`  

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.
+
+
+