@salesforce/afv-skills 1.66.0 → 1.68.0

package/skills/platform-policy-rule-generate/references/resource-expression.md

@@ -0,0 +1,48 @@
+# Resource Expressions
+
+Use `resourceExpression` when the resource-side operand is computed from a projection instead of a direct path. The condition must use `<resourcePath>EXPRESSION</resourcePath>`.
+
+A transform argument list is different: it is a top-level `resourceExpression` on the rule, not inside a condition. Use `ARGLIST` exactly as documented in `policy-shapes.md` and the retrieved masking example.
+
+The validated RLS join shape is:
+
+```xml
+<conditions>
+    <clause>WHEN</clause>
+    <operator>EXISTS</operator>
+    <policyRuleDefinitionCondition>
+        <clause>WHEN</clause>
+        <operator>EQUALS</operator>
+        <policyRuleValueSet>
+            <valueText>${User.Email}</valueText>
+        </policyRuleValueSet>
+        <resourcePath>RECORDFIELD</resourcePath>
+        <valueDomain>RESOURCE_DMO:RESOURCE_FIELD</valueDomain>
+    </policyRuleDefinitionCondition>
+    <resourceExpression>
+        <projection>
+            <join>
+                <alias>JOIN_ALIAS</alias>
+                <predicate>
+                    <attribute>JOIN_DMO:JOIN_FIELD</attribute>
+                    <comparator>EQUALS</comparator>
+                    <on>
+                        <field>RESOURCE_FIELD</field>
+                        <resourceAlias>resource</resourceAlias>
+                        <schema>RESOURCE_DMO</schema>
+                    </on>
+                </predicate>
+                <schema>JOIN_DMO</schema>
+            </join>
+        </projection>
+        <type>PROJECTION</type>
+        <version>1</version>
+    </resourceExpression>
+    <resourcePath>EXPRESSION</resourcePath>
+    <whereClauseConjunction>1</whereClauseConjunction>
+</conditions>
+```
+
+For a join, define an `<alias>`, a `<schema>`, and a `<predicate>`. `<attribute>` belongs to the joined schema; `<on>` identifies the evaluated resource schema and field. Verify that join keys have compatible types. `whereClauseConjunction` numbers the nested `policyRuleDefinitionCondition` elements from `1`; it does not refer to top-level rule conditions.
+
+Do not invent projection structure or substitute a different operator. Start from a retrieved, deployed example for the same relationship shape and change only resolved schema, field, and alias values while preserving which side is joined and which side is the evaluated resource.

package/skills/platform-policy-rule-generate/references/runtime-context.md

@@ -0,0 +1,9 @@
+# Runtime Context
+
+Keep three version concepts separate:
+
+- `MIN_API_VERSION`: static skill capability floor (`66.0` in the skill metadata).
+- `ORG_API_VERSION`: target org's discovered maximum API version; use it for every API call, manifest, deploy, and retrieve.
+- `EVIDENCE_API_VERSION`: historical version attached to retrieved examples; provenance only.
+
+In normal author mode, resolve `ORG_API_VERSION` once from `/services/data`, verify it is at least `MIN_API_VERSION`, and carry it unchanged through the operation. Never copy an evidence version such as `69.0` into authored output unless the target org resolves to that version. Explicit evidence-recreation eval fixtures retain `{API_VERSION}` for harness substitution while recording API 69.0 as provenance in their instructions. Never modify `sfdx-project.json` to set an operation-specific version.

package/skills/platform-policy-rule-generate/references/templates-access.md

@@ -1,10 +1,12 @@
 # ACCESS / GOVERNANCE Templates
 
-Each template is a verified shape from a passing test fixture. Copy, then change names/values.
+The GOVERNANCE TupleRead shape is MDAPI persistence-validated. Policy Builder open/save compatibility is not yet validated. The ACCESS examples are older fixture-only shapes retained for explicitly requested API-only metadata.
+
+Prefer the complete semantic OLS evidence under `examples/TaggedObjectAccess/` and resolve every target-org value again.
 
 ---
 
-## ACCESS — Simple Permit (no conditions)
+## API-only ACCESS — Simple Permit (no conditions)
 
 Source: `baseSteelthread`
 
@@ -26,9 +28,9 @@ Source: `baseSteelthread`
 
 ---
 
-## ACCESS / GOVERNANCE — "Objects AND all their fields" via TupleRead (UI-compatible)
+## GOVERNANCE — "Objects AND all their fields" via TupleRead
 
-Source: see §8.2.1 of policy.md
+Source: `references/examples/TaggedObjectAccess/`
 
 Three required pieces:
 1. `<action>TupleRead</action>` — cascades object-level condition to fields
