@salesforce/afv-skills 1.29.0 → 1.30.0

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

@@ -7,7 +7,7 @@ This document details how platform-metadata-deploy fits into the multi-skill wor
 
 ## Standard Orchestration Order
 
-```
+```text
 ┌─────────────────────────────────────────────────────────────────────────────┐
 │  STANDARD MULTI-SKILL ORCHESTRATION ORDER                                   │
 ├─────────────────────────────────────────────────────────────────────────────┤
@@ -45,7 +45,7 @@ platform-metadata-deploy is the **bridge** between local files and the org:
 
 When deploying multiple metadata types:
 
-```
+```text
 ┌─────────────────────────────────────────────────────────────────────────────┐
 │  INTERNAL DEPLOY ORDER                                                      │
 ├─────────────────────────────────────────────────────────────────────────────┤
@@ -78,7 +78,7 @@ When deploying multiple metadata types:
 
 When deploying agents with external API integrations:
 
-```
+```text
 ┌─────────────────────────────────────────────────────────────────────────────┐
 │  AGENTFORCE DEPLOYMENT ORDER                                                │
 ├─────────────────────────────────────────────────────────────────────────────┤

package/skills/platform-metadata-deploy/references/trigger-deployment-safety.md

@@ -13,7 +13,7 @@ This guide covers deployment considerations for triggers, focusing on cascade fa
 
 When an exception in one trigger causes rollback of operations from preceding triggers in the chain.
 
-```
+```text
 Account Insert → AccountTrigger → ContactTrigger → OpportunityTrigger
                      ✓               ✓                 ✗ (Exception)
 
