@salesforce/afv-skills 1.29.0 → 1.30.0

package/skills/platform-flexipage-generate/references/cli_commands.md

@@ -0,0 +1,39 @@
+# CLI Command Reference
+
+## RecordPage with fields
+
+```bash
+sf template generate flexipage \
+  --name Account_Custom_Page \
+  --template RecordPage \
+  --sobject Account \
+  --primary-field Name \
+  --secondary-fields Phone,Industry,AnnualRevenue \
+  --detail-fields Street,City,State,Name,Phone,Email
+```
+
+## AppPage
+
+```bash
+sf template generate flexipage \
+  --name Sales_Dashboard \
+  --template AppPage \
+  --label "Sales Dashboard"
+```
+
+## HomePage
+
+```bash
+sf template generate flexipage \
+  --name Custom_Home \
+  --template HomePage \
+  --description "Custom home for sales team"
+```
+
+## Common Options
+
+All templates support:
+- `--output-dir` (default: current directory)
+- `--api-version` (default: latest)
+- `--label` (default: page name)
+- `--description`

package/skills/platform-flexipage-generate/references/flexipage_fieldSection.md

@@ -0,0 +1,162 @@
+# flexipage:fieldSection — Field Section
+
+## Purpose
+
+Displays fields in a column layout under a labeled section heading.
+
+## Supported Page Types
+
+- RecordPage (`main` region or detail tab facets)
+
+## Structure
+
+Three-level nesting:
+1. Template Region (Region type) — contains the fieldSection component
+2. Column Facets (Facet type) — contains `flexipage:column` components pointing to field facets
+3. Field Facets (Facet type) — contains `fieldInstance` elements for each column
+
+**Critical:** The `columns` property value must match the `<name>` of the facet where the `flexipage:column` components are defined. It is *not* a number.
+
+## Property Table
+
+| Property | Type | Required | Default | Description |
+|----------|------|----------|---------|-------------|
+| columns | String (Facet ref) | Yes | — | Reference to the Facet containing `flexipage:column` components |
+| label | String | Yes | — | Section heading displayed to users |
+| horizontalAlignment | Boolean | No | false | Align fields horizontally within columns |
+
+## Property Inference Rules
+
+| User Intent | Inferred Properties |
+|-------------|-------------------|
+| "add a field section with {fields}" | Split fields evenly across 2 columns |
+| "section labeled {name}" | `label` = `{name}` |
+
+## XML Example
+
+```xml
+<!-- Field facet for first column -->
+<flexiPageRegions>
+   <itemInstances>
+      <fieldInstance>
+            <fieldInstanceProperties>
+               <name>uiBehavior</name>
+               <value>required</value>
+            </fieldInstanceProperties>
+            <fieldItem>Record.Field0</fieldItem>
+            <identifier>RecordColumn1Field0</identifier>
+      </fieldInstance>
+   </itemInstances>
+   <itemInstances>
+      <fieldInstance>
+            <fieldInstanceProperties>
+               <name>uiBehavior</name>
+               <value>none</value>
+            </fieldInstanceProperties>
+            <fieldItem>Record.Field1</fieldItem>
+            <identifier>RecordColumn1Field1</identifier>
+      </fieldInstance>
+   </itemInstances>
+   <name>Facet-FieldSection-Column1</name>
+   <type>Facet</type>
+</flexiPageRegions>
+
+<!-- Field facet for second column -->
+<flexiPageRegions>
+   <itemInstances>
+      <fieldInstance>
+            <fieldInstanceProperties>
+               <name>uiBehavior</name>
+               <value>none</value>
+            </fieldInstanceProperties>
+            <fieldItem>Record.Field2</fieldItem>
+            <identifier>RecordColumn2Field0</identifier>
+      </fieldInstance>
+   </itemInstances>
+   <itemInstances>
+      <fieldInstance>
+            <fieldInstanceProperties>
+               <name>uiBehavior</name>
+               <value>none</value>
+            </fieldInstanceProperties>
+            <fieldItem>Record.Type</fieldItem>
+            <identifier>RecordColumn2Field1</identifier>
+      </fieldInstance>
+   </itemInstances>
+   <name>Facet-FieldSection-Column2</name>
+   <type>Facet</type>
+</flexiPageRegions>
+
+<!-- Columns facet -->
+<flexiPageRegions>
+   <itemInstances>
+      <componentInstance>
+            <componentInstanceProperties>
+               <name>body</name>
+               <value>Facet-FieldSection-Column1</value>
+            </componentInstanceProperties>
+            <componentName>flexipage:column</componentName>
+            <identifier>flexipage_column1</identifier>
+      </componentInstance>
+   </itemInstances>
+   <itemInstances>
+      <componentInstance>
+            <componentInstanceProperties>
+               <name>body</name>
+               <value>Facet-FieldSection-Column2</value>
+            </componentInstanceProperties>
+            <componentName>flexipage:column</componentName>
+            <identifier>flexipage_column2</identifier>
+      </componentInstance>
+   </itemInstances>
+   <name>Facet-FieldSection-Columns</name>
+   <type>Facet</type>
+</flexiPageRegions>
+
+<!-- Template region with fieldSection component -->
+<flexiPageRegions>
+   <itemInstances>
+      <componentInstance>
+            <componentInstanceProperties>
+               <name>columns</name>
+               <value>Facet-FieldSection-Columns</value>
+            </componentInstanceProperties>
+            <componentInstanceProperties>
+               <name>horizontalAlignment</name>
+               <value>false</value>
+            </componentInstanceProperties>
+            <componentInstanceProperties>
+               <name>label</name>
+               <value>Information</value>
+            </componentInstanceProperties>
+            <componentName>flexipage:fieldSection</componentName>
+            <identifier>flexipage_fieldSection</identifier>
+      </componentInstance>
+   </itemInstances>
+   <name>main</name>
+   <type>Region</type>
+</flexiPageRegions>
+```
+
+## uiBehavior Attribute
+
+Every `fieldInstance` requires a `uiBehavior` property that controls field editability on the page.
+
+| Value | Meaning | When to use |
+|-------|---------|-------------|
+| `none` | Field respects standard editability settings (default) | Standard fields — uses object/layout-level permissions |
+| `required` | Field is required — must be filled before save | Fields that must have a value for the record to be valid |
+| `readonly` | Field is read-only — displayed but not editable | Formula fields, system fields, or fields locked by business rules |
+
+**Inference rules:**
+- Default to `none` unless the user specifies otherwise
+- If user says "required" or "mandatory" → use `required`
+- If user says "read-only", "display only", or "locked" → use `readonly`
+- Formula fields and auto-number fields should always be `readonly`
+
+## Edge Cases
+
+- `columns` property is a Facet name, not a count — common mistake
+- Split fields roughly evenly across columns
+- Identifiers: `flexipage_fieldSection`, `flexipage_fieldSection2`; columns: `flexipage_column1`, `flexipage_column2`
+- Second fieldSection on same page: all facet names and identifiers must be unique

