@salesforce/afv-skills 1.16.0 → 1.18.0

package/skills/managing-cdc-enablement/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/managing-cdc-enablement/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/observing-agentforce/SKILL.md

@@ -4,7 +4,6 @@ description: "Analyze production Agentforce agent behavior using session traces
 allowed-tools: Bash Read Write Edit Glob Grep
 metadata:
   version: "1.0"
-  last_updated: "2026-04-08"
   argument-hint: "<org-alias> [--agent-file <path>] [--session-id <id>] [--days <n>]"
   compatibility: claude-code
 ---

package/skills/observing-agentforce/references/stdm-queries.md

@@ -23,18 +23,10 @@ Methods:
 # Ensure the classes directory exists
 mkdir -p <project-root>/force-app/main/default/classes
 
-# Copy from the installed skill location
-cp skills/observing-agentforce/apex/AgentforceOptimizeService.cls \
+# Copy from the skill's apex directory
+cp ../apex/AgentforceOptimizeService.cls \
    <project-root>/force-app/main/default/classes/
-cp skills/observing-agentforce/apex/AgentforceOptimizeService.cls-meta.xml \
-   <project-root>/force-app/main/default/classes/
-```
-
-If the skill is installed globally via the installer, use the installed path:
-```bash
-cp ~/.claude/skills/observing-agentforce/apex/AgentforceOptimizeService.cls \
-   <project-root>/force-app/main/default/classes/
-cp ~/.claude/skills/observing-agentforce/apex/AgentforceOptimizeService.cls-meta.xml \
+cp ../apex/AgentforceOptimizeService.cls-meta.xml \
    <project-root>/force-app/main/default/classes/
 ```
 

package/skills/orchestrating-datacloud/README.md

@@ -63,14 +63,12 @@ These are intentionally generic and should be adapted to the target org.
 
 ## Quick start
 
-> The script examples below assume the skill is installed under `~/.claude/skills/` via the full Claude Code installer. If you are working from a repo checkout, run the same scripts from that checkout path.
-
 ### 1. Verify the runtime
 
 ```bash
-bash ~/.claude/skills/orchestrating-datacloud/scripts/verify-plugin.sh
+bash ./scripts/verify-plugin.sh
 # or with an org alias
-bash ~/.claude/skills/orchestrating-datacloud/scripts/verify-plugin.sh myorg
+bash ./scripts/verify-plugin.sh myorg
 ```
 
 The helper treats `sf data360 doctor` as advisory and falls back to additional read-only smoke checks when an org is only partially provisioned.
@@ -78,9 +76,9 @@ The helper treats `sf data360 doctor` as advisory and falls back to additional r
 ### 2. Diagnose feature readiness before mutating
 
 ```bash
-node ~/.claude/skills/orchestrating-datacloud/scripts/diagnose-org.mjs -o myorg --json
+node ./scripts/diagnose-org.mjs -o myorg --json
 # optional retrieve-plane probe, only when you know the table is real
-node ~/.claude/skills/orchestrating-datacloud/scripts/diagnose-org.mjs -o myorg --phase retrieve --describe-table MyDMO__dlm --json
+node ./scripts/diagnose-org.mjs -o myorg --phase retrieve --describe-table MyDMO__dlm --json
 ```
 
 Use the diagnose helper to distinguish between:
@@ -94,7 +92,7 @@ Use the diagnose helper to distinguish between:
 ```bash
 python3 ~/.claude/sf-skills-install.py --with-datacloud-runtime
 # or run the helper script directly
-bash ~/.claude/skills/orchestrating-datacloud/scripts/bootstrap-plugin.sh
+bash ./scripts/bootstrap-plugin.sh
 ```
 
 ### 4. Start with read-only inspection

package/skills/orchestrating-datacloud/SKILL.md

@@ -92,7 +92,7 @@ Recommended checks:
 ```bash
 sf data360 man
 sf org display -o <alias>
-bash ~/.claude/skills/orchestrating-datacloud/scripts/verify-plugin.sh <alias>
+bash ./scripts/verify-plugin.sh <alias>
 ```
 
 Treat `sf data360 doctor` as a broad health signal, not the sole gate. On partially provisioned orgs it can fail even when read-only command families like connectors, DMOs, or segments still work.
@@ -100,12 +100,12 @@ Treat `sf data360 doctor` as a broad health signal, not the sole gate. On partia
 ### 2. Classify readiness before changing anything
 Run the shared classifier first:
 ```bash
