@salesforce/afv-skills 1.41.0 → 1.43.0

package/skills/platform-custom-setting-generate/SKILL.md

@@ -0,0 +1,419 @@
+---
+name: platform-custom-setting-generate
+description: "Use this skill when users need to create, generate, or validate Salesforce Custom Setting metadata. Trigger when users mention custom settings (hierarchy or list), customSettingsType, SetupOwnerId, per-profile/per-user config overrides, feature flags, feature toggles, kill switches, or on/off switches admins flip to enable/disable behavior, e.g. bypass triggers/automation during a data load. Also use for \"create a custom setting\" or errors like \"Cannot specify: pluralLabel for CustomSettings\" or a setting that silently deployed as a regular custom object. A trigger bypass or kill switch is just a checkbox on a hierarchy custom setting — generate ONLY the setting, never an Apex trigger/handler. DO NOT TRIGGER for Custom Metadata Types or __mdt objects — route to platform-custom-metadata-type-generate; for business-record objects — use platform-custom-object-generate; for secrets, API keys, passwords, or tokens — recommend a Named Credential, never generated here."
+metadata:
+  version: "1.0"
+  minApiVersion: "60.0"
+  domains: ["Platform"]
+  relatedSkills:
+    - "platform-custom-field-generate"
+    - "platform-custom-metadata-type-generate"
+    - "platform-custom-object-generate"
+  cliTools:
+    - tool: ["sf"]
+      semver: ">=2.136.8"
+---
+
+# Salesforce Custom Setting Generator and Validator
+
+## When to Use This Skill
+
+Use this skill when you need to:
+
+- Create a Hierarchy or List custom setting
+- Generate custom setting metadata XML
+- Add or validate fields on an existing custom setting
+- Populate custom setting **values** (these are data, not metadata — see Section 6)
+- Troubleshoot custom setting deployment errors
+
+> **A trigger bypass / kill switch is a Custom Setting — not Apex and not a `__mdt`.** When the user wants a
+> switch admins can flip to turn behavior on or off — "disable my Account triggers during a data load", a
+> feature toggle, a maintenance-mode flag — generate **only** a hierarchy custom setting with a `Checkbox`
+> field (e.g. `Disable_Triggers__c` / `Bypass__c`). Do **not** author the Apex trigger, handler, or test
+> that reads it, and do **not** model it as a Custom Metadata Type: the per-profile/per-user override a
+> bypass flag needs is exactly what a hierarchy custom setting gives you and a `__mdt` does not. The Apex
+> that checks the flag is the developer's to write — this skill generates the setting only.
+
+---
+
+## 1. Overview and Purpose
+
+This document defines the mandatory constraints for generating Custom Setting metadata. A custom setting is
+a `CustomObject` with `<customSettingsType>` set — it is **not** a distinct metadata type.
+
+**File extension:** `.object-meta.xml`
+**File path:** `force-app/main/default/objects/<Name>__c/<Name>__c.object-meta.xml`
+**API name suffix:** `__c` (identical to a regular custom object — the suffix does **not** distinguish them)
+
+> **Values are data, not metadata.** You can generate the setting's *definition* as XML, but you cannot
+> deploy its *values* that way. There is no source-format equivalent of `customMetadata/` for custom
+> settings. Never generate a file that claims to carry setting values — see **Section 6** for what to do
+> instead.
+
+---
+
+## 2. Syntactic Essentials (Tier 1)
+
+### `<customSettingsType>` is mandatory — CRITICAL
+
+**This is the single highest-severity rule in this skill.** Omitting `<customSettingsType>` does not
+produce a "you forgot customSettingsType" error. The component silently stops being a custom setting and
+is validated as a plain custom object.
+
+The failure is dangerous because it is *recoverable in the wrong direction*: an agent that omits the
+element, then obediently fixes each error the platform reports, ends up with a **green deploy and
+completely the wrong kind of component**.
+
+| What you see | What it means |
+|---|---|
+| `Must specify a non-empty plural label for the CustomObject` | You are **NOT** building a custom setting. `customSettingsType` is missing. Add it — do **not** add `pluralLabel`. |
+| `Cannot specify: nameField for CustomSettings` | You **ARE** building a custom setting. Remove the named element. |
+
+These two strings are mutually exclusive tells. The giveaway in the first is the phrase
+**`for the CustomObject`** and the absence of any mention of custom settings.
+
+**If a deploy reports `Must specify a non-empty plural label for the CustomObject` on something the user
+asked to be a custom setting, never satisfy that error by adding `<pluralLabel>`.** Adding it (plus
+`nameField`, `deploymentStatus`, and `sharingModel`) makes the deploy succeed and creates a regular custom
+object that the user did not ask for.
+
+### Required and Allowed Elements
+
+| Element | Requirement | Notes |
+|---------|-------------|-------|
+| `<customSettingsType>` | **Required** | `Hierarchy` or `List` — see Section 3 |
+| `<label>` | **Required** | Singular UI name |
+| `<visibility>` | Always include | `Public`, or `Protected` only in a dev/sandbox/scratch org (Section 5) |
+| `<description>` | Always include | Explain what the setting controls and who edits it |
+| `<enableFeeds>` | Optional | Accepted |
+| `<listViews>` | Optional | Accepted — permitted despite `recordTypes` and `compactLayouts` being forbidden |
+
+### Forbidden Elements
+
+Every element below produces `Cannot specify: <element> for CustomSettings`:
+
+| Forbidden element | Note |
+|---|---|
+| `<pluralLabel>` | **Required on a regular custom object, forbidden here.** Exactly inverted. |
+| `<nameField>` | The `Name` field exists implicitly on List settings |
+| `<deploymentStatus>` | |
+| `<sharingModel>` | Custom settings are not shared records |
+| `<enableActivities>` `<enableReports>` `<enableHistory>` `<enableSearch>` | |
+| `<validationRules>` | Enforce these in Apex instead |
+| `<recordTypes>` | |
+| `<compactLayouts>` | |
+
+**INCORRECT** — carries a regular custom object's required elements:
+
+```xml
+<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
+  <customSettingsType>Hierarchy</customSettingsType>
+  <label>Feature Flags</label>
+  <pluralLabel>Feature Flags</pluralLabel>        <!-- WRONG: forbidden on custom settings -->
+  <sharingModel>ReadWrite</sharingModel>          <!-- WRONG: forbidden -->
+  <deploymentStatus>Deployed</deploymentStatus>   <!-- WRONG: forbidden -->
+  <nameField>                                    <!-- WRONG: forbidden -->
+    <label>Name</label>
+    <type>Text</type>
+  </nameField>
+  <visibility>Public</visibility>
+</CustomObject>
+```
+
+**Errors:** `Cannot specify: pluralLabel for CustomSettings` · `Cannot specify: sharingModel for CustomSettings` · `Cannot specify: deploymentStatus for CustomSettings` · `Cannot specify: nameField for CustomSettings`
+
+**CORRECT** — minimum valid custom setting:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
+  <customSettingsType>Hierarchy</customSettingsType>
+  <label>Feature Flags</label>
+  <description>Per-profile and per-user toggles for beta features in the ordering app. Edited by admins in Setup.</description>
+  <visibility>Public</visibility>
+</CustomObject>
+```
+
+Note there is no `<fullName>`. A root-level one is tolerated and ignored, but omit it — the API name comes
+from the directory and filename.
+
+`<customSettingsType>List</customSettingsType>` deployed without needing the "Manage List Custom Settings
+Type" toggle in Setup. That toggle exists in some orgs, so if a List setting is rejected on a
+`customSettingsType` grounds in a different org, check Schema Settings before assuming the XML is wrong.
+
+---
+
+## 3. List vs Hierarchy Decision (Tier 2)
+
+`<customSettingsType>` has exactly two values, and the choice changes how rows are addressed.
+
+| | `Hierarchy` | `List` |
+|---|---|---|
+| **Use when** | The value can vary per profile or per user, with an org-wide fallback | The setting is a small keyed reference table, the same for everyone |
+| **Row key** | `SetupOwnerId` (Organization, Profile, or User) | `Name` |
+| **Resolution** | User value → Profile value → org default | Look up by `Name` |
+| **Apex read** | `MySetting__c.getInstance()` / `getOrgDefaults()` | `MySetting__c.getValues('Key')` / `getAll()` |
+| **Typical case** | Feature flags, per-profile limits, debug toggles | Country codes, tax rates by region, integration endpoints by key |
+
+**Default to `Hierarchy`** when the user describes toggles, limits, or anything that "can be overridden."
+Choose `List` when they describe a lookup table with named rows.
+
+If the user asks for a keyed reference table that should be **deployable between orgs**, a List custom
+setting is usually the wrong answer — its rows are data and will not travel with the deploy. Route to
+`platform-custom-metadata-type-generate` instead (Section 7).
+
+---
+
+## 4. Field Rules
+
+Fields on a custom setting are ordinary `CustomField` components at
+`objects/<Name>__c/fields/<Field>__c.field-meta.xml`.
+
+**This skill owns the custom-setting-specific deltas only** — the supported-type allowlist and the
+`fieldManageability` prohibition below. For everything generic (`<fullName>` derivation, `<label>`,
+`<description>`, `<inlineHelpText>`, precision/scale, `<length>`, `externalId`), follow
+`platform-custom-field-generate`.
+
+### Supported Field Types
+
+`Checkbox`, `Currency`, `Date`, `DateTime`, `Email`, `Number`, `Percent`, `Phone`, `Text`, `TextArea`, `Url`
+
+`required`, `unique`, `externalId`, and `defaultValue` are accepted on custom setting fields. Whether a
+given one applies to a given type is a generic field rule — defer to `platform-custom-field-generate`.
+
+### Unsupported Field Types
+
+`Picklist`, `MultiselectPicklist`, `LongTextArea`, `Html`, `Lookup`, `MasterDetail`, `AutoNumber`,
+`Location`, `Time`, `EncryptedText`, and **Formula** (a `<formula>` element on any type).
+
+Every one of these fails with the same bare, uninformative string:
+
+```text
+Invalid data type.
+```
+
+**This error names neither field nor type.** On a multi-field deploy, read `componentFailures[].fullName`
+from the `--json` output to find the culprit — do not guess.
+
+**Roll-up summary fields are structurally impossible here** — a `Summary` needs a master-detail child, and
+`MasterDetail` is itself rejected on a custom setting. Don't generate one; the error text varies, so don't
+match on a specific string.
+
+**Picklist is the common trap.** Users frequently ask for a picklist on a custom setting. It is not
+supported. Use `Text` and enforce the allowed values in Apex, or route the request to
+`platform-custom-metadata-type-generate` — CMDT *does* support Picklist.
+
+Near-inversion vs CMDT: `Currency` works here but not on CMDT; `Picklist`/`LongTextArea` work on CMDT but
+not here. Never carry field-type assumptions across the two families.
+
+### `<fieldManageability>` is forbidden
+
+That element belongs to CMDT fields only. On a custom setting field it fails with:
+
+```text
+Field manageability cannot be set on this entity.
+```
+
+---
+
+## 5. Visibility, Secrets, and the No-Silent-Downgrade Rule
+
+### `Protected` is org-type dependent
+
+`<visibility>Protected</visibility>` deploys only in a developer, sandbox, or scratch org. Anywhere else:
+
+```text
+You can't set the visibility for a Custom Setting to Protected unless you are in a developer, sandbox, or scratch org.
+```
+
+### The no-silent-downgrade rule — CRITICAL
+
+**If `Protected` fails because of the org type, never "fix" it by switching to `Public`.** A silent
+downgrade turns a deliberate confidentiality choice into a world-readable component with no signal. Report
+it plainly: the org does not permit `Protected`, so the options are a dev/sandbox/scratch org or accepting
+`Public` — let the user decide. This applies to any visibility narrowing, not just this error.
+
+### Secrets do not belong in a custom setting
+
+Custom settings are **not** a secret store. Values are readable by anyone who can query the object, and
+`Protected` does not change that for code in the same namespace.
+
+When a user asks to store an API key, password, token, client secret, or certificate in a custom setting:
+
+1. **Warn prominently and first** — before generating anything — that a custom setting is the wrong place
+   for a credential and the value will be readable.
+2. **Recommend the right component** — a **Named Credential** with an **External Credential** for callout
+   auth. Say plainly that this skill does not generate those.
+3. **If the user still insists, comply** — generate the setting but keep the warning in the response. Do not
+   silently refuse, and do not silently obey.
+
+Never route a secret to `Protected` visibility as a compromise: if `Protected` is unavailable (above),
+the no-silent-downgrade rule applies with full force, because the downgrade would publish the secret.
+
+---
+
+## 6. Setting Values Are Data, Not Metadata
+
+**A custom setting's rows cannot be deployed as XML.** There is no `customMetadata/`-style folder for them.
+Only the object definition and its fields are metadata.
+
+When a user asks to create a setting *with values* — "add a feature flag setting with Beta enabled for
+admins" — do all of the following:
+
+1. Generate the object and field XML as normal.
+2. **State the limitation in one line:** setting values are data, not metadata, so they are not deployed.
+3. **Give ready-to-run commands inline in the chat response**, fully substituted with the real object and
+   field API names and the actual values — not a placeholder template, and not written to a file.
+
+All three shapes below are verified working.
+
+### Hierarchy — org-wide default row
+
+**Omit `SetupOwnerId`.** It defaults to the Organization Id, which is exactly the org-default row. No Id
+lookup is needed.
+
+```bash
+sf data create record --sobject Feature_Flags__c \
+  --values "Enable_Beta__c=true Max_Retries__c=3" \
+  --target-org <alias>
+```
+
+### Hierarchy — profile or user override
+
+This one **does** need an Id, so it is two steps. A user-level override uses the same shape with a `User` Id
+in place of the Profile Id (extrapolated from the profile case, not separately verified).
+
+```bash
+sf data query --query "SELECT Id FROM Profile WHERE Name='System Administrator'" --target-org <alias>
+
+sf data create record --sobject Feature_Flags__c \
+  --values "SetupOwnerId=00eXXXXXXXXXXXXXXX Enable_Beta__c=false" \
+  --target-org <alias>
+```
+
+An override row coexists with the org-default row; it does not replace it.
+
+### List — one row per key
+
+`Name` is the row key and is required.
+
+```bash
+sf data create record --sobject Country_Codes__c \
+  --values "Name='US' Iso_Code__c='USA' Dial_Prefix__c='+1'" \
+  --target-org <alias>
+```
+
+### Quoting
+
+Wrap the whole `--values` argument in double quotes; single-quote any value with a space or shell-special
+character (`Environment_Label__c='org default'`). Plain numbers, booleans, and Ids need no inner quotes.
+
+### Consuming a setting in Apex
+
+Values are read through the generated typed class — cached, so reads cost **no SOQL** and are safe inside
+loops and triggers. For a **Hierarchy** setting:
+
+```apex
+Feature_Flags__c cfg = Feature_Flags__c.getInstance();        // running user: user → profile → org default
+Feature_Flags__c org = Feature_Flags__c.getOrgDefaults();     // org-default row only, no hierarchy
+Feature_Flags__c forProfile = Feature_Flags__c.getInstance(profileId);  // a User Id works too
+Boolean beta = cfg.Enable_Beta__c;
+```
+
+`getInstance()` and `getOrgDefaults()` **never return null** (API ≥ 22) — a missing record comes back as an
+empty row, so test `org.Id != null` when you need to know whether a real record actually exists. For a
+**List** setting, use `getValues('Key')` for one row or `getAll()` for the `Map<String, Feature_Flags__c>`
+of every row.
+
+### The in-transaction DML rule
+
+Populating or changing values is **runtime DML** (Apex `insert`/`update`/`upsert`, or the `sf` commands
+above) — there is no metadata path. That is the operational face of "values are data," and it has two
+consequences worth stating to the user:
+
+- **Writes count against DML governor limits; reads do not.** In a trigger over 200 records, never `upsert`
+  the setting once per record — hoist the write out of the loop and do it once.
+- **Cross-transaction propagation lags.** After a write, other transactions may briefly read the previous
+  value while the org cache propagates; within the same transaction the new value is visible immediately.
+
+---
+
+## 7. Choosing the Right Component
+
+Before generating, confirm a custom setting is actually what the user needs. If it is not, say so and name
+the right skill rather than building the wrong thing.
+
+| If the config is… | Use | Why |
+|---|---|---|
+| Admin-editable per profile/user, or a small keyed table that stays in one org | **Custom Setting** (this skill) | Values are data; they do not travel with a deploy |
+| Reference data that must **deploy between orgs** with its records | `platform-custom-metadata-type-generate` | CMDT records are metadata and are deployable |
+| Business records users create and edit at runtime | `platform-custom-object-generate` | Custom settings are configuration, not transactional data |
+| Translatable UI text | Custom Label — this skill does not generate it | Labels are the supported translation surface |
+| Credentials, API keys, tokens, endpoints with auth | Named Credential / External Credential — this skill does not generate them | See Section 5 |
+| A permission check in Apex or a flow | Custom Permission — this skill does not generate it | Boolean access checks belong in the permission model |
+
+The distinction that matters most: **CMDT records deploy, custom setting values do not.** If the user says
+"and it should ship with these values" or "the same in every org," that is a CMDT request.
+
+---
+
+## 8. Common Deployment Errors
+
+| Error Message | Cause | Fix |
+|---|---|---|
+| `Must specify a non-empty plural label for the CustomObject` | `<customSettingsType>` is missing, so this is being validated as a regular custom object | Add `<customSettingsType>`. **Do NOT add `<pluralLabel>`** (Section 2) |
+| `Cannot specify: pluralLabel for CustomSettings` | `<pluralLabel>` present | Remove it — required on custom objects, forbidden here |
+| `Cannot specify: <element> for CustomSettings` (`<element>` = `nameField`, `sharingModel`, `deploymentStatus`, `validationRules`, `recordTypes`, or `compactLayouts`) | A custom-object-only element is present | Remove it (enforce validation logic in Apex instead) |
+| `Invalid data type.` | Unsupported field type (Section 4) | Read `componentFailures[].fullName` to find the field; switch to a supported type |
+| `Field manageability cannot be set on this entity.` | `<fieldManageability>` on a setting field | Remove it — CMDT only |
+| `You can't set the visibility for a Custom Setting to Protected unless you are in a developer, sandbox, or scratch org.` | `Protected` in a production-like org | Report to the user; **never silently switch to `Public`** (Section 5) |
+
+The `Cannot specify:` suffix is `for CustomSettings` (one word) versus CMDT's `for Custom Metadata Type`,
+and the visibility error uses `for a Custom Setting` (spaced, singular). Do not assume a shared template
+when matching these strings.
+
+---
+
+## 9. Verification Checklist
+
+Before generating custom setting XML, verify:
+
+### Component Identity Checks CRITICAL
+- [ ] Is `<customSettingsType>` present and set to `Hierarchy` or `List`?
+- [ ] Is the choice between Hierarchy and List justified by the request (overridable vs keyed table)?
+- [ ] If a deploy reported `Must specify a non-empty plural label for the CustomObject`, was it fixed by adding `<customSettingsType>` rather than by adding `<pluralLabel>`?
+- [ ] **After a successful deploy of a new setting**, was it confirmed to actually *be* a custom setting? Inspecting the XML cannot catch this failure, because the wrong-component outcome deploys green. Run `sf sobject describe --sobject <Name>__c --target-org <alias>` and verify `customSetting` is `true`.
+
+### Syntactic Checks
+- [ ] Are `<label>` and `<visibility>` present?
+- [ ] Is `<description>` present and specific about what the setting controls?
+- [ ] Is `<pluralLabel>` ABSENT?
+- [ ] Are `<nameField>`, `<sharingModel>`, and `<deploymentStatus>` ABSENT?
+- [ ] Are `<enableActivities>`, `<enableReports>`, `<enableHistory>`, and `<enableSearch>` ABSENT?
+- [ ] Are `<validationRules>`, `<recordTypes>`, and `<compactLayouts>` ABSENT?
+- [ ] Does the filename match the intended API name, ending in `__c`?
+
+### Field Checks
+- [ ] Is every field type in the supported list (Section 4)?
+- [ ] Is `Picklist` absent? (unsupported — use `Text`, or route to CMDT)
+- [ ] Is every `<formula>` element absent? (formulas are unsupported)
+- [ ] Is `<fieldManageability>` ABSENT on every field?
+- [ ] Do generic field attributes follow `platform-custom-field-generate`?
+
+### Values Checks
+- [ ] If the user asked for values, was the data-not-metadata limitation stated explicitly?
+- [ ] Were `sf` commands given **inline in the response**, fully substituted with real API names and real values — not written to a file, not left as a template?
+- [ ] For a Hierarchy org default, is `SetupOwnerId` omitted rather than guessed?
+- [ ] For a List row, is `Name` supplied?
+
+### Consumption Checks
+- [ ] If the user asked how to read the setting, was an Apex snippet given using the generated accessors (`getInstance` / `getOrgDefaults` for Hierarchy, `getValues` / `getAll` for List)?
+- [ ] Was the in-transaction DML rule stated — writes are DML that count against limits (bulkify, hoist out of loops), reads are free, and cross-transaction cache propagation lags?
+
+### Security Checks CRITICAL
+- [ ] If the request involves a secret, key, token, or password, was the warning given **before** generating, with a Named Credential recommended?
+- [ ] Was `Protected` left intact rather than silently downgraded to `Public` on an org-type failure?
+
+### Component-Choice Checks
+- [ ] If the values must deploy between orgs, was `platform-custom-metadata-type-generate` recommended instead?
+- [ ] If the request is really business records, was `platform-custom-object-generate` recommended instead?