package/skills/platform-flexipage-generate/references/flexipage_richText.md

@@ -0,0 +1,84 @@
+# flexipage:richText — Rich Text
+
+## Purpose
+
+Displays HTML-formatted rich text content on a page. Supports text formatting, headings, lists, links, and inline styles. Content is static (not data-bound).
+
+## Supported Page Types
+
+- RecordPage
+- AppPage
+- HomePage
+
+## Property Table
+
+| Property | Type | Required | Default | Description |
+|----------|------|----------|---------|-------------|
+| richTextValue | String (HTML-encoded) | Yes | — | HTML content, entity-encoded for XML |
+| decorate | Boolean | No | true | Show card-style border/decoration around the content |
+
+## Property Inference Rules
+
+| User Intent | Inferred Properties |
+|-------------|-------------------|
+| "add rich text with {content}" | `richTextValue` = HTML-encoded version of content |
+| "add a heading {text}" | `richTextValue` = `<p><b style="font-size: 16px;">{text}</b></p>` |
+| "add a link to {url}" | `richTextValue` = `<p><a href="{url}" rel="noopener noreferrer" target="_blank">{text}</a></p>` |
+| "no border" or "borderless" | `decorate` = `false` |
+| "with card border" or "in a card" | `decorate` = `true` |
+
+## HTML Encoding Rules
+
+**CRITICAL:** The `richTextValue` must be double-encoded for XML:
+1. Write the desired HTML content
+2. Entity-encode ALL HTML characters:
+   - `&` -> `&` (encode FIRST)
+   - `<` -> `&lt;`
+   - `>` -> `&gt;`
+   - `"` -> `&quot;`
+
+**Example:** To display `<b>Hello</b>`, the value must be `&lt;b&gt;Hello&lt;/b&gt;`
+
+**Supported HTML tags:**
+- `<p>` — paragraphs (required wrapper for all content)
+- `<b>` — bold
+- `<u>` — underline
+- `<i>` — italic
+- `<a href="..." rel="noopener noreferrer" target="_blank">` — links
+- `<span style="...">` — inline styling
+- `<br>` or `<br />` — line breaks
+
+**Supported inline styles:**
+- `font-size: Npx` (e.g., `12px`, `14px`, `16px`, `18px`)
+- `color: #hex` or `color: colorname`
+- `text-align: left|center|right`
+- `background-color: #hex`
+
+## XML Example
+
+```xml
+<itemInstances>
+    <componentInstance>
+        <componentInstanceProperties>
+            <name>richTextValue</name>
+            <value>&lt;p style=&quot;text-align: center;&quot;&gt;&lt;b style=&quot;font-size: 16px;&quot;&gt;Welcome to the Account Page&lt;/b&gt;&lt;/p&gt;&lt;p&gt;Use this page to manage account details and related records.&lt;/p&gt;</value>
+        </componentInstanceProperties>
+        <componentInstanceProperties>
+            <name>decorate</name>
+            <value>true</value>
+        </componentInstanceProperties>
+        <componentName>flexipage:richText</componentName>
+        <identifier>flexipage_richText</identifier>
+    </componentInstance>
+</itemInstances>
+```
+
+## Edge Cases
+
+- Never put raw HTML in `<value>` tags — always entity-encode
+- Encode `&` FIRST before encoding `<` and `>` to avoid double-encoding `&amp;lt;`
+- Multiple rich text components on same page: increment identifier (`flexipage_richText`, `flexipage_richText2`)
+- Empty content is invalid — always include at least one `<p>` element
+- Links must include `rel="noopener noreferrer" target="_blank"` for security
+- Can be placed in any region
+- Keep content concise — rich text is for static labels/instructions, not data display

