@salesforce/afv-skills 1.66.0 → 1.68.0

package/skills/platform-report-generate/references/verification-checklist.md

@@ -2,6 +2,9 @@
 
 Run through these checks before deploying any generated report metadata.
 
+## Before Writing the XML
+- [ ] Check every `<field>` in `<columns>`, `<groupingsDown>`, and `<groupingsAcross>`, every filter `<column>`, and the chart `<groupingColumn>` against the column table for the report type in `references/column-names.md` (or the MCP column list). No bare `NAME` or `USERS.NAME` — use the report type's name column (e.g. `OPPORTUNITY_NAME`, `FULL_NAME`, `OWNER`, `FIRST_NAME` + `LAST_NAME`)
+
 ## Universal Checks
 - [ ] File extension is `.report-meta.xml`
 - [ ] File is placed under `<sourceDir>/reports/<FolderName>/` (check sfdx-project.json for source path)
@@ -13,6 +16,8 @@ Run through these checks before deploying any generated report metadata.
 - [ ] `<description>` explains the business purpose (max 255 chars)
 - [ ] All column `<field>` values use correct platform column names
 - [ ] Custom field columns use `<ObjectApiName>.<FieldApiName__c>` format
+- [ ] Each `<columns>` contains exactly one `<field>`
+- [ ] Custom report type: `<reportType>` ends in `__c` and every column uses a `<table>$<field>` path from the report type's sections
 
 ## Format-Specific Checks
 - [ ] Tabular: no `<groupingsDown>`, no `<groupingsAcross>`, no `<chart>`, no `<aggregateTypes>`
@@ -28,6 +33,7 @@ Run through these checks before deploying any generated report metadata.
 - [ ] `<timeFrameFilter>` uses a valid `<interval>` value from `references/date-intervals.md`
 - [ ] Date columns use platform column names (e.g. `CLOSE_DATE`, not `CloseDate`)
 - [ ] Multi-value picklist uses ONE criteriaItem with comma-separated values
+- [ ] No `<params>` the request didn't ask for; Opportunity `probability` param is only `>0`
 
 ## Grouping Checks
 - [ ] `<dateGranularity>` is set for every grouping (use `None` for non-date fields)
@@ -38,8 +44,10 @@ Run through these checks before deploying any generated report metadata.
 - [ ] Chart is only on Summary or Matrix report
 - [ ] `<chartType>` is a valid type from `references/chart-types.md`
 - [ ] `<groupingColumn>` matches a grouping field
-- [ ] `<chartSummaries>` contains valid `<aggregate>` + `<column>` (or just `<column>RowCount</column>`)
-- [ ] `legendPosition` only used with grouped/stacked charts
+- [ ] `<chartSummaries>` contains valid `<aggregate>` + `<column>`, or ONLY `<column>RowCount</column>` with no `<aggregate>`
+- [ ] No `<columns><field>RowCount</field></columns>` — `RowCount` is only valid in `<chartSummaries><column>`, `<sortByName>`, or a `<calculatedFormula>`
+- [ ] `legendPosition` omitted on single-series `HorizontalBar`/`VerticalColumn`/`Line`; on grouped/stacked charts only `Right` or `Bottom` (see `references/chart-types.md`)
+- [ ] Every `<chart>` child element is in the allowed list in `references/chart-types.md`
 
 ## Cross-Filter Checks (if applicable)
 - [ ] Maximum 3 cross-filters per report

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

@@ -119,6 +119,7 @@ On success, read `[0].outputValues`.
 - 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`.
 
 ---
 
@@ -131,28 +132,7 @@ On success, read `[0].outputValues`.
 | `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.
 
@@ -175,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.
 
 ---
 
@@ -198,7 +169,7 @@ Widgets express *intent*, not pixels. Each surface provides a default look and f
 
 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` invocable action for the selected blocks. Review property metadata. **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.**
+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/`):
 
@@ -207,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`.
@@ -264,6 +238,8 @@ Widgets express *intent*, not pixels. Each surface provides a default look and f
 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`.
+
 ---
 
 ## Rules / Constraints
@@ -281,27 +257,25 @@ Run every check in `references/widget-bundle-validation.md`.
 
 ## 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`.
 
 ---
 
 ## Reference File Index
 
-| File | When to read|
-|---|---|
-| `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|
+| File | When to read                                                                                                                                                                        |
+|---|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `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-bundle-validation.md` | Step 9 — the checks to run before reporting |
-| `references/widget-formulas.md` | Supported formula functions and operators|
-| `examples/single-object.json` | Single-object pattern (root binding via `{!$attrs.X}`, no iteration)|
+| `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/conditional.json` | Conditional pattern (`if` on `meta`, including `if` + `forEach` together)                                                                                                           |
+| `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

