@salesforce/afv-skills 1.65.1 → 1.67.0

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

@@ -37,7 +37,7 @@ For authoritative Metadata API type, field, and enum details beyond this skill,
 | Root element | `<GlobalValueSet>` | `<StandardValueSet>` |
 | Name source | filename (dev name) | `<fullName>` = fixed catalog name |
 | Value element | `<customValue>` | `<standardValue>` |
-| Can add NEW values? | Yes | No — modify existing only |
+| Can add NEW values? | Yes | Yes — copy the attribute pattern of an existing value |
 | Can create a new NAME? | Yes | No — only the fixed catalog |
 | `*` wildcard in package.xml | Supported | Not supported |
 
@@ -50,7 +50,7 @@ For authoritative Metadata API type, field, and enum details beyond this skill,
 This document defines the mandatory constraints for generating value-set metadata XML. The agent must verify these constraints before outputting XML to prevent Metadata API deployment errors.
 
 - **GlobalValueSet** — a reusable, named set of picklist values defined once and referenced by any number of picklist/multi-select fields. Use when the same value list is shared across multiple fields.
-- **StandardValueSet** — the value list behind a Salesforce-defined standard picklist (Industry, Lead Source, etc.). You can only **modify** the values in a fixed catalog of named sets; you cannot invent a new set or add brand-new values.
+- **StandardValueSet** — the value list behind a Salesforce-defined standard picklist (Industry, Lead Source, etc.). You can only customize the fixed catalog of named sets, so you cannot invent a new set name, but you can modify existing values and add new ones.
 
 ---
 
@@ -142,16 +142,16 @@ In API 57.0+ orgs the platform *stores/displays* a GlobalValueSet's developer na
 
 #### HARD CONSTRAINTS — read before generating
 
-1. **You can ONLY modify values inside the fixed catalog of named standard value sets.** You **cannot** add a brand-new value, and you **cannot** create a new StandardValueSet name. The Metadata API will reject both.
+1. **A StandardValueSet name must come from the fixed catalog of named standard value sets.** You **cannot** create a new StandardValueSet name. You **can** add a new value to an existing standard set, but copy the full attribute pattern of an existing value in that set (for example `closed`, `forecastCategory`, `probability` and `won` on `OpportunityStage`), because omitted attributes are filled with platform defaults that can be wrong.
 2. The root carries a `<fullName>` whose value is the **fixed enum name** (e.g. `Industry`), NOT a `masterLabel`. The filename must match this name.
 3. Values are `<standardValue>` entries — **not** `<customValue>`.
-4. **Emit ONLY the values the request explicitly names — a surgical, minimal change.** Include a `<standardValue>` block for each value the user asks you to activate, deactivate, relabel, or reorder, and **nothing else**. Do **not** enumerate the full picklist or emit `<standardValue>` entries for values the request did not mention. A StandardValueSet deployment is a partial update: unlisted values keep their current org state untouched. Reproducing every value (e.g. all 30+ Industry entries) is noise and risks clobbering org state — it is wrong even when the request says "keep *only* X active," which means "set the named ones; leave the rest as-is," not "enumerate and deactivate everything else." If you use the grounding MCP to discover existing values, use it only to confirm the named values exist and to get their exact `<fullName>`/`<label>` — not as a list to reproduce in full.
+4. **A StandardValueSet write REPLACES the whole set. Send every existing value and change only what the request names.** Read the current set first (grounding MCP or a retrieve), then include a `<standardValue>` block for every existing value, with the requested activations, deactivations, relabels or additions applied. A value you leave out is deactivated on the field: a deploy that named only `Web` in `CaseOrigin` left `Email`, `Phone` and `Agentforce` inactive. Never send only the named values, even when the set is large (for example all 30+ `Industry` entries). Request wording such as "keep *only* X active" means set X active and every other value inactive, so state that intent in the result. Verify by reading the set back and diffing it against the read taken before the write.
 
 #### `<standardValue>` — Modifiable Sub-Elements
 
 | Sub-element | Modifiable? | Notes |
 |-------------|-------------|-------|
-| `<fullName>` | Identifies the value (must already exist) | Cannot introduce a new one |
+| `<fullName>` | Identifies the value | An existing value, or a new one you are adding |
 | `<label>` | Yes | Relabel the value's UI text |
 | `<isActive>` | Yes | `false` deactivates; omit or `true` keeps active |
 | `<default>` | Yes | At most one value `true` |
@@ -165,7 +165,7 @@ In API 57.0+ orgs the platform *stores/displays* a GlobalValueSet's developer na
 > `https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/standardvalueset_names.htm`.
 > If the name is not in that appendix, it is **not** a StandardValueSet — it is either a GlobalValueSet or an inline CustomField picklist.
 
-#### CORRECT — StandardValueSet (modify existing values only)
+#### CORRECT — StandardValueSet (the complete set, with the requested change applied)
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
@@ -183,6 +183,7 @@ In API 57.0+ orgs the platform *stores/displays* a GlobalValueSet's developer na
         <label>Agriculture</label>
         <isActive>false</isActive>   <!-- deactivated, but kept in the set -->
     </standardValue>