package/skills/platform-dataspace-access-configure/SKILL.md

@@ -1,7 +1,9 @@
 ---
 name: platform-dataspace-access-configure
-description: "Use this skill to configure or inspect Salesforce Data Cloud DataSpace access for permission sets. Grants dataspace-level access via MDAPI PermissionSet XML with dataspaceScopes elements, optionally grants object-level access to DMO, DLO, or CIO objects via the Object Access Grants Connect API, and inspects existing scopes via read-only PermissionSet metadata retrieval. TRIGGER when: user needs to create or update a permission set with DataSpace access, grant access to a specific dataspace, list permission sets with access to a DataSpace, configure dataAccessLevel/objectAccessLevel, add RBAC object access grants, or list/remove object access grants for a permission set + DataSpace pair. DO NOT TRIGGER when: the task is a generic permission set without dataspace access (use platform-permission-set-generate), the request is about data ingestion/streams (use data360-prepare), or the work involves creating dataspaces themselves rather than granting access to them."
+description: "Use this skill to configure or inspect Salesforce Data Cloud DataSpace access for permission sets. Grants dataspace-level access via MDAPI PermissionSet XML with dataspaceScopes elements, optionally grants object-level access to DMO, DLO, or CIO objects via the Object Access Grants Connect API, and inspects existing scopes via read-only PermissionSet metadata retrieval. TRIGGER when: user needs to create or update a permission set with DataSpace access, grant access to a specific dataspace, list permission sets with access to a DataSpace, configure dataAccessLevel/objectAccessLevel, add RBAC object access grants, or list/remove object access grants for a permission set + DataSpace pair. DO NOT TRIGGER when: the task is a generic permission set without dataspace access (use platform-permission-set-generate), the request is about data ingestion/streams, or the work involves creating dataspaces themselves rather than granting access to them."
 metadata:
