@salesforce/afv-skills 1.1.0 → 1.3.0

package/skills/generating-experience-lwr-site/docs/handle-ui-components.md

@@ -0,0 +1,215 @@
+# UI Component Handling
+
+**Use when** adding/configuring components to be used in Experience site.
+
+## Component Insertion
+
+Insert custom Lightning Web Components (LWC) into views.
+
+### What is a Custom Component?
+
+Any LWC in `c` namespace (e.g., `c:heroBanner`). Distinct from OOTB components (e.g., `community_builder:htmlEditor`).
+
+### Prerequisites for Custom LWC
+
+**js-meta.xml Requirements**:
+
+- `<isExposed>true</isExposed>`
+- Targets: `lightningCommunity__Page`, `lightningCommunity__Default`
+
+**Property Type Constraints (MANDATORY GATE)**:
+
+1. **Supported**: String, Integer, Boolean, Color, Picklist
+2. **Unsupported**: Any other type → **STOP immediately**
+   - Do NOT delete, comment, or auto-correct
+   - Advise user to set up Custom Property Editor (CPE) or Custom Property Type
+3. **Type Mismatch**: `type="Number"` → change to `type="Integer"` in js-meta.xml
+
+**Do not proceed** until LWC files are compliant or user advised on CPE/CPT.
+
+### Placement Hierarchy
+
+**NEVER** place components directly in top-level regions. Must nest inside `community_layout:section` → column region.
+
+```
+community_layout:sldsFlexibleLayout (root)
+└── region (content/header/footer)
+    └── community_layout:section
+        └── region (column: col1/col2)
+            └── component(s)
+```
+
+### Column Width & Layout
+
+**12-unit grid**: Column widths sum to 12 per section.
+
+**Width Formats**:
+
+- Grid units: 8 + 4
+- Percentages: 66% + 33% → 8 + 4; 50% + 50% → 6 + 6
+- Ratios: 2:1 → 8 + 4; 1:1 → 6 + 6; equal thirds → 4 + 4 + 4
+
+**Layout Rules**:
+
+- One section = one horizontal row
+- Multiple rows = multiple sections (siblings)
+- Multiple components in column = vertical stack
+
+**Set width in** `sectionConfig` (JSON string attribute on section component).
+
+### sectionConfig Structure
+
+**Top-level** (when parsed):
+
+- `UUID`: Section ID (matches section component's `id`)
+- `columns`: Array of column definitions
+
+**Each column**:
+
+- `UUID`: Column ID (matches column region's `id`)
+- `columnKey`: Column identifier (e.g., `col1`, `col2`) - matches column region's `name`
+- `columnName`: Display name (e.g., "Column 1")
+- `columnWidth`: String from `"1"` to `"12"` (must sum to 12)
+- `seedComponents`: Array or `null` (typically `[]` or `null`)
+
+**Example** (serialized as JSON string in `sectionConfig` attribute):
+
+```json
+{
+  "UUID": "295e6a8b-fd94-485b-af9d-7ccf5b3048ee",
+  "columns": [
+    {
+      "UUID": "7e1f7e33-5ba8-4fef-8494-6ea3e90b22a0",
+      "columnKey": "col1",
+      "columnName": "Column 1",
+      "columnWidth": "12",
+      "seedComponents": null
+    }
+  ]
+}
+```
+
+### Named Region Creation
+In order to create a component with drag-n-droppable region/slot that can be used in Experience Builder sites and persist across views, there are multiple steps needed.
+
+Page layout components should add the lightningCommunity__Page_Layout target in js-meta.xml.
+Theme layout components should add the lightningCommunity__Theme_Layout target in js-meta.xml.
+Add lightningCommunity__Page as a target for page layouts and any component with slots that is not explicitly defined as a theme layout.
+
+The js file in LWC need to declare named slots:
+```js
+/**
+ * @slot header
+ * @slot footer
+ */
+export default class YourComponentName extends LightningElement {}
+```
+
+Do not add any other comments in the declaration comment block. The named @slot annotations must be the last comments
+in the block before the class declaration.
+
+In html, named slots are needed. <slot name="header"> and <slot name="footer"> in the above example.
+
+For theme layout component, a <slot> with no name is the main content region, a slot with name is a sticky region that doesn't change from page to page that uses the same theme layout component.
+
+No need to declare target config properties for the slots/regions.
+See the example below for adding a component with named slots into a view.
+
+### Component Structure
+
+```json
+{
+  "id": "[UNIQUE_UUID]",
+  "type": "component",
+  "definition": "[NAMESPACE]:[COMPONENT_NAME]",
+  "attributes": {
+    "[ATTRIBUTE_NAME]": "[ATTRIBUTE_VALUE]"
+  }
+}
+```
+
+**Field Definitions**:
+
+- `id`: Unique UUID (see `handle-component-and-region-ids.md`)
+- `type`: Always `"component"`
+- `definition`:
+  - Custom LWC: `c:[componentName]` (e.g., `c:heroBanner`)
+  - OOTB: `[namespace]:[componentName]` (e.g., `community_builder:richTextEditor`)
+- `attributes`: Component properties
+  - **Omit if no attributes** (don't include empty object)
+  - Custom LWC: Only `@api` properties in `targetConfigs` (with `lightningCommunity__Default` target)
+  - OOTB: Only exposed schema properties
+
+### Complete Examples
+
+**Example 1: Overall structure**
+Correct nesting: `content` region → section → column region → components
+
+```json
+{
+  "type": "region",
+  "name": "content",
+  "children": [
+    {
+      "attributes": {
+        "sectionConfig": "{\"UUID\":\"295e6a8b-fd94-485b-af9d-7ccf5b3048ee\",\"columns\":[{\"UUID\":\"7e1f7e33-5ba8-4fef-8494-6ea3e90b22a0\",\"columnName\":\"Column 1\",\"columnKey\":\"col1\",\"columnWidth\":\"12\",\"seedComponents\":null}]}"
+      },
+      "children": [
+        {
+          "children": [
+            {
+              "definition": "c:testComponent",
+              "id": "2ae498bd-2871-487d-8fb1-b186376cee3b",
+              "type": "component"
+            },
+            {
+              "id": "7c7d3b6a-1e2f-4a33-9c1e-8b2a6d5f4e3b",
+              "type": "component",
+              "definition": "c:helloWorld",
+              "attributes": {
+                "title": "Hello"
+              }
+            }
+          ],
+          "id": "7e1f7e33-5ba8-4fef-8494-6ea3e90b22a0",
+          "name": "col1",
+          "title": "Column 1",
+          "type": "region"
+        }
+      ],
+      "definition": "community_layout:section",
+      "id": "295e6a8b-fd94-485b-af9d-7ccf5b3048ee",
+      "type": "component"
+    }
+  ]
+}
+```
+
+**CRITICAL**: Follow UUID generation process (`handle-component-and-region-ids.md`) when inserting components.
+
+**Example 2: Representing slots**
+If a component with slots (i.e. @slot annotation) is inserted, slots must appear as named regions.
+In this example the component threeColumn has 3 slots, named left, center, and right.
+```json
+{
+    "attributes" : { },
+    "children" : [ {
+    "id" : "4c6148c7-c07e-4245-ae50-ac07891046f2",
+    "name" : "left",
+    "title" : "left",
+    "type" : "region"
+    }, {
+    "id" : "f362e789-7f09-40b4-a59f-03f76ea73401",
+    "name" : "center",
+    "title" : "center",
+    "type" : "region"
+    }, {
+    "id" : "2678ddd4-a1a4-41c4-bf5a-1a3e55891eb2",
+    "name" : "right",
+    "title" : "right",
+    "type" : "region"
+    } ],
+    "definition" : "c:threeColumn",
+    "id" : "b9e517c5-90ac-49e9-91b7-3730512c95a3",
+    "type" : "component"
+}

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

@@ -0,0 +1,67 @@
+---
+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."
+---
+
+# 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.
+
+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`.
+
+## 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.
+
+| 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 |
+| **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 |
+| **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.
+
+## Generation Workflow
+### Step 1: Resolve All Required Properties
+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.
+
+Create any files and directories that don't already exist, using these paths:
+
+| Metadata Type | Path |
+|--------------|------|
+| Network | `networks/{siteName}.network-meta.xml` |
+| CustomSite | `sites/{siteName}.site-meta.xml` |
+| DigitalExperienceConfig | `digitalExperienceConfigs/{siteName}1.digitalExperienceConfig-meta.xml` |
+| DigitalExperienceBundle | `digitalExperiences/site/{siteName}1/{siteName}1.digitalExperience-meta.xml` |
+| DigitalExperience (sfdc_cms__site) | `digitalExperiences/site/{siteName}1/sfdc_cms__site/{siteName}1/*` |
+
+The DigitalExperience directory contains only `_meta.json` and `content.json`. Do not create any directories other than `sfdc_cms__site` inside the bundle.
+
+### Step 3: Populate All Metadata Fields
+Use the default templates in the docs below. Values in `{braces}` are resolved property references — substitute them with the actual values from Step 1.
+
+| Metadata Type | Template Reference |
+|--------------|-------------------|
+| Network | [configure-metadata-network.md](docs/configure-metadata-network.md) |
+| CustomSite | [configure-metadata-custom-site.md](docs/configure-metadata-custom-site.md) |
+| DigitalExperienceConfig | [configure-metadata-digital-experience-config.md](docs/configure-metadata-digital-experience-config.md) |
+| DigitalExperienceBundle | [configure-metadata-digital-experience-bundle.md](docs/configure-metadata-digital-experience-bundle.md) |
+| DigitalExperience (sfdc_cms__site) | [configure-metadata-digital-experience.md](docs/configure-metadata-digital-experience.md) |
+
+### 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.
+
+## Verification Checklist
+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
+- [ ] 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-custom-site.md

@@ -0,0 +1,41 @@
+# Configure Metadata: CustomSite
+
+## Purpose
+This configuration file creates a **net-new, default** CustomSite metadata record for a Digital Experience React Site. It is not intended to edit or modify an existing CustomSite record. Use this template only when provisioning a brand-new React site.
+
+## File Location
+```
+sites/{siteName}.site-meta.xml
+```
+
+## Default Template
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<CustomSite xmlns="http://soap.sforce.com/2006/04/metadata">
+    <active>true</active>
+    <allowGuestPaymentsApi>false</allowGuestPaymentsApi>
+    <allowHomePage>false</allowHomePage>
+    <allowStandardAnswersPages>false</allowStandardAnswersPages>
+    <allowStandardIdeasPages>false</allowStandardIdeasPages>
+    <allowStandardLookups>false</allowStandardLookups>
+    <allowStandardPortalPages>true</allowStandardPortalPages>
+    <allowStandardSearch>false</allowStandardSearch>
+    <authorizationRequiredPage>CommunitiesLogin</authorizationRequiredPage>
+    <bandwidthExceededPage>BandwidthExceeded</bandwidthExceededPage>
+    <browserXssProtection>true</browserXssProtection>
+    <cachePublicVisualforcePagesInProxyServers>true</cachePublicVisualforcePagesInProxyServers>
+    <clickjackProtectionLevel>SameOriginOnly</clickjackProtectionLevel>
+    <contentSniffingProtection>true</contentSniffingProtection>
+    <enableAuraRequests>true</enableAuraRequests>
+    <fileNotFoundPage>FileNotFound</fileNotFoundPage>
+    <genericErrorPage>Exception</genericErrorPage>
+    <inMaintenancePage>InMaintenance</inMaintenancePage>
+    <indexPage>CommunitiesLanding</indexPage>
+    <masterLabel>{siteName}</masterLabel>
+    <redirectToCustomDomain>false</redirectToCustomDomain>
+    <referrerPolicyOriginWhenCrossOrigin>true</referrerPolicyOriginWhenCrossOrigin>
+    <selfRegPage>CommunitiesSelfReg</selfRegPage>
+    <siteType>ChatterNetwork</siteType>
+    <urlPathPrefix>{siteUrlPathPrefix}vforcesite</urlPathPrefix>
+</CustomSite>
+```

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,5 +1,5 @@
 ---
-name: salesforce-flexipage
+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.
 ---
 
@@ -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, or Platform Event-Triggered Flows. 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
@@ -21,7 +21,7 @@ Use this skill when you need to:
 # Flow Metadata Specification
 
 ## Overview
-Salesforce Flows are powerful automation tools that enable complex business process automation without code. Flows can collect and process data through interactive screens, execute logic and calculations, manipulate records, call external services, and trigger based on various events. Flow types include Screen Flows (user-guided), Autolaunched Flows (background processing), Record-Triggered Flows (database events), Scheduled Flows (time-based), and Platform Event-Triggered Flows (event-driven).
+Salesforce Flows are powerful automation tools that enable complex business process automation without code. Flows can collect and process data through interactive screens, execute logic and calculations, manipulate records, call external services, and trigger based on various events. Flow types include Screen Flows (user-guided), Autolaunched Flows (background processing), Record-Triggered Flows (database events) and Scheduled Flows (time-based).
 
 ## Purpose
 - Automate complex business processes with declarative logic and branching