@salesforce/afv-skills 1.28.0 → 1.30.0

package/skills/platform-policy-rule-generate/references/ui-compatibility.md

@@ -0,0 +1,142 @@
+# UI Compatibility — Data Governance Policy Builder
+
+The Data Governance Policy Builder edits a **strict subset** of the MDAPI. Anything outside that subset must be maintained via MDAPI/Tooling for the policy's lifetime — admins cannot open it in the builder without silent data loss or a hard crash.
+
+> **Default goal**: produce UI-compatible policies. Only fall back to API-only after asking the operator and getting explicit confirmation.
+
+---
+
+## What the UI Can Render
+
+**Categories** : `GOVERNANCE_POLICY_RULE_DEFINITION`, `RECORD_POLICY_RULE_DEFINITION`, `TRANSFORM_POLICY_RULE_DEFINITION` 
+**Categories NOT handled** : `ACCESS_POLICY_RULE_DEFINITION` (UI forces to GOVERNANCE on save), `IDENTIFIED_RECORD_POLICY_RULE_DEFINITION`
+
+**Effects** : `Permit`, `Forbid` (UI label "Deny"), `Transform`
+
+**Actions** : `Read`, `TupleRead` — two real choices for OLS/FLS rules.
+- `Read`: evaluates conditions against the resource itself
+- `TupleRead`: cascade rewriter — expands object-level condition to also cover `resource.object.*` for fields. Use when the intent is "objects matching X AND all their fields"
+- Multiple `<action>` entries: only the first is kept on save
+
+**`<ruleConsumer>`** : only `DATACLOUD` (hardcoded on save) 
+**`<principalScopeType>`** : only `ANY` (hardcoded on save) 
+**`<resourceScopeType>`** : `ANY`, `RECORD`, `FIELD`, `DATASPACE`, `SPAN` 
+**`<principalAuthenticationLevel>`** : `INTERNAL`, `AUTHENTICATED`, `UNIDENTIFIED`. `IDENTIFIED` not exposed. 
+**`<replicated>`** : read but NOT editable. Once `true`, UI forces read-only mode. 
+**`<transformPrecedence>`** : not exposed; non-zero values dropped.
+
+---
+
+## Conditions — Supported Shapes
+
+**Top-level conjunction**: only `<whenPolicyRuleDefinitionClauseConjunction>`. The UI forces `<unlessPolicyRuleDefinitionClauseConjunction>` to `null` on save.
+
+**Conjunction expression**: the UI builds `(AND …)` of up to four sections dispatched by path type. A pure flat `(OR 1 2)` at the top level triggers `// ERROR: Unsupported rule!` — rule silently dropped. `OR` only round-trips inside a single section's group.
+
+**Path types per UI section:**
+
+| UI Section | Recognized path |
+|------------|-----------------|
+| Users (Permission) | `principalPath = ASSIGNED_PERMISSIONS_PATH` |
+| Resource entity-type | `resourcePath = ENTITYTYPE` with `IS` operator |
+| Data space | `resourcePath = DATASPACE` or `contextPath = SESSION_DATASPACE` |
+| Tag / Classification | `resourcePath = TAG` or `CLASSIFICATION` |
+| RLS rule criteria | `resourcePath = RECORDFIELD` or `EXPRESSION` |
+
+Any other path type → condition silently ignored when UI rebuilds the rule.
+
+**Operators per path**:
+- Tag/Classification: `CONTAINS_ANY`, `CONTAINS_NONE`. (`CONTAINS_ALL` exists in schema but not offered in dropdowns)
+- Permission: `CONTAINS_ANY` (Permit) / `CONTAINS_NONE` (Forbid/Transform)
+- RLS `RECORDFIELD`: `EQUALS`, `NOT_EQUALS`, `LIKE`, `LESS_THAN(_OR_EQUALS)`, `GREATER_THAN(_OR_EQUAL)`, `HIERARCHICALLY_ABOVE` (DLO/DMO only). **Not editable**: `HIERARCHICALLY_BELOW`, `IN`, `CONTAINS_ALL`
+- RLS join (`EXPRESSION`): `EXISTS` only
+
+**`<policyRuleValueSet>` reference types** : `CUSTOM_TAG`, `STANDARD_TAG`, `CUSTOM_CLASSIFICATION`, `STANDARD_CLASSIFICATION`, `CUSTOM_PERMISSION`. **Not editable**: `HIERARCHY`, `DATASPACE`.
+
+---
+
+## Implicit Defaults Injected by the UI on Save
+
+When the UI saves, it auto-injects these — if your hand-authored XML omits them or uses different values, the first UI save rewrites them:
+
+| Field | UI default |
+|-------|-----------|
+| `principalAuthenticationLevel` | `INTERNAL` |
+| `principalScopeType` | `ANY` |
+| `ruleConsumer` | `DATACLOUD` |
+| `unlessPolicyRuleDefinitionClauseConjunction` | `null` (always) |
+| `actions` | only first action kept |
+| `policyRuleResourceDomains` | only first `<resourceDomain>` kept |
+
+---
+
+## The Non-Round-Trip Checklist
+
+The policy will **not** round-trip through the UI without data loss or silent failure if **any** of the following is true:
+
+- [ ] `category` is `ACCESS_POLICY_RULE_DEFINITION` or `IDENTIFIED_RECORD_POLICY_RULE_DEFINITION`
+- [ ] `ruleConsumer` ≠ `DATACLOUD`
+- [ ] More than one `<action>`, or action is not `Read` / `TupleRead`
+- [ ] **No top-level `resourcePath=ENTITYTYPE` discriminator group** for ACCESS/GOVERNANCE rules — this causes a **hard crash** (`Cannot use 'in' operator to search for 'Permit' in undefined`), not a graceful degradation. A `TupleRead` rule without the OR-of-ENTITYTYPE clause still deploys and works at runtime — the crash is UI-only.
+- [ ] **Bare top-level condition index** in `<conjunctionExpression>` (e.g. `3` instead of `(AND 3)`) — causes crash in `buildCriteria` (`param.params.map(...)` = `undefined.map()`)
+- [ ] More than one `<resourceDomain>`
+- [ ] An `<unlessPolicyRuleDefinitionClauseConjunction>` block present
+- [ ] Any `<conditions>` uses `<clause>UNLESS</clause>`
+- [ ] `<conjunctionExpression>` uses top-level `OR` (e.g. `(OR 1 2)`)
+- [ ] `<principalPath>` other than `ASSIGNED_PERMISSIONS_PATH` (user ID etc. may appear only inside SOQL `${User.X}` substitutions)
+- [ ] `<resourcePath>` other than `TAG`, `CLASSIFICATION`, `DATASPACE`, `RECORDFIELD`, `EXPRESSION`, `ENTITYTYPE`
+- [ ] `<valuePrincipalPath>` is not one of `USER_ID`, `USER_ROLE_ID`, `ORGANIZATION_ID`, `SCALAR_ATTRIBUTE`, `PLURAL_ATTRIBUTE` (with `${User.X}` expression)
+- [ ] `<contextPath>` other than `SESSION_DATASPACE`
+- [ ] Operator is `HIERARCHICALLY_BELOW`, `IN`, or `CONTAINS_ALL`
+- [ ] `<valueReferenceType>` is `HIERARCHY` or `DATASPACE`
+- [ ] `<valueString>` is typed JSON other than `{"t":"Text","v":"FIELD"|"RECORD"|"OBJECT"}` or `{"t":"Boolean","v":…}` with a UI-recognized boolean field
+- [ ] `<resourceTransform>` not in the masking-category mapped set
+- [ ] `<resourceExpression>` ARGLIST has multiple arguments
+- [ ] `<replicated>true</replicated>` in an org with replication frozen
+
+If **none** of the above is true, the policy is **UI-compatible**.
+
+> **Important**: The UI shows NO banner when it drops unsupported pieces on save (`// ERROR: Unsupported rule!` comment, no surfaced message). Operator-confirmation is the only line of defense.
+
+---
+
+## Operator-Confirmation Protocol
+
+Whenever a request would produce a UI-incompatible policy:
+
+1. **Try to make it UI-compatible first.** Mechanical rewrites:
+ - `unless` → `when` with negated operator:
+ | Intent | UI-compatible rewrite |
+ |--------|----------------------|
+ | `unless principal has permission X` | `WHEN ASSIGNED_PERMISSIONS_PATH CONTAINS_NONE X` |
+ | `unless resource has tag X` | `WHEN TAG CONTAINS_NONE X` |
+ | `unless record field = value` | `WHEN RECORDFIELD NOT_EQUALS value` |
+ - Top-level `OR` between two tags → nest inside a tag/classification section group
+ - Multiple `<action>` → split into multiple rules
+
+2. **If a UI-compatible rewrite is not possible**, tell the operator:
+ - Which traits make it incompatible (cite items from the checklist above)
+ - That the Data Governance Policy Builder will silently drop unsupported pieces on save with no warning
+ - That maintenance must happen through MDAPI/Tooling for the policy's lifetime
+
+3. **Wait for explicit confirmation.** Do not write the file until confirmed.
+
+4. **On confirmation**, add an in-source marker to `<description>` (or a comment above the rule): `# API-only: not editable in Data Governance Policy Builder. Reasons: <bullets>`. Also set `<builderCompatible>false</builderCompatible>` on the parent set.
+
+---
+
+## UI-Compatibility Matrix for Templates
+
+| Template | UI-compatible? | Notes |
+|----------|----------------|-------|
+| Bare permit, no conditions | Partial | Single `<action>Read</action>` only; `ruleConsumer=DATACLOUD`. UI maps ACCESS → Governance on load. |
+| Tag / Classification / Permission gate | Yes | `CONTAINS_ANY` / `CONTAINS_NONE` only. Tag refs must resolve in org. |
+| Basic RLS (RECORDFIELD = user attribute) | Yes | `USER_ID` / `ORGANIZATION_ID` / `USER_ROLE_ID` round-trips. |
+| TupleRead with OR-of-ENTITYTYPE | Yes | The canonical UI-compatible OLS/FLS shape. |
+| IDENTIFIED_RECORD | Not MDAPI-authorable | Must be a runtime RuleProvider. |
+| RLS via PROJECTION join | Yes | Single PROJECTION editable. |
+| Scalar/plural SOQL principal | Out of MDAPI contract | `SCALAR_ATTRIBUTE`/`PLURAL_ATTRIBUTE` not in `RulePrincipalPathType`. Fixture-only. |
+| TRANSFORM with permission + classification | Yes | Use masking-category-mapped transforms only. |
+| `(AND 1 2)` multi-condition | Yes (if each section is one of the four UI buckets) | |
+| Top-level `(OR 1 2)` | No | Triggers unsupported-rule path; silently dropped. |
+| Hierarchy traversal | No | `HIERARCHICALLY_BELOW` and `HIERARCHY` not in UI dropdowns. Always API-only. |

