@salesforce/afv-skills 1.29.0 → 1.31.0

package/skills/platform-flexipage-generate/SKILL.md

@@ -1,8 +1,12 @@
 ---
 name: platform-flexipage-generate
-description: "Use this skill when users need to create, generate, modify, or validate Salesforce Lightning pages (FlexiPages). Trigger when users mention RecordPage, AppPage, HomePage, Lightning pages, page layouts, adding components to pages, or page customization. Also use when users say things like 'create a Lightning page', 'add a component to a page', 'customize the record page', 'generate a FlexiPage', or when they're working with FlexiPage XML files and need help with components, regions, or deployment errors. Always use this skill for any FlexiPage-related work, even if they just mention 'page' in the context of Salesforce."
+description: "Use this skill when users need to create, generate, modify, or validate Salesforce Lightning pages (FlexiPages). Trigger when users mention RecordPage, AppPage, HomePage, Lightning pages, page layouts, adding components to pages, or page customization. Also use when users say things like 'create a Lightning page', 'add a component to a page', 'customize the record page', 'generate a FlexiPage', or when they're working with FlexiPage XML files and need help with components, regions, or deployment errors. Always use this skill for any FlexiPage-related work, even if they just mention 'page' in the context of Salesforce. DO NOT TRIGGER when users ask about Visualforce pages, Aura components without FlexiPage context, page layout assignments in the UI, or Lightning Web Component development that does not involve placing components on a FlexiPage."
+allowed-tools: Bash Read Write
 metadata:
-  version: "1.0"
+  version: "1.1"
+  cliTools:
+    - tool: ["sf"]
+      semver: ">=2.126.4"
 ---
 
 ## When to Use This Skill
@@ -18,8 +22,6 @@ Use this skill when you need to:
 
 ## Specification
 
-# FlexiPage Generation Guide
-
 ## Overview
 
 **CRITICAL: When creating NEW FlexiPages, you MUST ALWAYS start with the CLI template command.** Never create FlexiPage XML from scratch - the CLI provides valid structure, proper regions, and correct component configuration that prevents deployment errors.
@@ -34,6 +36,8 @@ Generate Lightning pages (RecordPage, AppPage, HomePage) using CLI bootstrapping
 
 **MANDATORY FOR NEW PAGES: This step is NOT optional.** Always use the CLI template command when creating a new FlexiPage. The CLI generates valid XML structure, proper regions, and correct metadata that prevents common deployment errors. Only skip this step if you're editing an existing FlexiPage file.
 
+**`<packageDirectory>`** = the `path` value from `sfdx-project.json` → `packageDirectories[0]` (e.g., `force-app`). Read it from the project file before running commands.
+
 ```bash
 sf template generate flexipage \
   --name <PageName> \
@@ -42,7 +46,7 @@ sf template generate flexipage \
   --primary-field <Field1> \
   --secondary-fields <Field2,Field3> \
   --detail-fields <Field4,Field5,Field6,Field7> \
-  --output-dir force-app/main/default/flexipages
+  --output-dir <packageDirectory>/main/default/flexipages
 ```
 
 **CRITICAL:** If the `sf template generate flexipage` command fails, **STOP**.
@@ -84,439 +88,370 @@ Do NOT continue to Step 2 until the template command succeeds. The generated XML
 
 ### Step 2: Deploy Base Page
 
-Run a **dry-run** deployment of the entire project to validate the page and dependencies:
+Run a **dry-run** deployment to validate the page and dependencies (use the default package directory from `sfdx-project.json`):
 ```bash
-sf project deploy start --dry-run -d "force-app/main/default" --test-level NoTestRun --wait 10 --json
+sf project deploy start --dry-run -d "<packageDirectory>/main/default" --test-level NoTestRun --wait 10 --json
 ```
 
 **Critical:** Fix any deployment errors before proceeding. The page must validate successfully.
 
-### Step 3: **STOP - No Further Modifications**
+### Step 3: Add Components Dynamically (if requested)
 
-**MANDATORY: Stop after Step 2. Do not add components or edit the FlexiPage XML.**
+After the base page deploys successfully, if the user wants additional components, follow the **Adding Components Dynamically** workflow below. All component additions MUST go through the discovery and inference pipeline — never write component XML from memory alone.
 
