@salesforce/afv-skills 1.2.0 → 1.4.0

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

@@ -0,0 +1,17 @@
+# Configure Metadata: DigitalExperienceBundle
+
+## Purpose
+This configuration file creates a **net-new, default** DigitalExperienceBundle metadata record for a Digital Experience React Site. It is not intended to edit or modify an existing DigitalExperienceBundle record. Use this template only when provisioning a brand-new React site.
+
+## File Location
+```
+digitalExperiences/site/{siteName}1/{siteName}1.digitalExperience-meta.xml
+```
+
+## Default Template
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<DigitalExperienceBundle xmlns="http://soap.sforce.com/2006/04/metadata">
+    <label>{siteName}1</label>
+</DigitalExperienceBundle>
+```

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

@@ -0,0 +1,21 @@
+# Configure Metadata: DigitalExperienceConfig
+
+## Purpose
+This configuration file creates a **net-new, default** DigitalExperienceConfig metadata record for a Digital Experience React Site. It is not intended to edit or modify an existing DigitalExperienceConfig record. Use this template only when provisioning a brand-new React site.
+
+## File Location
+```
+digitalExperienceConfigs/{siteName}1.digitalExperienceConfig-meta.xml
+```
+
+## Default Template
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<DigitalExperienceConfig xmlns="http://soap.sforce.com/2006/04/metadata">
+    <label>{siteName}</label>
+    <site>
+        <urlPathPrefix>{siteUrlPathPrefix}</urlPathPrefix>
+    </site>
+    <space>site/{siteName}1</space>
+</DigitalExperienceConfig>
+```

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

@@ -0,0 +1,38 @@
+# Configure Metadata: DigitalExperience (sfdc_cms__site)
+
+## 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.
+
+## 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.
+
+```
+digitalExperiences/site/{siteName}1/sfdc_cms__site/{siteName}1/_meta.json
+digitalExperiences/site/{siteName}1/sfdc_cms__site/{siteName}1/content.json
+```
+
+## Default Templates
+### `_meta.json`
+```json
+{
+  "apiName": "{siteName}1",
+  "path": "",
+  "type": "sfdc_cms__site"
+}
+```
+
+### `content.json`
+```json
+{
+  "type": "sfdc_cms__site",
+  "title": "{siteName}",
+  "urlName": "{siteUrlPathPrefix}",
+  "contentBody": {
+    "authenticationType": "AUTHENTICATED_WITH_PUBLIC_ACCESS_ENABLED",
+    "appContainer": true,
+    "appSpace": "{appNamespace}__{appDevName}"
+  }
+}
+```

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

