@salesforce/afv-skills 1.66.0 → 1.67.0

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

@@ -1,8 +1,8 @@
 ---
 name: platform-metadata-deploy
-description: "Salesforce DevOps automation using sf CLI v2. TRIGGER when: user deploys metadata, creates/manages scratch orgs or sandboxes, sets up CI/CD pipelines, or troubleshoots deployment errors with sf project deploy. DO NOT TRIGGER when: writing Apex code (use platform-apex-generate), building LWC components (use experience-lwc-generate), creating metadata definitions (use platform-custom-object-generate or platform-custom-field-generate), or querying org data (use platform-data-manage)."
+description: "Salesforce DevOps automation using sf CLI v2. TRIGGER when: user deploys metadata, validates a deploy or does a dry-run, deploys to a Production org, quick-deploys a validated job ID, ships/promotes to prod, creates/manages scratch orgs or sandboxes, sets up CI/CD pipelines, or troubleshoots deployment errors with sf project deploy. DO NOT TRIGGER when: writing Apex code, building LWC components (use experience-lwc-generate), creating metadata definitions (use platform-custom-object-generate), deleting metadata from an org (use platform-destructive-deploy), or querying org data (use platform-data-manage)."
 metadata:
-  version: "1.1"
+  version: "1.2"
   domains: ["Platform", "Developer Experience"]
   relatedSkills:
     - "agentforce-generate"
@@ -11,9 +11,7 @@ metadata:
     - "experience-lwc-generate"
     - "integration-connectivity-connected-app-configure"
     - "integration-connectivity-generate"
-    - "platform-apex-generate"
     - "platform-apex-test-run"
-    - "platform-custom-field-generate"
     - "platform-custom-object-generate"
     - "platform-data-manage"
   cliTools:
@@ -40,9 +38,9 @@ Use `platform-metadata-deploy` when the work involves:
 - troubleshooting deployment failures and dependency ordering
 
 Delegate elsewhere when the user is:
-- authoring Apex code → [platform-apex-generate](../platform-apex-generate/SKILL.md)
+- authoring Apex code (this skill only deploys it)
 - authoring LWC components → [experience-lwc-generate](../experience-lwc-generate/SKILL.md)
-- creating custom objects or fields → [platform-custom-object-generate](../platform-custom-object-generate/SKILL.md), [platform-custom-field-generate](../platform-custom-field-generate/SKILL.md)
+- creating custom objects or fields → [platform-custom-object-generate](../platform-custom-object-generate/SKILL.md)
 - building Flows → [automation-flow-generate](../automation-flow-generate/SKILL.md)
 - doing org data operations → [platform-data-manage](../platform-data-manage/SKILL.md)
 - authoring or testing Agentforce agents → [agentforce-generate](../agentforce-generate/SKILL.md)
@@ -54,6 +52,7 @@ Delegate elsewhere when the user is:
 - Use **`sf` CLI v2 only**.
 - On non-source-tracking orgs, deploy/retrieve commands require an explicit scope such as `--source-dir`, `--metadata`, or `--manifest`.
 - Prefer **`--dry-run` first** before real deploys.
+- **Never run `sf project deploy start` against a production org.** Production goes through the validate → quick-deploy path below (server-side validation returns a 10-day job ID; quick-deploy promotes it without re-running tests, behind an explicit confirmation).
 - For Flows, deploy safely and activate only after validation.
 - Keep test-data creation guidance delegated to **`platform-data-manage`** after metadata is validated or deployed.
 
@@ -82,7 +81,7 @@ Ask for or infer:
 Preflight checks:
 ```bash
 sf --version
-sf org list
+sf org list --skip-connection-status
 sf org display --target-org <alias> --json
 test -f sfdx-project.json
 ```
@@ -94,7 +93,25 @@ test -f sfdx-project.json
 ### 1. Preflight
 Confirm auth, repo shape, package directories, and target scope.
 
