@salesforce/afv-skills 1.31.0 → 1.32.0

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).

package/skills/platform-lightning-type-widget-coordinate/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: platform-lightning-type-widget-coordinate
+description: "Orchestrate Apex-backed Lightning Type + HXL widget generation. TRIGGER only when the prompt EXPLICITLY invokes Lightning Types: user says 'Lightning Type', 'CLT', 'Custom Lightning Type', 'Apex-backed type', references '@apexClassType/...', asks to build a widget or card for a named Lightning Type, asks to create a new Lightning Type and widget together, or grounds a widget in a specific Apex class as its schema. DO NOT TRIGGER when the prompt names only a subject, domain, feature, or entity noun. Also DO NOT TRIGGER when: authoring only a Custom Lightning Type (use platform-custom-lightning-type-generate), only an Apex class (use platform-apex-generate), editing an existing widget without any Lightning Type change, or grounding a widget on an object/JSON-based Lightning Type (lightning__objectType with primitives)."
+metadata:
+  version: "1.1"
+  minApiVersion: "68.0"
+  relatedSkills:
+    - "platform-widget-generate"
+    - "platform-custom-lightning-type-generate"
+    - "platform-apex-generate"
+  cliTools:
+    - tool: ["jq"]
+      semver: ">=1.6.0"
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+---
+
+# Building a Lightning Type With a Widget
+
+Coordinate Lightning Type, Apex class, and HXL widget generation across the two paths below. This skill never authors content directly — it loads and invokes leaf skills in dependency order, gates progress on user approval, and runs validation gates before reporting completion.
+
+## Scope
+
+Apex-backed Lightning Types only — root `lightning:type` of the form `@apexClassType/<namespace>__<ClassName>` (outer class). The class itself carries the `@AuraEnabled` fields that define the payload shape; nested list-element types live as inner classes referenced by `List<Inner>` fields on the outer class. Object/JSON-based Lightning Types (root `lightning__objectType` with primitive `properties`) are out of scope; route those to `platform-custom-lightning-type-generate` and `platform-widget-generate` separately.
+
+---
+
+## Phase Graph
+
+| Phase | Purpose | Runs in | Output |
+|---|---|---|---|
+| 1 — Path selection | Pick the path (`existing-lightning-type-with-widget` · `new-lightning-type-with-widget`) from the user prompt. | All paths | `path` |
+| 2 — Lightning Type discovery | Local project first; then `sf project retrieve --metadata LightningTypeBundle:<name>`; ambiguity resolution; in-scope verification. | **`existing-lightning-type-with-widget` only** | `lightningTypeSchema` (path + SHA-256 + Apex class FQN) |
+| 3 — Build plan | Print the plan in full; proceed unless the next reply explicitly pushes back. | All paths | printed plan |
+| 4 — Generation | Load and invoke leaf skills per path. | All paths | files written |
+| 5 — Validation | Run hard gates (block) and warn gates (advisory). | All paths | gate report |
+| 6 — Summary | Files, validations, preview readiness, next steps. | All paths | summary |
+
+**Per-phase pattern:**
+
+| Step | What to do |
+|---|---|
+| 1. Load skill | Invoke the named skill. Even if you remember its content, skills evolve — always load fresh. |
+| 2. Execute | Follow the loaded skill's workflow. |
+| 3. Verify | Confirm outputs exist and match the spec. |
+| 4. Checkpoint | Confirm phase completion before moving on. |
+
+---
+
+## Phase 1 — Path selection
+
+Determine the path from the user prompt and pick the corresponding leaf-skill load order:
+
+| Path | Trigger | Phase 4 sub-skill load order |
+|---|---|---|
+| `existing-lightning-type-with-widget` | Prompt names a Lightning Type and treats it as existing (no *create*, *generate*, or *new* qualifier on the type). Phase 2 confirms it exists and is in scope. | `platform-widget-generate` (renderer wiring is authored inline per the Phase 4 "Renderer.json wiring step" — no separate skill load) |
+| `new-lightning-type-with-widget` | Prompt asks for a new Lightning Type (verbs: *create*, *generate*, *build*, *make a new*) **or** Phase 2 finds nothing in the local project or in the org. | `platform-apex-generate` → `platform-custom-lightning-type-generate` (schema authoring) → `platform-widget-generate` (renderer wiring authored inline afterwards per the Phase 4 "Renderer.json wiring step") |
+
+If the prompt names no Lightning Type at all (just a widget against prompt-provided fields or sample data), this orchestrator should not have been triggered — route the user to `platform-widget-generate` directly.
+
+If the prompt is ambiguous between the two paths, ask **one** clarifying question max and pick. The `new-lightning-type-with-widget` path's `platform-apex-generate` step is engaged automatically — do not prompt the user to confirm Apex.
+
+---
+
+## Phase 2 — Lightning Type discovery (`existing-lightning-type-with-widget` only)
+
+Skipped for `new-lightning-type-with-widget` (the Lightning Type does not yet exist).
+
+**For `existing-lightning-type-with-widget`, FIRST Read `references/lightning-type-discovery.md` (REQUIRED — do NOT skip; do not run Phase 2 from this summary alone), then execute its find → verify → ensure-class procedure step by step.** The bullets below are a reminder, not a substitute for the reference:
+
+- Local project first: search `force-app/**/lightningTypes/<TypeName>/schema.json`.
+- If not found, run `sf project retrieve --metadata LightningTypeBundle:<TypeName>` against the connected org.
+- If multiple candidates surface, list them with FQNs and paths. Ask the user to pick.
+- After locating the schema, verify it is in scope (root `lightning:type` starts with `@apexClassType/`). If the type is object/JSON-based, surface that and stop.
+- **Ensure the backing Apex class is in the local project.** Parse `<ClassName>` from the `@apexClassType/<ns>__<ClassName>` root. If `<pkgDir>/classes/<ClassName>.cls` is absent, run `sf project retrieve --metadata ApexClass:<ClassName>`. This runs whether the Lightning Type was found locally or retrieved from the org — a locally-present Lightning Type can still reference an absent class. If the class exists nowhere, surface it and stop (the type is unrenderable). See the reference for the full procedure.
+- If retrieval fails, surface the CLI error and offer: (a) ask the user to run retrieve manually and re-run, or (b) downgrade to `new-lightning-type-with-widget` if appropriate. Never silently downgrade.
+- If retrieval finds nothing, prompt the user to confirm flipping to `new-lightning-type-with-widget` before continuing.
+
+Capture the Lightning Type `schema.json` SHA-256 and the Apex class FQN (parsed from `@apexClassType/...`) at the end of this phase. The Phase 5 `lightning-type-unchanged` gate compares the SHA against the on-disk SHA at end of Phase 4 to enforce no silent schema edits.
+
+> Staleness: do NOT maintain a cross-session cache. Always read the local project fresh and always re-retrieve from the org per session.
+
+---
+
+## Phase 3 — Build plan + approval gate
+
+Print a build plan using the template in `references/build-plan-format.md`. The plan must list:
+
+- A one-line developer-facing summary of what will be built (the `PLAN:` line in the template).
+- Lightning Type name and source (existing in local project · retrieved from org · newly created), plus the Apex class FQN it references.
+- Files about to be created or modified, with absolute paths.
+- Sub-skills that will run after approval.
+- Validations that will run after generation.
+
+The plan is read by the developer. Keep it concrete: name the artifacts, files, sub-skills, and validations.
+
+**Print the plan in full, then proceed unless the user's next reply explicitly pushes back.** Explicit pushback = `no`, `stop`, `wait`, `change X`, `use Y instead`, or an equivalent rejection / revision request. Explicit approval (`yes`, `approve`, `go`, `looks good`, `ok`) is welcome but NOT required — silence, an unrelated follow-up, or the natural continuation of a single-turn eval all count as implicit approval. The plan being visible in the transcript is the invariant; blocking on interactive approval is not. If pushback arrives, revise the plan and re-print before moving on.
+
+---
+
+## Phase 4 — Generation
+
+Execute the sub-skill load order from the chosen path's row in the Phase 1 table. For each sub-skill:
+
+1. Load the skill.
+2. Execute the leaf skill's authoring workflow against the spec from Phase 3. The leaf skill is authoritative for its own deliverables.
+3. Verify the outputs match what the build plan promised.
+4. Checkpoint before invoking the next sub-skill.
+
+**`new-lightning-type-with-widget` handoff contract:**
+
+- Apex authors a class whose `@AuraEnabled` fields define the desired Lightning Type shape. Inner classes are used only for nested list-element types. Capture the **outer class FQN** (`<namespace>__<ClassName>`).
+- The Custom Lightning Type references the outer class via `lightning:type: "@apexClassType/<namespace>__<ClassName>"`.
+- Widget grounds on the outer class's `@AuraEnabled` fields and binds attributes via `{!$attrs.X}`.
+- After the widget bundle is written, author the Lightning Type's renderer wiring per the **renderer.json wiring step** below.
+
+**`existing-lightning-type-with-widget` handoff contract:**
+
+- Hand the widget skill the Lightning Type `schema.json` path and the Apex class FQN captured in Phase 2. The widget skill derives its own `schema.json` from the Apex class's `@AuraEnabled` fields (see `platform-widget-generate/references/schema-from-lightning-type.md`).
+- After the widget bundle is written, author the Lightning Type's renderer wiring per the **renderer.json wiring step** below. The Lightning Type `schema.json` is NOT modified (`lightning-type-unchanged` enforces this) — only `lightningDesktopGenAi/renderer.json` is written.
+
+**Renderer.json wiring step (BOTH flows — never optional):**
+
+**First, Read `platform-custom-lightning-type-generate/references/widget-rendition.md` (REQUIRED — do NOT skip; do not author `renderer.json` from memory or by copying an existing project sample, which may use a deprecated shape).**
+
+After the widget bundle exists, author `<pkgDir>/lightningTypes/<TypeName>/lightningDesktopGenAi/renderer.json` using the **widget-rendition pattern** documented in `platform-custom-lightning-type-generate/references/widget-rendition.md`. The renderer file is a thin wrapper — its first child references the widget via `"definition": "@widget/c/<widgetName>"` and maps **every widget schema property** to the Lightning Type instance's matching attribute via `{!$attrs.<schemaPropertyName>}`. Do **NOT** duplicate the widget body inside `renderer.json`; the widget bundle is the single source of truth for the rendering tree.
+
+Existing-renderer handling (`existing-lightning-type-with-widget` only): if `renderer.json` already exists at the target path, read it first.
+
+- If it already references the same widget (same `@widget/c/<widgetName>`) with the same attribute mapping, leave it alone.
+- If it references a **different** widget OR uses a custom-LWC root override (`c/<componentName>`), STOP and surface the conflict to the user before overwriting. Do not silently replace the user's existing rendition.
+- If the file exists but is not a widget-rendition (e.g. property-level overrides only), surface that and ask whether to merge or replace.
+
+Without this wiring the widget is unreachable from the Lightning Type — the widget bundle ships dead. `renderer-wires-widget` enforces existence and binding correctness.
+
+---
+
+## Phase 5 — Validation gates
+
+Read `references/validation-gates.md` and **run every gate**. The orchestrator runs cross-skill gates only — widget-bundle-internal checks (schema parse, root keys, leaf `lightning:type`, `{!$attrs.X}` resolution, `.uiwidget-meta.xml` well-formedness, `<UiWidgetBundle>` root, `<masterLabel>`, `<description>`, and `<widgetType>JSON</widgetType>`) are owned by `platform-widget-generate` and run as part of its own self-validation step.
+
+**Hard — block on failure:**
+
+1. `lightning-type-unchanged` — **`existing-lightning-type-with-widget` only.** Recompute SHA-256 of the on-disk Lightning Type `schema.json` and compare against the SHA captured in Phase 2. Mismatch = orchestrator silently edited the type.
+2. `renderer-wires-widget` — **both paths.** Confirm `<pkgDir>/lightningTypes/<TypeName>/lightningDesktopGenAi/renderer.json` exists, parses as JSON, wires this widget via `componentOverrides["$"].definition === "@widget/c/<widgetName>"`, and `componentOverrides["$"].attributes` binds every widget schema property as `{!$attrs.<schemaPropertyName>}`. See "renderer.json wiring step" in Phase 4 and `validation-gates.md` for the required shape.
+
+**Warn — advisory:**
+
+1. `field-trace` — **both paths.** RUN the trace procedure in `references/validation-gates.md` (grep `@AuraEnabled` from the outer .cls, `jq` widget schema property keys, print both lists, classify INVENTED vs OMITTED). PRINT both lists in the gate report — asserting `pass` without printing the lists is a hard violation. Silent omissions (Apex field absent from widget AND absent from the Phase 3 `Properties omitted:` plan) warn.
+2. `deploy-check` — **`new-lightning-type-with-widget` only.** RUN `sf project deploy --check-only --source-dir <pkgDir>/classes/<ClassName>.cls,<pkgDir>/lightningTypes/<TypeName>` and report the result. Reporting `pass` without running this command is a hard violation. See `validation-gates.md` for the "not yet deployed is not a valid skip reason" rule.
+
+Report each gate result by name in Phase 6 (`pass`, `fail (<reason>)`, `warn (<reason>)`, `not run`). Do **not** summarize as "all passed" — list each gate explicitly.
+
+---
+
+## Phase 6 — Summary
+
+Report. The summary is read by the developer — list only the files actually written; group by bundle so the developer can locate them quickly.
+
+```text
+Lightning Type + Widget Build Complete: <widgetName>
+
+FILES GENERATED:
+  Widget bundle:
+    <pkgDir>/uiWidgets/<widgetName>/<widgetName>.json
+    <pkgDir>/uiWidgets/<widgetName>/schema.json
+    <pkgDir>/uiWidgets/<widgetName>/<widgetName>.uiwidget-meta.xml
+
+  Lightning Type bundle:
+    <pkgDir>/lightningTypes/<TypeName>/schema.json                              # only when newly created
+    <pkgDir>/lightningTypes/<TypeName>/lightningDesktopGenAi/renderer.json      # always — wires the Lightning Type to the widget
+
+  Apex (only when newly created):
+    <pkgDir>/classes/<ClassName>.cls
+    <pkgDir>/classes/<ClassName>.cls-meta.xml
+
+VALIDATIONS:
+  widget self-validation (platform-widget-generate gates): <pass | fail — see sub-skill report>
+  Lightning Type schema unchanged from before this run: <pass | fail | n/a (newly created)>
+  Lightning Type renderer wires this widget: <pass | fail (<reason>)>
+  widget↔apex field trace (INVENTED + OMITTED lists printed): <pass | warn (<reason>) | fail (invented: <list>)>
+  sf project deploy --check-only: <pass | warn | n/a (no new Apex or Lightning Type to deploy)>
+
+NEXT STEPS:
+  - Deploy: sf project deploy start --source-dir <pkgDir>
+  - Preview: <preview-surface guidance>
+```
+
+---
+
+## Hard Rules (always apply)
+
+1. **Plan-first, then proceed.** Print the full Phase 3 build plan before writing any file. If the next turn contains explicit rejection or a change request, stop and revise; otherwise continue to Phase 4. The invariant is the plan being visible in the transcript — not an interactive human approval — so this rule holds in manual chat, in agent-to-agent flows, and in single-turn eval runs where no follow-up user message arrives.
+2. **No silent schema edits** to existing Lightning Types. Phase 5 `lightning-type-unchanged` enforces this for `existing-lightning-type-with-widget`.
+3. **No silent Apex changes** to existing Apex. If Phase 4 needs to modify a pre-existing class, surface it in Phase 3. **A leaf skill that hits a shape gap mid-Phase-4 MUST stop and surface to the orchestrator instead of editing `.cls` directly** — Phase 3 covers gaps the orchestrator already knew about; this clause covers gaps discovered later by a leaf skill.
+4. **No invented fields, no silent omissions.** Every `{!$attrs.X}` must trace to the widget `schema.json`, and the widget `schema.json` must be a subset of the Apex class's `@AuraEnabled` fields. Default disposition for every Apex field is **include**; omission requires the field to appear in the Phase 3 build plan's `Properties omitted:` section with a rationale the user has approved. `field-trace` prints both APEX_FIELDS and WIDGET_PROPS lists and warns on silent omissions. `List<InnerClass>` fields are NEVER candidates for silent omission.
+5. **One clarification at most** when Lightning Type lookup is ambiguous.
+6. **Always load the leaf skill** before generation. Do not author from memory.
+7. **Out-of-scope types stop the orchestrator.** If Phase 2 discovers an object/JSON-based Lightning Type, route the user to `platform-custom-lightning-type-generate` and `platform-widget-generate` separately.
+8. **Run gates, do not describe them.** Phase 5 gates are concrete checks/commands. Reporting `pass` without executing the gate is a hard violation; report `not run` instead.
+9. **Lightning Type rendition is mandatory, never optional.** Both paths end with `<pkgDir>/lightningTypes/<TypeName>/lightningDesktopGenAi/renderer.json` wiring the Lightning Type to the widget via `@widget/c/<widgetName>` with attribute mapping per the widget-rendition pattern. Without this, the widget bundle ships dead. `renderer-wires-widget` enforces existence and binding.
+10. **No shell metacharacters that trigger the Vibes safe-shell filter.** In every `Bash` tool call emitted by this orchestrator and by any leaf skill it invokes, do NOT use command substitution (`$(…)` or backticks), process substitution (`<(…)`, `>(…)`), brace expansion (`{a,b,c}` or `{1..N}`), or `eval` / `exec`. These patterns force manual approval even under Bypass mode and stall the eval. Instead: run separate commands (`mkdir -p a && mkdir -p b`, not `mkdir -p {a,b}`); print each intermediate value with its own command and reason about the result rather than capturing it (`jq … file` on its own, not `X=$(jq … file)`); use plain shell variables (`X=literal`) or here-strings when a value must be reused across commands.
+
+---
+
+## Reference File Index
+
+| File | When to read |
+|------|--------------|
+| `references/lightning-type-discovery.md` | Phase 2 — local-project scan, org retrieve, ambiguity handling, in-scope verification, and ensuring the backing Apex class is in the local project. |
+| `references/build-plan-format.md` | Phase 3 — plan template the model fills before STOP. |
+| `references/validation-gates.md` | Phase 5 — full hard / warn gate table with error→fix mapping. |
+| `examples/existing-lightning-type-with-widget-prompt.md` | Phase 3 — before drafting the build plan, read this for a complete `existing-lightning-type-with-widget` walkthrough. |
+| `examples/new-lightning-type-with-widget-prompt.md` | Phase 3 — before drafting the build plan, read this for a complete `new-lightning-type-with-widget` walkthrough. |