package/skills/platform-soql-query/README.md

@@ -14,7 +14,7 @@ Salesforce SOQL query generation, optimization, and analysis skill with 100-poin
 
 ### 1. Invoke the skill
 
-```
+```yaml
 Skill: platform-soql-query
 Request: "Find Accounts with open Opportunities created this quarter"
 ```

package/skills/platform-soql-query/SKILL.md

@@ -90,7 +90,7 @@ When finishing, report in this order:
 
 Suggested shape — use `references/soql-syntax-reference.md` for exact syntax:
 
-```
+```text
 Query goal: <summary>
 Query: <soql or sosl>
 Design: <relationship / aggregate / filter choices>

package/skills/platform-soql-query/references/anti-patterns.md

@@ -308,7 +308,7 @@ WHERE Days_Open__c > 30
 
 ## Quick Reference: Selectivity Rules
 
-```
+```text
 A filter is SELECTIVE when:
 ├── Uses an indexed field, AND
 ├── Returns < 10% of first million records, OR

package/skills/platform-soql-query/references/field-coverage-rules.md

@@ -21,7 +21,7 @@ This guide documents field coverage validation rules for SOQL queries — ensuri
 
 When you query an sObject, only the fields in the SELECT clause are populated. Accessing any other field results in a runtime error:
 
-```
+```text
 System.SObjectException: SObject row was retrieved via SOQL without querying the requested field: Account.Industry
 ```
 