@@ -54,7 +56,7 @@ Three required pieces:
             <clause>WHEN</clause>
             <operator>IS</operator>
             <policyRuleValueSet>
-                <valueString>{&quot;t&quot;:&quot;Text&quot;,&quot;v&quot;:&quot;OBJECT&quot;}</valueString>
+                <valueText>OBJECT</valueText>
             </policyRuleValueSet>
             <resourcePath>ENTITYTYPE</resourcePath>
         </conditions>
@@ -62,7 +64,7 @@ Three required pieces:
             <clause>WHEN</clause>
             <operator>IS</operator>
             <policyRuleValueSet>
-                <valueString>{&quot;t&quot;:&quot;Text&quot;,&quot;v&quot;:&quot;FIELD&quot;}</valueString>
+                <valueText>FIELD</valueText>
             </policyRuleValueSet>
             <resourcePath>ENTITYTYPE</resourcePath>
         </conditions>
@@ -82,11 +84,11 @@ Three required pieces:
 </PolicyRuleDefinition>
 ```
 
-For **deny semantics**: `<effect>Forbid</effect>`. To add "deny unless permission Y", insert a 4th condition with `ASSIGNED_PERMISSIONS_PATH CONTAINS_NONE Y` and use `(AND (OR 1 2) (AND 3) (AND 4))`.
+Do not infer deny semantics from this Permit example. Use a separately retrieved and target-org-validated shape.
 
 ---
 
-## ACCESS — Gated by Tag / Classification / Permission
+## API-only ACCESS — Gated by Tag / Classification / Permission
 
 Source: `conditionTagValidSteelthread`, `conditionClassificationValidClauseSteelthread`, `conditionAssignedPermPathValidSteelthread`
 
@@ -113,7 +115,7 @@ Source: `conditionTagValidSteelthread`, `conditionClassificationValidClauseSteel
                 <valueReferenceType>CUSTOM_TAG</valueReferenceType>
             </policyRuleValueSet>
         </conditions>
-        <conjunctionExpression>1</conjunctionExpression>
+        <conjunctionExpression>(AND 1)</conjunctionExpression>
     </whenPolicyRuleDefinitionClauseConjunction>
 </PolicyRuleDefinition>
 ```

package/skills/platform-policy-rule-generate/references/templates-advanced.md

@@ -1,10 +1,12 @@
-# Advanced Templates — Multi-Condition, Hierarchy, Unauthorable
+# Advanced Templates — API-only Multi-Condition, Hierarchy, Unauthorable
 
 Each template is a verified shape from a passing test fixture. Copy, then change names/values.
 
 ---
 
-## Multi-Condition with Custom Conjunction (AND/OR mix)
+> These examples are API-only exceptions. Do not copy them for the default UI-compatible output without explicit operator confirmation.
+
+## API-only Multi-Condition with Custom Conjunction (AND/OR mix)
 
 Source: `conjunctionExpressionSteelthread`
 

package/skills/platform-policy-rule-generate/references/templates-record.md

@@ -1,14 +1,16 @@
 # RECORD Templates
 
-Each template is a verified shape from a passing test fixture. Copy, then change names/values.
+These examples are distilled from retrieved policies. Use them to understand persisted structure, but generate only values published by the target release's MDAPI contract.
 
 ---
 
 ## RECORD — Basic RLS (record field = user attribute)
 
-Source: `conditionRLSValidSteelthread` (first condition), `conditionStandardIdRLSValidSteelthread`
+Source: `references/examples/PrincipalFieldMatchRLS/`
 
-> **RLS MDAPI round-trip is fragile in real orgs.** Deploy/retrieve can fail with opaque gacks if a DMO field in `<valueDomain>` is not mapped in the org's data streams. Build the rule in the UI first; use MDAPI templates as verification shapes, not first-try authoring. See §8.3 of policy.md.
+> **RLS MDAPI round-trip is fragile in real orgs.** Deploy/retrieve can fail with opaque gacks if a DMO field in `<valueDomain>` is not mapped in the org's data streams. Use read-only metadata inspection to verify the field mapping before generating XML; do not create or edit the rule in Policy Builder from this skill.
+
+> `SCALAR_ATTRIBUTE` is a confirmed, deployable, Policy Builder-compatible principal path for record-field-to-principal-attribute comparisons, per DG UI source (this is how the builder itself authors the condition, not established by a per-shape round-trip). Use this template directly in normal author mode.
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
@@ -16,10 +18,10 @@ Source: `conditionRLSValidSteelthread` (first condition), `conditionStandardIdRL
     <action>Read</action>
     <category>RECORD_POLICY_RULE_DEFINITION</category>
     <effect>Permit</effect>