+    <!-- ... every other existing standardValue entry repeated unchanged ... -->
 </StandardValueSet>
 ```
 
@@ -192,23 +193,23 @@ In API 57.0+ orgs the platform *stores/displays* a GlobalValueSet's developer na
 <StandardValueSet xmlns="http://soap.sforce.com/2006/04/metadata">
     <masterLabel>Industry</masterLabel>     <!-- WRONG: StandardValueSet uses <fullName>, not masterLabel -->
     <customValue>                           <!-- WRONG: uses <standardValue>, not customValue -->
-        <fullName>Renewable Energy</fullName> <!-- WRONG: cannot ADD a new value to a standard set -->
+        <fullName>Renewable Energy</fullName>
         <label>Renewable Energy</label>
     </customValue>
 </StandardValueSet>
 ```
 
-**Errors:** unknown element `masterLabel`/`customValue`; adding a value not already in the standard catalog fails deployment.
+**Errors:** unknown element `masterLabel`/`customValue` for a StandardValueSet.
 
 ---
 
 ### 4. Never Invent Values — Verify, Don't Hallucinate CRITICAL
 
-When customizing a **StandardValueSet** (or extending a shared GlobalValueSet), **only modify values that already exist** — never invent the value list of a standard picklist. The hard rule is about what you EMIT: a `<standardValue>` whose `<fullName>` is not a real catalog value will fail deployment.
+When customizing a **StandardValueSet** (or extending a shared GlobalValueSet), **never invent the existing value list of a standard picklist**. Existing values must be repeated exactly as the org has them, and a new value is added only when the request names it.
 
-For well-known standard picklists you already know the canonical values (e.g. `Industry`, `LeadSource`, `OpportunityStage`). When you are unsure a named value exists, you can confirm it against the live org — but treat lookup as a *confirmation* step, not a required first call:
+For well-known standard picklists you already know the canonical values (e.g. `Industry`, `LeadSource`, `OpportunityStage`). When you are unsure which values exist, you can confirm them against the live org — but treat lookup as a *confirmation* step, not a required first call:
 
-- **Grounding MCP** (if available) exposes `search_metadata` and `query_metadata` to look up live metadata. Use them only to confirm a named value's exact `<fullName>`/`<label>` — not to pull the full list to reproduce.
+- **Grounding MCP** (if available) exposes `search_metadata` and `query_metadata` to look up live metadata. Use them to read the complete current set, because a write must repeat every existing value with its exact `<fullName>`/`<label>`.
 - **CLI fallback** — query the Tooling API directly:
 
 ```bash
@@ -216,7 +217,7 @@ sf data query --use-tooling-api \
   --query "SELECT MasterLabel, Metadata FROM StandardValueSet WHERE MasterLabel = '<name>'"
 ```
 
