@salesforce/afv-skills 1.33.0 → 1.35.0

package/skills/omnistudio-dependencies-analyze/SKILL.md

@@ -2,6 +2,18 @@
 name: omnistudio-dependencies-analyze
 description: "Cross-cutting OmniStudio analysis skill for namespace detection, dependency visualization, and impact analysis across OmniScripts, FlexCards, Integration Procedures, and Data Mappers. TRIGGER when: user asks about OmniStudio dependencies, wants namespace detection (Core vs vlocity_cmt vs vlocity_ins), needs impact analysis, requests dependency graphs or Mermaid diagrams, or asks which components are affected by a change. DO NOT TRIGGER when: authoring OmniScripts (use omnistudio-omniscript-generate), building FlexCards (use omnistudio-flexcard-generate), creating Integration Procedures (use omnistudio-integration-procedure-generate), or configuring Data Mappers (use omnistudio-datamapper-generate)."
 metadata:
+  cliTools:
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+  relatedSkills:
+    - "external-diagram-mermaid-generate"
+    - "omnistudio-datamapper-generate"
+    - "omnistudio-flexcard-generate"
+    - "omnistudio-integration-procedure-generate"
+    - "omnistudio-omniscript-generate"
+    - "platform-custom-field-generate"
+    - "platform-custom-object-generate"
+    - "platform-metadata-deploy"
   version: "1.0"
 ---
 

package/skills/omnistudio-epc-catalog-generate/SKILL.md

@@ -2,7 +2,22 @@
 name: omnistudio-epc-catalog-generate
 description: "Salesforce Industries CME EPC product-modeling skill for Product2-based catalog creation. Use when creating EPC products, configuring product attributes, building offer bundles with Product Child Items, or reviewing EPC DataPack JSON metadata for product catalog changes. TRIGGER when: user creates or updates Product2 EPC records, AttributeAssignment payloads, AttributeMetadata/AttributeDefaultValues, Offer bundles, or ProductChildItem relationships. DO NOT TRIGGER when: designing OmniScripts/FlexCards/Integration Procedures (use omnistudio-omniscript-generate, omnistudio-flexcard-generate, or omnistudio-integration-procedure-generate), implementing Apex business logic (use platform-apex-generate), or troubleshooting deployment pipelines (use platform-metadata-deploy)."
 metadata:
+  cliTools:
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+  relatedSkills:
+    - "omnistudio-callable-apex-generate"
+    - "omnistudio-dependencies-analyze"
+    - "omnistudio-flexcard-generate"
+    - "omnistudio-integration-procedure-generate"
+    - "omnistudio-omniscript-generate"
+    - "platform-apex-generate"
+    - "platform-custom-field-generate"
+    - "platform-custom-object-generate"
+    - "platform-metadata-deploy"
+    - "platform-soql-query"
   version: "1.0"
+  minApiVersion: "60.0"
 ---
 
 # omnistudio-epc-catalog-generate: CME EPC Product and Offer Modeling

package/skills/omnistudio-flexcard-generate/SKILL.md

@@ -2,7 +2,18 @@
 name: omnistudio-flexcard-generate
 description: "OmniStudio FlexCard creation and validation with 130-point scoring. Use when building at-a-glance UI cards, configuring data source bindings to Integration Procedures, or reviewing existing FlexCard definitions for accessibility and performance. TRIGGER when: user creates FlexCards, configures data sources, designs card layouts, or asks about OmniUiCard metadata. DO NOT TRIGGER when: building OmniScripts (use omnistudio-omniscript-generate), creating Integration Procedures (use omnistudio-integration-procedure-generate), or analyzing dependencies (use omnistudio-dependencies-analyze)."
 metadata:
+  cliTools:
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+  relatedSkills:
+    - "experience-lwc-generate"
+    - "omnistudio-datamapper-generate"
+    - "omnistudio-dependencies-analyze"
+    - "omnistudio-integration-procedure-generate"
+    - "omnistudio-omniscript-generate"
+    - "platform-metadata-deploy"
   version: "1.0"
+  minApiVersion: "60.0"
 ---
 
 # omnistudio-flexcard-generate: OmniStudio FlexCard Creation and Validation

package/skills/omnistudio-integration-procedure-generate/SKILL.md

@@ -2,7 +2,18 @@
 name: omnistudio-integration-procedure-generate
 description: "OmniStudio Integration Procedure creation and validation with 110-point scoring. Use this skill when building server-side process orchestrations that combine Data Mapper actions, Apex Remote Actions, HTTP callouts, and conditional logic. TRIGGER when: user creates Integration Procedures, adds Data Mapper steps, configures Remote Actions, or reviews existing IP configurations. DO NOT TRIGGER when: building OmniScripts (use omnistudio-omniscript-generate), creating Data Mappers directly (use omnistudio-datamapper-generate), or analyzing cross-component dependencies (use omnistudio-dependencies-analyze)."
 metadata:
+  cliTools:
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+  relatedSkills:
+    - "omnistudio-datamapper-generate"
+    - "omnistudio-dependencies-analyze"
+    - "omnistudio-flexcard-generate"
+    - "omnistudio-omniscript-generate"
+    - "platform-apex-generate"
+    - "platform-metadata-deploy"
   version: "1.0"
+  minApiVersion: "60.0"
 ---
 
 # omnistudio-integration-procedure-generate: OmniStudio Integration Procedure Creation and Validation

package/skills/omnistudio-omniscript-generate/SKILL.md

@@ -2,6 +2,15 @@
 name: omnistudio-omniscript-generate
 description: "OmniStudio OmniScript creation and validation with 120-point scoring. Use when building guided digital experiences, multi-step forms, or interactive processes that orchestrate Integration Procedures and Data Mappers. TRIGGER when: user creates OmniScripts, designs step flows, configures element types, or reviews existing OmniScript configurations. DO NOT TRIGGER when: building FlexCards (use omnistudio-flexcard-generate), creating Integration Procedures directly (use omnistudio-integration-procedure-generate), or analyzing dependencies (use omnistudio-dependencies-analyze)."
 metadata:
+  cliTools:
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+  relatedSkills:
+    - "omnistudio-datamapper-generate"
+    - "omnistudio-dependencies-analyze"
+    - "omnistudio-flexcard-generate"
+    - "omnistudio-integration-procedure-generate"
+    - "platform-metadata-deploy"
   version: "1.0"
 ---
 

package/skills/platform-agentexchange-partner-offers-configure/SKILL.md

@@ -2,6 +2,14 @@
 name: platform-agentexchange-partner-offers-configure
 description: "Enable or disable the org preference that controls whether a Salesforce org can receive partner offers from the Transactable Marketplace. Use this skill when the user wants to turn partner offer reception on or off for an org. TRIGGER when: user asks to enable or disable partner offers, configure TransactableMarketplaceReceivePartnerOffers, configure enableTransactableMarketplaceReceivePartnerOffers, set up marketplace partner offer reception, toggle the TM partner offers setting, edit a TransactableMarketplacePrivateOffer.settings file, or configure org preferences related to transactable marketplace. DO NOT TRIGGER when: user needs to create or manage the partner offer records themselves, configure marketplace listing settings, or work with SfdcPartnerOffer objects (use platform-metadata-deploy or platform-apex-generate instead)."
 metadata:
+  cliTools:
+    - tool: ["jq"]
+      semver: ">=1.6.0"
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+  relatedSkills:
+    - "platform-apex-generate"
+    - "platform-metadata-deploy"
   version: "1.0"
   minApiVersion: "67.0"
 ---

package/skills/platform-agentsetup-categories-fetch/SKILL.md

@@ -3,6 +3,9 @@ name: platform-agentsetup-categories-fetch
 description: "Fetch agentic setup prompt categories from a connected Salesforce org using the Connect API. Use this skill to call GET /agenticsetup/categories and return the list of prompt categories, optionally with their nested prompts. TRIGGER when: user asks to get, fetch, list, or show agentic setup categories, prompt categories, setup copilot categories, prompt library categories, available setup prompts, Agentforce prompt library, or copilot prompts. DO NOT TRIGGER when: user wants to create new categories, work with non-categories endpoints, or generate OpenAPI specs."
 allowed-tools: Bash Read
 metadata:
+  cliTools:
+    - tool: ["sf"]
+      semver: ">=2.0.0"
   version: "1.0"
   minApiVersion: "67.0"
 ---

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

@@ -2,6 +2,11 @@
 name: platform-apex-generate
 description: "Primary Apex authoring skill for class generation, refactoring, and review. ALWAYS ACTIVATE when the user mentions Apex, .cls, triggers, or asks to create/refactor a class (service, selector, domain, batch, queueable, schedulable, invocable, DTO, utility, interface, abstract, exception, REST resource). Use this skill for requests involving SObject CRUD, mapping collections, fetching related records, scheduled jobs, batch jobs, trigger design, @AuraEnabled controllers, @RestResource endpoints, custom REST APIs, or code review of existing Apex."
 metadata:
+  cliTools:
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+  relatedSkills:
+    - "platform-apex-test-generate"
   version: "1.0"
   minApiVersion: "66.0"
 ---

package/skills/platform-apex-logs-debug/SKILL.md

@@ -2,6 +2,18 @@
 name: platform-apex-logs-debug
 description: "Salesforce debug log analysis and troubleshooting with 100-point scoring. TRIGGER when: user analyzes debug logs, hits governor limits, reads stack traces, or touches .log files from Salesforce orgs. DO NOT TRIGGER when: running Apex tests (use platform-apex-test-run), generating or fixing Apex code (use platform-apex-generate), or Agentforce session tracing (use agentforce-observe)."
 metadata:
+  cliTools:
+    - tool: ["jq"]
+      semver: ">=1.6.0"
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+  relatedSkills:
+    - "agentforce-observe"
+    - "platform-apex-generate"
+    - "platform-apex-test-run"
+    - "platform-data-manage"
+    - "platform-metadata-deploy"
+    - "platform-soql-query"
   version: "1.1"
 ---
 

package/skills/platform-apex-test-generate/SKILL.md

@@ -3,6 +3,11 @@ name: platform-apex-test-generate
 description: "Generate and validate Apex test classes with TestDataFactory patterns, bulk testing (251+ records), mocking strategies, assertion best practices, and disciplined test-fix loops. Use this skill when creating new Apex test classes, improving test coverage, debugging and fixing failing Apex tests, running test execution and coverage analysis, or implementing testing patterns for triggers, services, controllers, batch jobs, queueables, and integrations. Triggers on *Test.cls, *_Test.cls files, sf apex run test workflows, coverage reports, test-fix loops. Do NOT trigger for production Apex code (use platform-apex-generate) or Jest/LWC tests."
 metadata:
   version: "1.0"
+  relatedSkills:
+    - "platform-apex-generate"
+  cliTools:
+    - tool: ["sf"]
+      semver: ">=2.0.0"
 ---
 
 # Generating Apex Tests

package/skills/platform-apex-test-run/SKILL.md

@@ -2,6 +2,20 @@
 name: platform-apex-test-run
 description: "Apex test execution, coverage analysis, and test-fix loops with 120-point scoring. Use when the user needs to run Apex tests, check code coverage, fix failing tests, or work with *Test.cls / *_Test.cls files. TRIGGER when: user runs Apex tests, checks code coverage, fixes failing tests, or touches *Test.cls / *_Test.cls files. DO NOT TRIGGER when: writing Apex production code (use platform-apex-generate), Agentforce agent testing (use agentforce-test), or Jest/LWC tests (use experience-lwc-generate)."
 metadata:
+  cliTools:
+    - tool: ["jq"]
+      semver: ">=1.6.0"
+    - tool: ["python3"]
+      semver: ">=3.10.0"
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+  relatedSkills:
+    - "agentforce-test"
+    - "experience-lwc-generate"
+    - "platform-apex-generate"
+    - "platform-apex-logs-debug"
+    - "platform-data-manage"
+    - "platform-metadata-deploy"
   version: "1.1"
 ---
 

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

@@ -3,6 +3,7 @@ name: platform-custom-application-generate
 description: "Use this skill when users need to create or configure tab-based Salesforce Custom Applications with navigation, branding, and action overrides. Trigger when users mention custom apps, application metadata, app navigation, or organizing tabs into applications. Use when users want to create app containers for tabs and pages. Do NOT use when the goal is hosting a React UI bundle in the App Launcher — use experience-ui-bundle-custom-app-generate for that case."
 metadata:
   version: "1.0"
+  minApiVersion: "60.0"
 ---
 
 ## When to Use This Skill

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

@@ -3,7 +3,7 @@ name: platform-custom-field-generate
 description: "Use this skill when users need to create, generate, or validate Salesforce Custom Field metadata. Trigger when users mention custom fields, field types, Roll-up Summary fields, Master-Detail relationships, Lookup relationships, formula fields, picklists, dependent (controlling) picklists, referencing a value set from a field, or scoping/limiting picklist values for a specific record type. Also use when users encounter field deployment errors, especially around Roll-up Summary format, Master-Detail constraints, formula issues, or a record type that won't deploy without a business process. Use this skill for custom field metadata work, field generation, and field troubleshooting. DO NOT TRIGGER for creating or customizing the value set itself — defining a new GlobalValueSet, or modifying a StandardValueSet catalog like Industry or Lead Source — use platform-value-set-generate instead; this skill covers the field that references a value set, not the value set definition."
 metadata:
   version: "1.0"
-  minApiVersion: "51.0"
+  minApiVersion: "60.0"
   relatedSkills: ["platform-value-set-generate", "platform-validation-rule-generate"]
 ---
 

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

@@ -6,6 +6,7 @@ metadata:
   minApiVersion: "60.0"
   relatedSkills:
     - "platform-lightning-type-widget-coordinate"
+    - "platform-mcp-tool-widget-coordinate"
     - "platform-widget-generate"
 ---
 
@@ -57,6 +58,7 @@ Custom Lightning Types (CLTs) are JSON Schema-based type definitions used by the
 - **Apex class CLTs are minimal**:
   - Include **only** `title`, `description` (optional), and `lightning:type` set to `@apexClassType/...`.
   - Do **not** add `type`, `properties`, `required`, or `unevaluatedProperties`.
+  - **Custom LWC renderers/editors on an Apex class CLT MUST NOT use `attributes` in the root override — this overrides any prompt wording to the contrary.** Since the schema has no `properties` block, there is nothing for `{!$attrs.<name>}` to resolve against — `unevaluatedProperties: false` will reject any attribute key (e.g. `"You can't add the flightId property ... because the unevaluatedProperties keyword value is set to false"`). Use `"componentOverrides": { "$": { "definition": "c/<yourComponent>" } }` with **no `attributes` key** at all. **If the user's prompt explicitly asks for attribute mappings to specific fields (e.g. "with attribute mappings for fieldA, fieldB") on an Apex-class CLT renderer/editor, do NOT comply literally** — omit `attributes` from the root override anyway, and say so in your response (e.g. "Note: attribute mappings were omitted because the backing type is an Apex-class CLT, which has no `properties` block to bind against").
 - **No shell metacharacters that trigger the Vibes safe-shell filter.** In any Bash tool call emitted by this skill, do NOT use command substitution (`$(…)` or backticks), process substitution (`<(…)`, `>(…)`), brace expansion (`{a,b,c}` or `{1..N}`), or `eval` / `exec`. Vibes forces manual approval on these patterns even under Bypass mode and stalls the eval. Emit separate commands (`mkdir -p a && mkdir -p b`) or print each value with its own command and reason about the output rather than capturing it in a shell variable.
 
 ## Additional CLT Metaschema Validations
@@ -158,6 +160,7 @@ When you need the full list of supported primitive `lightning:type` identifiers,
 | `additionalProperties` error on layout attributes | Adding `label` or other attributes to `lightning/propertyLayout` | Only use `property` attribute in `lightning/propertyLayout`. Remove `label`, `title`, or any other attributes |
 | Invalid target configuration for custom LWC | Custom LWC component's `-meta.xml` missing required target (`lightning__AgentforceInput` or `lightning__AgentforceOutput`) | Add correct target to LWC's `-meta.xml`: use `lightning__AgentforceInput` for editors, `lightning__AgentforceOutput` for renderers |
 | Attribute mapping doesn't exist in type schema | Using `{!$attrs.propertyName}` where `propertyName` is not defined in schema | Ensure all attribute mappings reference actual properties in your type schema's `properties` section |
+| `unevaluatedProperties` error on custom LWC renderer for an Apex class CLT | Root override `attributes` mapping used on an Apex class CLT, which has no `properties` block to validate against | Remove `attributes` entirely from the root override; use `"componentOverrides": { "$": { "definition": "c/<component>" } }` only |
 | `additionalProperties` error with deprecated keys | Using `propertyRenderers` or `view` in editor/renderer config | Replace deprecated `propertyRenderers` with `componentOverrides` and `view` with `layout` |
 | Type mismatch in component attributes | Passing wrong type for component attribute (e.g., integer instead of string) | Ensure attribute values match the expected type defined by the component |
 