-    <label>Rule1</label>
-    <policyRuleDefinitionSetName>StandardFieldSet3</policyRuleDefinitionSetName>
+    <label>Rule 1</label>
+    <policyRuleDefinitionSetName>EXACT_SET_NAME</policyRuleDefinitionSetName>
     <policyRuleResourceDomains>
-        <resourceDomain>testDMO__dlm</resourceDomain>
+        <resourceDomain>EXACT_DMO</resourceDomain>
     </policyRuleResourceDomains>
     <principalAuthenticationLevel>INTERNAL</principalAuthenticationLevel>
     <principalScopeType>ANY</principalScopeType>
@@ -30,46 +32,59 @@ Source: `conditionRLSValidSteelthread` (first condition), `conditionStandardIdRL
         <conditions>
             <clause>WHEN</clause>
             <operator>EQUALS</operator>
+            <principalExpression>
+                <soqlTarget>
+                    <select>EXACT_USER_FIELD</select>
+                </soqlTarget>
+                <type>SOQLTARGETLISTEXPR</type>
+                <version>1</version>
+            </principalExpression>
             <resourcePath>RECORDFIELD</resourcePath>
-            <valueDomain>testDMO__dlm:name__c</valueDomain>
-            <valuePrincipalPath>USER_ID</valuePrincipalPath>
+            <valueDomain>EXACT_DMO:EXACT_FIELD</valueDomain>
+            <valuePrincipalPath>SCALAR_ATTRIBUTE</valuePrincipalPath>
         </conditions>
-        <conjunctionExpression>1</conjunctionExpression>
+        <conjunctionExpression>(AND 1)</conjunctionExpression>
     </whenPolicyRuleDefinitionClauseConjunction>
 </PolicyRuleDefinition>
 ```
 
-For literal-value RLS (e.g. `record.field == 'X'`), use `<policyRuleValueSet><valueString>X</valueString></policyRuleValueSet>` instead of `<valuePrincipalPath>`.
-
----
-
 ## RECORD — RLS via PROJECTION Join
 
-Source: `conditionRLSValidSteelthread` (second condition)
+Source: `references/examples/ExistsJoinRLS/`
 
 ```xml
 <conditions>
     <clause>WHEN</clause>
     <operator>EXISTS</operator>
-    <resourcePath>EXPRESSION</resourcePath>
+    <policyRuleDefinitionCondition>
+        <clause>WHEN</clause>
+        <operator>EQUALS</operator>
+        <policyRuleValueSet>
+            <valueText>${User.Email}</valueText>
+        </policyRuleValueSet>
+        <resourcePath>RECORDFIELD</resourcePath>
+        <valueDomain>RESOURCE_DMO:RESOURCE_FIELD</valueDomain>
+    </policyRuleDefinitionCondition>
     <resourceExpression>
-        <type>PROJECTION</type>
-        <version>1</version>
         <projection>
             <join>
-                <schema>testDMO__dlm</schema>
-                <alias>test 1</alias>
+                <alias>JOIN_ALIAS</alias>
                 <predicate>
+                    <attribute>JOIN_DMO:JOIN_FIELD</attribute>
                     <comparator>EQUALS</comparator>
-                    <attribute>testDMO__dlm:name__c</attribute>
                     <on>
+                        <field>RESOURCE_FIELD</field>
                         <resourceAlias>resource</resourceAlias>
-                        <schema>testDMO__dlm</schema>
-                        <field>age__c</field>
+                        <schema>RESOURCE_DMO</schema>
                     </on>
                 </predicate>
+                <schema>JOIN_DMO</schema>
             </join>
         </projection>
+        <type>PROJECTION</type>
+        <version>1</version>
     </resourceExpression>
+    <resourcePath>EXPRESSION</resourcePath>
+    <whereClauseConjunction>1</whereClauseConjunction>
 </conditions>
 ```

package/skills/platform-policy-rule-generate/references/templates-transform.md

@@ -1,6 +1,6 @@
 # TRANSFORM Templates
 
-Each template is a verified shape from a passing test fixture. Copy, then change names/values.
+The `LAST_N_CHARS_RESOURCE_TRANSFORM` shape is MDAPI persistence-validated in `references/examples/LastCharactersFieldMasking/`. Other transforms in this file are older fixture-only references.
 
 ---
 
@@ -28,7 +28,7 @@ Source: `conditionClassificationValidDataMaskingSteelthread`
             <operator>IS</operator>
             <resourcePath>ENTITYTYPE</resourcePath>
             <policyRuleValueSet>
-                <valueString>{&quot;t&quot;:&quot;Text&quot;,&quot;v&quot;:&quot;FIELD&quot;}</valueString>
+                <valueText>FIELD</valueText>
             </policyRuleValueSet>
         </conditions>
         <conditions>
