@salesforce/afv-skills 1.28.0 → 1.29.0

package/skills/platform-custom-field-generate/references/advanced-picklists.md

@@ -0,0 +1,590 @@
+# Advanced Picklist Reference
+
+Detailed rules and worked examples for picklist CustomFields that go beyond a
+simple inline value list. All XML uses the `http://soap.sforce.com/2006/04/metadata`
+namespace with a `<CustomField>` root, exactly like the simple-picklist examples in
+the main skill.
+
+Covered here:
+
+1. [Value Set References (`<valueSetName>`)](#1-value-set-references-valuesetname)
+2. [Controlling / Dependent Picklists](#2-controlling--dependent-picklists)
+3. [Enhanced Value Attributes (`color`, `isActive`, value-level `<description>`)](#3-enhanced-value-attributes)
+4. [Picklist Validation Rules](#4-picklist-validation-rules)
+5. [Scoping a Picklist to a Record Type](#5-scoping-a-picklist-to-a-record-type)
+
+---
+
+## 1. Value Set References (`<valueSetName>`)
+
+A picklist field can either define its values **inline** or **reference an existing
+value set** (a Global Value Set or a Standard Value Set). The shared set is defined
+once and reused across many fields.
+
+### ⭐ HARD RULE: `<valueSet>` is EITHER a reference OR inline — never both
+
+A `<valueSet>` element must contain **exactly one** of:
+
+- `<valueSetName>` — references an existing value set (this section), **OR**
+- `<valueSetDefinition>` — defines values inline (the simple-picklist case).
+
+Including both in the same `<valueSet>` is a deployment error.
+
+#### ❌ INCORRECT — both reference and inline definition:
+
+```xml
+<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
+  <fullName>Priority__c</fullName>
+  <label>Priority</label>
+  <type>Picklist</type>
+  <valueSet>
+    <restricted>true</restricted>
+    <valueSetName>Priority_Levels</valueSetName>   <!-- WRONG: reference … -->
+    <valueSetDefinition>                            <!-- WRONG: … AND inline -->
+      <sorted>false</sorted>
+      <value>
+        <fullName>High</fullName>
+        <default>false</default>
+        <label>High</label>
+      </value>
+    </valueSetDefinition>
+  </valueSet>
+</CustomField>
+```
+
+**Error:** `Value set must reference a value set name or define a value set, but not both.`
+
+#### ✅ CORRECT — reference a Global Value Set:
+
+```xml
+<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
+  <fullName>Priority__c</fullName>
+  <label>Priority</label>
+  <description>Account priority drawn from the shared Priority Levels value set</description>
+  <inlineHelpText>Select the priority defined by the central Priority Levels list</inlineHelpText>
+  <type>Picklist</type>
+  <valueSet>
+    <restricted>true</restricted>
+    <valueSetName>Priority_Levels</valueSetName>
+  </valueSet>
+</CustomField>
+```
+
+### Same `<valueSetName>` element — Global vs. Standard value sets
+
+The SAME `<valueSetName>` element is used to reference both kinds of value set; only
+the name you put inside it differs.
+
+| Referenced set | `<valueSetName>` value | Suffix |
+|----------------|------------------------|--------|
+| **StandardValueSet** (platform-defined, e.g. Industry, LeadSource) | Bare enum name | NO `__c`, NO `__gvs` → `<valueSetName>Industry</valueSetName>` |
+| **GlobalValueSet** | Bare developer name | NO `__c`, **NO `__gvs`** → `<valueSetName>Priority_Levels</valueSetName>` |
+
+> **Rule: always use the bare developer name — never add `__gvs`.** In API 57.0+ orgs the
+> platform stores/displays a GlobalValueSet's name with a `__gvs` suffix internally, but the
+> **Metadata API (deploy AND retrieve) uses the bare name** (the suffix came from a patched-out
+> Winter '23 change that broke deploys). So `<valueSetName>Priority_Levels</valueSetName>`, never
+> `Priority_Levels__gvs`. A retrieve showing `__gvs` (or a "returned from org but not found in
+> local project" warning) is expected org-storage display — keep local metadata on the bare name.
+> Never append `__c` to a value-set name either.
+
+#### ✅ CORRECT — reference a Standard Value Set (bare name, no suffix):
+
+```xml
+<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
+  <fullName>Industry__c</fullName>
+  <label>Industry</label>
+  <description>Industry classification from the standard Industry value set</description>
+  <inlineHelpText>Pick the industry that best describes this account</inlineHelpText>
+  <type>Picklist</type>
+  <valueSet>
+    <restricted>true</restricted>
+    <valueSetName>Industry</valueSetName>
+  </valueSet>
+</CustomField>
+```
+
+### A value-set-backed field is `<restricted>` by design
+
+When a field references a value set, its values can only change by editing the value
+set itself — the field cannot define ad-hoc values. Set `<restricted>true</restricted>`
+on these fields. Leaving it unrestricted is meaningless for a referenced set.
+
+### Cross-reference: creating the value set itself
+
+This skill only **references** an existing value set. **Creating** the GlobalValueSet
+or editing a StandardValueSet (the `.globalValueSet-meta.xml` / `.standardValueSet-meta.xml`
+metadata) is the job of the `platform-value-set-generate` skill. If the value set does not yet
+exist, generate it there first, then reference it here.
+
+---
+
+## 2. Controlling / Dependent Picklists
+
+A **dependent** picklist filters its available values based on the selected value of a
+**controlling** field (another picklist, or a checkbox). The dependency lives on the
+**dependent** field via a `<controllingField>` element plus one `<valueSettings>` block
+per (controlling value → dependent value) pair.
+
+### ⭐ Use the MODERN API 38.0+ form ONLY
+
+| Form | Elements | Status |
+|------|----------|--------|
+| **Modern (API 38.0+)** | `<valueSet>` → `<controllingField>` + `<valueSetDefinition>` + `<valueSettings>` (`<controllingFieldValue>` + `<valueName>`) | ✅ USE THIS |
+| **Legacy (API ≤ 37.0)** | `<picklist>` / `<picklistValues>` / `<controllingFieldValues>` | ❌ DEPRECATED — do NOT generate |
+
+Never emit the legacy `<picklist>`, `<picklistValues>`, or `<controllingFieldValues>`
+tags. They are not valid against the modern Metadata API and will fail deployment.
+
+### ⭐ HARD RULE: both the controlling and dependent field must be `<restricted>true</restricted>`
+
+A field dependency requires a fixed, admin-defined value set on **both** ends. **Always emit
+`<restricted>true</restricted>` inside the `<valueSet>` of the controlling field AND the
+dependent field** — even when the request does not mention "restricted". Omitting it produces
+an unrestricted picklist, which cannot reliably participate in a field dependency and diverges
+from the expected metadata. This is non-negotiable for dependent picklists: if you write a
+`<controllingField>` or `<valueSettings>`, the same `<valueSet>` must also carry
+`<restricted>true</restricted>`.
+
+### Structure of a dependent picklist
+
+Inside the dependent field's `<valueSet>`, in this order:
+
+1. `<controllingField>` — API name of the controlling field (e.g. `Country__c`).
+2. `<valueSetDefinition>` — defines the dependent field's own values (as usual). The dependency
+   mapping does **NOT** go in here.
+3. one or more `<valueSettings>` blocks — **siblings** of `<valueSetDefinition>`, NOT nested
+   inside it or inside any `<value>`. One block **per (controlling value, dependent value) pair**:
+   - `<controllingFieldValue>` — a controlling-field value that enables this dependent value.
+   - `<valueName>` — the dependent value that becomes available.
+
+> ### ⛔ THE #1 MISTAKE: do NOT put `<controllingFieldValue>` inside `<value>`
+> The mapping lives in **separate `<valueSettings>` blocks**, never as a child of a
+> `<value>` in `<valueSetDefinition>`. Putting `<controllingFieldValue>` inside a `<value>`
+> fails deployment with `Element controllingFieldValue invalid at this location in type CustomValue`.
+>
+> ```xml
+> <!-- ❌ WRONG — controllingFieldValue nested in the value definition -->
+> <valueSetDefinition>
+>   <value>
+>     <fullName>USA</fullName><label>USA</label><default>false</default>
+>     <controllingFieldValue>Americas</controllingFieldValue>   <!-- INVALID HERE -->
+>   </value>
+> </valueSetDefinition>
+>
+> <!-- ✅ CORRECT — values defined plainly; mapping in SEPARATE valueSettings siblings -->
+> <valueSetDefinition>
+>   <value><fullName>USA</fullName><label>USA</label><default>false</default></value>
+> </valueSetDefinition>
+> <valueSettings>
+>   <controllingFieldValue>Americas</controllingFieldValue>
+>   <valueName>USA</valueName>
+> </valueSettings>
+> ```
+>
+> **One `<valueSettings>` per pair.** With multiple controlling values (Americas→USA,Canada;
+> EMEA→UK,Germany) you emit **one block for each (controllingValue, dependentValue) pair** — four
+> pairs = four `<valueSettings>` blocks. And remember: both fields carry `<restricted>true</restricted>`.
+
+### ✅ CORRECT — State dependent on Country (USA → California, Texas)
+
+**Controlling field — `Country__c` (a plain restricted picklist):**
+
+```xml
+<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
+  <fullName>Country__c</fullName>
+  <label>Country</label>
+  <description>Country used to filter the dependent State picklist</description>
+  <inlineHelpText>Select the country first; the State list filters to match</inlineHelpText>
+  <type>Picklist</type>
+  <valueSet>
+    <restricted>true</restricted>
+    <valueSetDefinition>
+      <sorted>false</sorted>
+      <value>
+        <fullName>USA</fullName>
+        <default>false</default>
+        <label>USA</label>
+      </value>
+      <value>
+        <fullName>Canada</fullName>
+        <default>false</default>
+        <label>Canada</label>
+      </value>
+    </valueSetDefinition>
+  </valueSet>
+</CustomField>
+```
+
+**Dependent field — `State__c`, controlled by `Country__c`:**
+
+```xml
+<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
+  <fullName>State__c</fullName>
+  <label>State</label>
+  <description>State filtered by the selected Country</description>
+  <inlineHelpText>Available states depend on the Country you picked</inlineHelpText>
+  <type>Picklist</type>
+  <valueSet>
+    <controllingField>Country__c</controllingField>
+    <restricted>true</restricted>
+    <valueSetDefinition>
+      <sorted>false</sorted>
+      <value>
+        <fullName>California</fullName>
+        <default>false</default>
+        <label>California</label>
+      </value>
+      <value>
+        <fullName>Texas</fullName>
+        <default>false</default>
+        <label>Texas</label>
+      </value>
+    </valueSetDefinition>
+    <valueSettings>
+      <controllingFieldValue>USA</controllingFieldValue>
+      <valueName>California</valueName>
+    </valueSettings>
+    <valueSettings>
+      <controllingFieldValue>USA</controllingFieldValue>
+      <valueName>Texas</valueName>
+    </valueSettings>
+  </valueSet>
+</CustomField>
+```
+
+> Each dependent value gets its own `<valueSettings>` block per enabling controlling
+> value. If California were also valid under a second country, you would add another
+> `<valueSettings>` block with that country's `<controllingFieldValue>` and
+> `<valueName>California</valueName>`.
+
+### ❌ INCORRECT — deprecated legacy form:
+
+```xml
+<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
+  <fullName>State__c</fullName>
+  <label>State</label>
+  <type>Picklist</type>
+  <picklist>                                <!-- WRONG: deprecated wrapper -->
+    <controllingField>Country__c</controllingField>
+    <picklistValues>                        <!-- WRONG: use valueSetDefinition/value -->
+      <fullName>California</fullName>
+      <controllingFieldValues>USA</controllingFieldValues>  <!-- WRONG: use valueSettings -->
+    </picklistValues>
+  </picklist>
+</CustomField>
+```
+
+**Error:** `Element {http://soap.sforce.com/2006/04/metadata}picklist is not allowed` — the
+legacy dependency elements are not valid in the modern `<valueSet>` structure.
+
+---
+
+## 3. Enhanced Value Attributes
+
+### ⭐ Value-name fidelity — do NOT underscore picklist value names
+
+A **picklist value's `<fullName>` is NOT a field API name** and must NOT be transformed.
+Use the value text **exactly as the user spelled it**, spaces and all. A value the user
+calls `Closed Won` is `<fullName>Closed Won</fullName>` and `<label>Closed Won</label>` —
+**never** `Closed_Won`. Picklist value `<fullName>` permits spaces (and is not required to
+carry `__c`); the space-to-underscore + `__c` rule applies ONLY to the **field**
+`<fullName>` (e.g. field `Total Contract Value` → `Total_Contract_Value__c`), not to the
+values inside it. Underscoring a value name changes the value's identity, diverges from what
+the user asked for, and breaks any RecordType `<picklistValues>` / `<valueSettings>` that
+reference the value by its real name.
+
+| Element | Spaces? | `__c` suffix? | Example for "Closed Won" |
+|---|---|---|---|
+| **Field** `<fullName>` | ❌ replace with `_` | ✅ required | (field named) `Status__c` |
+| **Picklist value** `<fullName>` | ✅ keep as written | ❌ never | `Closed Won` |
+| **Picklist value** `<label>` | ✅ keep as written | ❌ never | `Closed Won` |
+
+> ❌ `<fullName>Closed_Won</fullName>`  ✅ `<fullName>Closed Won</fullName>`
+> When a RecordType filters this value it must also reference `Closed Won` (with the space)
+> in `<values><fullName>` — the names must match exactly across field and record type.
+
+Inline `<value>` entries (CustomValue subfields) support more than `<fullName>`,
+`<default>`, and `<label>`. The common extras:
+
+| Subfield | Type | Notes |
+|----------|------|-------|
+| `<color>` | Hex string | UI chart/badge color, e.g. `#FF0000`. Include the leading `#`. |
+| `<isActive>` | Boolean | `false` retires a value without deleting it (preserves history). Inactive values still count toward the 1,000-value restricted limit. |
+| `<description>` | String | Value-level documentation, distinct from the field-level `<description>`. |
+
+These are independent of `<default>` and `<label>` and may be combined freely.
+
+### ✅ CORRECT — Status picklist with colors and an inactive value
+
+```xml
+<CustomField xmlns="http://soap.sforce.com/2006/04/metadata">
+  <fullName>Status__c</fullName>
+  <label>Status</label>
+  <description>Lifecycle status of the record</description>
+  <inlineHelpText>Select the current lifecycle stage</inlineHelpText>
+  <type>Picklist</type>
+  <valueSet>
+    <restricted>true</restricted>
+    <valueSetDefinition>
+      <sorted>false</sorted>
+      <value>
+        <fullName>Cancelled</fullName>
+        <default>false</default>
+        <label>Cancelled</label>
+        <color>#FF0000</color>
+        <isActive>true</isActive>
+        <description>Work was stopped before completion</description>
+      </value>
+      <value>
+        <fullName>Complete</fullName>
+        <default>false</default>
+        <label>Complete</label>
+        <color>#00FF00</color>
+        <isActive>true</isActive>
+        <description>All work finished and accepted</description>
+      </value>
+      <value>
+        <fullName>Draft</fullName>
+        <default>false</default>
+        <label>Draft</label>
+        <isActive>false</isActive>
+        <description>Legacy draft state, retired from new records</description>
+      </value>
+    </valueSetDefinition>
+  </valueSet>
+</CustomField>
+```
+
+---
+
+## 4. Picklist Validation Rules
+
+The Metadata API rejects malformed picklist values at deploy time. Two common failures:
+
+### Duplicate value names
+
+Two `<value>` entries with the same `<fullName>` inside one `<valueSetDefinition>` are
+rejected.
+
+#### ❌ INCORRECT — duplicate value:
+
+```xml
+<valueSetDefinition>
+  <sorted>false</sorted>
+  <value>
+    <fullName>Open</fullName>
+    <default>false</default>
+    <label>Open</label>
+  </value>
+  <value>
+    <fullName>Open</fullName>              <!-- WRONG: duplicate fullName -->
+    <default>false</default>
+    <label>Open (again)</label>
+  </value>
+</valueSetDefinition>
+```
+
+**Error:** `duplicate value found: Open is defined multiple times`
+
+### Invalid API-name format
+
+A picklist `<value>`'s `<fullName>` must start with a letter and must NOT contain
+hyphens or begin with a digit. Unlike field API names, spaces ARE permitted (e.g.
+`Closed Won`, `United Kingdom`) — see §3 value-name fidelity; do NOT underscore them.
+The `__c` suffix is not required on value `<fullName>` values.
+
+The stricter "only alphanumerics and single underscores, no leading digit, no double
+or trailing underscore" rule applies to the *field* `<fullName>` (the `__c`-suffixed
+API name), not to picklist value fullNames.
+
+#### ❌ INCORRECT — invalid value API name:
+
+```xml
+<value>
+  <fullName>1st-Choice</fullName>          <!-- WRONG: starts with digit, has hyphen -->
+  <default>false</default>
+  <label>1st Choice</label>
+</value>
+```
+
+**Error:** `Invalid fullName: must begin with a letter and use only alphanumeric characters and underscores`
+
+#### ✅ CORRECT:
+
+```xml
+<value>
+  <fullName>First Choice</fullName>          <!-- fixed: letter-first, hyphen removed, space preserved -->
+  <default>false</default>
+  <label>1st Choice</label>
+</value>
+```
+
+---
+
+## 5. Scoping a Picklist to a Record Type
+
+> **Scope note.** This section covers ONLY the picklist seam between a CustomField and a
+> RecordType — i.e. "expose a subset of *this field's* values for a given record type." It
+> is NOT a general record-type authoring guide. Record types also carry compact layouts,
+> page-layout assignments, branding, and more, which are out of scope here and owned by the
+> record-type / UI metadata area. When a request goes beyond picklist value visibility, say
+> so and defer the broader record-type work rather than guessing.
+
+A common follow-on to creating a picklist field is "…and for the *X* record type, only show
+values A and B." That visibility is expressed on the **RecordType**, not the field — the
+field keeps its full value set; the record type filters which values appear.
+
+### Picklist value filtering
+
+Add one `<picklistValues>` block per filtered field inside the `<RecordType>`:
+
+| Element | Requirement | Notes |
+|---|---|---|
+| `<picklistValues>` | One per filtered picklist | Repeat per field you filter |
+| `<picklist>` | Required | The field API name (e.g. `Status__c`, or `StageName` for a standard field) |
+| `<values>` | One per **exposed** value | List ONLY the values this record type should show; omitted values are hidden (NOT deleted from the field) |
+| `<values><fullName>` | Required | The picklist value's API name |
+| `<values><default>` | Required | `true` on exactly one value, `false` on the rest |
+
+### The RecordType file always carries its own `<fullName>`
+
+Unlike a CustomObject (whose name is derived from the folder/filename), a `<RecordType>` **must
+include a `<fullName>`** element — the record type's developer name (e.g. `<fullName>Internal</fullName>`),
+matching the filename `Internal.recordType-meta.xml`. It's bare (no object prefix); the object
+comes from the `objects/<Object>/` folder path.
+
+### ⭐ STEP 1 — Decide if this object needs a BusinessProcess (do this BEFORE writing files)
+
+A record type on a **BusinessProcess-gated object — Opportunity, Lead, Case, or Solution —
+will NOT deploy without a `<businessProcess>` reference**, even when it only filters a *custom*
+picklist and never touches the standard status field (`Required field is missing: businessProcess`).
+**Every other object — all custom objects (`*__c`) and other standard objects like Account or
+Contact — needs NO BusinessProcess.** Decide first:
+
+| Object | BusinessProcess? | Files to emit |
+|---|---|---|
+| Opportunity / Lead / Case / Solution | **REQUIRED** | BusinessProcess file **+** RecordType that references it (two files) |
+| Custom object (`*__c`), Account, Contact, everything else | **None** | RecordType alone (one file) |
+
+For the gated four, a suitable BusinessProcess may already exist in the org — reference its
+developer name instead of generating a new one (confirm via the grounding MCP's `search_metadata`
+if available; otherwise generate a minimal one). For everything else, **do not invent a
+BusinessProcess** — adding one to a custom-object record type is wrong.
+
+#### ✅ CORRECT — Opportunity "Enterprise" record type, two deployable files
+
+```xml
+<!-- File 1: objects/Opportunity/businessProcesses/Enterprise_Sales_Process.businessProcess-meta.xml -->
+<BusinessProcess xmlns="http://soap.sforce.com/2006/04/metadata">
+  <fullName>Enterprise_Sales_Process</fullName>   <!-- BARE — see the api-context translation note below -->
+  <isActive>true</isActive>
+  <values><fullName>Prospecting</fullName></values>      <!-- these are Opportunity STAGE (StageName) values, NOT Status__c — the BP governs the standard stage picklist. Do NOT add <default> (fails: "Cannot specify a default on: Opportunity") -->
+  <values><fullName>Qualification</fullName></values>
+  <values><fullName>Closed Won</fullName></values>
+  <values><fullName>Closed Lost</fullName></values>
+</BusinessProcess>
+```
+
+> ⛔ **`<fullName>` is BARE in the source file — strip the entity prefix that api-context gives you.**
+> The metadata grounding / api-context for `BusinessProcess` reports the fullName in its **API
+> form**, entity-qualified: `Opportunity.Enterprise_Sales_Process`. That is correct for the API —
+> but in the **source/DX-format file you author**, the entity is already conveyed by the
+> `objects/Opportunity/` folder path, so the `<fullName>` element is the **bare process name**:
+> `Enterprise_Sales_Process`, NOT `Opportunity.Enterprise_Sales_Process`. (Same API-vs-source split
+> as the GlobalValueSet `__gvs` suffix in §1.) Writing the entity-qualified form makes the
+> RecordType's bare `<businessProcess>Enterprise_Sales_Process</businessProcess>` reference fail to
+> resolve → `no BusinessProcess named Opportunity.Enterprise_Sales_Process found`. **When you pull
+> the BP name from api-context and it looks like `Opportunity.X`, write `X` in the file.** The BP
+> file's `<fullName>` and the RecordType's `<businessProcess>` must be the identical bare string.
+
+```xml
+<!-- File 2: objects/Opportunity/recordTypes/Enterprise.recordType-meta.xml -->
+<RecordType xmlns="http://soap.sforce.com/2006/04/metadata">
+  <fullName>Enterprise</fullName>
+  <label>Enterprise</label>
+  <active>true</active>
+  <businessProcess>Enterprise_Sales_Process</businessProcess>  <!-- REQUIRED; must precede <picklistValues> -->
+  <picklistValues>
+    <picklist>Status__c</picklist>
+    <values>
+      <fullName>Qualified</fullName>
+      <default>true</default>
+    </values>
+    <values>
+      <fullName>Closed Won</fullName>
+      <default>false</default>
+    </values>
+  </picklistValues>
+</RecordType>
+```
+
+#### ❌ INCORRECT — BusinessProcess file emitted but NOT referenced (most common failure)
+
+```xml
+<!-- File 1 (businessProcesses/Enterprise_Sales_Process...) was generated correctly, BUT -->
+<!-- File 2, the RecordType, FORGOT the <businessProcess> element: -->
+<RecordType xmlns="http://soap.sforce.com/2006/04/metadata">
+  <fullName>Enterprise</fullName>
+  <active>true</active>
+  <label>Enterprise</label>
+  <!-- WRONG: no <businessProcess> here → the BP file is orphaned and the deploy fails -->
+  <picklistValues> ... </picklistValues>
+</RecordType>
+```
+
+**Error:** `Required field is missing: businessProcess`. Generating the BusinessProcess file is
+only half the job — the `<RecordType>` MUST also carry the `<businessProcess>NameMatchingTheFile</businessProcess>`
+element. Both, every time, for Opportunity/Lead/Case/Solution.
+
+**BusinessProcess gotchas (these block deployment):**
+- **`<fullName>` is BARE — never object-qualified.** Inside
+  `objects/Opportunity/businessProcesses/Enterprise_Sales_Process.businessProcess-meta.xml`, the
+  `<fullName>` is just `Enterprise_Sales_Process` — NOT `Opportunity.Enterprise_Sales_Process`.
+  The object comes from the folder path. Qualifying it (`<fullName>Opportunity.Enterprise_Sales_Process</fullName>`)
+  makes the RecordType's bare `<businessProcess>Enterprise_Sales_Process</businessProcess>`
+  reference unresolvable → `no BusinessProcess named Opportunity.Enterprise_Sales_Process found`.
+  The BP file's `<fullName>` and the RecordType's `<businessProcess>` value must be the **same
+  bare string**.
+- **Two coupled parts** — (1) the `businessProcesses/<Name>.businessProcess-meta.xml` file AND
+  (2) a `<businessProcess><Name></businessProcess>` element inside the `<RecordType>`. The
+  developer name must match. Doing only one is the #1 deploy failure.
+- **Element order** — `<businessProcess>` must appear **before** `<picklistValues>` inside
+  `<RecordType>` (it follows `<active>`). Out-of-order elements fail schema validation.
+- **No `<default>` on Opportunity BP values** — specifying `<default>` on a `<values>` entry
+  fails with `Cannot specify a default on: Opportunity`. (Lead / Case / Solution DO allow a
+  BP default; Opportunity is the exception.)
+
+### Deployment ordering
+
+```text
+GlobalValueSet / StandardValueSet  (if the field draws from a value set)
+        ↓
+CustomField  (the picklist field, with its full value set)
+BusinessProcess  (REQUIRED for Opportunity/Lead/Case/Solution record types)
+        ↓
+RecordType   (filters the field's values; references the BusinessProcess)
+```
+
+- The CustomField (and ALL the values the record type references) MUST deploy **before** the
+  RecordType, or you get `Cannot find the picklist value: <X>`.
+- For Opportunity/Lead/Case/Solution, the `<businessProcess>` must exist (same package or
+  already in the org) before the RecordType.
+
+### ⭐ UI-sync gotcha — values may not auto-display after API deploy
+
+When `<picklistValues>` are loaded via the Metadata API, the values are correctly associated
+under the hood, **but they may not automatically appear as "Selected Values" in the Record
+Type editing screen in Setup.** The API deploy succeeds; this is a platform UI-sync
+limitation, not a deployment error. Tell the user they may need to: **Setup → Object Manager →
+[Object] → Record Types → [Record Type] → Edit next to the picklist → move values into
+Selected Values → Save.** Always call this out when delivering record-type picklist filtering.
+
+### Common failures
+
+| Error / Symptom | Cause | Fix |
+|---|---|---|
+| `Required field is missing: businessProcess` | Opportunity/Lead/Case/Solution record type without a `<businessProcess>` | Add a BusinessProcess (deploy it first or reference an existing one) |
+| `Cannot specify a default on: Opportunity` | `<default>` set on an Opportunity BusinessProcess value | Remove `<default>` from the Opportunity BP `<values>` |
+| `Cannot find the picklist value: <X>` | A value in `<picklistValues>` doesn't exist on the field | Deploy the field with that value first; check spelling/case |
+| Filtered values still show full set in UI | API-loaded values not promoted to Selected Values | Perform the manual Setup step above |