package/skills/platform-flexipage-generate/references/identifiers_and_regions.md

@@ -0,0 +1,167 @@
+# Identifiers, Regions, and Container Facets
+
+## Generating Unique Identifiers
+
+**Before generating ANY new identifier or facet name, read the existing XML and extract all `<identifier>` and `<name>` values first.**
+
+**Identifier Generation Algorithm**:
+```text
+1. Extract ALL existing <identifier> AND <name> values from XML
+2. Generate base name: {namespace}_{componentType}_{context}
+   Examples: "lst_relatedList_contacts", "flexipage_richText_header"
+3. Find first available number:
+   - Try "{base}_1"
+   - If exists, try "{base}_2", "{base}_3", etc.
+   - Use first available
+```
+
+**Examples**:
+- First related list: `lst_relatedList_contacts`
+- Second related list: `lst_relatedList_contacts_2`
+- First rich text: `flexipage_richText_header`
+- Second rich text: `flexipage_richText_header_2`
+- Field section: `flexipage_fieldSection`
+
+**Facet Naming - Two Patterns**:
+
+1. **Named facets** (for major content areas):
+   - `detailTabContent` (detail tab content)
+   - `maintabs` (main tab container)
+   - `sidebartabs` (sidebar tab container)
+   - Use when facet represents meaningful content area
+
+2. **UUID facets** (for internal structure):
+   - Format: `Facet-{8hex}-{4hex}-{4hex}-{4hex}-{12hex}`
+   - 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 xml_rules.md section 5 for details)
+- If doesn't exist: Create new region with unique name
+
+---
+
+## Region Selection
+
+**Parse regions from file** - don't hardcode names. Templates vary:
+- `flexipage:recordHomeTemplateDesktop` → `header`, `main`, `sidebar`
+- `runtime_service_fieldservice:...` → `header`, `main`, `footer`
+- Others may have different region names
+
+**Default placement**: End of target region (after last `<itemInstances>`)
+
+**Insertion pattern**:
+```xml
+<flexiPageRegions>
+   <name>main</name>  <!-- or whatever region name exists -->
+   <type>Region</type>
+   <itemInstances><!-- Existing component 1 --></itemInstances>
+   <itemInstances><!-- Existing component 2 --></itemInstances>
+   <itemInstances>
+      <!-- INSERT NEW COMPONENT HERE -->
+   </itemInstances>
+</flexiPageRegions>
+```
+
+---
+
+## Container Components with Facets
+
+Components like tabs, accordions, and field sections require a **3-layer facet pattern**. There is NO single "tabs" component — you must use `flexipage:tabset` + `flexipage:tab` + content facets.
+
+**The 3-layer tab pattern:**
+
+```xml
+<!-- LAYER 1: Content facets — one per tab's body -->
+<flexiPageRegions>
+    <itemInstances>
+        <componentInstance>
+            <componentName>force:detailPanel</componentName>
+            <identifier>force_detailPanel1</identifier>
+        </componentInstance>
+    </itemInstances>
+    <name>detailTabContent</name>
+    <type>Facet</type>
+</flexiPageRegions>
+
+<flexiPageRegions>
+    <itemInstances>
+        <componentInstance>
+            <componentInstanceProperties>
+                <name>relatedListComponentOverride</name>
+                <value>NONE</value>
+            </componentInstanceProperties>
+            <componentName>force:relatedListContainer</componentName>
+            <identifier>force_relatedListContainer1</identifier>
+        </componentInstance>
+    </itemInstances>
+    <name>relatedTabContent</name>
+    <type>Facet</type>
+</flexiPageRegions>
+
+<!-- LAYER 2: Tab definitions facet — each flexipage:tab points to a content facet via "body" -->
+<flexiPageRegions>
+    <itemInstances>
+        <componentInstance>
+            <componentInstanceProperties>
+                <name>active</name>
+                <value>true</value>
+            </componentInstanceProperties>
+            <componentInstanceProperties>
+                <name>body</name>
+                <value>detailTabContent</value>
+            </componentInstanceProperties>
+            <componentInstanceProperties>
+                <name>title</name>
+                <value>Standard.Tab.detail</value>
+            </componentInstanceProperties>
+            <componentName>flexipage:tab</componentName>
+            <identifier>flexipage_tab1</identifier>
+        </componentInstance>
+    </itemInstances>
+    <itemInstances>
+        <componentInstance>
+            <componentInstanceProperties>
+                <name>active</name>
+                <value>false</value>
+            </componentInstanceProperties>
+            <componentInstanceProperties>
+                <name>body</name>
+                <value>relatedTabContent</value>
+            </componentInstanceProperties>
+            <componentInstanceProperties>
+                <name>title</name>
+                <value>Standard.Tab.relatedLists</value>
+            </componentInstanceProperties>
+            <componentName>flexipage:tab</componentName>
+            <identifier>flexipage_tab2</identifier>
+        </componentInstance>
+    </itemInstances>
+    <name>maintabs</name>
+    <type>Facet</type>
+</flexiPageRegions>
+
+<!-- LAYER 3: Tabset in the template region — references the tabs facet -->
+<flexiPageRegions>
+    <itemInstances>
+        <componentInstance>
+            <componentInstanceProperties>
+                <name>tabs</name>
+                <value>maintabs</value>
+            </componentInstanceProperties>
+            <componentName>flexipage:tabset</componentName>
+            <identifier>flexipage_tabset1</identifier>
+        </componentInstance>
+    </itemInstances>
+    <name>main</name>
+    <type>Region</type>
+</flexiPageRegions>
+```
+
+**Critical rules:**
+- Facet regions are **siblings** of template regions (same level), NEVER nested inside them
+- Each `flexipage:tab` has `body` pointing to a content facet name, `title` for the label, and `active` (true/false)
+- The `flexipage:tabset` has a single `tabs` property pointing to the tabs facet name
+- Standard tab titles: `Standard.Tab.detail`, `Standard.Tab.relatedLists`, `Standard.Tab.activity`, `Standard.Tab.news`
+- The component is `flexipage:tabset` — NOT `flexipage:tabs`, `flexipage:tabset2`, or `lightning:tabset`

