@salesforce/afv-skills 1.30.0 → 1.32.0

package/skills/platform-custom-field-generate/SKILL.md

@@ -4,6 +4,7 @@ description: "Use this skill when users need to create, generate, or validate Sa
 metadata:
   version: "1.0"
   minApiVersion: "51.0"
+  relatedSkills: ["platform-value-set-generate", "platform-validation-rule-generate"]
 ---
 
 # Salesforce Custom Field Generator and Validator
@@ -20,7 +21,7 @@ Every generated field must include these tags:
 
 | Attribute | Requirement | Notes |
 |-----------|-------------|-------|
-| `<fullName>` | Required | **Field** name only: 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`. ⚠️ This rule is for the FIELD name. **Picklist VALUE `<fullName>` is different — keep it exactly as the user spelled it, spaces and all, no `__c`** (e.g. `Closed Won`, NOT `Closed_Won`). See [`references/advanced-picklists.md`](references/advanced-picklists.md) (ref §3). |
+| `<fullName>` | Required | **Field** name only: 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`. This rule is for the FIELD name. **Picklist VALUE `<fullName>` is different — keep it exactly as the user spelled it, spaces and all, no `__c`** (e.g. `Closed Won`, NOT `Closed_Won`). See [`references/advanced-picklists.md`](references/advanced-picklists.md) (ref §3). |
 | `<label>` | Required | The UI name (Title Case) |
 | `<description>` | Always include | Explain the business reason *why* this field exists. |
 | `<inlineHelpText>` | Always include | Actionable end-user guidance that adds value beyond the label (e.g., "Enter the value in USD including tax", not "The amount"). |
@@ -49,7 +50,7 @@ To ensure deployment success, follow these mathematical constraints:
 
 ### The "Fixed 255" Rule
 
-**TextArea: always include `<length>255</length>` exactly** — this literal value is required by the Metadata API and **omitting it fails deployment**, even though the UI exposes no length control. Unlike every other type where `length` is a value you calculate, TextArea's is a fixed constant.
+**TextArea: do NOT include `<length>`** — the Metadata API fixes the length at 255 implicitly and **rejects an explicit `<length>` value** with "Can not specify 'length' for a CustomField of type TextArea". Omit `<length>` entirely; the field only needs `<fullName>`, `<label>`, and `<type>TextArea</type>`.
 
 ### Visible Lines
 
@@ -76,7 +77,7 @@ Mandatory for Long/Rich text and Multi-select picklists to control UI height.
 | Phone | `Phone` | Standardizes phone number formatting |
 | Picklist | `Picklist` | `valueSet` containing EITHER `valueSetDefinition` (inline) OR `valueSetName` (reference); `restricted` (see "Picklist `restricted` default" below; advanced cases in §3.4) |
 | Text | `Text` | `length` (Max 255) |
-| Text Area | `TextArea` | `<length>255</length>` |
+| Text Area | `TextArea` | None — do NOT include `<length>`; the API fixes length at 255 implicitly |
 | Text (Long) | `LongTextArea` | `length`, `visibleLines` (default 3) |
 | Text (Rich) | `Html` | `length`, `visibleLines` (default 25) |
 | Time | `Time` | Stores time only (no date) |
@@ -112,7 +113,7 @@ Mandatory for Long/Rich text and Multi-select picklists to control UI height.
 
 ### 3.4 Advanced Picklists
 
-The inline `<valueSetDefinition>` above is the simple case. Full rules and worked ✅/❌
+The inline `<valueSetDefinition>` above is the simple case. Full rules and worked correct/incorrect
 examples for everything below are in
 [`references/advanced-picklists.md`](references/advanced-picklists.md) — load it for any
 non-trivial picklist. Section numbers in parentheses below (e.g. "ref §1") point to that
@@ -166,12 +167,12 @@ Master-Detail fields have **strict attribute restrictions** that differ from Loo
 
 | 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 |