-> **The point is the output, not the lookup:** emit modifications ONLY to values you know exist. A generated StandardValueSet that introduces unseen values is a hallucination and will fail deployment. (This pairs with the minimal-scope rule in §3: confirm the *named* values; don't enumerate the whole set.)
+> **The point is the output, not the lookup:** the written set must contain every existing value unchanged, plus only the changes the request names. Do not invent values the request did not ask for. (This pairs with rule 4 in §3: a write replaces the whole set.)
 
 ---
 
@@ -247,17 +248,16 @@ The agent must **reject** and explain — not silently "fix" by inventing metada
 
 | Violation | Action / Message |
 |-----------|------------------|
-| Add a NEW value to a **StandardValueSet** | Reject. "Standard value sets cannot accept new values. Create a **GlobalValueSet** (reusable) or an inline picklist on a **CustomField** instead." |
 | Create a NEW StandardValueSet name | Reject. The name must be in the standard catalog appendix. Otherwise it is a GlobalValueSet. |
 | **Value set developer name** with spaces / invalid chars | Convert spaces to underscores; must start with a letter; alphanumeric + underscore only. `Priority Levels` → `Priority_Levels`. (This applies to the value SET name and the field API name — NOT to individual `<customValue><fullName>` values, which keep spaces as written.) |
 | Duplicate value `fullName` within one set | Reject. Each `fullName` must be unique within the value set. |
 | More than one `<default>true</default>` | Reject. At most one default value per set. |
 
-#### INCORRECT — adding a value to a standard set
+#### Adding a value to a standard set
 
 > "Add a `Cryptocurrency` value to the Industry picklist."
 
-Do not emit a `<standardValue>` with `fullName` `Cryptocurrency`. Respond that standard value sets are a fixed catalog and propose a GlobalValueSet (if reused across fields) or an inline restricted picklist on a single CustomField.
+This is allowed. Read the complete current `Industry` set, then write it back with every existing value unchanged plus one new `<standardValue>` for `Cryptocurrency`. Copy the attribute pattern of an existing value in the set, because omitted attributes get platform defaults that can be wrong.
 
 ---
 
@@ -275,7 +275,7 @@ A value set must deploy **before** any CustomField that references it.
 
 | Error / Symptom | Cause | Fix |
 |-----------------|-------|-----|
-| Value not added to standard picklist | Tried to ADD a value to a `StandardValueSet` | Standard sets are fixed; use GlobalValueSet or inline CustomField picklist |
+| Other values of a standard picklist became inactive after a deploy | The deploy listed only some values, and a write replaces the whole set | Resend the complete set with every existing value (§3 rule 4) |
 | `Required field missing: sorted` | GlobalValueSet missing `<sorted>` | Add `<sorted>true</sorted>` or `<sorted>false</sorted>` |
 | Unknown element `masterLabel` (StandardValueSet) | Used `masterLabel` instead of `fullName` | StandardValueSet root uses `<fullName>` = catalog name |
 | Unknown element `customValue` (StandardValueSet) | Used `customValue` instead of `standardValue` | Use `<standardValue>` in standard sets |
@@ -301,12 +301,12 @@ Before generating value-set XML, verify:
 - [ ] When referencing from a field, is `<valueSetName>` the **bare** developer name with NO `__gvs` suffix?
 
 ### StandardValueSet Checks CRITICAL
-- [ ] Are you emitting modifications ONLY to values you know exist (confirmed from known standard catalogs, or via grounding `search_metadata`/`query_metadata` / Tooling API if unsure) — never invented values?
+- [ ] Did you read the complete current set (grounding `search_metadata`/`query_metadata` / Tooling API / retrieve) so every existing value is repeated exactly?
 - [ ] Is the root `<StandardValueSet>` with the correct namespace?
 - [ ] Does the root use `<fullName>` set to the fixed catalog name (NOT `masterLabel`)?
 - [ ] Are values `<standardValue>` entries (NOT `customValue`)?
-- [ ] Are you ONLY modifying values that already exist (no new `fullName`)?
-- [ ] Did you avoid adding a brand-new value or a new set name?
+- [ ] Does the written set contain every existing value, with only the changes the request names applied?
+- [ ] Did you avoid a new set name, and for any new value did you copy the attribute pattern of an existing value?
 
 ### Shared Checks
 - [ ] At most one value has `<default>true</default>`?

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

@@ -2,17 +2,16 @@
 name: platform-widget-generate
 description: "Use this skill to author a complete HXL WidgetBundle (UEM body + schema.json + -meta.xml). TRIGGER when: user asks for a widget, mosaic, fragment, card, or rich UI surface for any subject, domain, feature, or entity noun; the prompt names only an entity or data shape without invoking Lightning Types, CLTs, or Apex-backed types. DO NOT TRIGGER when: the prompt explicitly says 'Lightning Type', 'CLT', 'Custom Lightning Type', 'Apex-backed type', or references '@apexClassType/...' (use platform-lightning-type-widget-coordinate); authoring a custom-LWC renderer for a Custom Lightning Type (use platform-custom-lightning-type-generate); or editing only an LWC component."
 metadata:
-  version: "1.4"
+  version: "1.5"
   domains: ["Platform", "Agentforce"]
   minApiVersion: "68.0"
+  cliTools:
+    - tool: ["sf"]
+      semver: ">=2.0.0"
   relatedSkills:
     - "platform-apex-generate"
     - "platform-custom-lightning-type-generate"
     - "platform-lightning-type-widget-coordinate"
-  mcpTools:
-    metadata-experts:
-      tools: ["execute_metadata_action"]
-      semver: ">=1.0.0"
 ---
 
 # Generating a Widget Bundle
@@ -67,23 +66,49 @@ The first child of `tile/widget.children` SHOULD be a single `tile/column`. All
 
 ---
 
-## Available Metadata Actions
+## Available Invocable Actions
+
+Both are standard invocable actions on the target org.
+
+### Calling Convention
+
+Fire each action with whichever mechanism is available: the H360 MCP `dispatch` tool (a `POST` to the endpoint path with the request body) or `sf api request rest`. Use `v{version}` = this skill's `minApiVersion`. Never use `curl`, and never extract the org's access token.
+
+```bash
+sf api request rest '/services/data/v{version}/actions/standard/<actionName>' --method POST --body '<request body>' --target-org <org>
+```
+
+### Response Handling
+
+Each response is an array with one envelope (`dispatch` nests it under `body`). Check three failure layers, in order:
+
+| Layer | Signal | Action |
+|---|---|---|
+| Transport / auth | `dispatch` `status_code` is not 200, or CLI exits non-zero | Surface the error |
+| Action | `[0].isSuccess` is `false`, or `[0].errors` is non-empty | Surface `errors[].message` |
+| Per-entry (`getUiComponentSchemas` only) | any `componentSchemas[].success` is `false`, even when `[0].isSuccess` is `true` | Treat that block as unavailable |
+
+On success, read `[0].outputValues`.
 
 ### discoverUiComponents
 
 **Purpose:** Discover the palette of blocks available for composition.
 
-**Required parameters:** `actionName: "discoverUiComponents"`, `metadataType: "FRAGMENT"`, `parameters.pageType: "FRAGMENT"`. Optional: `searchQuery` to filter by name/description.
+**Endpoint:** `POST /services/data/v{version}/actions/standard/discoverUiComponents`
+
+**Request body:** `{"inputs":[{"pageType":"FRAGMENT"}]}`
 
-**Returns:** list of `{ definition, description, label, attributes? }`.
+**Returns:** `outputValues.componentDefinitions[]` — list of `{ definition, description, label }`.
 
 ### getUiComponentSchemas
 
-**Purpose:** Fetch JSON schemas (property types, required vs optional, validation) for selected blocks.
+**Purpose:** Fetch schemas (property types, required vs optional, validation) for selected blocks.
+
+**Endpoint:** `POST /services/data/v{version}/actions/standard/getUiComponentSchemas`
 
-**Required parameters:** `actionName: "getUiComponentSchemas"`, `metadataType: "FRAGMENT"`, `parameters.pageType: "FRAGMENT"`, `parameters.componentDefinitions: ["namespace/definition", ...]`. Optional: `includeKnowledge` (default `true`).
+**Request body:** `{"inputs":[{"pageType":"FRAGMENT","componentDefinitions":["namespace/definition", ...]}]}`
 
-**Returns:** `componentSchemas[]` — success entries carry the JSON schema, failure entries carry an error message. Partial failures are supported.
+**Returns:** `outputValues.componentSchemas[]` — list of `{ definition, success, schema }` (`schema` is a YAML string). Partial failures are supported.
 
 > Never pass `tile/widget` to `getUiComponentSchemas` — it is a fixed wrapper, not a queryable component.
 
@@ -94,6 +119,7 @@ The first child of `tile/widget.children` SHOULD be a single `tile/column`. All
 - Bind a block property to runtime data with `{!$attrs.<attrName>}`. `<attrName>` MUST match a property name in `schema.json`.
 - Inside a `forEach`, reference the loop variable instead — e.g. `"text": "{!$item.name}"`. See `references/widget-meta-directives.md`.
 - A binding may be a **formula expression** instead of a bare field reference. See `references/widget-formulas.md` for the full supported-function list, syntax, and gotchas.
+- **Localization:** only when the user asks for localized or translated text (or names Custom Labels / `$Label`), write static, user-visible strings as Custom Label references — `{!$Label.c.<LabelName>}`. See `references/widget-labels.md`.
 
 ---
 
@@ -106,28 +132,7 @@ The first child of `tile/widget.children` SHOULD be a single `tile/column`. All
 | `action/openLink` | synchronous | `url` (string). Optional `target` (`_blank`\|`_self`, default `_blank`) | Opens a URL |
 | `action/sendMessage` | asynchronous | `content` (string) | Posts a new user message back to the agent and earns a fresh turn |
 
-```json
-{
-  "definition": "tile/button",
-  "attributes": {
-    "label": "Button Label",
-    "variant": "primary",
-    "actions": { "click": [ { "definition": "action/sendMessage", "attributes": { "content": "content" } } ] }
-  }
-}
-```
-
-```json
-{
-   "definition": "tile/button",
-   "attributes": {
-      "label": "Button Label",
-      "variant": "primary",
-      "actions": { "click": [ { "definition": "action/openLink", "attributes": { "url": "https://www.example.com", "target": "_blank" } } ] }
-   }
-}
-```
-
+See `references/widget-actions.md` for complete `sendMessage` and `openLink` button JSON.
 
 **A `tile/button` with no `actions` attribute renders disabled** — a button exists to trigger an action, so always attach a `click` action to a button meant to be interactive.
 
@@ -150,16 +155,7 @@ These conventions cover widget *structure* — how blocks are grouped and stacke
 
 ## Styling Best Practices
 
-Widgets express *intent*, not pixels. Each surface provides a default look and feel; brand/theme overrides apply automatically.
-
-- **Style semantically.** Use `variant`, `size`, and other enum-typed attributes (`primary`, `destructive`, `success`, `warning`). Do not pin literal colors or pixel values.
-- **One primary action per visible group.** At most one `tile/button` with `variant: primary`. Use `secondary` or `destructive` for additional actions (see the `tile/button` schema for the full variant enum).
-- **Every `tile/button` needs a `click` action.** See *Actions* above — an action-less button renders disabled.
-- **One `h1` per widget.** Use `h2`/`h3` for sub-section headings, `body` for prose, `caption` for helper text.
-- **Use semantic state variants on state-bearing blocks** (`tile/badge`, `tile/callout`).
-- **Accept schema defaults for `gap`, `size`** unless there is a specific reason to override.
-- **Don't pin `width`** unless a content constraint requires it.
-- **Use the Lucide icon set.** Pass the Lucide name (`"check"`, `"alert-circle"`); other icon libraries are not supported.
+Style semantically (variants, not literal colors or pixels), one primary button per group, one `h1` per widget, Lucide icons only. Read `references/widget-styling.md` before assigning variants, sizes, or icons.
 
 ---
 
@@ -169,11 +165,11 @@ Widgets express *intent*, not pixels. Each surface provides a default look and f
    - If `lightningTypeSchema` was passed by the orchestrator → derive per `references/schema-from-lightning-type.md`.
    - Otherwise → infer the list directly from the user prompt (pasted JSON payload, enumerated field list, or descriptive prose).
 
-2. **Discover blocks (REQUIRED — do NOT skip).** Call the `discoverUiComponents` metadata action via `execute_metadata_action`. Use property types from the widget spec to seed `searchQuery` (text → `"text"`, number → `"number"`). **If `discoverUiComponents` returns `success: false`, an error, or an empty list, STOP and surface the error verbatim — do not improvise block names from memory, prior runs, or training data. Re-run discover with a different `searchQuery` only if the failure is search-query-specific.**
+2. **Discover blocks (REQUIRED — do NOT skip).** Call the `discoverUiComponents` invocable action (see *Available Invocable Actions*) and match widget-spec property types against the returned `label`/`description` values. **If `isSuccess` is `false`, `errors` is non-empty, or `componentDefinitions` is empty, STOP and surface the error verbatim — do not improvise block names from memory, prior runs, or training data.**
 
 3. **Select blocks.** Choose one block per widget-spec property, plus structural primitives from *Layout Best Practices*.
 
-4. **Get block schemas (REQUIRED — do NOT skip).** Call the `getUiComponentSchemas` metadata action via `execute_metadata_action` for the selected blocks. Review property metadata. **If `componentSchemas` returns all-failure or empty, STOP and surface the error — do not improvise from existing widgets in the project.**
+4. **Get block schemas (REQUIRED — do NOT skip).** Call the `getUiComponentSchemas` invocable action for the selected blocks. Review property metadata, including each property's `default` — omit any attribute whose value would equal it (see `references/widget-styling.md`). **If `isSuccess` is `false`, `componentSchemas` is empty, or any entry has `success: false`, do not use that block — re-select a different one from step 2's results; if none works, STOP and surface the error. Never improvise from existing widgets in the project.**
 
 5. **Build the UEM tree (example reads REQUIRED — do NOT skip).** First, identify which patterns match the widget spec and read each matching example file from this skill's own `examples/` directory (`<skill-root>/examples/`):
 
@@ -182,12 +178,15 @@ Widgets express *intent*, not pixels. Each surface provides a default look and f
    | Single object (no iteration) | `<skill-root>/examples/single-object.json` |
    | Any list iteration (root-level array, nested list, or list embedded in a single-object widget) | `<skill-root>/examples/list-with-foreach.json` |
    | Conditional rendering (`if` bound to a boolean or formula) | `<skill-root>/examples/conditional.json` |
-   | Computed values, text/number transforms, or `if` driven by a formula (not a bare boolean field) | `<skill-root>/examples/formulas.json` |
+   | Computed values, text/number transforms, locale-formatted numbers/currency/dates, or `if` driven by a formula (not a bare boolean field) | `<skill-root>/examples/formulas.json` |
+   | The user asked for localized / translated text (Custom Labels) | `<skill-root>/examples/localized-labels.json` |
 
    A spec may match multiple patterns (e.g. a list of items where some items render conditionally reads both `list-with-foreach.json` and `conditional.json`). **Read every matching example, and only those — do not skip the read because the pattern feels familiar.**
 
    **Before writing any formula**, read `references/widget-formulas.md` in full — it is the authoritative list of supported operators and functions; do not improvise a function name or operator that isn't documented there.
 
+   **Before writing any `$Label` reference**, read `references/widget-labels.md` in full.
+
    Then:
    - Map each widget-spec property to a block property; preserve spec order.
    - **Decide root iteration:** single object → properties directly under root `tile/column`. Collection → wrap repeating block in `forEach`/`forItem`. See `references/widget-meta-directives.md`.
@@ -236,17 +235,10 @@ Widgets express *intent*, not pixels. Each surface provides a default look and f
 
    Write all three before proceeding to self-validation.
 
-9. **Self-validate.** Before reporting, confirm each check below and report each result individually (`pass` or `fail (<reason>)`). Do **not** summarize as a single "all passed" line — list every check so a reviewer can spot a silent skip.
-    - **`schema-parses`** — `<pkgDir>/uiWidgets/<widgetName>/schema.json` parses as JSON.
-    - **`schema-root-keys`** — root has `title` (string), `type: "object"`, and `properties.attributes` (object) — where `properties.attributes` carries `lightning:type: "lightning__objectType"` and a nested `properties` map. No `unevaluatedProperties: false`.
-    - **`schema-leaf-types`** — every leaf under `properties.attributes.properties` carries a `lightning:type`. Singular nested inner-class fields carry `lightning:type` set to the inner Apex class reference (`@apexClassType/<namespace>__<OuterClass>$<InnerClass>`); the nested shape is not redeclared. `List<InnerClass>` fields carry `lightning:type: "lightning__listType"` with `items.lightning:type` set to the inner Apex class reference (`@apexClassType/<namespace>__<OuterClass>$<InnerClass>`), not a redeclared field map — see `references/schema-from-lightning-type.md`. **When the list has no Apex-backed type** (schema inferred from the prompt), `items.lightning:type: "lightning__objectType"` MUST carry an inline nested `properties` map for every item field the body binds via `{!$item.X}`.
-    - **`bindings-resolve`** — every `{!$attrs.X}` (or `{!$attrs.<outerField>.<innerField>}` for nested objects) in `<widgetName>.json` resolves to a property under `schema.json` `properties.attributes.properties`, and every `{!$item.X}` resolves to a `forItem` loop variable defined upstream. This applies to `$attrs`/`$item` references **inside formula expressions** too.
-    - **`formulas-supported`** — every function name used inside a `{!...}` expression appears in the *Supported functions* list in `references/widget-formulas.md`.
-    - **`body-envelope`** — `<widgetName>.json` root has `type: "lightning__agentforceWidget"` and a `contentBody` object whose `widgetBody` carries the UEM tree rooted at `tile/widget`. No node in the tree — root or non-root — carries a `type` key.
-    - **`metaxml-wellformed`** — `<widgetName>.uiwidget-meta.xml` parses as well-formed XML.
-    - **`metaxml-elements`** — `<widgetName>.uiwidget-meta.xml` has root `<UiWidgetBundle>` and contains `<masterLabel>` (non-empty), `<description>` (non-empty), and `<widgetType>JSON</widgetType>`.
-    - **`files-present`** — all three files exist at the resolved `<pkgDir>/uiWidgets/<widgetName>/` path.
-    - **`button-actions-present`** — every `tile/button` in `<widgetName>.json` has an `actions.click` action node whose `definition` is `action/openLink` or `action/sendMessage`.
+9. **Self-validate.** Before reporting, run the checks and report each result individually (`pass` or `fail (<reason>)`). Do **not** summarize as a single "all passed" line — list every check so a reviewer can spot a silent skip.
+Run every check in `references/widget-bundle-validation.md`.
+
+10. **Report labels.** If the widget uses `$Label`, end the response with the label report described in `references/widget-labels.md`.
 
 ---
 
@@ -256,7 +248,7 @@ Widgets express *intent*, not pixels. Each surface provides a default look and f
 |---|---|
 | Block definitions follow `{namespace}/{blockName}` and must match `discoverUiComponents` output | Runtime resolves blocks by exact definition string |
 | Never pass `tile/widget` to `getUiComponentSchemas` | It is a fixed wrapper, not a queryable component |
-| Always supply `parameters` (with required keys) when calling `execute_metadata_action` | Missing parameters cause hard failure, not partial result |
+| Read `references/` and `examples/` files only at the step that names them | Upfront reads waste context and precede the discovery result that determines which files are needed |
 | Every `{!$attrs.X}` in the body resolves to a property in the widget `schema.json` | No invented fields |
 | Every `tile/button` carries an `actions.click` entry using `action/openLink` or `action/sendMessage` only | These are the only two supported tile action definitions; an action-less button renders disabled |
 | No `$(…)`, backticks, `<(…)`, brace expansion `{a,b,c}`, or `eval`/`exec` in any Bash tool call | Vibes' safe-shell filter forces manual approval on these patterns even in Bypass mode. Emit separate commands (`mkdir -p a && mkdir -p b`) or print each value with its own command and reason about the output — do not capture into a shell variable |
@@ -265,14 +257,7 @@ Widgets express *intent*, not pixels. Each surface provides a default look and f
 
 ## Gotchas
 
-| Issue | Resolution                                                                                                                                                                                                                                                     |
-|---|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `getUiComponentSchemas` returns a partial-failure entry | Pick a different block from `discoverUiComponents`; do not silently continue without a schema                                                                                                                                                                  |
-| Body references `{!$attrs.foo}` but `foo` is not under `schema.json` `properties.attributes.properties` | Add `foo` to `schema.json` `properties.attributes.properties` OR remove the body reference                                                                                                                                                                     |
-| Output written outside `<pkgDir>/uiWidgets/<widgetName>/` | `<pkgDir>` = `<packageDirectories[].path>/main/default` (see `references/widget-bundle-layout.md`). Dropping the `main/default/` segment is the common cause of widgets landing at `force-app/uiWidgets/...` instead of `force-app/main/default/uiWidgets/...` |
-| `if` bound directly to a raw string or number relies on truthiness and is unreliable | Bind to a `lightning__booleanType` property, or use a formula comparison that evaluates to boolean                                                                                                                                                             |
-| `tile/button` renders but does nothing when clicked | No `actions.click` entry was set — an action-less button renders disabled by design. Add one (see *Actions* above)                                                                                                                                             |
-| Using `action/sendMessage` for pure navigation, or `action/openLink` when the agent should respond | `action/openLink` is synchronous and does not consume a turn; `action/sendMessage` is asynchronous and earns a fresh turn. Pick the one matching the intended UX                                                                                               |
+Known failure modes and fixes (partial schemas, unresolved bindings, wrong output path, `if` truthiness, dead buttons, action choice): see `references/widget-gotchas.md`.
 
 ---
 
@@ -283,8 +268,14 @@ Widgets express *intent*, not pixels. Each surface provides a default look and f
 | `references/widget-meta-directives.md` | For `forEach` / `forItem` (iteration) and `if` (conditional rendering), including nested loops                                                                                      |
 | `references/schema-from-lightning-type.md` | When `lightningTypeSchema` is provided; how to derive the widget `schema.json` from an Apex-backed Lightning Type                                                                   |
 | `references/widget-bundle-layout.md` | Folder layout, `-meta.xml` shape, `<pkgDir>` resolution rules                                                                                                                       |
-| `references/widget-formulas.md` | Supported formula functions and operators                                                                                                                                           |
+| `references/widget-bundle-validation.md` | Step 9 — the checks to run before reporting |
+| `references/widget-formulas.md` | Supported formula functions and operators, including locale format functions (`FORMATNUMBER`, `FORMATCURRENCY`, `FORMATDATE`, …)                                                                                                                                           |
+| `references/widget-labels.md` | Localization — `$Label` syntax, naming and reuse, allowed attributes, combining with data, creating labels, and the label report |
+| `references/widget-actions.md` | Complete `tile/button` JSON for `action/sendMessage` and `action/openLink` |
+| `references/widget-styling.md` | Variant, size, heading, and icon conventions |
+| `references/widget-gotchas.md` | Known failure modes and their fixes |
 | `examples/single-object.json` | Single-object pattern (root binding via `{!$attrs.X}`, no iteration)                                                                                                                |
 | `examples/list-with-foreach.json` | Any list-iteration case — root-level collections, nested lists, and lists embedded inside a single-object widget (e.g. iterating a `List<InnerClass>` inside an outer Apex payload) |
 | `examples/conditional.json` | Conditional pattern (`if` on `meta`, including `if` + `forEach` together)                                                                                                           |
-| `examples/formulas.json` | Formula usage — text/arithmetic/date transforms, `IF`/`AND`/`NOT` driving both a `tile/text` and `meta.if`                                                                          |
+| `examples/formulas.json` | Formula usage — text/arithmetic/date transforms, locale format functions, `IF`/`AND`/`NOT` driving both a `tile/text` and `meta.if`                                                                          |
+| `examples/localized-labels.json` | Localization — `$Label` in a heading, caption, badge (`IF` choosing between labels), button label, and a label joined with data |

package/skills/platform-widget-generate/examples/formulas.json

@@ -138,6 +138,23 @@
 
             { "definition": "tile/spacer", "attributes": { "size": "sm" } },
 
+            {
+              "definition": "tile/column",
+              "attributes": { "gap": "xs" },
+              "children": [
+                { "definition": "tile/text", "attributes": { "text": "9. Locale format functions", "variant": "h3" } },
+                { "definition": "tile/text", "attributes": { "text": "FORMATNUMBER: {!FORMATNUMBER($attrs.price)}  |  precision 0: {!FORMATNUMBER($attrs.price, 0)}" } },
+                { "definition": "tile/text", "attributes": { "text": "FORMATCURRENCY: {!FORMATCURRENCY($attrs.price)}" } },
+                { "definition": "tile/text", "attributes": { "text": "FORMATPERCENT: {!FORMATPERCENT($attrs.winProbability)}  |  precision 1: {!FORMATPERCENT($attrs.winProbability, 1)}" } },
+                { "definition": "tile/text", "attributes": { "text": "FORMATDATE: {!FORMATDATE($attrs.departureDate)}  |  long: {!FORMATDATE($attrs.departureDate, 'long')}" } },
+                { "definition": "tile/text", "attributes": { "text": "FORMATDATETIME: {!FORMATDATETIME($attrs.departureDateTime)}  |  medium: {!FORMATDATETIME($attrs.departureDateTime, 'medium')}" } },
+                { "definition": "tile/text", "attributes": { "text": "FORMATTIME: {!FORMATTIME($attrs.departureDateTime)}  |  long: {!FORMATTIME($attrs.departureDateTime, 'long')}" } },
+                { "definition": "tile/text", "attributes": { "text": "{!'Fare with tax: ' & FORMATCURRENCY($attrs.price * (1 + $attrs.taxRate))}", "variant": "h4" } }
+              ]
+            },
+
+            { "definition": "tile/spacer", "attributes": { "size": "sm" } },
+
             {
               "definition": "tile/column",
               "meta": { "if": "{!AND($attrs.isPriority, $attrs.price > 500)}" },
@@ -147,7 +164,7 @@
                   "attributes": { "gap": "sm", "align": "center" },
                   "children": [
                     { "definition": "tile/icon", "attributes": { "name": "lightning", "color": "warning" } },
-                    { "definition": "tile/text", "attributes": { "text": "9. Formula-driven meta.if: priority fare over $500 — expedited handling" } }
+                    { "definition": "tile/text", "attributes": { "text": "10. Formula-driven meta.if: priority fare over $500 — expedited handling" } }
                   ]
                 }
               ]
