@salesforce/afv-skills 1.55.0 → 1.56.0

package/skills/service-de-channel-settings-configure/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: service-de-channel-settings-configure
+description: "Configure settings on an already-existing Enhanced `MessagingChannel` (any type — WhatsApp, Text/SMS, LINE, Apple, Facebook, EmbeddedMessaging), given its `{CHANNEL_ID}`. Covers five facets: consent (ConsentType + per-language keyword records), automated responses, messaging keywords, session-inactivity timeouts, and pre-chat parameters. Consent + a matching language-keyword record are required for activation's readiness check. TRIGGER when setting or changing settings on a channel that already exists (opt-out keyword, consent type, double opt-in confirmation, initial/help auto-responses, OptIn/OptOut keywords, session-inactivity timeout) — typically between insertion/routing and activation, or on a live channel. DO NOT TRIGGER for creating a new channel (`service-de-channel-create`), deploying a MIAW/EmbeddedMessaging channel from metadata XML (`service-digital-engagement-channel-configure`), setting routing (`service-de-channel-routing-configure`), or activating a channel (`service-de-channel-activate`)."
+metadata:
+  version: "2.0"
+  minApiVersion: "67.0"
+  domains: ["Service"]
+  cliTools:
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+  relatedSkills:
+    - "service-de-channel-activate"
+    - "service-de-channel-create"
+    - "service-de-channel-routing-configure"
+    - "service-de-headless-channel-configure"
+    - "service-digital-engagement-channel-configure"
+---
+
+# Configuring Channel Settings
+
+## What this skill does
+
+Configures settings on an **already-existing Enhanced `MessagingChannel`** (identified by `{CHANNEL_ID}`), for any message type. It groups five facets; you only run the ones the caller asks for.
+
+| # | Facet | Write surface | Applies to |
+| --- | --- | --- | --- |
+| 1 | **Consent** — `ConsentType` + `OptInPrompt`/`DoubleOptInPrompt` on the channel, plus per-language `MsgChannelLanguageKeyword` records | **Data/SObjects API** (`sf data update/create record`) | all Enhanced types |
+| 2 | **Automated responses** — `<automatedResponses>` (initial, agent-engaged/-ended, opt-in prompt/confirmation, help, opt-out, inactive/idle) | **Metadata API** deploy | all Enhanced types |
+| 3 | **Messaging keywords** — `<messagingKeywords>` (OptIn/OptOut/Help keyword groups per language) | **Metadata API** deploy | all Enhanced types |
+| 4 | **Session inactivity** — `endUserIdleTimeOut`, `endUserIdleAction`, `endInactiveSessionTimeOut`, `isAgentMessageResetInactivityEnabled` | **Metadata API** deploy | **MIAW-only** (reset-flag also Apple/Facebook) |
+| 5 | **Pre-chat parameters** — `<customParameters>` / `<standardParameters>` | **Metadata API** deploy | **MIAW pre-chat only** (rare) |
+
+**This skill is mixed-surface.** Consent (facet 1) is written with the Data API on the live record. Facets 2–5 live only in the channel's **metadata** and are configured by retrieving the channel's `.messagingChannel-meta.xml`, editing it, and deploying it back. Verified live on sdb6 (2026-09): every Data/Connect/Tooling read of the facet-2–5 fields fails `INVALID_TYPE`/"No such column" — they are Metadata-API-only.
+
+**Per-type applicability is verified, not assumed** (from a live retrieve of real channels of each type). Facets 2 and 3 are genuinely type-agnostic. Facet 4's four timeout fields appear **only on MIAW**; only `isAgentMessageResetInactivityEnabled` extends to Apple/Facebook, and SMS/WhatsApp/LINE carry no inactivity fields at all. Facet 5 appears only on MIAW channels that use pre-chat. Scope per-type accordingly — do **not** deploy a facet a type doesn't support.
+
+## When to use (TRIGGER)
+
+Trigger this skill when the user wants to configure or change settings on a channel that **already exists**, e.g.:
+
+- "set the opt-out keyword / consent type on my WhatsApp channel"
+- "add a double opt-in confirmation to this messaging channel"
+- "configure the initial / agent-engaged / help auto-response on my Apple channel"
+- "add OptIn/OptOut/Help keywords to my Text channel"
+- "set the session inactivity timeout / idle action on my MIAW channel"
+- "change the auto-responses on channel 0MjXXXXXXXXXXXX"
+
+**DO NOT TRIGGER — hand off instead:**
+
+- **Creating or deploying a new channel from a metadata XML file (MIAW / EmbeddedMessaging)** → `service-digital-engagement-channel-configure`. That skill *creates* an Embedded Messaging channel from XML; **this** skill only configures a channel that already exists (it needs a live `{CHANNEL_ID}`, prefix `0Mj`).
+- **Inserting a brand-new channel of any type** → `service-de-channel-create`.
+- **Setting routing / queue / SessionHandler** → `service-de-channel-routing-configure`.
+- **Flipping a channel live** → `service-de-channel-activate`.
+
+## Where this fits
+
+Part of the Enhanced-channel headless pipeline: `service-de-channel-create` → `service-de-channel-routing-configure` → **this skill** → `service-de-channel-activate`. Activation's readiness check requires **both** routing and consent, so at minimum run facet 1 before activating. The `service-de-headless-channel-configure` orchestrator sequences the pipeline automatically; invoke this skill directly to configure settings on their own. For the MIAW-specific channel-*creation-from-XML* flow, see the sibling `service-digital-engagement-channel-configure`.
+
+## Reference File Index
+
+| Reference file | Load when |
+| --- | --- |
+| `references/language-keywords.md` | Facet 1: creating/updating `MsgChannelLanguageKeyword` records — field list, CSV keyword semantics, create-vs-update, Unified-SMS help/custom rules. |
+| `references/channel-settings-facets.md` | Facets 2–5: the Metadata-API retrieve→edit→deploy flow, the full `<automatedResponses>` type/shape catalog (12 types, 2 content shapes), `<messagingKeywords>`, the inactivity fields, and per-type applicability. |
+| `references/gotchas.md` | Troubleshooting an unexpected result, or before modifying this skill. |
+| `references/worked-examples.md` | Reference runs of the ImplicitOptIn/ExplicitOptIn/DoubleOptIn consent paths. |
+
+## When NOT to use this skill
+
+- **The channel isn't Enhanced.** These settings apply to `PlatformType=Enhanced` channels only. Stage 1 confirms this and stops otherwise.
+- **The channel doesn't exist yet.** Run `service-de-channel-create` first; this skill expects a real `MessagingChannel.Id` (prefix `0Mj`).
+- **You're configuring consent on an outbound-only channel.** Outbound-only channels pass the consent-readiness check automatically — nothing to configure for facet 1.
+
+## Inputs (from caller)
+
+- `{CHANNEL_ID}` — a 15/18-char `MessagingChannel.Id` (prefix `0Mj`). Must already exist and be Enhanced.
+- `{FACETS}` — optional; which facets to configure (`consent`, `auto-responses`, `keywords`, `inactivity`, `parameters`). If omitted, infer from the request or ask.
+- `{CONSENT_TYPE}` — optional (facet 1); `ImplicitOptIn` | `ExplicitOptIn` | `DoubleOptIn`.
+- `{LANGUAGE}` — optional; locale for keyword/response records (e.g. `en_US`). Default `en_US`.
+- `{ORG_ALIAS}` — optional; `sf` target-org alias. Default: `sf config get target-org`.
+
+Facet-specific values (prompts, keyword lists, response text, timeout minutes) are collected interactively per facet, or accepted if pre-supplied.
+
+## Output (to caller)
+
+**Success:**
+```json
+{"ok": true, "channelId": "0Mj...", "messageType": "WhatsApp",
+ "facetsConfigured": ["consent","auto-responses"],
+ "consent": {"consentType": "ExplicitOptIn", "languageKeywordId": "3Or...", "activationReady": true},
+ "metadataDeploy": {"status": "Succeeded", "facets": ["auto-responses","keywords"]}}
+```
+
+**No change needed / precondition / failure:**
+```json
+{"ok": true, "noop": true, "message": "Requested settings already configured"}
+{"ok": false, "kind": "not-enhanced", "hint": "settings apply to Enhanced channels only; this channel is PlatformType=<x>"}
+{"ok": false, "kind": "facet-not-applicable", "hint": "<facet> is not supported on <messageType> channels"}
+{"ok": false, "kind": "channel-patch-failed" | "keyword-record-failed" | "metadata-deploy-failed" | "verify-failed", "message": "..."}
+```
+
+---
+
+## Stage 1: Read the channel and decide facets
+
+Read the channel; confirm it exists and is Enhanced; capture `MessageType` (drives per-type applicability).
+
+```bash
+sf data query --target-org '{ORG_ALIAS}' \
+  --query "SELECT Id, DeveloperName, PlatformType, MessageType, MessagingPlatformKey, ConsentType, OptInPrompt, DoubleOptInPrompt, IsRequireDoubleOptIn FROM MessagingChannel WHERE Id = '{CHANNEL_ID}'" \
+  --json > /tmp/cs-channel.json
+```
+
+- Channel missing → halt: `Error: Channel {CHANNEL_ID} not found — check the id, or run service-de-channel-create first.`
+- `PlatformType != 'Enhanced'` → emit `{ok:false, kind:"not-enhanced", ...}` and stop.
+
+Decide which facets to run from `{FACETS}` or the request. For each requested facet, check per-type applicability (table above / `references/channel-settings-facets.md`); if a facet doesn't apply to this `MessageType`, emit `{ok:false, kind:"facet-not-applicable", ...}` for that facet (or skip it and note it) rather than deploying an unsupported field.
+
+**sf CLI is slow, not broken.** Calls to this org routinely take 2–4 minutes (heavy CLI startup + slow round-trip). Run each `sf` command with a generous timeout; a slow return is normal, not a hang.
+
+---
+
+## Stage 2: Facet 1 — Consent (Data API)
+
+Run when `consent` is requested (and always before activation). Read the existing keyword records:
+
+```bash
+sf data query --target-org '{ORG_ALIAS}' \
+  --query "SELECT Id, MasterLanguage, OptInKeywords, DoubleOptInKeywords, OptInConfirmation, OptOutKeywords, OptOutConfirmation, HelpKeywords, HelpResponse, CustomKeywords, CustomResponse FROM MsgChannelLanguageKeyword WHERE MessagingChannelId = '{CHANNEL_ID}'" \
+  --json > /tmp/cs-keywords.json
+```
+
+**No-op check:** if `ConsentType` is non-null AND an existing keyword record already satisfies the readiness matrix for that ConsentType, don't overwrite — this facet is already activation-ready.
+
+Choose the ConsentType (prompt if `{CONSENT_TYPE}` absent — do not auto-pick), then satisfy this contract (the exact server-side activation-readiness rule — source in `references/gotchas.md`):
+
+| ConsentType | MessagingChannel fields | `MsgChannelLanguageKeyword` (≥1 record) |
+| --- | --- | --- |
+| ImplicitOptIn | (none required) | `OptOutKeywords` + `OptOutConfirmation` |
+| ExplicitOptIn | `OptInPrompt`¹ | above + `OptInKeywords` |
+| DoubleOptIn | `OptInPrompt`¹ + `DoubleOptInPrompt` + `IsRequireDoubleOptIn=true` | above + `DoubleOptInKeywords` |
+
+¹ `OptInPrompt` is optional for readiness on Unified SMS / WhatsApp / RCS (`MessageType IN ('Text','WhatsApp','Rcs')` on Enhanced); still recommend setting it. `ImplicitOptIn` is **never a no-op** — it still needs an opt-out keyword record.
+
+Write the channel fields in one PATCH, then create/update the language-keyword record per `references/language-keywords.md`.
+
+**Quoting rule (load-bearing):** `sf data ... --values` splits on spaces — wrap every multi-word value in single quotes *inside* the double-quoted string: `OptInPrompt='Reply YES to receive messages'`. Unquoted fails with `Malformed key=value pair`.
+
+```bash
+# ExplicitOptIn example
+sf data update record --target-org '{ORG_ALIAS}' --sobject MessagingChannel \
+  --record-id '{CHANNEL_ID}' --values "ConsentType=ExplicitOptIn OptInPrompt='{OPT_IN_PROMPT}'" --json > /tmp/cs-patch.json
+```
+
+On non-zero status: emit `{ok:false, kind:"channel-patch-failed"|"keyword-record-failed", message: ...}`. Then verify by re-reading (Stage 5).
+
+> **WhatsApp rich content rejects ExplicitOptIn** server-side — surface the message, don't retry (see `references/gotchas.md`).
+
+---
+
+## Stage 3: Facets 2 & 3 — Automated responses + Messaging keywords (Metadata API)
+
+Run when `auto-responses` and/or `keywords` are requested. These are type-agnostic (all Enhanced types). **Load `references/channel-settings-facets.md` and follow it** — it has the retrieve→edit→deploy flow, the 12 `<automatedResponses>` type values, the two content shapes (`TextResponse` vs `MessageDefinition`), the `EndUserIdleResponse` `<responseTimeoutInMins>` rule, XML escaping, and the `<messagingKeywords>` OptIn/OptOut/Help groups.
+
+Outline:
+1. Retrieve the channel's metadata into a scratch sfdx project (`sf project retrieve start -m MessagingChannel:{DeveloperName}`).
+2. Edit `<automatedResponses>` / `<messagingKeywords>` blocks in the retrieved `.messagingChannel-meta.xml` (add/replace by `<type>` / `<keywordType>`+`<language>`; XML-escape response text).
+3. Deploy it back (`sf project deploy start -m MessagingChannel:{DeveloperName}`).
+4. On deploy failure: `{ok:false, kind:"metadata-deploy-failed", message: <componentFailures>}`.
+
+**Never emit `<actionParameterMappings>`** (0 occurrences across a 191-channel scan — it's a Tooling-only mapping done in the UI post-deploy).
+
+---
+
+## Stage 4: Facets 4 & 5 — Inactivity + Pre-chat parameters (Metadata API, scoped)
+
+Run only when requested **and** applicable to this `MessageType`:
+
+- **Facet 4 (inactivity):** the four timeout fields (`endUserIdleTimeOut` 5–30, `endUserIdleAction` = `Inactivate`|`End`|`InactivateAndEnd`, `endInactiveSessionTimeOut`, `isAgentMessageResetInactivityEnabled`) are **top-level siblings of `<embeddedConfig>`**, not inside it. Full four fields → **MIAW only**; `isAgentMessageResetInactivityEnabled` also valid on Apple/Facebook; **not applicable on SMS/WhatsApp/LINE** → emit `facet-not-applicable`. (On 262-line pods only `endUserIdleTimeOut` deploys — see `references/gotchas.md`.)
+- **Facet 5 (parameters):** `<customParameters>` (`name`, `masterLabel`, `externalParameterName`, `parameterDataType=String`, optional `maxLength`) and `<standardParameters>` — **MIAW pre-chat only**, rare. Skip unless the caller explicitly configures pre-chat.
+
+Both use the same retrieve→edit→deploy flow as Stage 3 (`references/channel-settings-facets.md`).
+
+---
+
+## Stage 5: Verify and report
+
+For facet 1, re-read the channel + keyword records and confirm every required field for the chosen ConsentType is non-null (channel and ≥1 language record); else `{ok:false, kind:"verify-failed", hint:"..."}`. For metadata facets, confirm the deploy `status` is `Succeeded`, then re-retrieve the channel metadata and confirm the edited `<automatedResponses>` / `<messagingKeywords>` / inactivity / parameter blocks are present; if a deploy reports `Succeeded` but the re-retrieved block is missing, emit `{ok:false, kind:"verify-failed", hint:"..."}`.
+
+Emit the JSON envelope. If invoked directly (leaf), render a short summary:
+- `Success — configured {facets} on channel {CHANNEL_ID} ({MessageType}).` (add `Activation-ready.` when consent passed)
+- `Info: requested settings already configured — no changes.` (no-op)
+- `Warning: {facet} is not supported on {MessageType} channels — skipped.` (facet-not-applicable)
+- `Warning: this channel is PlatformType={x}, not Enhanced — these settings don't apply.` (not-enhanced)
+- `Error: {kind}: {message}` (failures)

package/skills/service-de-channel-settings-configure/references/channel-settings-facets.md

@@ -0,0 +1,152 @@
+# Metadata-API facets: automated responses, keywords, inactivity, parameters
+
+Load this for facets 2–5. These settings live only in the channel's **metadata** — every Data/Connect/Tooling read of them returns `INVALID_TYPE`/"No such column" (verified live on sdb6, 2026-09). Configure them by retrieving the channel's `.messagingChannel-meta.xml`, editing it, and deploying it back.
+
+## The retrieve → edit → deploy flow
+
+You need the channel's **DeveloperName** (the metadata member name), not just its Id. Get it from the Stage 1 query (`DeveloperName`).
+
+```bash
+# 1. Scratch sfdx project (throwaway — do NOT create inside the skills repo)
+mkdir -p /tmp/cs-meta/force-app/main/default && cd /tmp/cs-meta
+cat > sfdx-project.json <<'EOF'
+{ "packageDirectories": [{ "path": "force-app", "default": true }], "sourceApiVersion": "69.0" }
+EOF
+
+# 2. Retrieve the channel (use a package.xml manifest for >1 channel;
+#    a comma-separated -m list is parsed as one member by some CLI versions)
+sf project retrieve start --target-org '{ORG_ALIAS}' -m 'MessagingChannel:{DeveloperName}' --json
+
+# 3. Edit force-app/main/default/messagingChannels/{DeveloperName}.messagingChannel-meta.xml
+#    (add/replace the facet blocks below)
+
+# 4. Deploy back
+sf project deploy start --target-org '{ORG_ALIAS}' -m 'MessagingChannel:{DeveloperName}' --json
+```
+
+On deploy failure, read `result.details.componentFailures[].problem` and return it as `{ok:false, kind:"metadata-deploy-failed", message: ...}`. **sf calls on this org take 2–4 min each — slow is normal, not a hang.**
+
+Edit rules: match/replace an existing block by its identity (`<type>` for auto-responses; `<keywordType>`+`<language>` for keywords), otherwise append a new one. Preserve all other elements. Keep the file well-formed.
+
+---
+
+## Facet 2 — Automated responses (`<automatedResponses>`)
+
+Repeatable top-level element. Each block has a `<type>` (the event) and one of two content shapes.
+
+**Content shapes:**
+- `TextResponse` — inline text: `<autoResponseContentType>TextResponse</autoResponseContentType>`, `<response>…</response>`, and usually `<language>` (may be omitted on `OptInPrompt`).
+- `MessageDefinition` — references a `ConversationMessageDefinition` by name: `<autoResponseContentType>MessageDefinition</autoResponseContentType>`, `<messageDefinitionName>…</messageDefinitionName>` (that definition must already exist in the org). Common on MIAW.
+
+**The 12 `<type>` values** (superset across all Enhanced types):
+
+| `type` | When sent |
+| --- | --- |
+| `InitialResponse` | Customer's first inbound message was received |
+| `AgentEngagedResponse` | A service rep accepted the session |
+| `AgentEndEngagementResponse` | Session ended (rep or end user); optional post-chat URL |
+| `EndUserInactiveResponse` | Conversation ended because the end user stopped responding |
+| `EndUserIdleResponse` | End user went idle; **adds `<responseTimeoutInMins>`** (minutes of idle before it fires) |
+| `RerouteResponse` | Conversation was rerouted |
+| `OptInPrompt` | Reply didn't match an opt-in keyword |
+| `OptInConfirmation` | Successful opt-in |
+| `DoubleOptInPrompt` | Reply didn't match a double-opt-in keyword |
+| `OptOutConfirmation` | Successful opt-out |
+| `HelpResponse` | End user sent a help keyword |
+| `CustomResponse` | Custom keyword match |
+
+**XML-escape** `<response>` text: `'`→`&apos;` `"`→`&quot;` `&`→`&amp;` `<`→`&lt;` `>`→`&gt;`.
+
+```xml
+<!-- TextResponse -->
+<automatedResponses>
+    <autoResponseContentType>TextResponse</autoResponseContentType>
+    <language>en_US</language>
+    <response>You&apos;ve opted out of receiving messages from us.</response>
+    <type>OptOutConfirmation</type>
+</automatedResponses>
+<!-- MessageDefinition + idle timeout -->
+<automatedResponses>
+    <autoResponseContentType>MessageDefinition</autoResponseContentType>
+    <messageDefinitionName>Customer_Idle_Message</messageDefinitionName>
+    <responseTimeoutInMins>4</responseTimeoutInMins>
+    <type>EndUserIdleResponse</type>
+</automatedResponses>
+```
+
+---
+
+## Facet 3 — Messaging keywords (`<messagingKeywords>`)
+
+Repeatable top-level element — one block per (keywordType, language). Each has one or more `<keyword>` children, a `<keywordType>` (`OptIn` | `OptOut` | `Help`), and a `<language>`. Type-agnostic; `OptIn` groups appear on types that support explicit opt-in (e.g. Apple, LINE).
+
+```xml
+<messagingKeywords>
+    <keyword>cancel</keyword>
+    <keyword>end</keyword>
+    <keyword>stop</keyword>
+    <keyword>unsubscribe</keyword>
+    <keywordType>OptOut</keywordType>
+    <language>en_US</language>
+</messagingKeywords>
+<messagingKeywords>
+    <keyword>help</keyword>
+    <keywordType>Help</keywordType>
+    <language>en_US</language>
+</messagingKeywords>
+```
+
+> Consent keyword *records* (`MsgChannelLanguageKeyword`, facet 1) and metadata `<messagingKeywords>` are distinct surfaces. Facet 1 (Data API) drives the activation-readiness check; `<messagingKeywords>` is the channel's metadata representation. Configure consent via facet 1 for activation; use `<messagingKeywords>` when editing the channel's metadata directly.
+
+---
+
+## Facet 4 — Session inactivity (top-level, scoped)
+
+Four fields, **siblings of `<embeddedConfig>`** (top-level, NOT nested inside it):
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `endUserIdleTimeOut` | int (5–30) | minutes idle before the idle action |
+| `endUserIdleAction` | enum | `Inactivate` \| `End` \| `InactivateAndEnd` |
+| `endInactiveSessionTimeOut` | int | minutes before an inactive session ends |
+| `isAgentMessageResetInactivityEnabled` | bool | agent message resets the idle timer |
+
+```xml
+<endInactiveSessionTimeOut>5</endInactiveSessionTimeOut>
+<endUserIdleAction>InactivateAndEnd</endUserIdleAction>
+<endUserIdleTimeOut>5</endUserIdleTimeOut>
+```
+
+**Per-type scope (verified live):** all four → **MIAW (EmbeddedMessaging) only**. `isAgentMessageResetInactivityEnabled` alone also appears on **Apple** and **Facebook**. **SMS/WhatsApp/LINE carry no inactivity fields** — emit `facet-not-applicable`. On 262-line pods only `endUserIdleTimeOut` deploys (`endInactiveSessionTimeOut`/`endUserIdleAction` land at 264+) — see `gotchas.md`.
+
+---
+
+## Facet 5 — Pre-chat parameters (MIAW pre-chat only, rare)
+
+`<customParameters>` / `<standardParameters>` are pre-chat-form fields. A live scan found **0 occurrences across all sampled channels including MIAW** — they exist only on MIAW channels that explicitly enable pre-chat. Skip unless the caller is configuring pre-chat.
+
+```xml
+<customParameters>
+    <externalParameterName>City</externalParameterName>
+    <masterLabel>City</masterLabel>
+    <maxLength>30</maxLength>
+    <name>City</name>
+    <parameterDataType>String</parameterDataType>
+</customParameters>
+```
+
+`parameterDataType` is `String` (not `Text`). **Never emit `<actionParameterMappings>`** — 0 occurrences across a 191-channel scan; it's a Tooling-only entity, mapped in the UI post-deploy. `<standardParameters>` (`parameterType` = `FirstName`|`LastName`|`Email`|`Subject`) is likewise MIAW-pre-chat-only.
+
+---
+
+## Per-type applicability matrix (verified live, sdb6 2026-09)
+
+| Facet | MIAW | Apple | Facebook | LINE | SMS | WhatsApp |
+| --- | :-: | :-: | :-: | :-: | :-: | :-: |
+| Auto-responses (2) | yes | yes | yes | yes | yes | yes |
+| Messaging keywords (3) | yes | yes | yes | yes | yes | yes |
+| Inactivity — 3 timeout fields (4) | yes | no | no | no | no | no |
+| Inactivity — reset flag (4) | yes | yes | yes | no | no | no |
+| Pre-chat parameters (5) | pre-chat only | no | no | no | no | no |
+
+Derived from a Metadata-API retrieve of real channels of each type. Don't deploy a facet a type doesn't support — the deploy will either fail or silently drop the element.

package/skills/{service-de-channel-consent-configure → service-de-channel-settings-configure}/references/gotchas.md

@@ -1,9 +1,9 @@
 ---
-name: service-de-channel-consent-configure-gotchas
-description: "Load when debugging an unexpected result from service-de-channel-consent-configure, or before implementing changes to it. Covers the known gotchas: the exact per-ConsentType activation-readiness contract and its source, the ImplicitOptIn-still-needs-a-keyword-record trap, comma-separated keyword storage, one-record-per-language uniqueness, the Unified-SMS help/French-custom rules, the OptInPrompt Unified-SMS/WhatsApp/RCS exemption, the outbound-only auto-pass, the Enhanced-only gate, the legacy OptInResponse/OptOutResponse deprecation, and why MsgChannelLanguageKeyword must be written over the Data/SObjects API rather than the Tooling API despite its setupEntity perApiAccess block. DO NOT load this during a normal first-time consent run — only when troubleshooting or modifying the skill."
+name: service-de-channel-settings-configure-gotchas
+description: "Load when debugging an unexpected result from service-de-channel-settings-configure, or before implementing changes to it. Covers the known gotchas: the exact per-ConsentType activation-readiness contract and its source, the ImplicitOptIn-still-needs-a-keyword-record trap, comma-separated keyword storage, one-record-per-language uniqueness, the Unified-SMS help/French-custom rules, the OptInPrompt Unified-SMS/WhatsApp/RCS exemption, the outbound-only auto-pass, the Enhanced-only gate, the legacy OptInResponse/OptOutResponse deprecation, and why MsgChannelLanguageKeyword must be written over the Data/SObjects API rather than the Tooling API despite its setupEntity perApiAccess block. DO NOT load this during a normal first-time consent run — only when troubleshooting or modifying the skill."
 metadata:
   version: "1.0"
-  related-skills: service-de-channel-consent-configure
+  related-skills: service-de-channel-settings-configure
 ---
 
 # Gotchas

package/skills/{service-de-channel-consent-configure → service-de-channel-settings-configure}/references/language-keywords.md

@@ -1,6 +1,6 @@
 # Per-language keyword records: `MsgChannelLanguageKeyword`
 
-Load this when Stage 4 needs to create or update the per-language keyword record for a channel.
+Load this when Stage 2 (Facet 1 — Consent) needs to create or update the per-language keyword record for a channel.
 
 ## Entity shape
 
@@ -33,7 +33,7 @@ Keyword fields hold a **comma-separated string**, not a multi-value/picklist. Th
 
 ## Create vs update — reuse the record for a language
 
-**There is one record per (channel, language).** Before creating, check the Stage 1 read (`/tmp/cc-keywords.json`) for an existing `MsgChannelLanguageKeyword` whose `MasterLanguage` equals `{LANGUAGE}`:
+**There is one record per (channel, language).** Before creating, check the Stage 2 read (`/tmp/cs-keywords.json`) for an existing `MsgChannelLanguageKeyword` whose `MasterLanguage` equals `{LANGUAGE}`:
 
 - **Exists →** `updateRecord` path: PATCH that record's Id with the new field values. Do NOT create a second record for the same language — duplicates confuse the readiness check and the UI.
 - **Doesn't exist →** `createRecord` path: insert a new record, setting `MessagingChannelId={CHANNEL_ID}` and `MasterLanguage={LANGUAGE}` plus the collected keyword/response fields.
@@ -44,7 +44,7 @@ Keyword fields hold a **comma-separated string**, not a multi-value/picklist. Th
 sf data create record --target-org '{ORG_ALIAS}' --sobject MsgChannelLanguageKeyword \
   --values "MessagingChannelId={CHANNEL_ID} MasterLanguage={LANGUAGE} \
 OptOutKeywords='STOP,UNSUBSCRIBE' OptOutConfirmation='You have been unsubscribed.'" \
-  --json > /tmp/cc-kw-write.json
+  --json > /tmp/cs-kw-write.json
 ```
 
 Add `OptInKeywords`/`OptInConfirmation` for ExplicitOptIn, and `DoubleOptInKeywords` for DoubleOptIn.
@@ -57,7 +57,7 @@ Add `OptInKeywords`/`OptInConfirmation` for ExplicitOptIn, and `DoubleOptInKeywo
 sf data update record --target-org '{ORG_ALIAS}' --sobject MsgChannelLanguageKeyword \
   --record-id '{KEYWORD_RECORD_ID}' \
   --values "OptInKeywords='START,YES' OptInConfirmation='You are now subscribed.'" \
-  --json > /tmp/cc-kw-write.json
+  --json > /tmp/cs-kw-write.json
 ```
 
 Check `status` in the JSON result; on non-zero return `{ok:false, kind:"keyword-record-failed", message: ...}`.

package/skills/{service-de-channel-consent-configure → service-de-channel-settings-configure}/references/worked-examples.md

@@ -1,6 +1,6 @@
-# Worked examples: `service-de-channel-consent-configure`
+# Worked examples: consent facet (`service-de-channel-settings-configure`)
 
-Reference runs for the three ConsentType paths. The ExplicitOptIn channel-side write, the read model, and the WhatsApp restriction below were verified live on `messaging_sdb6c` 2026-08-13.
+Reference runs for the three ConsentType paths — all sub-steps of **Stage 2 (Facet 1 — Consent)** in the current skill (read state → choose ConsentType → collect prompts → write channel + keyword record), verified against **Stage 5 (verify)**. The step labels below describe that consent sub-flow, not separate top-level SKILL.md stages. The ExplicitOptIn channel-side write, the read model, and the WhatsApp restriction below were verified live on `messaging_sdb6c` 2026-08-13.
 
 ---
 
@@ -10,7 +10,7 @@ Input:
 - `{CHANNEL_ID}` = `0MjSG00000030wL0AQ` (Enhanced WhatsApp channel `DummyChannelForTesting`)
 - `{LANGUAGE}` = `en_US`
 
-**Stage 1** read shows `PlatformType=Enhanced`, `ConsentType=ImplicitOptIn`, and one existing `MsgChannelLanguageKeyword` (`3OrSG0000002kUz0AI`, `MasterLanguage=en_US`) with:
+The **Stage 1** channel read shows `PlatformType=Enhanced`, `ConsentType=ImplicitOptIn`, and the **Stage 2** keyword read finds one existing `MsgChannelLanguageKeyword` (`3OrSG0000002kUz0AI`, `MasterLanguage=en_US`) with:
 ```text
 OptOutKeywords    = unsubscribe_en_US,stopall_en_US,cancel_en_US,quit_en_US,stop_en_US,end_en_US
 OptOutConfirmation = You've opted out of receiving messages from us, so we won't contact you again.
@@ -44,11 +44,11 @@ Input:
 
 **Stage 1**: `PlatformType=Enhanced`, `ConsentType=ImplicitOptIn`, `OptInPrompt=null`. Continue.
 
-**Stage 2**: ExplicitOptIn chosen. Facebook accepts it (unlike WhatsApp rich content — see below).
+**Stage 2 (Facet 1) — choose ConsentType**: ExplicitOptIn chosen. Facebook accepts it (unlike WhatsApp rich content — see below).
 
-**Stage 3**: collect `OptInPrompt` = `Reply YES to receive messages`.
+**Stage 2 — collect prompts**: `OptInPrompt` = `Reply YES to receive messages`.
 
-**Stage 5 (channel PATCH)** — verified live, note the single-quoting of the multi-word prompt:
+**Stage 2 — channel PATCH** — verified live, note the single-quoting of the multi-word prompt:
 
 ```bash
 $ sf data update record --sobject MessagingChannel --record-id 0MjSG0000000D9V0AU \
@@ -58,7 +58,7 @@ $ sf data update record --sobject MessagingChannel --record-id 0MjSG0000000D9V0A
 
 Re-read confirmed `ConsentType=ExplicitOptIn`, `OptInPrompt=Reply YES to receive messages`.
 
-**Stage 5 (keyword record)** — the record must also carry `OptInKeywords` (plus the ImplicitOptIn opt-out fields). Create or update the `en_US` record:
+**Stage 2 — keyword record** — the record must also carry `OptInKeywords` (plus the ImplicitOptIn opt-out fields). Create or update the `en_US` record:
 
 ```bash
 sf data update record --sobject MsgChannelLanguageKeyword --record-id <3Or...> \
@@ -67,9 +67,9 @@ sf data update record --sobject MsgChannelLanguageKeyword --record-id <3Or...> \
 
 (Live keyword shape confirmed on sdb6c: e.g. Facebook channel `0MjSG0000000Beb0AE` carries `OptInKeywords=yes,sure` — multiple opt-in keywords as a comma-separated string.)
 
-**Stage 6**: re-read channel + keyword record; `OptInPrompt` non-null on the channel and `OptInKeywords`+`OptOutKeywords`+`OptOutConfirmation` non-null on the keyword record → activation-ready.
+**Stage 5 (verify)**: re-read channel + keyword record; `OptInPrompt` non-null on the channel and `OptInKeywords`+`OptOutKeywords`+`OptOutConfirmation` non-null on the keyword record → activation-ready.
 
-**Stage 7**:
+**Stage 5 (report)**:
 ```json
 {"ok": true, "consentType": "ExplicitOptIn", "channelFieldsSet": ["ConsentType","OptInPrompt"],
  "languageKeywordId": "3Or...", "language": "en_US", "created": false, "activationReady": true}
@@ -85,9 +85,9 @@ Input:
 - `{CHANNEL_ID}` = an Enhanced Text (SMS) channel
 - `{CONSENT_TYPE}` = `DoubleOptIn`
 
-**Stage 3** collects both `OptInPrompt` and `DoubleOptInPrompt`.
+**Stage 2 — collect prompts**: both `OptInPrompt` and `DoubleOptInPrompt`.
 
-**Stage 5 (channel PATCH)** — all three fields in one write:
+**Stage 2 — channel PATCH** — all three fields in one write:
 
 ```bash
 sf data update record --sobject MessagingChannel --record-id '{CHANNEL_ID}' \
@@ -95,7 +95,7 @@ sf data update record --sobject MessagingChannel --record-id '{CHANNEL_ID}' \
 DoubleOptInPrompt='Reply CONFIRM to confirm your subscription' IsRequireDoubleOptIn=true"
 ```
 
-**Stage 5 (keyword record)** — needs `OptInKeywords`, `DoubleOptInKeywords`, `OptOutKeywords`, `OptOutConfirmation`:
+**Stage 2 — keyword record** — needs `OptInKeywords`, `DoubleOptInKeywords`, `OptOutKeywords`, `OptOutConfirmation`:
 
 ```bash
 sf data update record --sobject MsgChannelLanguageKeyword --record-id <3Or...> \
@@ -105,7 +105,7 @@ OptOutKeywords=stop,unsubscribe OptOutConfirmation='You have been unsubscribed.'
 
 (Live example on sdb6c: keyword record `3OrSG00000002rR0AQ` has both `OptInKeywords=yes` and `DoubleOptInKeywords=yes`, confirming DoubleOptIn uses both keyword fields.)
 
-**Stage 6** verifies `OptInPrompt` + `DoubleOptInPrompt` non-null on the channel and `OptInKeywords` + `DoubleOptInKeywords` + opt-out fields non-null on the keyword record.
+**Stage 5 (verify)** confirms `OptInPrompt` + `DoubleOptInPrompt` non-null on the channel and `OptInKeywords` + `DoubleOptInKeywords` + opt-out fields non-null on the keyword record.
 
 ---
 
@@ -115,7 +115,7 @@ Input:
 - `{CHANNEL_ID}` = `0MjSG00000030wL0AQ` (Enhanced WhatsApp channel with rich content)
 - User asks for `ExplicitOptIn`
 
-**Stage 5** PATCH is rejected server-side:
+**Stage 2 — channel PATCH** is rejected server-side:
 
 ```bash
 $ sf data update record --sobject MessagingChannel --record-id 0MjSG00000030wL0AQ \

package/skills/service-de-headless-channel-configure/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: service-de-headless-channel-configure
-description: "Top-level orchestrator: given a messaging channel type and its type-specific inputs, produces an activated Enhanced `MessagingChannel` in the target Salesforce org — without the Meta/LINE/Apple setup popups. Prompts for `{MESSAGE_TYPE}` if not supplied, then sequences insert → route → consent → activate via the type-agnostic dispatcher (`service-de-channel-create`) plus the shared routing/consent/activation leaves. Resumes from partial state on re-run. Use this skill when the user wants to set up an Enhanced messaging channel (WhatsApp, Facebook, LINE, Apple, or SMS/Text) end-to-end from the command line, bypassing the in-org setup popups."
+description: "Top-level orchestrator: given a messaging channel type and its inputs, produces an activated Enhanced `MessagingChannel` in the target org — without the Meta/LINE/Apple setup popups. Prompts for `{MESSAGE_TYPE}` if not supplied, then sequences insert → route → consent → activate via the type-agnostic dispatcher (`service-de-channel-create`) plus the shared routing/consent/activation leaves. Resumes from partial state on re-run. Use to set up an Enhanced channel (WhatsApp, Facebook, LINE, Apple, SMS) end-to-end, bypassing in-org setup popups. Do not use for a single stage of an already-inserted channel — use the matching leaf skill (`service-de-channel-activate`, `service-de-channel-settings-configure`, `service-de-channel-routing-configure`) instead."
 metadata:
   version: "1.0"
   minApiVersion: "67.0"
@@ -10,9 +10,9 @@ metadata:
       semver: ">=2.0.0"
   relatedSkills:
     - "service-de-channel-activate"
-    - "service-de-channel-consent-configure"
     - "service-de-channel-create"
     - "service-de-channel-routing-configure"
+    - "service-de-channel-settings-configure"
     - "service-de-waba-integrate"
 ---
 
@@ -25,7 +25,7 @@ Takes a channel type (`WhatsApp` | `Line` | `AppleBusinessChat` | `Facebook` | `
 0. **Accept Terms and Conditions** — renders the Enhanced Messaging disclaimer and requires the user to certify they have authority to bind their org, mirroring the in-org "Add a Channel" wizard. Blocking — a decline ends the run before any org work. *(Stage 0.5, in this skill)*
 1. **Insert the channel** — invokes `service-de-channel-create`, which handles the per-type third-party prereq internally (e.g. WhatsApp's `service-de-waba-integrate` runs inside `service-de-channel-create`). *(skill: `service-de-channel-create`)*
 2. **Configure routing** — sets `SessionHandlerId` to an Omni-Channel Queue (pick existing or create new). Message-type-agnostic. *(skill: `service-de-channel-routing-configure`)*
-3. **Configure consent** — ensures a valid `ConsentType` + matching `MsgChannelLanguageKeyword` record. The Connect insert auto-seeds a default `ConsentType=ImplicitOptIn` + opt-out keyword, so on a fresh channel this step is frequently a **no-op** — or an *upgrade* if the caller wants ExplicitOptIn/DoubleOptIn. Activation's readiness check requires both routing AND consent, so this runs before activation. *(skill: `service-de-channel-consent-configure`)*
+3. **Configure consent** — ensures a valid `ConsentType` + matching `MsgChannelLanguageKeyword` record. The Connect insert auto-seeds a default `ConsentType=ImplicitOptIn` + opt-out keyword, so on a fresh channel this step is frequently a **no-op** — or an *upgrade* if the caller wants ExplicitOptIn/DoubleOptIn. Activation's readiness check requires both routing AND consent, so this runs before activation. *(skill: `service-de-channel-settings-configure`)*
 4. **Activate** — PATCHes `MessagingChannelUsage.DeploymentStatus` to `Provisioning` via REST; the server-side save-hook drives the full observer chain synchronously and returns 204 once the MCU reaches `Active` and `MessagingChannel.IsActive=true`. Message-type-agnostic. *(skill: `service-de-channel-activate`)*
 
 **Resume-by-default.** Each step is idempotent — if you re-run after a failure, the orchestrator detects existing state and skips steps that already succeeded.
@@ -49,7 +49,7 @@ Takes a channel type (`WhatsApp` | `Line` | `AppleBusinessChat` | `Facebook` | `
 
 **This orchestrator MUST run all stages (0-5) in a SINGLE response without stopping between stages.**
 
-When you invoke a leaf skill (service-de-channel-create, service-de-channel-routing-configure, service-de-channel-consent-configure, service-de-channel-activate) and it returns via function_results:
+When you invoke a leaf skill (service-de-channel-create, service-de-channel-routing-configure, service-de-channel-settings-configure, service-de-channel-activate) and it returns via function_results:
 
 - **DO:** Immediately parse the function_results return value and continue to the next stage
 - **DO:** Run Stage 0.5 → Stage 1 → Stage 2 → Stage 3 → Stage 3.5 → Stage 4 → Stage 5 consecutively in ONE response
@@ -209,7 +209,7 @@ Handle the envelope:
 
 ## Stage 3.5: Configure consent (before activation)
 
-Activation's readiness check requires **consent AND routing** — a fully-routed channel still fails to activate if consent isn't configured. Invoke `service-de-channel-consent-configure`:
+Activation's readiness check requires **consent AND routing** — a fully-routed channel still fails to activate if consent isn't configured. Invoke `service-de-channel-settings-configure`:
 
 - `{CHANNEL_ID}` = recorded above
 - `{CONSENT_TYPE}`, `{LANGUAGE}`, and the keyword/prompt values — forward whatever the user supplied; omit what they didn't
@@ -248,7 +248,7 @@ Handle the envelope:
 | `{ok: true, isActive: true, ...}` (including `noop: true`) | Record results. Append `"activate"` to `STEPS_RUN`. Continue to Stage 5. |
 | `{ok: false, kind: "no-routing"}` | Unusual (we just set it) — probably a race or permission issue. Emit failure with a hint about the permissions check. Return. |
 | `{ok: false, kind: "no-mcu" \| "channel-missing"}` | Shouldn't happen after successful insert. Emit failure with the leaf's envelope. Return. |
-| `{ok: false, kind: "readiness-failed", errorMessage}` | `validateChannelReadinessOnProvisioning` rejected the PATCH — missing consent (STOP/HELP keyword record). Stage 3.5 should have caught this; if it re-appears, re-run `service-de-channel-consent-configure` for the channel. Emit failure and pass through the resume hint. Return. |
+| `{ok: false, kind: "readiness-failed", errorMessage}` | `validateChannelReadinessOnProvisioning` rejected the PATCH — missing consent (STOP/HELP keyword record). Stage 3.5 should have caught this; if it re-appears, re-run `service-de-channel-settings-configure` for the channel. Emit failure and pass through the resume hint. Return. |
 | `{ok: false, kind: "provisioning-error", errorReason, errorDetails}` | Third-party side rejected (Meta `/register` failed, etc.). MCU is now in `Error`. Emit failure and pass through `errorReason`/`errorDetails`. Return. |
 | `{ok: false, kind: "auth" \| "transport"}` | REST call failed at the HTTP layer (401 from `sf` auth, 5xx from the instance). Pass through. Return. |
 

package/skills/service-de-headless-channel-configure/references/worked-examples.md

@@ -26,7 +26,7 @@ Returns `{ok:true, channelId:"0MjSG...", mcuId:"0gLSG...", developerName:"WHATSA
 
 **Stage 3** (route): `service-de-channel-routing-configure` prompts user. User picks existing `Messaging_Queue` (`00GSG0000000LSf2AM`). PATCH lands. `STEPS_RUN=["insert","route"]`.
 
-**Stage 3.5** (consent): `service-de-channel-consent-configure` runs. The insert auto-seeded `ConsentType=ImplicitOptIn` + a default opt-out `MsgChannelLanguageKeyword` (STOP-family + confirmation), so the leaf's Stage 1 finds the channel already activation-ready and returns `noop:true` — no write needed. (Had the user asked for ExplicitOptIn/DoubleOptIn or custom keywords, the leaf would upgrade it here.) `STEPS_RUN=["insert","route"]`, `STEPS_SKIPPED=["consent"]`.
+**Stage 3.5** (consent): `service-de-channel-settings-configure` runs. The insert auto-seeded `ConsentType=ImplicitOptIn` + a default opt-out `MsgChannelLanguageKeyword` (STOP-family + confirmation), so the leaf's Stage 1 finds the channel already activation-ready and returns `noop:true` — no write needed. (Had the user asked for ExplicitOptIn/DoubleOptIn or custom keywords, the leaf would upgrade it here.) `STEPS_RUN=["insert","route"]`, `STEPS_SKIPPED=["consent"]`.
 
 **Stage 4** (activate): `service-de-channel-activate` PATCHes `MessagingChannelUsage.DeploymentStatus='Provisioning'` via REST. The PATCH blocks synchronously until the server-side observer chain finishes, then returns 204 with `DeploymentStatus=Active` → `channel.IsActive=true` in ~15-21s (Meta `/register` round-trip). `STEPS_RUN=["insert","route","activate"]`.
 

package/skills/service-helpagent-coordinate/SKILL.md

@@ -13,6 +13,7 @@ metadata:
     - "integration-connectivity-connected-app-configure"
     - "platform-metadata-deploy"
     - "service-agentforce-channel-configure"
+    - "service-agentforce-contact-center-coordinate"
     - "service-concierge-portal-generate"
     - "service-digital-engagement-channel-configure"
     - "service-digital-engagement-deployment-configure"
@@ -193,7 +194,7 @@ Deploy new channels with Queue routing (`service-digital-engagement-channel-conf
 
 - **Help Portal** → delegate to `service-concierge-portal-generate` (deploys an Agentforce Concierge experience on an LWR site). Pass the resolved `$ORG`, `$BOT_ID`, and `$BOT_DEV_NAME` so it can skip its entry-point questions.
 
-- **Voice** → read `references/channel-voice.md` and follow it fully. Voice wires an existing `PstnVoice` MessagingChannel via `service-agentforce-channel-configure` Branch B — it does not provision a phone number.
+- **Voice** → read `references/channel-voice.md` and follow it fully. Wires a `PstnVoice` MessagingChannel via `service-agentforce-channel-configure` Branch B; if none exists, the reference delegates procurement to `service-agentforce-contact-center-coordinate`.
 
 - **Any other existing channel (WhatsApp, SMS, Facebook, Apple Business Chat, Line, Email-to-Case, Custom)** → no dedicated reference file. List channels of that type from discovery, let the user pick one (`"Add agent to: {MasterLabel}"`), and delegate straight to `service-agentforce-channel-configure` with the agent and channel DeveloperNames — it resolves the fallback queue and picks the routing branch itself (Branch A for Enhanced Chat/Messaging, Branch C for Email-to-Case). This skill only wires an agent to a channel that already exists; it never provisions the underlying 3rd-party/email infrastructure.
 
@@ -256,5 +257,5 @@ The one deliverable is a single `report.md`: a **status report of what was decid
 | `references/agent-script.md` | At agent creation only (after Checkpoint 2) — the canonical agent script + placeholders |
 | `references/channel-web-chat.md` | Only if the user selects Web Chat at Checkpoint 3 |
 | `service-concierge-portal-generate` (external skill) | Only if the user selects Help Portal at Checkpoint 3 — delegate, do not inline |
-| `references/channel-voice.md` | Only if the user selects Voice (wires an existing `PstnVoice` channel; no number provisioning) |
+| `references/channel-voice.md` | Only if the user selects Voice (wires a `PstnVoice` channel; delegates procurement when none exists) |
 | `references/output-report-format.md` | Right before writing the final `report.md` — the two report shapes, templates, and scored-failure list |