@salesforce/afv-skills 1.20.0 → 1.22.0

package/skills/integration-eventing-cdc-configure/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: integration-eventing-cdc-configure
+description: "Use to enable Salesforce Change Data Capture (CDC) on a standard or custom object, configure a custom event channel, set a filter expression, or add enrichment fields. TRIGGER broadly on any of: 'enable CDC', 'enable Change Data Capture', 'turn on CDC', 'subscribe X to change events', 'only emit events for', 'filter change events', 'enrich change events', 'create a custom event channel'; or any mention of CDC, change events, PlatformEventChannel, PlatformEventChannelMember, EnrichedField, ChangeEvents channel, enrichment fields, change event filter; or when the user wants a downstream system to receive Salesforce data changes; or when the user touches .platformEventChannelMember-meta.xml / .platformEventChannel-meta.xml files. SKIP when publishing platform events, Pub/Sub API or REST/SOAP (use integration-connectivity-generate), or ManagedEventSubscription (out of scope for CDC). Always use this skill for CDC channel-membership metadata."
+metadata:
+  version: "1.0"
+---
+
+# Managing Change Data Capture Enablement
+
+Generate the metadata that subscribes Salesforce objects to Change Data Capture: `PlatformEventChannelMember` files for the default `ChangeEvents` channel or a custom channel, and `PlatformEventChannel` files for new custom channels. Covers enrichment fields, filter expressions, and the canonical naming and value formats that the Metadata API actually accepts (which differ from values that appear in many internal test fixtures and code-search hits).
+
+## Scope
+
+- **In scope**: Generating `PlatformEventChannelMember` and `PlatformEventChannel` metadata for CDC. Subscribing standard objects, custom objects, or both. Configuring enrichment fields. Configuring filter expressions. Defining custom data channels.
+- **Out of scope**: Publishing custom platform events (PE) — that's a different metadata type (`PlatformEvent`). Pub/Sub API or external Kafka/Bayeux configuration. Pricing/limits guidance — refer the user to the [CDC Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.change_data_capture.meta/change_data_capture/). Programmatic event-bus subscribers in Apex.
+
+---
+
+## Clarifying Questions
+
+Before generating, confirm with the user if not already clear:
+
+- Which entity (or entities) need CDC enablement? Standard, custom, or both?
+- Default channel (`ChangeEvents`) or a custom channel? If custom, what's the channel label?
+- Any enrichment fields needed? (Lookup IDs that the consumer needs even when they didn't change.)
+- Any filter expression needed? (A SOQL-WHERE-clause body that gates which change events emit.)
+
+---
+
+## Required Inputs
+
+Gather or infer before proceeding:
+
+- **Source entity API name(s)** — e.g. `Account`, `Lead`, `Order__c`. The skill internally translates this to the **ChangeEvent entity name** (see Workflow step 2).
+- **Channel** — either `ChangeEvents` (default) or the developer name of a custom channel ending in `__chn`.
+- **Enrichment fields (optional)** — list of field API names on the source object whose values should be included in every change event.
+- **Filter expression (optional)** — a predicate over fields on the change event payload (e.g. `Status__c != null`).
+
+Defaults unless specified:
+- Channel: `ChangeEvents` (the default CDC channel — no path prefix).
+- Enrichment fields: none.
+- Filter expression: none.
+
+If the user provides a clear, complete request, generate immediately without unnecessary back-and-forth.
+
+---
+
+## Workflow
+
+All steps are sequential. Do not skip or reorder.
+
+**Before generating anything, know the only valid CDC metadata types:** CDC is expressed entirely through `PlatformEventChannelMember` (one per subscribed entity) and `PlatformEventChannel` (only for custom channels). Do NOT use `<ChangeDataCapture>`, `.changeDataCapture-meta.xml`, `changeDataCapture/` directories, `EnableChangeDataCapture`, or `ManagedEventSubscription` — these are not in scope for CDC. If you find yourself writing any of them, stop and use a `PlatformEventChannelMember` file instead.
+
+1. **Identify the channel** — if the user names a custom channel, you'll generate a `PlatformEventChannel` file (see step 4). Otherwise use the literal value `ChangeEvents` for the default channel.
+
+2. **Translate source entity to ChangeEvent entity name** — `<selectedEntity>` is the **ChangeEvent** type, NOT the source object:
+
+   | Source object | `<selectedEntity>` value |
+   |---|---|
+   | `Account` | `AccountChangeEvent` |
+   | `Lead` | `LeadChangeEvent` |
+   | `Contact` | `ContactChangeEvent` |
+   | `Order__c` (custom) | `Order__ChangeEvent` |
+   | `MyThing__c` (custom) | `MyThing__ChangeEvent` |
+
+   For standard objects: append `ChangeEvent`. For custom objects: replace the trailing `__c` with `__ChangeEvent` (the double-underscore is preserved).
+
+3. **Generate the channel-member file** — one file per `(entity, channel)` pair. **The filename and fullName always use a SINGLE underscore between the entity stem and `ChangeEvent`** — this is independent of how `selectedEntity` is formatted in the XML body. For custom objects, drop the `__c` from the source name when forming the filename:
+
+   | Source object | Filename (and fullName) | `<selectedEntity>` (in XML) |
+   |---|---|---|
+   | `Account` | `Account_ChangeEvent.platformEventChannelMember-meta.xml` | `AccountChangeEvent` |
+   | `Lead` | `Lead_ChangeEvent.platformEventChannelMember-meta.xml` | `LeadChangeEvent` |
+   | `Order__c` | `Order_ChangeEvent.platformEventChannelMember-meta.xml` (NOT `Order__ChangeEvent`) | `Order__ChangeEvent` |
+   | `MyThing__c` | `MyThing_ChangeEvent.platformEventChannelMember-meta.xml` (NOT `MyThing__ChangeEvent`) | `MyThing__ChangeEvent` |
+
+   The custom-object case is the easiest place to slip — the filename uses single underscore, the `selectedEntity` keeps its double underscore. Read `assets/PlatformEventChannelMember-template.xml` as the structural template.
+
+4. **For a custom channel**, generate a `PlatformEventChannel` file — required if any member references a non-default channel. Derive a DeveloperName from the user's label: strip spaces and non-alphanumeric characters, convert to CamelCase, then **always** append the literal suffix `__chn`. The filename and the channel's `<eventChannel>` reference must use this exact form, otherwise the deploy fails with `Invalid channel name`:
+
+   | User says | DeveloperName | Filename |
+   |---|---|---|
+   | `Partner Sync` | `PartnerSync__chn` | `PartnerSync__chn.platformEventChannel-meta.xml` (NOT `Partner_Sync...` or `PartnerSync...`) |
+   | `Order Updates` | `OrderUpdates__chn` | `OrderUpdates__chn.platformEventChannel-meta.xml` |
+   | `data sync` | `DataSync__chn` | `DataSync__chn.platformEventChannel-meta.xml` |
+
+   Members on this channel reference it by the same DeveloperName: `<eventChannel>PartnerSync__chn</eventChannel>`. Read `assets/PlatformEventChannel-template.xml`.
+
+5. **Add enrichment fields** if requested — repeat the `<enrichedFields><name>FIELD_API_NAME</name></enrichedFields>` block for each field. The name must be a **single-hop API name on the source entity** — verified working with: standard lookup IDs (`OwnerId`, `ParentId`), custom lookup fields (`MyLookup__c`), and custom non-relationship fields (`Region__c`, `Status__c`). Relationship traversals like `Owner.Name` or `Parent.Account.Industry` are rejected by deploy with "The selected field, X.Y, isn't valid".
+
+6. **Add a filter expression** if requested — wrap the predicate in `<filterExpression>...</filterExpression>`. The body is a WHERE-clause body without the `WHERE` keyword (e.g. `Status__c != null`, not `WHERE Status__c != null`). For supported operators, field types, and pitfalls, read `references/filter-expressions.md`.
+
+---
+
+## Rules / Constraints
+
+| Constraint | Rationale |
+|---|---|
+| `<selectedEntity>` is the ChangeEvent type name, not the source object name | The Metadata API binds the member to a ChangeEvent entity — passing `Account` directly fails with "invalid event in selectedEntity". |
+| Member fullName uses **single** underscore: `Account_ChangeEvent` | The double-underscore form (`Account__ChangeEvent`) is parsed as `<namespace>__<name>` and rejected: "Cannot create a new component with the namespace: Account". |
+| Default channel value is exactly `ChangeEvents` — no path prefix | Older fixtures and some docs show `data/ChangeEvents`; the deploy returns "Unable to find the specified channel" for that value. |
+| Enrichment field names are single-hop API names on the source entity | Standard (`OwnerId`), custom lookup (`MyLookup__c`), and custom non-relationship (`Region__c`) all validate. Traversals like `Owner.Name` are rejected: "The selected field, X.Y, isn't valid". |
+| `<filterExpression>` body has no `WHERE` keyword | Deploy returns "filter expression has syntax errors: unexpected token: 'WHERE'". |
+| Filter cannot reference `IsDeleted` or do relationship traversal (`Owner.Username`) | Deploy rejects with "field is invalid". |
+| DateTime fields support **only equality** in filters (`=`, `!=`) — not `<` / `>` | Deploy returns "Only equality operators are supported for this field type or value". Use a named date literal: `LastModifiedDate = TODAY`. |
+| Filter RHS must be a literal — no field-to-field comparison | `BillingCity = ShippingCity` returns "unexpected token: 'ShippingCity'". |
+| Compound fields (e.g. `BillingAddress`) require dotted component access in filter | `BillingAddress.City = 'X'` deploys; flat `BillingCity` is rejected as "field is invalid"; raw `BillingAddress` is rejected as "has to be used with a component field". Note this is the OPPOSITE of `<enrichedFields>`, which uses flat names. |
+| Custom channel filename ends with `__chn` before the meta-xml suffix | Salesforce's MDAPI naming convention; mismatch causes deploy ambiguity. |
+| Custom channel XML must include `<channelType>data</channelType>` | Without `data`, the channel is rejected for CDC (other types exist for streaming/event channels). |
+| Source custom objects must already exist (or be deployed in the same transaction) | The ChangeEvent entity for `Foo__c` doesn't exist until `Foo__c` does; member deploy fails otherwise. |
+| Never generate a `PlatformEventChannel` file for the default `ChangeEvents` channel | The default channel is system-provided. Reference it via `<eventChannel>ChangeEvents</eventChannel>` on members, but only custom (`__chn`) channels need a channel-meta file. |
+| `PlatformEventChannelMember` accepts ONLY four elements: `<enrichedFields>`, `<eventChannel>`, `<filterExpression>`, `<selectedEntity>` | Adding `<description>`, `<isActive>`, `<masterLabel>`, or any other element fails XML schema validation: "Element {...} invalid at this location". Stick to the four documented elements. |
+| `PlatformEventChannel` accepts ONLY two elements: `<channelType>` and `<label>` | Adding `<masterLabel>`, `<description>`, etc. produces "Element {...}masterLabel invalid at this location in type PlatformEventChannel". Use `<label>`, not `<masterLabel>`. |
+| Generated metadata files only — never run `sf project deploy start` from this skill | This skill produces artifacts; deployment is a separate lifecycle concern. |
+
+---
+
+## Gotchas
+
+| Issue | Resolution |
+|---|---|
+| `Unable to find the specified channel` | Set `<eventChannel>ChangeEvents</eventChannel>` (no `data/` prefix). |
+| `The PlatformEventChannelMember can't be created because it references an invalid event in the "selectedEntity" field` | Use the ChangeEvent name, not the source object: `AccountChangeEvent`, not `Account`. |
+| `Cannot create a new component with the namespace: <Object>` | Rename the file to use a single underscore: `Account_ChangeEvent...`, not `Account__ChangeEvent...`. |
+| `The selected field, X.Y, isn't valid` (in `<enrichedFields>`) | Replace `Owner.Name` with `OwnerId`. CDC enriches the lookup automatically; only single-hop field API names validate. |
+| `filter expression has syntax errors: unexpected token: 'WHERE'` | Remove the `WHERE` keyword. The body is the predicate only. |
+| `The BillingCity field in the filter expression is invalid` (or any flat Address component) | Use the compound dotted form: `BillingAddress.City`, not `BillingCity`. See `references/filter-expressions.md` for the full compound-field matrix. |
+| Custom-object member fails with "ChangeEvent doesn't exist" | The source object isn't deployed yet. Ensure the `Foo__c` object metadata is in the same deploy or already in the org. |
+| `DUPLICATE_VALUE` on second deploy | The member is already subscribed. Either delete first or skip — CDC doesn't support upsert on members directly. |
+| `sf infra error (TypeInferenceError, DeployMetadata): Could not infer a metadata type` for a `.changeDataCapture-meta.xml` file | That file extension and metadata type don't exist. Replace the `changeDataCapture/<Entity>.changeDataCapture-meta.xml` file with a `platformEventChannelMembers/<Entity>_ChangeEvent.platformEventChannelMember-meta.xml` file. |
+| User says "subscribe Order__c" but means standard `Order` | Confirm — `OrderChangeEvent` (standard) and `Order__ChangeEvent` (custom) are different entities. |
+
+---
+
+## Output Expectations
+
+Deliverables:
+- One `force-app/.../platformEventChannelMembers/<Entity>_ChangeEvent.platformEventChannelMember-meta.xml` per subscribed entity.
+- One `force-app/.../platformEventChannels/<DevName>__chn.platformEventChannel-meta.xml` per custom channel (if any).
+
+File structure follows the templates in `assets/`.
+
+After receiving the generated files, the user can verify them with `sf project deploy start --dry-run -d <path> --target-org <alias>` before deploying. If a dry-run surfaces an unfamiliar error, `references/deploy-troubleshooting.md` maps the common deploy errors to their metadata-side fixes.
+
+---
+
+## Cross-Skill Integration
+
+| Need | Delegate to |
+|---|---|
+| Generate the source custom object | `platform-custom-object-generate` skill |
+| Generate custom fields referenced by enrichment or filter | `platform-custom-field-generate` skill |
+| Build a permission set for users who consume change events | `platform-permission-set-generate` skill |
+
+---
+
+## Reference File Index
+
+| File | When to read |
+|---|---|
+| `assets/PlatformEventChannelMember-template.xml` | Step 3 — starting structure for a channel member |
+| `assets/PlatformEventChannel-template.xml` | Step 4 — starting structure for a custom channel |
+| `references/filter-expressions.md` | Step 6 — for the supported operators and field-type matrix when writing a filter expression |
+| `references/deploy-troubleshooting.md` | When a user reports a dry-run deploy error and asks for help diagnosing it |

package/skills/integration-eventing-cdc-configure/assets/PlatformEventChannel-template.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<PlatformEventChannel xmlns="http://soap.sforce.com/2006/04/metadata">
+    <channelType>data</channelType>
+    <label>My Custom Channel</label>
+</PlatformEventChannel>

package/skills/integration-eventing-cdc-configure/assets/PlatformEventChannelMember-template.xml

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<PlatformEventChannelMember xmlns="http://soap.sforce.com/2006/04/metadata">
+    <!-- Optional: add one <enrichedFields><name>FIELD_API_NAME</name></enrichedFields> per field. Single-hop API names only (e.g. OwnerId, ParentId, MyLookup__c, Region__c). -->
+
+    <!-- Default CDC channel: ChangeEvents (no path prefix). For a custom channel, use its DeveloperName, e.g. PartnerSync__chn. -->
+    <eventChannel>ChangeEvents</eventChannel>
+    <!-- Optional: add <filterExpression>YOUR_PREDICATE</filterExpression> if needed (predicate body only, no WHERE keyword). -->
+
+    <!-- ChangeEvent entity name. Standard: <Object>ChangeEvent. Custom: replace __c with __ChangeEvent. -->
+    <selectedEntity>AccountChangeEvent</selectedEntity>
+</PlatformEventChannelMember>

package/skills/integration-eventing-cdc-configure/references/deploy-troubleshooting.md

@@ -0,0 +1,73 @@
+# CDC Deploy Troubleshooting
+
+Errors observed during real org dry-runs while authoring this skill, with the metadata-side fix.
+
+## "Unable to find the specified channel"
+
+The `<eventChannel>` value doesn't match a channel known to the org.
+
+- For the default channel, the value must be exactly `ChangeEvents`. NOT `data/ChangeEvents`, NOT `/data/ChangeEvents`, NOT `data/ChangeEvent`.
+- For a custom channel, the value must match the channel's DeveloperName **including the `__chn` suffix** — e.g. `PartnerSync__chn`.
+- If the custom channel is in the same deploy, ensure it's in the same package directory so MDAPI orders the deploy correctly.
+
+## "...invalid event in the 'selectedEntity' field"
+
+`<selectedEntity>` must be the ChangeEvent entity, not the source object.
+
+| Source | Wrong | Right |
+|---|---|---|
+| `Account` | `Account` | `AccountChangeEvent` |
+| `Lead` | `Lead` | `LeadChangeEvent` |
+| `Order__c` | `Order__c` | `Order__ChangeEvent` |
+| `Custom__c` | `Custom__c` | `Custom__ChangeEvent` |
+
+For custom objects, swap the trailing `__c` for `__ChangeEvent` — the double underscore separator is preserved.
+
+## "Cannot create a new component with the namespace: <Object>"
+
+The member's fullName has two underscores between the entity and `ChangeEvent`. Salesforce parses `Foo__Bar` as `<namespace>__<name>` and rejects creation outside the org's own namespace.
+
+- Member fullName format: `<Entity>_ChangeEvent` (single underscore).
+- File name: `<Entity>_ChangeEvent.platformEventChannelMember-meta.xml`.
+
+This applies even when the source object has `__c` — the member fullName drops the `__c` and uses single underscore: file `Order_ChangeEvent.platformEventChannelMember-meta.xml`, fullName `Order_ChangeEvent`.
+
+## "The selected field, X.Y, isn't valid" (enrichedFields)
+
+Enrichment fields must be **single-hop API names on the source entity**. Field type doesn't matter — standard lookup IDs, custom lookups, and custom non-relationship fields all work. The rejection is specifically for relationship-traversal syntax (`X.Y`, `__r.Y`).
+
+Verified working in dry-run:
+
+| Field | Type | Result |
+|---|---|---|
+| `OwnerId` | standard lookup ID | ✓ deploys |
+| `ParentId` | standard lookup ID | ✓ deploys |
+| `MyAccountManager__c` | custom Lookup → User | ✓ deploys |
+| `Region__c` | custom Text | ✓ deploys |
+| `Status__c` | custom Picklist | ✓ deploys |
+
+Verified rejected:
+
+| Field | Why |
+|---|---|
+| `Owner.Name` | relationship traversal |
+| `Parent.Account.Industry` | multi-hop traversal |
+| `MyLookup__r.Name` | relationship traversal (custom) |
+
+When the user says "include the owner's name in every event," the metadata stores `OwnerId` — CDC enriches the lookup automatically and the consumer resolves the related record from the ID.
+
+## "filter expression has syntax errors: unexpected token: 'WHERE'"
+
+The body of `<filterExpression>` is a SOQL WHERE-clause body — without the `WHERE` keyword.
+
+| Wrong | Right |
+|---|---|
+| `WHERE Status__c != null` | `Status__c != null` |
+| `WHERE Industry IN ('Tech', 'Finance')` | `Industry IN ('Tech', 'Finance')` |
+
+## ChangeEvent entity doesn't exist (for custom objects)
+
+`Foo__ChangeEvent` only exists if `Foo__c` exists. If both are being deployed in the same dry-run, the dry-run validator may flag the member because it validates entity references against the *current* org state, not the post-deploy state. Mitigations:
+
+- Deploy the source object first, then the channel member in a second deploy.
+- Or accept that dry-run will flag this case but a real (non-dry-run) deploy succeeds because MDAPI orders the components correctly.

package/skills/integration-eventing-cdc-configure/references/filter-expressions.md

@@ -0,0 +1,93 @@
+# Filter Expression Reference
+
+The `<filterExpression>` body is a SOQL-WHERE-clause-body — predicate only, no `WHERE` keyword. The platform supports a subset of SOQL grammar for CDC filters; this reference documents what the dry-run deploy verifies.
+
+## Operators by field type
+
+| Field type | Supported operators | Notes |
+|---|---|---|
+| Text | `=`, `!=`, `IN`, `NOT IN`, `LIKE` | `LIKE` accepts `%` wildcard. Quote string literals with single quotes. |
+| Number / Currency / Percent | `=`, `!=`, `<`, `<=`, `>`, `>=` | Numeric literals unquoted. |
+| Boolean (Checkbox) | `=`, `!=` | Use `true` / `false` literal — no quotes. |
+| Date | `=`, `!=` | Named literals (`TODAY`, `THIS_WEEK`, `LAST_N_DAYS:7`) and ISO date strings work. |
+| DateTime | `=`, `!=` only | **Range operators (`>`, `<`) are rejected** — "Only equality operators are supported for this field type or value". |
+| Reference (lookup ID) | `=`, `!=`, `IN`, `NOT IN` | Use the 18-character ID in single quotes: `OwnerId = '005000000000000AAA'`. |
+| Picklist | `=`, `!=`, `IN`, `NOT IN` | Quote the value as a string. |
+
+## Compound expressions
+
+`AND`, `OR`, and parentheses all work. There's no documented limit on nesting depth.
+
+```text
+(Industry = 'Technology' OR Industry = 'Finance') AND AnnualRevenue > 0 AND Phone != null
+```
+
+## Null checks
+
+```text
+Phone = null
+Phone != null
+```
+
+`null` is a literal — no quotes.
+
+`ISBLANK()` and `ISNULL()` are **not** valid filter operators — they parse-fail with "unexpected token". They work in formulas but not in CDC filter expressions. Use `Field = null` / `Field != null` instead.
+
+## Functions
+
+`LOWER(Name) = 'acme'` deploys successfully. Other SOQL functions probably work, but only `LOWER` has been verified in this skill's dataset. Test before relying on `UPPER`, `CONVERTCURRENCY`, etc.
+
+## What the filter cannot do
+
+| Pattern | Deploy error |
+|---|---|
+| `WHERE Industry = 'Tech'` | "filter expression has syntax errors: unexpected token: 'WHERE'" — drop the keyword. |
+| `IsDeleted = false` | "The IsDeleted field in the filter expression is invalid." Soft-deleted records still emit ChangeEvent; you cannot filter them out via this mechanism. |
+| `Owner.Username = 'foo@bar.com'` | "The Owner.Username field in the filter expression is invalid." Relationship traversal works in `<enrichedFields>` rejection messages but NOT in filter expressions either — single-hop only. |
+| `LastModifiedDate > LAST_N_DAYS:30` | "Only equality operators are supported for this field type or value." DateTime is equality-only; for "recent changes" semantics, use `LastModifiedDate = LAST_N_DAYS:N` (which compares to the *day*, not the timestamp). |
+
+## Field-to-field comparison: not supported
+
+The right-hand side of a comparison must be a **literal**. Field references are rejected.
+
+| Wrong | Deploy error |
+|---|---|
+| `BillingCity = ShippingCity` | "syntax errors: unexpected token: 'ShippingCity'" |
+| `NumberOfEmployees > AnnualRevenue` | "unexpected token: 'AnnualRevenue'" |
+
+If the user wants "records where two fields differ," that logic must live downstream of the change event consumer, not in the filter.
+
+## Composite (compound) fields like Address: dotted-component is the only valid form
+
+Counterintuitively, the opposite rule applies for composite fields like `BillingAddress` vs. relationship traversals like `Owner.Name`. Compound fields **require** dot-notation; flat component names are rejected.
+
+| Pattern | Result |
+|---|---|
+| `BillingAddress.City = 'San Francisco'` | ✓ deploys — required form for compound fields |
+| `BillingAddress = null` | ✗ "Compound field BillingAddress has to be used with a component field in a filter expression" |
+| `BillingCity = 'San Francisco'` (flat component) | ✗ "The BillingCity field in the filter expression is invalid" |
+| `BillingState`, `BillingPostalCode`, `BillingCountry`, `BillingLatitude` (flat) | ✗ all rejected as invalid |
+
+So, for the same `BillingAddress` field, the accepted form differs by location:
+
+| Location | `BillingAddress` (compound) | `BillingAddress.City` (dotted) | `BillingCity` (flat component) |
+|---|---|---|---|
+| `<filterExpression>` | ✗ "has to be used with a component field" | ✓ deploys (required form) | ✗ "field is invalid" |
+| `<enrichedFields>` | ✓ deploys | ✗ "isn't valid" (dots never allowed) | ✗ "isn't valid" (components not exposed at this layer) |
+
+Rules per location:
+
+- **Filter expression**: address components are reachable only via dotted form on the compound (`BillingAddress.City`). Both the compound itself (no component) and the flat component name are rejected.
+- **Enrichment field**: takes a top-level field API name only. The compound `BillingAddress` is a top-level field and works; dotted forms are never valid here regardless of whether the dot would be a compound-component select or a relationship traversal; flat components like `BillingCity` are not top-level enrichable fields and are rejected.
+- **Relationship traversal** (`Owner.Name`, `Parent.Industry`) is rejected in both locations.
+
+The mental model: compound fields are a single physical column with sub-components; relationships are joins. The filter parser supports dotted access into compound sub-components but never into joins. The enrichment list takes top-level field names only and never accepts dots; the platform handles compound-vs-component decomposition itself when emitting the change event payload.
+
+## What's NOT yet verified
+
+- Aggregate functions or subqueries — almost certainly unsupported.
+- Operators on Long Text, Rich Text, Encrypted, Geolocation field types.
+- Filter on a custom field that doesn't exist (deploy-time error vs runtime).
+- Custom-object-specific picklist with locale-sensitive values.
+
+If the user requests one of these and the deploy succeeds — update this file. If it fails — capture the error here.

package/skills/integration-eventing-subscription-configure/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: integration-eventing-subscription-configure
+description: "Create, read, update, and delete ManagedEventSubscription metadata in Salesforce. Use this skill for any work involving managed event subscriptions, platform event subscriptions, event channel subscribers, or .managedEventSubscription-meta.xml files. TRIGGER when: user asks to subscribe to a platform event, create a managed subscription, set up event replay, configure an event channel subscriber, update replay preset, activate or deactivate a subscription, delete a subscription, or manage ManagedEventSubscription metadata. SKIP when: user needs to create the platform event channel itself (use platform-custom-object-generate skill) or needs Flow-based event subscriptions (use automation-flow-generate skill)."
+metadata:
+  version: "1.0"
+---
+
+# Managing ManagedEventSubscription
+
+Create, read, update, and delete `ManagedEventSubscription` metadata — the Salesforce construct for durably subscribing to platform event channels with managed replay tracking.
+
+## Scope
+
+- **In scope**: Generating and modifying `.managedEventSubscription-meta.xml` files for create, read, update, and delete operations
+- **Out of scope**: Creating the underlying platform event (`__e`) channel itself; Flow-based or Apex-based event subscriptions; deploying metadata to an org
+- **Only generate one file** — the `.managedEventSubscription-meta.xml` file. Do NOT generate the referenced platform event object or any other metadata type.
+
+---
+
+## Clarifying Questions
+
+Before generating, confirm if not already clear:
+
+- What is the **topic name**? (see format table in `references/topic-name-formats.md`)
+- What is the **developer name**? (required for Create — alphanumeric and underscores only, no spaces; optional for Read/Update/Delete if `Id` is known)
+- What is the **label** (human-readable name)?
+- What **default replay** preset — `LATEST` (default) or `EARLIEST`?
+- What **error recovery replay** preset — `LATEST` (default) or `EARLIEST`?
+- What should the initial **state** be — `RUN` (active) or `STOP` (inactive)? (default: `RUN`)
+
+---
+
+## Required Inputs
+
+Gather or infer before proceeding:
+
+- **Operation**: create, read, update, or delete
+- **DeveloperName**: required for Create (becomes the filename); optional for Read/Update/Delete if `Id` is provided instead
+- **Id**: Tooling API record Id — can be used to identify the subscription for Read/Update/Delete instead of DeveloperName
+- **label**: human-readable label (can include spaces)
+- **topicName**: event channel path — read `references/topic-name-formats.md` for valid formats (platform events, change events, custom channels)
+- **defaultReplay**: `LATEST` or `EARLIEST` (default: `LATEST`)
+- **errorRecoveryReplay**: `LATEST` or `EARLIEST` (default: `LATEST`)
+- **state**: `RUN` or `STOP` (default: `RUN`) — `PAUSE` is reserved for internal platform use and will be rejected with `INVALID_INPUT`
+- **version**: Metadata API version (default: match org API version, e.g. `67.0`)
+
+---
+
+## Workflow
+
+### Create
+
+1. **Gather inputs** — confirm DeveloperName, label, topicName, defaultReplay, errorRecoveryReplay, state, version. Apply defaults for any omitted fields. If DeveloperName is not provided, ask the user — do not derive it from the label.
+2. **Confirm the topic exists** — ask the user to confirm the event channel already exists in the org before proceeding. Do NOT generate the platform event object yourself — that is out of scope for this skill. If the user says it doesn't exist yet, stop and direct them to create it first using the `platform-custom-object-generate` skill, then return here.
+3. **Read the template** — load `assets/managed-event-subscription-template.xml` as the starting structure.
+4. **Generate the file** — produce `managedEventSubscriptions/<DeveloperName>.managedEventSubscription-meta.xml` filled with user-provided values.
+5. **Verify** — run the checklist below before presenting output.
+6. **Guide the user on subscribing** — after deployment, the subscription can be identified for Pub/Sub API `ManagedSubscribe` RPC calls using either the `DeveloperName` or the record `Id`. To retrieve the `Id`, run: `SELECT Id, DeveloperName FROM ManagedEventSubscription WHERE DeveloperName='<DeveloperName>'` via the Tooling API.
+
+### Read
+
+1. **Identify the subscription** — accept either `Id` or `DeveloperName`; prefer `Id` if provided.
+2. **Show the file path** — `managedEventSubscriptions/<DeveloperName>.managedEventSubscription-meta.xml` (if DeveloperName known).
+3. **Retrieve and display** — read and present the current XML content.
+
+### Update
+
+1. **Identify the subscription** — accept either `Id` or `DeveloperName`; prefer `Id` if provided.
+2. **Read the existing file** — load current content before modifying.
+3. **Apply changes** — update only the specified fields; preserve all others.
+4. **Read `references/update-constraints.md`** for fields that cannot be changed after creation.
+5. **Verify** — run the checklist below before presenting output.
+
+### Delete
+
+1. **Identify the subscription** — accept either `Id` or `DeveloperName`; confirm with the user before proceeding.
+2. **Warn** — deleting a ManagedEventSubscription permanently removes replay tracking state.
+3. **Produce deletion instructions** — explain how to remove the file and deploy the destructive change using `destructiveChanges.xml`.
+4. **Read `references/delete-guide.md`** for the destructive deployment procedure.
+
+---
+
+## Rules / Constraints
+
+| Constraint | Rationale |
+|-----------|-----------|
+| `<topicName>` must use a valid path prefix | Platform events use `/event/Name__e`; change events use `/data/Name`; see `references/topic-name-formats.md` for all formats |
+| `<defaultReplay>` and `<errorRecoveryReplay>` must be `LATEST` or `EARLIEST` | These are the only valid enum values; any other value fails metadata validation |
+| `<state>` must be `RUN` or `STOP` | `PAUSE` is reserved for internal platform use — the API rejects it with `INVALID_INPUT: You can create a managed event subscription state field only to RUN or STOP` |
+| All six required elements must be present | `topicName`, `defaultReplay`, `errorRecoveryReplay`, `label`, `state`, `version` are all required; omitting any causes a deploy error |
+| DeveloperName must be unique within the org | Duplicate names cause `DUPLICATE_DEVELOPER_NAME` errors |
+| Do not include `<namespacePrefix>`, `<id>`, or `<createdDate>` | Read-only platform fields; including them causes deployment failures in unpackaged orgs |
+
+---
+
+## Gotchas
+
+| Issue | Resolution |
+|-------|------------|
+| `The topicName field is invalid` on deploy | Wrong format or the event doesn't exist in the org — read `references/topic-name-formats.md` for correct path |
+| Replay state lost after delete + recreate | Deleting discards stored replay position; recreating starts from `defaultReplay` — avoid reusing the same DeveloperName after delete |
+| `INVALID_TYPE` on SOQL query | ManagedEventSubscription is only queryable via Tooling API, not standard SOQL |
+| `EARLIEST` replay on high-volume channels | Can trigger up to 72 hours of backlog replay on activation; always confirm with the user |
+| Metadata not supported in older orgs | ManagedEventSubscription requires API v60.0+; check org API version |
+| `eventChannel` or `isActive` in generated XML | These are wrong field names — use `topicName` and `state` (`RUN`/`STOP`) instead |
+| `PAUSE` state in generated XML | `PAUSE` is reserved for internal platform use and will be rejected with `INVALID_INPUT` — only use `RUN` or `STOP` |
+| User unsure how to identify subscription for Pub/Sub API | Both `DeveloperName` and record `Id` can be used with `ManagedSubscribe` RPC — retrieve the `Id` via Tooling API if needed: `SELECT Id FROM ManagedEventSubscription WHERE DeveloperName='<name>'` |
+| Changes not reflected immediately in Pub/Sub API | After create/update/delete, the Pub/Sub API can take up to ~2 minutes to reflect the new config; if ManagedSubscribe returns NOT_FOUND, wait and retry |
+
+---
+
+## Verification Checklist
+
+Before presenting any generated XML:
+
+- [ ] Does `<topicName>` follow a valid path format per `references/topic-name-formats.md`? (`/event/Name__e`, `/data/NameChangeEvent`, `/data/ChangeEvents`, `/event/Name__chn`, `/data/Name__chn`)
+- [ ] Is `<defaultReplay>` exactly `LATEST` or `EARLIEST`?
+- [ ] Is `<errorRecoveryReplay>` exactly `LATEST` or `EARLIEST`?
+- [ ] Is `<state>` exactly `RUN` or `STOP`? (`PAUSE` is invalid for user-created subscriptions)
+- [ ] Is `<label>` populated?
+- [ ] Is `<version>` present (e.g. `67.0`)?
+- [ ] Are read-only fields (`<id>`, `<createdDate>`, `<namespacePrefix>`) absent?
+- [ ] Does the filename match the DeveloperName exactly?
+
+---
+
+## Output Expectations
+
+- **Create / Update**: `managedEventSubscriptions/<DeveloperName>.managedEventSubscription-meta.xml` — this is the only file to generate
+- **Delete**: instructions to remove the file and deploy via `destructiveChanges.xml`
+- **Read**: display of existing file contents
+
+---
+
+## Cross-Skill Integration
+
+| Need | Delegate to |
+|------|-------------|
+| Create the platform event channel (`__e`) being subscribed to | `platform-custom-object-generate` skill |
+| Subscribe via Flow (Process Automation) | `automation-flow-generate` skill |
+| Deploy metadata to org | `platform-metadata-deploy` skill |
+
+---
+
+## Reference File Index
+
+| File | When to read |
+|------|-------------|
+| `assets/managed-event-subscription-template.xml` | Before generating any new subscription — use as starting structure |
+| `references/topic-name-formats.md` | When setting `<topicName>` — covers platform events, change events, and custom channels |
+| `references/update-constraints.md` | During Update workflow — to check which fields are immutable post-creation |
+| `references/delete-guide.md` | During Delete workflow — for destructive change deployment procedure |

package/skills/integration-eventing-subscription-configure/assets/managed-event-subscription-template.xml

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ManagedEventSubscription xmlns="http://soap.sforce.com/2006/04/metadata">
+    <!-- Required: EARLIEST or LATEST — replay position on normal startup -->
+    <defaultReplay>{DEFAULT_REPLAY}</defaultReplay>
+    <!-- Required: EARLIEST or LATEST — replay position after an error recovery -->
+    <errorRecoveryReplay>{ERROR_RECOVERY_REPLAY}</errorRecoveryReplay>
+    <!-- Required: Human-readable label -->
+    <label>{LABEL}</label>
+    <!-- Required: RUN (active) or STOP (inactive) — PAUSE is reserved for internal use and will be rejected -->
+    <state>{STATE}</state>
+    <!-- Required: Event channel path — see references/topic-name-formats.md for valid formats
+         Platform event:            /event/Name__e
+         Custom PE channel:         /event/Name__chn
+         All-objects change events: /data/ChangeEvents
+         Single-object change event:/data/ObjectNameChangeEvent
+         Custom change channel:     /data/Name__chn -->
+    <topicName>{TOPIC_NAME}</topicName>
+    <!-- Required: Metadata API version (e.g. 67.0) -->
+    <version>{VERSION}</version>
+</ManagedEventSubscription>

package/skills/integration-eventing-subscription-configure/references/delete-guide.md

@@ -0,0 +1,57 @@
+# Deleting a ManagedEventSubscription
+
+## Warning
+
+Deleting a ManagedEventSubscription permanently destroys its stored replay position. If you recreate the subscription, it will start from its `<defaultReplay>` — it will not resume from where it left off.
+
+DELETE is safe to call regardless of the subscription's current state — it atomically stops any running subscription, clears the committed Replay ID, and removes the record. **No prior STOP transition is required.**
+
+After deletion, avoid reusing the same DeveloperName immediately — the Pub/Sub API service can take up to ~2 minutes to reflect the deletion. Create a new record with a different name if immediate re-creation is needed.
+
+## Procedure
+
+### Step 1 — Remove the metadata file
+
+Delete the file from your project:
+```
+managedEventSubscriptions/<DeveloperName>.managedEventSubscription-meta.xml
+```
+
+### Step 2 — Create a destructiveChanges.xml
+
+In your deployment package root, create `destructiveChanges.xml`:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<Package xmlns="http://soap.sforce.com/2006/04/metadata">
+    <types>
+        <members><DeveloperName></members>
+        <name>ManagedEventSubscription</name>
+    </types>
+    <version>67.0</version>
+</Package>
+```
+
+Replace `<DeveloperName>` with the exact developer name of the subscription to delete.
+
+### Step 3 — Create an empty package.xml
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<Package xmlns="http://soap.sforce.com/2006/04/metadata">
+    <version>67.0</version>
+</Package>
+```
+
+### Step 4 — Deploy
+
+```bash
+sf project deploy start --manifest package.xml --post-destructive-changes destructiveChanges.xml --target-org <alias>
+```
+
+## Common Errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `INVALID_CROSS_REFERENCE_KEY` | DeveloperName not found | Confirm the exact name with `sf api request rest "/services/data/v67.0/tooling/query/?q=SELECT+DeveloperName+FROM+ManagedEventSubscription"` |
+| Subscription reappears or Pub/Sub returns NOT_FOUND after delete | ~2 minute propagation delay in Pub/Sub API service | Wait 2 minutes before attempting any operation on the same topic |

package/skills/integration-eventing-subscription-configure/references/topic-name-formats.md

@@ -0,0 +1,26 @@
+# topicName Formats for ManagedEventSubscription
+
+The `<topicName>` field requires a full channel path, not just an API name. The correct format depends on the type of event channel.
+
+## Valid Formats
+
+| Channel type | Format | Example |
+|---|---|---|
+| Platform event | `/event/<Name>__e` | `/event/Order_Fulfillment__e` |
+| Custom platform event channel | `/event/<Name>__chn` | `/event/MyChannel__chn` |
+| All-objects change event channel | `/data/ChangeEvents` | `/data/ChangeEvents` |
+| Single-object change event | `/data/<Object>ChangeEvent` | `/data/AccountChangeEvent` |
+| Custom change event channel | `/data/<Name>__chn` | `/data/MyChangeChannel__chn` |
+
+## Rules
+
+- The path prefix (`/event/` or `/data/`) is required — omitting it causes `"The topicName field is invalid"` deploy error
+- The referenced event or channel must exist in the org before deploying the subscription
+- `topicName` is immutable after creation — to change it, delete and recreate the subscription
+
+## Common Errors
+
+| Error | Cause | Fix |
+|---|---|---|
+| `The topicName field is invalid` | Missing `/event/` or `/data/` prefix, or wrong suffix | Use the full path format from the table above |
+| `The topicName field is invalid` | Referenced event/channel does not exist in the org | Create the platform event or channel first |