@@ -12,3 +12,4 @@ Report each check individually as `pass` or `fail (<reason>)`.
 - **`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.

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

@@ -17,6 +17,7 @@ Every formula expression is wrapped in `{!...}`, similar to a plain binding:
 - Functions and operators are case-sensitive UPPERCASE.
 - A formula can nest functions and mix functions with operators: `{!TEXT(ROUND($attrs.property, 2))}`, `{!LEFT($attrs.property, 5) & "..."}`.
 - A formula-bearing attribute is still bound to schema properties the same way as a plain binding — every `$attrs.X` / `$item.X` referenced inside a formula must resolve to a real schema property or loop variable, per the `bindings-resolve` self-validation check.
+- A Custom Label reference `$Label.c.<LabelName>` can be used as a text value inside a formula. See `references/widget-labels.md`.
 
 ---
 
@@ -34,7 +35,7 @@ Only the operators/functions listed here are confirmed supported — do not inve
 | `/` | Divide | `$attrs.operand1 / $attrs.operand2` |
 | `^` | Exponent | `$attrs.operand1 ^ $attrs.operand2` |
 
-Standard precedence applies (`^` > `*`/`/` > `+`/`-`); parenthesize to be explicit, especially when combining multiple arithmetic operators.
+Unary minus (`-$attrs.fieldName`) is also supported. Precedence, lowest to highest: `||`, `&&`, equality, relational, `+` `-` `&`, `^`, `*` `/`, unary. Note that `*` and `/` bind tighter than `^`, so `2 * 3 ^ 2` is `(2 * 3) ^ 2`; parenthesize to be explicit.
 
 ### 2. Comparison operators
 
@@ -47,36 +48,40 @@ Return `true`/`false`; commonly used inside `IF()` or `meta.if`.
 | `>` / `<` | Greater / less than | `$attrs.property > 1000`               |
 | `>=` / `<=` | Greater-or-equal / less-or-equal | `$attrs.property1 >= $attrs.property2` |
 
+`==` and `!=` are accepted as aliases for `=` and `<>`. Both operands must have the same type; text is never compared with a number.
+
 ### 3. Logical functions
 
 | Function | Description | Example                                                                                              |
 |---|---|------------------------------------------------------------------------------------------------------|
-| `IF(cond, then, else)` | Conditional value; nests for multi-branch logic | `IF($attrs.property > value, 'result1', 'result2')`                                                  |
+| `IF(cond, then, else)` | Conditional value; nests for multi-branch logic. `cond` must be a boolean (`IF($attrs.count > 0, …)`, not `IF($attrs.count, …)`) and both branches must have the same type | `IF($attrs.property > value, 'result1', 'result2')`                                                  |
 | `CASE(expr, val1, res1, val2, res2, ..., default)` | Multi-way match, cleaner than nested `IF` for 3+ branches | `CASE($attrs.property, 'value1', 'result1', 'value2', 'result2', 'value3', 'result3', 'defaultResult')` |
 | `AND(...)` | All conditions true | `AND($attrs.property1, $attrs.property2 > value)`                                                    |
 | `OR(...)` | Any condition true | `OR($attrs.property1, $attrs.property2 > value)`                                                     |
 | `NOT(val)` | Negate a boolean | `NOT($attrs.property)`                                                                               |
-| `ISNULL(val)` | True if the value is null | `IF(ISNULL($attrs.property), 'null', 'has-value')`                                                   |
+| `&&` / `\|\|` / `!` (operators) | Aliases for `AND` / `OR` / `NOT` | `$attrs.property1 && !$attrs.property2` |
+| `ISNULL(val)` | True if the value is null. Always false for text — use `ISBLANK` for strings | `IF(ISNULL($attrs.property), 'null', 'has-value')`                                                   |
 | `ISBLANK(val)` | True if null or empty string | `IF(ISBLANK($attrs.property), 'blank', 'has-value')`                                                 |
 
 ### 4. Text functions
 
 | Function | Description | Example                                             |
 |---|---|-----------------------------------------------------|
-| `UPPER(str)` / `LOWER(str)` | Case conversion | `UPPER($attrs.property)`                            |
+| `UPPER(str[, locale])` / `LOWER(str[, locale])` | Case conversion, optionally for a locale such as `'tr'` | `UPPER($attrs.property)`                            |
 | `LEFT(str, n)` / `RIGHT(str, n)` | First/last `n` characters | `LEFT($attrs.property, 3)`                          |
 | `MID(str, start, len)` | Substring, **1-based** start index (first character is position 1, not 0) | `MID($attrs.property, 1, 3)`                        |
+| `SUBSTR(str, start[, len])` | Substring with a **1-based** start; a negative `start` counts from the end; without `len`, runs to the end | `SUBSTR($attrs.property, -4)` |
 | `LEN(val)` | Length of a string | `LEN($attrs.property)`                              |
 | `TRIM(str)` | Strip leading/trailing whitespace | `TRIM($attrs.property)`                             |
 | `REVERSE(str)` | Reverse a string | `REVERSE($attrs.property)`                          |
 | `SUBSTITUTE(str, old, new)` | Replace all occurrences | `SUBSTITUTE($attrs.property, 'string1', 'string2')` |
-| `FIND(search, str)` | 1-based index of `search` in `str`, or falsy if absent | `FIND('string', $attrs.property)`                   |
+| `FIND(search, str[, start])` | 1-based index of `search` in `str`, or `0` if absent; optional 1-based `start` position | `FIND('string', $attrs.property)`                   |
 | `LPAD(str, len, pad)` / `RPAD(str, len, pad)` | Pad to a fixed width | `LPAD($attrs.property, 12, '.')`                    |
 | `TEXT(val)` | Coerce a non-string value to text (commonly paired with `ROUND`) | `TEXT(ROUND($attrs.property, 2))`                   |
 | `VALUE(str)` | Parse text to a number (inverse of `TEXT`) | `VALUE($attrs.property)`                            |
 | `CONTAINS(str, sub)` | String contains substring — boolean, pair with `IF` | `CONTAINS($attrs.property, 'string')`               |
 | `BEGINS(str, prefix)` | String starts with — boolean, pair with `IF` | `BEGINS($attrs.property, 'string')`                 |
-| `&` (operator) | Concatenate strings | `$attrs.property1 & ' — ' & $attrs.property2`       |
+| `&` (operator) | Concatenate strings. Both sides must be text, so wrap numbers and dates in `TEXT()` — `'Total: ' & TEXT($attrs.total)` | `$attrs.property1 & ' — ' & $attrs.property2`       |
 
 ### 5. Math functions
 
@@ -99,7 +104,7 @@ Return `true`/`false`; commonly used inside `IF()` or `meta.if`.
 | `DAY(date)` / `MONTH(date)` / `YEAR(date)` | Extract date components | `DAY(DATEVALUE($attrs.fieldName))`              |
 | `WEEKDAY(date)` | Day of week, `1`=Sunday … `7`=Saturday | `WEEKDAY(DATEVALUE($attrs.fieldName))`      |
 | `ADDMONTHS(date, n)` | Add `n` whole months to a date | `ADDMONTHS(DATEVALUE($attrs.fieldName), 3)` |
-| `TODAY()` / `NOW()` / `TIMENOW()` | Current server date / datetime / time — no arguments | `TODAY()`                                       |
+| `TODAY()` / `NOW()` / `TIMENOW()` | Current date / datetime / time in UTC — no arguments | `TODAY()`                                       |
 | `DATE(year, month, day)` | Construct a date literal | `DATE(2026, 12, 31)`                            |
 | `HOUR(dt)` / `MINUTE(dt)` / `SECOND(dt)` / `MILLISECOND(dt)` | Extract time components from a datetime | `HOUR(NOW())`                                   |
 
@@ -121,3 +126,15 @@ A raw date/datetime **string** attribute (e.g. an ISO string from `$attrs`) must
 | `ISNUMBER(val)` | True if the value parses as a number | `ISNUMBER($attrs.fieldName)` |
 | `REGEX(str, pattern)` | True if `str` matches the regex `pattern` (standard regex string) | `REGEX($attrs.fieldName, '^[A-Z]{2} [0-9]+$')` |
 
+### 9. Locale formatting functions
+
+Format values for the viewer's locale. A null or blank input returns null. The optional last argument is a decimal count for the number functions and `'short'` (default), `'medium'` or `'long'` for the date and time functions.
+
+| Function | Description | Example |
+|---|---|---|
+| `FORMATNUMBER(num[, decimals])` | Locale-formatted number | `FORMATNUMBER($attrs.fieldName, 2)` |
+| `FORMATPERCENT(num[, decimals])` | Locale-formatted percent (`0.25` → `25%`) | `FORMATPERCENT($attrs.fieldName, 1)` |
+| `FORMATCURRENCY(num)` | Currency code followed by the amount, e.g. `USD 1,234.50` (no currency symbol) | `FORMATCURRENCY($attrs.fieldName)` |
+| `FORMATDATE(date[, style])` | Locale date | `FORMATDATE($attrs.fieldName, 'medium')` |
+| `FORMATDATETIME(dt[, style])` | Locale date and time | `FORMATDATETIME($attrs.fieldName, 'long')` |
+| `FORMATTIME(time[, style])` | Locale time | `FORMATTIME($attrs.fieldName)` |

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

@@ -0,0 +1,10 @@
+# Widget Generation 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 SKILL.md *Actions*)                                                                                                                                             |
+| 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                                                                                               |