+  relatedSkills:
+    - "platform-permission-set-generate"
   version: "1.0"
   domains: ["Platform", "Data 360"]
   minApiVersion: "67.0"
@@ -65,8 +67,6 @@ Trigger this skill when the user wants to:
 
 Delegate elsewhere when:
 - The permission set has no DataSpace access at all → `platform-permission-set-generate`
-- The task is creating the DataSpace itself → `data360-orchestrate`
-- The task is ingesting data or configuring streams → `data360-prepare`
 
 ---
 

package/skills/platform-sharing-owd-configure/SKILL.md

@@ -2,6 +2,9 @@
 name: platform-sharing-owd-configure
 description: "Use when the user wants to retrieve or update Organization-Wide Default (OWD) sharing settings for Salesforce objects. TRIGGER when: user asks to check current OWD settings, view sharing defaults, change default access levels (Private, Public Read Only, Public Read/Write, Controlled by Parent), configure internal or external access for standard or custom objects, mentions org-wide defaults, wants to make records private or restrict who can see records, wants to control default record visibility for an object, or references .settings-meta.xml sharing fields or sharingModel in .object-meta.xml files. DO NOT TRIGGER when: user asks about sharing rules, criteria-based sharing, role hierarchy, or manual sharing — delegate to platform-sharing-rules-generate."
 metadata:
