@salesforce/afv-skills 1.34.0 → 1.36.0

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

@@ -0,0 +1,85 @@
+# Example: Pasted tool-output source
+
+A complete walkthrough of the flow when the payload source is a pasted MCP tool-output JSON sample and no Apex class is available (`source = sample`).
+
+## The prompt
+
+> Here's what my MCP tool returns. Build a widget for it.
+>
+> ```json
+> {
+>   "actionName": "GetOrderStatus",
+>   "isSuccess": true,
+>   "outputValues": {
+>     "orderId": "80100000ABC",
+>     "orderNumber": "ORD-4471",
+>     "status": "Shipped",
+>     "itemCount": 3,
+>     "orderTotal": 249.95,
+>     "expedited": true
+>   }
+> }
+> ```
+
+## Phase 1 — Input selection
+
+- Source: `sample` (the prompt pastes a tool-output envelope; no Apex class referenced).
+- Tool API name: `getOrderStatus` (from `actionName`).
+
+## Phase 2 — Payload discovery
+
+Read `references/mcp-tool-output-discovery.md`, then parse the `outputValues` object. Infer each `lightning:type` from the JSON value:
+
+| Field | JSON value | Inferred CLT `lightning:type` |
+|---|---|---|
+| orderId | `"80100000ABC"` (string) | `lightning__textType` |
+| orderNumber | `"ORD-4471"` (string) | `lightning__textType` |
+| status | `"Shipped"` (string) | `lightning__textType` |
+| itemCount | `3` (integer) | `lightning__integerType` |
+| orderTotal | `249.95` (fractional) | `lightning__numberType` |
+| expedited | `true` (boolean) | `lightning__booleanType` |
+
+Envelope keys confirmed against the sample: `actionName`, `isSuccess`, `outputValues`. **No extra nesting** — `outputValues.<field>` is flat, so bindings will be `{!$attrs.outputValues.<field>}`.
+
+> If the sample had nested the payload one level deeper (e.g. `outputValues.data.orderId`), the response CLT would model that `data` object and every renderer binding would be `{!$attrs.outputValues.data.<field>}`. Call this out in the plan.
+
+`payloadFields` = the 6 rows above.
+
+## Phase 3 — Build plan (abridged)
+
+```text
+MCP Tool Widget Build Plan: getOrderStatusWidget
+
+PLAN: Render the GetOrderStatus MCP tool output as an order-status card.
+
+TOOL / SOURCE:
+  Tool API name: getOrderStatus
+  Payload source: pasted tool-output sample
+
+LIGHTNING TYPES:
+  Response CLT:  getOrderStatusResponse   (6 payload properties)
+  Envelope CLT: getOrderStatus
+    Renderer (default, bundle root): .../lightningTypes/getOrderStatus/renderer.json
+    Envelope: actionName (text), isSuccess (boolean), outputValues (c__getOrderStatusResponse)
+
+WIDGET: getOrderStatusWidget
+  Renderer binding: each attribute → {!$attrs.outputValues.<field>}
+  Properties omitted: none
+
+GENERATION ORDER: response CLT → widget → envelope CLT
+```
+
+Proceed unless the next reply pushes back.
+
+## Phase 4 — Generation order
+
+1. Response CLT `getOrderStatusResponse` — `lightning__objectType`, 6 properties (numerics: `itemCount` → `lightning__integerType` in the CLT but `lightning__numberType` in the widget schema; `orderTotal` → `lightning__numberType` in both).
+2. Envelope CLT `getOrderStatus` — `actionName`, `isSuccess`, `outputValues` → `c__getOrderStatusResponse`.
+3. Widget `getOrderStatusWidget` — flat schema over the 6 payload fields; body binds `{!$attrs.orderNumber}` etc.
+4. Default renderer at `lightningTypes/getOrderStatus/renderer.json` — `definition: @widget/c/getOrderStatusWidget`, each attribute `{!$attrs.outputValues.<field>}`.
+
+## Phase 5 — Validation
+
+- `clt-reference-integrity`: envelope `outputValues` → `c__getOrderStatusResponse`, response CLT exists, no `$schema`/`items` → **pass**.
+- `renderer-wires-widget`: bundle-root renderer present, definition `@widget/c/getOrderStatusWidget`, all 6 bindings nested under `outputValues` → **pass**.
+- `field-trace`: source is a sample, so INVOCABLE_FIELDS = `outputValues` keys; INVENTED empty, OMITTED empty → **pass**.

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