-This applies even if the user requested:
-- Additional components
-- Page customization
-- Component configuration
+---
 
-What you CAN do:
-- Suggest what components would be useful
-- Explain what enhancements are possible
-- Document what would need to be added manually
+## Critical XML Rules
 
-What you CANNOT do:
-- Modify the XML file
-- Add any components
-- Make any enhancements
+**Read `references/xml_rules.md`** for all XML encoding rules, field reference format, region/facet types, fieldInstance structure, unique identifier requirements, and common deployment error resolutions.
+
+**Key rules (quick reminder):**
+- Encode HTML in `<value>` tags: `&` first, then `<`, `>`, `"`, `'`
+- Field references: `Record.{FieldApiName}` (never `Object.Field`)
+- Every `<identifier>` and region `<name>` must be unique across the file
+- Multiple components in same facet → combine in ONE region with multiple `<itemInstances>`
 
 ---
 
-## Critical XML Rules
+### Identifiers, Regions, and Containers
 
-### 1. Property Value Encoding (MOST COMMON ERROR)
+**Read `references/identifiers_and_regions.md`** for the identifier generation algorithm, facet naming patterns (named vs UUID), region selection rules, and container component facet structure.
 
-**Any property value with HTML/XML characters MUST be manually encoded in the following order** (wrong order causes double-encoding corruption):
+---
 
-```
-1. & → &amp;   (FIRST! Encode this before others)
-2. < → &lt;
-3. > → &gt;
-4. " → &quot;
-5. ' → &apos;
-```
+## Component-Specific Tips
 
-**Wrong:**
-```xml
-<value><b>Important</b> text</value>
-```
+### dynamicHighlights (RecordPage Header)
+**Location:** `header` region only. See `references/record_flexipage_dynamicHighlights.md` for full structure.
+CLI generates Facets automatically from `--primary-field` and `--secondary-fields`.
+
+### fieldSection
+**Use for:** Displaying fields in columns. Three-level nesting: Region → Column Facets → Field Facets.
+See `references/flexipage_fieldSection.md` for full structure and XML example.
+**Critical:** The `columns` property value is a Facet name, not a number.
+
+### richText
+See `references/flexipage_richText.md` for encoding rules and XML structure.
+Identifier: `flexipage_richText` or `flexipage_richText_{N}`
+
+---
+## Required Metadata Structure
 
-**Correct:**
 ```xml
-<value>&lt;b&gt;Important&lt;/b&gt; text</value>
+<FlexiPage xmlns="http://soap.sforce.com/2006/04/metadata">
+   <flexiPageRegions>
+      <!-- Regions and components here -->
+   </flexiPageRegions>
+   <masterLabel>Page Label</masterLabel>
+   <template>
+      <name>flexipage:recordHomeTemplateDesktop</name>
+   </template>
+   <type>RecordPage</type>
+   <sobjectType>Object__c</sobjectType> <!-- RecordPage only -->
+</FlexiPage>
 ```
 
-**Check your XML:** Search for `<value>` tags - they should never contain raw `<` or `>` characters.
+**Page Types:**
+- `RecordPage` - requires `<sobjectType>`
+- `AppPage` - no sobjectType
+- `HomePage` - no sobjectType
 
-### 2. Field References
+---
 
-**ALWAYS:** `Record.{FieldApiName}`  
-**NEVER:** `{ObjectName}.{FieldApiName}`
+## Validation Checklist
 
-```xml
-<!-- Correct -->
-<fieldItem>Record.Name</fieldItem>
+### Structure (new pages)
+- [ ] Used CLI to bootstrap — never create FlexiPage XML from scratch
 
-        <!-- Wrong -->
-<fieldItem>Account.Name</fieldItem>
-```
+### Identifiers & Regions
+- [ ] All `<identifier>` values unique across entire file
+- [ ] All region/facet `<name>` values unique across entire file
+- [ ] Multiple components in same facet combined in ONE region with multiple `<itemInstances>`
 
-### 3. Region vs Facet Types
+### Field Instances
+- [ ] All field references use `Record.{Field}` format
+- [ ] Each fieldInstance has `fieldInstanceProperties` with `uiBehavior`
+- [ ] Each fieldInstance in its own `<itemInstances>` wrapper
 