+  relatedSkills:
+    - "platform-metadata-deploy"
+    - "platform-sharing-rules-generate"
   version: "1.2"
   domains: ["Platform"]
   cliTools:

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

@@ -2,6 +2,8 @@
 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:
+  relatedSkills:
+    - "platform-custom-field-generate"
   version: "1.0"
   domains: ["Platform"]
   minApiVersion: "60.0"

package/skills/service-agentforce-channel-configure/SKILL.md

@@ -1,15 +1,16 @@
 ---
 name: service-agentforce-channel-configure
-description: "Wires an existing, active Agentforce agent to a channel by resolving a fallback queue, setting up inbound routing (either PATCH SessionHandlerId on the MessagingChannel, or an inbound RoutingFlow for Voice/Email), and optionally configuring outbound escalation. Use when the user wants to add a channel to an existing agent, connect an agent to a messaging or voice channel, route Voice or Email-to-Case to an Agentforce agent, or set up a fallback queue for an agent channel. Applies to any already-created agent, including an existing Help Agent. The channel infrastructure (MessagingChannel, Voice config, email-to-case) must already exist — this skill only adds the routing. DO NOT TRIGGER when the agent does not yet exist or still needs Help Agent setup (use agentforce-generate or service-helpagent-coordinate), when creating the MessagingChannel itself (use service-digital-engagement-channel-configure), or when creating an Embedded Service Deployment (use service-digital-engagement-deployment-configure)."
+description: "Wires an existing, active Agentforce agent to a channel by resolving a fallback queue, setting up inbound routing (either PATCH SessionHandlerId on the MessagingChannel, or an inbound RoutingFlow for Voice/Email), and optionally configuring outbound escalation. Use when the user wants to add a channel to an existing agent, connect an agent to a messaging or voice channel, route Voice or Email-to-Case to an Agentforce agent, or set up a fallback queue for an agent channel. Also applies to an existing Help Agent. The channel infrastructure must already exist — this skill adds routing. DO NOT TRIGGER when the agent does not yet exist or still needs Help Agent setup (use agentforce-generate or service-helpagent-coordinate), when setting up Email-to-Case with an agent end-to-end (use service-email-to-case-configure), when creating the MessagingChannel itself (use service-digital-engagement-channel-configure), or when creating an Embedded Service Deployment (use service-digital-engagement-deployment-configure)."
 allowed-tools: Bash Read Write Edit Glob Grep AskUserQuestion
 metadata:
