@salesforce/afv-skills 1.33.0 → 1.35.0

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.

package/skills/platform-mcp-tool-widget-coordinate/references/validation-gates.md

@@ -0,0 +1,181 @@
+# Validation Gates
+
+The orchestrator runs only **cross-skill validations** — checks that span the two CLTs, the widget, and the renderer. Widget-bundle-internal checks (schema parses, root keys, leaf types, `{!$attrs.X}` resolution, `.uiwidget-meta.xml` well-formedness, `<UiWidgetBundle>` root, widget-type) are owned by `platform-widget-generate` and run in its own self-validation.
+
+Run every gate below. If a hard gate fails, fix and re-run before reporting success. Warn gates are advisory.
+
+**Shell note:** run each command verbatim and reason about its printed output. Do NOT capture into shell variables with `$(…)`, do NOT use process substitution `<(…)`, do NOT use brace expansion. Vibes' safe-shell filter blocks those patterns and prompts for manual approval even in Bypass mode. See Hard Rule 11 in the SKILL.md.
+
+---
+
+## Hard — block on failure
+
+### 1. `clt-reference-integrity`
+
+Confirms the envelope→response typing the renderer depends on.
+
+1. **Both CLTs parse:**
+
+   ```bash
+   jq . <pkgDir>/lightningTypes/<responseCLT>/schema.json > /dev/null && echo "RESPONSE_PARSE: ok" || echo "RESPONSE_PARSE: FAIL"
+   ```
+
+   ```bash
+   jq . <pkgDir>/lightningTypes/<toolCLT>/schema.json > /dev/null && echo "ENVELOPE_PARSE: ok" || echo "ENVELOPE_PARSE: FAIL"
+   ```
+
+2. **Envelope `outputValues` references the response CLT.** Print the value and compare in reasoning:
+
+   ```bash
+   jq -r '.properties.outputValues["lightning:type"]' <pkgDir>/lightningTypes/<toolCLT>/schema.json
+   ```
+
+   Expected: `c__<responseCLT>`. Match → `REFERENCE: ok`; else `REFERENCE: FAIL (got <actual>, expected c__<responseCLT>)`.
+
+3. **Neither CLT carries a forbidden keyword.** Print any hits (empty output = clean):
+
+   ```bash
+   jq 'paths | select(.[-1] == "$schema" or .[-1] == "items")' <pkgDir>/lightningTypes/<responseCLT>/schema.json
+   ```
+
+   ```bash
+   jq 'paths | select(.[-1] == "$schema" or .[-1] == "items")' <pkgDir>/lightningTypes/<toolCLT>/schema.json
+   ```
+
+   Any output → `KEYWORDS: FAIL (<path>)`; empty → `KEYWORDS: ok`.
+
+4. **Nested-object response fields (if any) use `@apexClassType`, never a bare object.** For every response CLT property that is not a primitive leaf, print its `lightning:type`:
+
+   ```bash
+   jq -r '.properties | to_entries[] | select(.value["lightning:type"] == null or (.value["lightning:type"] | test("^lightning__") | not)) | "\(.key): \(.value["lightning:type"])"' <pkgDir>/lightningTypes/<responseCLT>/schema.json
+   ```
+
+   Every printed entry must match `@apexClassType/<ns>__<OuterClass>$<InnerClass>`. A bare `{"type":"object"}` (no `lightning:type`, or a `lightning:type` of `lightning__objectType` inlined on a *property* rather than the CLT root) → `NESTED_TYPE: FAIL (<key>: <actual>)`. All match or no such properties exist → `NESTED_TYPE: ok`.
+
+**Result:** all ok → `pass`. Otherwise `fail (<first failing check>)`.
+
+**Failure → fix:** the renderer's `{!$attrs.outputValues.<field>}` paths cannot resolve unless `outputValues` is typed to the response CLT. Fix the envelope CLT's `outputValues.lightning:type` to `c__<responseCLT>`, ensure the response CLT exists, and remove any `$schema` / `items` keywords.
+
+---
+
+### 2. `renderer-wires-widget`
+
+Confirms the envelope CLT's default renderer assigns the widget and binds every widget property through the nested `outputValues` path.
+
+1. **File exists at the bundle root and parses** (NOT `lightningDesktopGenAi/`):
+
+   ```bash
+   jq . <pkgDir>/lightningTypes/<toolCLT>/renderer.json > /dev/null && echo "PARSE: ok" || echo "PARSE: FAIL"
+   ```
+
+2. **Definition points at this widget:**
+
+   ```bash
+   jq -r '.renderer.componentOverrides["$"].definition' <pkgDir>/lightningTypes/<toolCLT>/renderer.json
+   ```
+
+   Expected: `@widget/c/<widgetName>`. Match → `DEFINITION: ok`; else `DEFINITION: FAIL (got <actual>)`.
+
+3. **Attribute keys cover every widget schema property.** Print both lists; compare in reasoning:
+
+   ```bash
+   echo "SCHEMA_KEYS (expected):"
+   jq -r '.properties.attributes.properties | keys[]' <pkgDir>/uiWidgets/<widgetName>/schema.json | sort -u
+   ```
+
+   ```bash
+   echo "RENDERER_KEYS (actual):"
+   jq -r '.renderer.componentOverrides["$"].attributes | keys[]' <pkgDir>/lightningTypes/<toolCLT>/renderer.json | sort -u
+   ```
+
+   Same set → `ATTRIBUTES: ok`. Keys in SCHEMA not in RENDERER → `ATTRIBUTES: FAIL (missing: <list>)`. Keys in RENDERER not in SCHEMA → `ATTRIBUTES: FAIL (extra: <list>)`.
+
+4. **Each binding uses the nested `outputValues` path.** Dump the map and inspect each entry:
+
+   ```bash
+   jq '.renderer.componentOverrides["$"].attributes' <pkgDir>/lightningTypes/<toolCLT>/renderer.json
+   ```
+
+   For every key `K`, the value MUST equal `{!$attrs.outputValues.K}` exactly (nested path, matching key, no whitespace) — **unless** `K` is a leaf of a nested-object response field (per the response CLT's `@apexClassType` properties, see `clt-reference-integrity` check 4), in which case it MUST equal `{!$attrs.outputValues.<objectField>.K}` (three segments: `outputValues`, the object field, the leaf). All match their expected form → `BINDINGS: ok`. A flat `{!$attrs.K}` (missing `outputValues.`) or a one-level binding for a nested-object leaf (missing the `<objectField>.` segment) is a FAIL — these are the most common mistakes in this flow. Report `BINDINGS: FAIL (<key>: got <value>, expected <expected>)`.
+
+**Result classification:**
+- All checks pass → `pass`
+- File missing / at wrong path / invalid JSON → `fail (renderer.json missing, mislocated, or invalid — must be at lightningTypes/<toolCLT>/renderer.json)`
+- Definition mismatch → `fail (definition does not point at widget: got <actual>)`
+- Coverage mismatch → `fail (missing bindings: <list>)` or `fail (extra bindings: <list>)`
+- Flat or malformed binding → `fail (binding for <key> is not nested under outputValues: <actual>)`
+
+**Failure → fix:** without correct nested wiring the widget either ships dead (no definition) or renders empty (flat bindings resolve against the envelope root, where the payload fields do not exist). Author the renderer per `references/two-clt-modeling.md`.
+
+---
+
+## Warn — advisory
+
+### `field-trace`
+
+Enforces: no invented widget fields (subset rule) and no silent omission of response fields.
+
+`INVOCABLE_FIELDS` and `WIDGET_PROPS` are labels in the printed output, NOT shell variables. Do NOT assign with `$(…)`.
+
+1. **Extract the authoritative payload field names**, using the same source chosen in Phase 2:
+
+   **`action` source (preferred)** — read the Actions REST API `outputs` (already excludes inputs/helpers):
+
+   ```bash
+   echo "INVOCABLE_FIELDS:"
+   sf api request rest '/services/data/v<APIVER>/actions/custom/apex/<ActionApiName>' -o <org> \
+     | jq -r '.outputs[].name' | sort -u
+   ```
+
+   **`apex` source** — grep the response class (scope to the response class block only; exclude the request class and private helpers):
+
+   ```bash
+   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 grep misses multi-line annotations, read the `.cls` with the Read tool and list fields manually. For the `sample` source, use the `outputValues` keys instead.
+
+   **Nested-object fields (per `references/mcp-tool-output-discovery.md` "Nested-object payload fields") expand before comparison.** A field resolved to `@apexClassType/<ns>__<OuterClass>$<InnerClass>` is not itself compared against `WIDGET_PROPS` — the widget flattens to that class's own leaf fields, never the object field. Replace that field name in `INVOCABLE_FIELDS` with its referenced class's leaf field names (its own `@InvocableVariable`/public members) before running the diff in step 3. Note the substitution in the printed output, e.g. `INVOCABLE_FIELDS (expanded): flightInfo → flightId, origin, destination, departureTime, arrivalTime, price`.
+
+2. **Extract widget schema property keys:**
+
+   ```bash
+   echo "WIDGET_PROPS:"
+   jq -r '.properties.attributes.properties | keys[]' <pkgDir>/uiWidgets/<widgetName>/schema.json | sort -u
+   ```
+
+3. **PRINT both lists** in the gate report (not just an assertion):
+
+   ```text
+   INVOCABLE_FIELDS: accountName, accountIndustry, contactCount, status, ...
+   WIDGET_PROPS:     accountName, accountIndustry, contactCount, ...
+   INVENTED (widget − invocable): <empty>
+   OMITTED  (invocable − widget): status, ...
+   ```
+
+4. **Result classification:**
+   - `INVENTED` non-empty → **fail** (subset rule violated). `fail (invented: <list>)`.
+   - `OMITTED` non-empty AND every omitted field is in the Phase 3 `Properties omitted:` → **pass**.
+   - `OMITTED` non-empty AND any omitted field is NOT in `Properties omitted:` → **warn** (silent omission). `warn (silent omission: <list>)`, surface before the summary.
+   - Both empty → **pass**.
+
+**Reporting `pass` without printing the two lists is a hard violation — report `not run` instead.**
+
+---
+
+## Direction of the subset rule
+
+The widget `schema.json` and the response CLT `properties` are a **subset** of the response `@InvocableVariable` fields.
+
+- **No invented fields (hard via `field-trace`).** The widget must not introduce properties the response class does not expose.
+- **No silent omissions (warn).** The widget MAY omit response fields, but every omission must appear in the Phase 3 `Properties omitted:` section with a rationale.
+
+---
+
+## Reporting
+
+Phase 6 must list each gate's result by name: `pass`, `fail (<reason>)`, `warn (<reason>)`, or `not run`. Do not summarize as "all passed".

package/skills/platform-metadata-api-context-get/SKILL.md

@@ -6,9 +6,13 @@ metadata:
   minApiVersion: "67.0"
   cliTools:
     - tool: ["jq"]
-      semver: ">=1.6"
+      semver: ">=1.6.0"
+    - tool: ["node"]
+      semver: ">=18.0.0"
     - tool: ["python3"]
-      semver: ">=3.8"
+      semver: ">=3.10.0"
+    - tool: ["sf"]
+      semver: ">=2.0.0"
 ---
 
 # Salesforce Metadata API Skill

package/skills/platform-metadata-retrieve/SKILL.md

@@ -4,6 +4,11 @@ description: "ALWAYS USE THIS SKILL to retrieve metadata from an org to your loc
 compatibility: Salesforce CLI (sf) v2+
 metadata:
   version: "1.0"
+  relatedSkills:
+    - "platform-metadata-deploy"
+  cliTools:
+    - tool: ["sf"]
+      semver: ">=2.0.0"
 ---
 
 # platform-metadata-retrieve

package/skills/platform-models-api-configure/SKILL.md

@@ -2,6 +2,16 @@
 name: platform-models-api-configure
 description: "Configure (or troubleshoot) an AI coding agent or CLI to route through the Salesforce Models API using a signed OrgJWT. Use this skill when pointing an agent at the Salesforce model endpoint (api.salesforce.com/ai/gpt/v1), setting up OrgJWT / Bedrock-mode auth, wiring the agent's settings, API-key helper, and credentials file for the Salesforce endpoint, or fixing Models API 401 / 404 / \"model not available\" errors. DO NOT TRIGGER when the user needs to create or configure the Salesforce Connected App itself (use integration-connectivity-connected-app-configure) or set up Named Credentials / callout auth (use integration-connectivity-generate)."
 metadata:
+  cliTools:
+    - tool: ["curl"]
+      semver: ">=7.29.0"
+    - tool: ["jq"]
+      semver: ">=1.6.0"
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+  relatedSkills:
+    - "integration-connectivity-connected-app-configure"
+    - "integration-connectivity-generate"
   version: "1.0"
 ---
 

package/skills/platform-permission-set-generate/SKILL.md

@@ -1,10 +1,9 @@
 ---
 name: platform-permission-set-generate
 description: "Generates correct, deployable Salesforce permission set metadata (PermissionSet XML) with object, field, user, and app permissions. Use this skill when creating or editing permission set metadata, object permissions, field-level security (FLS), tab visibility, or deploying permission sets."
-compatibility: Salesforce Metadata API v60.0+
 metadata:
-  author: sf-skills
   version: "1.0"
+  minApiVersion: "60.0"
 ---
 
 ## When to Use This Skill

package/skills/platform-policy-rule-generate/SKILL.md

@@ -5,6 +5,8 @@ metadata:
   version: "1.0"
   minApiVersion: "64.0"
   cliTools:
+    - tool: ["jq"]
+      semver: ">=1.6.0"
     - tool: ["sf"]
       semver: ">=2.0.0"
 ---

package/skills/platform-report-generate/SKILL.md

@@ -3,7 +3,7 @@ name: platform-report-generate
 description: "Use this skill when users need to create, generate, or validate Salesforce Lightning Report metadata. Trigger when users mention reports, creating reports, report metadata, .report-meta.xml files, tabular reports, summary reports, matrix reports, joined reports, report columns, report groupings, report filters, report charts, cross-filters, bucket fields, report formulas, or report time frame filters. Also use when users say things like 'create a report', 'generate a report', 'build a report on Accounts', 'add a chart to my report', or when they encounter deployment errors for .report-meta.xml files. Do NOT trigger for: creating or modifying Custom Report Type metadata (.reportType-meta.xml — use platform-custom-report-type-generate), creating dashboards, creating list views, running or viewing existing reports in the UI, or SOQL queries."
 metadata:
   version: "1.0"
-  minApiVersion: "51.0"
+  minApiVersion: "60.0"
   relatedSkills:
     - "platform-custom-report-type-generate"
   mcpTools:

package/skills/platform-sharing-rules-generate/SKILL.md

@@ -3,7 +3,7 @@ name: platform-sharing-rules-generate
 description: "Use this skill when users need to create, edit, delete, or manage Salesforce Sharing Rules metadata. TRIGGER when: users mention sharing rules, record sharing, criteria-based sharing, role-based sharing, guest user sharing, sharingRules, sharingCriteriaRules, sharingGuestRules, sharingOwnerRules, .sharingRules-meta.xml files, or ask to share records with specific roles or groups. Also trigger when users want to modify or remove existing sharing rules, or update sharing rule criteria or access levels. DO NOT TRIGGER when user needs permission sets or profiles (use platform-permission-set-generate), or needs object-level security rather than record-level sharing (use platform-permission-set-generate)."
 metadata:
   version: "1.2"
-  minApiVersion: "51.0"
+  minApiVersion: "60.0"
   relatedSkills:
     - "platform-custom-object-generate"
     - "platform-permission-set-generate"

package/skills/platform-soql-query/SKILL.md

@@ -2,6 +2,19 @@
 name: platform-soql-query
 description: "SOQL query generation, optimization, and analysis with 100-point scoring. Use this skill when the user needs SOQL/SOSL authoring or optimization: natural-language-to-query generation, relationship queries, aggregates, query-plan analysis, and performance or safety improvements for Salesforce queries. TRIGGER when: user writes, optimizes, or debugs SOQL/SOSL queries, touches .soql files, or asks about relationship queries, aggregates, or query performance. DO NOT TRIGGER when: bulk data operations (use platform-data-manage), Apex DML logic (use platform-apex-generate), or report/dashboard queries."
 metadata:
+  cliTools:
+    - tool: ["jq"]
+      semver: ">=1.6.0"
+    - tool: ["python3"]
+      semver: ">=3.10.0"
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+  relatedSkills:
+    - "experience-lwc-generate"
+    - "platform-apex-generate"
+    - "platform-apex-logs-debug"
+    - "platform-apex-test-run"
+    - "platform-data-manage"
   version: "1.1"
 ---
 

package/skills/platform-tracing-agentforce-configure/SKILL.md

@@ -4,7 +4,11 @@ description: "Generate AgentforcePlatformTracingSettings metadata to enable or d
 metadata:
   version: "1.0"
   minApiVersion: "68.0"
-  relatedSkills: platform-tracing-configure
+  relatedSkills:
+    - "agentforce-observe"
+    - "integration-eventing-cdc-configure"
+    - "integration-eventing-subscription-configure"
+    - "platform-tracing-configure"
 ---
 
 # Platform Tracing — Agentforce Configure

package/skills/platform-tracing-configure/SKILL.md

@@ -4,7 +4,10 @@ description: "Generate EventSettings metadata to enable or disable Platform Trac
 metadata:
   version: "1.0"
   minApiVersion: "68.0"
-  relatedSkills: platform-tracing-agentforce-configure
+  relatedSkills:
+    - "integration-eventing-cdc-configure"
+    - "integration-eventing-subscription-configure"
+    - "platform-tracing-agentforce-configure"
 ---
 
 # Platform Tracing — Configure