package/skills/platform-flexipage-generate/references/mcp_action_examples.md

@@ -0,0 +1,104 @@
+# MCP Action Integration — Examples & Reference
+
+Two MCP actions provide component discovery and schema retrieval. Call them via `execute_metadata_action`.
+
+## discoverUiComponents
+
+Discovers components available for a page type in the user's org.
+
+**When to call:** Tier 2 discovery — after local scan finds no match.
+
+**Input:**
+```json
+execute_metadata_action({
+  "actionName": "DISCOVER_UI_COMPONENTS",
+  "metadataType": "FLEXI_PAGE",
+  "parameters": {
+    "pageType": "RECORD_PAGE",
+    "pageContext": { "entityName": "Account" },
+    "searchQuery": "related list"
+  }
+})
+```
+
+**Parameters:**
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| pageType | String | Yes | `RECORD_PAGE`, `APP_PAGE`, or `HOME_PAGE` |
+| pageContext | JSON | Conditional | Required for RECORD_PAGE: `{"entityName": "ObjectApiName"}` |
+| searchQuery | String | No | Natural language search from user intent |
+
+**Output:**
+```json
+{
+  "componentDefinitions": [
+    {
+      "definition": "lst/dynamicRelatedList",
+      "label": "Dynamic Related List",
+      "description": "Shows related records...",
+      "attributes": [{"name": "parentFieldApiName", "description": "..."}]
+    }
+  ]
+}
+```
+
+**Notes:**
+- Output uses forward-slash delimiter (`namespace/blockName`), but XML uses colon (`namespace:blockName`)
+- Only returns components compatible with the page type and accessible in the org
+- May return empty list if no match — proceed to Tier 3
+
+**When multiple components are returned:**
+1. **Best-match selection:** If one component clearly matches user intent (label/description aligns with the request), auto-select it
+2. **Ambiguous results:** If multiple components could satisfy the request, present the top candidates to the user with their labels and descriptions, and ask which one to use
+3. **Refinement:** If results are too broad, refine the `searchQuery` parameter with more specific keywords from user intent and retry once before prompting the user
+
+## getUiComponentSchemas
+
+Retrieves the full property schema for one or more components.
+
+**When to call:** Tier 2 (org-discovered) components only — skip for Tier 1 (local) and Tier 3 (generated) components; read @api properties from source instead.
+
+**Input:**
+```json
+execute_metadata_action({
+  "actionName": "GET_UI_COMPONENT_SCHEMAS",
+  "metadataType": "FLEXI_PAGE",
+  "parameters": {
+    "pageType": "RECORD_PAGE",
+    "pageContext": { "entityName": "Account" },
+    "componentDefinitions": ["lst/dynamicRelatedList", "flexipage/richText"],
+    "includeKnowledge": true
+  }
+})
+```
+
+**Parameters:**
+
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| pageType | String | Yes | `RECORD_PAGE`, `APP_PAGE`, or `HOME_PAGE` |
+| pageContext | JSON | Conditional | Required for RECORD_PAGE |
+| componentDefinitions | List | Yes | Component FQNs (forward-slash format) |
+| includeKnowledge | Boolean | No | Include component guidance text (default: true) |
+
+**Output:**
+```json
+{
+  "componentSchemas": [
+    {
+      "definition": "lst/dynamicRelatedList",
+      "success": true,
+      "schema": "{...JSON Schema string...}",
+      "knowledge": "Optional guidance text for this component"
+    }
+  ]
+}
+```
+
+**Notes:**
+- Supports **partial failures** — each component has its own `success` boolean
+- On failure: `{"definition": "...", "success": false, "error": "reason"}`
+- When a component schema fails, fall through to Step 3 (smart defaults + LLM inference)
+- `knowledge` provides platform-curated guidance — use it alongside instructions files
+- Component definition format: always `namespace/blockName` (forward-slash)