package/skills/platform-lightning-type-widget-coordinate/examples/existing-lightning-type-with-widget-prompt.md

@@ -0,0 +1,80 @@
+# Worked Example — Render an Existing Apex-Backed Lightning Type
+
+## User prompt
+
+> Build a widget for the OrderSummary Lightning Type — show order id, customer, total, and a list of line items.
+
+## Walkthrough
+
+**Phase 1 — Path selection.** The prompt names a Lightning Type (`OrderSummary`) and treats it as existing → pick the `existing-lightning-type-with-widget` path. Phase 4 will load `platform-widget-generate` only, after Phase 2 confirms the type is Apex-backed.
+
+**Phase 2 — Lightning Type discovery.** Find first, verify after.
+
+```bash
+$ rg -l 'lightning:type' force-app/**/lightningTypes/OrderSummary/
+force-app/main/default/lightningTypes/OrderSummary/schema.json
+```
+
+Found in the local project. Now verify in scope — read `schema.json`. Root is `"lightning:type": "@apexClassType/orders__OrderSummary"`. Apex-backed → continue. Capture path + SHA-256 + Apex class FQN `orders__OrderSummary` (outer-class form; an inner-class root like `orders__OrderResponses$CreateResult` is also in scope and would scope the trace to that inner class). Source = `existing in local project`.
+
+> If the root had been `lightning__objectType` (object/JSON-based), the orchestrator would have stopped here and routed the user to use `platform-custom-lightning-type-generate` and `platform-widget-generate` separately.
+
+**Phase 3 — Build plan.** Print:
+
+```text
+Lightning Type + Widget Build Plan: orderSummaryWidget
+
+PLAN: Generate a widget that renders the existing OrderSummary Lightning Type.
+
+LIGHTNING TYPE:
+  Name: OrderSummary
+  Source: existing in local project
+  Path: force-app/main/default/lightningTypes/OrderSummary/schema.json
+  Renderer (wires the Lightning Type to the widget): force-app/main/default/lightningTypes/OrderSummary/lightningDesktopGenAi/renderer.json
+  Schema fingerprint (captured before any sub-skill runs): <hex>
+  Apex class FQN: orders__OrderSummary
+
+WIDGET:
+  Name: orderSummaryWidget
+  Output:
+    force-app/main/default/uiWidgets/orderSummaryWidget/orderSummaryWidget.json
+    force-app/main/default/uiWidgets/orderSummaryWidget/schema.json
+    force-app/main/default/uiWidgets/orderSummaryWidget/orderSummaryWidget.uiwidget-meta.xml
+  Schema source: derived from Apex class @AuraEnabled fields via the Lightning Type
+  Layout intent: card with header (id + customer), body (total + shipping-address fields), footer (line items list with forEach)
+  Properties omitted: lastUpdatedTime (audit field, not relevant to render — proposed omission)
+
+SUB-SKILLS THAT WILL RUN:
+  platform-widget-generate
+
+VALIDATIONS THAT WILL RUN AFTER GENERATION:
+  Widget bundle self-validation (run by platform-widget-generate):
+    - widget schema.json parses, root keys correct, every leaf has lightning:type
+    - every {!$attrs.X} (and {!$attrs.shippingAddress.city} for the singular nested address object) resolves
+    - <name>.uiwidget-meta.xml is well-formed XML, root is <UiWidgetBundle>, and declares <widgetType>JSON</widgetType>
+  Cross-skill checks (run by this orchestrator):
+    - lightning-type-unchanged: existing schema.json is byte-identical to the captured fingerprint
+    - renderer-wires-widget: renderer.json references @widget/c/orderSummaryWidget with one {!$attrs.<schemaPropertyName>} mapping per widget schema property
+    - field-trace: print @AuraEnabled fields, widget properties (with nested dot paths and list-item paths expanded), and the diff
+
+----------------------------------------------------------------
+STOP — wait for the user to Approve or Decline.
+```
+
+User picks Approve.
+
+**Phase 4 — Generation.** Load `platform-widget-generate`. Hand it the Lightning Type schema path, the Apex class FQN (`orders__OrderSummary`), and the widget name. The widget skill derives its `schema.json` from the Apex class's `@AuraEnabled` fields:
+
+- Primitive fields → primitive `lightning:type`.
+- Singular nested inner class (e.g. `Address shippingAddress`) → `lightning__objectType`; bound in the widget body via dot-notation `{!$attrs.shippingAddress.city}`, `{!$attrs.shippingAddress.zip}`.
+- `List<LineItem> lineItems` → `lightning__listType`; iterated with `forEach`/`forItem` and bound via `{!$item.<innerField>}`.
+
+The skill omits `lastUpdatedTime` per the build plan and writes the three widget files. Then author `force-app/main/default/lightningTypes/OrderSummary/lightningDesktopGenAi/renderer.json` using the widget-rendition pattern, binding each widget attribute via `{!$attrs.<schemaPropertyName>}`. (If `renderer.json` already exists referencing a different widget or a custom LWC, STOP and surface the conflict.)
+
+**Phase 5 — Validation.** The widget skill reports its own self-validation results. This orchestrator runs:
+
+- `lightning-type-unchanged` — confirms the Lightning Type was untouched.
+- `renderer-wires-widget` — confirms the renderer points at this widget and binds every widget schema property.
+- `field-trace` — prints APEX_FIELDS / WIDGET_PROPS / INVENTED / OMITTED. The omission of `lastUpdatedTime` is in the build plan and emits no warning.
+
+**Phase 6 — Summary.** Print files generated and each validation result by name (`lightning-type-unchanged: pass`, `renderer-wires-widget: pass`, `field-trace: pass`), followed by the deploy command.