@@ -54,17 +54,19 @@ Source: `conditionClassificationValidDataMaskingSteelthread`
 </PolicyRuleDefinition>
 ```
 
-For parameterized masking (e.g. mask all but first 4 chars):
+Validated `LAST_N_CHARS_RESOURCE_TRANSFORM` argument shape:
 ```xml
-<resourceTransform>ALL_BUT_FIRST_N_CHARS_RESOURCE_TRANSFORM</resourceTransform>
 <resourceExpression>
-    <type>ARGLIST</type>
-    <version>1</version>
     <transformExpression>
         <argument>
-            <type>NUMBER</type>
-            <value>4</value>
+            <type>STRING</type>
+            <value>12</value>
         </argument>
     </transformExpression>
+    <type>ARGLIST</type>
+    <version>1</version>
 </resourceExpression>
+<resourceTransform>LAST_N_CHARS_RESOURCE_TRANSFORM</resourceTransform>
 ```
+
+Do not infer argument type or count for another transform.

package/skills/platform-policy-rule-generate/references/templates.md

@@ -1,10 +1,10 @@
 # Policy Templates — Index
 
-Each template is a verified shape from a passing test fixture. Pick the file matching the category you need.
+Evidence levels differ by file. Prefer API 69.0 retrieved examples for OLS, FLS deny, masking, and RLS; treat remaining templates as fixture-only references that require target-org validation.
 
 | File | What's inside |
 |------|---------------|
 | [`templates-access.md`](templates-access.md) | ACCESS and GOVERNANCE: simple Permit, TupleRead "objects + all fields", tag/classification/permission gates |
 | [`templates-record.md`](templates-record.md) | RECORD: basic RLS (record field = user attribute), RLS via PROJECTION join |
-| [`templates-transform.md`](templates-transform.md) | TRANSFORM: field masking with permission + classification gates, parameterized masking (ARGLIST) |
+| [`templates-transform.md`](templates-transform.md) | TRANSFORM: field masking gates and validated `LAST_N_CHARS` ARGLIST shape |
 | [`templates-advanced.md`](templates-advanced.md) | Multi-condition with custom conjunction (AND/OR mix), hierarchy traversal, IDENTIFIED_RECORD (not authorable via MDAPI) |

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

@@ -1,8 +1,12 @@
 # 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.
+The Data Governance Policy Builder edits a **strict subset** of the MDAPI. Anything outside that subset must be maintained through the MDAPI package path 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.
+> **Default goal**: produce policies that can eventually be validated in Policy Builder. `<builderCompatible>` and `<builderValidated>` are both server-managed fields — the server sets them on save/create, authoring either one in generated XML has no effect, and authoring `true` is never legitimate regardless of how many items on this checklist a shape satisfies. Omit both. Only an actual Policy Builder open/save/retrieve comparison can establish UI compatibility for a specific shape.
+
+> **Evidence boundary:** MDAPI dry-run, deploy, and retrieve prove metadata validity and persistence. They do not prove that Policy Builder can open and save the policy without normalization or loss. A retrieved set with `<builderCompatible>false</builderCompatible>` is persisted-shape evidence only.
+
+> **ACCESS distinction:** An OR-of-ENTITYTYPE discriminator prevents the builder crash for object-level ACCESS-shaped rules, but ACCESS categories still do not round-trip as ACCESS; the builder rewrites them to GOVERNANCE. Treat explicitly requested ACCESS output as API-only and record that status in the description or an XML comment, not in compatibility fields.
 
 ---
 
@@ -31,7 +35,7 @@ The Data Governance Policy Builder edits a **strict subset** of the MDAPI. Anyth
 
 **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.
+**Conjunction expression**: the UI builds one top-level `(AND …)` from typed sections dispatched by path type. Conditions are not combined as one undifferentiated list. Put all conditions for the same UI section into that section's local group, then combine the non-empty section groups under the top-level `AND`. 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:**
 
@@ -45,6 +49,16 @@ The Data Governance Policy Builder edits a **strict subset** of the MDAPI. Anyth
 
 Any other path type → condition silently ignored when UI rebuilds the rule.
 
+**Required grouping examples**:
+
+- Two classifications that are alternatives belong in one Tag / Classification group: `(OR 1 2)`.
+- A permission condition belongs in the Users / Permission group: `(AND 3)`.
+- The complete policy expression combines those section groups: `(AND (OR 1 2) (AND 3))`.
+- If the policy also has object/field entity discriminators, add a separate Entity Type group, for example `(AND (OR 1 2) (AND 3) (OR 4 5))`.
+- A record-field or join condition belongs in the RLS rule criteria group; it must not be placed directly beside a classification condition at the top level.
+
+The exact condition numbers depend on final document order. The invariant is section-local grouping followed by a top-level `AND`, not the example numbers.
+
 **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)
@@ -68,33 +82,36 @@ When the UI saves, it auto-injects these — if your hand-authored XML omits the
 | `actions` | only first action kept |
 | `policyRuleResourceDomains` | only first `<resourceDomain>` kept |
 
+`policyRuleResourceDomains` scopes a **RECORD (RLS)** rule to the named object; it does **not** confine a `GOVERNANCE` (OLS) rule, whose entity-type conditions match every object, and it is **not** a condition — every renderable rule still needs at least one resource `<conditions>`. To scope read access to one named object, author RLS with a row criterion — see `policy-shapes.md` shape-selection.
+
 ---
 
 ## 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:
 
+- [ ] **No resource-side condition present** — zero `<conditions>`, or only principal conditions (`ASSIGNED_PERMISSIONS_PATH` / `SCALAR_ATTRIBUTE`) and no resource condition (`ENTITYTYPE` / `TAG` / `CLASSIFICATION` / `RECORDFIELD` / `EXPRESSION` / `DATASPACE`). Every renderable rule needs ≥1 resource condition; `policyRuleResourceDomains` does not count. Not deployable/renderable — see `policy-shapes.md`.
 - [ ] `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.