package/skills/platform-custom-lightning-type-generate/assets/primitive-types-and-constraints.md

@@ -38,4 +38,4 @@ When strict validation is enabled (`unevaluatedProperties: false`), keep each pr
 - `const`, `enum`
 - `lightning:textIndexed`, `lightning:supportsPersonalization`, `lightning:localizable`
 - `lightning:uiOptions`, `lightning:allowedUrlSchemes`
-- `lightning:tags` (metaschema restricts values; currently `flow` is the only known allowed tag)
+- `lightning:tags` (metaschema restricts values; known allowed tags are `flow` and `mcp` — use `mcp` on object-based CLTs that model an MCP-tool envelope/response, per `platform-mcp-tool-widget-coordinate`)

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

@@ -3,6 +3,7 @@ name: platform-custom-tab-generate
 description: "Use this skill when users need to create or configure Salesforce Custom Tabs. Trigger when users mention tabs, navigation tabs, object tabs, web tabs, Visualforce tabs, Lightning component tabs, app page tabs, or tab configuration. Also use when users want to add navigation to custom objects, create tabs for external content, or set up Lightning page tabs. Always use this skill for any custom tab work."
 metadata:
   version: "1.0"
+  minApiVersion: "60.0"
 ---
 
 ## When to Use This Skill

package/skills/platform-data-manage/SKILL.md

@@ -2,6 +2,21 @@
 name: platform-data-manage
 description: "Salesforce data operations with 130-point scoring. Use this skill to create, update, delete, bulk import/export, generate test data, and clean up org records using sf CLI and anonymous Apex. TRIGGER when: user creates test data, performs bulk import/export, uses sf data CLI commands, needs data factory patterns for Apex tests, or needs to seed/clean records in a Salesforce org. DO NOT TRIGGER when: SOQL query writing only (use platform-soql-query), Apex test execution (use platform-apex-test-run), or metadata deployment (use platform-metadata-deploy)."
 metadata:
+  cliTools:
+    - tool: ["jq"]
+      semver: ">=1.6.0"
+    - tool: ["python3"]
+      semver: ">=3.8.0"
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+  relatedSkills:
+    - "automation-flow-generate"
+    - "platform-apex-generate"
+    - "platform-apex-test-run"
+    - "platform-custom-field-generate"
+    - "platform-custom-object-generate"
+    - "platform-metadata-deploy"
+    - "platform-soql-query"
   version: "1.1"
 ---
 

package/skills/platform-dataspace-access-configure/SKILL.md

@@ -5,10 +5,10 @@ metadata:
   version: "1.0"
   minApiVersion: "67.0"
   cliTools:
+    - tool: ["jq"]
+      semver: ">=1.6.0"
     - tool: ["sf"]
       semver: ">=2.0.0"
-    - tool: ["jq"]
-      semver: ">=1.6"
 ---
 
 # platform-dataspace-access-configure

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

@@ -4,7 +4,10 @@ description: "Use this skill when users need to create, generate, modify, or val
 allowed-tools: Bash Read Write
 metadata:
   version: "1.1"
+  minApiVersion: "60.0"
   cliTools:
+    - tool: ["python3"]
+      semver: ">=3.10.0"
     - tool: ["sf"]
       semver: ">=2.126.4"
 ---

package/skills/platform-lightning-app-coordinate/SKILL.md

@@ -3,7 +3,24 @@ name: platform-lightning-app-coordinate
 description: "Build complete Salesforce Lightning Experience applications from natural language descriptions. Use this skill when a user requests a \"complete app\", \"Lightning app\", \"business solution\", \"management system\", or describes a scenario requiring multiple interconnected Salesforce components (objects, fields, pages, tabs, security). Orchestrates all required metadata types in proper dependency order to produce a deployable application."
 metadata:
   version: "1.0"
-  related-skills: platform-custom-object-generate, platform-custom-field-generate, platform-custom-tab-generate, platform-flexipage-generate, platform-custom-application-generate, automation-flow-generate, platform-validation-rule-generate, platform-list-view-generate, platform-permission-set-generate
+  minApiVersion: "60.0"
+  relatedSkills:
+    - "automation-flow-generate"
+    - "platform-custom-application-generate"
+    - "platform-custom-field-generate"
+    - "platform-custom-object-generate"
+    - "platform-custom-tab-generate"
+    - "platform-flexipage-generate"
+    - "platform-list-view-generate"
+    - "platform-permission-set-generate"
+    - "platform-validation-rule-generate"
+  mcpTools:
+    salesforce-api-context:
+      tools: ["get_metadata_type_sections", "get_metadata_type_context", "get_metadata_type_fields", "get_metadata_type_fields_properties", "search_metadata_types"]
+      semver: ">=1.0.0"
+    metadata-experts:
+      tools: ["execute_metadata_action"]
+      semver: ">=1.0.0"
 ---
 
 # Generating Lightning App

package/skills/platform-mcp-tool-widget-coordinate/SKILL.md