@@ -0,0 +1,72 @@
+# Configure Metadata: Network
+
+## Purpose
+This configuration file creates a **net-new, default** Network metadata record for a Digital Experience React Site. It is not intended to edit or modify an existing Network record. Use this template only when provisioning a brand-new React site.
+
+## File Location
+```
+networks/{siteName}.network-meta.xml
+```
+
+## Default Template
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<Network xmlns="http://soap.sforce.com/2006/04/metadata">
+    <allowInternalUserLogin>false</allowInternalUserLogin>
+    <allowMembersToFlag>false</allowMembersToFlag>
+    <changePasswordTemplate>unfiled$public/CommunityChangePasswordEmailTemplate</changePasswordTemplate>
+    <disableReputationRecordConversations>true</disableReputationRecordConversations>
+    <emailSenderAddress>admin@company.com</emailSenderAddress>
+    <emailSenderName>{siteName}</emailSenderName>
+    <embeddedLoginEnabled>false</embeddedLoginEnabled>
+    <enableApexCDNCaching>true</enableApexCDNCaching>
+    <enableCustomVFErrorPageOverrides>false</enableCustomVFErrorPageOverrides>
+    <enableDirectMessages>true</enableDirectMessages>
+    <enableExpFriendlyUrlsAsDefault>false</enableExpFriendlyUrlsAsDefault>
+    <enableExperienceBundleBasedSnaOverrideEnabled>true</enableExperienceBundleBasedSnaOverrideEnabled>
+    <enableGuestChatter>{enableGuestAccess}</enableGuestChatter>
+    <enableGuestFileAccess>false</enableGuestFileAccess>
+    <enableGuestMemberVisibility>false</enableGuestMemberVisibility>
+    <enableImageOptimizationCDN>true</enableImageOptimizationCDN>
+    <enableInvitation>false</enableInvitation>
+    <enableKnowledgeable>false</enableKnowledgeable>
+    <enableLWRExperienceConnectedApp>false</enableLWRExperienceConnectedApp>
+    <enableMemberVisibility>false</enableMemberVisibility>
+    <enableNicknameDisplay>true</enableNicknameDisplay>
+    <enablePrivateMessages>false</enablePrivateMessages>
+    <enableReputation>false</enableReputation>
+    <enableShowAllNetworkSettings>false</enableShowAllNetworkSettings>
+    <enableSiteAsContainer>true</enableSiteAsContainer>
+    <enableTalkingAboutStats>true</enableTalkingAboutStats>
+    <enableTopicAssignmentRules>true</enableTopicAssignmentRules>
+    <enableTopicSuggestions>false</enableTopicSuggestions>
+    <enableUpDownVote>false</enableUpDownVote>
+    <forgotPasswordTemplate>unfiled$public/CommunityForgotPasswordEmailTemplate</forgotPasswordTemplate>
+    <gatherCustomerSentimentData>false</gatherCustomerSentimentData>
+    <headlessForgotPasswordTemplate>unfiled$public/CommunityHeadlessForgotPasswordTemplate</headlessForgotPasswordTemplate>
+    <headlessRegistrationTemplate>unfiled$public/CommunityHeadlessRegistrationTemplate</headlessRegistrationTemplate>
+    <networkMemberGroups>
+        <profile>admin</profile>
+    </networkMemberGroups>
+    <networkPageOverrides>
+        <changePasswordPageOverrideSetting>Standard</changePasswordPageOverrideSetting>
+        <forgotPasswordPageOverrideSetting>Designer</forgotPasswordPageOverrideSetting>
+        <homePageOverrideSetting>Designer</homePageOverrideSetting>
+        <loginPageOverrideSetting>Designer</loginPageOverrideSetting>
+        <selfRegProfilePageOverrideSetting>Designer</selfRegProfilePageOverrideSetting>
+    </networkPageOverrides>
+    <newSenderAddress>admin@company.com</newSenderAddress>
+    <picassoSite>{siteName}1</picassoSite>
+    <selfRegistration>false</selfRegistration>
+    <sendWelcomeEmail>true</sendWelcomeEmail>
+    <site>{siteName}</site>
+    <siteArchiveStatus>NotArchived</siteArchiveStatus>
+    <status>Live</status>
+    <tabs>
+        <defaultTab>home</defaultTab>
+        <standardTab>Chatter</standardTab>
+    </tabs>
+    <urlPathPrefix>{siteUrlPathPrefix}vforcesite</urlPathPrefix>
+    <welcomeTemplate>unfiled$public/CommunityWelcomeEmailTemplate</welcomeTemplate>
+</Network>
+```

package/skills/{salesforce-flexipage → generating-flexipage}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: salesforce-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.
+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."
 ---
 
 ## When to Use This Skill
@@ -149,6 +149,68 @@ Every fieldInstance requires:
 - Must have `fieldInstanceProperties` with `uiBehavior`
 - Use `Record.{Field}` format
 
+### 5. Unique Identifiers and Region Names (CRITICAL - PREVENTS DUPLICATE ERRORS)
+
+**EVERY identifier and region/facet name MUST be unique across the entire FlexiPage file.**
+
+**Critical Rules:**
+- ❌ **NEVER create two `<flexiPageRegions>` blocks with the same `<name>`**
+- ✅ **If multiple components belong to same facet, combine them in ONE region with multiple `<itemInstances>`**
+- ❌ **NEVER reuse the same `<identifier>` value**
+- ✅ **Always read entire file first and extract ALL existing identifiers and names**
+
+**Wrong - This WILL FAIL with duplicate name error:**
+```xml
+<!-- First field section in detail tab -->
+<flexiPageRegions>
+   <itemInstances>
+      <componentInstance>
+         <identifier>flexipage_property_details_fieldSection</identifier>
+         ...
+      </componentInstance>
+   </itemInstances>
+   <name>detailTabContent</name>  <!-- ❌ DUPLICATE NAME -->
+   <type>Facet</type>
+</flexiPageRegions>
+
+<!-- Second field section in detail tab -->
+<flexiPageRegions>
+   <itemInstances>
+      <componentInstance>
+         <identifier>flexipage_pricing_fieldSection</identifier>
+         ...
+      </componentInstance>
+   </itemInstances>
+   <name>detailTabContent</name>  <!-- ❌ DUPLICATE NAME - DEPLOYMENT FAILS -->
+   <type>Facet</type>
+</flexiPageRegions>
+```
+
+**Correct - Combine itemInstances in ONE region:**
+```xml
+<!-- Both field sections in same detail tab facet -->
+<flexiPageRegions>
+   <itemInstances>
+      <componentInstance>
+         <identifier>flexipage_property_details_fieldSection</identifier>
+         ...
+      </componentInstance>
+   </itemInstances>
+   <itemInstances>
+      <componentInstance>
+         <identifier>flexipage_pricing_fieldSection</identifier>
+         ...
+      </componentInstance>
+   </itemInstances>
+   <name>detailTabContent</name>  <!-- ✅ ONE REGION, MULTIPLE COMPONENTS -->
+   <type>Facet</type>
+</flexiPageRegions>
+```
+
+**When to combine vs separate:**
+- **Combine**: Components that logically belong to same tab/section (e.g., multiple field sections in detail tab)
+- **Separate**: Components that belong to different tabs/sections (e.g., `detailTabContent` vs `relatedTabContent`)
+
 ---
 
 ## Common Deployment Errors
@@ -178,7 +240,7 @@ Every fieldInstance requires:
 **Fix:** Use "Volunteer_Record_Page" not "Volunteer__c_Record_Page"
 
 ### "Region specifies mode that parent doesn't support"
-**Cause:** Added `<mode>` tag to region  
+**Cause:** Added `<mode>` tag to region
 **Fix:** Remove `<mode>` tags - they're not needed for standard regions
 
 ---
@@ -211,21 +273,28 @@ When user provides an existing FlexiPage file path:
 
 1. **Read the file** using native file I/O
 2. **Parse XML** to extract:
-   - Existing component identifiers
+   - **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. **Generate component XML** (apply all rules from "Critical XML Rules" section)
-4. **Insert** into appropriate region
-5. **Write** modified XML back to file
-6. **Deploy**: `sf project deploy start --source-dir force-app/...`
+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
 
-**Algorithm**:
+**CRITICAL: Before generating ANY new identifier or facet name, follow the rules in section 5 of "Critical XML Rules" above.**
+
+**Identifier Generation Algorithm**:
 ```