+- [ ] **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. OLS uses an `(OR OBJECT FIELD)` group; FLS uses `FIELD` only. A `TupleRead` OLS rule without its OR group 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)
+- [ ] `<principalPath>` other than `ASSIGNED_PERMISSIONS_PATH` or `SCALAR_ATTRIBUTE` (paired with a `SOQLTARGETLISTEXPR` `principalExpression`) — other values such as raw user ID 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
+- [ ] Entity-type conditions do not use the MDAPI-authorable `<valueText>OBJECT</valueText>` / `<valueText>FIELD</valueText>` form, or the persisted UI JSON representation is assumed to be authorable without a target-org dry-run
 - [ ] `<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**.
+If none of the above is true, the policy is a candidate for UI validation. It is not proven UI-compatible until Policy Builder opens and saves it and a subsequent MDAPI retrieval shows no semantic loss.
 
 > **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.
 
@@ -112,16 +129,16 @@ Whenever a request would produce a UI-incompatible policy:
  | `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
+ - Multiple `<action>` → reject the request or generate separate one-rule policy sets; one policy set in this skill contains exactly one rule
 
 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
+   - That maintenance must happen through the MDAPI package path 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.
+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>`. Do not author server-managed compatibility fields on the parent set.
 
 ---
 
@@ -130,13 +147,14 @@ Whenever a request would produce a UI-incompatible policy:
 | 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. |
+| GOVERNANCE / RECORD / TRANSFORM tag, classification, or permission gate | Candidate; requires Policy Builder validation | `CONTAINS_ANY` / `CONTAINS_NONE` only. Tag refs must resolve in org. Explicit ACCESS-category variants are API-only because the builder rewrites ACCESS to GOVERNANCE. |
+| Basic RLS (RECORDFIELD = user attribute) | UI-compatible (per DG UI source) | `SCALAR_ATTRIBUTE` is confirmed deployable; UI-compatible per DG UI source (this is how the builder itself authors the condition), not by a per-shape round-trip. |
+| TupleRead with OR-of-ENTITYTYPE | Candidate; requires Policy Builder validation | Persistence-validated 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) | |
+| RLS via PROJECTION join | Requires UI validation | API 69.0 MDAPI persistence is validated for one `EXISTS`/PROJECTION shape; Policy Builder open/save is not. |
+| Scalar SOQL principal | UI-compatible (per DG UI source) | `SCALAR_ATTRIBUTE`/`SOQLTARGETLISTEXPR` is confirmed deployable; UI-compatible per DG UI source (this is how the builder itself authors the condition), not by a per-shape round-trip. |
+| Plural SOQL principal | Unvalidated | No retrieved and round-trip-tested example is included. |
+| TRANSFORM with permission + classification | Candidate; requires Policy Builder validation | Use masking-category-mapped transforms only. |
+| `(AND 1 2)` multi-condition | Candidate; requires Policy Builder validation | Each section must use a supported UI bucket. |
 | 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-report-generate/SKILL.md

@@ -21,10 +21,14 @@ Lightning Reports define how Salesforce data is queried, grouped, filtered, and
 
 **TOP DEPLOYMENT KILLERS — check these BEFORE generating any report:**
 1. **Grouping fields in columns** — Fields in `<groupingsDown>` or `<groupingsAcross>` must NEVER also appear in `<columns>`
-2. **Wrong column names** — Column names are report-type-specific. ALWAYS call MCP tools to verify (see `references/column-names.md`)
+2. **Wrong column names (REQUIRED lookup)** — Before writing any `<columns>`, `<groupingsDown>`, `<groupingsAcross>`, filter `<column>`, or chart `<groupingColumn>`, take every name from the table for the chosen `<reportType>` in `references/column-names.md`, or confirm it with `get_metadata_type_sections`. NEVER derive a column name from the field's API name: `CASENUMBER`, `ISCLOSED`, `PHONE`, `MAILING_CITY` all fail (use `CASE_NUMBER`, a `STATUS` filter, `PHONE1`, `ADDRESS2_CITY`)
 3. **Wrong scope** — LeadList uses `org`, not `organization`
 4. **Filter column dot notation** — Filter `<column>` values use FLAT names (`INDUSTRY`, `TYPE`) NOT dot notation (`ACCOUNT.INDUSTRY` is INVALID)
 5. **Multi-value picklist filters** — Use ONE `<criteriaItems>` with comma-separated `<value>` (e.g., `Technology,Financial Services`). Do NOT split into multiple criteriaItems with booleanFilter
+6. **Report `<name>` over 40 characters** — Count the characters before writing. `Opportunities by Stage with Avg Deal Size` (41 characters) fails with `Value too long for field: Name maximum length is:40`; use something like `Opps by Stage - Avg Deal Size`
+7. **Bare `NAME` / `USERS.NAME`** — Never use a bare `NAME` or `USERS.NAME` in columns or groupings; they are invalid on every standard report type. Look up the name column for the report type in `references/column-names.md` (e.g. `OPPORTUNITY_NAME`, `FULL_NAME` for the opportunity owner, `OWNER` for Case/Lead owner, `FIRST_NAME` + `LAST_NAME`)
+8. **Unrequested or invalid `<params>`** — Do NOT add `<params>` the request didn't ask for. On Opportunity reports the only accepted `probability` value is `>0` (`0`, `all`, `>50` fail with `is not one of the picklist choices`); for a probability threshold, filter on `PROBABILITY` instead
+9. **`RowCount` as a column** — `RowCount` is NOT a report column: `<columns><field>RowCount</field></columns>` fails with `columns-field: Invalid value specified: RowCount`. It is valid ONLY as `<chartSummaries><column>RowCount</column>`, as a `<sortByName>` value, or inside a custom summary formula's `<calculatedFormula>` (e.g. `AMOUNT:SUM / RowCount`). When the request asks for a record count, a Summary/Matrix report already shows the count per grouping — add no column; chart it with `RowCount` in `<chartSummaries>` if a chart is requested
 
 ### Rule 1: Format Determines Required Elements
 
@@ -41,11 +45,11 @@ Report metadata uses **platform report column names**, NOT raw API field names.
 
 ### Rule 3: Valid Report Type Required
 
-`<reportType>` must be a standard API name (e.g., `Opportunity`, `AccountList`, `CaseList`, `LeadList`, `AccountContactRole`) or a deployed custom report type developer name.
+`<reportType>` must be a standard API name (e.g., `Opportunity`, `AccountList`, `CaseList`, `LeadList`, `AccountContactRole` for "Accounts with Contacts" — there is no `AccountContact`; see the label → API name table in `references/column-names.md`) or a deployed custom report type developer name **with a `__c` suffix** (`Accounts_with_Projects.reportType-meta.xml` → `<reportType>Accounts_with_Projects__c</reportType>`; without the suffix the deploy fails with `invalid report type`). Custom report type columns use `$` paths, not platform names: `Account$Name` for the base object, `Account.Projects__r$Budget_Amount__c` for a joined object. See the Custom Report Types section in `references/column-names.md`.
 
 ### Rule 4–5: Chart & Aggregates Require Summary/Matrix
 
-Charts and `<aggregateTypes>` (Sum, Average, etc.) only work in Summary and Matrix reports.
+Charts and `<aggregateTypes>` (Sum, Average, etc.) only work in Summary and Matrix reports. Use only the `<chart>` child elements listed in `references/chart-types.md` — invented elements such as `<summaryAxisManualRangeEnabled>` or `<showInlineChart>` fail parsing. Use `<legendPosition>` ONLY on grouped/stacked chart types (`Right` or `Bottom`) or on `Pie`, `Donut`, `Funnel`, `Scatter`; on a single-series `HorizontalBar`, `VerticalColumn`, `Line`, or `LineCumulative` any value fails with `chart-legendPosition: Invalid value specified: Right` — omit it. A record-count chart summary is `<chartSummaries><column>RowCount</column></chartSummaries>` with NO `<aggregate>` (`Sum`/`Count` with `RowCount` fails).
 
 ### Rule 6–8: Limits
 
@@ -71,6 +75,7 @@ Determine `<sourceDir>` from `sfdx-project.json` (commonly `force-app/main/defau
 
 - `<description>` max **255 characters**
 - Grouping fields must NOT appear in `<columns>` — automatic deployment failure
