@salesforce/afv-skills 1.37.0 → 1.38.0

package/skills/platform-mcp-tool-widget-coordinate/examples/nested-object-single-source-prompt.md

@@ -0,0 +1,198 @@
+# Example: single nested-object payload field, discovered from the IA describe
+
+A complete walkthrough for the case where an Invocable Action output is itself **another Apex class** —
+a **single nested object** (`maxOccurs: 1`). **The Invocable Action (IA) describe is the source of
+truth**; the Apex class is read only to enumerate the referenced class's own leaf fields. This is the
+second, additive payload shape alongside the flat-primitive shape in `apex-invocable-source-prompt.md` —
+read `references/mcp-tool-output-discovery.md` ("Nested-object and list payload fields") and
+`references/two-clt-modeling.md` ("Nested-object and list payload fields") first. The **list** shapes
+(top-level list, list-inside-wrapper) are in the companion example `nested-object-list-source-prompt.md`.
+
+> **The skill never modifies the Apex.** The describe's `apexClass` + `maxOccurs` tell you the shape;
+> reading the referenced class is a read-only enumeration step, not a reshape.
+
+---
+
+## Single nested object (`maxOccurs: 1`)
+
+### The prompt
+
+> I have an MCP server tool backed by the `GetFlightDetailsAction` Apex invocable action. Build a
+> widget that renders its output as a flight details card.
+
+### Phase 1 — Input selection
+
+- Source: `action` — the prompt names an Apex Invocable, so describe it through the Actions REST API
+  (`/services/data/v<APIVER>/actions/custom/apex/GetFlightDetailsAction`). This is the source of truth
+  for the output shape; the `.cls` is read later only to enumerate the referenced class's leaves.
+- Tool API name: `getFlightDetails` (from the class name `GetFlightDetailsAction`, stripping the
+  trailing `Action` suffix and lower-camelCasing — see the naming convention in
+  `references/two-clt-modeling.md`).
+
+### Phase 2 — Payload discovery (from the describe)
+
+The Actions describe returns a scalar sibling alongside the single nested-object output:
+
+```jsonc
+// GET /services/data/v67.0/actions/custom/apex/GetFlightDetailsAction  →  .outputs[]
+[
+  { "name": "searchStatus", "type": "STRING", "maxOccurs": 1 },
+  { "name": "flightInfo", "type": null, "apexClass": "SearchFlightsAction$Flight", "maxOccurs": 1 }
+]
+```
+
+- `searchStatus` is a **flat primitive** (`STRING`) → `lightning__textType`, bound two segments deep. Flat scalars and a single nested object coexist in one response; handle each per its own branch.
+- `flightInfo`: `type: null` + `apexClass` set + `maxOccurs: 1` = a **single nested object** (not a describe gap, not a list).
+- The nested output's own leaf fields are **not** in the describe. Read the named class
+  (`SearchFlightsAction.Flight`) and enumerate its **public / `@AuraEnabled`** members — an
+  inner/referenced class is not gated by `@InvocableVariable` (that gates only the top-level response
+  class). These become the widget's flat leaf properties. **Never ignore any property.**
+
+```apex
+public class Flight {
+    @InvocableVariable public String flightId;
+    @InvocableVariable public String origin;
+    @InvocableVariable public String destination;
+    @InvocableVariable public String departureTime;
+    @InvocableVariable public String arrivalTime;
+    @InvocableVariable public Long   price;
+}
+```
+
+| Leaf field | Apex type | widget `lightning:type` |
+|---|---|---|
+| flightId | String | `lightning__textType` |
+| origin | String | `lightning__textType` |
+| destination | String | `lightning__textType` |
+| departureTime | String | `lightning__textType` |
+| arrivalTime | String | `lightning__textType` |
+| price | Long | `lightning__numberType` |
+
+`payloadFields` (from describe) = 2 fields: `searchStatus` (flat `STRING`) + `flightInfo` (Apex-class-typed → nested-object branch).
+`payloadFields` (flattened, for the widget) = `searchStatus` + the 6 leaf rows above (7 total).
+
+### Phase 3 — Build plan (abridged)
+
+```text
+MCP Tool Widget Build Plan: getFlightDetailsWidget
+
+PLAN: Render the GetFlightDetails MCP tool output as a flight-details card.
+
+TOOL / SOURCE:
+  Tool API name: getFlightDetails
+  Payload source: Actions describe of Apex Invocable GetFlightDetailsAction
+  Outputs: searchStatus (STRING, maxOccurs 1 → flat scalar) + flightInfo (apexClass SearchFlightsAction$Flight, maxOccurs 1 → single nested object)
+
+LIGHTNING TYPES:
+  Response CLT:  getFlightDetailsResponse
+    Properties: searchStatus → "lightning__textType"; flightInfo → "@apexClassType/c__SearchFlightsAction$Flight"   # nested-object field, NOT {"type":"object"}
+  Envelope CLT: getFlightDetails
+    Renderer (default, bundle root): .../lightningTypes/getFlightDetails/renderer.json
+    Envelope: actionName (text), isSuccess (boolean), outputValues (c__getFlightDetailsResponse)
+
+WIDGET: getFlightDetailsWidget
+  Schema: searchStatus (flat scalar) + flightInfo's 6 leaf fields (flightId, origin, destination, departureTime, arrivalTime, price)
+  Renderer binding: searchStatus → {!$attrs.outputValues.searchStatus} (two segments); each flightInfo leaf → {!$attrs.outputValues.flightInfo.<leaf>} (three segments)
+
+GENERATION ORDER: response CLT → widget → envelope CLT
+```
+
+Proceed unless the next reply pushes back.
+
+### Phase 4 — Generation order
+
+1. **Response CLT** `getFlightDetailsResponse`:
+
+   ```json
+   {
+     "title": "Get Flight Details Response",
+     "description": "Response fields from the GetFlightDetailsAction invocable-action (FlightDetailsResponse)",
+     "type": "object",
+     "lightning:type": "lightning__objectType",
+     "lightning:tags": ["mcp"],
+     "unevaluatedProperties": false,
+     "properties": {
+       "searchStatus": {
+         "title": "Search Status",
+         "lightning:type": "lightning__textType"
+       },
+       "flightInfo": {
+         "title": "Flight Info",
+         "lightning:type": "@apexClassType/c__SearchFlightsAction$Flight"
+       }
+     }
+   }
+   ```
+
+2. **Widget** `getFlightDetailsWidget` — flat schema over `searchStatus` + the 6 leaf fields (not the
+   single `flightInfo` field); body binds `{!$attrs.searchStatus}`, `{!$attrs.flightId}`,
+   `{!$attrs.origin}`, etc.
+
+3. **Envelope CLT** `getFlightDetails`:
+
+   ```json
+   {
+     "title": "Get Flight Details",
+     "description": "Invocable-action result envelope for the GetFlightDetailsAction MCP tool",
+     "type": "object",
+     "lightning:type": "lightning__objectType",
+     "lightning:tags": ["mcp"],
+     "unevaluatedProperties": false,
+     "properties": {
+       "actionName": { "title": "Action Name", "lightning:type": "lightning__textType" },
+       "isSuccess":  { "title": "Is Success",  "lightning:type": "lightning__booleanType" },
+       "outputValues": { "title": "Output Values", "lightning:type": "c__getFlightDetailsResponse" }
+     }
+   }
+   ```
+
+4. **Default renderer** at `lightningTypes/getFlightDetails/renderer.json` —
+   `definition: @widget/c/getFlightDetailsWidget`, each attribute bound three segments deep through
+   the nested object:
+
+   ```json
+   {
+     "renderer": {
+       "componentOverrides": {
+         "$": {
+           "definition": "@widget/c/getFlightDetailsWidget",
+           "attributes": {
+             "searchStatus":  "{!$attrs.outputValues.searchStatus}",
+             "flightId":      "{!$attrs.outputValues.flightInfo.flightId}",
+             "origin":        "{!$attrs.outputValues.flightInfo.origin}",
+             "destination":   "{!$attrs.outputValues.flightInfo.destination}",
+             "departureTime": "{!$attrs.outputValues.flightInfo.departureTime}",
+             "arrivalTime":   "{!$attrs.outputValues.flightInfo.arrivalTime}",
+             "price":         "{!$attrs.outputValues.flightInfo.price}"
+           }
+         }
+       }
+     }
+   }
+   ```
+
+### Phase 5 — Validation
+
+- `clt-reference-integrity`: envelope `outputValues` → `c__getFlightDetailsResponse`, response CLT
+  exists, `searchStatus` is a primitive `lightning__textType`, `flightInfo` uses
+  `@apexClassType/c__SearchFlightsAction$Flight` (not a bare `{"type":"object"}`, not an inlined
+  `lightning__objectType`), no `$schema`/`items` → **pass**. PROP_GROUNDING: both trace to describe outputs → **ok**.
+- `renderer-wires-widget`: bundle-root renderer present, definition `@widget/c/getFlightDetailsWidget`,
+  `searchStatus` bound two segments, every `flightInfo` leaf bound three segments as
+  `{!$attrs.outputValues.flightInfo.<property>}` (not two, which would bind to an unresolvable object) → **pass**.
+- `field-trace`: `searchStatus` (primitive) compares directly; `flightInfo` resolves to
+  `@apexClassType/...` and expands to its class's leaves before comparing. INVOCABLE_FIELDS (expanded)
+  = `searchStatus, flightId, origin, destination, departureTime, arrivalTime, price`. Widget properties
+  match exactly; INVENTED empty; OMITTED empty → **pass**.
+
+---
+
+## Notes
+
+- **Why not a single-level opaque object.** Typing an Apex-class-typed field as `{"type":"object"}`
+  produces an opaque blob with no leaf fields — not renderable. The
+  `@apexClassType/<ns>__<OuterClass>$<InnerClass>` reference is what actually deploys.
+- **This is additive, not a replacement.** A response of all primitives still uses the flat mapping
+  tables unchanged. Check each field independently — outputs can mix primitive and Apex-class-typed fields.
+- **List shapes are separate.** A top-level list output or a list nested inside a wrapper is covered in
+  `nested-object-list-source-prompt.md`.