@@ -230,7 +230,7 @@ trigger AccountChangedSubscriber on Account_Changed__e (after insert) {
 
 Before deploying triggers, analyze the cascade impact:
 
-```
+```text
 CHECKLIST:
 □ List all triggers that fire on the same transaction
 □ Identify which operations are atomic (same business process)

package/skills/platform-models-api-configure/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: platform-models-api-configure
+description: "Configure (or troubleshoot) an AI coding agent or CLI to route through the Salesforce Models API using a signed OrgJWT. Use this skill when pointing an agent at the Salesforce model endpoint (api.salesforce.com/ai/gpt/v1), setting up OrgJWT / Bedrock-mode auth, wiring the agent's settings, API-key helper, and credentials file for the Salesforce endpoint, or fixing Models API 401 / 404 / \"model not available\" errors. DO NOT TRIGGER when the user needs to create or configure the Salesforce Connected App itself (use integration-connectivity-connected-app-configure) or set up Named Credentials / callout auth (use integration-connectivity-generate)."
+metadata:
+  version: "1.0"
+---
+
+# Salesforce Models API setup for an AI coding agent
+
+The Salesforce Models API (`https://api.salesforce.com/ai/gpt/v1`) is
+authenticated with a signed **OrgJWT** (obtained via `client_credentials` with
+the `sfap_api` scope — see `scripts/get-orgjwt.sh`; no proxy). That auth and the
+base URL are the same for **any** agent. How each agent then talks to the
+endpoint is agent-specific: Anthropic clients (**Claude Code** and the **Claude
+Agent SDK**) route through **Bedrock mode** (the env vars in Step 3), whereas
+other agents (e.g. Codex) use their own client config against the same endpoint
+and token — Bedrock mode does **not** apply to them.
+
+The steps below are the **Claude Code / Claude Agent SDK reference
+implementation** (Bedrock mode + a JSON settings file + an API-key helper). For
+a non-Bedrock agent, reuse the OrgJWT auth (Step 1) and the base URL, and apply
+the equivalent client settings in that agent's own config location instead of
+the Bedrock env vars.
+
+Bundled scripts are in `scripts/`. Path placeholders below: `<SKILL>` = the
+absolute path to **this skill's own directory** (the folder containing this
+`SKILL.md`; resolve it from the skill path in context). `<ABS>` = the absolute
+path to the user's project root. Always emit fully resolved absolute paths —
+the API-key helper runs from an undefined working directory, so relative paths
+break it.
+
+## Prerequisite
+
+A connected app in the org with the **`sfap_api`** OAuth scope and the
+**client_credentials** flow enabled (consumer key/secret + a run-as user).
+Setup steps: https://developer.salesforce.com/docs/ai/agentforce/guide/access-models-api-with-rest.html
+`curl` + `jq` installed.
+
+## Inputs to collect
+
+- `SF_INSTANCE_URL` — org My Domain, e.g. `https://acme.my.salesforce.com`
+- `SF_CLIENT_ID`, `SF_CLIENT_SECRET` — connected-app consumer key/secret
+- Models API base URL: `https://api.salesforce.com/ai/gpt/v1`
+- Model: a fully qualified `sfdc_ai__…` name, e.g.
+  `sfdc_ai__DefaultBedrockAnthropicClaude46Sonnet`
+  (full list: https://developer.salesforce.com/docs/ai/agentforce/guide/supported-models.html)
+- Scope: project (`<cwd>/.claude/settings.json`, default) or user (`~/.claude/settings.json`) — reference-agent settings paths
+- Headers — `<FEAT>` = `x-client-feature-id` (default `ai-platform-models-connected-app`),
+  `<APP>` = `x-sfdc-app-context` (default `EinsteinGPT`). Used in the Step 2 verify curl
+  and in `ANTHROPIC_CUSTOM_HEADERS`.
+
+## Steps (reference implementation)
+
+Concrete values for a JSON-settings + API-key-helper agent. Reuse the OrgJWT
+auth, verify curl, and base URL verbatim for any agent; adapt the settings-file
+location and env-var wiring to the target agent.
+
+1. Write `<project>/.claude/.orgjwt.env` (chmod 600), gitignore it:
+   ```ini
+   SF_INSTANCE_URL="..."
+   SF_CLIENT_ID="..."
+   SF_CLIENT_SECRET="..."
+   ```
+2. Verify — must return `200` before writing settings:
+   ```bash
+   TOKEN=$(bash <SKILL>/scripts/get-orgjwt.sh <ABS>/.claude/.orgjwt.env)
+   curl -s -o /dev/null -w '%{http_code}\n' \
+     <MODELS_API_URL>/model/<MODEL>/invoke-with-response-stream \
+     -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
+     -H 'x-client-feature-id: <FEAT>' -H 'x-sfdc-app-context: <APP>' \
+     --data '{"anthropic_version":"bedrock-2023-05-31","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}'
+   ```
+3. Write `.claude/settings.json` (merge into existing; keep other keys):
+   ```json
+   {
+     "apiKeyHelper": "bash <SKILL>/scripts/get-orgjwt.sh <ABS>/.claude/.orgjwt.env",
+     "model": "<MODEL>",
+     "env": {
+       "ANTHROPIC_AUTH_TOKEN": "",
+       "CLAUDE_CODE_USE_BEDROCK": "1",
+       "CLAUDE_CODE_SKIP_BEDROCK_AUTH": "1",
+       "ANTHROPIC_BEDROCK_BASE_URL": "<MODELS_API_URL>",
+       "ANTHROPIC_SMALL_FAST_MODEL": "<MODEL>",
+       "ANTHROPIC_DEFAULT_MODEL": "<MODEL>",
+       "ANTHROPIC_CUSTOM_HEADERS": "x-client-feature-id: <FEAT>\nx-sfdc-app-context: <APP>"
+     }
+   }
+   ```
+   Use absolute paths in `apiKeyHelper`. (`<FEAT>` / `<APP>` defaults are in
+   "Inputs to collect" above.)
+4. Tell the admin to fully restart the agent (`claude` for the reference agent) —
+   settings and the API-key helper load at startup only.
+
+### Capturing as a runbook (when asked to document, not apply)
+
+If the user wants the setup written up for review instead of applied to their
+machine (e.g. "save it as a Markdown runbook"), write **all** of the above into
+the requested file (e.g. `models-api-setup-runbook.md`), in order and self-contained:
+the exact `.orgjwt.env` contents, the `chmod 600` + gitignore note, the
+verification curl (with the "must be `200` before writing settings" note), the
+full `settings.json` block with every key from Step 3, and the final
+"fully restart `claude`" step. Don't omit any of the nine `settings.json` keys.
+
+## Verify before finishing
+
+- [ ] `.claude/.orgjwt.env` created, `chmod 600`, and gitignored
+- [ ] Verification curl returned HTTP `200` before `settings.json` was written
+- [ ] `ANTHROPIC_AUTH_TOKEN` set to `""` in `settings.json`
+- [ ] `CLAUDE_CODE_USE_BEDROCK` set to `"1"`
+- [ ] `CLAUDE_CODE_SKIP_BEDROCK_AUTH` set to `"1"`
+- [ ] `ANTHROPIC_BEDROCK_BASE_URL` is exactly `https://api.salesforce.com/ai/gpt/v1` (no trailing slash/path)
+- [ ] `model`, `ANTHROPIC_DEFAULT_MODEL`, and `ANTHROPIC_SMALL_FAST_MODEL` all use the fully qualified `sfdc_ai__…` alias
+- [ ] `ANTHROPIC_CUSTOM_HEADERS` contains `x-client-feature-id` and `x-sfdc-app-context`
+- [ ] `apiKeyHelper` uses absolute paths (`bash <SKILL>/scripts/get-orgjwt.sh <ABS>/.claude/.orgjwt.env`)
+- [ ] User told to fully restart `claude`
+
+## Must be exact (each prevents a specific failure)
+
+- `"ANTHROPIC_AUTH_TOKEN": ""` — clears any global token that would otherwise
+  outrank `apiKeyHelper` (precedence: `ANTHROPIC_AUTH_TOKEN` > `ANTHROPIC_API_KEY`
+  > `apiKeyHelper`). Without it → wrong/old bearer → 401/404.
+- `CLAUDE_CODE_USE_BEDROCK=1` — activates the Bedrock API client; without it
+  Claude Code uses the standard Anthropic API protocol and ignores
+  `ANTHROPIC_BEDROCK_BASE_URL` entirely, so every call bypasses the Models API.
+- `CLAUDE_CODE_SKIP_BEDROCK_AUTH=1` — else Claude Code overwrites `Authorization`
+  with AWS SigV4 and the OrgJWT never lands.
+- `apiKeyHelper` must be invoked as `bash <path> <credsfile>` (avoids exit-126).
+- Model must be a fully qualified `sfdc_ai__…` name (see supported models).
+- Auth is the OrgJWT from `client_credentials` (a signed JWT, 2 dots, scope
+  `sfap_api`) — NOT `sf org display` (unsigned session token → 404). `sf` CLI
+  has no client_credentials command; the helper calls `/services/oauth2/token`.
+- Only `ANTHROPIC_BEDROCK_BASE_URL` routes; no tenant-id header needed.
+
+## Diagnose
+
+| Error | Meaning | Check first |
+|-------|---------|-------------|
+| `401` | Token is not a valid OrgJWT | Connected App `sfap_api` scope, `client_credentials` flow enabled, consumer key/secret in `.orgjwt.env`; `ANTHROPIC_AUTH_TOKEN` not cleared to `""` |
+| `404` | Token valid but model/env/org not routable | Fully qualified `sfdc_ai__…` model alias, `ANTHROPIC_BEDROCK_BASE_URL` exactly `https://api.salesforce.com/ai/gpt/v1`, org entitled for the Models API, `ANTHROPIC_AUTH_TOKEN` cleared |
+| `model not available` | Non-alias model id | Replace with a fully qualified `sfdc_ai__…` alias (see supported models) |

package/skills/platform-models-api-configure/scripts/get-orgjwt.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# Mint a signed OrgJWT (sfap_api scope) via the OAuth 2.0 client_credentials
+# flow and print it to stdout. This is the value Claude Code sends as
+# `Authorization: Bearer <jwt>` to the Salesforce Models API.
+#
+# Credentials come from an env file passed as $1 (recommended — that's what the
+# generated settings.json does), or from the environment:
+#   SF_INSTANCE_URL   e.g. https://my-org.my.salesforce.com
+#   SF_CLIENT_ID      connected-app consumer key   (app needs the sfap_api scope
+#   SF_CLIENT_SECRET  connected-app consumer secret  + client_credentials enabled)
+#
+# Usage (as apiKeyHelper):  bash get-orgjwt.sh /path/to/.orgjwt.env
+set -euo pipefail
+
+command -v jq >/dev/null 2>&1 || { echo "get-orgjwt: jq is required but not found on PATH" >&2; exit 1; }
+
+CREDS="${1:-${SFGW_CREDS:-}}"
+if [ -n "$CREDS" ]; then
+  [ -f "$CREDS" ] || { echo "get-orgjwt: creds file not found: $CREDS" >&2; exit 1; }
+  # Read only the three expected KEY=VALUE assignments. We deliberately do NOT
+  # `source` the file — sourcing would execute any shell code a malformed or
+  # tampered creds file happened to contain (e.g. command substitution).
+  while IFS='=' read -r key val; do
+    case "$key" in
+      SF_INSTANCE_URL|SF_CLIENT_ID|SF_CLIENT_SECRET)
+        val="${val%\"}"; val="${val#\"}"   # strip surrounding double quotes
+        export "$key=$val" ;;
+    esac
+  done < "$CREDS"
+fi
+: "${SF_INSTANCE_URL:?set SF_INSTANCE_URL (in creds file or env)}"
+: "${SF_CLIENT_ID:?set SF_CLIENT_ID}"
+: "${SF_CLIENT_SECRET:?set SF_CLIENT_SECRET}"
+
+RESPONSE=$(curl -s --location "${SF_INSTANCE_URL%/}/services/oauth2/token" \
+  --header 'Content-Type: application/x-www-form-urlencoded' \
+  --data-urlencode "client_id=${SF_CLIENT_ID}" \
+  --data-urlencode "client_secret=${SF_CLIENT_SECRET}" \
+  --data-urlencode 'grant_type=client_credentials')
+
+TOKEN=$(printf '%s' "$RESPONSE" | jq -r '.access_token // empty')
+if [ -z "$TOKEN" ]; then
+  ERR=$(printf '%s' "$RESPONSE" | jq -r '.error_description // .error // empty' 2>/dev/null)
+  [ -n "$ERR" ] || ERR="check connected-app creds / sfap_api scope / client_credentials flow"
+  echo "get-orgjwt: token request failed — $ERR" >&2
+  exit 1
+fi
+printf '%s' "$TOKEN"