package/skills/platform-lightning-type-widget-coordinate/examples/new-lightning-type-with-widget-prompt.md

@@ -0,0 +1,75 @@
+# Worked Example — Create a New Apex-Backed Lightning Type With a Widget
+
+## User prompt
+
+> Generate a Lightning Type and a widget for an account briefing — fields: account name, owner, last activity date, top three open opportunities.
+
+> Note: the user did not mention Apex. This orchestrator only supports Apex-backed Lightning Types, so the `new-lightning-type-with-widget` path implicitly engages `platform-apex-generate` because the new typed Lightning Type requires a backing Apex class. The orchestrator surfaces this Apex step in the Phase 3 build plan so the developer sees what it intends to do.
+
+## Walkthrough
+
+**Phase 1 — Path selection.** User asks for a new Lightning Type plus a widget. Pick the `new-lightning-type-with-widget` path: `platform-apex-generate` → `platform-custom-lightning-type-generate` → `platform-widget-generate`. Apex backing for the typed payload is implied; do not ask the user to confirm Apex is wanted.
+
+**Phase 2 — Lightning Type discovery.** **Skipped.** The prompt is explicit about creating a new Lightning Type, so there is no existing schema to discover and no fingerprint to capture.
+
+**Phase 3 — Build plan.** Print:
+
+```text
+Lightning Type + Widget Build Plan: accountBriefingWidget
+
+PLAN: Create a new Apex class, Lightning Type, and widget for AccountBriefing.
+
+LIGHTNING TYPE:
+  Name: AccountBriefing
+  Source: newly created
+  Path: force-app/main/default/lightningTypes/AccountBriefing/schema.json
+  Renderer (wires the Lightning Type to the widget): force-app/main/default/lightningTypes/AccountBriefing/lightningDesktopGenAi/renderer.json
+  Apex class FQN: c__AccountBriefing
+
+APEX (only when creating a new Lightning Type — auto-engaged because this orchestrator only supports Apex-backed Lightning Types):
+  Class name: AccountBriefing
+  Class FQN: c__AccountBriefing
+  Shape: outer class with @AuraEnabled fields (accountName, ownerName, lastActivityDate, primaryContact: Contact, openOpportunities: List<OpenOpportunity>). Contact is an inner class for a singular nested object. OpenOpportunity is an inner class for nested list elements. The Apex shape itself is owned by platform-apex-generate.
+  Returns: typed payload shaped to AccountBriefing
+
+WIDGET:
+  Name: accountBriefingWidget
+  Output:
+    force-app/main/default/uiWidgets/accountBriefingWidget/accountBriefingWidget.json
+    force-app/main/default/uiWidgets/accountBriefingWidget/schema.json
+    force-app/main/default/uiWidgets/accountBriefingWidget/accountBriefingWidget.uiwidget-meta.xml
+  Schema source: derived from Apex class @AuraEnabled fields via the Lightning Type
+  Layout intent: header card (name + owner + last activity + primary contact name/title via dot-notation), body list (top opportunities with forEach over List<OpenOpportunity>)
+  Properties omitted: none
+
+SUB-SKILLS THAT WILL RUN:
+  platform-apex-generate
+  platform-custom-lightning-type-generate
+  platform-widget-generate
+
+VALIDATIONS THAT WILL RUN AFTER GENERATION:
+  Widget bundle self-validation (run by platform-widget-generate):
+    - widget schema.json parses, root keys correct, every leaf has lightning:type
+    - every {!$attrs.X} (and {!$attrs.primaryContact.name} for the singular nested contact object, {!$item.X} inside forEach) resolves
+    - <name>.uiwidget-meta.xml is well-formed XML, root is <UiWidgetBundle>, and declares <masterLabel>, <description>, and <widgetType>JSON</widgetType>
+  Cross-skill checks (run by this orchestrator):
+    - renderer-wires-widget: renderer.json references @widget/c/accountBriefingWidget with one {!$attrs.<schemaPropertyName>} mapping per widget schema property
+    - field-trace: print @AuraEnabled fields from AccountBriefing plus inner classes Contact and OpenOpportunity, widget properties (with nested dot paths and list-item paths expanded), and the diff
+    - deploy-check: `sf project deploy --check-only --source-dir force-app/main/default/classes/AccountBriefing.cls,force-app/main/default/lightningTypes/AccountBriefing` (RUN the command — do not assume).
+
+----------------------------------------------------------------
+STOP — wait for the user to Approve or Decline.
+```
+
+User picks Approve.
+
+**Phase 4 — Generation.**
+
+1. Load `platform-apex-generate`. Author `AccountBriefing.cls` (outer class with `@AuraEnabled` fields including `Contact primaryContact` as a singular nested object and `List<OpenOpportunity> openOpportunities` as a list-element collection; `Contact` and `OpenOpportunity` are inner classes). Capture FQN `c__AccountBriefing` (outer-class form for this example).
+2. Load `platform-custom-lightning-type-generate`. Author `lightningTypes/AccountBriefing/schema.json` with `lightning:type: "@apexClassType/c__AccountBriefing"` (outer-class form).
+3. Load `platform-widget-generate`. Pass the Lightning Type schema path, the Apex class FQN, and the widget name. The widget skill derives its `schema.json` and writes the three widget files. `Contact primaryContact` becomes a `lightning__objectType` property bound via `{!$attrs.primaryContact.name}` etc.; `List<OpenOpportunity>` becomes a `lightning__listType` property whose body iterates with `forEach`/`forItem` and binds `{!$item.<innerField>}`.
+4. Author `lightningTypes/AccountBriefing/lightningDesktopGenAi/renderer.json` using the **widget rendition pattern** (see `platform-custom-lightning-type-generate/SKILL.md` step 4): a thin wrapper whose first child is `"definition": "@widget/c/accountBriefingWidget"` with attribute mappings binding each widget attribute to a Lightning Type schema property via `{!$attrs.<schemaPropertyName>}`.
+
+**Phase 5 — Validation.** The widget skill reports its own self-validation results. This orchestrator runs `renderer-wires-widget`, `field-trace`, and `deploy-check` (the `sf project deploy --check-only ...` command above). Reporting `pass` without running `deploy-check` is a hard violation — report `not run` instead.
+
+**Phase 6 — Summary.** Print each validation result by name and value (`renderer-wires-widget: pass`, `field-trace: pass`, `deploy-check: pass`), files generated, and the deploy command.