-**Template Regions** (header, main, sidebar):
-```xml
-<name>header</name>
-<type>Region</type>
-```
+### Types & Encoding
+- [ ] Template regions use `<type>Region</type>`; component facets use `<type>Facet</type>`
+- [ ] Property values with HTML/XML are entity-encoded
+- [ ] No unnecessary `<mode>` tags (only where component patterns require them)
+- [ ] No `__c` suffix in page names
+- [ ] Each Facet referenced by exactly one component property
 
-**Component Facets** (internal slots like fieldSection columns):
-```xml
-<name>Facet-12345</name>
-<type>Facet</type>
-```
+---
 
-**Rule:** If it's a template region name → `Region`. If it's a component slot → `Facet`.
+## Quick Reference: CLI Command
 
-### 4. fieldInstance Structure
+**Read `references/cli_commands.md`** for full CLI examples (RecordPage, AppPage, HomePage) and available options.
 
-Every fieldInstance requires:
-```xml
-<itemInstances>
-   <fieldInstance>
-      <fieldInstanceProperties>
-         <name>uiBehavior</name>
-         <value>none</value> <!-- none|readonly|required -->
-      </fieldInstanceProperties>
-      <fieldItem>Record.FieldName__c</fieldItem>
-      <identifier>RecordFieldName_cField</identifier>
-   </fieldInstance>
-</itemInstances>
-```
+---
 
-**Rules:**
-- Each fieldInstance in its own `<itemInstances>` wrapper
-- Must have `fieldInstanceProperties` with `uiBehavior`
-- Use `Record.{Field}` format
+## Adding Components Dynamically
 
-### 5. Unique Identifiers and Region Names (CRITICAL - PREVENTS DUPLICATE ERRORS)
+> **MANDATORY WORKFLOW:** ALL component additions to a FlexiPage MUST follow this workflow. Do not write component XML from memory or skip discovery. This applies to standard OOTB components, custom LWC components, and any other component type.
 
-**EVERY identifier and region/facet name MUST be unique across the entire FlexiPage file.**
+### Overview
 
-**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**
+When the user requests components (e.g., "add a related list of contacts and a report"), follow this pipeline:
 
-**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>
+```text
+1. Parse Intent → identify ALL requested components
+2. Discover ALL → batch components through 3-tier discovery
+3. Infer Properties → run 3-step inference for EACH discovered component
+4. Generate XML → produce valid XML for all components together
+5. Validate → check identifiers, regions, property completeness
 ```
 
-**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>
-```
+**Key rule:** Discover ALL components as a batch first (one scan, one MCP call), THEN infer properties for each. Do not invoke discovery steps per-component or interleave discovery and inference.
 
-**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`)
+### Step 1: Parse User Intent
 
----
+Extract every component request from the user's utterance. Examples:
+- "Create Account page with a report and related contacts" → 2 components: report, related list
+- "Add activities, chatter, and a DRL of Cases" → 3 components: activities, chatter, dynamic related list
 
-## Common Deployment Errors
+### Step 2: 3-Tier Component Discovery
 
-### "We couldn't retrieve or load the information on the field"
-**Cause:** Invalid field API name - field doesn't exist on the object or has incorrect spelling
-**Fix:** Use MCP tools or describe commands to discover valid fields, then update the field reference (see Field Selection Rules)
+Complete each tier for ALL components before moving to the next tier — do NOT run Tier 1→2→3 per component:
 
-### "Invalid field reference"
-**Cause:** Used `ObjectName.Field` instead of `Record.Field`  
-**Fix:** Change to `Record.{FieldApiName}`
+| Tier | Source | When | Calls |
+|------|--------|------|-------|
+| **1** | Local workspace scan | Always first — run for ALL components | 0 (local only) |
+| **2** | `discoverUiComponents` MCP action | Single call for all components unresolved after Tier 1 | 1 |
+| **3** | Generate new LWC bundle | Only for components still unresolved after Tier 2 + user confirms | 0 |
 
-### "Element fieldInstance is duplicated"
-**Cause:** Multiple fieldInstances in one itemInstances  
-**Fix:** Each fieldInstance needs its own `<itemInstances>` wrapper
+After Tier 1 completes for all components, collect only the unresolved ones and pass them to Tier 2 in a single MCP call. Only components still unresolved after Tier 2 proceed to Tier 3.
 