-node ~/.claude/skills/orchestrating-datacloud/scripts/diagnose-org.mjs -o <org> --json
+node ./scripts/diagnose-org.mjs -o <org> --json
 ```
 
 Only use a query-plane probe after you know the table name is real:
 ```bash
-node ~/.claude/skills/orchestrating-datacloud/scripts/diagnose-org.mjs -o <org> --phase retrieve --describe-table MyDMO__dlm --json
+node ./scripts/diagnose-org.mjs -o <org> --phase retrieve --describe-table MyDMO__dlm --json
 ```
 
 Use the classifier to distinguish:

package/skills/orchestrating-datacloud/references/feature-readiness.md

@@ -27,13 +27,13 @@ Examples:
 Run the shared readiness classifier before mutation-heavy work:
 
 ```bash
-node ~/.claude/skills/orchestrating-datacloud/scripts/diagnose-org.mjs -o myorg --json
+node ../scripts/diagnose-org.mjs -o myorg --json
 ```
 
 For retrieve/query work, only add a table probe when you already know the table name is real:
 
 ```bash
-node ~/.claude/skills/orchestrating-datacloud/scripts/diagnose-org.mjs -o myorg --phase retrieve --describe-table MyDMO__dlm --json
+node ../scripts/diagnose-org.mjs -o myorg --phase retrieve --describe-table MyDMO__dlm --json
 ```
 
 ## Signal matrix

package/skills/orchestrating-datacloud/references/plugin-setup.md

@@ -18,8 +18,6 @@ The orchestrating-datacloud family uses a **community `sf data360` CLI runtime**
 
 ## Recommended setup path
 
-The command examples below assume the skill is installed under `~/.claude/skills/` via the full Claude Code installer. If you are working from a cloned sf-skills repo instead, run the same scripts from that checkout path.
-
 If you use the Python installer, it can install this optional runtime for you:
 
 ```bash
@@ -29,7 +27,7 @@ python3 ~/.claude/sf-skills-install.py --with-datacloud-runtime
 Or use the helper script directly:
 
 ```bash
-bash ~/.claude/skills/orchestrating-datacloud/scripts/bootstrap-plugin.sh
+bash ../scripts/bootstrap-plugin.sh
 ```
 
 By default it clones the plugin into `~/.sf-community-tools/datacloud/sf-cli-plugin-data360`, installs dependencies, compiles it, and links it into the local Salesforce CLI.
@@ -41,7 +39,7 @@ git clone https://github.com/Jaganpro/sf-cli-plugin-data360.git
 cd sf-cli-plugin-data360
 yarn install
 npx tsc
-node ~/.claude/skills/orchestrating-datacloud/scripts/generate-manifest.mjs .
+node ../scripts/generate-manifest.mjs .
 sf plugins link .
 ```
 
@@ -49,9 +47,9 @@ sf plugins link .
 
 ```bash
 sf data360 man
-bash ~/.claude/skills/orchestrating-datacloud/scripts/verify-plugin.sh
-bash ~/.claude/skills/orchestrating-datacloud/scripts/verify-plugin.sh myorg
-node ~/.claude/skills/orchestrating-datacloud/scripts/diagnose-org.mjs -o myorg --json
+bash ../scripts/verify-plugin.sh
+bash ../scripts/verify-plugin.sh myorg
+node ../scripts/diagnose-org.mjs -o myorg --json
 ```
 
 For newer command families such as `sf data360 query hybrid` and recent pagination fixes, update the community runtime to the latest upstream commit by re-running the bootstrap helper.
@@ -80,7 +78,7 @@ sf data360 segment list -o myorg 2>/dev/null
 If you see `Warning: @gthoppae/sf-cli-plugin-data360 is a linked ESM module and cannot be auto-transpiled`, generate the oclif command manifest:
 
 ```bash