package/skills/platform-flexipage-generate/references/record_flexipage_dynamicHighlights.md

@@ -0,0 +1,119 @@
+# record_flexipage:dynamicHighlights — Dynamic Highlights Panel
+
+## Purpose
+
+Displays the record highlights panel at the top of a record page with a primary identifying field, secondary summary fields, and configurable actions. Replaces the older static `force:highlightsPanel`.
+
+## Supported Page Types
+
+- RecordPage only (always in `header` region)
+
+## Property Table
+
+| Property | Type | Required | Default | Description |
+|----------|------|----------|---------|-------------|
+| primaryField | String (Facet ref) | Yes | — | Reference to a Facet containing the primary field (typically Record.Name) |
+| secondaryFields | String (Facet ref) | No | — | Reference to a Facet containing secondary highlight fields |
+| actionNames | valueList | No | — | Actions in the highlights panel: `Edit`, `Delete`, `ChangeOwnerOne`, `Share`, `RecordShareHierarchy` |
+| numVisibleActions | Integer | No | 3 | Number of actions shown before overflow menu |
+
+## Structural Pattern
+
+This component uses an **indirect Facet reference** pattern. The `primaryField` and `secondaryFields` properties point to Facet regions that contain `fieldInstance` elements — they are NOT direct field API names.
+
+**Required supporting structure:**
+1. A Facet region for `primaryField` containing one `fieldInstance` (the identifying field)
+2. A Facet region for `secondaryFields` containing multiple `fieldInstance` elements (summary fields)
+
+## Property Inference Rules
+
+| User Intent | Inferred Properties |
+|-------------|-------------------|
+| "highlights with {fields}" | Create secondaryFields facet with those fields as fieldInstances |
+| "show actions: Edit, Delete" | `actionNames` = valueList with `Edit`, `Delete` |
+| "show {N} actions" | `numVisibleActions` = `{N}` |
+
+**Field selection:** Primary = `Record.Name` (or object's identifying field). Secondary = 4-6 useful fields (max 12). Prefer CLI `--secondary-fields` values if available.
+
+## XML Example
+
+```xml
+<!-- Component in header region -->
+<flexiPageRegions>
+    <itemInstances>
+        <componentInstance>
+            <componentInstanceProperties>
+                <name>actionNames</name>
+                <valueList>
+                    <valueListItems>
+                        <value>Edit</value>
+                    </valueListItems>
+                    <valueListItems>
+                        <value>Delete</value>
+                    </valueListItems>
+                    <valueListItems>
+                        <value>ChangeOwnerOne</value>
+                    </valueListItems>
+                </valueList>
+            </componentInstanceProperties>
+            <componentInstanceProperties>
+                <name>numVisibleActions</name>
+                <value>3</value>
+            </componentInstanceProperties>
+            <componentInstanceProperties>
+                <name>primaryField</name>
+                <value>Facet-primary-field-001</value>
+            </componentInstanceProperties>
+            <componentInstanceProperties>
+                <name>secondaryFields</name>
+                <value>Facet-secondary-fields-001</value>
+            </componentInstanceProperties>
+            <componentName>record_flexipage:dynamicHighlights</componentName>
+            <identifier>record_flexipage_dynamicHighlights</identifier>
+        </componentInstance>
+    </itemInstances>
+    <name>header</name>
+    <type>Region</type>
+</flexiPageRegions>
+
+<!-- Primary field Facet -->
+<flexiPageRegions>
+    <itemInstances>
+        <fieldInstance>
+            <fieldInstanceProperties>
+                <name>uiBehavior</name>
+                <value>none</value>
+            </fieldInstanceProperties>
+            <fieldItem>Record.Name</fieldItem>
+            <identifier>RecordNameField</identifier>
+        </fieldInstance>
+    </itemInstances>
+    <name>Facet-primary-field-001</name>
+    <type>Facet</type>
+</flexiPageRegions>
+
+<!-- Secondary fields Facet (same structure as primary, multiple fieldInstances) -->
+<flexiPageRegions>
+    <itemInstances>
+        <fieldInstance>
+            <fieldInstanceProperties>
+                <name>uiBehavior</name>
+                <value>none</value>
+            </fieldInstanceProperties>
+            <fieldItem>Record.Phone</fieldItem>
+            <identifier>RecordPhoneField</identifier>
+        </fieldInstance>
+    </itemInstances>
+    <name>Facet-secondary-fields-001</name>
+    <type>Facet</type>
+</flexiPageRegions>
+```
+
+## Edge Cases
+
+- Only ONE per page — never multiple instances
+- Always in `header` region — never in `main` or sidebar
+- Facet names must be unique UUIDs or descriptive names
+- Primary field `uiBehavior` is `none`; secondary fields also use `none`
+- If CLI already generated highlights, modify existing — do not add a duplicate
+- Identifier is always `record_flexipage_dynamicHighlights` (singular, never numbered)