+- Each `<columns>` element holds exactly ONE `<field>` — repeat `<columns>` per field (multiple `<field>`s fail with `Element field is duplicated`)
 
 ### Rule 14: Folder Metadata Requires `<sharedTo>`
 
@@ -139,7 +144,7 @@ Common operators: `equals`, `notEqual`, `lessThan`, `greaterThan`, `contains`, `
 
 1. **Gather Requirements** — object, fields, groupings, filters, chart needs
 2. **Determine Format** — no groupings → Tabular; row groupings → Summary; row + column → Matrix; multiple objects → Joined
-3. **Identify Column Names** — call `get_metadata_type_sections` MCP tool to get valid platform column names for the report type
+3. **Look Up Every Column Name (required)** — list every field the report needs, then take each name from the `references/column-names.md` table for the chosen `<reportType>` or confirm it with `get_metadata_type_sections`. Do not write XML until every column, grouping, filter column, and chart grouping column is looked up
 4. **Author Metadata** — start from closest example in `examples/` and adapt
 5. **Create Folder** — generate folder directory + `<FolderName>-meta.xml` with `<folderShares>`
 6. **Validate** — run through `references/verification-checklist.md`

package/skills/platform-report-generate/references/chart-types.md

@@ -26,6 +26,30 @@ Charts can only be added to Summary or Matrix reports. A Tabular report with a `
 
 ## legendPosition
 