package/skills/platform-lightning-type-widget-coordinate/references/build-plan-format.md

@@ -0,0 +1,67 @@
+# Build Plan Format
+
+Use this template in Phase 3 to print the plan before the STOP gate. Fill every section. Do not abbreviate.
+
+---
+
+```text
+Lightning Type + Widget Build Plan: <widgetName>
+
+PLAN: <one line in developer-facing terms, e.g.:
+  "Generate a widget that renders the existing OrderStatusResponse Lightning Type"
+  OR
+  "Create a new Apex class, Lightning Type, and widget for AppointmentSummary">
+
+LIGHTNING TYPE:
+  Name: <TypeName>
+  Source: <existing in local project | retrieved from org | newly created>
+  Path: <pkgDir>/lightningTypes/<TypeName>/schema.json
+  Renderer (wires the Lightning Type to the widget): <pkgDir>/lightningTypes/<TypeName>/lightningDesktopGenAi/renderer.json
+  Schema fingerprint (captured before any sub-skill runs): <hex SHA-256>   # omit when source is "newly created"
+  Apex class FQN: <namespace>__<ClassName>[$<InnerClass>]   # outer-class form, or inner-class form when the CLT roots on a specific inner class
+
+APEX (only when creating a new Lightning Type — auto-engaged because this orchestrator only supports Apex-backed Lightning Types):
+  Class name: <ClassName>
+  Class FQN: <namespace>__<ClassName>
+  Shape: outer class with @AuraEnabled fields matching the desired Lightning Type payload. Inner classes are used for nested list-element types (e.g. List<OpenOpportunity>) and for singular nested objects (e.g. Address address). The Apex shape itself is owned by platform-apex-generate; this plan records the FQN and field summary, not the class body.
+  Returns: typed payload shaped to <TypeName>
+
+WIDGET:
+  Name: <widgetName>
+  Output:
+    <pkgDir>/uiWidgets/<widgetName>/<widgetName>.json
+    <pkgDir>/uiWidgets/<widgetName>/schema.json
+    <pkgDir>/uiWidgets/<widgetName>/<widgetName>.uiwidget-meta.xml
+  Schema source: <derived from Apex class @AuraEnabled fields via the Lightning Type | derived from prompt fields>
+  Layout intent: <one-line description of the widget composition>
+  Properties omitted: <list any Apex class fields the widget intentionally drops, e.g. lastUpdatedTime, audit fields — or "none">
+
+SUB-SKILLS THAT WILL RUN:
+  <list per the chosen path's row in SKILL.md — skill IDs only>
+
+VALIDATIONS THAT WILL RUN AFTER GENERATION:
+  Widget bundle self-validation (run by platform-widget-generate):
+    - widget schema.json parses and has the required root keys
+    - every leaf in properties has a lightning:type
+    - every {!$attrs.X} (and {!$attrs.<outer>.<inner>} for nested objects, {!$item.X} inside forEach) resolves
+    - <name>.uiwidget-meta.xml is well-formed XML, root is <UiWidgetBundle>, and declares <widgetType>JSON</widgetType>
+  Cross-skill checks (run by this orchestrator):
+    - lightning-type-unchanged: when an existing Lightning Type was used as input, its schema.json is byte-identical to the version captured before this run
+    - renderer-wires-widget: the Lightning Type's renderer.json exists and references this widget via `@widget/c/<widgetName>`, with one {!$attrs.<schemaPropertyName>} mapping per widget schema property
+    - field-trace (advisory): print the @AuraEnabled fields from the outer Apex class plus every inner class referenced as a singular nested object or List<InnerClass>; print the widget schema properties (expanded for nested objects and list items); print the diff. Invented widget fields fail; omissions not declared above warn.
+    - deploy-check (advisory, new-type path only): `sf project deploy --check-only --source-dir <pkgDir>/classes/<ClassName>.cls,<pkgDir>/lightningTypes/<TypeName>` is run and the result reported.
+
+----------------------------------------------------------------
+STOP — wait for the user to Approve or Decline.
+The host surface may render Approve/Decline as buttons; a text reply ("approve", "yes", "go") is also accepted.
+A Decline (or edits to the plan) reprints the plan; the orchestrator does not write any file until an explicit Approve.
+```
+
+---
+
+## Notes for the model
+
+- If the user replies with edits or declines, revise the plan and reprint it. Do not assume which sections changed.
+- Approval applies only to the plan as printed. If the user later asks for additional widgets or Lightning Types, start a new planning cycle for the new ask.
+- Do not print this plan inside a code fence that the user might mistake for output. The plan is conversational, not a file.
+- "Properties omitted" makes intentional drops explicit. Examples of fields that often do not belong on a render surface: `lastUpdatedTime`, `createdBy`, audit timestamps, internal IDs.