@@ -0,0 +1,250 @@
+---
+name: platform-mcp-tool-widget-coordinate
+description: "Orchestrate object-based Lightning Type + HXL widget generation to render the output of a custom MCP server tool backed by an Apex Invocable Action. TRIGGER only when the prompt EXPLICITLY involves rendering an MCP tool result: user says 'MCP server', 'MCP tool', 'custom MCP server', references a tool 'output schema' / 'tool output' / 'outputValues' envelope, names an 'invocable action' backing an MCP tool, or asks to build a widget or rich UI rendition for the output of an Apex-invocable-backed MCP tool. DO NOT TRIGGER when: customizing an Apex-backed agent action output (use platform-lightning-type-widget-coordinate), authoring only a Custom Lightning Type (use platform-custom-lightning-type-generate), authoring only an Apex class (use platform-apex-generate), or building a standalone widget with no Lightning Type or MCP tool involved (use platform-widget-generate)."
+metadata:
+  version: "1.0"
+  minApiVersion: "68.0"
+  relatedSkills:
+    - "platform-apex-generate"
+    - "platform-custom-lightning-type-generate"
+    - "platform-lightning-type-widget-coordinate"
+    - "platform-widget-generate"
+  cliTools:
+    - tool: ["jq"]
+      semver: ">=1.6.0"
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+---
+
+# Rendering a Custom MCP Tool Output With a Widget
+
+Coordinate **two object-based Custom Lightning Types (CLTs)** and an **HXL widget** to render the output of a custom MCP server tool whose implementation is an Apex `@InvocableMethod`. This skill never authors content directly — it loads and invokes leaf skills in dependency order, gates progress on user approval, and runs validation gates before reporting completion.
+
+## Scope
+
+Custom MCP server tools backed by an Apex Invocable Action only. The MCP tool returns the platform's **invocable-action result envelope** — an object with `actionName`, `isSuccess`, and an `outputValues` node that carries the tool's real payload. To render this envelope with a widget, model it as **two object-based CLTs** (`lightning__objectType`) of equal standing — the only reason there are two is that one must reference the other by name (a CLT cannot reference itself), so they need distinct deployed names. Name and describe each by what it actually models — never by an invented role-label pair like "Payload CLT"/"Envelope CLT" or "Inner CLT"/"Outer CLT":
+
+- The CLT that mimics the tool-result envelope, named `<toolApiName>`. Its `outputValues` property is typed to the other CLT via `c__<responseCLT>`.
+- The CLT that is the exact shape of the Invocable Action's **response** (`@InvocableVariable` fields on the `@InvocableMethod` response class), named `<toolApiName>Response` — "Response" here is not an invented role word, it's the same word the Apex source already uses for that class (e.g. `GetAccountSummaryResponse`).
+
+The widget grounds on the **response fields** (flat), and the **default `renderer.json` in the envelope CLT** bridges the envelope nesting to the flat widget via `{!$attrs.outputValues.<field>}`.
+
+**Out of scope, route elsewhere:**
+
+- Customizing an **Apex-backed agent action** output (Apex-backed CLT `@apexClassType/...`, single CLT, surface-specific renderer) → `platform-lightning-type-widget-coordinate`.
+- A standalone widget with no MCP tool / Lightning Type → `platform-widget-generate`.
+- Authoring only a CLT or only an Apex class → `platform-custom-lightning-type-generate` / `platform-apex-generate`.
+
+> **Beta cardinality:** the invocable-action result is a bulk array (`content[]`). For the beta release this skill models and renders a **single response** — the first element of `content[]`. The CLT envelope models one result object, not the `content[]` wrapper.
+
+---
+
+## How this differs from `platform-lightning-type-widget-coordinate`
+
+| Dimension | agent-action flow (`...lightning-type-widget-coordinate`) | this MCP-tool flow |
+|---|---|---|
+| CLT kind | Apex-backed (`@apexClassType/...`) | Object-based (`lightning__objectType`) |
+| Number of CLTs | one | **two** (envelope + response) |
+| Field source | `@AuraEnabled` | **`@InvocableVariable`** on the response class |
+| Renderer location | `lightningTypes/<T>/lightningDesktopGenAi/renderer.json` (surface-specific) | `lightningTypes/<toolCLT>/renderer.json` (**default, parallel to `schema.json`**) |
+| Renderer binding | flat `{!$attrs.<field>}` | **nested `{!$attrs.outputValues.<field>}`** |
+
+---
+
+## Phase Graph
+
+| Phase | Purpose | Output |
+|---|---|---|
+| 1 — Input selection | Determine the payload source: an **invocable action API name** (preferred), an Apex Invocable class, or a pasted tool-output JSON sample. | `source` (`action` \| `apex` \| `sample`), tool API name |
+| 2 — Payload discovery | Describe the invocable action via the Actions REST API and read its typed `outputs` (or parse the response class from source, or `outputValues` from the sample). | `payloadFields` (name + `lightning:type`) |
+| 3 — Build plan | Print the plan in full; proceed unless the next reply explicitly pushes back. | printed plan |
+| 4 — Generation | Load and invoke leaf skills: response CLT → envelope CLT → widget → inline default renderer in the envelope CLT. | files written |
+| 5 — Validation | Run hard gates (block) and warn gates (advisory). | gate report |
+| 6 — Summary | Files, validations, deploy order, preview readiness. | summary |
+
+**Per-phase pattern:** load the skill fresh → execute its workflow → verify outputs → checkpoint before the next phase. Even if you remember a leaf skill's content, skills evolve — always load fresh.
+
+---
+
+## Phase 1 — Input selection
+
+Determine where the payload shape comes from. Prefer the sources top-to-bottom:
+
+| Source | Trigger | Phase 2 action |
+|---|---|---|
+| `action` | Prompt gives an **invocable action API name** — directly, or via an Apex class name that resolves to one — AND an authenticated org is available. **Preferred.** | Describe the action via the Actions REST API and read its typed `outputs`. |
+| `sample` | No reachable org (or the describe 404s), but a pasted tool-output JSON sample is available. | Parse the `outputValues` object from the sample. |
+| `apex` | Only the Apex **class** is available (no action name resolvable, no reachable org, no sample) — fallback only, may be stale relative to what's deployed. | Resolve the response class and enumerate `@InvocableVariable` fields. |
+
+Capture the **tool API name** (used to name all artifacts — see the naming convention below).
+
+**Source priority:** live/authoritative schema sources beat parsing a local class, which beats a pasted example. In order:
+1. **`action`** if an action API name and an authenticated org are available. The Actions REST API describe is the same schema the platform itself exposes, so it needs no request/helper filtering and gives real field types.
+2. **`sample`** if a runtime JSON sample is pasted (runtime response — explicit and current).
+3. **`apex`** if an Apex class exists locally AND none of the above apply (fallback only — may be stale relative to what's actually deployed behind the action).
+
+If none are available, STOP and ask the user for an action name, a class, a sample, or a schema.
+
+---
+
+## Phase 2 — Payload discovery
+
+FIRST Read `references/mcp-tool-output-discovery.md` (REQUIRED — do NOT run Phase 2 from this summary alone), then execute the procedure for the chosen source. Reminders:
+
+**For `action` (preferred):** describe the action with the Actions REST API and read its `outputs`:
+
+- Resolve the action API name (for Apex actions this is the **class name** declaring `@InvocableMethod`, not the method label).
+- `sf api request rest '/services/data/v<APIVER>/actions/custom/apex/<ActionApiName>' -o <org>`.
+- Use the `outputs` array only (each entry `{ name, label, type, maxOccurs }`). **Ignore `inputs`** — that is the tool input (request wrapper). A field with `maxOccurs > 1` is a list — surface it in the plan (beta renders a single response).
+- Map the Actions API `type` → CLT `lightning:type` (see the discovery reference's table; `STRING`/`ID`/`REFERENCE`/… → `lightning__textType`, `INTEGER`/`LONG` → `lightning__integerType`, `DOUBLE`/`DECIMAL`/`CURRENCY`/`PERCENT` → `lightning__numberType`, `BOOLEAN` → `lightning__booleanType`, `DATE`/`DATETIME` → date types). Match case-insensitively.
+- An entry with **`"type": null` and an `"apexClass": "<OuterClass>$<InnerClass>"` key** instead of a primitive `type` is a nested-object field, not a describe gap — see "Nested-object payload fields" below. The describe never exposes that class's own leaf fields, so retrieving/reading the named Apex class to enumerate them is the expected next step, not a fallback away from `action`.
+- If the describe 404s, fall back to `sample` (a pasted tool-output JSON) if one is available, else `apex` (parse the class from source, if locally available).
+
+**For `apex` (fallback):**
+
+- Locate the class (`<pkgDir>/classes/<ClassName>.cls`; retrieve `ApexClass:<ClassName>` if absent).
+- Identify the **response class** — the element type of the `@InvocableMethod` return `List<...>` (e.g. `List<GetAccountSummaryResponse>` → `GetAccountSummaryResponse`).
+- Enumerate its `@InvocableVariable` fields. **Exclude** the request class (the `@InvocableMethod` parameter type) and any `private` helper classes — those are not part of the tool's externally visible output schema.
+- Map Apex → CLT `lightning:type`: `String`/`Id` → `lightning__textType`, `Integer` → `lightning__integerType`, `Decimal`/`Double` → `lightning__numberType`, `Boolean` → `lightning__booleanType`, `Date` → `lightning__dateType`, `Datetime` → `lightning__dateTimeType`.
+- **A field whose type is itself an Apex class** (e.g. `flightInfo : SearchFlightsAction.Flight`) is a second, additive case alongside the flat-primitive mapping above — see "Nested-object payload fields" below. This applies to every source (`action`, `apex`, `sample`), not just `apex`.
+
+**For `sample` (fallback):** parse the `outputValues` object; infer each field's `lightning:type` from its JSON value (string → `lightning__textType`, integer → `lightning__integerType`, fractional number → `lightning__numberType`, boolean → `lightning__booleanType`).
+
+**Nested-object payload fields (applies to every source above):** when a response/output field's type is not a primitive but another Apex class (object), do NOT model it as `{"type":"object"}` or an inlined `lightning__objectType` — both produce an opaque, unrenderable blob and neither deploys. Instead:
+- Type the response CLT property as `"@apexClassType/<ns>__<OuterClass>$<InnerClass>"` (e.g. `"@apexClassType/c__SearchFlightsAction$Flight"`), matching the Apex-backed-CLT convention `platform-custom-lightning-type-generate` already documents.
+- Enumerate the referenced Apex class's own `@InvocableVariable`/public fields as the leaf set; the widget schema flattens to those leaves (never the object field itself).
+- The renderer binds one level deeper: `{!$attrs.outputValues.<objectField>.<leaf>}` (e.g. `{!$attrs.outputValues.flightInfo.flightId}`), not `{!$attrs.outputValues.<objectField>}`.
+- A field typed `List<ApexClass>` is out of scope for the beta single-response flow — surface it in the build plan like a `maxOccurs > 1` scalar, do not emit a schema for it.
+- See `references/two-clt-modeling.md` ("Nested-object payload fields") and `examples/nested-object-source-prompt.md` for the full walkthrough.
+
+Capture `payloadFields` — the ordered list of `{ name, title, lightning:type }` that defines the response CLT and the widget schema. Record which source produced it in the build plan.
+
+> Staleness: do NOT maintain a cross-session cache. Read the local project fresh and re-retrieve from the org per session.
+
+---
+
+## Phase 3 — Build plan + approval gate
+
+Print a build plan using the template in `references/build-plan-format.md`. The plan must list:
+
+- A one-line developer-facing summary (the `PLAN:` line).
+- The tool API name and the response class FQN (or "from pasted sample").
+- The two CLT names (envelope + payload) and the widget name, with absolute paths.
+- The envelope fields the envelope CLT will carry, and the response fields the response CLT + widget will carry.
+- `Properties omitted:` — any response fields intentionally dropped, with rationale. **`actionName` and `isSuccess` are envelope fields and never appear here or on the widget** — they belong to the envelope CLT only. Any payload-side operational/status field (`isSuccess`, `errorMessage`, `status`, `message`, and similar) that the response happens to carry is omitted from the widget by default and MUST be listed here with a one-line rationale — the widget renders `outputValues` data fields only.
+- The validations that will run after generation.
+
+**Print the plan in full, then proceed unless the user's next reply explicitly pushes back.** Explicit pushback = `no`, `stop`, `wait`, `change X`, `use Y instead`, or an equivalent rejection / revision request. Explicit approval is welcome but NOT required — silence, an unrelated follow-up, or the natural continuation of a single-turn eval all count as implicit approval. The invariant is the plan being visible in the transcript. If pushback arrives, revise and re-print before moving on.
+
+---
+
+## Phase 4 — Generation
+
+Load and invoke leaf skills in this order. For each: load the skill, execute its workflow against the Phase 3 spec, verify the outputs, checkpoint before the next.
+
+1. **Response CLT** — load `platform-custom-lightning-type-generate`. Author an object-based CLT `<responseCLT>` (convention: `<toolApiName>Response`) whose `properties` are the `payloadFields` from Phase 2 (1:1 with the response `@InvocableVariable` fields). Root is `lightning__objectType`, with root-level `"lightning:tags": ["mcp"]`.
+
+2. **Envelope CLT** — load `platform-custom-lightning-type-generate`. Author an object-based CLT `<toolCLT>` (convention: `<toolApiName>`, the envelope), also with root-level `"lightning:tags": ["mcp"]`, and:
+   - `actionName` → `lightning__textType`
+   - `isSuccess` → `lightning__booleanType`
+   - `outputValues` → **`c__<responseCLT>`** (the referenced-CLT pattern; the response CLT must be deployed before the envelope CLT)
+   - Add `message` / other envelope scalars only if the widget needs to render them.
+
+3. **Widget** — load `platform-widget-generate`. Author a **flat** widget whose `schema.json` properties are the `payloadFields` (name + primitive type) — a standalone widget contract, not derived from or coupled to any Lightning Type. It renders **only `outputValues` data fields**: never `actionName`/`isSuccess` (envelope-only), and never a response-side operational/status field declared in `Properties omitted:`. The widget body binds each field via `{!$attrs.<field>}` — the widget is envelope-agnostic and never references `outputValues` itself.
+
+4. **Default renderer (authored inline in the ENVELOPE CLT — never optional).** FIRST Read `platform-custom-lightning-type-generate/references/widget-rendition.md` (REQUIRED — do NOT author from memory or copy an existing sample, which may use a deprecated shape). Then author `<pkgDir>/lightningTypes/<toolCLT>/renderer.json` — the **default renderer, at the bundle root, parallel to `schema.json`** (NOT under `lightningDesktopGenAi/`). Shape:
+
+   ```json
+   {
+     "renderer": {
+       "componentOverrides": {
+         "$": {
+           "definition": "@widget/c/<widgetName>",
+           "attributes": {
+             "<payloadField>": "{!$attrs.outputValues.<payloadField>}"
+           }
+         }
+       }
+     }
+   }
+   ```
+
+   The renderer maps **every widget schema property** to the matching payload field nested under the envelope's `outputValues` node via `{!$attrs.outputValues.<payloadField>}`. This nested binding is the crux of this flow — it bridges the envelope CLT to the flat widget. Do **NOT** duplicate the widget body inside `renderer.json`.
+
+**Existing-renderer handling:** if `renderer.json` already exists at the target path, read it first. If it references the same widget with the same bindings, leave it. If it references a different widget or a custom-LWC root override (`c/<component>`), STOP and surface the conflict before overwriting.
+
+---
+
+## Phase 5 — Validation gates
+
+Read `references/validation-gates.md` and **run every gate**. Widget-bundle-internal checks (schema parse, root keys, leaf types, `{!$attrs.X}` resolution, `.uiwidget-meta.xml` well-formedness) are owned by `platform-widget-generate` and run in its own self-validation.
+
+**Hard — block on failure:**
+
+1. `clt-reference-integrity` — the envelope CLT's `outputValues` property has `lightning:type === "c__<responseCLT>"`, the response CLT exists at `<pkgDir>/lightningTypes/<responseCLT>/schema.json`, both parse as JSON, and neither carries `$schema` or (nested) `items`.
+2. `renderer-wires-widget` — `<pkgDir>/lightningTypes/<toolCLT>/renderer.json` exists (at the bundle root, **not** `lightningDesktopGenAi/`), parses, wires the widget via `componentOverrides["$"].definition === "@widget/c/<widgetName>"`, and binds every widget schema property as **`{!$attrs.outputValues.<property>}`** (nested path). Bidirectional: missing or extra bindings both fail.
+
+**Warn — advisory:**
+
+1. `field-trace` — RUN the trace in `references/validation-gates.md`: grep `@InvocableVariable` from the **response** class, `jq` the widget schema property keys, print both lists, classify INVENTED vs OMITTED. Invented widget fields fail; silent omissions (a response field absent from the widget AND absent from the Phase 3 `Properties omitted:` plan) warn.
+
+Report each gate result by name in Phase 6 (`pass`, `fail (<reason>)`, `warn (<reason>)`, `not run`). Do **not** summarize as "all passed". This skill produces metadata only — it does not deploy; deployment is the caller's responsibility.
+
+---
+
+## Phase 6 — Summary
+
+```text
+MCP Tool Widget Build Complete: <widgetName>
+
+FILES GENERATED:
+  Response CLT:
+    <pkgDir>/lightningTypes/<responseCLT>/schema.json
+  Envelope CLT:
+    <pkgDir>/lightningTypes/<toolCLT>/schema.json
+    <pkgDir>/lightningTypes/<toolCLT>/renderer.json          # default renderer — wires the widget
+  Widget bundle:
+    <pkgDir>/uiWidgets/<widgetName>/<widgetName>.json
+    <pkgDir>/uiWidgets/<widgetName>/schema.json
+    <pkgDir>/uiWidgets/<widgetName>/<widgetName>.uiwidget-meta.xml
+
+VALIDATIONS:
+  widget self-validation (platform-widget-generate gates): <pass | fail — see sub-skill report>
+  clt-reference-integrity (envelope.outputValues → c__<responseCLT>): <pass | fail (<reason>)>
+  renderer-wires-widget (nested {!$attrs.outputValues.X} bindings): <pass | fail (<reason>)>
+  field-trace (INVENTED + OMITTED lists printed): <pass | warn (<reason>) | fail (invented: <list>)>
+```
+
+---
+
+## Hard Rules (always apply)
+
+1. **Plan-first, then proceed.** Print the full Phase 3 build plan before writing any file. Explicit rejection or a change request → stop and revise; otherwise continue. The invariant is the plan being visible in the transcript, not an interactive human approval — this holds in manual chat, agent-to-agent flows, and single-turn evals.
+2. **Two object-based CLTs, never one.** The envelope and the payload are separate CLTs. The envelope's `outputValues` is typed via `c__<responseCLT>`, never inlined as a nested `lightning__objectType`. Both CLTs carry root-level `"lightning:tags": ["mcp"]` (see `platform-custom-lightning-type-generate/assets/primitive-types-and-constraints.md`).
+3. **Renderer lives in the ENVELOPE CLT, at the bundle root.** `lightningTypes/<toolCLT>/renderer.json` — the default renderer, parallel to `schema.json`. Never `lightningDesktopGenAi/renderer.json` (that is the agent-action flow's surface-specific path), never in the response CLT.
+4. **Renderer bindings are nested.** Every widget attribute maps to `{!$attrs.outputValues.<field>}`, not `{!$attrs.<field>}`. The widget schema stays flat; the renderer does the bridging.
+5. **Widget grounds on the payload, not the envelope, and renders `outputValues` data fields only.** The widget schema properties are the payload fields. The widget never references `actionName` or `isSuccess` — those are envelope-only. A payload field that is itself operational/status (`isSuccess`, `errorMessage`, `status`, `message`, and similar) is omitted from the widget by default and declared in `Properties omitted:`.
+6. **Field source is `@InvocableVariable` on the response class.** Enumerate the response class only. Exclude the request class and private helper classes.
+7. **No invented fields, no silent omissions.** The widget schema (and the response CLT) must be a subset of the response `@InvocableVariable` fields. Omission requires the field to appear in the Phase 3 `Properties omitted:` section with an approved rationale. `field-trace` prints both lists.
+8. **Single response for beta.** Model one result object, not the `content[]` bulk wrapper.
+9. **Always load the leaf skill** before generation. Do not author from memory.
+10. **Run gates, do not describe them.** Reporting `pass` without executing a gate is a hard violation; report `not run` instead.
+11. **No shell metacharacters that trigger the Vibes safe-shell filter.** In every `Bash` tool call emitted by this orchestrator and by any leaf skill it invokes, do NOT use command substitution (`$(…)` or backticks), process substitution (`<(…)`, `>(…)`), brace expansion (`{a,b,c}` or `{1..N}`), or `eval` / `exec`. These force manual approval even under Bypass mode and stall the eval. Run separate commands (`mkdir -p a && mkdir -p b`), print each intermediate value with its own command and reason about the result, and use plain shell variables (`X=literal`) or here-strings when a value must be reused.
+12. **Resolve `action` schema from the Actions REST API describe, never from raw HTTP to the MCP endpoint or from credential extraction.** Use `sf api request rest` against the org's Actions REST API (which uses the existing `sf` org auth). Never read `a4d_mcp_settings.json` or any MCP settings file, never extract an org access token, never `curl` an MCP server endpoint directly — that requires credentials the session doesn't have and targets a URL the runtime doesn't actually expose that way.
+13. **Never invoke an MCP tool to discover its output shape.** Describing the payload must never execute the underlying action. Resolve the schema via the Actions REST API describe of the backing action — never by calling the tool with sample/guessed input to observe a response. If no action name is resolvable, ask the user for a pasted `sample` instead of invoking anything.
+14. **A response field typed as another Apex class is never a bare `{"type":"object"}`.** Type it `@apexClassType/<ns>__<OuterClass>$<InnerClass>` in the response CLT, flatten to its leaf fields in the widget, and bind the renderer two levels deep (`{!$attrs.outputValues.<objectField>.<leaf>}`). This is additive to the flat-primitive case (Hard Rule 5), not a replacement for it — see `references/two-clt-modeling.md`.
+
+---
+
+## Reference File Index
+
+| File | When to read |
+|------|--------------|
+| `references/mcp-tool-output-discovery.md` | Phase 2 — the three sources (`action` describe via Actions REST API; pasted `sample`; `apex` class parse), field enumeration, and type mapping. |
+| `references/two-clt-modeling.md` | Phase 4 — how the envelope + response CLTs and the nested renderer binding fit together, with the naming convention and nested-object payload handling. |
+| `references/build-plan-format.md` | Phase 3 — plan template the model fills before proceeding. |
+| `references/validation-gates.md` | Phase 5 — full hard / warn gate table with RUN procedures. |
+| `examples/action-name-source-prompt.md` | Phase 3 — a complete walkthrough starting from an invocable action API name (preferred source). |
+| `examples/apex-invocable-source-prompt.md` | Phase 3 — a complete walkthrough starting from an Apex Invocable class (fallback). |
+| `examples/pasted-tool-output-prompt.md` | Phase 3 — a complete walkthrough starting from a pasted tool-output sample (fallback). |
+| `examples/nested-object-source-prompt.md` | Phase 3 — a complete walkthrough where a payload field is itself an Apex-class reference, not a primitive. |