-Only use `legendPosition` with grouped/stacked chart types (e.g., `VerticalColumnGrouped`, `HorizontalBarStacked`). Do NOT include it for simple single-series charts like `VerticalColumn`, `HorizontalBar`, `Pie`, `Donut`.
+`legendPosition` is only accepted on some chart types. On the others, ANY value fails with `chart-legendPosition: Invalid value specified: Right` — omit the element.
 
-Valid values: `Right`, `Bottom`, `OnChart`
+| Chart types | Accepted `legendPosition` |
+|-------------|---------------------------|
+| Single-series `HorizontalBar`, `VerticalColumn`, `Line`, `LineCumulative` | None — omit it |
+| Grouped/stacked (`VerticalColumnGrouped`, `HorizontalBarStacked`, …) | `Right`, `Bottom` (`OnChart` fails) |
+| `Pie`, `Donut`, `Funnel`, `Scatter` | `Right`, `Bottom`, `OnChart` |
+
+## Allowed `<chart>` Child Elements
+
+Use only these elements inside `<chart>`. Anything else (e.g. `<summaryAxisManualRangeEnabled>`, `<showInlineChart>`) fails with `Element ... invalid at this location in type ReportChart`.
+
+`backgroundColor1`, `backgroundColor2`, `backgroundFadeDir`, `chartSummaries` (`aggregate`, `axisBinding`, `column`), `chartType`, `enableHoverLabels`, `expandOthers`, `groupingColumn`, `legendPosition`, `location`, `secondaryGroupingColumn`, `showAxisLabels`, `showPercentage`, `showTotal`, `showValues`, `size`, `summaryAxisRange` (`Auto` or `Manual`), `textColor`, `textSize`, `title`, `titleColor`, `titleSize`.
+
+A minimal chart needs only `chartType`, `groupingColumn`, `chartSummaries`, and `location`.
+
+## Record Count Charts
+
+To chart a record count, `<chartSummaries>` holds ONLY `<column>RowCount</column>` — no `<aggregate>`. `Sum` with `RowCount` fails with `aggregate type cannot be specified with RowCount summary`, and `Count` is not a valid aggregate at all.
+
+```xml
+<chartSummaries>
+    <column>RowCount</column>
+</chartSummaries>
+```
+
+For any other column, `<aggregate>` is required and must be `Sum`, `Average`, `Maximum`, or `Minimum`.

package/skills/platform-report-generate/references/column-names.md

@@ -2,6 +2,20 @@
 
 Report metadata uses **platform report column names**, NOT raw API field names. These names are report-type-specific — ALWAYS verify using MCP tools (`get_metadata_type_sections` or `get_metadata_type_context`).
 