@@ -160,7 +177,7 @@
               "meta": { "forEach": "{!$attrs.flights}", "forItem": "$flight" },
               "attributes": { "gap": "xs" },
               "children": [
-                { "definition": "tile/text", "attributes": { "text": "10. forEach + per-row formula", "variant": "h3" } },
+                { "definition": "tile/text", "attributes": { "text": "11. forEach + per-row formula", "variant": "h3" } },
                 {
                   "definition": "tile/row",
                   "attributes": { "justify": "between", "align": "center" },

package/skills/platform-widget-generate/examples/localized-labels.json

@@ -0,0 +1,57 @@
+{
+  "type": "lightning__agentforceWidget",
+  "contentBody": {
+    "widgetBody": {
+      "definition": "tile/widget",
+      "children": [
+        {
+          "definition": "tile/column",
+          "attributes": { "gap": "md" },
+          "children": [
+            {
+              "definition": "tile/text",
+              "attributes": { "text": "{!$Label.c.OrderStatus_Heading}", "variant": "h1" }
+            },
+            {
+              "definition": "tile/row",
+              "attributes": { "gap": "sm", "align": "center" },
+              "children": [
+                {
+                  "definition": "tile/text",
+                  "attributes": { "text": "{!$Label.c.OrderStatus_OrderNumberCaption}", "variant": "caption" }
+                },
+                {
+                  "definition": "tile/text",
+                  "attributes": { "text": "{!$attrs.orderNumber}" }
+                }
+              ]
+            },
+            {
+              "definition": "tile/badge",
+              "attributes": {
+                "label": "{!IF($attrs.isShipped, $Label.c.OrderStatus_ShippedStatus, $Label.c.OrderStatus_ProcessingStatus)}",
+                "variant": "{!IF($attrs.isShipped, 'success', 'info')}"
+              }
+            },
+            {
+              "definition": "tile/text",
+              "attributes": { "text": "{!$Label.c.OrderStatus_ItemsPrefix & ' ' & TEXT($attrs.itemCount)}" }
+            },
+            {
+              "definition": "tile/button",
+              "attributes": {
+                "label": "{!$Label.c.OrderStatus_TrackButton}",
+                "variant": "primary",
+                "actions": {
+                  "click": [
+                    { "definition": "action/openLink", "attributes": { "url": "{!$attrs.trackingUrl}" } }
+                  ]
+                }
+              }
+            }
+          ]
+        }
+      ]
+    }
+  }
+}

package/skills/platform-widget-generate/references/widget-actions.md

@@ -0,0 +1,29 @@
+# Widget Actions
+
+Complete `tile/button` examples for the two supported action definitions. The action table and the action-less-button rule live in SKILL.md *Actions*.
+
+---
+
+## `action/sendMessage` and `action/openLink`
+
+```json
+{
+  "definition": "tile/button",
+  "attributes": {
+    "label": "Button Label",
+    "variant": "primary",
+    "actions": { "click": [ { "definition": "action/sendMessage", "attributes": { "content": "content" } } ] }
+  }
+}
+```
+
+```json
+{
+   "definition": "tile/button",
+   "attributes": {
+      "label": "Button Label",
+      "variant": "primary",
+      "actions": { "click": [ { "definition": "action/openLink", "attributes": { "url": "https://www.example.com" } } ] }
+   }
+}
+```

package/skills/platform-widget-generate/references/widget-bundle-validation.md

@@ -0,0 +1,15 @@
+# Widget Bundle Validation Checks
+
+Report each check individually as `pass` or `fail (<reason>)`.
+
+- **`schema-parses`** — `<pkgDir>/uiWidgets/<widgetName>/schema.json` parses as JSON.
+- **`schema-root-keys`** — root has `title` (string), `type: "object"`, and `properties.attributes` (object) — where `properties.attributes` carries `lightning:type: "lightning__objectType"` and a nested `properties` map. No `unevaluatedProperties: false`.
+- **`schema-leaf-types`** — every leaf under `properties.attributes.properties` carries a `lightning:type`. Singular nested inner-class fields carry `lightning:type` set to the inner Apex class reference (`@apexClassType/<namespace>__<OuterClass>$<InnerClass>`); the nested shape is not redeclared. `List<InnerClass>` fields carry `lightning:type: "lightning__listType"` with `items.lightning:type` set to the inner Apex class reference (`@apexClassType/<namespace>__<OuterClass>$<InnerClass>`), not a redeclared field map — see `references/schema-from-lightning-type.md`. **When the list has no Apex-backed type** (schema inferred from the prompt), `items.lightning:type: "lightning__objectType"` MUST carry an inline nested `properties` map for every item field the body binds via `{!$item.X}`.
+- **`bindings-resolve`** — every `{!$attrs.X}` (or `{!$attrs.<outerField>.<innerField>}` for nested objects) in `<widgetName>.json` resolves to a property under `schema.json` `properties.attributes.properties`, and every `{!$item.X}` resolves to a `forItem` loop variable defined upstream. This applies to `$attrs`/`$item` references **inside formula expressions** too.
+- **`formulas-supported`** — every function name used inside a `{!...}` expression appears in the *Supported functions* list in `references/widget-formulas.md`.
+- **`body-envelope`** — `<widgetName>.json` root has `type: "lightning__agentforceWidget"` and a `contentBody` object whose `widgetBody` carries the UEM tree rooted at `tile/widget`. No node in the tree — root or non-root — carries a `type` key.
+- **`metaxml-wellformed`** — `<widgetName>.uiwidget-meta.xml` parses as well-formed XML.
+- **`metaxml-elements`** — `<widgetName>.uiwidget-meta.xml` has root `<UiWidgetBundle>` and contains `<masterLabel>` (non-empty), `<description>` (non-empty), and `<widgetType>JSON</widgetType>`.
+- **`files-present`** — all three files exist at the resolved `<pkgDir>/uiWidgets/<widgetName>/` path.
+- **`button-actions-present`** — every `tile/button` in `<widgetName>.json` has an `actions.click` action node whose `definition` is `action/openLink` or `action/sendMessage`.
+- **`labels-valid`** — if the user did not ask for localization, `<widgetName>.json` contains no `$Label` (report `pass (not requested)`). Otherwise every `$Label` follows the rules in `references/widget-labels.md` and appears in the step 10 report.