package/skills/platform-mcp-tool-widget-coordinate/examples/pasted-tool-output-prompt.md

@@ -64,7 +64,6 @@ LIGHTNING TYPES:
 
 WIDGET: getOrderStatusWidget
   Renderer binding: each attribute → {!$attrs.outputValues.<field>}
-  Properties omitted: none
 
 GENERATION ORDER: response CLT → widget → envelope CLT
 ```

package/skills/platform-mcp-tool-widget-coordinate/references/build-plan-format.md

@@ -20,11 +20,14 @@ LIGHTNING TYPES (two object-based CLTs of equal standing — named for what each
     Name: <responseCLT>          # convention: <toolApiName>Response
     Path: <pkgDir>/lightningTypes/<responseCLT>/schema.json
     Properties: <field: lightning:type, ...>   # 1:1 with response @InvocableVariable fields
+    Nested/list fields: <objectField: @apexClassType/c__<Outer>$<Inner>, ... — or "none">
+      # A single nested object is one @apexClassType property; a List<ApexClass> rides INSIDE an
+      # @apexClassType object (the CLT carries no lightning__listType — the list surfaces in the widget schema).
   Envelope CLT:
     Name: <toolCLT>          # convention: <toolApiName>
     Path: <pkgDir>/lightningTypes/<toolCLT>/schema.json
     Renderer (default, at bundle root — wires the widget): <pkgDir>/lightningTypes/<toolCLT>/renderer.json
-    Envelope properties: actionName (text), isSuccess (boolean), outputValues (c__<responseCLT>), <plus any others>
+    Envelope properties: actionName (text), isSuccess (boolean), outputValues (c__<responseCLT>)   # exactly these three — no others
 
 WIDGET:
   Name: <widgetName>          # convention: <toolApiName>Widget
@@ -33,12 +36,11 @@ WIDGET:
     <pkgDir>/uiWidgets/<widgetName>/schema.json
     <pkgDir>/uiWidgets/<widgetName>/<widgetName>.uiwidget-meta.xml
   Schema source: derived from the response field list (name + primitive type) — a standalone contract, not tied to any Lightning Type
-  Renderer binding: each widget attribute maps to {!$attrs.outputValues.<field>}
-  Layout intent: <one-line description of the widget composition>
-  Properties omitted: <response fields the widget intentionally drops, with rationale — or "none">
-    # actionName/isSuccess never appear here — they are envelope-only and never candidates for the widget.
-    # Default omissions to declare when present in the response: isSuccess, errorMessage, status, message
-    # (operational/status indicators, not display data) — each needs its own one-line rationale, not just the field name.
+  List fields: <listField: element class @apexClassType/c__<Outer>$<Inner> — or "none">   # widget schema/body authored by platform-widget-generate
+  Renderer binding: primitive → {!$attrs.outputValues.<field>}; nested-object leaf → {!$attrs.outputValues.<objectField>.<leaf>};
+    list → {!$attrs.outputValues.<listField>} (top-level) or {!$attrs.outputValues.<wrapperField>.<listField>} (list inside wrapper)
+  Layout intent: <one-line description of the widget composition, incl. how lists are rendered>
+    # actionName/isSuccess are envelope-only fields (on the envelope CLT) and never widget candidates.
 
 SUB-SKILLS THAT WILL RUN:
   platform-custom-lightning-type-generate   (response CLT, then envelope CLT)
@@ -52,11 +54,16 @@ VALIDATIONS THAT WILL RUN AFTER GENERATION:
     - every {!$attrs.X} resolves to a widget schema property
     - <name>.uiwidget-meta.xml is well-formed, root <UiWidgetBundle>, declares <widgetType>JSON</widgetType>
   Cross-skill checks (run by this orchestrator):
-    - clt-reference-integrity: envelope CLT outputValues → c__<responseCLT>; response CLT exists; no $schema/items
+    - clt-reference-integrity: envelope CLT outputValues → c__<responseCLT>; response CLT exists; no $schema/items;
+      non-primitive response fields typed @apexClassType (no CLT-level lightning__listType — lists ride inside the object)
     - renderer-wires-widget: envelope CLT renderer.json (bundle root) references the widget via @widget/c/<widgetName>,
-      binding every widget property as {!$attrs.outputValues.<property>}
+      binding every widget property under outputValues ({!$attrs.outputValues.<property>}, or
+      {!$attrs.outputValues.<objectField>.<leaf|listField>} for nested/list fields)
+    - nested-list-coverage: every nested-object and list field discovered in Phase 2 is rendered by the widget
+      (authored by platform-widget-generate) and bound in the renderer at the correct depth. A discovered
+      nested/list field that is absent FAILS ("out of scope" / "beta single-response" are not valid drop rationales).
     - field-trace (advisory): print response @InvocableVariable fields and widget schema properties; print the diff.
-      Invented widget fields fail; omissions not declared above warn.
+      Invented widget fields fail; a response data field absent from the widget warns.
 
 GENERATION ORDER: response CLT → widget → envelope CLT (response CLT must exist before the envelope CLT references it).
 
@@ -70,5 +77,4 @@ Proceeding unless you push back (reply "no", "stop", "change X"). The plan above
 
 - If the user replies with edits or declines, revise the plan and reprint. Do not assume which sections changed.
 - Approval applies only to the plan as printed. A later request for another tool starts a new planning cycle.
-- "Properties omitted" makes intentional drops explicit — e.g. `status`, `message`, internal IDs that do not belong on the render surface.
 - If the payload source is a pasted sample that nests under `outputValues.data`, record that extra level here — it changes the response CLT and every renderer binding to `{!$attrs.outputValues.data.<field>}`.

package/skills/platform-mcp-tool-widget-coordinate/references/mcp-tool-output-discovery.md

@@ -55,8 +55,8 @@ The describe response has an `outputs` array. Each entry describes one payload f
 
 - **Use `outputs` only.** `inputs` is the tool input (the request wrapper) — exclude it, exactly as `apex` excludes the request class.
 - `name` → the CLT/widget property key. `label` → the property `title`.
-- A field with `maxOccurs > 1` is a **collection** (list). For the beta, surface it to the user in the build plan — the widget renders a single response, and list payloads need a nested item CLT (out of scope for the default flow).
-- An entry with **`"type": null` and an `"apexClass"` key instead** (e.g. `{ "name": "flightInfo", "type": null, "apexClass": "SearchFlightsAction$Flight", "maxOccurs": 1 }`) is **not missing data to default to text** — it is the describe's encoding for a field typed as another Apex class. `$` separates the outer class from the inner class, matching the `@apexClassType/<ns>__<OuterClass>$<InnerClass>` convention used elsewhere in this skill. This is the same case as a `List<ApexClass>`/nested-object field from the other two sources — see "Nested-object payload fields" below; the Actions REST API describe never exposes that class's own leaf fields, so retrieving/reading the Apex class named in `apexClass` (via `apex` §1/§3) is the correct next step, not a fallback away from `action`.
+- A field with `maxOccurs > 1` is a **collection** (list) — it is in scope, not out of scope. If its `apexClass` is set (a list of nested objects) or its `type` is a primitive (a list of scalars), render it as a collection per "Nested-object and list payload fields" below; never drop it silently. (The `content[]` beta single-response limit is about rendering one tool *result*, not about list *fields* inside that result.)
+- An entry with **`"type": null` and an `"apexClass"` key instead** (e.g. `{ "name": "flightInfo", "type": null, "apexClass": "SearchFlightsAction$Flight", "maxOccurs": 1 }`) is **not missing data to default to text** — it is the describe's encoding for a field typed as another Apex class. `$` separates the outer class from the inner class, matching the `@apexClassType/<ns>__<OuterClass>$<InnerClass>` convention used elsewhere in this skill. This is the same nested-object / list-of-objects case as from the other two sources — see "Nested-object and list payload fields" below (`maxOccurs: 1` → single object; `maxOccurs > 1` → list of that object); the Actions REST API describe never exposes that class's own leaf fields, so retrieving/reading the Apex class named in `apexClass` (via `apex` §1/§3) is the correct next step, not a fallback away from `action`.
 
 Extract the field list with `jq` (do NOT wrap in `$()`):
 
@@ -156,29 +156,62 @@ If the grep misses multi-line annotations, read the `.cls` with the Read tool an
 
 ---
 
-## Nested-object payload fields (applies to every source above)
+## Nested-object and list payload fields (applies to every source above)
 
-The mapping tables above (Actions-API `type`, Apex type, JSON value/schema `type`) cover **primitive** fields. A field can also be typed as **another Apex class** instead of a primitive — e.g. `GetFlightDetailsAction.FlightDetailsResponse.flightInfo`, typed `SearchFlightsAction.Flight`. This is a second, additive branch — check every payload field against it, regardless of which of the three sources produced the field list:
+The mapping tables above (Actions-API `type`, Apex type, JSON value/schema `type`) cover **primitive** fields. A field can also be typed as **another Apex class** — as a single object or as a list of them. Both are in scope; check every payload field against both branches, regardless of which of the three sources produced the field list. Detect a nested/list field by source:
 
-- **Actions API**: an output entry with `"type": null` and an `"apexClass": "<OuterClass>$<InnerClass>"` key, rather than a primitive `STRING`/`INTEGER`/etc. `type` (see step 3 above).
-- **`apex`**: an `@InvocableVariable` field whose declared type is not `String`/`Id`/`Integer`/`Long`/`Decimal`/`Double`/`Boolean`/`Date`/`Datetime` but another Apex class.
-- **`sample`**: a property whose JSON value/schema `type` is `"object"` (not a primitive).
+- **Actions API**: an output entry with `"type": null` and an `"apexClass": "<OuterClass>$<InnerClass>"` key, rather than a primitive `STRING`/`INTEGER`/etc. `type` (see step 3 above). `maxOccurs: 1` → single object; `maxOccurs > 1` → list of that object.
+- **`apex`**: an `@InvocableVariable` field whose declared type is not `String`/`Id`/`Integer`/`Long`/`Decimal`/`Double`/`Boolean`/`Date`/`Datetime` — either another Apex class (single object) or `List<ApexClass>` (list of objects).
+- **`sample`**: a property whose JSON value/schema `type` is `"object"` (single object) or `"array"` of objects (list).
 
-**Never** model such a field as `{"type":"object"}` (opaque, unrenderable) or inline it as a nested `lightning__objectType` (rejected by the CLT metaschema — same rule as the envelope↔response relationship). Instead:
+**Never** model such a field as `{"type":"object"}` (opaque, unrenderable) or inline it as a nested `lightning__objectType` (rejected by the CLT metaschema — same rule as the envelope↔response relationship).
+
+> **Enumerating a referenced/inner Apex class — use its public/`@AuraEnabled` members, not `@InvocableVariable`** (SKILL.md Hard Rule 6: the invocable annotation gates only the top-level response class; an inner class's leaves are never in the describe, so grepping it for `@InvocableVariable` enumerates zero leaves). The grep:
+>
+> ```bash
+> # Inner/referenced class leaves — public/@AuraEnabled members (NOT @InvocableVariable).
+> echo "INNER_FIELDS:"
+> grep -oE '(public|global)\s+[A-Za-z0-9_<>,\s]+\s+[a-zA-Z_][a-zA-Z0-9_]*\s*;' \
+>   <pkgDir>/classes/<OuterClass>.cls \
+>   | sed -E 's/.*\s([a-zA-Z_][a-zA-Z0-9_]*)\s*;/\1/' \
+>   | sort -u
+> # Scope to the inner class block; @AuraEnabled fields have no @InvocableVariable line above them.
+> # If the grep misses multi-line declarations, Read the .cls and list the inner class fields manually.
+> ```
+
+### Single nested object (`maxOccurs: 1`)
+
+`<objectField>` throughout this section is the output entry's own `name` from the describe (e.g. `flightInfo`) — the property key that carries the object, used verbatim in the response CLT property name and the renderer binding path. It is never an invented label.
 
 1. Type the response CLT property as `"@apexClassType/<ns>__<OuterClass>$<InnerClass>"` (e.g. `"@apexClassType/c__SearchFlightsAction$Flight"`) — the same convention `platform-custom-lightning-type-generate` documents for Apex-backed CLTs.
-2. Enumerate the referenced Apex class's own fields (its own `@InvocableVariable`/public members) — these become the widget's leaf properties. The object field itself never appears on the widget.
+2. Enumerate the referenced Apex class's own fields by its **public / `@AuraEnabled`** members (see the callout above — inner classes are *not* gated by `@InvocableVariable`) — these become the widget's leaf properties. The object field itself never appears on the widget.
 3. Bind the renderer one level deeper: `{!$attrs.outputValues.<objectField>.<leaf>}` (e.g. `{!$attrs.outputValues.flightInfo.flightId}`), not `{!$attrs.outputValues.<objectField>}`.
-4. A field typed `List<ApexClass>` (a list of nested objects, not a single one) is out of scope for the beta single-response flow — surface it in the build plan like a `maxOccurs > 1` scalar rather than emitting a schema for it.
 
-See `references/two-clt-modeling.md` ("Nested-object payload fields") for the worked JSON, and `examples/nested-object-source-prompt.md` for the full end-to-end walkthrough.
+### List of nested objects (`List<ApexClass>` / `maxOccurs > 1` with an `apexClass`)
+
+A list of nested objects is **in scope** — a real, boundary-crossing, renderable field. Do **not** declare it "out of scope" and do **not** drop it silently. In a response CLT the list is **always a plain `@apexClassType/...` reference** (the CLT metaschema forbids `lightning__listType`/`items` on a response-CLT property — `unevaluatedProperties: false`); the list-ness surfaces in the *widget* schema. **Never touch the Apex to make a list renderable** — both list positions below bind directly, no wrapper reshape.
+
+> **The binding depth equals the list's position in the describe — read it off the describe, never apply a transform.** Two positions, both directly bindable:
+> - **Top-level list output** — the describe surfaces the list itself as an output entry: `apexClass` set + `maxOccurs > 1` (e.g. `GetLeadsList` → `leads`, `apexClass: GetLeadsList$LeadSummary`, `maxOccurs: 2000`), often alongside scalar sibling outputs (`leadCount`, `status`). Type the response CLT property **directly** as `@apexClassType/c__<Outer>$<ElementClass>` (the element/summary class) and bind the renderer at **two segments**: `{!$attrs.outputValues.<listField>}` (e.g. `{!$attrs.outputValues.leads}`). *No Apex change, no wrapper.*
+> - **List inside a wrapper object** — the describe returns exactly ONE `apexClass` output with `maxOccurs: 1` (e.g. `GetShipmentDetails` → `shipmentDetailsResponse`), and the list is a field *inside* that class that the describe **does not surface**. Read the inner Apex class (via the `apex` source / apex describe) and enumerate its **public / `@AuraEnabled`** members — not `@InvocableVariable` (see the referenced/inner-class callout above) — to discover the list field, type the response CLT property as the wrapper class `@apexClassType/c__<Outer>$<ResponseClass>`, and bind the renderer at **three segments**: `{!$attrs.outputValues.<wrapperField>.<listField>}` (e.g. `{!$attrs.outputValues.shipmentDetailsResponse.statusUpdates}`).
+>
+> Whichever position, the response CLT property is a single `@apexClassType/...` reference — the extra binding depth for the wrapper case comes from the wrapper level in the describe, not from any reshape. See `references/two-clt-modeling.md` ("Top-level list vs list-inside-wrapper") for the worked JSON.
+
+1. **Response CLT:** type the list as a plain `@apexClassType/...` reference — `c__<Outer>$<ElementClass>` for a top-level list output, or `c__<Outer>$<ResponseClass>` (the wrapper class, whose interior list field you found by reading the class) for a list-inside-wrapper. Do NOT add a `lightning__listType` property to the CLT.
+2. **Renderer:** bind the list at the depth its describe position dictates — **two segments** `{!$attrs.outputValues.<listField>}` for a top-level list output, or **three segments** `{!$attrs.outputValues.<wrapperField>.<listField>}` for a list inside a wrapper object (never `.<leaf>`).
+
+The **widget bundle** (schema + body) that surfaces and iterates the list is authored and validated by `platform-widget-generate` — this skill does not specify the widget's `lightning__listType`/`items` schema property or its iteration mechanism.
+
+A `List<InnerClass>` collection is never omitted — it is domain data and is always rendered.
+
+See `references/two-clt-modeling.md` ("Nested-object and list payload fields") for the worked JSON, and `examples/nested-object-single-source-prompt.md` (single object) / `examples/nested-object-list-source-prompt.md` (lists) for the full end-to-end walkthroughs.
 
 ## Output of Phase 2
 
-`payloadFields` — an ordered list of `{ name, title, lightning:type }` describing the response payload (primitive fields), plus any nested-object fields resolved to `@apexClassType/...` per above. This drives:
+`payloadFields` — an ordered list of `{ name, title, lightning:type }` describing the response payload (primitive fields), plus any nested-object or list-of-object fields resolved to `@apexClassType/...` per above. A list-of-object field rides inside an `@apexClassType` object (it is not a CLT-level `lightning__listType`); it surfaces as a `lightning__listType` with an `items` element type in the **widget** schema. This drives:
 
-- the **response CLT** `properties` (CLT type vocabulary, `lightning__integerType` allowed, `@apexClassType/...` for nested-object fields),
-- the **widget schema** `properties.attributes.properties` (widget type vocabulary, numerics → `lightning__numberType`; nested-object fields flattened to their leaf properties),
-- the **renderer** attribute bindings (`{!$attrs.outputValues.<name>}` for primitives, `{!$attrs.outputValues.<objectField>.<leaf>}` for nested-object leaves).
+- the **response CLT** `properties` (CLT type vocabulary, `lightning__integerType` allowed, `@apexClassType/...` for single nested-object fields and for the object a list rides inside — never `lightning__listType`/`items` in the CLT),
+- the **widget schema** (authored by `platform-widget-generate` — flat leaf properties for single nested-object fields, and a list property for list-of-object fields; this skill supplies the field list and element typing, not the widget schema/body shape),
+- the **renderer** attribute bindings (`{!$attrs.outputValues.<name>}` for primitives, `{!$attrs.outputValues.<objectField>.<leaf>}` for single nested-object leaves, `{!$attrs.outputValues.<listField>}` / `{!$attrs.outputValues.<wrapperField>.<listField>}` for list fields at the depth the describe dictates).
 
 Whichever source produced the fields, record it in the build plan so the reviewer knows whether the schema came from the live org (`action`), source (`apex`), or an example (`sample`).

package/skills/platform-mcp-tool-widget-coordinate/references/two-clt-modeling.md

@@ -1,6 +1,6 @@
 # Two-CLT Modeling for an MCP Tool Output
 
-A custom MCP server tool backed by an Apex Invocable Action returns the platform's **invocable-action result envelope**. The real payload the tool consumer cares about lives under `outputValues`; the surrounding fields (`actionName`, `isSuccess`, `errors`, `sortOrder`, `version`, …) are envelope metadata.
+A custom MCP server tool backed by an Apex Invocable Action returns the platform's **invocable-action result envelope**. The real payload the tool consumer cares about lives under `outputValues`; the surrounding fields (`errors`, `sortOrder`, `version`, …) are envelope metadata and are not modeled — the envelope CLT declares only `actionName`, `isSuccess`, `outputValues`.
 
 To render this with an HXL widget we model it as **two object-based CLTs** and wire them with a renderer that bridges the nesting. Both are ordinary CLTs of equal standing — nothing in the platform or the metaschema distinguishes an "envelope type" from a "response type." The only reason two files exist is that one CLT (the envelope) must reference the other (the response) by name via `c__<name>`, and a CLT cannot reference itself — so the two need distinct deployed names, nothing more. Don't invent a role-label pair for the two CLTs themselves ("Payload CLT"/"Envelope CLT", "Outer CLT"/"Inner CLT") — name and describe each by what it actually models (see below), and in prose refer to them by that same identifier: "the `<toolApiName>` envelope" / "the `<toolApiName>Response`". ("Payload" and "response" remain fine as ordinary words for the data itself — e.g. "response fields", "the payload the tool consumer cares about" — the rule is about not naming or labeling the *CLTs* by an invented role.)
 
@@ -20,8 +20,6 @@ To render this with an HXL widget we model it as **two object-based CLTs** and w
 - Both CLT names are derived from the **same single `<toolApiName>`** — there is no separate naming decision to make per artifact, and no free-standing role word (no "Result", "OutputValues", "Payload", "Envelope", and no `_CLT` suffix either — a Lightning Type is identified by living under `lightningTypes/`, not by a suffix on its name). `Response` is not a role label; it is literally what the class is (the Invocable Action's declared `List<...Response>` return-element type) — the same word the Apex source itself already uses (e.g. `GetAccountSummaryResponse`, `FlightDetailsResponse`).
 - The envelope CLT is *structurally* generic but **cannot be a single shared CLT** — its `outputValues` must be typed to a tool-specific response CLT via `c__<responseCLT>`. One envelope CLT per tool.
 
-> **Naming convention supersedes the earlier hand-verified prototype.** Two bundles were manually fixed and successfully deployed during development using an older `<toolApiName>Result` / `<toolApiName>OutputValues` naming pair — that proved the *structural* pattern (two object-based CLTs, `@apexClassType` for nested fields, two-level renderer bindings) deploys correctly. The naming convention above replaces those two suffixes; every other structural rule in this file (root keys, `unevaluatedProperties`, the `c__` reference, nested-object typing, renderer bindings) is unchanged and still matches what was verified.
-
 ## Response CLT
 
 Object-based CLT whose `properties` are exactly the response `@InvocableVariable` fields (1:1). Root `lightning:type` is `lightning__objectType`. `platform-custom-lightning-type-generate` injects and enforces `"unevaluatedProperties": false` on every object-based CLT (its metaschema rejects a CLT without it) — this orchestrator does not fight that, it matches it in every example and every generated file. Give both CLTs a real, tool-specific `description` (never `""`) — it is what a consumer sees when picking a referenced CLT. Both CLTs also carry a root-level `"lightning:tags": ["mcp"]` — it marks the type as MCP-tool-generated per `platform-custom-lightning-type-generate/assets/primitive-types-and-constraints.md`.
@@ -43,14 +41,18 @@ Object-based CLT whose `properties` are exactly the response `@InvocableVariable
 }
 ```
 
-### Nested-object payload fields (a second, additive case)
+> **Response CLT properties are 1:1 with the describe outputs — never an invented wrapper.** The response CLT's top-level property names equal the describe's `outputs[].name` set (for `apex`/`sample`, the response class's `@InvocableVariable` field names). A describe with **N sibling outputs** → **N flat properties** (the `GetAccountSummary` example above; `GetLeadsList` → `leadCount`, `leads`, `message`, `status`); a describe with **one output** → **one property named after it** (`GetShipmentDetails` → `shipmentDetailsResponse`, `GetFlightDetails` → `flightInfo`). Do **not** collapse several sibling outputs into one lone property such as `leadsListResponse` — that key appears in no describe output and is unresolvable under `action` (the response-class name is never in `outputs[]`). A single-property response CLT is correct only when the describe itself returns a single output. This is enforced by `clt-reference-integrity` check 5 (`PROP_GROUNDING`).
+
+### Nested-object and list payload fields (a second, additive case)
+
+The example above covers a **flat** payload — every `@InvocableVariable` field is a primitive. Some invocable responses instead have a field whose type is **itself an Apex class** — either a single object (e.g. `GetFlightDetailsAction.FlightDetailsResponse.flightInfo`, typed `SearchFlightsAction.Flight`) or a **list** of them (e.g. the `GetShipmentDetails` wrapper's `shipmentDetailsResponse.statusUpdates`, typed `List<StatusUpdateResponse>`). All three shapes — flat, single-object, list-of-objects — are in scope; pick the branch per field. In every case:
 
-The example above covers a **flat** payload — every `@InvocableVariable` field is a primitive. Some invocable responses instead have a field whose type is **itself an Apex class** (e.g. `GetFlightDetailsAction.FlightDetailsResponse.flightInfo`, typed `SearchFlightsAction.Flight`). Both shapes are in scope; pick the branch per field:
+- **Never** type the property as a bare `{"type":"object"}` (opaque, unrenderable, and not what deploys) and **never** inline it as a nested `lightning__objectType` (rejected by the CLT metaschema, same as the envelope↔response relationship below).
+
+#### Single nested object
 
-- **Never** type that property as a bare `{"type":"object"}` (opaque, unrenderable, and not what deploys) and **never** inline it as a nested `lightning__objectType` (rejected by the CLT metaschema, same as the envelope↔response relationship below).
 - **Do** type it as `"@apexClassType/<ns>__<OuterClass>$<InnerClass>"` — e.g. `"lightning:type": "@apexClassType/c__SearchFlightsAction$Flight"` — exactly the Apex-backed-CLT convention `platform-custom-lightning-type-generate` already documents for `@apexClassType/namespace__ClassName$InnerClass`.
-- The **widget** and **renderer** then flatten through it — see the nested-binding note at the end of the "Default renderer" section below, and the full walkthrough in `examples/nested-object-source-prompt.md`.
-- A field typed `List<ApexClass>` (a list of nested objects) is out of scope for the beta single-response flow — surface it in the build plan rather than emitting a schema for it, the same way a `maxOccurs > 1` scalar is surfaced.
+- The **widget** and **renderer** then flatten through it — see the nested-binding note at the end of the "Default renderer" section below, and the full walkthroughs in `examples/nested-object-single-source-prompt.md` (single object) and `examples/nested-object-list-source-prompt.md` (lists).
 
 ```json
 {
@@ -69,6 +71,61 @@ The example above covers a **flat** payload — every `@InvocableVariable` field
 }
 ```
 
+#### List of nested objects
+
+A `List<ApexClass>` field (an Actions-API output with `apexClass` set and `maxOccurs > 1`, or an `@InvocableVariable List<Inner>` in source) is **in scope** — a real, renderable, boundary-crossing field. It is NOT out of scope for the beta: the `content[]` single-response limit governs how many tool *results* render (one), not list *fields* inside that one result. Render it as a collection; never drop it silently.
+
+> **A list is bindable in whichever position the describe returns it — never reshape the Apex to move it.** Two positions occur, and both bind directly: (a) a **top-level list output** — the describe returns the list as its own output entry (`apexClass` set, `maxOccurs > 1`, e.g. a flat `GetLeadsList` whose `leads` output is `maxOccurs: 2000`); the response CLT types that property **directly** as `@apexClassType/c__<Outer>$<ElementClass>` and the renderer binds it at two segments, `{!$attrs.outputValues.<listField>}`. (b) a **list inside a single wrapper object** — the describe returns ONE output (`apexClass`, `maxOccurs: 1`, e.g. `GetShipmentDetails` → `shipmentDetailsResponse`) whose class *contains* the list (`statusUpdates`); the renderer binds it at three segments, `{!$attrs.outputValues.<wrapper>.<listField>}`. See "Top-level list vs list-inside-wrapper" below. In neither case does the CLT declare a `lightning__listType`/`items` — the list-typed property is always a plain `@apexClassType/...` reference.
+
+The rule is that **a list-typed CLT property is always a plain `@apexClassType/...` reference — the object-based response CLT never declares the list as a `lightning__listType` property itself.** The `@apexClassType` describe layer resolves the list and its element type; the list surfaces as a `lightning__listType` in the *widget* schema, not the CLT. Which class the reference names, and how deep the renderer binds, depend on the list's **position in the describe** (see "Top-level list vs list-inside-wrapper" below). Concretely:
+
+- **Response CLT:** the list-typed property is a plain `@apexClassType` reference (never a `lightning__listType`, never `items`). For a **top-level list output** (flat `GetLeadsList` → `leads`, `maxOccurs: 2000`) the property names the **element** class directly — `leads → @apexClassType/c__GetLeadsList$LeadSummary` — and the CLT carries that property itself. For a **list inside a wrapper** (`GetShipmentDetails` → `shipmentDetailsResponse`) the CLT carries the **wrapper** property — `shipmentDetailsResponse → @apexClassType/c__GetShipmentDetails$GetShipmentDetailsResponse` — and the `List<StatusUpdateResponse>` lives inside that class (discovered by reading it, not from the describe). Either way the CLT gets **no** `lightning__listType` property.
+- **Renderer:** bind the list at the depth its position dictates (NOT `.<leaf>` in either case): `{!$attrs.outputValues.<listField>}` (two segments) for a **top-level list output** (e.g. `{!$attrs.outputValues.leads}`), or `{!$attrs.outputValues.<objectField>.<listField>}` (three segments) for a **list inside a wrapper** (e.g. `{!$attrs.outputValues.shipmentDetailsResponse.statusUpdates}`). This bridges the envelope to the widget's flat `{!$attrs.<listField>}`.
+
+How the widget bundle surfaces the list (its `lightning__listType` + `items` schema property) and iterates the items is authored and validated by `platform-widget-generate` — not by this skill.
+
+Deployed response CLT (the list is NOT here — it rides inside the `@apexClassType` object):
+
+```json
+{
+  "title": "Get Shipment Details Response",
+  "description": "Payload fields returned by the GetShipmentDetails invocable action",
+  "type": "object",
+  "lightning:type": "lightning__objectType",
+  "lightning:tags": ["mcp"],
+  "unevaluatedProperties": false,
+  "properties": {
+    "shipmentDetailsResponse": {
+      "title": "Shipment Details Response",
+      "lightning:type": "@apexClassType/c__GetShipmentDetails$GetShipmentDetailsResponse"
+    }
+  }
+}
+```
+
+Deployed renderer binding (list bound one level through the object; the widget iterates the items):
+
+```json
+{ "statusUpdates": "{!$attrs.outputValues.shipmentDetailsResponse.statusUpdates}" }
+```
+
+The widget schema property for the list (`lightning__listType` + `items`) and the widget body that iterates it are authored by `platform-widget-generate`.
+
+#### Top-level list vs list-inside-wrapper (which position the describe returns the list in)
+
+**The describe is the source of truth, and the list is renderable in whichever position it returns — never touch the Apex to move it.** Two positions occur in practice. They differ ONLY in renderer binding depth:
+
+| Position | Actions describe `outputs` | Response CLT list property | Renderer binding |
+|---|---|---|---|
+| **Top-level list output** (e.g. flat `GetLeadsList`) | The list is its **own** output entry — `apexClass` set, `maxOccurs > 1` (e.g. `leads` → `apexClass: GetLeadsList$LeadSummary`, `maxOccurs: 2000`), beside sibling scalars | `leads` → `@apexClassType/c__GetLeadsList$LeadSummary` (the **element** class) | **Two segments:** `{!$attrs.outputValues.leads}` |
+| **List inside a wrapper** (e.g. `GetShipmentDetails`) | ONE output — `shipmentDetailsResponse` · `apexClass` set · `maxOccurs: 1`; the list is a field **inside** that class (`statusUpdates`), which the describe does NOT surface | `shipmentDetailsResponse` → `@apexClassType/c__GetShipmentDetails$GetShipmentDetailsResponse` (the **wrapper** class; the list is discovered by reading it) | **Three segments:** `{!$attrs.outputValues.shipmentDetailsResponse.statusUpdates}` |
+
+**A top-level `@apexClassType` list binds directly.** A response CLT that types a top-level list property directly as `@apexClassType/c__<Outer>$<ElementClass>`, with an envelope whose renderer binds `{!$attrs.outputValues.<listField>}` (two segments, no wrapper hop), is a valid, deployable shape. There is no need for — and the skill must not perform — any Apex reshaping (no wrapper class, no `List<Wrapper>` return-type change) to render a top-level list. The Apex is never modified by this skill.
+
+**Typing facts:**
+- A response CLT list property **must** be a plain `@apexClassType/c__<Outer>$<ElementClass>` reference. Typing it as `lightning__listType` with an `items` element type is **rejected** by the CLT metaschema (*"You can't add the items property … because the `unevaluatedProperties` keyword value is set to false"*). `items`/`lightning__listType` belong to the **widget** schema only.
+- The binding depth is dictated purely by the list's position in the describe (two segments for a top-level output, three for a list inside a wrapper) — not by any transform you apply.
+
 ## Envelope CLT
 
 Object-based CLT that mimics the tool-result envelope. `outputValues` is typed to the response CLT via the referenced-CLT pattern `c__<responseCLT>` — **not** inlined as a nested `lightning__objectType` (nested object typing is rejected by the CLT metaschema; see `platform-custom-lightning-type-generate`).
@@ -91,7 +148,7 @@ Object-based CLT that mimics the tool-result envelope. `outputValues` is typed t
 
 - The `c__<responseCLT>` string is the referenced type's **registered identifier / FQN**, not its `title`. It must match the response CLT's deployed name.
 - The response CLT must be deployed **before** the envelope CLT.
-- Include only the envelope scalars the widget or the platform needs (`actionName`, `isSuccess`, and `outputValues` at minimum). Add `message` etc. only when rendered.
+- Include only the envelope scalars the widget or the platform needs (`actionName`, `isSuccess`, and `outputValues` only). Add `message` etc. only when rendered. `outputValues` is the load-bearing field the renderer bridges through; the widget renders the payload under it, never the envelope metadata (`actionName`/`isSuccess`).
 
 ## Default renderer (in the ENVELOPE CLT)
 
@@ -117,7 +174,13 @@ The renderer is the **default `renderer.json` at the envelope CLT bundle root**,
 
 **The binding path is the crux:** each widget attribute (left, flat) maps to the response field nested under the envelope's `outputValues` node (right) via `{!$attrs.outputValues.<field>}`. Because the envelope CLT's `outputValues` is typed to the response CLT, the runtime can resolve `outputValues.<field>` against the response CLT's `properties`.
 
-**Nested-object response fields bind one level deeper.** When a response field is itself an Apex-class reference (the `flightInfo` case above), the widget flattens to that class's own leaf fields, and the renderer binding goes two levels deep: `{!$attrs.outputValues.flightInfo.flightId}`, `{!$attrs.outputValues.flightInfo.origin}`, etc. — `outputValues.<objectField>.<leaf>`, not `outputValues.<objectField>` alone (which would bind the widget to an unresolvable object, not a renderable leaf).
+**Nested-object response fields bind one level deeper.** When a response field is itself a single Apex-class reference (the `flightInfo` case above), the widget flattens to that class's own leaf fields, and the renderer binding goes two levels deep: `{!$attrs.outputValues.flightInfo.flightId}`, `{!$attrs.outputValues.flightInfo.origin}`, etc. — `outputValues.<objectField>.<leaf>`, not `outputValues.<objectField>` alone (which would bind the widget to an unresolvable object, not a renderable leaf).
+
+**List-of-object response fields bind the list, not the leaves — at a depth set by the list's position.** A `List<ApexClass>` returned as a **top-level output** (flat `GetLeadsList` → `leads`) binds at two segments — `{!$attrs.outputValues.leads}`. A `List<ApexClass>` that lives **inside a wrapper object** (`GetShipmentDetails` → `shipmentDetailsResponse.statusUpdates`) binds at three — `{!$attrs.outputValues.shipmentDetailsResponse.statusUpdates}`. Do NOT append `.<leaf>` to the list binding in the renderer — there is no single leaf to bind at the list level; the widget (authored by `platform-widget-generate`) iterates the list and renders each item's leaves. The renderer binding depth is set by the describe position.
+
+> **The list binding must still go through the renderer's `outputValues` path.** A common failure is a widget that iterates the list correctly but whose *renderer* binds the list flat — `"leads": "{!$attrs.leads}"` instead of `"leads": "{!$attrs.outputValues.<wrapper>.leads}"`. The flat renderer binding resolves against the envelope root, where the payload does not live, so the widget renders "No data available" even though the widget body is correct. Every list is wired through the `outputValues` bridge.
+
+> **A renderer attribute CAN bind a top-level `@apexClassType` list directly.** The bindable right-hand paths are: a primitive (`outputValues.<field>`), a **top-level `@apexClassType` list** (`outputValues.<listField>`, e.g. `outputValues.leads` — two segments), or a leaf/list reached *through* one `@apexClassType` wrapper (`outputValues.<wrapper>.<leaf>` / `outputValues.<wrapper>.<listField>` — three segments). There is no "top-level `@apexClassType` list is unbindable" constraint, and the skill must never reshape the Apex to a wrapper to render a top-level list. Bind at the depth the describe's position dictates and leave the Apex untouched.
 
 ## Why two CLTs and not one