+## Standard Report Type API Names
+
+Use the API name, never a name guessed from the UI label. There is NO `AccountContact` report type.
+
+| UI label | `<reportType>` |
+|----------|----------------|
+| Accounts | `AccountList` |
+| Accounts with Contacts / Accounts with Contact Roles | `AccountContactRole` |
+| Contacts & Accounts | `ContactList` |
+| Opportunities | `Opportunity` |
+| Opportunities with Products | `OpportunityProduct` |
+| Cases | `CaseList` |
+| Leads | `LeadList` |
+
 ## Opportunity
 
 | Object.Field | Report Column Name |
@@ -69,6 +83,19 @@ Filter `<column>` values use plain names for Account fields — NOT dot notation
 
 ## Common Mistakes
 
+- `RowCount` in `<columns><field>` → NEVER valid (fails with `columns-field: Invalid value specified: RowCount`). `RowCount` is valid only in `<chartSummaries><column>`, as a `<sortByName>` value, or inside a `<calculatedFormula>`; a Summary/Matrix report shows the record count per grouping without any column
+- Bare `NAME` or `USERS.NAME` → NEVER valid on any standard report type (fails with `columns-field: Invalid value specified: NAME` / `Grouping: Invalid value specified: USERS.NAME`). Pick the name column for the report type from the tables above:
+  - Opportunity name → `OPPORTUNITY_NAME`; opportunity owner → `FULL_NAME`; account → `ACCOUNT_NAME`
+  - Case or Lead owner → `OWNER`
+  - Lead or contact person → `FIRST_NAME` + `LAST_NAME`
+  - Account (AccountList) → `ACCOUNT_NAME`; account on AccountContactRole → `ACCOUNT.NAME`
+- `USERS.NAME` as the owner → `OWNER` (CaseList, LeadList) or `FULL_NAME` (Opportunity)
+- `CASENUMBER` → `CASE_NUMBER` (CaseList)
+- `ISCLOSED` filter → NOT a valid filter column; to exclude closed cases filter `STATUS` `notEqual` `Closed`
+- `PHONE` → `PHONE1` (AccountContactRole)
+- `MAILING_CITY` → `ADDRESS2_CITY` (AccountContactRole)
+- `FULL_NAME`, `ACCOUNT_NAME` on AccountContactRole → `FIRST_NAME` + `LAST_NAME`, `ACCOUNT.NAME`
+- Never derive a column from the field API name (`CaseNumber` → `CASENUMBER`, `IsClosed` → `ISCLOSED`); take it from the table for the report type
 - `OWNER_FULL_NAME` → Use `FULL_NAME` (Opportunity) or `OWNER` (Case/Lead)
 - `OWNER_NAME` → Use `OWNER` (CaseList) or `FULL_NAME` (Opportunity)
 - `CONTACT_NAME` → Verify per report type; some use `FIRST_NAME` + `LAST_NAME`
@@ -78,3 +105,19 @@ Filter `<column>` values use plain names for Account fields — NOT dot notation
 ## Custom Fields
 
 Custom fields use the format `<ObjectApiName>.<FieldApiName__c>` (e.g., `Opportunity.Custom_Field__c`).
+
+## Custom Report Types
+
+A report built on a custom report type (`reportTypes/<Name>.reportType-meta.xml`) follows different naming than standard report types:
+
+- `<reportType>` is the developer name **plus `__c`**: `Accounts_with_Projects__c`.
+- Every column, grouping, filter, chart, and time-frame column is a `$` path built from the report type's section `<table>` and `<field>`: `<table>$<field>`.
+- Only fields listed in the report type's `<sections>` are valid. Do not add a `<timeFrameFilter>` on a date field (e.g. `CreatedDate`) the layout does not include.
+
+For a report type with `<baseObject>Account</baseObject>` joined through `<relationship>Projects__r</relationship>`:
+
+| Section `<table>` | Section `<field>` | Report column |
+|-------------------|-------------------|---------------|
+| `Account` | `Name` | `Account$Name` (NOT `ACCOUNT_NAME`) |
+| `Account.Projects__r` | `Name` | `Account.Projects__r$Name` (NOT `Project__c.Name`) |
+| `Account.Projects__r` | `Budget_Amount__c` | `Account.Projects__r$Budget_Amount__c` |

package/skills/platform-report-generate/references/errors-and-troubleshooting.md

@@ -61,7 +61,7 @@ The `<summaryColumn>` in a chart uses a special syntax for aggregate references:
 - `a!AMOUNT` — Average of Amount
 - `m!AMOUNT` — Max of Amount
 - `x!AMOUNT` — Min of Amount
-- `RowCount` — Record count
+- `RowCount` — Record count (valid only here, in `<sortByName>`, and in a `<calculatedFormula>`; never as a `<columns><field>`)
 
 ### Pitfall 5: Joined Report Restrictions