+| `<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:
 
@@ -451,7 +452,7 @@ Before generating CustomField XML, verify:
 - [ ] Is `precision ≤ 18`?
 
 ### Text Area Checks
-- [ ] For TextArea: Is `<length>255</length>` explicitly included?
+- [ ] For TextArea: Is `<length>` **omitted**? (The API rejects an explicit `<length>` value on TextArea fields.)
 - [ ] For LongTextArea/Html: Is `<visibleLines>` set?
 
 ### Relationship Limit Checks

package/skills/platform-custom-field-generate/references/advanced-picklists.md

@@ -21,7 +21,7 @@ A picklist field can either define its values **inline** or **reference an exist
 value set** (a Global Value Set or a Standard Value Set). The shared set is defined
 once and reused across many fields.
 
-### ⭐ HARD RULE: `<valueSet>` is EITHER a reference OR inline — never both
+### HARD RULE: `<valueSet>` is EITHER a reference OR inline — never both
 
 A `<valueSet>` element must contain **exactly one** of:
 
@@ -30,7 +30,7 @@ A `<valueSet>` element must contain **exactly one** of:
 
 Including both in the same `<valueSet>` is a deployment error.
 
-#### ❌ INCORRECT — both reference and inline definition:
+#### INCORRECT — both reference and inline definition:
 
 ```xml
 <CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
@@ -54,7 +54,7 @@ Including both in the same `<valueSet>` is a deployment error.
 
 **Error:** `Value set must reference a value set name or define a value set, but not both.`
 
-#### ✅ CORRECT — reference a Global Value Set:
+#### CORRECT — reference a Global Value Set:
 
 ```xml
 <CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
@@ -88,7 +88,7 @@ the name you put inside it differs.
 > local project" warning) is expected org-storage display — keep local metadata on the bare name.
 > Never append `__c` to a value-set name either.
 
-#### ✅ CORRECT — reference a Standard Value Set (bare name, no suffix):
+#### CORRECT — reference a Standard Value Set (bare name, no suffix):
 
 ```xml
 <CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
@@ -126,7 +126,7 @@ A **dependent** picklist filters its available values based on the selected valu
 **dependent** field via a `<controllingField>` element plus one `<valueSettings>` block
 per (controlling value → dependent value) pair.
 
-### ⭐ Use the MODERN API 38.0+ form ONLY
+### Use the MODERN API 38.0+ form ONLY
 
 | Form | Elements | Status |
 |------|----------|--------|
@@ -136,7 +136,7 @@ per (controlling value → dependent value) pair.
 Never emit the legacy `<picklist>`, `<picklistValues>`, or `<controllingFieldValues>`
 tags. They are not valid against the modern Metadata API and will fail deployment.
 
-### ⭐ HARD RULE: both the controlling and dependent field must be `<restricted>true</restricted>`
+### HARD RULE: both the controlling and dependent field must be `<restricted>true</restricted>`
 
 A field dependency requires a fixed, admin-defined value set on **both** ends. **Always emit
 `<restricted>true</restricted>` inside the `<valueSet>` of the controlling field AND the
@@ -186,7 +186,7 @@ Inside the dependent field's `<valueSet>`, in this order:
 > EMEA→UK,Germany) you emit **one block for each (controllingValue, dependentValue) pair** — four
 > pairs = four `<valueSettings>` blocks. And remember: both fields carry `<restricted>true</restricted>`.
 
-### ✅ CORRECT — State dependent on Country (USA → California, Texas)
+### CORRECT — State dependent on Country (USA → California, Texas)
 
 **Controlling field — `Country__c` (a plain restricted picklist):**
 
@@ -258,7 +258,7 @@ Inside the dependent field's `<valueSet>`, in this order:
 > `<valueSettings>` block with that country's `<controllingFieldValue>` and
 > `<valueName>California</valueName>`.
 
-### ❌ INCORRECT — deprecated legacy form:
+### INCORRECT — deprecated legacy form:
 
 ```xml
 <CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
@@ -282,7 +282,7 @@ legacy dependency elements are not valid in the modern `<valueSet>` structure.
 
 ## 3. Enhanced Value Attributes
 
-### ⭐ Value-name fidelity — do NOT underscore picklist value names
+### Value-name fidelity — do NOT underscore picklist value names
 
 A **picklist value's `<fullName>` is NOT a field API name** and must NOT be transformed.
 Use the value text **exactly as the user spelled it**, spaces and all. A value the user
@@ -315,7 +315,7 @@ Inline `<value>` entries (CustomValue subfields) support more than `<fullName>`,
 
 These are independent of `<default>` and `<label>` and may be combined freely.
 
-### ✅ CORRECT — Status picklist with colors and an inactive value
+### CORRECT — Status picklist with colors and an inactive value
 
 ```xml
 <CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