package/skills/platform-policy-rule-generate/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: platform-policy-rule-generate
+description: "Use this skill when authoring PolicyRuleDefinition and PolicyRuleDefinitionSet metadata XML for the Salesforce Enforce-O-Matic MDAPI (Data Cloud governance policies), or when editing *.policyRuleDefinition / *.policyRuleDefinitionSet files. Covers the category decision tree, full schema for all policy variants (ACCESS, GOVERNANCE, RECORD, TRANSFORM), UI-compatibility rules for the Data Governance Policy Builder, and validation guardrails. Do NOT use this skill for UserAccessPolicy, AccessPolicy, SharingRules, PermissionSet, or any non-Enforce-O-Matic access-control metadata — those have their own types and live outside the PolicyRuleDefinition schema."
+metadata:
+  version: "1.0"
+  minApiVersion: "64.0"
+  cliTools:
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+---
+
+# Authoring Policy Rule Definitions
+
+**Gating:** `@WsdlGuard("EnforceOMatic.orgCanUsePolicyRuleMDAPI")` = `OrgPermissions.EnforceOMatic && OrgPermissions.PolicyRuleMDAPI` 
+**Min API version:** 64.0 (66.0 for conditions using `PolicyJsonExpression`)
+
+> **For human maintainers (not the agent):** the Java source-of-truth lives at `enforce-o-matic-impl/java/src/enforce/o/matic/metadata/` and reference fixtures at `enforce-o-matic-impl/test/func/filemetadata/<name>/`. The agent should rely on the templates and reference docs in this skill bundle — those impl paths are not readable from the Vibes/MCP runtime.
+
+This skill covers the **on-disk metadata XML format** for authoring policies. Use it whenever a task asks to write a `*.policyRuleDefinition` or `*.policyRuleDefinitionSet` file, add a fixture under `test/func/filemetadata/`, or ship a metadata package. The runtime side (RuleProvider, hooks) is out of scope.
+
+---
+
+> **Eval coverage:** This skill is exercised by the team's ADK eval framework, not by `tests/evals/` under the skill directory. Five datasets covering the ACCESS / GOVERNANCE / RECORD / TRANSFORM variants live in `packages/adk-eval/eval/domains/platform-policy-rule-generate/datasets/`.
+
+## 1. Package Layout
+
+A deployable package always contains:
+
+```text
+<fixture>/
+  package.xml
+  policyRuleDefinitionSets/<setName>.policyRuleDefinitionSet
+  policyRuleDefinitions/<ruleName>.policyRuleDefinition
+```
+
+`package.xml` template (use `<version>[ftest]</version>` for ftests, `64.0` or higher for real orgs):
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<Package xmlns="http://soap.sforce.com/2006/04/metadata">
+    <types>
+        <members>Rule0</members>
+        <name>PolicyRuleDefinition</name>
+    </types>
+    <types>
+        <members>Set1</members>
+        <name>PolicyRuleDefinitionSet</name>
+    </types>
+    <version>64.0</version>
+</Package>
+```
+
+---
+
+## 2. PolicyRuleDefinitionSet Schema
+
+```xml
+<PolicyRuleDefinitionSet xmlns="http://soap.sforce.com/2006/04/metadata">
+    <label>Set1</label>
+    <description>Optional free text</description>
+    <replicated>false</replicated>             <!-- MinAppVersion 260 -->
+    <builderCompatible>true</builderCompatible> <!-- MinAppVersion 262, author-settable -->
+    <!-- builderValidated: server-managed — do not set in authored XML -->
+</PolicyRuleDefinitionSet>
+```
+
+| Element | Req | Notes |
+|---------|-----|-------|
+| `<label>` | yes | Master label. File basename (devName) is the MDAPI identifier, not the label. |
+| `<description>` | no | Free text. |
+| `<replicated>` | no | `true` triggers placeholder transformation across companion orgs. Omit for null/false. |
+| `<builderCompatible>` | no | `true` = rules audited per §7 checklist. `false` = API-only. Omit = unaudited. Informational only — no deploy/runtime effect. |
+| `<builderValidated>` | no | **Server-managed. Never set in authored XML.** Server overwrites on validation. |
+
+---
+
+## 3. PolicyRuleDefinition — Core Fields
+
+| Element | Req | Notes |
+|---------|-----|-------|
+| `<label>` | yes | MasterLabel. |
+| `<category>` | yes | See §4. Drives `resourceScopeType` and whether `policyRuleResourceDomains`/`resourceTransform` are required. **Does NOT constrain `effect` outside of TRANSFORM.** |
+| `<effect>` | yes | `Permit`, `Forbid`, or `Transform`. The only category-coupling enforced by core: `effect=Transform ↔ category=TRANSFORM_POLICY_RULE_DEFINITION` (bidirectional). All other categories accept Permit and Forbid freely. |
+| `<action>` | yes (≥1) | `Read`, `TupleRead`, `Create`, etc. Multiple elements OR-combine. |
+| `<policyRuleDefinitionSetName>` | yes | Developer name of parent set. |
+| `<principalScopeType>` | yes | Always `ANY`. |
+| `<resourceScopeType>` | yes | `ANY`, `FIELD`, `RECORD`, `DATASPACE`, or `SPAN`. Must match category (§4). |
+| `<principalAuthenticationLevel>` | no | `INTERNAL`, `AUTHENTICATED`, `UNIDENTIFIED`, `IDENTIFIED`. |
+| `<ruleConsumer>` | no | `ALL`, `DATACLOUD`, `MULESOFT`, `TABLEAU`, `CORE`. |
+| `<policyRuleResourceDomains>` | no | Required for RECORD (RLS) and FIELD-scope TRANSFORM rules only. Forbidden on ACCESS/GOVERNANCE. |
+| `<resourceTransform>` | no | Required (and only valid) when `category=TRANSFORM`. |
+| `<whenPolicyRuleDefinitionClauseConjunction>` | no | WHEN conditions. |
+| `<unlessPolicyRuleDefinitionClauseConjunction>` | no | UNLESS conditions. Not UI-editable — prefer WHEN + negated operator. |
+
+---
+
+## 4. Category Decision Tree
+
+**Category names a domain (where in the platform's enforcement layers the rule applies). Effect names the action (allow / deny / transform). They are independent except for TRANSFORM.**
+
+The **only** Category × Effect rule the platform validates
+(`enforce-o-matic-api/java/src/enforce/o/matic/api/module/api/RuleBuilder.java`):
+
+- `effect=Transform` ⇔ `category=TRANSFORM_POLICY_RULE_DEFINITION` (bidirectional; mismatched throws `INVALIDFORCATEGORY`).
+- All other categories (`ACCESS`, `GOVERNANCE`, `RECORD`, `IDENTIFIED_RECORD`) accept either `Permit` or `Forbid`.
+
+> **Note on the platform's auto-fill default:** When `<category>` is omitted from authored XML, the impl-side save hook (`PolicyRuleDefinitionObject.saveHook_Validate`) fills it in from `effect`: `Permit→ACCESS`, `Forbid→GOVERNANCE`, `Transform→TRANSFORM`. **This is a default-fill, not a validation.** If you author an explicit category that contradicts this default, it is accepted and persisted as-is.
+
+### Picking the category
+
+```text
+What kind of policy?
+│
+├── OLS/FLS allow/deny on tagged or classified resources
+│     category = ACCESS_POLICY_RULE_DEFINITION (allow/deny attestation in the access plane)
+│              | GOVERNANCE_POLICY_RULE_DEFINITION (governance-audited)
+│     effect = Permit | Forbid (chosen independently from category)
+│     resourceScopeType = ANY | FIELD | DATASPACE
+│     NO <policyRuleResourceDomains>
+│     condition: resourcePath=TAG|CLASSIFICATION CONTAINS_ANY <ref>
+│     For "objects AND all their fields" → action=TupleRead + OR-of-ENTITYTYPE clause (§7)
+│     Note: "Block access to Foo object" → tag Foo with <yourTag>, write rule on tag
+│        Do NOT use <resourceDomain>Foo</resourceDomain> — forbidden for ACCESS/GOVERNANCE
+│
+├── Row-level filter on a DMO/DLO
+│     category = RECORD_POLICY_RULE_DEFINITION
+│     effect = Permit | Forbid
+│     resourceScopeType = RECORD
+│     <policyRuleResourceDomains> = the DMO/DLO API name  ← entity targeting allowed here
+│
+├── Identified-Guest record access
+│     NOT authorable via MDAPI — SESSION_CONSUMER_ID is not in RuleContextPathType
+│        Must be implemented as a runtime RuleProvider.
+│
+└── Field masking
+      category = TRANSFORM_POLICY_RULE_DEFINITION   ← required by RuleBuilder validator
+      effect = Transform                            ← required by RuleBuilder validator
+      resourceScopeType = FIELD (structured) or SPAN (unstructured)
+      <policyRuleResourceDomains> = the DMO whose field is masked
+      <resourceTransform> required (e.g. NULL_RESOURCE_TRANSFORM, LAST_N_CHARS_RESOURCE_TRANSFORM)
+```
+
+### ACCESS vs GOVERNANCE — how to choose
+
+Both legally accept Permit and Forbid. Pick by *which enforcement layer should record/audit the rule* and **what the prompt literally asks for**:
+
+| Use case | Pick | Reason |
+|---|---|---|
+| The prompt names "ACCESS policy rule" / "access rule" / "OLS/FLS" explicitly | `ACCESS_POLICY_RULE_DEFINITION` | Matches the prompt's vocabulary; sits in the data-access enforcement layer. |
+| The prompt names "governance" / "audit" / "policy framework" / data-residency or compliance language | `GOVERNANCE_POLICY_RULE_DEFINITION` | Matches the prompt's vocabulary; rules surface in governance reporting. |
+| Prompt is ambiguous and only describes allow/deny semantics | Default to `ACCESS` for Permit, `GOVERNANCE` for Forbid (mirrors the platform's auto-fill default; safe and deployable, but **not required**) |
+
+> **Important — honor the explicit category in the prompt.** If the prompt says "ACCESS policy rule that denies …" or "GOVERNANCE policy rule that permits …", emit exactly that category. Do not silently swap to the auto-fill default just because effect is Forbid (or Permit). The platform accepts both. The agent must not override the user's stated intent.
+
+**Scope × category compatibility** — any combination outside this matrix throws `INVALIDFORCATEGORY`:
+
+|            | `ACCESS` | `GOVERNANCE` | `TRANSFORM` | `RECORD` |
+|------------|:--------:|:------------:|:-----------:|:--------:|
+| `ANY`      | Yes | Yes | No  | No  |
+| `DATASPACE`| Yes | Yes | No  | No  |
+| `FIELD`    | Yes | Yes | Yes | No  |
+| `RECORD`   | No  | No  | No  | Yes |
+| `SPAN`     | No  | No  | Yes | No  |
+
+---
+
+## 5. Condition Patterns (Quick Reference)
+
+Every `<conditions>` block needs **all four**: `<clause>`, `<operator>`, one path element, and the value.
+
+| Goal | path element | operator | value |
+|------|-------------|----------|-------|
+| Resource has tag | `<resourcePath>TAG</resourcePath>` | `CONTAINS_ANY` | `<valueReferenceType>CUSTOM_TAG` \| `STANDARD_TAG</valueReferenceType>` |
+| Resource has classification | `<resourcePath>CLASSIFICATION</resourcePath>` | `CONTAINS_ANY` | `CUSTOM_CLASSIFICATION` \| `STANDARD_CLASSIFICATION` |
+| Principal has permission | `<principalPath>ASSIGNED_PERMISSIONS_PATH</principalPath>` | `CONTAINS_ANY` \| `CONTAINS_NONE` | `<valueReferenceType>CUSTOM_PERMISSION</valueReferenceType>` |
+| Session in dataspace | `<contextPath>SESSION_DATASPACE</contextPath>` | `CONTAINS_ANY` | `<valueReferenceType>DATASPACE</valueReferenceType>` |
+| Record field = user attribute | `<resourcePath>RECORDFIELD</resourcePath>` + `<valueDomain>Schema:field</valueDomain>` | `EQUALS` | `<valuePrincipalPath>USER_ID` \| `ORGANIZATION_ID` \| `USER_ROLE_ID</valuePrincipalPath>` |
+| Entity type check | `<resourcePath>ENTITYTYPE</resourcePath>` | `IS` | `<valueString>{"t":"Text","v":"FIELD"}</valueString>` |
+
+`<conjunctionExpression>` is 1-indexed prefix notation: `1`, `(AND 1 2)`, `(OR 1 2)`, `(AND (OR 1 2) (AND 3))`. A bare top-level index like `1` is valid for **deploy** (impl fixtures use it) but **crashes the Data Governance Policy Builder UI** — see §7 if UI editability matters.
+
+For full path enums (`RulePrincipalPathType`, `RuleResourcePathType`, `RuleContextPathType`), operators, and JSON expressions (PROJECTION / ARGLIST / SOQLTARGETLISTEXPR), see [`references/policy-schema-full.md`](references/policy-schema-full.md). 
+For copy-paste templates for all policy variants, see [`references/templates.md`](references/templates.md).
+
+---
+
+## 6. Validation Guardrails
+
+1. Every `<conditions>` needs an `<operator>`. Missing operator → reject.
+2. Every `<conditions>` needs at least one path element (`<resourcePath>`, `<principalPath>`, `<contextPath>`, or `<valueDomain>`).
+3. `<contextPath>` is exclusively `SESSION_DATASPACE`. Never put a resource path value there.
+4. Scope × category must be in the §4 matrix. Common offenders: ACCESS/GOVERNANCE + RECORD scope; RECORD + ANY/FIELD scope; TRANSFORM + ANY/RECORD scope. (Effect is independent of category except for TRANSFORM — see §4.)
+5. `<resourceTransform>` and `effect=Transform` are coupled. Transform effect needs a resourceTransform. Permit/Forbid must not have one.
+6. `<policyRuleResourceDomains>` is **required** for RECORD (RLS) and FIELD-scope TRANSFORM; **forbidden** on ACCESS/GOVERNANCE.
+7. `<conjunctionExpression>` indices must match actual `<conditions>` count. Off-by-one → reject.
+8. `<clause>` inside `<conditions>` must match the wrapper (`WHEN` inside `<when…>`, `UNLESS` inside `<unless…>`).
+9. JSON literals in `<valueString>` must escape `"` to `&quot;`. Wrong escaping silently corrupts the literal.
+10. Reference targets (`<valueReference>`, `<resourceDomain>`) must exist in the target org at deploy time.
+11. `SCALAR_ATTRIBUTE` / `PLURAL_ATTRIBUTE` are not in `RulePrincipalPathType` — not in MDAPI contract. Use a runtime RuleProvider for those shapes.
+12. `IDENTIFIED_RECORD` is not authorable via MDAPI — `SESSION_CONSUMER_ID` not in `RuleContextPathType`.
+13. Standard tag/classification dev names are fully-qualified dotted paths (e.g. `DataGovernanceTags.ExternalData.Visibility.Public`). Retrieve an existing rule to get the exact string before authoring.
+14. Min API versions: `PolicyRuleDefinition` = 64.0; `PolicyJsonExpression` conditions = 66.0; `<replicated>` = 260+; `<builderCompatible>` / `<builderValidated>` = 262+.
+
+> **Note on `<conjunctionExpression>` shape:** A bare top-level index (e.g. `<conjunctionExpression>1</conjunctionExpression>`) deploys cleanly — the impl-side parser accepts bare tokens at the top level, and most positive single-condition fixtures in `enforce-o-matic-impl/test/func/filemetadata/` use it. It is **not** a deploy-time validation error. It does, however, crash the Data Governance Policy Builder UI on load — see §7.
+
+---
+
+## 7. UI Compatibility — Core Rules
+
+The Data Governance Policy Builder edits a **strict subset** of the MDAPI. Default goal: produce UI-compatible policies. Always confirm with the operator before producing API-only XML.
+
+**Hard blockers** — any of these make the policy uneditable (and several crash the builder on load):
+
+- **Missing OR-of-ENTITYTYPE clause on ACCESS/GOVERNANCE rules** → hard crash: `Cannot use 'in' operator to search for 'Permit' in undefined`. Required even when paired with `TupleRead` (where it's functionally redundant at runtime). Must include `IS` conditions for `{"t":"Text","v":"OBJECT"}` and `{"t":"Text","v":"FIELD"}`.
+- **Bare top-level condition index** in `<conjunctionExpression>` (e.g. `1`, or `(AND (OR 1 2) 3)`) → crash on builder load in `buildCriteria`. Deploy is unaffected, but the policy is uneditable in the UI. Always wrap: `(AND 1)` for a single condition; `(AND (OR 1 2) (AND 3))` instead of `(AND (OR 1 2) 3)`.
+- `category = ACCESS_POLICY_RULE_DEFINITION` + `effect = Forbid` → the **Data Governance Policy Builder UI** (not MDAPI) collapses it to GOVERNANCE on save; round-trip via the builder will rewrite the category. MDAPI deploy is unaffected — the original ACCESS+Forbid combination is valid and deploys without modification. If your goal is UI round-trippability, prefer GOVERNANCE for Forbid; if the source of truth is MDAPI, ACCESS+Forbid is fine.
+- Any `<unlessPolicyRuleDefinitionClauseConjunction>` block → silently dropped on first UI save.
+- More than one `<action>` → only the first is kept.
+- `ruleConsumer` ≠ `DATACLOUD` → UI hardcodes DATACLOUD on save.
+- Top-level `(OR 1 2)` conjunction → triggers `// ERROR: Unsupported rule!` path, rule silently dropped.
+
+**UI-compatible "unless" rewrite:**
+
+| Author intent | UI-compatible shape |
+|---|---|
+| `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` |
+
+For the full UI-compatibility checklist, round-trip rules, and operator support matrix, see [`references/ui-compatibility.md`](references/ui-compatibility.md).
+
+---
+
+## 8. Authoring Workflow
+
+1. **Start from the closest template** in [`references/templates.md`](references/templates.md) — modify from there, don't start blank.
+2. **Pick category first** (§4). Category fixes effect, resourceScopeType, and whether policyRuleResourceDomains/resourceTransform are required.
+3. **Lay out the bare rule**: top-level fields only, no conditions. Match the category template in [`references/templates.md`](references/templates.md).
+4. **Add conditions one at a time**, each with all four anchors: `<clause>`, `<operator>`, one path element, and the value.
+5. **Update `<conjunctionExpression>`** — 1-indexed prefix notation. Bare top-level index (e.g. `1`) deploys but breaks the UI; wrap as `(AND 1)` if UI editability matters (§7).
+6. **Run the UI-compatibility check** (§7 / [`references/ui-compatibility.md`](references/ui-compatibility.md)). If any item trips, attempt the "unless" rewrite first; if not possible, get explicit operator confirmation before continuing.
+7. **Update `package.xml`** — list each `<members>` for both types.
+8. **Set `<builderCompatible>`** on the set to `true` if §7 checklist passes; `false` if intentionally API-only.
+9. **Sanity-check against §6 (guardrails)** before considering done.
+10. **Validate with dry-run** before any non-dry deploy to a persistent org. Surface errors using the error reference in [`references/deploy-errors.md`](references/deploy-errors.md).
+
+**Three-layer correctness check** before done:
+- **Runtime / Cedar** — does the rule enforce what's intended? (action choice, condition shape)
+- **MDAPI deploy validity** — does it deploy? (§6 guardrails, scope×category, tag dev names, org perms)
+- **UI editability** — can the builder render and re-save it? (§7 checklist, OR-of-ENTITYTYPE requirement)
+
+---
+
+## Reference Docs
+
+| Detail | File |
+|--------|------|
+| Full path enums, operators, value sets, JSON expressions (PROJECTION / ARGLIST / SOQLTARGETLISTEXPR) | [`references/policy-schema-full.md`](references/policy-schema-full.md) |
+| Copy-paste templates — index at [`references/templates.md`](references/templates.md); per-variant: [`templates-access.md`](references/templates-access.md), [`templates-record.md`](references/templates-record.md), [`templates-transform.md`](references/templates-transform.md), [`templates-advanced.md`](references/templates-advanced.md) |
+| Full UI-compatibility checklist, round-trip rules, operator/path support matrix | [`references/ui-compatibility.md`](references/ui-compatibility.md) |

package/skills/platform-policy-rule-generate/references/deploy-errors.md

@@ -0,0 +1,54 @@
+# Deploy Error Reference
+
+When `sf project deploy start` fails, it prints a per-component status table. Below are the most common error families for `PolicyRuleDefinition` / `PolicyRuleDefinitionSet` metadata.
+
+For verbose output when scripting:
+```bash
+sf project deploy start --target-org <alias> --source-dir … --json --verbose \
+  | jq '.result.details.componentFailures'
+```
+
+---
+
+## Error Table
+
+| Error fragment | Likely cause | Fix |
+|---|---|---|
+| `Not available for deploy for this organization` | Org has `EnforceOMatic` perm (entities visible) but lacks `PolicyRuleMDAPI` org perm | Internal license/feature provisioning — surface to the operator. Both `EnforceOMatic` AND `PolicyRuleMDAPI` are required (see §11.1 of policy.md). |
+| `Cannot find … PolicyRuleDefinition` (older orgs) | Org missing `EnforceOMatic` entirely, or API version too low | Confirm both `EnforceOMatic` and `PolicyRuleMDAPI` perms; ensure `<version>` ≥ 64.0 in package.xml |
+| `INVALIDFORCATEGORY` / `Resource scope … not valid for category …` | Scope × category mismatch (e.g., ACCESS/GOVERNANCE + RECORD scope, or TRANSFORM + ANY scope) | Match scope to category per the §4 matrix in SKILL.md. For OLS/FLS on tagged objects: use `ANY`/`FIELD` scope + tag/classification condition — **not** `<resourceDomain>`. |
+| `Identified record category should use record field …` | Attempted to author an `IDENTIFIED_RECORD` policy with a non-`RECORDFIELD` resource path | Do not author `IDENTIFIED_RECORD` via MDAPI — use a runtime `RuleProvider` instead. |
+| `Invalid resource domain - <name>` | `<resourceDomain>` references an entity that doesn't exist in the target org | Pre-deploy the DMO/entity, or remove the rule until the target is available. Namespaced DMOs (e.g. `ssot__Account__dlm`) need the namespace prefix in the XML. |
+| `An unexpected error occurred. Please include this ErrorId… (-116061062)` (opaque gack on RLS deploy) | RLS rule references a `<valueDomain>` DMO field that exists in metadata but is **not mapped** in the target org's data streams. Server-side NPE instead of a clean validation error. | Verify each `<valueDomain>` field is mapped in Setup → Data Cloud → Data Explorer. Build the rule in the UI first — the UI surfaces field-mapping issues with usable errors where MDAPI doesn't. |
+| `Metadata API received improper input. … Load of metadata from db failed for metadata of type:PolicyRuleDefinition and file name:<name>` (on **retrieve**) | UI-saved RLS rules can fail to round-trip back through MDAPI retrieve in some org states | No clean fix. Use the UI as source of truth for that rule, or hand-author from a known-deployable RLS template. |
+| `Use the principal … with external record category.` | `EXTERNAL_RECORD` rule used a non-`IS_AUTHENTICATED`/`IS_INTERNAL` `principalPath` | Switch principal path or change category |
+| `Unsupported … contextPath` | Used a context path outside `RuleContextPathType.SESSION_DATASPACE` | Not authorable via MDAPI XML — use a runtime `RuleProvider` |
+
+---
+
+## OrgPerm Gating
+
+Two org permissions are **both** required for MDAPI authoring:
+
+| Permission | Gate | Effect if missing |
+|---|---|---|
+| `EnforceOMatic` | `@WsdlGuard` master switch | Entities not visible in UI/Tooling API at all |
+| `PolicyRuleMDAPI` | `orgCanUsePolicyRuleMDAPI` WSDL layer | Deploy fails with `Not available for deploy for this organization` |
+
+`EnforcOMaticMDAPI` is a separate **packaging** gate (`isMdAPIAllowedInternal`) — only required for packaging/change sets, not for DX CLI deploys. After PR #98647 (merged 2026-06-08) the predicate is `DBContext.get().isDoingPackageInstall()`, so DX CLI deploys work with just the two perms above.
+
+---
+
+## Dry-Run First
+
+Always validate before deploying to a long-lived org:
+
+```bash
+sf project deploy start \
+  --target-org <alias> \
+  --source-dir force-app/main/default \
+  --dry-run \
+  --wait 10
+```
+
+A `--dry-run` failure runs the full server-side validation hooks (including the `IDENTIFIED_RECORD` constraint at `PolicyRuleDefinitionCondObject.java:332-339`) without persisting. This catches all of the errors in the table above before they affect a real org.

package/skills/platform-policy-rule-generate/references/fixtures-index.md

@@ -0,0 +1,29 @@
+# Fixtures Index
+
+> **For human maintainers only.** This index requires a checkout of `enforce-o-matic-impl`. The agent should rely on [`templates.md`](templates.md), which reproduces the relevant XML shapes inline.
+
+Quick lookup from "what I need" to "fixture that already does it".
+
+All fixtures are under `enforce-o-matic-impl/test/func/filemetadata/<name>/`.
+
+| If you need… | Fixture |
+|---|---|
+| Bare permit rule, no conditions | `baseSteelthread`, `steelthreadPayload` |
+| Custom conjunction `(AND 1 2)` over UNLESS | `conjunctionExpressionSteelthread` |
+| Tag check | `conditionTagValidSteelthread`, `conditionCustomTagValidDataMaskingSteelthread` |
+| Classification check | `conditionClassificationValidClauseSteelthread`, `conditionClassificationValidDataMaskingSteelthread` |
+| Dataspace / session dataspace | `conditionDataspaceValidSteelthread`, `conditionSessionDataspaceValidSteelthread` |
+| Custom permission gate | `conditionAssignedPermPathValidSteelthread` |
+| Plain RLS (record field = user ID) | `conditionRLSValidSteelthread` (1st condition), `conditionStandardIdRLSValidSteelthread` |
+| RLS via PROJECTION join | `conditionRLSValidSteelthread` (2nd condition) |
+| Scalar / plural SOQL principal (out-of-contract) | `conditionScalarAttributeValidSteelThread`, `conditionPluralAttributeValidSteelthread` |
+| Hierarchy traversal | `conditionWithHierarchy` |
+| Field masking transform | `conditionClassificationValidDataMaskingSteelthread`, `conditionInvalidDataMaskingSteelthread` (negative) |
+| Field-scoped resource domain | `resourceDomainWithField` |
+| Core standard object policy (Case) | `coreObjectCaseWithPolicy` (persistence-layer only; not a working IDENTIFIED_RECORD shape — see §8.4 of policy.md) |
+| Extended steelthread (set referenced from sibling package) | `extendedSteelthread` |
+| Negative: missing operator | `conditionMissingOperatorSteelthread` |
+| Negative: missing path | `conditionMissingPathSteelthread` |
+| Negative: invalid context path | `conditionInvalidContextPathSteelthread` |
+| Negative: invalid data masking shape | `conditionInvalidDataMaskingSteelthread` |
+| Negative: invalid payload | `invalidPayload` |