@salesforce/afv-skills 1.41.0 → 1.43.0

package/skills/service-de-channel-routing-configure/references/target-locate.md

@@ -0,0 +1,98 @@
+---
+name: service-de-channel-routing-configure-target-locate
+description: "Load when configuring a non-queue routing type on service-de-channel-routing-configure (Flow, ASA, Digital Worker, or direct User). Holds the per-domain SOQL to locate and validate an eligible SessionHandler target, the exact Id shape each PATCH needs, the FallbackQueue requirement matrix, and the per-domain 'no eligible target' Setup pointer. DO NOT load this for the Omni-Channel Queue path — see references/queue-creation.md."
+metadata:
+  version: "1.0"
+  related-skills: service-de-channel-routing-configure
+---
+
+# Locating a SessionHandler target (Flow / ASA / Digital Worker / User)
+
+`MessagingChannel.SessionHandler` is a polymorphic foreign key. Its domain (from `MessagingChannel.entity.xml`) is `Queue, FlowDefinition, User, BotDefinition, AgenticCtxtDecorDefinition`. The Id prefix identifies the domain, and the server-side `validateSessionHandler` enforces a per-domain FallbackQueue rule that this skill must satisfy before the PATCH will succeed.
+
+## FallbackQueue requirement matrix (server-enforced)
+
+| routingType | SessionHandlerId prefix | FallbackQueueId |
+| --- | --- | --- |
+| queue | `00G` | **must be null** — a non-null value is rejected with `UnsupportedFallbackQueue` |
+| flow | `300` | **required** — null is rejected with *"A Fallback Queue must be specified when selecting a Flow routing method."* (verified live on sdb6c 2026-08-12) |
+| asa | `0Xx` | **required** — null rejected with `MissingFallbackQueueForAsaRouting` |
+| digital_worker | `1iE` | **required** — null rejected with `MissingFallbackQueueForDigitalWorkerRouting` |
+| user | `005` | **must be null** |
+
+For every FallbackQueue-required path, resolve a FallbackQueue **first** (see below) so the SessionHandler + FallbackQueue can be written in a single PATCH — the record must never sit in an invalid intermediate state.
+
+## Resolving a FallbackQueue (flow / asa / digital_worker)
+
+The FallbackQueue is an Omni-Channel-enabled, MessagingSession-capable Queue — the same eligibility as the primary Queue path. Enumerate and let the user pick (or reuse the one they already have in mind):
+
+```bash
+sf data query --target-org '{ORG_ALIAS}' \
+  --query "SELECT Id, Name, DeveloperName FROM Group WHERE Type = 'Queue' AND QueueRoutingConfigId != null AND Id IN (SELECT QueueId FROM QueueSobject WHERE SobjectType = 'MessagingSession') ORDER BY Name" \
+  --json > /tmp/ccr-fallback-queues.json
+```
+
+Each row's `Id` (a `00G` `Group.Id`) is a valid `{FALLBACK_QUEUE_ID}`. If this returns 0 rows, emit `{ok:false, kind:"no-fallback-queue", ...}` — the user must create a MessagingSession queue (queue path → `references/queue-creation.md`) before Flow/ASA/Digital Worker routing can be configured.
+
+---
+
+## Flow (`300` FlowDefinition) — VERIFIED live on sdb6c
+
+The SessionHandler value is the **`FlowDefinition.Id`** (`300`-prefixed), not the flow version. Eligible flows are `ProcessType='RoutingFlow'` with an active version. `ProcessType` lives on `FlowDefinitionView` (the `FlowDefinition` sObject has no `ProcessType` column), and `FlowDefinitionView.DurableId` equals the `300` FlowDefinition Id **only for org-local flows** (namespaced/packaged flows carry a `<namespace>__<ApiName>` DurableId that is *not* a `300` id and can't be used directly). So filter to org-local, active RoutingFlows:
+
+```bash
+sf data query --target-org '{ORG_ALIAS}' \
+  --query "SELECT DurableId, Label, ApiName, NamespacePrefix, IsActive, ActiveVersionId FROM FlowDefinitionView WHERE ProcessType = 'RoutingFlow' AND IsActive = true AND NamespacePrefix = null ORDER BY Label" \
+  --json > /tmp/ccr-flows.json
+```
+
+Keep only rows where `DurableId` starts with `300`. That `DurableId` is `{TARGET_ID}`. Present the list, let the user pick, resolve a FallbackQueue, then Stage 5 PATCH (`SessionHandlerId={TARGET_ID} FallbackQueueId={FALLBACK_QUEUE_ID}`).
+
+If 0 eligible rows: `{ok:false, kind:"no-eligible-target", routingType:"flow", hint:"no active Omni-Channel RoutingFlow found — build one in Setup → Flows (template 'Route Work Item' / process type Routing Flow) and activate it, then re-run this skill"}`.
+
+**Verified 2026-08-12 (sdb6c):** `DirectToAgentFlow` (`300SG0000002gw1YAA`, active RoutingFlow) + FallbackQueue `Messaging_Queue` (`00GSG0000000LSf2AM`) PATCHed onto Enhanced channel `Customer_Support` (`0MjSG0000004rIf0AI`) → success, both fields persisted. Nulling the FallbackQueue afterward was rejected with the "A Fallback Queue must be specified" message. Channel restored to null/null.
+
+---
+
+## ASA (`0Xx` BotDefinition) — VERIFIED live on sdb6c
+
+ASA = an Agentforce Service Agent bot: `BotDefinition WHERE Type='ExternalCopilot' AND AgentType='EinsteinServiceAgent'`, routable only if it has a linked bot user AND an active version. The full precondition/enumeration/selection detail lives in `references/asa-routing.md` — load that. ASA additionally **requires a FallbackQueue** (resolve one as above), which the PATCH writes alongside the `0Xx` SessionHandler.
+
+**Verified 2026-08-12 (sdb6c):** `Type='ExternalCopilot' AND AgentType='EinsteinServiceAgent'` returns two bots; one (`0XxSG000000Sv9p0AC`) has both `BotUserId` and an active `BotVersion` (routable), the other (`ASA2`) has no active version (listed but flagged not-live). Note: the Data-API `BotDefinition` sObject exposes only `Type` / `AgentType` / `AgentTemplate` (no version/rich-content columns) — the active-version check must go through the `BotVersions` child relationship / `BotUserId`, exactly as `references/asa-routing.md` does.
+
+---
+
+## Digital Worker (`1iE` AgenticCtxtDecorDefinition) — NOT live-verifiable on sdb6c
+
+The SessionHandler domain `AgenticCtxtDecorDefinition` (Digital Worker, added v262) is gated by the org permission `orgHasOmniChannelScrt2DigitalWorkerRouting` (per `LiveAgentPresenceUtilImpl.isActiveDigitalWorker`). On sdb6c that object is **not SOQL-addressable** (`INVALID_TYPE`), which means the perm/feature isn't enabled there — so this path could not be verified against a live org.
+
+Intended locate (unverified — validate against an org that has the perm before relying on it):
+
+```bash
+sf data query --target-org '{ORG_ALIAS}' \
+  --query "SELECT Id, DeveloperName, MasterLabel FROM AgenticCtxtDecorDefinition ORDER BY MasterLabel" \
+  --json > /tmp/ccr-digital-workers.json
+```
+
+`Id` (`1iE`-prefixed) is `{TARGET_ID}`. FallbackQueue is **required** (server rejects null with `MissingFallbackQueueForDigitalWorkerRouting`). If the object errors with `INVALID_TYPE`, emit `{ok:false, kind:"no-eligible-target", routingType:"digital_worker", hint:"this org doesn't have Digital Worker routing enabled (AgenticCtxtDecorDefinition not available) — use a different routing type or contact your Salesforce rep to enable it"}`.
+
+---
+
+## User (`005`) — PARTIALLY verified on sdb6c
+
+Direct-to-user routing points SessionHandler at a `User` with FallbackQueue **null**. `validateSessionHandler` additionally requires the user to have a RoutingConfiguration (else `NoRoutingConfigDefined`) — but this is **not** a direct field on `User` (`User.RoutingConfigurationId` does not exist). The linkage runs through Omni-Channel presence configuration: `PresenceUserConfig` (the config, which references a routing/priority setup) joined to users via `PresenceUserConfigUser`.
+
+Locate eligible users (those assigned to a presence config, which carries the routing configuration):
+
+```bash
+# users assigned to an Omni-Channel presence config
+sf data query --target-org '{ORG_ALIAS}' \
+  --query "SELECT UserId, User.Name, PresenceUserConfigId FROM PresenceUserConfigUser WHERE User.IsActive = true ORDER BY User.Name" \
+  --json > /tmp/ccr-users.json
+```
+
+`UserId` (`005`-prefixed) is `{TARGET_ID}`; FallbackQueue stays null. Present, let the user pick, then Stage 5 PATCH (`SessionHandlerId={TARGET_ID}` only).
+
+If 0 rows: `{ok:false, kind:"no-eligible-target", routingType:"user", hint:"no users are assigned to an Omni-Channel presence configuration with routing — set one up in Setup → Omni-Channel → Presence Configurations, then re-run this skill"}`.
+
+**Verified 2026-08-12 (sdb6c):** the *persisted-state* rule is confirmed — Enhanced channel `Facebook_US_104218168883106` (`0MjSG0000000C7d0AE`) carries `SessionHandlerId=005SG00000051bNYAQ` with `FallbackQueueId=null`, so User-as-SessionHandler with a null FallbackQueue is a valid live configuration. The *locate query* (`PresenceUserConfigUser`) and the RoutingConfiguration precondition were not exercised end-to-end via a fresh PATCH; treat the enumeration query as best-effort and confirm the picked user actually has routing before relying on activation.

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

@@ -0,0 +1,174 @@
+# Worked examples: `service-de-channel-routing-configure`
+
+Reference runs:
+
+- Queue path: reuse an existing queue (fast path) and create a new queue via the Metadata API (slow path). Both validated against test1.
+- Flow path: attach an active Omni-Channel RoutingFlow with a fallback queue. Validated live against sdb6c 2026-08-12.
+- ASA path: pick an existing live ASA with a fallback queue. Enumeration/selection validated against sdb14-test; the ASA `Type/AgentType` filter and routable-vs-not-live split re-verified live on sdb6c 2026-08-12.
+
+---
+
+## Worked example: reuse an existing Queue on test1
+
+Verified by inspection on `messagingsdb6ccom.test1.my.pc-rnd.salesforce.com`, 2026-04-30. Input:
+
+- `{CHANNEL_ID}` = `0MjSG000000Fc1l0AC` (the WhatsApp channel)
+
+**Stage 1** read shows `SessionHandlerId = 00GSG0000000LSf2AM`, so this channel would short-circuit to the no-op path and report:
+
+```json
+{"ok": true, "noop": true, "sessionHandlerId": "00GSG0000000LSf2AM", "queueName": "Messaging Queue", "message": "Routing already configured"}
+```
+
+If the channel were freshly inserted with `SessionHandlerId = null`, the skill would:
+- Stage 3: list existing queues (`Messaging Queue`, `MyQueue`, ...)
+- User picks `Messaging Queue` → `{QUEUE_ID} = 00GSG0000000LSf2AM`
+- Stage 5: PATCH
+- Stage 6: verify
+- Stage 7: report `Success — Routing configured — channel 0MjSG000000Fc1l0AC now routes to Queue 'Messaging Queue' (reused existing queue).`
+
+## Worked example: create a new Queue
+
+Input:
+- `{CHANNEL_ID}` = `0MjSG000000NewChannel`
+- User chooses "create new" with `Label="WhatsApp Demo Queue"`, `DevName="WhatsApp_Demo_Queue"`, `RoutingModel=MostAvailable`, `AddSelf=Y`
+
+**Stages 1–3**: channel has null routing, user picks "create new".
+
+**Stage 4**: skill writes to `/tmp/ccr-metadata-<ts>/`:
+- `force-app/main/default/queues/WhatsApp_Demo_Queue.queue-meta.xml`
+- `force-app/main/default/queueRoutingConfigs/WhatsApp_Demo_Queue_Routing.queueRoutingConfig-meta.xml`
+- `sfdx-project.json`
+
+`sf project deploy start` succeeds. Re-query returns `{Id: '00GSG00000NewQueue01'}`.
+
+GroupMember insert adds the current user to the queue.
+
+**Stage 5**: PATCH `MessagingChannel.SessionHandlerId = 00GSG00000NewQueue01`.
+
+**Stage 6**: verify.
+
+**Stage 7**: `Success — Routing configured — channel 0MjSG000000NewChannel now routes to Queue 'WhatsApp Demo Queue'.`
+
+---
+
+## Worked example: attach an Omni-Channel Flow (verified live on sdb6c)
+
+Verified live on `messaging_sdb6c` 2026-08-12. Input:
+
+- `{CHANNEL_ID}` = `0MjSG0000004rIf0AI` (Enhanced channel `Customer_Support`, `SessionHandlerId = null`)
+
+**Stage 1**: read shows `SessionHandlerId = null, FallbackQueueId = null`. Continue.
+
+**Stage 2**: `PlatformType = Enhanced` confirmed. User picks `2) flow`.
+
+**Locate (references/target-locate.md)** — active, org-local RoutingFlows:
+
+```soql
+SELECT DurableId, Label, ApiName, NamespacePrefix, IsActive, ActiveVersionId
+FROM FlowDefinitionView
+WHERE ProcessType = 'RoutingFlow' AND IsActive = true AND NamespacePrefix = null
+ORDER BY Label
+```
+
+Returns org-local flows whose `DurableId` is the `300` FlowDefinition Id (e.g. `DirectToAgentFlow` → `300SG0000002gw1YAA`). User picks it → `{TARGET_ID} = 300SG0000002gw1YAA`.
+
+**Resolve FallbackQueue** (required for Flow): eligible-queue query returns `Messaging_Queue` (`00GSG0000000LSf2AM`). User picks it → `{FALLBACK_QUEUE_ID} = 00GSG0000000LSf2AM`.
+
+**Stage 5**: single PATCH writing both fields:
+
+```bash
+$ sf data update record --sobject MessagingChannel --record-id 0MjSG0000004rIf0AI \
+    --values 'SessionHandlerId=300SG0000002gw1YAA FallbackQueueId=00GSG0000000LSf2AM'
+# → success
+```
+
+(A PATCH that sets the Flow SessionHandler but leaves FallbackQueue null is rejected server-side: *"A Fallback Queue must be specified when selecting a Flow routing method."* — observed live.)
+
+**Stage 6**: re-read returns `SessionHandlerId = 300SG0000002gw1YAA, FallbackQueueId = 00GSG0000000LSf2AM`. Verified.
+
+**Stage 7**:
+
+```json
+{"ok": true, "routingType": "flow", "sessionHandlerId": "300SG0000002gw1YAA",
+ "fallbackQueueId": "00GSG0000000LSf2AM", "flowName": "DirectToAgentFlow",
+ "flowDeveloperName": "DirectToAgentFlow", "created": false}
+```
+
+User-facing: `Success — Routing configured — channel 0MjSG0000004rIf0AI now routes to Omni-Flow 'DirectToAgentFlow' (300SG0000002gw1YAA), fallback Queue 00GSG0000000LSf2AM.`
+
+*(The test channel was restored to `SessionHandlerId=null, FallbackQueueId=null` afterward.)*
+
+---
+
+## Worked example: pick an existing live ASA on sdb14-test
+
+Verified on `sdb14com-a8.test2.my.pc-rnd.salesforce.com` (`sdb14-test`), 2026-05-12. The fast path: an Agentforce-licensed org has ASAs already authored and we just need to attach one. Input:
+
+- `{CHANNEL_ID}` = `0MjRZ00000004210AA` (a freshly-inserted WhatsApp channel)
+
+**Stage 1**: channel has `SessionHandlerId = null, FallbackQueueId = null`. Continue.
+
+**Stage 2**: user picks `2) asa`.
+
+**Stage 3-ASA.0** precondition check:
+```bash
+$ sf sobject describe --target-org sdb14-test --sobject BotDefinition 2>&1 | grep -q "does not exist" && echo MISSING || echo PRESENT
+PRESENT
+```
+Continue.
+
+**Stage 3-ASA.1** enumerate active ASAs (one query, child-relationship form works on this org):
+
+```soql
+SELECT Id, DeveloperName, MasterLabel, BotUserId,
+       (SELECT Id, Status FROM BotVersions WHERE Status='Active' LIMIT 1)
+FROM BotDefinition
+WHERE Type='ExternalCopilot' AND AgentType='EinsteinServiceAgent'
+ORDER BY MasterLabel
+```
+
+Returns 25 rows. After post-processing (filter rows where `BotUserId != null` AND `BotVersions[0].Status == 'Active'`), 13 are routable.
+
+**Stage 3-ASA.2** prompt:
+
+```text
+Existing Agentforce Service Agents on sdb14-test:
+
+  1) Agentforce Service Agent KAFile (Agentforce_Service_Agent_KAFile) — 0XxRZ0000002ZWL0A2 [live]
+  2) Agentforce Service Agent Test (Agentforce_Service_Agent_Test) — 0XxRZ0000002kJh0AI [live]
+  3) BYO Service Agent (BYO_Service_Agent) — 0XxRZ0000002lAv0AI [live]
+  4) MON ASA Apex (MON_ASA_Apex) — 0XxRZ0000003APR0A2 [live]
+  ...
+
+Pick [1-13]: 4
+```
+
+Records: `{ASA_ID} = 0XxRZ0000003APR0A2`, `{ASA_LABEL} = "MON ASA Apex"`, `{ASA_DEV_NAME} = "MON_ASA_Apex"`, `{BOT_USER_ID} = 005RZ000001wJ3JYAU`, `{BOT_VERSION_ID} = 0X9RZ0000002b8L0AQ`.
+
+**Stage 3-ASA.3** resolve FallbackQueue (required for ASA): eligible-queue query returns a MessagingSession queue; user picks it → `{FALLBACK_QUEUE_ID} = 00GRZ0000000abc0AA`.
+
+**Stage 5**: single PATCH writing both fields — `sf data update record --sobject MessagingChannel --record-id 0MjRZ00000004210AA --values 'SessionHandlerId=0XxRZ0000003APR0A2 FallbackQueueId=00GRZ0000000abc0AA'` succeeds. (Omitting the FallbackQueue would be rejected with `MissingFallbackQueueForAsaRouting`.)
+
+**Stage 6**: re-read returns `SessionHandlerId = 0XxRZ0000003APR0A2, FallbackQueueId = 00GRZ0000000abc0AA`. Verified.
+
+**Stage 7**:
+
+```json
+{
+  "ok": true,
+  "routingType": "asa",
+  "sessionHandlerId": "0XxRZ0000003APR0A2",
+  "fallbackQueueId": "00GRZ0000000abc0AA",
+  "asaName": "MON ASA Apex",
+  "asaDeveloperName": "MON_ASA_Apex",
+  "botUserId": "005RZ000001wJ3JYAU",
+  "botVersionId": "0X9RZ0000002b8L0AQ",
+  "created": false
+}
+```
+
+User-facing: `Success — Routing configured — channel 0MjRZ00000004210AA now routes to Agentforce Service Agent 'MON ASA Apex' (0XxRZ0000003APR0A2), fallback Queue 00GRZ0000000abc0AA. Bot user: 005RZ000001wJ3JYAU. Active version: 0X9RZ0000002b8L0AQ.`
+
+Total elapsed: ~3s (SOQL + PATCH, no external callouts needed).
+

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

@@ -0,0 +1,305 @@
+---
+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."
+metadata:
+  version: "1.0"
+  minApiVersion: "67.0"
+  domains: ["Service"]
+  cliTools:
+    - tool: ["sf"]
+      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-waba-integrate"
+---
+
+# Headless Channel Setup (type-agnostic)
+
+## What this skill does
+
+Takes a channel type (`WhatsApp` | `Line` | `AppleBusinessChat` | `Facebook` | `Text`) plus its type-specific inputs and drives it to an activated `MessagingChannel`. It first gates on the Enhanced Messaging Terms and Conditions, then runs four steps:
+
+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`)*
+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.
+
+**Prompt mid-flow.** If `{MESSAGE_TYPE}` isn't in the initial request, the orchestrator asks upfront. Routing choices (pick queue / create new) are prompted when step 2 runs, not upfront — keeps leaf skills self-contained.
+
+## Reference File Index
+
+| Reference file | Load when |
+| --- | --- |
+| `references/inputs.md` | You need the full input field list — MESSAGE_TYPE/ORG_ALIAS plus per-type fields for WhatsApp, LINE, AppleBusinessChat, Facebook, Text (SMS). |
+| `references/terms-and-conditions.md` | Rendering the Stage 0.5 disclaimer and certification prompt — verbatim text and per-type label/third-party mappings. |
+| `references/output-envelopes.md` | Wiring error handling or parsing the canonical success/failure/terms-declined JSON envelope shapes. |
+| `references/partial-success.md` | The orchestrator fails mid-way and you need to render the partial-success/resume report. |
+| `references/gotchas.md` | Debugging unexpected behavior — duplicate-key errors, resume/idempotency questions, preflight SOQL shape, unattended/CI usage. |
+| `references/worked-examples.md` | You need a reference trace (fresh WhatsApp run, resume after failure, Apple dispatch, unsupported-type rejection) for exact envelope shapes. |
+
+---
+
+## Critical execution rule
+
+**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:
+
+- **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
+- **DO NOT:** Stop and report back to the user between stages
+- **DO NOT:** Wait for user confirmation between stages
+- **DO NOT:** Treat each stage as a separate turn in the conversation
+
+**Why this matters:** The user invoked THIS orchestrator skill to get an end-to-end activated channel. They did NOT invoke the individual leaf skills. Your job is to run the entire pipeline autonomously and report the final result. Stopping mid-flow breaks the orchestrator pattern and forces the user to manually resume each stage.
+
+**Exception:** Only stop mid-flow if a leaf skill returns `ok: false` with a terminal error (not a recoverable prompt), or if the user declines the Stage 0.5 Terms and Conditions gate (emit `terms-not-accepted` and halt). Then report the failure immediately with context about which stage failed and what state was reached.
+
+**Stage 0.5 is a required blocking prompt.** The Terms and Conditions gate is the one prompt that must be answered affirmatively before any org work. It is not optional and must not be auto-accepted. A `no`/decline ends the run per the exception above; a `yes` continues to Stage 1 in the same response.
+
+**Leaf skill prompts:** Some leaf skills (like `service-de-waba-integrate` or `service-de-channel-routing-configure`) may prompt the user for input mid-execution. That's fine — answer those prompts as they come up, but then CONTINUE to the next stage immediately after the prompt is answered. Don't stop just because a prompt was involved.
+
+---
+
+## When NOT to use this skill
+
+- **You only want one step.** Invoke the leaf skill directly (`service-de-channel-create`, `service-de-channel-routing-configure`, `service-de-channel-activate`). This orchestrator is for the full automated path from nothing → activated channel.
+- **You want to run stages independently in separate conversation turns.** This orchestrator runs all stages consecutively in one response. If you need manual control between stages, invoke the leaf skills individually.
+- **You want a message type outside `WhatsApp` / `Line` / `AppleBusinessChat` / `Facebook` / `Text`.** The dispatcher will return `unsupported-type`. WeChat / MsCopilot / Alexa would need their own leaves + a dispatcher update.
+- **The prereq hasn't been met (WABA not shared, LINE channel not created, Apple account not registered, SMS number not provisioned).** The per-type insert skill's Stage 2-equivalent surfaces this clearly and returns; no orchestration fixes it. (For SMS/Text the number-provisioning prereq isn't checked at insert — an unprovisioned number surfaces later as an activation-time `provisioning-error`.)
+
+## Inputs (from user)
+
+`{MESSAGE_TYPE}` (prompted if omitted) and `{ORG_ALIAS}` (optional), plus type-specific fields for WhatsApp, LINE, AppleBusinessChat, Facebook, and Text (SMS) forwarded to the dispatcher. **Load `references/inputs.md` and follow it** for the full field list and the omitted-type prompt text.
+
+## Output (to user)
+
+Three top-level outcomes: success, step-annotated failure, and terms-declined. **Load `references/output-envelopes.md` and follow it** for the exact JSON shapes.
+
+---
+
+## Stage 0: Resolve `{MESSAGE_TYPE}` and type-specific key
+
+If `{MESSAGE_TYPE}` is omitted, prompt the user (see "Inputs" above). Refuse to proceed without one — there's no sensible default.
+
+Once known, determine the **preflight key** — the field we'll filter the `MessagingChannel` SOQL on to detect existing state. It's always `MessagingPlatformKey`, but what that value *is* varies by type:
+
+| `{MESSAGE_TYPE}` | Preflight key value `{PLATFORM_KEY}` | Notes |
+| --- | --- | --- |
+| `WhatsApp` | `{PHONE_NUMBER_ID}` | Required upfront |
+| `Line` | `{LINE_CHANNEL_ID}` | Required upfront |
+| `AppleBusinessChat` | `{APPLE_BC_ID}` | Required upfront |
+| `Facebook` | `{PAGE_ID}` | Optional - OAuth → fetch pages → prompt if not provided |
+| `Text` | `{SMS_NUMBER}` | Required upfront (the phone number / short code itself) |
+
+**Facebook is unique:** If `{PAGE_ID}` is not provided, the orchestrator cannot run its own Stage 1 preflight. Instead, skip Stage 1 and let `service-de-channel-create` handle the full OAuth → page selection → preflight → creation flow. The insertion skill has its own Stage 1 preflight that runs after page selection.
+
+For non-Facebook types, validate that the caller provided the required type-specific inputs for `{MESSAGE_TYPE}` (see Inputs above). If missing, prompt or halt — don't call the dispatcher, it will re-validate and return `missing-input`, wasting a round trip.
+
+---
+
+## Stage 0.5: Enhanced Messaging Terms and Conditions (blocking gate)
+
+**Run this before any org query or channel work.** The in-org "Add a Channel" wizard requires the admin to accept the Enhanced Messaging Terms and Conditions before it will let them proceed to channel setup. The headless flow must enforce the same gate — do not skip it, do not accept on the user's behalf. This runs once per orchestrator invocation, after `{MESSAGE_TYPE}` is known (the disclaimer names the channel) and before Stage 1.
+
+**Render the disclaimer and certification prompt from `references/terms-and-conditions.md` (verbatim, substituting the channel label) — load it and follow it for the exact wording and per-type label/third-party mappings.**
+
+**Gate behavior:**
+
+- If the user answers **yes** (affirmative acceptance), record `{TC_ACCEPTED} = true` and continue to Stage 1.
+- If the user answers **no**, declines, or does not affirmatively accept, **halt immediately** — do not run Stage 1 or any subsequent stage. Emit:
+  ```json
+  {"ok": false, "kind": "terms-not-accepted",
+   "hint": "user did not accept the Enhanced Messaging Terms and Conditions — channel setup cannot proceed. Re-run when ready to accept."}
+  ```
+- Acceptance is required on **every** orchestrator invocation, including resume runs. It is a per-session gate, not persisted — we don't have a place to durably record it, and the cost of re-confirming is one prompt.
+
+---
+
+## Stage 1: Pre-flight state detection (resume support)
+
+**Skip this stage entirely if `MESSAGE_TYPE=Facebook` and `{PAGE_ID}` was not provided.** The Facebook insertion skill needs to run OAuth first before we know which PAGE_ID to check for. Let the insertion skill handle its own preflight in Stage 1 after page selection.
+
+For all other cases, query the org to see how far a prior run got. This enables skip-ahead on resume. **Two queries, not a subquery** — the `(SELECT ... FROM MessagingChannelUsages)` subquery fails on some orgs where the child relationship is unnameable. Use FK-keyed second query instead (see gotcha #9).
+
+```bash
+sf data query --target-org '{ORG_ALIAS}' \
+  --query "SELECT Id, DeveloperName, MessageType, IsActive, SessionHandlerId, FallbackQueueId FROM MessagingChannel WHERE MessagingPlatformKey = '{PLATFORM_KEY}' AND MessageType = '{MESSAGE_TYPE}'" \
+  --json > /tmp/hcs-preflight.json
+```
+
+If the channel query returns a row, fire a second query to resolve its MCU:
+
+```bash
+sf data query --target-org '{ORG_ALIAS}' \
+  --query "SELECT Id, DeploymentStatus FROM MessagingChannelUsage WHERE MessagingChannelId = '{CHANNEL_ID}'" \
+  --json > /tmp/hcs-preflight-mcu.json
+```
+
+Parse the combined result to figure out `{CURRENT_STATE}`:
+
+| Preflight result | `CURRENT_STATE` | First step to run |
+| --- | --- | --- |
+| No records | `fresh` | Step 1 (insert) |
+| Record exists, `IsActive=false`, `SessionHandlerId=null` and `FallbackQueueId=null` | `inserted-no-routing` | Step 2 (configure routing) |
+| Record exists, `IsActive=false`, routing set | `routed-not-active` | Step 3 (configure consent), then Step 4 (activate) |
+| Record exists, `IsActive=true` | `already-active` | Emit no-op success envelope; return. |
+
+Record the existing `{CHANNEL_ID}` and `{MCU_ID}` if present — downstream steps need them.
+
+Initialize `{STEPS_RUN} = []`, `{STEPS_SKIPPED} = []`, `{T0} = Date.now()`.
+
+---
+
+## Stage 2: Insert the channel (step 1 of 4)
+
+Skip this stage if `CURRENT_STATE` ∈ `{inserted-no-routing, routed-not-active, already-active}` — the channel already exists. Append `"insert"` to `STEPS_SKIPPED` in that case.
+
+Otherwise invoke `service-de-channel-create` with:
+
+- `{MESSAGE_TYPE}` = (from Stage 0)
+- All type-specific inputs (forwarded verbatim — dispatcher routes to the right leaf)
+- `{ORG_ALIAS}`
+
+The insertion skill handles per-type prereqs internally (e.g., for WhatsApp, `service-de-channel-create` invokes `service-de-waba-integrate` as its Stage 2). This orchestrator doesn't need to know about WABA linking, LINE token verification, or Apple registration — `service-de-channel-create` owns the prereq semantics for whichever type it's running.
+
+Handle the envelope:
+
+| Leaf envelope | Orchestrator action |
+| --- | --- |
+| `{ok: true, channelId, mcuId, ...}` | Record `{CHANNEL_ID}` and `{MCU_ID}`. Append `"insert"` to `STEPS_RUN`. Continue. |
+| `{ok: false, kind: "partnership-blocked" \| "user-declined" \| "apple-registration-pending" \| "line-prereq-missing"}` | These come from the per-type prereq stage. Pass through as `failedStep: "insert"`, `failedStepIndex: 1`. Return. |
+| `{ok: false, kind: "missing-input" \| "unsupported-type"}` | Should have been caught in Stage 0 — emit failure with `failedStep: "insert"` and a note that the caller's inputs were incomplete. |
+| `{ok: false, kind: <anything else>}` | Emit failure envelope with `failedStep: "insert"`, `failedStepIndex: 1`. Return. |
+
+At this point we have `{CHANNEL_ID}` and `{MCU_ID}` regardless of whether step 1 ran or was skipped.
+
+**→ Continue immediately to Stage 3 in this same response. DO NOT STOP.**
+
+---
+
+## Stage 3: Configure routing (step 2 of 4)
+
+Skip this stage if `CURRENT_STATE === "routed-not-active"` — routing is already set. Append `"route"` to `STEPS_SKIPPED`.
+
+Otherwise invoke `service-de-channel-routing-configure`:
+
+- `{CHANNEL_ID}` = recorded above
+- `{ORG_ALIAS}`
+
+This is the step that **prompts the user** for queue choice (pick existing / create new / escape hatch). Don't try to pre-empt the prompts — forward the user's answers as-is.
+
+Handle the envelope:
+
+| Leaf envelope | Orchestrator action |
+| --- | --- |
+| `{ok: true, sessionHandlerId, queueName, ...}` (including `noop: true`) | Record `{SESSION_HANDLER_ID}` and `{QUEUE_NAME}`. Append `"route"` to `STEPS_RUN`. Continue. |
+| `{ok: false, kind: "unsupported-routing-type", ...}` | User chose flow/user/asa/aea. Emit partial-success with `failedStep: "route"` and a resume hint pointing at the UI. Return. |
+| `{ok: false, kind: "metadata-deploy-failed" \| "patch-failed" \| "verify-failed"}` | Emit failure envelope with `failedStep: "route"`. Return. |
+
+**→ Continue immediately to Stage 3.5 in this same response. DO NOT STOP.**
+
+---
+
+## 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`:
+
+- `{CHANNEL_ID}` = recorded above
+- `{CONSENT_TYPE}`, `{LANGUAGE}`, and the keyword/prompt values — forward whatever the user supplied; omit what they didn't
+- `{ORG_ALIAS}`
+
+This stage **ensures consent is activation-ready** — it doesn't always write. The Connect insert **auto-seeds** `ConsentType=ImplicitOptIn` plus a default opt-out `MsgChannelLanguageKeyword`, which already satisfies the readiness check. So the leaf's Stage 1 will frequently find the channel *already* ready and return `noop: true` — the expected outcome on a fresh `ImplicitOptIn` channel, not a bug. It performs a **real write only** to upgrade (ExplicitOptIn/DoubleOptIn) or override the seeded keywords/prompts. When the user pre-supplied inputs asking for an upgrade, expect a write and let the leaf prompt for missing values — don't suppress those prompts.
+
+Handle the envelope:
+
+| Leaf envelope | Orchestrator action |
+| --- | --- |
+| `{ok: true, ...}` (including `noop: true`) | Append `"consent"` to `STEPS_RUN` (or `STEPS_SKIPPED` if `noop`). Continue. |
+| `{ok: false, kind: "not-enhanced"}` | Shouldn't happen — these skills only create Enhanced channels. Emit failure with `failedStep: "consent"`. Return. |
+| `{ok: false, kind: "missing-consent-input", hint}` | The user didn't supply a required keyword/prompt for the chosen ConsentType. Emit failure with `failedStep: "consent"` and pass through the `hint`. Return. |
+| `{ok: false, ...}` (any other kind — `channel-patch-failed`, `keyword-record-failed`, `verify-failed`, or an unrecognized envelope) | Emit failure with `failedStep: "consent"` and pass through the leaf's `kind` and message verbatim. Return. |
+
+**→ Continue immediately to Stage 4 in this same response. DO NOT STOP.**
+
+---
+
+## Stage 4: Activate (step 4 of 4)
+
+Always run (unless `CURRENT_STATE === "already-active"`, in which case Stage 1 returned early).
+
+Invoke `service-de-channel-activate`:
+
+- `{CHANNEL_ID}` = recorded above
+- `{ORG_ALIAS}`
+
+No timeout knobs — activation is a single synchronous PATCH. The leaf does a defensive poll if the server ever returns mid-transition, but the expected path is one round-trip.
+
+Handle the envelope:
+
+| Leaf envelope | Orchestrator action |
+| --- | --- |
+| `{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: "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. |
+
+---
+
+## Stage 5: Final report
+
+Build the success envelope:
+
+```json
+{
+  "ok": true,
+  "messageType": "{MESSAGE_TYPE}",
+  "channelId": "{CHANNEL_ID}",
+  "mcuId": "{MCU_ID}",
+  "channelName": "{CHANNEL_NAME or inferred}",
+  "sessionHandlerId": "{SESSION_HANDLER_ID}",
+  "queueName": "{QUEUE_NAME}",
+  "isActive": true,
+  "stepsRun": [...],
+  "stepsSkipped": [...],
+  "totalDurationMs": Date.now() - T0
+}
+```
+
+Render to the user as:
+
+```text
+Success — {MESSAGE_TYPE} channel '{CHANNEL_NAME}' is live on {ORG_ALIAS}.
+   Channel ID: {CHANNEL_ID}
+   Routed to: {queueName} ({SESSION_HANDLER_ID})
+   Steps: ran {STEPS_RUN.join(", ")}{, skipped " + STEPS_SKIPPED.join(", ") if any}
+   Total time: {formatted from durationMs}
+```
+
+If any step was skipped due to resume, the report should make that visible.
+
+---
+
+## Partial-success and resume reporting
+
+If the orchestrator fails mid-way, the envelope always includes `stateSoFar` describing what landed. **`stateSoFar` must always carry both `stepsRun` and `stepsSkipped`** (each an array, empty if nothing landed/skipped yet) alongside the fields that landed — the partial-success renderer reads both. **When rendering a failure, load `references/partial-success.md` and follow it** — it has the exact template for showing which steps already landed and how to retry.
+
+---
+
+## Worked examples
+
+For reference traces (fresh WhatsApp run, resume after routing failure, Apple dispatch, unsupported-type rejection), see `references/worked-examples.md`.
+
+---
+
+## Gotchas
+
+Nine known gotchas covering prereq ownership, `MessagingPlatformKey` uniqueness, resume semantics, CSOT-only support, error-classification boundaries, prompt placement, platform-key mapping, wall-clock duration, and the two-query preflight workaround. **When debugging unexpected behavior, load `references/gotchas.md` and follow it.**

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

@@ -0,0 +1,27 @@
+---
+name: service-de-headless-channel-configure-gotchas
+description: "Load when debugging unexpected orchestrator behavior — duplicate-key errors, resume/idempotency questions, preflight SOQL shape, or unattended/CI usage of the headless channel setup orchestrator. Covers the nine known gotchas: prereq ownership, MessagingPlatformKey uniqueness, resume-by-reinvocation, CSOT-only support, error-classification boundaries, prompt placement, platform-key mapping, wall-clock duration, and the two-query preflight. DO NOT load during a normal end-to-end run with no errors."
+metadata:
+  version: "1.0"
+  related-skills: service-de-headless-channel-configure
+---
+
+# Gotchas
+
+1. **Type-specific prereqs are owned by the insertion skill, not this orchestrator.** For WhatsApp, `service-de-channel-create` handles the WABA-linking prompt internally. For Line/Apple, `service-de-channel-create` is likewise responsible for its own credential-collection prereq, per the `MESSAGE_TYPE` it's given. This orchestrator stays type-agnostic — it doesn't know (or want to know) what a WABA is.
+
+2. **Idempotency relies on `(MessagingPlatformKey, MessageType)` uniqueness.** The preflight query keys off the pair. If there are stale/deleted channels with the same key, SF should prevent duplicates on insert (DB uniqueness constraint on `(MessagePlatform, MessageType, MessagingPlatformKey)` for active rows). If insert fails with `DUPLICATE_VALUE` but preflight found no record, the backing MCU index is inconsistent — escalate to user.
+
+3. **Resume is opt-in-by-reinvocation, not background.** The orchestrator doesn't store state files — it re-queries on each run. Keeps it simple.
+
+4. **Step ordering assumes CSOT channels (Enhanced).** Legacy pre-CSOT channels used different activation paths (`activateWhatsAppNumber`, etc.). Not supported here.
+
+5. **Don't catch transport/internal errors at this layer.** The leaf skills handle that — by the time a failure reaches this orchestrator, it's already classified into `ok:false, kind:"..."`. Just annotate which step failed.
+
+6. **The orchestrator's prompts are limited to Stage 0 (type if omitted) and Stage 3 (routing choices).** Stages 2 and 4 are non-interactive. For fully-unattended mode (CI, cron), you need `{MESSAGE_TYPE}` supplied, and either (a) use an already-configured queue so Stage 3 no-ops, or (b) add a `--queue-id` override. Not built yet.
+
+7. **Channel-agnostic preflight keys off `{PLATFORM_KEY}`, not the type-specific id name.** The SOQL filter is always `MessagingPlatformKey = '{PLATFORM_KEY}'`. Map the per-type input to `{PLATFORM_KEY}` once at Stage 0 rather than branching the SOQL — keeps Stage 1 one query, not three.
+
+8. **Total duration is wall-clock, not sum-of-steps.** If the user pauses mid-prompt in Stage 0 or Stage 3, `totalDurationMs` includes think time. For perf analysis, care about the per-leaf `durationMs` values.
+
+9. **Preflight uses two queries, not a subquery.** The `MessagingChannel` → `MessagingChannelUsage` child relationship is `MessagingChannelUsages` on some orgs (`test1`) but unnameable on others (`wadtesting` has `relationshipName: None` in `sf sobject describe`). Subqueries fail with `INVALID_TYPE` on the latter. FK-keyed second query (`MessagingChannelUsage WHERE MessagingChannelId = '{CHANNEL_ID}'`) works everywhere. Cost is one extra SOQL per preflight — negligible.