@@ -0,0 +1,74 @@
+# Build Plan Format
+
+Use this template in Phase 3 to print the plan before proceeding. Fill every section. Do not abbreviate. Do not print inside a code fence the user might mistake for output — the plan is conversational.
+
+---
+
+```text
+MCP Tool Widget Build Plan: <widgetName>
+
+PLAN: <one line in developer-facing terms, e.g.:
+  "Render the GetAccountSummary MCP tool output with an account-summary widget">
+
+TOOL / SOURCE:
+  Tool API name: <toolApiName>
+  Payload source: <action: Actions REST describe of <ActionApiName> | apex: class <ClassName> | sample: pasted tool-output>
+  Response class FQN: <namespace>__<ClassName>.<ResponseClass>   # apex source only; omit for action/sample
+
+LIGHTNING TYPES (two object-based CLTs of equal standing — named for what each models, not by role; both carry root-level "lightning:tags": ["mcp"]):
+  Response CLT:
+    Name: <responseCLT>          # convention: <toolApiName>Response
+    Path: <pkgDir>/lightningTypes/<responseCLT>/schema.json
+    Properties: <field: lightning:type, ...>   # 1:1 with response @InvocableVariable fields
+  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>
+
+WIDGET:
+  Name: <widgetName>          # convention: <toolApiName>Widget
+  Output:
+    <pkgDir>/uiWidgets/<widgetName>/<widgetName>.json
+    <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.
+
+SUB-SKILLS THAT WILL RUN:
+  platform-custom-lightning-type-generate   (response CLT, then envelope CLT)
+  platform-widget-generate                  (widget bundle)
+  (renderer.json authored inline in the envelope CLT by this orchestrator)
+
+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} 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
+    - renderer-wires-widget: envelope CLT renderer.json (bundle root) references the widget via @widget/c/<widgetName>,
+      binding every widget property as {!$attrs.outputValues.<property>}
+    - field-trace (advisory): print response @InvocableVariable fields and widget schema properties; print the diff.
+      Invented widget fields fail; omissions not declared above warn.
+
+GENERATION ORDER: response CLT → widget → envelope CLT (response CLT must exist before the envelope CLT references it).
+
+----------------------------------------------------------------
+Proceeding unless you push back (reply "no", "stop", "change X"). The plan above is the record of intent.
+```
+
+---
+
+## Notes for the model
+
+- 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