@@ -367,7 +367,7 @@ The Metadata API rejects malformed picklist values at deploy time. Two common fa
 Two `<value>` entries with the same `<fullName>` inside one `<valueSetDefinition>` are
 rejected.
 
-#### ❌ INCORRECT — duplicate value:
+#### INCORRECT — duplicate value:
 
 ```xml
 <valueSetDefinition>
@@ -398,7 +398,7 @@ The stricter "only alphanumerics and single underscores, no leading digit, no do
 or trailing underscore" rule applies to the *field* `<fullName>` (the `__c`-suffixed
 API name), not to picklist value fullNames.
 
-#### ❌ INCORRECT — invalid value API name:
+#### INCORRECT — invalid value API name:
 
 ```xml
 <value>
@@ -410,7 +410,7 @@ API name), not to picklist value fullNames.
 
 **Error:** `Invalid fullName: must begin with a letter and use only alphanumeric characters and underscores`
 
-#### ✅ CORRECT:
+#### CORRECT:
 
 ```xml
 <value>
@@ -454,7 +454,7 @@ include a `<fullName>`** element — the record type's developer name (e.g. `<fu
 matching the filename `Internal.recordType-meta.xml`. It's bare (no object prefix); the object
 comes from the `objects/<Object>/` folder path.
 
-### ⭐ STEP 1 — Decide if this object needs a BusinessProcess (do this BEFORE writing files)
+### STEP 1 — Decide if this object needs a BusinessProcess (do this BEFORE writing files)
 
 A record type on a **BusinessProcess-gated object — Opportunity, Lead, Case, or Solution —
 will NOT deploy without a `<businessProcess>` reference**, even when it only filters a *custom*
@@ -472,7 +472,7 @@ developer name instead of generating a new one (confirm via the grounding MCP's
 if available; otherwise generate a minimal one). For everything else, **do not invent a
 BusinessProcess** — adding one to a custom-object record type is wrong.
 
-#### ✅ CORRECT — Opportunity "Enterprise" record type, two deployable files
+#### CORRECT — Opportunity "Enterprise" record type, two deployable files
 
 ```xml
 <!-- File 1: objects/Opportunity/businessProcesses/Enterprise_Sales_Process.businessProcess-meta.xml -->
@@ -519,7 +519,7 @@ BusinessProcess** — adding one to a custom-object record type is wrong.
 </RecordType>
 ```
 
-#### ❌ INCORRECT — BusinessProcess file emitted but NOT referenced (most common failure)
+#### INCORRECT — BusinessProcess file emitted but NOT referenced (most common failure)
 
 ```xml
 <!-- File 1 (businessProcesses/Enterprise_Sales_Process...) was generated correctly, BUT -->
@@ -571,7 +571,7 @@ RecordType   (filters the field's values; references the BusinessProcess)
 - For Opportunity/Lead/Case/Solution, the `<businessProcess>` must exist (same package or
   already in the org) before the RecordType.
 
-### ⭐ UI-sync gotcha — values may not auto-display after API deploy
+### UI-sync gotcha — values may not auto-display after API deploy
 
 When `<picklistValues>` are loaded via the Metadata API, the values are correctly associated
 under the hood, **but they may not automatically appear as "Selected Values" in the Record

package/skills/platform-custom-lightning-type-generate/SKILL.md

@@ -1,8 +1,11 @@
 ---
 name: platform-custom-lightning-type-generate
-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, Custom Lightning Types (CLTs) with widget/mosaic/fragment rendition/renderer, JSON schemas for agents, type definitions, lightning__objectType, or editor/renderer configurations. When widget renditions are requested, you MUST first read the widget-rendition.md reference file in this skill's references/ directory and follow its complete workflow. This is complex - always use this skill for CLT work."
+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. For widget renditions that combine a CLT with a Widget bundle, use the platform-lightning-type-widget-coordinate orchestrator instead. This is complex - always use this skill for CLT work."
 metadata:
   version: "1.0"
+  minApiVersion: "60.0"
+  relatedSkills:
+    - "platform-lightning-type-widget-coordinate"
 ---
 
 ## When to Use This Skill
@@ -12,7 +15,6 @@ Use this skill when you need to:
 - Generate JSON Schema-based type definitions for Lightning Platform
 - Configure CLTs for Einstein Agent actions
 - Set up editor and renderer configurations for custom UI
-- Create CLTs with widget/mosaic/fragment rendition
 - Troubleshoot deployment errors related to Custom Lightning Types
 
 ## Specification
@@ -54,6 +56,7 @@ Custom Lightning Types (CLTs) are JSON Schema-based type definitions used by the
 - **Apex class CLTs are minimal**:
   - Include **only** `title`, `description` (optional), and `lightning:type` set to `@apexClassType/...`.
   - Do **not** add `type`, `properties`, `required`, or `unevaluatedProperties`.
+- **No shell metacharacters that trigger the Vibes safe-shell filter.** In any Bash tool call emitted by this skill, do NOT use command substitution (`$(…)` or backticks), process substitution (`<(…)`, `>(…)`), brace expansion (`{a,b,c}` or `{1..N}`), or `eval` / `exec`. Vibes forces manual approval on these patterns even under Bypass mode and stalls the eval. Emit separate commands (`mkdir -p a && mkdir -p b`) or print each value with its own command and reason about the output rather than capturing it in a shell variable.
 
 ## 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.
@@ -66,7 +69,7 @@ When you need the full list of supported primitive `lightning:type` identifiers,
 
 ## Generation Workflow
 1. **Confirm the CLT approach**
-   - If referencing Apex: capture the exact class reference (`@apexClassType/namespace__ClassName$InnerClass`).
+   - 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`**
    - **DO NOT include `"$schema"` at the top**