-### 2. Validate first
+### 1a. Classify the target org (routes prod vs non-prod)
+
+Before any deploy, classify the target from its `sf org list` record — the path forks on whether the org is **production**. Do NOT classify from `sf org display`: it reports only a plain My Domain and omits the sandbox/scratch/trial fields, so a Sandbox-or-Demo Org (SDO) is misclassified as production (forcedotcom/sf-skills#356). The `sf org list` record carries the real classification booleans. Pass `--skip-connection-status` so this stays a local read that does not refresh an OAuth token per authenticated org (forcedotcom/sf-skills#349):
+
+```bash
+sf org list --skip-connection-status --json
+```
+
+Find the record whose `alias`, `username`, or `orgId` matches the target, then classify from that record (first match wins):
+- **Scratch** — `isScratch` is `true`.
+- **Sandbox** — `isSandbox` is `true`, or the `instanceUrl` contains `--` (the My Domain sandbox marker) or `test.salesforce.com`.
+- **Trial / Developer Edition** — `trailExpirationDate` (the CLI's spelling; also accept `trialExpirationDate`) is a date in the **future**, or the `instanceUrl` host contains `orgfarm-`, `.develop.my.salesforce.com`, `.pc-rnd.`, or `.scratch.my.salesforce.com`. A past date does not count — the date is cached at login and never refreshed, so a converted trial keeps a stale past date and is not a trial.
+
+Anything else is **production** — including a **Dev Hub** (`isDevHub` is `true`) that shows none of the above signals, since Dev Hub is normally enabled in the customer's own production org. If no record matches or the record has no usable info (no `instanceUrl` and none of the flags), treat it as **unknown** and ask the user before proceeding, rather than assuming production or non-production.
+
+- **Non-production** → the dry-run + deploy path (steps 2–6).
+- **Production** → the validate → quick-deploy path ([Production deploys](#production-deploys-validate--quick-deploy)). Never run `sf project deploy start` against production.
+
+### 2. Validate first (non-production)
 ```bash
 sf project deploy start --dry-run --source-dir force-app --target-org <alias> --wait 30 --json
 ```
@@ -118,9 +135,6 @@ sf project deploy start --manifest manifest/package.xml --target-org <alias> --t
 
 # manifest deploy with Spring '26 relevant-test selection
 sf project deploy start --manifest manifest/package.xml --target-org <alias> --test-level RunRelevantTests --wait 30 --json
-
-# quick deploy after successful validation
-sf project deploy quick --job-id <validation-job-id> --target-org <alias> --json
 ```
 
 ### 5. Verify
@@ -136,6 +150,93 @@ Output template: [references/deployment-report-template.md](references/deploymen
 
 ---
 
+## Production deploys (validate → quick-deploy)
+
+Production is never deployed with `sf project deploy start`. It is a two-step promotion: a **server-side validation** produces a job ID, then a **quick deploy** promotes that validated job without re-running tests, behind an explicit confirmation.
+
+### P1. Validate against production
+
+Production validations REQUIRE a test level. Use `RunLocalTests` by default; switch to `RunSpecifiedTests --tests <ClassName>...` only if the user has explicitly listed tests.
+
+```bash
+sf project deploy validate --target-org <alias> --json [scope flags] --test-level RunLocalTests
+```
+
+Scope flags — use exactly one: `--source-dir <path>`, `--metadata <Type:Name>`, or `--manifest manifest/package.xml`.
+
+The response returns a **job ID** (`result.id`) valid for **10 days**. Persist it **with the target's immutable identity** — the org ID and instance URL from `sf org display`, not just the alias — so the quick deploy can prove the validation belongs to the org it is about to promote to:
+
+```bash
+mkdir -p .sfdx
+ORG_JSON=$(sf org display --target-org <alias> --json)
+ORG_ID=$(printf '%s' "$ORG_JSON" | jq -r '.result.id')
+INSTANCE_URL=$(printf '%s' "$ORG_JSON" | jq -r '.result.instanceUrl')
+printf '{"jobId":"%s","createdAt":"%s","targetOrg":"%s","orgId":"%s","instanceUrl":"%s","testLevel":"RunLocalTests"}\n' \
+  "<id>" "<iso8601>" "<alias>" "$ORG_ID" "$INSTANCE_URL" > .sfdx/last-validation.json
+```
+
+On validation failure, triage from `result.details.componentFailures` and `result.details.runTestResult.failures` — surface the top component errors and test failures with a scoped fix direction, then STOP. Never use `--ignore-errors`/`--ignore-warnings` during validation.
+
+### P2. Gate the quick deploy strictly
+
+Before promoting, verify all five:
+1. **Target is production** — re-confirm via step 1a's classification.
+2. **A validation exists** — read `.sfdx/last-validation.json`, or ask for the job ID, or fall back to `--use-most-recent`. Resolve `--use-most-recent` to a concrete job ID **now** (do not carry it forward as an unresolved flag), so the checks below run against a known job.
+3. **Validation belongs to THIS target** — re-run `sf org display --target-org <alias> --json` and require the current `result.id` (org ID) to equal the `orgId` persisted in `.sfdx/last-validation.json`. This closes the stale-cache hazard: a cached job ID resolves its org from the deploy cache, so without this check the banner can show org B while the job promotes to org A. On any mismatch — or if the persisted record lacks an `orgId`/`instanceUrl` to compare — treat it as a **hard stop** and re-validate (P1) against the intended target. Never promote a validation whose target you cannot prove.
+4. **Validation is fresh** — explicit `--job-id` ≤ 10 days; a `--use-most-recent` resolution ≤ 3 days. If stale, re-validate (P1) first.
+5. **Explicit user confirmation** — print the banner below and require a literal "yes". Populate every banner field from the verified validation record and the just-fetched org data — never from unverified input. Never auto-confirm.
+
+```text
+┌─ PRODUCTION DEPLOY ─────────────────────────────┐
+│ Org alias:      <alias>                         │
+│ Instance:       <instanceUrl>                   │
+│ Edition:        <edition>                       │
+│ Validation ID:  <jobId>                         │
+│ Validated:      <createdAt> (X days ago)        │
+│ Components:     <componentCount> queued         │
+│ Tests:          <run>/<passed>/<failed>         │
+└─────────────────────────────────────────────────┘
+Confirm deploy to PRODUCTION? (yes/no)
+```
+
+`sf org display --json` does not return the edition. Read `<edition>` from the Organization object's `OrganizationType` (e.g. `Enterprise Edition`):
+
+```bash
+sf data query --query "SELECT OrganizationType FROM Organization" --target-org <alias> --json | jq -r '.result.records[0].OrganizationType'
+```
+
+### P3. Promote and audit
+
+The literal "yes" from P2's banner is the authorization. In the **Salesforce development plugin** context, a PreToolUse hook (`sf-deploy-gate`) blocks a bare production `deploy quick` and only permits it when the command carries the machine-readable confirmation marker `CONFIRM_PROD=1`. Emit that marker to transmit the confirmation the user just gave — it is **not** an independent bypass, so add it **only after** the explicit "yes", never before:
+
+```bash
+# plugin context: CONFIRM_PROD=1 relays P2's confirmation to the safety hook
+CONFIRM_PROD=1 sf project deploy quick --job-id <validation-id> --target-org <alias> --wait 30 --json
+```
+
+Outside the plugin (bare CLI, headless/MCP) there is no such hook — run the same command without the marker.
+
+**Quick deploy starts a new deployment with its own job ID** — it does not reuse the validation ID. Capture the response, extract the new ID, and use *that* for polling, reporting, and the audit filename; keep the validation ID separately for traceability. Stop if the response carries no deployment ID:
+
+```bash
+QUICK_RESULT=$(CONFIRM_PROD=1 sf project deploy quick --job-id <validation-id> --target-org <alias> --wait 30 --json)
+QUICK_DEPLOY_ID=$(printf '%s' "$QUICK_RESULT" | jq -r '.result.id')
+[ -n "$QUICK_DEPLOY_ID" ] && [ "$QUICK_DEPLOY_ID" != "null" ] || { echo "No quick-deploy ID returned — do not report the validation ID as the deploy; investigate."; exit 1; }
+```
+
+Quick deploy promotes the validated components and does NOT re-run tests. Persist the report **for the quick-deploy operation** (not the validation) for the audit trail, then guide post-deploy verification (smoke-test critical paths, watch Setup → Deployment Status, prepare a rollback plan if anything regressed):
+
+```bash
+mkdir -p .sfdx/deploy-history
+sf project deploy report --job-id "$QUICK_DEPLOY_ID" --target-org <alias> --json > ".sfdx/deploy-history/${QUICK_DEPLOY_ID}.json"
+```
+
+If quick deploy times out or stays in progress, poll with the **quick-deploy ID**, not the validation ID.
+
+Adding `CONFIRM_PROD=1` after an explicit confirmation is the sanctioned path — it is not "working around" the gate. But never override a denial the user has **not** confirmed, and never override one raised for a different reason — a target mismatch (P2 check 3), a destructive deploy, or an unknown/unresolved org. Surface those denials and stop.
+
+---
+
 ## High-Signal Failure Patterns
 
 | Error / symptom | Likely cause | Default fix direction |
@@ -163,7 +264,7 @@ Default pipeline shape:
 7. verify + notify
 
 - When org policy and release risk allow it, consider `--test-level RunRelevantTests` for Apex-heavy deployments.
-- Pair this with modern Apex test annotations such as `@IsTest(testFor=...)` and `@IsTest(isCritical=true)` — see [platform-apex-generate](../platform-apex-generate/SKILL.md) for authoring guidance.
+- Pair this with modern Apex test annotations such as `@IsTest(testFor=...)` and `@IsTest(isCritical=true)`.
 
 Static analysis now uses **Code Analyzer v5** (`sf code-analyzer`), not retired `sf scanner`.
 
@@ -185,9 +286,7 @@ For full agent DevOps details, including `Agent:` pseudo metadata, publish/activ
 
 | Need | Delegate to | Reason |
 |---|---|---|
-| custom object creation | [platform-custom-object-generate](../platform-custom-object-generate/SKILL.md) | define objects before deploy |
-| custom field creation | [platform-custom-field-generate](../platform-custom-field-generate/SKILL.md) | define fields before deploy |
-| Apex authoring / fixes | [platform-apex-generate](../platform-apex-generate/SKILL.md) | code authoring and repair |
+| custom object / field creation | [platform-custom-object-generate](../platform-custom-object-generate/SKILL.md) | define objects and fields before deploy |
 | run tests after deployment | [platform-apex-test-run](../platform-apex-test-run/SKILL.md) | post-deploy test execution and coverage |
 | Flow creation / repair | [automation-flow-generate](../automation-flow-generate/SKILL.md) | Flow authoring and activation guidance |
 | test data or seed records | [platform-data-manage](../platform-data-manage/SKILL.md) | describe-first data setup and cleanup |

package/skills/platform-metadata-deploy/references/agent-deployment-guide.md

@@ -366,9 +366,9 @@ Pass the BotVersion number you intend to activate as the third argument.
 **Critical:** Dependencies must be deployed BEFORE the agent.
 
 ```text
-1. Custom Objects/Fields (platform-custom-object-generate, platform-custom-field-generate)
+1. Custom Objects/Fields (platform-custom-object-generate)
    ↓
-2. Apex Classes (platform-apex-generate)
+2. Apex Classes
    ↓
 3. Flows (automation-flow-generate)
    ↓
@@ -571,14 +571,13 @@ sf agent activate --api-name My_Agent --target-org myorg
 | From Skill | To Skill | Purpose |
 |------------|----------|---------|
 | agentforce-generate | platform-metadata-deploy | Publish and activate agents |
-| platform-apex-generate | platform-metadata-deploy | Deploy Apex before agent |
 | automation-flow-generate | platform-metadata-deploy | Deploy Flows before agent |
 | integration-connectivity-generate | platform-metadata-deploy | Deploy Named Credentials for external APIs |
 
 ### Integration Pattern
 
 ```bash
-# 1. platform-apex-generate creates InvocableMethod class
+# 1. An InvocableMethod class is authored
 # 2. automation-flow-generate creates wrapper Flow
 # 3. agentforce-generate creates agent with flow:// action
 # 4. platform-metadata-deploy orchestrates deployment in correct order

package/skills/platform-metadata-deploy/references/orchestration.md

@@ -11,7 +11,7 @@ This document details how platform-metadata-deploy fits into the multi-skill wor
 ┌─────────────────────────────────────────────────────────────────────────────┐
 │  STANDARD MULTI-SKILL ORCHESTRATION ORDER                                   │
 ├─────────────────────────────────────────────────────────────────────────────┤
-│  1. platform-custom-object-generate / platform-custom-field-generate                      │
+│  1. platform-custom-object-generate                                                      │
 │     └── Create object/field definitions (LOCAL files)                       │
 │                                                                             │
 │  2. automation-flow-generate                                                         │
@@ -84,7 +84,7 @@ When deploying agents with external API integrations:
 ├─────────────────────────────────────────────────────────────────────────────┤
 │  1. integration-connectivity-connected-app-configure → Create OAuth Connected App                 │
 │  2. integration-connectivity-generate    → Create Named Credential + External Service          │
-│  3. platform-apex-generate   → Create @InvocableMethod (if needed)                 │
+│  3. Apex authoring          → Create @InvocableMethod (if needed)                 │
 │  4. automation-flow-generate   → Create Flow wrapper                                 │
 │                                                                             │
 │  5. platform-metadata-deploy         ◀── FIRST DEPLOYMENT                                 │
@@ -169,7 +169,6 @@ sf agent activate --api-name AgentName --version N --target-org alias --json
 |------------|--------------|------|
 | platform-custom-object-generate | → platform-metadata-deploy | "Deploy objects to [org]" |
 | automation-flow-generate | → platform-metadata-deploy | "Deploy flow with --dry-run" |
-| platform-apex-generate | → platform-metadata-deploy | "Deploy classes with RunLocalTests" |
 | agentforce-generate | → platform-metadata-deploy | "Deploy and publish agent" |
 
 ---

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" },