@@ -0,0 +1,184 @@
+# MCP Tool Output Discovery
+
+Phase 2 resolves the payload shape that defines the response CLT and the widget schema. There are three sources, in order of preference: an invocable action API name (`action`), a pasted tool-output sample (`sample`), or an Apex Invocable class (`apex`).
+
+---
+
+| Source | Use when | Authority |
+|---|---|---|
+| `action` | An **invocable action API name** is known — directly, or from a class name that resolves to one. **Preferred.** | The org's Actions REST API describes the action's typed outputs directly — it already excludes the request wrapper and private helpers. |
+| `sample` | The describe 404s or no org is reachable, but a pasted tool-output JSON is available. | Infers types from example values. |
+| `apex` | Only the Apex **class** name is known, and no org and no sample are available — fallback only, may be stale relative to what's deployed. | Parses `@InvocableVariable` fields from source. |
+
+Prefer `action` whenever an action name (directly given, or derived from a class name that resolves to a single invocable action) and an authenticated org are available — it is the same schema the platform itself exposes, so it needs no request/helper filtering and gives real field types. Fall back to `sample`, then `apex`.
+
+---
+
+## `action` — resolve from the invocable action name (preferred)
+
+The Salesforce **Actions REST API** describes any custom Apex invocable action, including its output variables and their types. This is authoritative: the `outputs` it returns are exactly the `@InvocableVariable` fields on the response class — the request wrapper and private helper classes never appear.
+
+### 1. Confirm the action API name
+
+For an Apex invocable action the action API name is the **Apex class name** that declares the `@InvocableMethod` (e.g. `GetAccountSummaryTest`), not the method label. If the user gave a label ("Get Account Summary") resolve it to the class name — the class name is what the endpoint path uses.
+
+### 2. Describe the action
+
+```bash
+sf api request rest '/services/data/v63.0/actions/custom/apex/<ActionApiName>' -o <org>
+```
+
+`<ActionApiName>` is the Apex class name. Use the org's API version (`v63.0` here — match `sourceApiVersion` in `sfdx-project.json` or the org's max). If the org alias is the default, `-o <org>` may be omitted. (`sf api request rest ...` is the form used elsewhere in this repo; `sf org api request rest ...` is an equivalent alias.)
+
+To list all custom Apex actions first (when the exact name is unknown) — the action names are under `.actions[].name`:
+
+```bash
+sf api request rest '/services/data/v63.0/actions/custom/apex' -o <org> | jq -r '.actions[].name'
+```
+
+If the describe returns 404 / `NOT_FOUND`, the action is not deployed or is not exposed as a custom Apex action — fall back to `sample` (a pasted tool-output JSON) if one is available, else `apex` (parse the class), and surface the miss.
+
+### 3. Read the `outputs` array
+
+The describe response has an `outputs` array. Each entry describes one payload field:
+
+```json
+{
+  "outputs": [
+    { "name": "accountName",  "label": "Account Name",  "type": "STRING",  "maxOccurs": 1 },
+    { "name": "contactCount", "label": "Contact Count", "type": "INTEGER", "maxOccurs": 1 },
+    { "name": "totalOpportunityAmount", "label": "Total Opportunity Amount", "type": "DOUBLE", "maxOccurs": 1 }
+  ],
+  "inputs": [ { "name": "accountId", "type": "ID", "required": true } ]
+}
+```
+
+- **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`.
+
+Extract the field list with `jq` (do NOT wrap in `$()`):
+
+```bash
+sf api request rest '/services/data/v63.0/actions/custom/apex/<ActionApiName>' -o <org> \
+  | jq -r '.outputs[] | "\(.name)\t\(.type)"'
+```
+
+### 4. Map Actions-API `type` → CLT `lightning:type`
+
+| Actions API `type` | CLT `lightning:type` |
+|---|---|
+| `STRING`, `TEXTAREA`, `PICKLIST`, `ID`, `REFERENCE`, `EMAIL`, `PHONE`, `URL` | `lightning__textType` |
+| `INTEGER`, `INT`, `LONG` | `lightning__integerType` |
+| `DOUBLE`, `DECIMAL`, `CURRENCY`, `PERCENT` | `lightning__numberType` |
+| `BOOLEAN` | `lightning__booleanType` |
+| `DATE` | `lightning__dateType` |
+| `DATETIME` | `lightning__dateTimeType` |
+
+Casing varies by API version (some return `Int`/`Double`, some `INTEGER`/`DOUBLE`) — match case-insensitively. An unrecognized `type` defaults to `lightning__textType`; note the assumption in the build plan.
+
+> **Widget schema vs CLT schema type vocabulary** (applies to every source). The response CLT uses `lightning__integerType` for integers. The widget `schema.json` (per `platform-widget-generate`) has no integer type — all numerics are `lightning__numberType`. So integer fields are `lightning__integerType` in the *response CLT* but `lightning__numberType` in the *widget* schema. Do not copy CLT leaf types verbatim into the widget schema. Renderer bindings are strings and type-agnostic.
+
+---
+
+## `sample` — parse from a pasted tool-output JSON (fallback)
+
+Use when the action describe 404s or no org is reachable, but a pasted tool-output sample is available.
+
+Given a pasted envelope sample, read the `outputValues` object and infer each field's type from its value:
+
+| JSON value | CLT `lightning:type` |
+|---|---|
+| string | `lightning__textType` |
+| integer (no fraction) | `lightning__integerType` |
+| number (fractional) | `lightning__numberType` |
+| boolean | `lightning__booleanType` |
+
+Confirm the envelope keys (`actionName`, `isSuccess`, `outputValues`) against the sample. If the sample nests the payload further (e.g. `outputValues.data.<field>`), the response CLT and the renderer bindings must reflect that extra level (`{!$attrs.outputValues.data.<field>}`) — surface this in the build plan, because it changes every binding.
+
+---
+
+## `apex` — parse the Invocable class (fallback)
+
+Use when no org is reachable and no sample is available, but the `.cls` is in the project.
+
+### 1. Locate the class
+
+Search the local project first: `<pkgDir>/classes/<ClassName>.cls` where `<pkgDir>` = `<packageDirectories[].path>/main/default`. If absent, retrieve from the org:
+
+```bash
+sf project retrieve start --metadata ApexClass:<ClassName>
+```
+
+If it exists nowhere, STOP and surface — the payload shape cannot be enumerated.
+
+### 2. Identify the response class
+
+The Invocable method is annotated `@InvocableMethod` and returns `List<ResponseType>`. The **response class** is that element type.
+
+```apex
+@InvocableMethod(label='Get Account Summary')
+global static List<GetAccountSummaryResponse> getAccountSummary(
+    List<GetAccountSummaryRequest> requests
+) { ... }
+```
+
+- Response class = `GetAccountSummaryResponse` (the `List<...>` element type). **This is the payload source.**
+- Request class = `GetAccountSummaryRequest` (the parameter element type). **Excluded** — it is the tool input, not output.
+- Private helper classes (e.g. `private class OpportunityMetrics`) are **excluded** — not part of the invocable's externally visible schema. The Apex author signals this with `private`; respect it.
+
+### 3. Enumerate `@InvocableVariable` fields
+
+Read the response class block and list every field annotated `@InvocableVariable`. These become the response CLT `properties` and the widget schema properties (1:1).
+
+```bash
+# Print the response class field declarations. Do NOT wrap in $().
+echo "INVOCABLE_FIELDS:"
+grep -A1 '@InvocableVariable' <pkgDir>/classes/<ClassName>.cls \
+  | grep -oE '(public|global)\s+[A-Za-z0-9_<>,\s]+\s+[a-zA-Z_][a-zA-Z0-9_]*\s*;' \
+  | sed -E 's/.*\s([a-zA-Z_][a-zA-Z0-9_]*)\s*;/\1/' \
+  | sort -u
+```
+
+If the grep misses multi-line annotations, read the `.cls` with the Read tool and list fields manually — but do not skip enumeration. Scope the enumeration to the **response class block only**; do not pick up `@InvocableVariable` fields from the request class.
+
+### 4. Map Apex → CLT `lightning:type`
+
+| Apex type | CLT `lightning:type` |
+|---|---|
+| `String`, `Id` | `lightning__textType` |
+| `Integer`, `Long` | `lightning__integerType` |
+| `Decimal`, `Double` | `lightning__numberType` |
+| `Boolean` | `lightning__booleanType` |
+| `Date` | `lightning__dateType` |
+| `Datetime` | `lightning__dateTimeType` |
+
+---
+
+## Nested-object 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:
+
+- **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).
+
+**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:
+
+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.
+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.
+
+## 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:
+
+- 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).
+
+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

@@ -0,0 +1,128 @@
+# 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.
+
+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.)
+
+## Naming convention
+
+| Artifact | Convention | Example |
+|---|---|---|
+| Envelope CLT | `<toolApiName>` | `getFlightDetails` |
+| Response CLT | `<toolApiName>Response` | `getFlightDetailsResponse` |
+| Widget | `<toolApiName>Widget` | `getFlightDetailsWidget` |
+
+- `<toolApiName>` is derived **deterministically from the Apex class / Invocable Action name**, not the label: lower-camelCase the class name and strip a trailing `Action`, `Test`, or `WidgetAction` suffix if present.
+  - `AccountSummaryWidgetAction` → `accountSummary`
+  - `GetFlightDetailsAction` → `getFlightDetails`
+  - `GetAccountSummaryTest` → `getAccountSummary`
+  - Only when no class/action name is available at all (e.g. a bare `sample` with no `actionName` resolvable to a class) fall back to camelCasing the tool/action **label** (e.g. `Get Account Summary` → `accountSummary`).
+- 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`.
+
+```json
+{
+  "title": "Get Account Summary Response",
+  "description": "Response fields from the GetAccountSummaryTest invocable-action (GetAccountSummaryResponse)",
+  "type": "object",
+  "lightning:type": "lightning__objectType",
+  "lightning:tags": ["mcp"],
+  "unevaluatedProperties": false,
+  "properties": {
+    "accountName":    { "title": "accountName",    "lightning:type": "lightning__textType" },
+    "accountIndustry":{ "title": "accountIndustry","lightning:type": "lightning__textType" },
+    "contactCount":   { "title": "contactCount",   "lightning:type": "lightning__integerType" },
+    "totalOpportunityAmount": { "title": "totalOpportunityAmount", "lightning:type": "lightning__numberType" }
+  }
+}
+```
+
+### Nested-object 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** (e.g. `GetFlightDetailsAction.FlightDetailsResponse.flightInfo`, typed `SearchFlightsAction.Flight`). Both shapes are in scope; pick the branch per field:
+
+- **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.
+
+```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": {
+    "flightInfo": {
+      "title": "Flight Info",
+      "lightning:type": "@apexClassType/c__SearchFlightsAction$Flight"
+    }
+  }
+}
+```
+
+## 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`).
+
+```json
+{
+  "title": "Get Account Summary",
+  "description": "Invocable-action result envelope for the GetAccountSummaryTest MCP tool",
+  "type": "object",
+  "lightning:type": "lightning__objectType",
+  "lightning:tags": ["mcp"],
+  "unevaluatedProperties": false,
+  "properties": {
+    "actionName":   { "title": "actionName",   "lightning:type": "lightning__textType" },
+    "isSuccess":    { "title": "isSuccess",     "lightning:type": "lightning__booleanType" },
+    "outputValues": { "title": "outputValues",  "lightning:type": "c__getAccountSummaryResponse" }
+  }
+}
+```
+
+- 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.
+
+## Default renderer (in the ENVELOPE CLT)
+
+The renderer is the **default `renderer.json` at the envelope CLT bundle root**, parallel to `schema.json` — NOT under `lightningDesktopGenAi/`. It assigns the widget and bridges the envelope nesting to the flat widget schema.
+
+```json
+{
+  "renderer": {
+    "componentOverrides": {
+      "$": {
+        "definition": "@widget/c/accountSummaryWidget",
+        "attributes": {
+          "accountName":    "{!$attrs.outputValues.accountName}",
+          "accountIndustry":"{!$attrs.outputValues.accountIndustry}",
+          "contactCount":   "{!$attrs.outputValues.contactCount}",
+          "totalOpportunityAmount": "{!$attrs.outputValues.totalOpportunityAmount}"
+        }
+      }
+    }
+  }
+}
+```
+
+**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).
+
+## Why two CLTs and not one
+
+The platform binds the tool's output rendition to the CLT whose shape matches the **tool output schema** — that is the envelope, not the response. So the renderer (and thus the widget assignment) must live in the envelope CLT. But the widget wants a flat attribute contract, so the renderer flattens the nesting via `outputValues.`. The response CLT exists purely to *type* the `outputValues` node so those nested paths resolve. Inlining the response fields as a nested `lightning__objectType` inside the envelope is rejected by the CLT metaschema — hence a separate, referenced response CLT.
+
+## The widget schema is generic, not CLT-derived
+
+The widget schema is a standalone contract: `properties.attributes.properties` built from the **response field list** (name + primitive `lightning:type`), nothing more. It happens to share the field set with the response CLT for this flow, but it is not typed against the CLT, does not carry `unevaluatedProperties`, and would look identical if the same field list arrived from any other source `platform-widget-generate` supports. The widget schema and body know nothing about the envelope. The widget binds `{!$attrs.accountName}` (flat); only the renderer knows the field actually lives at `outputValues.accountName`. This keeps the widget reusable and lets `platform-widget-generate` author it exactly as it would for any flat response.