-  version: "1.0"
+  version: "1.1"
   domains: ["Service", "Agentforce"]
   minApiVersion: "67.0"
   relatedSkills:
     - "agentforce-generate"
     - "service-digital-engagement-channel-configure"
     - "service-digital-engagement-deployment-configure"
+    - "service-email-to-case-configure"
     - "service-helpagent-coordinate"
   cliTools:
     - tool: ["python3"]
@@ -30,7 +31,7 @@ This skill is generic — it works for any Agentforce agent, not just the Help A
 - Resolving or creating a fallback queue with the correct `QueueSobject` SobjectType
 - Branch A (Enhanced Chat / Enhanced Messaging): deploying `sessionHandlerType=AgentforceServiceAgent` + `sessionHandlerQueue` on an existing MessagingChannel, then binding `SessionHandlerId` via Data API PATCH
 - Branch B (Voice): assumes the phone number and `PstnVoice` MessagingChannel already exist (provisioned by the caller, e.g. `service-helpagent-coordinate`), then creating an inbound RoutingFlow (`routingType: Copilot`) that routes to the agent with the queue as fallback
-- Branch C (Email-to-Case): same inbound RoutingFlow, using the org-specific Case-based ServiceChannel
+- Branch C (Email-to-Case): inbound routing via direct case-owner assignment or an Omni-Channel RoutingFlow, plus deploying a `BotEmailDefinition` (Email Configuration) that links the agent to Service Email and binding it to the routing address
 - Optional outbound escalation: adding the appropriate `connection {type}:` block to the agent and republishing
 
 **Out of scope:**