package/skills/platform-soql-query/references/query-optimization.md

@@ -17,7 +17,7 @@
 
 ## Selectivity Rules
 
-```
+```text
 A filter is selective when it returns:
 - < 10% of total records for first 1 million
 - < 5% of total records for additional records

package/skills/platform-soql-query/scripts/post-tool-validate.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 """
-Post-Tool Validation Hook for querying-soql skill.
+Post-Tool Validation Hook for platform-soql-query skill.
 
 This hook runs AFTER Write or Edit tool completes and provides validation
 feedback for SOQL files (*.soql).
@@ -23,8 +23,8 @@ import json
 SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
 sys.path.insert(0, SCRIPT_DIR)
 
-# Find shared modules (../../shared relative to querying-soql)
-PLUGIN_ROOT = os.path.dirname(os.path.dirname(SCRIPT_DIR))  # querying-soql/
+# Find shared modules (../../shared relative to platform-soql-query)
+PLUGIN_ROOT = os.path.dirname(os.path.dirname(SCRIPT_DIR))  # platform-soql-query/
 SKILLS_ROOT = os.path.dirname(PLUGIN_ROOT)  # sf-skills/
 SHARED_DIR = os.path.join(SKILLS_ROOT, "shared")
 sys.path.insert(0, SHARED_DIR)

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

@@ -0,0 +1,305 @@
+---
+name: platform-value-set-generate
+description: "Use this skill when users need to create, generate, or validate a Salesforce global value set or customize a standard value set. Trigger when users mention a global value set, GlobalValueSet, standard value set, StandardValueSet, a reusable picklist, a picklist value set shared across fields, or customizing standard picklists like Industry, Lead Source, or Opportunity Stage. Also use when users hit deployment errors adding values to a standard picklist, referencing a value set from a custom field, or working with .globalValueSet-meta.xml or .standardValueSet-meta.xml files. DO NOT TRIGGER for an inline one-off picklist on a single field with no reuse, or for general custom field metadata work that does not involve a GlobalValueSet or StandardValueSet — use platform-custom-field-generate instead."
+metadata:
+  version: "1.0"
+  minApiVersion: "60.0"
+  cliTools:
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+---
+
+## Overview
+
+Generates and validates the two reusable picklist value-set metadata types — **GlobalValueSet** (a new reusable set shared across fields) and **StandardValueSet** (customizing a built-in catalog picklist like Industry or Lead Source) — and wires a CustomField to one via `<valueSetName>`.
+
+### Scope
+
+- **In scope:** creating a GlobalValueSet, customizing a StandardValueSet, referencing either from a field, and the related deployment errors.
+- **Out of scope:** a one-off inline picklist on a single field with no reuse → use **`platform-custom-field-generate`** (inline `<valueSetDefinition>`). Generating the *field* that references a value set is also `platform-custom-field-generate`'s job; this skill produces the value set itself.
+
+**Two different metadata types — do not confuse them:**
+
+| Concern | GlobalValueSet | StandardValueSet |
+|---------|----------------|------------------|
+| Folder | `globalValueSets/` | `standardValueSets/` |
+| File suffix | `.globalValueSet-meta.xml` | `.standardValueSet-meta.xml` |
+| 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 create a new NAME? | Yes | No — only the fixed catalog |
+| `*` wildcard in package.xml | Supported | Not supported |
+
+---
+
+## Specification
+
+### 1. Purpose
+
+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.
+
+---
+
+### 2. GlobalValueSet — Syntactic Essentials
+
+**File:** `globalValueSets/<DeveloperName>.globalValueSet-meta.xml`
+
+The developer name comes from the **filename**, not a `<fullName>` tag.
+
+#### Required Elements
+
+| Element | Requirement | Notes |
+|---------|-------------|-------|
+| `<masterLabel>` | Required | UI label for the value set |
+| `<sorted>` | Required | `true` = alphabetize values in the UI; `false` = preserve listed order |
+| `<customValue>` | Required (≥1) | One per value (see below) |
+
+#### `<customValue>` Sub-Elements
+
+| Sub-element | Requirement | Notes |
+|-------------|-------------|-------|
+| `<fullName>` | Required | The value's API name. Use the value text **as the user spelled it** — spaces are allowed and must be preserved (e.g. `Closed Won`, not `Closed_Won`). Must start with a letter. This is a value name, NOT a field API name, so do not append `__c` or replace spaces with underscores. |
+| `<default>` | Optional | At most one value `true`. Omit it (or use `false`) on the rest — it is not required on every value. |
+| `<label>` | Required | UI label for the value |
+| `<color>` | Optional | Hex color, e.g. `#FF0000` |
+| `<isActive>` | Optional | Omit (active) or `false` to deactivate |
+| `<description>` | Optional | Per-value description |
+
+#### The `__gvs` Suffix — do NOT use it in metadata
+
+**Rule: reference a GlobalValueSet by its bare developer name. Never add `__gvs`.**
+
+In API 57.0+ orgs the platform *stores/displays* a GlobalValueSet's developer name with a `__gvs` suffix internally, but the **Metadata API (deploy and retrieve) always uses the bare name** — `<valueSetName>Priority_Levels</valueSetName>`, not `Priority_Levels__gvs`. The suffix was briefly emitted by a Winter '23 change that caused deploy failures and was patched out. So:
+
+- The file is `globalValueSets/Priority_Levels.globalValueSet-meta.xml` — **no `__gvs`** in the filename.
+- A field references it as `<valueSetName>Priority_Levels</valueSetName>` — **no `__gvs`**.
+- If a retrieve shows `Priority_Levels__gvs` in the org or you see a "returned from org but not found in local project" warning, that's the expected org-storage display — keep your local metadata on the bare name.
+
+#### CORRECT — GlobalValueSet
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<GlobalValueSet xmlns="http://soap.sforce.com/2006/04/metadata">
+    <masterLabel>Priority Levels</masterLabel>
+    <sorted>false</sorted>
+    <customValue>
+        <fullName>Critical</fullName>
+        <default>false</default>
+        <label>Critical</label>
+    </customValue>
+    <customValue>
+        <fullName>High</fullName>
+        <default>false</default>
+        <label>High</label>
+    </customValue>
+    <customValue>
+        <fullName>Medium</fullName>
+        <default>true</default>
+        <label>Medium</label>
+    </customValue>
+    <customValue>
+        <fullName>Low</fullName>
+        <default>false</default>
+        <label>Low</label>
+    </customValue>
+</GlobalValueSet>
+```
+
+#### INCORRECT — GlobalValueSet
+
+```xml
+<GlobalValueSet xmlns="http://soap.sforce.com/2006/04/metadata">
+    <fullName>Priority_Levels</fullName>      <!-- WRONG: name comes from the filename -->
+    <masterLabel>Priority Levels</masterLabel>
+    <!-- WRONG: <sorted> is required and missing -->
+    <standardValue>                            <!-- WRONG: GVS uses <customValue>, not <standardValue> -->
+        <fullName>Critical</fullName>
+    </standardValue>
+</GlobalValueSet>
+```
+
+**Errors:** missing required `sorted`; unknown element `standardValue`; root `fullName` is rejected because the name is derived from the filename.
+
+---
+
+### 3. StandardValueSet — Syntactic Essentials CRITICAL
+
+**File:** `standardValueSets/<Name>.standardValueSet-meta.xml`
+
+#### 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.
+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.
+
+#### `<standardValue>` — Modifiable Sub-Elements
+
+| Sub-element | Modifiable? | Notes |
+|-------------|-------------|-------|
+| `<fullName>` | Identifies the value (must already exist) | Cannot introduce a new one |
+| `<label>` | Yes | Relabel the value's UI text |
+| `<isActive>` | Yes | `false` deactivates; omit or `true` keeps active |
+| `<default>` | Yes | At most one value `true` |
+| `<groupingString>` | Yes | Category grouping (used by some standard picklists) |
+
+#### Canonical StandardValueSet Names (partial)
+
+`Industry`, `LeadSource`, `OpportunityStage`, `OpportunityType`, `AccountType`, `AccountRating`, `LeadStatus`, `CaseStatus`, `CaseOrigin`, `CasePriority`, `CaseReason`, `TaskStatus`, `TaskPriority`, `QuoteStatus`, `Product2Family`, `Salutation`, `AccountOwnership`, `ContractStatus`, `OrderStatus`, `PartnerRole`.
+
+> Full appendix: the complete list of valid standard value set names is at
+> `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)
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<StandardValueSet xmlns="http://soap.sforce.com/2006/04/metadata">
+    <fullName>Industry</fullName>
+    <standardValue>
+        <fullName>Technology</fullName>
+        <default>false</default>
+        <label>Technology</label>
+        <isActive>true</isActive>
+    </standardValue>
+    <standardValue>
+        <fullName>Agriculture</fullName>
+        <default>false</default>
+        <label>Agriculture</label>
+        <isActive>false</isActive>   <!-- deactivated, but kept in the set -->
+    </standardValue>
+</StandardValueSet>
+```
+
+#### INCORRECT — StandardValueSet
+
+```xml
+<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 -->
+        <label>Renewable Energy</label>
+    </customValue>
+</StandardValueSet>
+```
+
+**Errors:** unknown element `masterLabel`/`customValue`; adding a value not already in the standard catalog fails deployment.
+
+---
+
+### 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.
+
+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:
+
+- **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.
+- **CLI fallback** — query the Tooling API directly:
+
+```bash
+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.)
+
+---
+
+### 5. Referencing a Value Set from a CustomField
+
+A picklist/multi-select CustomField references a value set via `<valueSetName>` inside `<valueSet>` (instead of an inline `<valueSetDefinition>`).
+
+```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>  <!-- bare developer name, NO __gvs; see §2 -->
+    </valueSet>
+</CustomField>
+```
+
+- For a **GlobalValueSet**, `<valueSetName>` is the **bare developer name** (e.g. `Priority_Levels`) — **never** add `__gvs`. The suffix is an org-storage display artifact; the Metadata API uses the bare name for both deploy and retrieve (see §2).
+- A field bound to a value set must **not** also declare an inline `<valueSetDefinition>` — choose one or the other.
+
+---
+
+### 6. Validation Rules
+
+The agent must **reject** and explain — not silently "fix" by inventing metadata — the following:
+
+| 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
+
+> "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.
+
+---
+
+### 7. Deployment Ordering
+
+A value set must deploy **before** any CustomField that references it.
+
+- Deploy the `GlobalValueSet` / `StandardValueSet` first, then the CustomField whose `<valueSetName>` points at it.
+- A field referencing a value set that does not yet exist fails with `valueSetName ... does not exist` (or a "not found" error).
+- In `package.xml`: `GlobalValueSet` **supports** the `*` wildcard; `StandardValueSet` does **not** — list each standard set member explicitly.
+
+---
+
+### 8. Common Deployment Errors
+
+| 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 |
+| `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 |
+| `valueSetName ... does not exist` | Field deployed before its value set, or `__gvs` wrongly added to the reference | Deploy the value set first; reference it by the **bare** developer name with NO `__gvs` (§2) |
+| Duplicate value name | Two `<customValue>` entries share a `fullName` | Make each `fullName` unique within the set (spaces in a value name are allowed — do NOT underscore them) |
+
+---
+
+## Verification Checklist
+
+Before generating value-set XML, verify:
+
+### Type Selection
+- [ ] Is this a reusable set shared across fields (GlobalValueSet) or a built-in standard picklist (StandardValueSet)?
+- [ ] If StandardValueSet: is the name in the standard catalog appendix? If not, it must be a GlobalValueSet or inline picklist.
+
+### GlobalValueSet Checks
+- [ ] Is the root `<GlobalValueSet>` with namespace `http://soap.sforce.com/2006/04/metadata`?
+- [ ] Is `<masterLabel>` present?
+- [ ] Is `<sorted>` present (`true` or `false`)?
+- [ ] Is there at least one `<customValue>`, each with `<fullName>` and `<label>` (at most one carrying `<default>true</default>`)?
+- [ ] Is there NO root `<fullName>` (name comes from the filename)?
+- [ ] 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?
+- [ ] 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?
+
+### Shared Checks
+- [ ] At most one value has `<default>true</default>`?
+- [ ] Are all value `fullName`s unique within the set? (Spaces in a value name are fine — preserve them as written; only the value-SET developer name and field API name use underscores.)
+- [ ] Does the value set deploy BEFORE any CustomField that references it?
+- [ ] Does the filename match the intended name?

package/skills/data360-activate/CREDITS.md

@@ -1,5 +0,0 @@
-# Credits & Acknowledgments
-
-This skill is part of the `*-datacloud` family. Shared attribution, upstream source mapping, and maintenance notes live in:
-- [../data360-orchestrate/CREDITS.md](../data360-orchestrate/CREDITS.md)
-- [../data360-orchestrate/UPSTREAM.md](../data360-orchestrate/UPSTREAM.md)

package/skills/data360-connect/CREDITS.md

@@ -1,5 +0,0 @@
-# Credits & Acknowledgments
-
-This skill is part of the `*-datacloud` family of skills covering the full Data Cloud workflow lifecycle. Shared upstream source mapping and maintenance notes live in:
-- [../data360-orchestrate/CREDITS.md](../data360-orchestrate/CREDITS.md)
-- [../data360-orchestrate/UPSTREAM.md](../data360-orchestrate/UPSTREAM.md)

package/skills/data360-harmonize/CREDITS.md

@@ -1,3 +0,0 @@
-# Credits & Acknowledgments
-
-This skill is part of the `*-datacloud` family of skills covering the Data Cloud lifecycle: ingestion, harmonization, segmentation, and retrieval.

package/skills/data360-orchestrate/CREDITS.md

@@ -1,15 +0,0 @@
-# Credits & Acknowledgments
-
-This skill family distills publicly shared Data Cloud implementation knowledge into sf-skills house style. Attribution is intentionally explicit because contributor credit is a core sf-skills principle.
-
----
-
-This family intentionally:
-- keeps sf-skills naming consistency (`*-datacloud`)
-- keeps the external CLI plugin outside this repo
-- favors deterministic helper scripts and reusable JSON templates
-- rewrites examples into generic sf-skills-style guidance rather than copying workshop-specific payloads
-
-See [UPSTREAM.md](UPSTREAM.md) for the maintenance contract.
-
----

package/skills/data360-orchestrate/UPSTREAM.md

@@ -1,45 +0,0 @@
-# Upstream Distillation Map for data360-orchestrate
-
-This file exists to make downstream maintenance easy without sacrificing sf-skills consistency.
-
-## Maintenance contract
-
-When upstream changes, do **not** copy blindly.
-
-Instead:
-1. review new upstream commits
-2. identify changed command behaviors, install patterns, or gotchas
-3. update sf-skills prompts and templates in a distilled form
-4. keep naming, attribution, and cross-skill boundaries consistent with sf-skills
-5. update this file with the new reviewed commit SHAs
-
-## High-priority upstream areas to re-check
-
-- installation / linking workflow for the community plugin
-- command counts and topic coverage
-- API-version guidance
-- known issues and bug-fix notes
-- live-tested command set
-- any new commands affecting Connect / Prepare / Harmonize / Segment / Act / Retrieve boundaries
-- connector-specific payload examples worth distilling into generic repo-safe examples
-- search-index / hybrid-search guidance and any command-surface changes around hybrid scoring or prefilter behavior
-- Ingestion API schema-upload flow, send-data examples, and problem-record guidance
-- unstructured-source setup differences between connection-level reruns, stream refreshes, and initial UI seeding
-- UI-only gaps where upstream introduces browser automation; validate before importing
-
-## Cross-skill boundary reminders
-
-Keep Data Cloud product work in `*-datacloud`, but do not blur into:
-- `agentforce-observe` for STDM/session tracing/parquet workflows
-- `platform-soql-query` for CRM SOQL-only tasks
-- `platform-data-manage` for CRM record seeding/cleanup
-- `platform-*-generate` skills for CRM schema creation (custom objects, fields, validation rules, etc.)
-
-## Local helper files in this family
-
-- `references/plugin-setup.md`
-- `scripts/bootstrap-plugin.sh`
-- `scripts/verify-plugin.sh`
-- `assets/definitions/`
-
-These are sf-skills-owned conveniences and should evolve independently from upstream when that improves user experience.

package/skills/data360-prepare/CREDITS.md

@@ -1,7 +0,0 @@
-# Credits & Acknowledgments
-
-Primary contributor: **Gnanasekaran Thoppae**
-
-This skill is part of the `*-datacloud` family. Shared attribution, upstream source mapping, and maintenance notes live in:
-- [../data360-orchestrate/CREDITS.md](../data360-orchestrate/CREDITS.md)
-- [../data360-orchestrate/UPSTREAM.md](../data360-orchestrate/UPSTREAM.md)

package/skills/data360-query/CREDITS.md

@@ -1,7 +0,0 @@
-# Credits & Acknowledgments
-
-Primary contributor: **Gnanasekaran Thoppae**
-
-This skill is part of the `*-datacloud` family. Shared attribution, upstream source mapping, and maintenance notes live in:
-- [../data360-orchestrate/CREDITS.md](../data360-orchestrate/CREDITS.md)
-- [../data360-orchestrate/UPSTREAM.md](../data360-orchestrate/UPSTREAM.md)

package/skills/data360-segment/CREDITS.md

@@ -1,3 +0,0 @@
-# Credits & Acknowledgments
-
-This skill is part of the `*-datacloud` family of skills covering the Salesforce Data Cloud workflow phases. Shared definitions, templates, and readiness scripts for this family live in the `data360-orchestrate` skill directory.

package/skills/experience-lwc-generate/CREDITS.md

@@ -1,5 +0,0 @@
-# Credits & Acknowledgments
-
-This skill is built on official Salesforce LWC platform patterns and established component development practices.
-
----