@@ -100,26 +103,18 @@ When you need the full list of supported primitive `lightning:type` identifiers,
    - **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 or mosaic rendition is required)
+4. **(Optional) Draft `renderer.json`** (only if custom UI or widget rendition 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.
      - **DEPRECATED**: Do NOT use `propertyRenderers` or `view` — these are legacy keys. Always use `componentOverrides` and `layout` instead.
-   - **Root override pattern** (most common for fully custom rendering UI):
+   - **Widget rendition pattern** (reference an existing WidgetBundle as the root renderer): the renderer file is a thin wrapper that points at the widget by developer name (`"definition": "@widget/c/<widgetDeveloperName>"`) and maps CLT schema properties to widget attributes via `{!$attrs.<schemaPropertyName>}`. Do **NOT** duplicate the widget body inside `renderer.json`. See `references/widget-rendition.md` for the full shape, binding rules, and constraints. For the full Apex → Lightning Type → Widget pipeline, use the `platform-lightning-type-widget-coordinate` orchestrator instead of this skill.
+   - **Root override pattern** (most common for fully custom rendering UI with a custom LWC):
      - `renderer.componentOverrides["$"] = { "definition": "c/<yourRendererComponent>", "attributes": { ... } }`
      - Use `{!$attrs.<name>}` in attribute mappings when binding schema data to custom renderer component attributes.
      - **CRITICAL**: Attribute mappings like `{!$attrs.propertyName}` must reference properties that **actually exist** in your type schema. Referencing non-existent properties will fail validation.
      - **Type matching**: Attribute values must match the expected type for the component. For example, if a component expects a string attribute, passing an integer will fail validation.
-   - **Widget renderer pattern** (for widget rendition):
-       - **When to use:** Use this when users request "mosaic", "widget", "fragment", or "cross-platform rendering" for their CLT.
-       - **Structure:** `renderer.componentOverrides["$"] = { "type": "mosaic", "definition": "tile/mosaic", "children": [ /* UEM tree of blocks and regions */ ] }`
-       - **REQUIRED workflow:**
-           - **STOP**: Do NOT attempt to create the widget renderer yourself.
-           - **MANDATORY FIRST STEP**: You MUST fetch the reference file `references/widget-rendition.md` located in this skill's directory before proceeding.
-           - Follow the complete workflow documented in `widget-rendition.md` using the generated CLT schema as the grounding schema.
-           - The `widget-rendition.md` reference contains the full widget generation workflow: discovering UEM blocks via discoverUiComponents, calling getUiComponentSchemas, building the UEM tree, and writing renderer.json.
-           - **Do not** attempt to generate widget rendition without first fetching the `widget-rendition.md` reference file.
    - **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.
    - **Layout pattern for renderer**:

package/skills/platform-custom-lightning-type-generate/references/widget-rendition.md

@@ -1,124 +1,40 @@
-# Widget Generation Guide
+# Widget Rendition Pattern for CLT renderer.json
 
 ## Overview
-Widgets are reusable pieces of UI similar to templates, with placeholders for actual data values. The purpose of this file is to assist developers in creating mosaic renditions for CLTs.
 
-## Purpose
-Widgets render data in a structured and unified way across various Salesforce experiences like Slack, Mobile, LEX etc.
+When a Custom Lightning Type needs to render through a Widget bundle (authored by `platform-widget-generate`), the `renderer.json` uses a flat widget-reference pattern. The renderer points at the widget by developer name and maps each CLT schema property to the widget's attribute contract.
 
-## Schema Grounding
-Widget generation is **always schema-grounded** using a CLT's schema. The schema describes the data shape the widget should render. Extract property names, types, required vs optional, and nesting from the schema; then follow the full **Workflow** below, using this extracted structure to guide every step. Do not add or remove properties relative to the schema.
+> **For full widget generation** (Apex → Lightning Type → Widget pipeline), use the `platform-lightning-type-widget-coordinate` orchestrator. This file documents only the renderer.json wiring pattern for CLTs that reference an existing widget.
 
-## Composition
-A widget is a UEM (Unified Experience Model) tree of blocks and regions. The widget you return must follow the Typescript interfaces below:
+## renderer.json Shape
 
-```ts
-interface BlockType {
-   type: 'block'
-   definition: string  // {namespace}/{blockName}
-   attributes?: Record<string, any>
-   children?: (BlockType | RegionType)[]
-}
-
-interface RegionType {
-   type: 'region'
-   name: string
-   children: BlockType[]
+```json
+{
+  "renderer": {
+    "componentOverrides": {
+      "$": {
+        "definition": "@widget/c/<widgetDeveloperName>",
+        "attributes": {
+          "<widgetAttrKey>": "{!$attrs.<schemaPropertyName>}"
+        }
+      }
+    }
+  }
 }
 ```
----
-
-## Available Metadata Actions
-
-### When to Use Each Action
-
-#### discoverUiComponents
-
-**Purpose:** Discover the palette of available blocks that can be used in widget composition.
-
-**Use for:** Finding available blocks before building your widget structure.
-
-**Input Parameters:**
-- `actionName` (**required***): "discoverUiComponents"
-- `metadataType` (**required**): "FRAGMENT"
-- `parameters` (**required**): JSON object with the below fields
-  - `pageType` (**required**): "FRAGMENT"
-  - `pageContext` (optional): JSON object - not required for FRAGMENT type
-  - `searchQuery` (optional): String to filter components by name or description
-
-**Returns:** List of components with:
-- `definition`: Fully qualified name (e.g., "namespace/definiton")
-- `description`: Component description
-- `label`: Human-readable label
-- `attributes`: Optional attribute metadata
-
-#### getUiComponentSchemas
-
-**Purpose:** Get detailed JSON schemas for component configuration, including property types, required vs optional fields, and validation rules.
-
-**Use for:** You know which components you want but need to understand their properties before adding them to your widget.
-
-**Input Parameters:**
-- `actionName` (**required***): "getUiComponentSchemas"
-- `metadataType` (**required**): "FRAGMENT"
-- `parameters` (**required**): JSON object with the below fields
-  - `pageType` (**required**): "FRAGMENT"
-  - `componentDefinitions` (**required**): List of fully qualified names (e.g., ["namespace/definition"])
-    - **CRITICAL**: NEVER include "tile/mosaic" in this list. "tile/mosaic" is a container component used in renderer.json structure and **should not** be passed to getUiComponentSchemas
-  - `pageContext` (optional): JSON object - not required for FRAGMENT type
-  - `includeKnowledge` (optional): Boolean, defaults to true - includes additional component-specific guidance
-
-**Returns:**
-- `componentSchemas`: List of results (supports partial failures)
-- **Success entries**: Contains JSON schema with property definitions, types, constraints
-- **Failure entries**: Contains error message explaining why schema couldn't be retrieved
-- `$defs`: Schema definitions and references (if schema transformation applied)
-
-**Key Feature:** Supports partial failures - if some components can't be found, you still get schemas for the successful ones.
-
----
-
-## Attribute binding using placeholder syntax
-
-- **Where to use:** When block properties must display or pass runtime data from the grounding schema, use the **Placeholder Syntax** below so that the runtime binds values into the widget. Check each block's schema (from `getUiComponentSchemas`) for the correct property name (e.g. `value`, `text`, `label`).
-- **Placeholder Syntax:** Use `{!$attrs.<attrName>}` as the placeholder for each block property that should receive data.
-  `<attrName>` **must** match the property name from the grounding schema so that the runtime can resolve its value.
-  Example: for a schema property `title`, set the block property to `{!$attrs.title}`.
-- **List / iterative data:** Only the children (list items) hold bound values; the parent list block does not. For each item inside a list (e.g. `tile/listItem`), use `{!$attrs.<listAttrName>.item}` so the runtime binds the current item. `<listAttrName>` MUST match the schema property name of the list. Example: for `icons`, use `"{!$attrs.icons.item}"` on the list item.
-
----
-
-## Workflow
-
-1. **Schema Parsing**
-- Parse the schema and extract: property names, types, required vs optional, and nested structure. Use this as the **widget spec**.
-
-2. **Discover Available Blocks** (**REQUIRED** - do NOT skip)
-- Use **discoverUiComponents metadata action** above to explore what blocks are available.
-- Use property types from the **widget spec** to inform `searchQuery` (e.g. text → "text", number → "number").
-
-3. **Select Components**
-- Choose blocks that can represent each property in the **widget spec** from the results of step 2.
-
-4. **Get Component Schemas** (**REQUIRED** - do NOT skip)
-- Use **getUiComponentSchemas metadata action** with the selected block definitions from step 3 and review block properties' metadata.
 
-5. **Build Widget**
-- Construct the UEM tree. Map each property in the **widget spec** to block properties and preserve order of the **widget spec**.
-- For block properties that must show or pass runtime data, use the placeholder syntax (see **Attribute binding using placeholder syntax** above).
-- Use block properties from the schemas retrieved in step 4.
+- `<widgetDeveloperName>` matches the widget bundle directory name under `uiWidgets/`.
+- `<widgetAttrKey>` is a property under the widget's `schema.json` `properties.attributes.properties`.
+- `<schemaPropertyName>` is a property on the Custom Lightning Type's schema.
+- One attribute mapping per widget property — the set of attributes must match the widget's schema contract.
 
-6. **Write output to CLT Bundle**
-- Always write to `lightningTypes/<TypeName>/lightningDesktopGenAi/renderer.json` (or the correct target subfolder for the product surface, e.g. `experienceBuilder/`, `lightningMobileGenAi/`, `enhancedWebChat/` when applicable).
-  Check **required root override pattern** below -
-  `renderer.componentOverrides["$"] = { "type": "mosaic", "definition": "tile/mosaic", "children": [ ... ] — array of UEM nodes - contains the widget UEM generated using the **Workflow** steps 1-5 above }`
+## Attribute Binding
 
----
+Use `{!$attrs.<name>}` syntax in attribute values. `<name>` must match a property defined in the CLT's own `schema.json`. At runtime the renderer resolves these bindings and passes the live data to the widget.
 
-## Important Notes
+## Constraints
 
-- **widget spec** includes both required and optional attributes - review carefully to ensure valid configuration.
-- When using **`execute_metadata_action`** tool, always supply **`parameters`** with the required fields above; missing `parameters` or required keys causes hard failures, not partial results.
-- Block definitions always follow the `{namespace}/{blockName}` convention.
-- Use the same definition format returned by `discoverUiComponents` when calling `getUiComponentSchemas`
-- Placeholder syntax for non-list properties is `{!$attrs.<attrName>}` and for list properties is `{!$attrs.<listAttrName>.item}`.
+- Do NOT duplicate the widget UEM body inside `renderer.json` — the widget bundle owns its own UEM tree.
+- The widget bundle (`<pkgDir>/uiWidgets/<widgetDeveloperName>/`) must exist and be deployed before the Lightning Type that references it.
+- Every attribute key in the renderer must resolve to a property in the widget's `schema.json` `properties.attributes.properties`.
+- Write the renderer to `lightningTypes/<TypeName>/lightningDesktopGenAi/renderer.json` (or the correct target subfolder for the product surface).