-1. Extract all existing <identifier> values from XML
+1. Extract ALL existing <identifier> AND <name> values from XML
 2. Generate base name: {componentType}_{context}
    Examples: "relatedList_contacts", "richText_header", "tabs_main"
 3. Find first available number:
@@ -253,6 +322,11 @@ When user provides an existing FlexiPage file path:
    - Example: `Facet-66d5a4b3-bf14-4665-ba75-1ceaa71b2cde`
    - Use for field section columns, nested containers, anonymous slots
 
+**When adding components to existing files:**
+- Check if target facet name already exists
+- If exists: Add new `<itemInstances>` to that existing region (see section 5 above for details)
+- If doesn't exist: Create new region with unique name
+
 ---
 
 ### Region Selection
@@ -401,6 +475,9 @@ Identifier Pattern: flexipage_richText or flexipage_richText_{sequence}
 
 Before deploying:
 - [ ] Used CLI to bootstrap (don't start 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
 - [ ] All field references use `Record.{Field}` format
 - [ ] Each fieldInstance has `fieldInstanceProperties` with `uiBehavior`
 - [ ] Each fieldInstance in own `<itemInstances>` wrapper

package/skills/{salesforce-flow → generating-flow}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: salesforce-flow
-description: Generate Salesforce Flows using the MCP tool execute_metadata_action. Use when the user asks to create, build, or generate a flow — including Screen, Autolaunched, Record-Triggered (before/after-save), Scheduled. Also trigger for flow-like requests such as "when a record is created", "trigger daily at", "send an email when", "update the field when", "automate", "workflow", or "flow XML/metadata". This is the only skill for Salesforce Flow generation.
+name: generating-flow
+description: "Generate Salesforce Flows using the MCP tool execute_metadata_action. Use when the user asks to create, build, or generate a flow — including Screen, Autolaunched, Record-Triggered (before/after-save), Scheduled. Also trigger for flow-like requests such as \"when a record is created\", \"trigger daily at\", \"send an email when\", \"update the field when\", \"automate\", \"workflow\", or \"flow XML/metadata\". This is the only skill for Salesforce Flow generation."
 ---
 
 ## Goal

package/skills/{salesforce-fragment → generating-fragment}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: salesforce-fragment
-description: Use this skill when users need to create or edit Salesforce Fragments (reusable UI pieces). Trigger when users mention fragments, UEM blocks, reusable UI templates, structured rendering across Slack/Mobile/LEX, or block-based layouts. Also use when users want to create unified experience components. Always use this skill for any fragment work.
+name: generating-fragment
+description: "Use this skill when users need to create or edit Salesforce Fragments (reusable UI pieces). Trigger when users mention fragments, UEM blocks, reusable UI templates, structured rendering across Slack/Mobile/LEX, or block-based layouts. Also use when users want to create unified experience components. Always use this skill for any fragment work."
 ---
 
 ## When to Use This Skill