-### "Missing fieldInstanceProperties"
-**Cause:** No uiBehavior specified  
-**Fix:** Add `fieldInstanceProperties` with `uiBehavior`
+See **Local Workspace Scanner** and **MCP Action Integration** sections below for details.
 
-### "Unused Facet"
-**Cause:** Facet defined but not referenced by any component  
-**Fix:** Remove Facet or reference it in a component property
+### Step 3: Property Inference (per component)
 
-### "XML parsing error"
-**Cause:** Unencoded HTML/XML in property values  
-**Fix:** Manually encode `<`, `>`, `&`, `"`, `'` in all `<value>` tags
+For EACH discovered component, infer properties using the 3-step strategy:
 
-### "Cannot create component with namespace"
-**Cause:** Invalid page name (don't use `__c` suffix in page names)  
-**Fix:** Use "Volunteer_Record_Page" not "Volunteer__c_Record_Page"
+1. **Fetch schema or read source** — For Tier 2 (org) components, call `getUiComponentSchemas`; for Tier 1 (local), extract `@api` props from source
+2. **Apply component instructions** — If `references/<name>.md` exists, read and follow its inference rules
+3. **Resolve remaining** — Smart defaults → LLM inference → user prompts (last resort)
 
-### "Region specifies mode that parent doesn't support"
-**Cause:** Added `<mode>` tag to region
-**Fix:** Remove `<mode>` tags - they're not needed for standard regions
+See **Hybrid Property Inference Strategy** below for full details.
 
----
+### Step 4: Generate XML
+
+What you CANNOT do:
+- Modify top level structure in the XML file
+- Add any components from memory which is not resolved from 3-Tier Component Discovery
+- Make any enhancements
 
-### Generating Unique Identifiers
+**Read `references/xml_rules.md` before writing any XML.** Follow all element naming and structure rules defined there. 
 
-**CRITICAL: Before generating ANY new identifier or facet name, follow the rules in section 5 of "Critical XML Rules" above.**
+Produce `<itemInstances>` XML for all resolved components:
+- Use `<componentInstanceProperties>` for every property (NOT `<properties>`)
+- Assign unique identifiers across the full set (see references/identifiers_and_regions.md)
+- Insert into appropriate regions (header, main, sidebar, or facets)
+- Follow each component's XML structure from its instructions file or schema
 
-**Identifier Generation Algorithm**:
-```
-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:
-   - Try "{base}_1"
-   - If exists, try "{base}_2", "{base}_3", etc.
-   - Use first available
+### Step 5: Validate
+
+Check the complete FlexiPage for:
+- Identifier uniqueness (no duplicates across entire file)
+- Region validity (components in correct regions)
+- Property completeness (all required properties populated)
+- XML encoding (HTML values entity-encoded)
+- Element name correctness (see references/xml_rules.md §6)
+
+Deploy with dry-run (use default package directory from `sfdx-project.json`):
+```bash
+sf project deploy start --dry-run -d "<packageDirectory>/main/default" --test-level NoTestRun --wait 10 --json
 ```
 
-**Examples**:
-- First contacts related list: `relatedList_contacts_1`
-- Second contacts related list: `relatedList_contacts_2`
-- Rich text in header: `richText_header_1`
-- Field section: `fieldSection_details_1`
+---
+
+## MCP Action Integration
 
-**Facet Naming - Two Patterns**:
+**Read `references/mcp_action_examples.md`** for full input/output examples and parameter tables.
 
-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
+Two MCP actions via `execute_metadata_action`:
 
-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
+| Action | Purpose | When |
+|--------|---------|------|
+| `DISCOVER_UI_COMPONENTS` | Find components for a page type | Tier 2 discovery — single call for all unresolved components |
+| `GET_UI_COMPONENT_SCHEMAS` | Get property schemas | Property inference Step 1 (Tier 2 org components only) |
 
-**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
+**Key conventions:**
+- Component definition format: `namespace/blockName` (forward-slash) in MCP calls, `namespace:blockName` (colon) in XML
+- `pageContext` with `entityName` is required for RECORD_PAGE
+- `getUiComponentSchemas` supports partial failures — check each component's `success` boolean
 
 ---
 
-### Region Selection
+## Local Workspace Scanner
 
-**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
+Scans the local SFDX project for custom LWC components before making any MCP calls (Tier 1 discovery).
 
-**Default placement**: End of target region (after last `<itemInstances>`)
+### Algorithm
 
-**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>
+Run the scanner for each component query (local scan — no network calls):
+
+```bash
+scripts/scan-lwc-components.sh "<query>" [packageDirectory]
 ```
 
----
+The script scans `<packageDirectory>/**/lwc/*/`, tokenizes camelCase component names, scores them against user intent keywords, and returns a JSON array of matches with confidence tiers:
 
-### Container Components with Facets
+- **High confidence (≥70%):** auto-select, confirm with user
+- **Medium confidence (40-69%):** present ranked list for user selection
+- **Low confidence (<40%):** skip, proceed to Tier 2
 
-Components like tabs, accordions, field sections require facets.
+Run Tier 1 for ALL components before moving any to Tier 2. Collect all unresolved components from Tier 1, then pass them to Tier 2 in a single MCP call.
 
-**Pattern**:
-```xml
-<!-- 1. Component in region -->
-<flexiPageRegions>
-   <itemInstances>
-      <componentInstance>
-         <componentName>flexipage:tabset2</componentName>
-         <identifier>tabs_main_1</identifier>
-         <componentInstanceProperties>
-            <name>tabs</name>
-            <value>tab1_content</value>
-            <value>tab2_content</value>
-         </componentInstanceProperties>
-      </componentInstance>
-   </itemInstances>
-   <name>main</name>
-   <type>Region</type>
-</flexiPageRegions>
-
-        <!-- 2. Facets (siblings of region, NOT nested inside) -->
-<flexiPageRegions>
-<itemInstances><!-- Tab 1 content --></itemInstances>
-<name>tab1_content</name>
-<type>Facet</type>
-</flexiPageRegions>
-
-<flexiPageRegions>
-<itemInstances><!-- Tab 2 content --></itemInstances>
-<name>tab2_content</name>
-<type>Facet</type>
-</flexiPageRegions>
-```
+### Disambiguation
+
+For medium-confidence matches (40-69%) or multiple high-confidence matches:
+1. Read each candidate's `.js-meta.xml` for `<description>` and `<targetConfigs>`
+2. Present ranked list to user with component name + description
+3. User selects or says "none of these" (→ proceed to Tier 2)
+
+### When to Skip
+
+Skip local scan when:
+- User explicitly mentions an org-level component ("use the standard report component")
+- User intent clearly maps to a known standard component (DRL, richText, etc.)
+- No `<packageDirectory>` directory exists in the workspace
 
-**Critical**: Facet regions are siblings of template regions at the same level, not nested inside them.
 ---
-## Component-Specific Tips
-### dynamicHighlights (RecordPage Header)
-**Location:** Must be in `header` region.
-**Explicit Fields** (via CLI): Use the most important fields to show a summary of the record. The single primary field is used to identify the record, like a name. The secondary fields (max 12, recommended 6) are used as a summary of the record.
-```bash
---primary-field Name
---secondary-fields Phone,Industry,AnnualRevenue
-```
-CLI generates Facets with field references automatically.
-### fieldSection
-**Use for:** Displaying fields in columns.
-**Structure:** Three-level nesting:
-1. Template Region (Region type)
-2. Column Facets (Facet type)
-3. Field Facets (Facet type)
-   **Referenced in component property:**
-```xml
-<componentInstanceProperties>
-   <name>columns</name>
-   <value>Facet-{uuid}</value>
-</componentInstanceProperties>
-```
 
-### rich Text component
+## Hybrid Property Inference Strategy
 
-Component name: flexipage:richText
+For EACH discovered component, populate its properties using this 3-step strategy in order:
 
-Use for: Displaying HTML-formatted rich text content with support for text formatting, headings, lists, tables, images, links, forms, and multimedia elements. Preserves styling and layout. Escape all special characters in the default text.
+### Step 1: Fetch Latest Schema (conditional)
 
-Location: Can be used in any region on any page type (Home, Record, App, Community pages).
+Call `getUiComponentSchemas` only when the component does **not** exist on the local machine (i.e., Tier 2 org-discovered components). For local components (Tier 1), extract `@api` properties directly from the source code instead.
 
+**When to call:**
+- Tier 2 (org discovery): Always — the schema is the only source of property info
+- Tier 1 (local): Skip — read `@api` properties from the component's `.js` source file
+- Tier 3 (generated): Skip — you just created the source, so properties are already known
 
-CLI generates the component directly without nested structures.
+### Step 2: Apply Component Instructions (if present)
 
-User: "Add a rich text component to force-app/.../Account_Record_Page.flexipage-meta.xml"
+Run `scripts/resolve-component-instructions.sh <namespace:component>` — it returns the instructions file path if it exists, or empty string.
 
-Structure: Single-level component (no facets):
-1. Component instance (flexipage:richText) with direct properties
+Examples:
+- `record_flexipage:dynamicHighlights` → `references/record_flexipage_dynamicHighlights.md`
+- `flexipage:fieldSection` → `references/flexipage_fieldSection.md`
+- `c:expenseTracker` → (empty — no file)
 
-XML Structure Example:
-```xml
-<itemInstances>
-   <componentInstance>
-      <componentInstanceProperties>
-         <name>decorate</name>
-         <value>true</value>
-      </componentInstanceProperties>
-      <componentName>flexipage:richText</componentName>
-      <identifier>flexipage_richText</identifier>
-   </componentInstance>
-</itemInstances>
-```
+If a file is returned: read and follow its inference rules, XML patterns, and defaults.
+If empty: skip directly to Step 3.
+
+Instructions files augment the schema — they provide *how* to derive values from user intent. Any properties in the schema not covered by the instructions file are resolved in Step 3.
+
+### Step 3: Resolve Remaining Properties
+
+For any properties not yet resolved, apply in this priority order:
+
+**3a. Smart Default Heuristics:**
+
+| Property Pattern | Default Value |
+|-----------------|---------------|
+| `recordId` | `{!recordId}` |
+| `objectApiName` / `sObjectName` | Page's `<sobjectType>` value |
+| `show*` / `visible*` / `display*` | `true` |
+| `hide*` / `hidden*` / `disabled*` | `false` |
+| Boolean without prefix | `false` |
+| Schema specifies `"default"` | Use schema default |
+
+**3b. LLM Inference:**
+Use the component schema + user intent + page context to infer reasonable values. Example: user says "report showing top opportunities" → infer `reportName` should reference an opportunities report.
+
+**3c. User Prompts (last resort):**
+Only prompt the user for critical required properties that cannot be inferred. If user says "skip", omit the component entirely.
+
+### Tier-Specific Behavior
 
-Identifier Pattern: flexipage_richText or flexipage_richText_{sequence}
+| Tier | Extra Step | Schema Call | Instructions |
+|------|-----------|-------------|--------------|
+| Tier 1 (local) | Extract `@api` props from source | No (use source) | If exists |
+| Tier 2 (org) | — | Yes | If exists |
+| Tier 3 (generated) | Extract `@api` from just-generated source | No (just created) | No |
 
 ---
-## Required Metadata Structure
 
-```xml
-<FlexiPage xmlns="http://soap.sforce.com/2006/04/metadata">
-   <flexiPageRegions>
-      <!-- Regions and components here -->
-   </flexiPageRegions>
-   <masterLabel>Page Label</masterLabel>
-   <template>
-      <name>flexipage:recordHomeTemplateDesktop</name>
-   </template>
-   <type>RecordPage</type>
-   <sobjectType>Object__c</sobjectType> <!-- RecordPage only -->
-</FlexiPage>
-```
+## New LWC Generation (Tier 3)
 
-**Page Types:**
-- `RecordPage` - requires `<sobjectType>`
-- `AppPage` - no sobjectType
-- `HomePage` - no sobjectType
+When no component is found locally (Tier 1) or in the org (Tier 2), offer to generate a new LWC.
+
+### Trigger Conditions
+
+- Tier 1 and Tier 2 both miss or user rejected all candidates
+- User has not explicitly said "skip" or "don't create"
+
+### Confirmation
+
+Always confirm before creating. Explain: component name. If user declines: skip, continue with other components.
+
+### Post-Generation
+
+After creating the LWC bundle:
+1. Treat as a Tier 1 local component immediately
+2. Extract `@api` properties from the generated source
+3. Apply smart defaults for `recordId` and `objectApiName`
+4. Generate FlexiPage XML with `c:{componentName}` as the componentName
+
+### Naming Convention
+
+- Derive from user intent: "customer health score" → `customerHealthScore`
+- camelCase, no hyphens, no underscores in the JS class name
+- Folder name matches class name (lowercase first letter): `customerHealthScore/`
 
 ---
 
-## Validation Checklist
+## Reference File Index
 
-Before deploying:
-- [ ] **[NEW PAGES ONLY]** Used CLI to bootstrap - NEVER create FlexiPage XML from scratch
-- [ ] **ALL identifiers are unique** - no duplicate `<identifier>` values anywhere in file
-- [ ] **ALL region/facet names are unique** - no duplicate `<name>` values in `<flexiPageRegions>`
-- [ ] **Multiple components in same facet are combined** - ONE region with multiple `<itemInstances>`, NOT separate regions with same name
-- [ ] All field references use `Record.{Field}` format
-- [ ] Each fieldInstance has `fieldInstanceProperties` with `uiBehavior`
-- [ ] Each fieldInstance in own `<itemInstances>` wrapper
-- [ ] Template regions use `<type>Region</type>`
-- [ ] Component facets use `<type>Facet</type>`
-- [ ] Property values with HTML/XML are manually encoded
-- [ ] No `<mode>` tags in regions
-- [ ] No `__c` suffix in page names
-- [ ] Each Facet referenced by exactly one component property
+| File | When to read |
+|------|-------------|
+| `references/xml_rules.md` | Before writing or editing any FlexiPage XML — encoding, field refs, identifiers, deployment errors |
+| `references/identifiers_and_regions.md` | When adding components — identifier algorithm, facet naming, region selection, container pattern |
+| `references/cli_commands.md` | When bootstrapping new pages — full CLI examples for RecordPage, AppPage, HomePage |
+| `references/mcp_action_examples.md` | When calling MCP actions — full input/output JSON for discoverUiComponents and getUiComponentSchemas |
+| `references/flexipage_fieldSection.md` | When adding a Field Section with columns |
+| `references/record_flexipage_dynamicHighlights.md` | When adding a Dynamic Highlights panel |
+| `references/flexipage_richText.md` | When adding a Rich Text component |
+| `scripts/scan-lwc-components.sh` | Tier 1 local workspace scan — tokenizes and scores LWC component names against user query |
+| `scripts/resolve-component-instructions.sh` | Property inference Step 2 — resolves component definition to instructions file path |
+
+**To add a new component pattern:** Create `references/<namespace>_<componentName>.md` following the structure in existing files. The skill automatically checks for the file during Step 2 of property inference.
 
 ---
 
-## Quick Reference: CLI Command
+## Validation Rules for Dynamic Components
 
-```bash
-# RecordPage with fields
-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
-sf template generate flexipage \
-  --name Sales_Dashboard \
-  --template AppPage \
-  --label "Sales Dashboard"
+After generating XML for dynamically added components, verify ALL of the following before deployment:
 
-# HomePage
-sf template generate flexipage \
-  --name Custom_Home \
-  --template HomePage \
-  --description "Custom home for sales team"
-```
+### Identifier Uniqueness
+- Extract ALL `<identifier>` values from the entire FlexiPage file
+- Confirm zero duplicates
+- If conflict: auto-increment suffix (`_2`, `_3`, etc.)
+
+### Region Validity
+- Components placed in correct regions for their type:
+  - `record_flexipage:dynamicHighlights` → `header` only
+  - `flexipage:fieldSection` → `main` or tab facets
+  - `flexipage:richText` → any region
+
+### Property Completeness
+- All properties marked required in schema have values
+- All values match expected types (String, Boolean, valueList, Integer)
+- No raw HTML in `<value>` tags (must be entity-encoded)
+
+### Structural Integrity
+- Every Facet referenced by a component property exists as a `<flexiPageRegions>` block
+- No orphan Facets (every Facet is referenced by exactly one component)
+- Multiple components in same region use ONE `<flexiPageRegions>` block with multiple `<itemInstances>`
 
-**All templates support:**
-- `--output-dir` (default: current directory)
-- `--api-version` (default: latest)
-- `--label` (default: page name)
-- `--description`
+### Cross-Component Consistency
+- For multi-component additions: identifiers are unique across ALL new components
+- Facet UUIDs don't collide between components
+- Components that require singleton placement (dynamicHighlights, recordDetailPanelMobile) are not duplicated