@@ -162,25 +163,22 @@ Proceed to Phase 3 (optional).
 
 #### Branch C — Email-to-Case
 
-Same inbound RoutingFlow shape as Branch B, but using the org-specific Case-based ServiceChannel. Additionally requires an outbound `connection service_email:` and a mandatory manual BotEmailDefinition step in Setup — these are not optional and cannot be deferred to Phase 3.
+Inbound routing to the agent via direct case-owner assignment or an Omni-Channel `Copilot` RoutingFlow — user chooses in Step 2. Additionally requires the `connection service_email:` **surface** block and a mandatory BotEmailDefinition step (Email Configuration). It gates on API v68.0+ up front (see `references/channel-branch-email.md`).
 
-Follow `references/channel-branch-email.md` end to end. Highlights:
+Follow `references/channel-branch-email.md` end to end. Load-bearing gotchas (full walkthrough in that file):
 
-- Step 0 — verify `emailToCase.enableEmailToCase` and `emailToCase.enableOnDemandEmailToCase` are `true` in CaseSettings via the Tooling API; if either is off, deploy a settings file that enables both (safe-fields-only pattern) before continuing.
-- Step 1 — reuse an existing `EmailRoutingAddress` or create one for the support email address, then patch `caseOrigin` / `saveEmailHeaders: true` / `addressType: EmailToCase` for that entry in `CaseSettings.Metadata.caseEmailRoutingAddresses` via Tooling-API PATCH (fallback: `sf project deploy start --metadata Settings:Case`). Inform the user about the verification email but do not block on it.
-- Step 2 — query the Case-based ServiceChannel (see `references/channel-types.md`), then write and deploy the inbound RoutingFlow using the template in `references/routing-flow.md`; verify `ActiveVersionId` is non-null.
-- Step 3 — mandatory outbound: reuse or create `{AgentDevName}_Outbound_Email_Flow` (QueueBased template in `references/routing-flow.md` Part 2), then add `connection service_email:` to the agent and republish per `references/agent-wiring.md`.
-- Step 4 — mandatory manual: prompt the user to create an **Email Configuration for Agentforce Service Agent** at `{ORG_INSTANCE_URL}/lightning/setup/AsaForEmail/home` and set the Agentforce Configuration field on the Email-to-Case routing address. Wait for user confirmation.
+- Step 1 — bind routing-address fields via Tooling-API PATCH or a `--metadata-dir` `Settings:Case` deploy, **never** a source `--metadata Settings:Case` deploy (it reads `sourceApiVersion` and mutates the user's project).
+- Step 2 — choose inbound routing (`AskUserQuestion`): **case-owner** (`caseOwner` = the agent's bot user) or **Omni-Channel flow** (`Copilot` RoutingFlow + `routingFlow`/`fallbackQueue`). Resolve the bot user either way; routing fields go in the Step 4d deploy.
+- Step 3 — the agent is already active, so add the mandatory `connection service_email:` surface via **deactivate → publish → activate** (a plain publish fails with `couldn't find the default agent user`). Batch the outbound route here too if escalation is wanted.
+- Step 4 — BotEmailDefinition: preflight the save-time gates, validate the reply template, deploy via `--metadata-dir`, then bind the routing address in one `Settings:Case` deploy (`botEmailDefinition` + Step 2 routing fields + the required `casePriority`). Stop on failure.
 
-Branch C is complete once the user confirms Step 4. Skip Phase 3 for Email-to-Case (outbound escalation is already handled inline).
+Branch C is complete once the routing-address binding is verified. Proceed to Phase 3.
 
 ---
 
-### Phase 3 — Outbound escalation (optional — Branches A/B only)
+### Phase 3 — Outbound escalation (optional)
 
-> **Branch C (Email-to-Case):** outbound escalation was handled inline in Branch C above. Do not run Phase 3 for Email-to-Case.
-
-After inbound routing is confirmed (Branches A or B), ask the user:
+After inbound routing is confirmed, ask the user:
 
 > *"Inbound routing is now set up — the channel will route to [agent name]. Do you also want to configure outbound escalation so the agent can hand off to a human when requested?"*
 
@@ -219,7 +217,9 @@ If yes:
 | Branches B/C: use `routingType: Copilot` and `copilotLabel` — not `QueueBased` | `QueueBased` routes to the queue directly; `Copilot` routes to the agent first with the queue as fallback |
 | Queue `Id` must be queried and embedded in the RoutingFlow XML | The `queueId` parameter requires a hardcoded 18-char record Id — do not leave it empty |
 | Queue naming: `{ChannelTypeLabel} Queue` | Named after the channel type, not the agent |
-| Outbound escalation is optional for Branches A/B — mandatory for Branch C (Email-to-Case) | BotEmailDefinition (Email Configuration in Setup) requires `connection service_email:` to already be on the agent; it cannot be created before the connection block is deployed |
+| Outbound escalation is optional — never block inbound routing completion on it | Inbound and outbound are independent; inbound wiring is complete without the outbound step |
+| Branch C: deploy BotEmailDefinition via `--metadata-dir`, never `--metadata BotEmailDefinition:<name>` | Not in the CLI's SDR registry, so the named-type deploy fails; metadata-format works |
+| Branch C: do not wire an agent carrying a `ServiceCustomerVerification` topic to email | Detect and stop — do not auto-remove (may be legitimate for a multi-surface agent). See `channel-branch-email.md` Step 4a |
 
 ---
 
@@ -248,8 +248,11 @@ If yes:
 - [ ] If new: user informed that a verification email was sent to the support address (non-blocking)
 
 ### Branch C — BotEmailDefinition
-- [ ] User has confirmed creation of Email Configuration for Agentforce Service Agent at `/lightning/setup/AsaForEmail/home`
-- [ ] Email-to-Case routing address has the Agentforce Configuration field set
+- [ ] Preflight passed: agent is `EinsteinServiceAgent` with a bot user holding `agentforceServiceAgentUser`; active version carries the `ServiceEmail` surface; no `ServiceCustomerVerification` topic on the email agent
+- [ ] Reply `EmailTemplate` is SFX, HTML, public, and contains `[[[GENERATED_CONTENT]]]` + `[[[LEGAL_DISCLOSURE]]]`
+- [ ] Headless path (API ≥68): `BotEmailDefinition` deployed via `--metadata-dir` with `success: true`; `legalDisclaimer`/`signature` ≥10 chars
+- [ ] Routing address's `botEmailDefinition` child set to the deployed component `fullName`
+- [ ] Inbound routing set on the same routing address: `caseOwner`+`caseOwnerType` or `routingFlow`+`fallbackQueue`, with `casePriority` present
 
 ### Optional Phase 3 — Outbound escalation
 - [ ] Correct connection block used: `customer_web_client:` for EmbeddedMessaging, `messaging:` for 3rd-party, `telephony:` for Voice, `service_email:` for Email-to-Case
@@ -266,6 +269,12 @@ If yes:
 | `references/queue-resolution.md` | Phase 1 — queue lookup, creation, and Id capture |
 | `references/live-traffic-gate.md` | Phase 2 — detection queries, deferred-flow rules, and manual wiring copy for the live-traffic warning gate |
 | `references/channel-branch-voice.md` | Branch B — full Voice inbound wiring: PstnVoice channel selection, RoutingFlow, MessagingChannel assignment, `modality voice:` republish |
-| `references/channel-branch-email.md` | Branch C — full Email-to-Case wiring: CaseSettings flags, EmailRoutingAddress + read-modify-write patch, inbound RoutingFlow, mandatory outbound `connection service_email:`, BotEmailDefinition manual step |
+| `references/channel-branch-email.md` | Branch C — full Email-to-Case wiring: API v68.0+ precondition gate, CaseSettings flags, EmailRoutingAddress + read-modify-write patch, inbound RoutingFlow, mandatory `connection service_email:` surface block, headless BotEmailDefinition deploy, routing-address binding |
+| `references/botemaildefinition.md` | Branch C Step 4 — BotEmailDefinition fields, save-time validation order, ASA template rules, `--metadata-dir` deploy recipe, `ServiceEmail` surface prerequisite, composite org gate |
 | `references/routing-flow.md` | Branches B/C — inbound RoutingFlow XML template, deploy, verify |
-| `references/agent-wiring.md` | Phase 3 (optional) — outbound escalation `connection messaging:` block |
+| `references/agent-wiring.md` | Phase 3 (optional) — outbound escalation `connection` block |
+| `assets/BotEmailDefinition.botEmailDefinition-meta.xml` | Branch C Step 4c — starting template for the BotEmailDefinition source file |
+| `assets/mdapi-package.xml` | Branch C Step 4c — metadata-format `package.xml` for the `--metadata-dir` deploy |
+| `assets/email/unfiled$public/AgentforceForServiceEmailTemplate.email` + `.email-meta.xml` | Branch C Step 4b (fallback) — minimal ASA-compliant SFX reply template when the user has none |
+| `scripts/validate-botemaildefinition.py` | Branch C Step 4c — validate the BotEmailDefinition file before deploy |
+| `scripts/validate-emailtemplate.py` | Branch C Step 4b (fallback) — validate the SFX template before deploy |

package/skills/service-agentforce-channel-configure/assets/BotEmailDefinition.botEmailDefinition-meta.xml

@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  BotEmailDefinition source file — links an Agentforce Service Agent to Service
+  Email (API v68.0+) so the agent can reply to Email-to-Case messages. Deploy it
+  via metadata format (the deploy "metadata-dir" path), NOT source format:
+  BotEmailDefinition is absent from the CLI's source-deploy-retrieve registry
+  (see references/botemaildefinition.md). Then bind the Email-to-Case routing address
+  to it by setting the routing address's <botEmailDefinition> to this component's
+  fullName (the file name without the suffix).
+
+  fullName is the FILE NAME, not a child element. Name the file
+  <DeveloperName>.botEmailDefinition-meta.xml and do NOT add a <fullName> element.
+
+  All six fields below are REQUIRED (the WSDL marks none optional) and none are
+  platform-generated/read-only. legalDisclaimer and signature must each be at
+  least 10 characters (save-time MinLengthNotMet check).
+-->
+<BotEmailDefinition xmlns="http://soap.sforce.com/2006/04/metadata">
+    <!-- Developer/API name of the AgentforceServiceAgent (Bot) to link. Must
+         already exist, be published/active, be of type EinsteinServiceAgent, and
+         have a bot user holding the agentforceServiceAgentUser permission. -->
+    <botDefinition>{AGENT_DEVELOPER_NAME}</botDefinition>
+    <!-- FOLDER-QUALIFIED developer name of the reply email template (must exist,
+         uiType=SFX, HTML, public, and contain both ASA tokens). A bare name is
+         rejected ("no EmailTemplate named X found"); qualify it with the folder,
+         e.g. unfiled$public/AgentforceForServiceEmailTemplate. -->
+    <emailTemplate>{EMAIL_TEMPLATE_FOLDER}/{EMAIL_TEMPLATE_DEVELOPER_NAME}</emailTemplate>
+    <!-- Display label for this email definition. -->
+    <label>{LABEL}</label>
+    <!-- Legal disclosure / footer text appended to the agent's replies (>= 10 chars). -->
+    <legalDisclaimer>{LEGAL_DISCLAIMER_TEXT}</legalDisclaimer>
+    <!-- true = reply-all; false = reply to sender only. -->
+    <replyAll>false</replyAll>
+    <!-- Email signature block (>= 10 chars). -->
+    <signature>{SIGNATURE_TEXT}</signature>
+</BotEmailDefinition>

package/skills/service-agentforce-channel-configure/assets/email/unfiled$public/AgentforceForServiceEmailTemplate.email

@@ -0,0 +1,17 @@
+<!--
+  HTML body for the Agentforce Service Agent email-reply template (uiType=SFX).
+  This body MUST contain the two literal ASA placeholder tokens below, exactly
+  as written (raw substring match) — BotEmailDefinition rejects the template
+  otherwise:
+    [[[GENERATED_CONTENT]]]  — where the agent's generated reply is injected.
+    [[[LEGAL_DISCLOSURE]]]   — where the BotEmailDefinition legalDisclaimer is injected.
+  These are literal triple-bracket tokens, NOT Salesforce merge fields; do not
+  convert them to merge-field syntax. (The SFX deploy validator scans the whole
+  body, including comments, and rejects any occurrence of merge-field syntax.)
+-->
+<html>
+  <body>
+    <div>[[[GENERATED_CONTENT]]]</div>
+    <div>[[[LEGAL_DISCLOSURE]]]</div>
+  </body>
+</html>