-node ~/.claude/skills/orchestrating-datacloud/scripts/generate-manifest.mjs ~/.sf-community-tools/datacloud/sf-cli-plugin-data360
+node ../scripts/generate-manifest.mjs ~/.sf-community-tools/datacloud/sf-cli-plugin-data360
 ```
 
 This tells oclif to use pre-compiled output directly instead of attempting auto-transpilation. The `npx oclif manifest` alternative may fail on newer Node.js versions due to `@oclif/core` version mismatches.

package/skills/orchestrating-datacloud/scripts/diagnose-org.mjs

@@ -257,7 +257,7 @@ function guidanceFromProbe(scope, probe) {
   if (probe.state === 'runtime_missing') {
     return [
       'Install or relink the community sf data360 runtime before attempting Data Cloud work.',
-      'Use python3 ~/.claude/sf-skills-install.py --with-datacloud-runtime or bash ~/.claude/skills/orchestrating-datacloud/scripts/bootstrap-plugin.sh.',
+      'Use python3 ~/.claude/sf-skills-install.py --with-datacloud-runtime or bash ./scripts/bootstrap-plugin.sh.',
     ];
   }
 

package/skills/orchestrating-datacloud/scripts/verify-plugin.sh

@@ -10,7 +10,7 @@ fi
 
 if ! sf data360 man >/dev/null 2>&1; then
   echo "The community 'sf data360' runtime is not available." >&2
-  echo "Run bash ~/.claude/skills/orchestrating-datacloud/scripts/bootstrap-plugin.sh first." >&2
+  echo "Run bash ./scripts/bootstrap-plugin.sh first." >&2
   exit 1
 fi
 
@@ -54,5 +54,5 @@ fi
 
 echo "Verification complete."
 if [[ -n "${ORG}" ]]; then
-  echo "Next: node ~/.claude/skills/orchestrating-datacloud/scripts/diagnose-org.mjs -o '${ORG}' --json"
+  echo "Next: node ./scripts/diagnose-org.mjs -o '${ORG}' --json"
 fi

package/skills/preparing-datacloud/SKILL.md

@@ -44,7 +44,7 @@ Ask for or infer:
 ## Core Operating Rules
 
 - Verify the external plugin runtime before running Data Cloud commands.
-- Run the shared readiness classifier before mutating ingestion assets: `node ~/.claude/skills/orchestrating-datacloud/scripts/diagnose-org.mjs -o <org> --phase prepare --json`.
+- Run the shared readiness classifier before mutating ingestion assets: `node ../orchestrating-datacloud/scripts/diagnose-org.mjs -o <org> --phase prepare --json`.
 - Prefer inspecting existing streams and DLOs before creating new ingestion assets.
 - Suppress linked-plugin warning noise with `2>/dev/null` for normal usage.
 - Treat DLO naming and field naming as Data Cloud-specific, not CRM-native.
@@ -59,7 +59,7 @@ Ask for or infer:
 
 ### 1. Classify readiness for prepare work
 ```bash
-node ~/.claude/skills/orchestrating-datacloud/scripts/diagnose-org.mjs -o <org> --phase prepare --json
+node ../orchestrating-datacloud/scripts/diagnose-org.mjs -o <org> --phase prepare --json
 ```
 
 ### 2. Inspect existing ingestion assets

package/skills/retrieving-datacloud/SKILL.md

@@ -39,7 +39,7 @@ Ask for or infer:
 ## Core Operating Rules
 
 - Treat Data Cloud SQL as its own query language, not SOQL.
-- Run the shared readiness classifier before relying on query/search surfaces: `node ~/.claude/skills/orchestrating-datacloud/scripts/diagnose-org.mjs -o <org> --phase retrieve --json`.
+- Run the shared readiness classifier before relying on query/search surfaces: `node ../orchestrating-datacloud/scripts/diagnose-org.mjs -o <org> --phase retrieve --json`.
 - Use describe before guessing columns.
 - Prefer `sqlv2` or async query flows for larger result sets.
 - Use vector search or hybrid search only when the search index lifecycle is healthy.
@@ -51,9 +51,9 @@ Ask for or infer:
 
 ### 1. Classify readiness for retrieve work
 ```bash
-node ~/.claude/skills/orchestrating-datacloud/scripts/diagnose-org.mjs -o <org> --phase retrieve --json
+node ../orchestrating-datacloud/scripts/diagnose-org.mjs -o <org> --phase retrieve --json
 # optional query-plane probe, only with a real table name
-node ~/.claude/skills/orchestrating-datacloud/scripts/diagnose-org.mjs -o <org> --phase retrieve --describe-table MyDMO__dlm --json
+node ../orchestrating-datacloud/scripts/diagnose-org.mjs -o <org> --phase retrieve --describe-table MyDMO__dlm --json
 ```
 
 ### 2. Choose the smallest correct query shape

package/skills/reviewing-lwc-mobile-offline/SKILL.md

@@ -4,7 +4,6 @@ description: "Review a Lightning Web Component for **mobile offline** compatibil
 metadata:
   version: "1.0"
 ---
-<!-- adk-managed-skill -->
 
 # Reviewing LWC Mobile Offline