@salesforce/afv-skills 1.1.0

package/skills/salesforce-custom-field/SKILL.md

@@ -0,0 +1,505 @@
+---
+name: salesforce-custom-field
+description: Use this skill when users need to create, generate, or validate Salesforce Custom Field metadata. Trigger when users mention custom fields, field types, Roll-up Summary fields, Master-Detail relationships, Lookup relationships, formula fields, picklists, or field metadata. Also use when users encounter field deployment errors, especially around Roll-up Summary format, Master-Detail constraints, or formula issues. Always use this skill for any custom field metadata work, field generation, or field troubleshooting.
+---
+
+## When to Use This Skill
+
+Use this skill when you need to:
+- Create custom fields on any object
+- Generate field metadata for any field type
+- Set up relationship fields (Lookup or Master-Detail)
+- Create formula or roll-up summary fields
+- Troubleshoot deployment errors related to custom fields
+
+# Salesforce Custom Field Generator and Validator
+
+## Overview
+
+Generate and validate Salesforce Custom Field metadata with mandatory constraints to prevent deployment errors. This skill has special focus on the **highest-failure-rate field types**: Roll-up Summary and Master-Detail relationships.
+
+## Specification
+
+## 1. Purpose
+
+This document defines the mandatory constraints for generating CustomField metadata XML. The agent must verify these constraints before outputting XML to prevent Metadata API deployment errors.
+
+**Critical Focus Areas:**
+- Roll-up Summary field format errors
+- Master-Detail field attribute restrictions
+- Lookup Filter restrictions
+
+---
+
+## 2. Universal Mandatory Attributes
+
+Every generated field must include these tags:
+
+| Attribute | Requirement | Notes |
+|-----------|-------------|-------|
+| `<fullName>` | Required | Derive from `<label>`: capitalize each word, replace spaces with `_`, append `__c`. Must start with a letter. E.g., label `Total Contract Value` → `Total_Contract_Value__c` |
+| `<label>` | Required | The UI name (Title Case) |
+| `<description>` | Mandatory | State the business "why" behind the field |
+| `<inlineHelpText>` | Mandatory | Provide actionable guidance for the end-user. Must add value beyond the label (e.g., "Enter the value in USD including tax" instead of just "The amount") |
+
+### XML Comments — NEVER Before Root Element
+
+**NEVER place XML comments (`<!-- ... -->`) before the root `<CustomField>` element in metadata XML files.** Comments between the XML declaration and `<CustomField>` cause a `ConversionError` during deployment. Comments inside the root element are safe.
+
+### External ID Configuration
+
+**Trigger:** If the user mentions "integration," "importing data," "external system ID," or "unique key from [System Name]," set `<externalId>true</externalId>`.
+
+**Applicable Types:** Text, Number, Email
+
+---
+
+## 3. Technical Interplay: Precision, Scale, and Length
+
+To ensure deployment success, follow these mathematical constraints:
+
+### Precision vs. Scale Rules
+
+- `precision` is the total digits; `scale` is the decimal digits
+- **Rule:** `precision ≤ 18` AND `scale ≤ precision`
+- **Calculation:** Digits to the left of decimal = `precision - scale`
+
+### The "Fixed 255" Rule
+
+For standard TextArea types, the Metadata API requires `<length>255</length>`, even though it isn't configurable in the UI.
+
+### Visible Lines
+
+Mandatory for Long/Rich text and Multi-select picklists to control UI height.
+
+---
+
+## 4. Field Data Types
+
+### 4.1 Simple Attribute Types
+
+| Type | `<type>` Value | Required Attributes |
+|------|----------------|---------------------|
+| Auto Number | `AutoNumber` | `displayFormat` (must include `{0}`), `startingNumber` |
+| Checkbox | `Checkbox` | Default `defaultValue` to `false` |
+| Date | `Date` | No precision/length required |
+| Date/Time | `DateTime` | No precision/length required |
+| Email | `Email` | Built-in format validation |
+| Lookup Relationship | `Lookup` | `referenceTo`, `relationshipName`, `deleteConstraint` |
+| Master-Detail Relationship | `MasterDetail` | `referenceTo`, `relationshipName`, `relationshipOrder` |
+| Number | `Number` | `precision`, `scale` |
+| Currency | `Currency` | Default precision: 18, scale: 2 |
+| Percent | `Percent` | Default precision: 5, scale: 2 |
+| Phone | `Phone` | Standardizes phone number formatting |
+| Picklist | `Picklist` | `valueSet` with `valueSetDefinition` and `restricted` |
+| Text | `Text` | `length` (Max 255) |
+| Text Area | `TextArea` | `<length>255</length>` |
+| Text (Long) | `LongTextArea` | `length`, `visibleLines` (default 3) |
+| Text (Rich) | `Html` | `length`, `visibleLines` (default 25) |
+| Time | `Time` | Stores time only (no date) |
+| URL | `Url` | Validates for protocol and format |
+
+### 4.2 Computed & Multi-Value Types
+
+| Type | `<type>` Value | Required Attributes |
+|------|----------------|---------------------|
+| Formula | Result type (e.g., `Number`) | `formula`, `formulaTreatBlanksAs` |
+| Roll-Up Summary | `Summary` | See Section 6 for complete requirements |
+| Multi-Select Picklist | `MultiselectPicklist` | `valueSet`, `visibleLines` (default 4) |
+
+### 4.3 Specialized Types
+
+| Type | `<type>` Value | Required Attributes |
+|------|----------------|---------------------|
+| Geolocation | `Location` | `scale`, `displayLocationInDecimal` |
+
+### Picklist `restricted` Rule
+
+The `<restricted>` boolean inside `<valueSet>` controls whether only admin-defined values are allowed.
+
+- IF user does not specify → default to `<restricted>true</restricted>` (restricted, avoids performance issues with large picklist value sets)
+- IF user explicitly says the picklist should allow custom/new values, or mentions "unrestricted" or "open" → set `<restricted>false</restricted>`
+- Restricted picklists are limited to 1,000 total values (active + inactive)
+
+```xml
+<valueSet>
+  <restricted>true</restricted>
+  <valueSetDefinition>
+    <sorted>false</sorted>
+    <value>
+      <fullName>Option_A</fullName>
+      <default>false</default>
+      <label>Option A</label>
+    </value>
+  </valueSetDefinition>
+</valueSet>
+```
+
+---
+
+## 5. Master-Detail Relationship Rules ⭐ CRITICAL
+
+Master-Detail fields have **strict attribute restrictions** that differ from Lookup fields. Violating these rules causes deployment failures.
+
+### Forbidden Attributes on Master-Detail Fields
+
+**NEVER include these attributes on Master-Detail fields:**
+
+| Forbidden Attribute | Why | What Happens |
+|---------------------|-----|--------------|
+| `<required>` | Master-Detail is ALWAYS required by design | Deployment error |
+| `<deleteConstraint>` | Master-Detail ALWAYS cascades deletes | Deployment error |
+| `<lookupFilter>` | Only supported on Lookup fields | Deployment error |
+
+### Master-Detail vs Lookup Comparison
+
+| Attribute | Master-Detail | Lookup |
+|-----------|---------------|--------|
+| `<required>` | ❌ FORBIDDEN | ✅ Optional |
+| `<deleteConstraint>` | ❌ FORBIDDEN (always CASCADE) | ✅ Required (`SetNull`, `Restrict`, `Cascade`) |
+| `<lookupFilter>` | ❌ FORBIDDEN | ✅ Optional |
+| `<relationshipOrder>` | ✅ Required (0 or 1) | ❌ Not applicable |
+| `<reparentableMasterDetail>` | ✅ Optional | ❌ Not applicable |
+| `<writeRequiresMasterRead>` | ✅ Optional | ❌ Not applicable |
+
+### ❌ INCORRECT — Master-Detail with forbidden attributes:
+
+```xml
+<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
+  <fullName>Account__c</fullName>
+  <label>Account</label>
+  <type>MasterDetail</type>
+  <referenceTo>Account</referenceTo>
+  <relationshipName>Contacts</relationshipName>
+  <relationshipOrder>0</relationshipOrder>
+  <required>true</required>           <!-- WRONG: Remove this -->
+  <deleteConstraint>Cascade</deleteConstraint>  <!-- WRONG: Remove this -->
+  <lookupFilter>                       <!-- WRONG: Remove this entire block -->
+    <active>true</active>
+    <filterItems>
+      <field>Account.Type</field>
+      <operation>equals</operation>
+      <value>Customer</value>
+    </filterItems>
+  </lookupFilter>
+</CustomField>
+```
+
+**Errors:**
+- `Master-Detail Relationship Fields Cannot be Optional or Required`
+- `Can not specify 'deleteConstraint' for a CustomField of type MasterDetail`
+- `Lookup filters are only supported on Lookup Relationship Fields`
+
+### ✅ CORRECT — Master-Detail field:
+
+```xml
+<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
+  <fullName>Account__c</fullName>
+  <label>Account</label>
+  <description>Links this record to its parent Account</description>
+  <type>MasterDetail</type>
+  <referenceTo>Account</referenceTo>
+  <relationshipLabel>Child Records</relationshipLabel>
+  <relationshipName>ChildRecords</relationshipName>
+  <relationshipOrder>0</relationshipOrder>
+  <reparentableMasterDetail>false</reparentableMasterDetail>
+  <writeRequiresMasterRead>false</writeRequiresMasterRead>
+  <!-- NO required, deleteConstraint, or lookupFilter -->
+</CustomField>
+```
+
+### ✅ CORRECT — Lookup field (with optional attributes):
+
+```xml
+<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
+  <fullName>Related_Account__c</fullName>
+  <label>Related Account</label>
+  <description>Optional link to a related Account</description>
+  <type>Lookup</type>
+  <referenceTo>Account</referenceTo>
+  <relationshipLabel>Related Records</relationshipLabel>
+  <relationshipName>RelatedRecords</relationshipName>
+  <required>false</required>
+  <deleteConstraint>SetNull</deleteConstraint>
+  <lookupFilter>
+    <active>true</active>
+    <filterItems>
+      <field>Account.Type</field>
+      <operation>equals</operation>
+      <value>Customer</value>
+    </filterItems>
+    <isOptional>false</isOptional>
+  </lookupFilter>
+</CustomField>
+```
+
+### Additional Master-Detail Rules
+
+- **Relationship Order:** First Master-Detail on object = `0`, second = `1`
+- **Relationship Name:** Must be a plural PascalCase string (e.g., `Travel_Bookings`)
+- **Junction Objects:** Use two Master-Detail fields for standard many-to-many (enables Roll-ups)
+- **Limit:** Maximum 2 Master-Detail relationships per object. Use Lookup for additional relationships.
+
+---
+
+## 6. Roll-Up Summary Field Rules ⭐ CRITICAL
+
+Roll-up Summary fields have the **highest deployment failure rate**. Follow these rules exactly.
+
+### Required Elements for Roll-Up Summary
+
+| Element | Requirement | Format |
+|---------|-------------|--------|
+| `<type>` | Required | Always `Summary` |
+| `<summaryOperation>` | Required | `count`, `sum`, `min`, or `max` |
+| `<summaryForeignKey>` | Required | `ChildObject__c.MasterDetailField__c` |
+| `<summarizedField>` | Conditional | Required for `sum`, `min`, `max`. NOT for `count` |
+
+### Forbidden Elements on Roll-Up Summary
+
+**NEVER include these attributes on Roll-Up Summary fields:**
+
+| Forbidden Attribute | Why |
+|---------------------|-----|
+| `<precision>` | Summary inherits from summarized field |
+| `<scale>` | Summary inherits from summarized field |
+| `<required>` | Not applicable to Summary fields |
+| `<length>` | Not applicable to Summary fields |
+
+### Format Rules for summaryForeignKey and summarizedField
+
+**CRITICAL:** Both `summaryForeignKey` and `summarizedField` MUST use the fully qualified format:
+
+```
+ChildObjectAPIName__c.FieldAPIName__c
+```
+
+**Decision Logic:**
+- `summaryForeignKey` = `ChildObject__c.MasterDetailFieldOnChild__c`
+- `summarizedField` = `ChildObject__c.FieldToSummarize__c`
+
+### ❌ INCORRECT — Roll-Up Summary with common errors:
+
+```xml
+<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
+  <fullName>Total_Amount__c</fullName>
+  <label>Total Amount</label>
+  <type>Summary</type>
+  <precision>18</precision>           <!-- WRONG: Remove - inherited from source -->
+  <scale>2</scale>                    <!-- WRONG: Remove - inherited from source -->
+  <summaryOperation>sum</summaryOperation>
+  <summaryForeignKey>Order__c</summaryForeignKey>        <!-- WRONG: Missing field name -->
+  <summarizedField>Amount__c</summarizedField>           <!-- WRONG: Missing object name -->
+</CustomField>
+```
+
+**Errors:**
+- `Can not specify 'precision' for a CustomField of type Summary`
+- `Must specify the name in the CustomObject.CustomField format (e.g. Account.MyNewCustomField)`
+
+### ✅ CORRECT — Roll-Up Summary (SUM operation):
+
+```xml
+<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
+  <fullName>Total_Amount__c</fullName>
+  <label>Total Amount</label>
+  <description>Sum of all line item amounts</description>
+  <inlineHelpText>Automatically calculated from child line items</inlineHelpText>
+  <type>Summary</type>
+  <summaryOperation>sum</summaryOperation>
+  <summarizedField>Order_Line_Item__c.Amount__c</summarizedField>
+  <summaryForeignKey>Order_Line_Item__c.Order__c</summaryForeignKey>
+  <!-- NO precision, scale, required, or length -->
+</CustomField>
+```
+
+### ✅ CORRECT — Roll-Up Summary (COUNT operation):
+
+```xml
+<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
+  <fullName>Line_Item_Count__c</fullName>
+  <label>Line Item Count</label>
+  <description>Count of related line items</description>
+  <inlineHelpText>Automatically calculated from child records</inlineHelpText>
+  <type>Summary</type>
+  <summaryOperation>count</summaryOperation>
+  <summaryForeignKey>Order_Line_Item__c.Order__c</summaryForeignKey>
+  <!-- NO summarizedField needed for COUNT -->
+  <!-- NO precision, scale, required, or length -->
+</CustomField>
+```
+
+### ✅ CORRECT — Roll-Up Summary (MIN operation):
+
+```xml
+<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
+  <fullName>Earliest_Due_Date__c</fullName>
+  <label>Earliest Due Date</label>
+  <description>Earliest due date among all line items</description>
+  <inlineHelpText>Shows the soonest deadline</inlineHelpText>
+  <type>Summary</type>
+  <summaryOperation>min</summaryOperation>
+  <summarizedField>Order_Line_Item__c.Due_Date__c</summarizedField>
+  <summaryForeignKey>Order_Line_Item__c.Order__c</summaryForeignKey>
+</CustomField>
+```
+
+### ✅ CORRECT — Roll-Up Summary (MAX operation):
+
+```xml
+<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
+  <fullName>Highest_Price__c</fullName>
+  <label>Highest Price</label>
+  <description>Maximum unit price among all line items</description>
+  <inlineHelpText>Shows the most expensive item</inlineHelpText>
+  <type>Summary</type>
+  <summaryOperation>max</summaryOperation>
+  <summarizedField>Order_Line_Item__c.Unit_Price__c</summarizedField>
+  <summaryForeignKey>Order_Line_Item__c.Order__c</summaryForeignKey>
+</CustomField>
+```
+
+### Roll-Up Summary Quick Reference
+
+| Operation | summarizedField Required? | Use Case |
+|-----------|---------------------------|----------|
+| `count` | NO | Count number of child records |
+| `sum` | YES | Add up numeric values |
+| `min` | YES | Find smallest value |
+| `max` | YES | Find largest value |
+
+### Roll-Up Summary Prerequisites
+
+- Roll-Up Summary fields can ONLY be created on the **parent** object in a Master-Detail relationship
+- The child object MUST have a Master-Detail field pointing to this parent
+- The summarized field must exist on the child object
+
+---
+
+## 7. Formula Field Rules
+
+### Formula Result Types
+
+A Formula is not a type itself. The `<formula>` tag is added to a field whose `<type>` is set to the **result data type**:
+- `Checkbox`, `Currency`, `Date`, `DateTime`, `Number`, `Percent`, `Text`
+
+### Formula XML Generation Rules
+
+- The contents of the `<formula>` tag MUST be wrapped in a `<![CDATA[ ... ]]>` section. This prevents the XML parser from interpreting formula operators (like `&`, `<`, `>`) as XML markup.
+- If the formula text itself contains the literal sequence `]]>`, escape it by breaking the CDATA block: e.g., `<![CDATA[Text_Field__c & "]]]]><![CDATA[>"]]>`
+- NEVER use an attribute or tag named `returnType`. This does not exist in the Metadata API. The `<type>` tag defines the return data type of the formula result.
+
+### formulaTreatBlanksAs Rule
+
+**Decision Logic:**
+- IF formula result type = `Number`, `Currency`, or `Percent` → set `<formulaTreatBlanksAs>BlankAsZero</formulaTreatBlanksAs>`
+- IF formula result type = `Text`, `Date`, or `DateTime` → set `<formulaTreatBlanksAs>BlankAsBlank</formulaTreatBlanksAs>`
+
+### ❌ INCORRECT — Using Formula as type:
+
+```xml
+<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
+  <fullName>Calculated_Value__c</fullName>
+  <type>Formula</type>  <!-- WRONG: Formula is not a valid type -->
+  <returnType>Number</returnType>  <!-- WRONG: returnType does not exist in Metadata API -->
+  <formula>Field1__c + Field2__c</formula>  <!-- WRONG: Missing CDATA wrapper -->
+</CustomField>
+```
+
+### ✅ CORRECT — Formula field:
+
+```xml
+<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
+  <fullName>Calculated_Value__c</fullName>
+  <label>Calculated Value</label>
+  <description>Sum of Field1 and Field2</description>
+  <type>Number</type>  <!-- Result type, not "Formula" -->
+  <precision>18</precision>
+  <scale>2</scale>
+  <formula><![CDATA[Field1__c + Field2__c]]></formula>
+  <formulaTreatBlanksAs>BlankAsZero</formulaTreatBlanksAs>
+</CustomField>
+```
+
+### Formula Field Dependencies
+
+Formula fields that reference other fields will fail deployment if the referenced field does not exist or has not been deployed yet. Ensure all referenced fields are deployed before the formula field.
+
+### Specific Function Guidelines
+
+| Function | Rule |
+|----------|------|
+| `TEXT()` | MUST NOT be used with Text fields. If the field is already Text, remove the `TEXT()` wrapper. |
+| `CASE()` | Last parameter is always the default value. Total parameter count MUST be even (value-result pairs + default). |
+| `VALUE()` | MUST only be used with Text fields. If a Number is passed as parameter, remove the `VALUE()` wrapper. |
+| `DAY()` | MUST only be used with Date fields. If a DateTime field is used, convert it to Date first (e.g., `DAY(DATEVALUE(DateTimeField__c))`). |
+| `MONTH()` | MUST only be used with Date fields. If a DateTime field is used, convert it to Date first (e.g., `MONTH(DATEVALUE(DateTimeField__c))`). |
+| `DATEVALUE()` | MUST only be used with DateTime fields. If a Date field is used, remove the `DATEVALUE()` wrapper. |
+| `ISPICKVAL()` | MUST be used when checking equality of a Picklist field. NEVER use `==` with Picklist fields. |
+| `ISCHANGED()` | Use `ISCHANGED()` to check if a field value has changed. Do not manually compare with `PRIORVALUE()`. |
+
+---
+
+## 8. Common Deployment Errors
+
+| Error Message | Cause | Fix |
+|---------------|-------|-----|
+| `ConversionError: Invalid XML tags or unable to find matching parent xml file for CustomField` | XML comments placed before the root `<CustomField>` element | Remove XML comments (`<!-- ... -->`) that appear before `<CustomField>` in the `.field-meta.xml` file |
+| `Field [FieldName] does not exist. Check spelling.` | Referenced field does not exist or has not been deployed yet | Verify the referenced field exists and is deployed before this field |
+| `DUPLICATE_DEVELOPER_NAME` | Field fullName already exists on the object | Use a unique business-driven name |
+| `MAX_RELATIONSHIPS_EXCEEDED` | More than 2 Master-Detail or 15 Lookup fields on the object | Use Lookup for 3rd+ Master-Detail; review Lookup count |
+| Reserved keyword error | Using `Order__c`, `Group__c`, etc. | Rename to `Status_Order__c`, etc. |
+
+---
+
+## 9. Verification Checklist
+
+Before generating CustomField XML, verify:
+
+### Universal Checks
+- [ ] Does `<fullName>` use valid format and end in `__c`?
+- [ ] Are `<description>` and `<inlineHelpText>` both populated and meaningful?
+- [ ] Is `<label>` in Title Case?
+- [ ] Are there no XML comments (`<!-- ... -->`) before the root `<CustomField>` element? (Comments before the root element break SDR's parser)
+
+### Master-Detail Field Checks ⭐ CRITICAL
+- [ ] Is `<required>` attribute ABSENT? (Master-Detail is always required)
+- [ ] Is `<deleteConstraint>` attribute ABSENT? (Master-Detail always cascades)
+- [ ] Is `<lookupFilter>` block ABSENT? (Only for Lookup fields)
+- [ ] Is `<relationshipOrder>` set to `0` or `1`?
+- [ ] Is parent object's `<sharingModel>` set to `ControlledByParent`?
+
+### Lookup Field Checks
+- [ ] Is `<deleteConstraint>` set to `SetNull`, `Restrict`, or `Cascade`?
+- [ ] Is `<relationshipName>` in plural PascalCase?
+
+### Roll-Up Summary Field Checks ⭐ CRITICAL
+- [ ] Is `<precision>` attribute ABSENT?
+- [ ] Is `<scale>` attribute ABSENT?
+- [ ] Is `<summaryForeignKey>` in format `ChildObject__c.MasterDetailField__c`?
+- [ ] For SUM/MIN/MAX: Is `<summarizedField>` in format `ChildObject__c.FieldName__c`?
+- [ ] For COUNT: Is `<summarizedField>` ABSENT?
+- [ ] Does the child object have a Master-Detail field to this parent?
+
+### Formula Field Checks
+- [ ] Is `<type>` set to result type (NOT "Formula")?
+- [ ] Is `<formula>` content wrapped in `<![CDATA[ ... ]]>`?
+- [ ] Is `<returnType>` attribute ABSENT? (does not exist in Metadata API)
+- [ ] Is `<formulaTreatBlanksAs>` set to `BlankAsZero` for numeric results or `BlankAsBlank` for text/date results?
+- [ ] Do all referenced fields exist and deploy before this field?
+
+### Numeric Field Checks
+- [ ] Is `scale ≤ precision`?
+- [ ] Is `precision ≤ 18`?
+
+### Text Area Checks
+- [ ] For TextArea: Is `<length>255</length>` explicitly included?
+- [ ] For LongTextArea/Html: Is `<visibleLines>` set?
+
+### Relationship Limit Checks
+- [ ] Are there 2 or fewer Master-Detail relationships on the object?
+- [ ] Are there 15 or fewer Lookup relationships on the object?
+
+### Naming Checks
+- [ ] Is the API name free of reserved words (`Order`, `Group`, `Select`, etc.)?
+- [ ] Is the API name unique on this object?

package/skills/salesforce-custom-lightning-type/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: salesforce-custom-lightning-type
+description: Use this skill when users need to create Custom Lightning Types (CLTs) for Einstein Agent actions or structured input/output schemas. Trigger when users mention CLT, Custom Lightning Types, JSON schemas for agents, type definitions, lightning__objectType, or editor/renderer configurations. This is complex - always use this skill for CLT work.
+---
+
+## When to Use This Skill
+
+Use this skill when you need to:
+- Create Custom Lightning Types (CLTs) for structured inputs/outputs
+- Generate JSON Schema-based type definitions for Lightning Platform
+- Configure CLTs for Einstein Agent actions
+- Set up editor and renderer configurations for custom UI
+- Troubleshoot deployment errors related to Custom Lightning Types
+
+## Specification
+
+# CustomLightningType Metadata Specification
+
+## Overview & Purpose
+Custom Lightning Types (CLTs) are JSON Schema-based type definitions used by the Lightning Platform (including Einstein Agent actions) to describe structured inputs/outputs and drive editor/renderer experiences.
+
+## Configuration
+- **Choose standard Lightning types** when the structure is simple and can be expressed with properties and supported primitive `lightning:type` identifiers.
+- **Choose Apex class types** (`@apexClassType/...`) when the structure already exists server-side and you want the Apex class to define the shape.
+- **Include editor/renderer config** only when you need custom UI behavior (custom LWC input/output components). Otherwise, omit.
+
+## Critical Rules (Read First)
+- **Root object schemas MUST include**:
+  - `"type": "object"`
+  - `"title"`
+  - `"lightning:type": "lightning__objectType"`
+  - `"unevaluatedProperties": false`
+- `"unevaluatedProperties"` is enforced as `false` by the CLT metaschema. Do not set it to `true`.
+- **Root object schemas MUST NOT include** `"examples"` when `"unevaluatedProperties": false` is set.
+- **Nested objects (inside `properties`) MUST NOT set** `"lightning:type": "lightning__objectType"`.
+  - Nested objects should be plain JSON Schema objects (`type`, `properties`, optional `required`, optional `unevaluatedProperties`).
+- **List/array properties are highly restricted by the CLT metaschema**:
+  - **CRITICAL LIMITATION**: the CLT metaschema may reject the `items` keyword entirely. Treat `items` as **disallowed by default**.
+  - **Root-level arrays** (direct children of the root `properties`):
+    - **MUST include** `"lightning:type": "lightning__listType"`
+    - **MUST NOT include** `"items"`
+    - **OPTIONAL** `"type": "array"`
+  - **Nested arrays** (arrays inside nested objects) are the most common failure:
+    - **MUST include** `"type": "array"`
+    - **MUST NOT include** `"lightning:type": "lightning__listType"`
+    - **MUST NOT include** `"items"`
+- **When `"unevaluatedProperties": false` is set, any unknown keyword will fail validation**. Prefer removing keywords over relaxing strictness.
+- **Apex class CLTs are minimal**:
+  - Include **only** `title`, `description` (optional), and `lightning:type` set to `@apexClassType/...`.
+  - Do **not** add `type`, `properties`, `required`, or `unevaluatedProperties`.
+
+## Additional CLT Metaschema Validations
+- **Org namespace validation**: titles/descriptions and other string fields may be validated to ensure you are not using an org namespace in places that are disallowed.
+- **Lightning type validation**: CLTs are validated to prevent referencing internal namespaces (for example, disallowing types from internal namespaces like `sfdc_cms` where not permitted).
+- **Object type validation**: the CLT root is validated to ensure `lightning:type` is exactly `lightning__objectType`.
+
+## Primitive Types & Constraints
+- `lightning__textType`
+  - Max length 255
+- `lightning__multilineTextType`
+  - Max length 2000
+- `lightning__richTextType`
+  - Max length 100000
+- `lightning__urlType`
+  - Max length 2000
+  - Optional `lightning:allowedUrlSchemes` enum values: `https`, `http`, `relative`, `mailto`, `tel`
+- `lightning__dateType`
+  - Data pattern: YYYY-MM-DD
+- `lightning__timeType`
+  - Data pattern: HH:MM:SS.sssZ
+- `lightning__dateTimeType`
+  - Data shape is an object with required `dateTime` and optional `timeZone`
+- `lightning__numberType`
+  - Decimal numbers; optional `maximum`, `minimum`, `multipleOf`
+- `lightning__integerType`
+  - Whole numbers only; optional `maximum`, `minimum`
+- `lightning__booleanType`
+  - true/false
+
+## Allowed Property-Level Keywords
+When strict validation is enabled (`unevaluatedProperties: false`), keep each property minimal and prefer only keywords known to be allowed:
+- `title`, `description`, `einstein:description`
+- `type` (when used, ensure it matches the chosen `lightning:type`)
+- `lightning:type`
+- `maximum`, `minimum`, `multipleOf` (numeric)
+- `maxLength`, `minLength` (string)
+- `const`, `enum`
+- `lightning:textIndexed`, `lightning:supportsPersonalization`, `lightning:localizable`
+- `lightning:uiOptions`, `lightning:allowedUrlSchemes`
+- `lightning:tags` (metaschema restricts values; currently `flow` is the only known allowed tag)
+
+## Generation Workflow
+1. **Confirm the CLT approach**
+   - If referencing Apex: capture the exact class reference (`@apexClassType/namespace__ClassName$InnerClass`).
+   - If using standard primitives: list the fields, their Lightning primitive types, and which fields are required.
+2. **Draft `schema.json`**
+   - Start with the root object structure (required root fields).
+   - Add `properties` using valid primitive `lightning:type` identifiers.
+   - For nested objects: omit `lightning:type` and keep keywords minimal.
+   - For arrays: follow the strict list rules (avoid `items`; avoid `lightning:type` on nested arrays).
+3. **(Optional) Draft `editor.json`** (only if custom UI is required)
+   - **Supported shape:** Top-level `editor` object with `editor.componentOverrides` and `editor.layout`.
+     - Top-level `editor` object.
+     - Use `editor.componentOverrides` for component overrides.
+     - Use `editor.layout` for layout.
+   - **Root override pattern** (most common for fully custom editing UI):
+     - `editor.componentOverrides["$"] = { "definition": "c/<yourEditorComponent>", "attributes": { ... } }`
+     - When passing schema data into a custom LWC, use attribute mapping with the `{!$attrs.<name>}` syntax: e.g. `"attributes": { "myField": "{!$attrs.value}" }` so the runtime binds schema values to your component's attributes.
+   - **Property-level override pattern** (for individual fields):
+     - `editor.componentOverrides["<propertyName>"] = { "definition": "es_property_editors/<...>" }`
+     - **Valid editor components** (examples): `es_property_editors/inputText`, `es_property_editors/inputNumber`, `es_property_editors/inputRichText`, `es_property_editors/inputImage`, `es_property_editors/inputTextarea`. **Do not use** `es_property_editors/inputList`.
+   - **Collection editor** (for root-level `lightning__listType` properties): Use a collection-level override so the list is edited by a custom component: `collection.editor.componentOverrides["$"] = { "definition": "c/<yourCollectionEditorComponent>" }`. Alternatively, use `editor.layout` with `lightning/propertyLayout` and `attributes.property = "<listPropertyName>"` for default list editing.
+   - **Layout pattern**:
+     - `editor.layout.definition = "lightning/verticalLayout"`
+     - `editor.layout.children[*].definition = "lightning/propertyLayout"` with `attributes.property = "<propertyName>"`
+   - **Avoid known-invalid patterns**:
+     - Do not use `es_property_editors/inputList`.
+     - Do not use `itemSchema` attributes.
+4. **(Optional) Draft `renderer.json`** (only if custom UI is required)
+   - **Supported shape:** Top-level `renderer` object with `renderer.componentOverrides` and `renderer.layout`.
+     - Top-level `renderer` object.
+     - Use `renderer.componentOverrides` for component overrides.
+     - Use `renderer.layout` for layout.
+   - **Root override pattern** (most common for fully custom rendering UI):
+     - `renderer.componentOverrides["$"] = { "definition": "c/<yourRendererComponent>", "attributes": { ... } }`
+     - Use `{!$attrs.<name>}` in attribute mappings when binding schema data to custom renderer component attributes.
+   - **Property-level override pattern**:
+     - `renderer.componentOverrides["<propertyName>"] = { "definition": "es_property_editors/outputText" | "es_property_editors/outputNumber" | "es_property_editors/outputImage" | ... }`. **Valid renderer components** (examples): `es_property_editors/outputText`, `es_property_editors/outputNumber`, `es_property_editors/outputImage`. Avoid input-style components in the renderer.
+   - **Collection renderer** (for root-level `lightning__listType` properties): Use `collection.renderer.componentOverrides["$"] = { "definition": "c/<yourListRendererComponent>" }` or `es_property_editors/genericListTypeRenderer` to render the list.
+5. **Place files in the correct bundle structure**
+   - `lightningTypes/<TypeName>/schema.json`
+   - (Optional) `lightningTypes/<TypeName>/lightningDesktopGenAi/editor.json`
+   - (Optional) `lightningTypes/<TypeName>/lightningDesktopGenAi/renderer.json`
+   - For Gen AI / Copilot the standard path is `lightningDesktopGenAi/`. Other targets (e.g. Experience Builder, Mobile Copilot, Enhanced Web Chat) use different subfolders when supported: `experienceBuilder/`, `lightningMobileGenAi/`, `enhancedWebChat/`.
+6. **Deploy and validate**
+   - Deploy the bundle using your org's standard metadata deployment flow (e.g. Salesforce CLI or IDE). The MCP client or tooling in use should provide or integrate with the appropriate deploy/retrieve commands for Lightning Type bundles.
+   - Validate incrementally: if deployment fails, remove disallowed keywords first (especially `examples`, `items`, nested `lightning:type`).
+
+## Common Deployment Errors
+| Error / Symptom | Likely Cause | Fix |
+|---|---|---|
+| Schema validation fails due to unknown keyword | `unevaluatedProperties: false` + disallowed keyword (commonly `examples`, `items`) | Remove the offending keyword; keep schema minimal |
+| Nested object validation failure | Nested object includes `lightning:type: lightning__objectType` | Remove `lightning:type` from nested objects |
+| Array property rejected | Use of `items` (or `lightning:type` in nested arrays) rejected by validator | For nested arrays: keep only `type: "array"`. For root arrays: use minimal structure; remove `items` if rejected |
+| Apex-based CLT rejected | Extra fields added (e.g., `type`, `properties`) | Use only `title`, optional `description`, and `lightning:type` |
+| Editor config rejected | Use of invalid patterns (`es_property_editors/inputList`, `itemSchema`) or unrecognized top-level keys | Use `editor.componentOverrides` and `editor.layout`; keep config minimal |
+
+## Verification Checklist
+- [ ] Root schema has `type: "object"`, `title`, `lightning:type: "lightning__objectType"`, and `unevaluatedProperties: false`
+- [ ] Root schema does not include `examples` when strict validation is enabled
+- [ ] No nested object includes `lightning:type: "lightning__objectType"`
+- [ ] Arrays are defined minimally (especially nested arrays)
+- [ ] Only supported primitive `lightning:type` identifiers are used for leaf properties
+- [ ] Apex class CLTs contain only `title`/`description` and `lightning:type: "@apexClassType/..."`
+- [ ] Bundle structure and filenames match Lightning Types requirements
+- [ ] Editor config uses only allowed patterns (no `es_property_editors/inputList`, no `itemSchema`); use valid components (e.g. `es_property_editors/inputText`, `es_property_editors/inputNumber`) or custom `c/` components
+- [ ] Renderer config uses output-style components (e.g. `es_property_editors/outputText`, `es_property_editors/outputNumber`) where applicable, not input editors