@salesforce/afv-skills 1.41.0 → 1.43.0

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

@@ -0,0 +1,345 @@
+---
+name: service-de-channel-routing-configure
+description: "Configure routing on a newly-inserted Enhanced `MessagingChannel` so that activation will accept it. Given a `{CHANNEL_ID}`, walks the user through picking a routing type (Omni-Channel Queue, Omni-Flow, Agentforce Service Agent, Digital Worker, or direct User), locates or provisions the routing target, then PATCHes the channel's `SessionHandlerId` (plus `FallbackQueueId` where required) to it. Use between the insertion skill and the activation skill — activation fails server-side with `nullQueueId` / `LiveMessageSetupException` if no valid `SessionHandlerId` is set on the channel."
+metadata:
+  version: "1.1"
+  minApiVersion: "67.0"
+  domains: ["Service"]
+  cliTools:
+    - tool: ["node"]
+      semver: ">=20.0.0"
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+  relatedSkills:
+    - "service-de-channel-activate"
+    - "service-de-channel-consent-configure"
+    - "service-de-channel-create"
+    - "service-de-headless-channel-configure"
+---
+
+# Configuring Channel Routing
+
+## What this skill does
+
+Ensures a `MessagingChannel` has valid routing configured before activation. The channel's `SessionHandler` field is a **polymorphic foreign key** (verified against `MessagingChannel.entity.xml`, `domain="Queue, FlowDefinition, User, BotDefinition, AgenticCtxtDecorDefinition"`) — it names *who* the channel routes incoming sessions to. Some targets additionally require a `FallbackQueue` (an Omni-Channel Queue that catches sessions the primary target can't take).
+
+These skills create **Enhanced** channels (`PlatformType=Enhanced`, SCRT2). All five SessionHandler domains are writable on Enhanced channels. (A Standard/SCRT1 channel would only accept a Flow as SessionHandler — the server rejects any other domain with "Only flows of type Omni-Channel are supported". These skills never create Standard channels, so that path isn't handled here.)
+
+**Where this fits:** the channel is inserted by `service-de-channel-create` (or a per-type leaf); this skill sets routing; `service-de-channel-consent-configure` sets consent; then `service-de-channel-activate` flips it live — activation requires both routing and consent. The `service-de-headless-channel-configure` orchestrator runs all four in sequence.
+
+Supported routing types — all set `SessionHandlerId`, some also set `FallbackQueueId`:
+
+| Type | SessionHandler target | Id prefix | FallbackQueue |
+| --- | --- | --- | --- |
+| **Omni-Channel Queue** | `Group` (Type=Queue) | `00G` | must be **null** |
+| **Omni-Flow** | `FlowDefinition` (ProcessType=RoutingFlow) | `300` | **required** |
+| **Agentforce Service Agent (ASA)** | `BotDefinition` (Type=ExternalCopilot) | `0Xx` | **required** |
+| **Digital Worker** | `AgenticCtxtDecorDefinition` | `1iE` | **required** |
+| **User** | `User` (with a RoutingConfiguration) | `005` | must be **null** |
+
+Provisioning behavior:
+- **Queue** — pick an existing `MessagingSession`-capable Queue, or create a new Queue + QueueRoutingConfig via Metadata API.
+- **Flow / ASA / Digital Worker / User** — locate an existing eligible target and PATCH it. These skills do **not** create Flows, bots, digital workers, or users — if none eligible exist, the skill reports the precondition and points the user at Setup.
+
+## Reference File Index
+
+| Reference file | Load when |
+| --- | --- |
+| `references/queue-creation.md` | The user picked "create a new queue" on the Queue routing path — full Metadata API scaffold → deploy → ID lookup → optional member add. |
+| `references/target-locate.md` | You need the per-domain SOQL to locate and validate an eligible target (Queue, Flow, ASA, Digital Worker, User) and the FallbackQueue requirement matrix. |
+| `references/asa-routing.md` | The user picked ASA (Agentforce Service Agent) routing — precondition check, enumerating live ASAs, and selection. |
+| `references/gotchas.md` | Troubleshooting an unexpected result, or before modifying this skill — the known gotchas. |
+| `references/worked-examples.md` | You want a reference run of the reuse-existing-queue, create-new-queue, Flow, or ASA paths. |
+
+## When NOT to use this skill
+
+- **The channel already has `SessionHandlerId` or `FallbackQueueId` set.** This skill no-ops and tells you — nothing to do. Proceed to activation.
+- **The channel doesn't exist yet.** Run the insertion skill first; this skill expects a real `MessagingChannel.Id`.
+- **You want to replace existing routing.** Safer to clear `SessionHandlerId` manually in the UI, then re-run this skill. The no-op check is a guardrail, not a limitation worth bypassing automatically.
+
+## Inputs (from caller)
+
+- `{CHANNEL_ID}` — a 15- or 18-char `MessagingChannel.Id` (prefix `0Mj`). The channel must already exist.
+- `{ORG_ALIAS}` — optional; the `sf` CLI target-org alias. Default: whatever `sf config get target-org` returns. All SOQL, PATCH, and Metadata deploys run against this org.
+
+## Output (to caller)
+
+One of:
+
+**Success — no change needed:**
+```json
+{"ok": true, "noop": true, "routingType": "queue|flow|asa|digital_worker|user", "sessionHandlerId": "00G...|300...|0Xx...|1iE...|005...", "fallbackQueueId": "00G...|null", "targetName": "...", "message": "Routing already configured"}
+```
+
+**Success — Queue routing configured:**
+```json
+{"ok": true, "routingType": "queue", "sessionHandlerId": "00G...", "fallbackQueueId": null, "queueName": "...", "queueDeveloperName": "...", "created": true|false}
+```
+
+**Success — Flow routing configured:**
+```json
+{"ok": true, "routingType": "flow", "sessionHandlerId": "300...", "fallbackQueueId": "00G...", "flowName": "...", "flowDeveloperName": "...", "created": false}
+```
+
+**Success — ASA routing configured:**
+```json
+{"ok": true, "routingType": "asa", "sessionHandlerId": "0Xx...", "fallbackQueueId": "00G...", "asaName": "...", "asaDeveloperName": "...", "botUserId": "005...", "botVersionId": "0X9...", "created": false}
+```
+
+**Success — Digital Worker routing configured:**
+```json
+{"ok": true, "routingType": "digital_worker", "sessionHandlerId": "1iE...", "fallbackQueueId": "00G...", "workerName": "...", "created": false}
+```
+
+**Success — User routing configured:**
+```json
+{"ok": true, "routingType": "user", "sessionHandlerId": "005...", "fallbackQueueId": null, "userName": "...", "created": false}
+```
+
+**Precondition not met:**
+```json
+{"ok": false, "kind": "no-eligible-target", "routingType": "flow|asa|digital_worker|user", "hint": "no eligible <target> found on this org — <how to create one in Setup>, then re-run this skill"}
+{"ok": false, "kind": "no-fallback-queue", "hint": "Flow/ASA/Digital Worker routing requires a FallbackQueue but no MessagingSession-capable queue exists — create one (Queue routing path) first"}
+{"ok": false, "kind": "asa-not-supported", "hint": "this org doesn't have BotDefinition (Agentforce not licensed); use Queue routing instead"}
+{"ok": false, "kind": "standard-channel", "hint": "this is a Standard (SCRT1) channel — only Flow routing is supported; these skills only create Enhanced channels, so this is unexpected"}
+```
+
+**Failure:**
+```json
+{"ok": false, "kind": "metadata-deploy-failed", "message": "..."}
+{"ok": false, "kind": "patch-failed", "message": "..."}
+{"ok": false, "kind": "verify-failed", "hint": "PATCH returned success but re-read shows SessionHandlerId still null — permission or trigger issue"}
+```
+
+The PATCH failure `message` often carries the server-side validation error verbatim (from `MessagingChannelFunctionsHelper.validateSessionHandler`). Surface it — it tells the user exactly which linking rule failed. Common ones: `MissingFallbackQueueForFlowRouting` / `...ForAsaRouting` / `...ForDigitalWorkerRouting` (FallbackQueue required but null), `UnsupportedFallbackQueue` (FallbackQueue set on a Queue/User path where it must be null), `InvalidSessionHandlerFlowType` (Flow isn't ProcessType=RoutingFlow, **or** the channel is Standard/SCRT1), `NoRoutingConfigDefined` (User has no RoutingConfiguration).
+
+---
+
+## Stage 1: Read current routing state
+
+Query the channel. If it already has `SessionHandlerId` OR `FallbackQueueId`, no-op. Otherwise, continue.
+
+```bash
+sf data query --target-org '{ORG_ALIAS}' \
+  --query "SELECT Id, DeveloperName, SessionHandlerId, FallbackQueueId FROM MessagingChannel WHERE Id = '{CHANNEL_ID}'" \
+  --json > /tmp/ccr-channel.json
+```
+
+Parse with `node -e` or `jq`. If the record is missing — halt with `Error: Channel {CHANNEL_ID} not found — check the id, or run the insertion skill first.`
+
+If `SessionHandlerId` is non-null, branch on the Id prefix to figure out what the existing routing target is, then no-op with the right envelope. The prefix maps 1:1 to the SessionHandler domain (verified against `MessagingChannel.entity.xml`):
+
+| Prefix | Domain / Target | Lookup query | routingType |
+| --- | --- | --- | --- |
+| `00G` | `Group` (Type=Queue) | `SELECT Id, Name, DeveloperName FROM Group WHERE Id='<sh>' AND Type='Queue'` | `queue` |
+| `300` | `FlowDefinition` | `SELECT DurableId, Label, ApiName FROM FlowDefinitionView WHERE DurableId='<sh>'` | `flow` |
+| `0Xx` | `BotDefinition` (ASA) | `SELECT Id, DeveloperName, MasterLabel, AgentType FROM BotDefinition WHERE Id='<sh>'` | `asa` |
+| `1iE` | `AgenticCtxtDecorDefinition` (Digital Worker) | `SELECT Id, DeveloperName, MasterLabel FROM AgenticCtxtDecorDefinition WHERE Id='<sh>'` | `digital_worker` |
+| `005` | `User` | `SELECT Id, Name FROM User WHERE Id='<sh>'` | `user` |
+
+```bash
+SESSION_HANDLER_ID="$(node -e 'console.log(JSON.parse(require("fs").readFileSync("/tmp/ccr-channel.json","utf8")).result.records[0].SessionHandlerId)')"
+PREFIX="${SESSION_HANDLER_ID:0:3}"
+case "$PREFIX" in
+  00G) sf data query --target-org '{ORG_ALIAS}' --query "SELECT Id, Name, DeveloperName FROM Group WHERE Id = '$SESSION_HANDLER_ID' AND Type = 'Queue'" --json > /tmp/ccr-noop-target.json ;;
+  300) sf data query --target-org '{ORG_ALIAS}' --query "SELECT DurableId, Label, ApiName FROM FlowDefinitionView WHERE DurableId = '$SESSION_HANDLER_ID'" --json > /tmp/ccr-noop-target.json ;;
+  0Xx) sf data query --target-org '{ORG_ALIAS}' --query "SELECT Id, DeveloperName, MasterLabel, AgentType FROM BotDefinition WHERE Id = '$SESSION_HANDLER_ID'" --json > /tmp/ccr-noop-target.json ;;
+  1iE) sf data query --target-org '{ORG_ALIAS}' --query "SELECT Id, DeveloperName, MasterLabel FROM AgenticCtxtDecorDefinition WHERE Id = '$SESSION_HANDLER_ID'" --json > /tmp/ccr-noop-target.json ;;
+  005) sf data query --target-org '{ORG_ALIAS}' --query "SELECT Id, Name FROM User WHERE Id = '$SESSION_HANDLER_ID'" --json > /tmp/ccr-noop-target.json ;;
+  *)   echo "{\"records\":[{\"Id\":\"$SESSION_HANDLER_ID\"}]}" > /tmp/ccr-noop-target.json ;;
+esac
+```
+
+Report the success-noop envelope (include the existing `FallbackQueueId` from the Stage 1 read) and return.
+
+If `FallbackQueueId` is non-null but `SessionHandlerId` is null — still no-op. That's a partially-configured Flow/ASA state; don't touch it, but flag it in the envelope `message` (`"FallbackQueue set but SessionHandler null — incomplete routing, review in Setup"`) since activation will still fail readiness without a SessionHandler.
+
+---
+
+## Stage 2: Confirm the channel is Enhanced, then choose routing type
+
+First confirm `PlatformType`. The Stage 1 read didn't include it — add it, or re-query:
+
+```bash
+sf data query --target-org '{ORG_ALIAS}' \
+  --query "SELECT Id, PlatformType FROM MessagingChannel WHERE Id = '{CHANNEL_ID}'" --json > /tmp/ccr-platform.json
+```
+
+If `PlatformType != 'Enhanced'` (i.e. Standard/SCRT1), only Flow routing is writable. These skills only create Enhanced channels, so a Standard channel here is unexpected — emit `{ok:false, kind:"standard-channel", ...}` and stop rather than guessing.
+
+Then ask the user (via a prompt — do NOT auto-pick):
+
+```text
+The MessagingChannel '{developerName}' ({CHANNEL_ID}) has no routing configured.
+Which routing type do you want?
+
+  1) queue          — Omni-Channel queue routing
+  2) flow           — Omni-Flow (RoutingFlow) + fallback queue
+  3) asa            — Agentforce Service Agent (requires Agentforce license) + fallback queue
+  4) digital_worker — Digital Worker (Agentic) + fallback queue
+  5) user           — Direct to a specific user (requires a RoutingConfiguration on the user)
+
+Pick [1-5]:
+```
+
+Branch on the user's pick. For every non-queue path, **load `references/target-locate.md`** — it holds the per-domain locate SOQL, eligibility filters, FallbackQueue rules, and exact PATCH shape:
+
+- **1 (queue)** — continue to Stage 3-Queue below.
+- **2 (flow)** — locate an eligible `FlowDefinition` (ProcessType=RoutingFlow, active version) + a FallbackQueue, then Stage 5.
+- **3 (asa)** — continue to Stage 3-ASA; ASA requires a FallbackQueue too.
+- **4 (digital_worker)** — locate an eligible `AgenticCtxtDecorDefinition` + a FallbackQueue, then Stage 5.
+- **5 (user)** — locate a `User` that has a RoutingConfiguration, then Stage 5.
+
+If a path finds no eligible target, emit `{ok:false, kind:"no-eligible-target", routingType, hint}` (see `references/target-locate.md` for the per-domain Setup pointer) and return — do not fabricate an id.
+
+---
+
+## Stage 3-Queue: Pick an existing queue, or create a new one
+
+*(This stage runs only on the Queue path. ASA path: see Stage 3-ASA below.)*
+
+Enumerate eligible queues. The UI's routing dropdown (`MessagingRoutingMethodDataProviderController.getOmniQueues`) lists Groups where `QueueRoutingConfigId != null` — i.e. Omni-Channel-enabled queues. For a MessagingChannel we additionally want the queue to accept `MessagingSession`. Query the intersection: enumerate MessagingSession-capable queues, then keep only those with a QueueRoutingConfig.
+
+```bash
+# MessagingSession-capable queues that are also Omni-enabled (QueueRoutingConfigId != null)
+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-queues.json
+```
+
+Each row's `Id` is the `00G` `Group.Id` — that is what gets written to `SessionHandlerId`. (If the semi-join subquery errors on an org, fall back to two queries: list `QueueSobject WHERE SobjectType='MessagingSession'`, then filter to those whose `Group.QueueRoutingConfigId != null`.)
+
+Present the user with a numbered list plus a final "create new" option:
+
+```text
+Omni-enabled MessagingSession queues on {ORG_ALIAS}:
+
+  1) Messaging Queue (Messaging_Queue) — 00GSG0000000LSf2AM
+  2) MyQueue (MyQueue) — 00GSG000000144n2AA
+  ...
+  N) Create a new queue
+
+Pick [1-N]:
+```
+
+- **If the user picks an existing queue**: record its `Id` as `{QUEUE_ID}` (this is the `Group.Id`). Skip to Stage 5.
+- **If the user picks "create new"**: go to Stage 4.
+
+If the list is empty AND the user picks (1) "Create a new queue" implicitly, skip directly to Stage 4.
+
+---
+
+## Stage 3-Queue, continued: Create a new Queue via Metadata API
+
+*(Continuation of the Queue path. Skip if the user picked an existing queue above.)*
+
+We deploy a Queue + QueueRoutingConfig pair using a minimal scratch sfdx project (the `help-agent-accelerator` pattern), then look up the new Queue's Id and optionally add the current user as a member.
+
+**To create a new Queue via the Metadata API (sfdx project scaffold → deploy → ID lookup → optional member add), load `references/queue-creation.md` and follow it — it is the complete guide for this flow.**
+
+After that stage, jump to Stage 5 (PATCH).
+
+---
+
+## Stage 3-ASA: Pick an existing ASA
+
+*(This stage runs only on the ASA path. Queue path: skip to Stage 5.)*
+
+ASA routing points `SessionHandlerId` at an existing, live Agentforce Service Agent (`BotDefinition`). This skill never creates a new ASA — it verifies the org supports one (Agentforce licensed), enumerates the live/routable ones, and lets the user pick.
+
+**For ASA precondition checks, enumeration, and selection, load `references/asa-routing.md`.** After selection, continue to Stage 5 (PATCH).
+
+---
+
+## Stage 5: PATCH `MessagingChannel.SessionHandlerId` (+ `FallbackQueueId`)
+
+By this point we have a **routing target id** in `{TARGET_ID}` and know its `{ROUTING_TYPE}`:
+
+| routingType | `{TARGET_ID}` | FallbackQueue write |
+| --- | --- | --- |
+| `queue` | `00G` `Group.Id` | none (must stay null) |
+| `flow` | `300` `FlowDefinition` id | set `FallbackQueueId={FALLBACK_QUEUE_ID}` |
+| `asa` | `0Xx` `BotDefinition.Id` | set `FallbackQueueId={FALLBACK_QUEUE_ID}` |
+| `digital_worker` | `1iE` `AgenticCtxtDecorDefinition.Id` | set `FallbackQueueId={FALLBACK_QUEUE_ID}` |
+| `user` | `005` `User.Id` | none (must stay null) |
+
+`SessionHandler` is a polymorphic FK spanning `[Group, FlowDefinition, User, BotDefinition, AgenticCtxtDecorDefinition]` (per `MessagingChannel.entity.xml`; the BotDefinition/AgenticCtxtDecorDefinition targets only materialize on Agentforce-licensed orgs). The standard REST sObject PATCH accepts whichever Id type fits. The **FallbackQueue rule is enforced server-side** (`validateSessionHandler`): Flow/ASA/Digital Worker reject a null FallbackQueue; Queue/User reject a non-null one.
+
+For the FallbackQueue paths, write both fields in one PATCH so the record never passes through an invalid intermediate state:
+
+```bash
+# queue / user — SessionHandler only
+sf data update record --target-org '{ORG_ALIAS}' --sobject MessagingChannel \
+  --record-id '{CHANNEL_ID}' \
+  --values 'SessionHandlerId={TARGET_ID}' --json > /tmp/ccr-patch.json
+
+# flow / asa / digital_worker — SessionHandler + FallbackQueue together
+sf data update record --target-org '{ORG_ALIAS}' --sobject MessagingChannel \
+  --record-id '{CHANNEL_ID}' \
+  --values 'SessionHandlerId={TARGET_ID} FallbackQueueId={FALLBACK_QUEUE_ID}' --json > /tmp/ccr-patch.json
+```
+
+If `status !== 0`: emit `{ok:false, kind:"patch-failed", message: ...}` and return. Surface the server message verbatim — it names the exact linking rule that failed (see the failure-envelope note under "Output (to caller)").
+
+---
+
+## Stage 6: Verify
+
+Re-read the channel:
+
+```bash
+sf data query --target-org '{ORG_ALIAS}' \
+  --query "SELECT Id, SessionHandlerId, FallbackQueueId FROM MessagingChannel WHERE Id = '{CHANNEL_ID}'" \
+  --json
+```
+
+If the freshly-read `SessionHandlerId` doesn't equal `{TARGET_ID}` — or (for flow/asa/digital_worker) `FallbackQueueId` doesn't equal `{FALLBACK_QUEUE_ID}`:
+```json
+{"ok": false, "kind": "verify-failed", "hint": "PATCH returned success but re-read shows SessionHandlerId/FallbackQueueId not persisted — check user permissions or field-level security on MessagingChannel"}
+```
+
+Otherwise, emit the path-appropriate success envelope (see "Output (to caller)" at the top of this file — one shape per routingType, each carrying `fallbackQueueId`).
+
+---
+
+## Stage 7: Report to caller
+
+Report the JSON envelope. If this skill is the leaf (user invoked it directly), render:
+
+**Queue path:**
+- `Success — Routing configured — channel {CHANNEL_ID} now routes to Queue '{QUEUE_LABEL}' ({QUEUE_ID}).{'' if created else ' (reused existing queue)'}`
+- `Info: Routing already configured — Queue '{name}' ({QUEUE_ID}). No changes.` (no-op path)
+
+**Flow path:**
+- `Success — Routing configured — channel {CHANNEL_ID} now routes to Omni-Flow '{FLOW_LABEL}' ({TARGET_ID}), fallback Queue {FALLBACK_QUEUE_ID}.`
+
+**ASA path:**
+- `Success — Routing configured — channel {CHANNEL_ID} now routes to Agentforce Service Agent '{ASA_LABEL}' ({ASA_ID}), fallback Queue {FALLBACK_QUEUE_ID}. Bot user: {BOT_USER_ID}. Active version: {BOT_VERSION_ID}.`
+- `Info: Routing already configured — ASA '{MasterLabel}' ({ASA_ID}). No changes.` (no-op path)
+
+**Digital Worker path:**
+- `Success — Routing configured — channel {CHANNEL_ID} now routes to Digital Worker '{WORKER_LABEL}' ({TARGET_ID}), fallback Queue {FALLBACK_QUEUE_ID}.`
+
+**User path:**
+- `Success — Routing configured — channel {CHANNEL_ID} now routes directly to User '{USER_NAME}' ({TARGET_ID}).`
+
+**Failure / precondition:**
+- `Warning: No eligible {routingType} target found. {per-domain Setup pointer from references/target-locate.md}. Then re-run this skill.` (no-eligible-target)
+- `Warning: {routingType} routing needs a fallback queue but none exists. Create a MessagingSession queue first (queue path), then re-run.` (no-fallback-queue)
+- `Warning: This org doesn't have Agentforce licensed (no BotDefinition entity). Use Queue routing instead.` (asa-not-supported)
+- `Warning: This is a Standard (SCRT1) channel — only Flow routing is supported. These skills only create Enhanced channels, so this is unexpected; check the channel.` (standard-channel)
+- `Error: {kind}: {message}` (other failures — the message names the server-side validation rule that failed)
+
+---
+
+## Worked examples
+
+For reference runs of both the reuse-an-existing-queue fast path (validated on test1) and the create-a-new-queue-via-Metadata-API path, see `references/worked-examples.md`.
+
+---
+
+## Gotchas
+
+Known gotchas — `Group.Type` filtering, DeveloperName uniqueness, QueueRoutingConfig naming, empty-queue caveats, Metadata-API-only queue creation, the per-domain **FallbackQueue requirement matrix**, the server-side `nullQueueId` / readiness enforcement point, the **Standard-vs-Enhanced** SessionHandler write restriction, and `SessionHandler` polymorphism across org shapes.
+
+**When troubleshooting an unexpected result, or before modifying this skill, load `references/gotchas.md` and follow it — it is the complete list.**

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

@@ -0,0 +1,90 @@
+---
+name: service-de-channel-routing-configure-asa-routing
+description: "Load when the user picked Agentforce Service Agent (ASA) routing on service-de-channel-routing-configure. Covers the BotDefinition precondition check, enumerating live ASAs (with the routable-vs-not-yet-live filter and the INVALID_TYPE subquery fallback), and prompting the user to pick one. DO NOT load this for the Omni-Channel Queue routing path — see references/queue-creation.md for that."
+metadata:
+  version: "1.0"
+  related-skills: service-de-channel-routing-configure
+---
+
+# Stage 3-ASA: Pick an existing ASA
+
+*(This stage runs only on the ASA path. Queue path: skip to Stage 5.)*
+
+## Stage 3-ASA.0: Precondition check
+
+Verify the org has Agentforce licensed (`BotDefinition` sObject exists):
+
+```bash
+sf sobject describe --target-org '{ORG_ALIAS}' --sobject BotDefinition 2>&1 | grep -q "does not exist" \
+  && echo "MISSING" \
+  || echo "PRESENT"
+```
+
+If `MISSING` — emit and return:
+
+```json
+{"ok": false, "kind": "asa-not-supported", "hint": "this org doesn't have BotDefinition (Agentforce not licensed); use Queue routing instead"}
+```
+
+## Stage 3-ASA.1: Enumerate live ASAs
+
+```bash
+sf data query --target-org '{ORG_ALIAS}' \
+  --query "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" \
+  --json > /tmp/ccr-asas.json
+```
+
+Parse with `node -e`. For each row, extract:
+- `Id` — `BotDefinition.Id` (used as `SessionHandlerId`)
+- `MasterLabel` / `DeveloperName` — for display
+- `BotUserId` — bot user already linked? (null = not linked, ASA can't actually serve sessions yet)
+- `BotVersions[0]` — has an Active version? (null = ASA exists but isn't live)
+
+Filter: an ASA is **routable** only if `BotUserId != null` AND `BotVersions[0].Status == 'Active'`. ASAs failing either check are listed but flagged as "not yet live — selecting will fail at activation time."
+
+If the channel-relationship subquery returns `INVALID_TYPE` (the `BotVersions` child relationship isn't named on some orgs — same family of issue as the MessagingChannelUsage subquery gotcha), fall back to two queries:
+
+```bash
+sf data query --target-org '{ORG_ALIAS}' \
+  --query "SELECT Id, DeveloperName, MasterLabel, BotUserId FROM BotDefinition WHERE Type='ExternalCopilot' AND AgentType='EinsteinServiceAgent' ORDER BY MasterLabel" \
+  --json > /tmp/ccr-asas.json
+# then for each id, query BotVersion separately
+sf data query --target-org '{ORG_ALIAS}' \
+  --query "SELECT Id, BotDefinitionId, Status FROM BotVersion WHERE BotDefinitionId IN (<comma-sep ids>) AND Status='Active'" \
+  --json > /tmp/ccr-asas-versions.json
+```
+
+If no live ASAs found (all rows have `BotUserId=null` or no Active BotVersion), emit:
+
+```json
+{"ok": false, "kind": "no-live-asa", "hint": "no live ASAs found on this org — create one in Setup → Agentforce first, then re-run this skill"}
+```
+
+## Stage 3-ASA.2: Prompt the user
+
+Present a numbered list of live ASAs only:
+
+```text
+Existing live Agentforce Service Agents on {ORG_ALIAS}:
+
+  1) Agentforce Service Agent KAFile (Agentforce_Service_Agent_KAFile) — 0XxRZ0000002ZWL0A2
+  2) MON ASA Apex (MON_ASA_Apex) — 0XxRZ0000003APR0A2
+
+Pick [1-N]:
+```
+
+Record `{ASA_ID}` = `BotDefinition.Id`, `{ASA_LABEL}`, `{ASA_DEV_NAME}`, `{BOT_USER_ID}`, `{BOT_VERSION_ID}`.
+
+## Stage 3-ASA.3: Resolve a FallbackQueue (required)
+
+ASA routing **requires a FallbackQueue** — `validateSessionHandler` rejects a null FallbackQueue on the `0Xx` SessionHandler path with `MissingFallbackQueueForAsaRouting`. Enumerate eligible queues (Omni-enabled, MessagingSession-capable) and let the user pick:
+
+```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
+```
+
+Record `{FALLBACK_QUEUE_ID}` = the chosen `00G` `Group.Id`. If 0 rows, emit `{ok:false, kind:"no-fallback-queue", hint:"ASA routing needs a fallback queue but no MessagingSession-capable queue exists — create one (queue path) first"}` and return.
+
+Continue to Stage 5 (PATCH), which writes `SessionHandlerId={ASA_ID} FallbackQueueId={FALLBACK_QUEUE_ID}` in one call.

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

@@ -0,0 +1,27 @@
+---
+name: service-de-channel-routing-configure-gotchas
+description: "Load when debugging an unexpected result from service-de-channel-routing-configure, or before implementing changes to it. Covers the known gotchas: Group.Type filtering, DeveloperName uniqueness, QueueRoutingConfig naming, empty-queue caveats, Metadata-API-only queue creation, the per-domain FallbackQueue requirement matrix, the server-side nullQueueId enforcement point, the Standard-vs-Enhanced SessionHandler write restriction, and SessionHandler polymorphism differences across org shapes. DO NOT load this during a normal first-time routing configuration run — only when troubleshooting or modifying the skill."
+metadata:
+  version: "1.0"
+  related-skills: service-de-channel-routing-configure
+---
+
+# Gotchas
+
+1. **The `sf data query` `Group.Type='Queue'` filter matters.** `Group` also holds roles/role-and-subordinates/public-groups etc. Always filter on `Type='Queue'` when reading for a queue. (Entity shape confirmed on test1: 2 MessagingSession-capable queues present, both with `Type='Queue'`, both with matching `QueueSobject.SobjectType='MessagingSession'`.)
+
+2. **`DeveloperName` must be unique across all Queues.** A deploy with a duplicate DevName is rejected with `duplicate value found: DeveloperName duplicates value on record with id: <existingId>`. Either detect that up front (query Group first) or let the deploy fail and re-prompt.
+
+3. **`QueueRoutingConfig.DeveloperName` must also be globally unique.** The skill names it `{QUEUE_DEV_NAME}_Routing` to stay unique per queue. Keep this pattern — don't reuse a single routing config across queues unless the user explicitly asks.
+
+4. **A queue without members still PATCHes fine, and `activateChannelUsage` still succeeds.** But the channel won't actually route messages anywhere until someone joins the queue with an Omni Presence. The skill's "add self" option papers over this for demo/test orgs; for prod, the caller is responsible for populating the queue separately.
+
+5. **Queue + QueueRoutingConfig via Metadata API, NOT via `sf data create record`.** The REST sObject insert for `Group(Type=Queue)` works for the Group row itself but does NOT create the routing config, and some related `QueueMember`/Omni-Presence linkage is done server-side only by the Metadata API deploy. Stick with the metadata path — that's how `help-agent-accelerator` does it, and it's what we validated against test1.
+
+6. **`FallbackQueueId` is required for some SessionHandler domains and forbidden for others — it is NOT interchangeable.** The rule (from `MessagingChannelFunctionsHelper.validateSessionHandler`, cross-verified live): Flow (`300`), ASA (`0Xx`), and Digital Worker (`1iE`) **require** a non-null FallbackQueue; Queue (`00G`) and User (`005`) **require it null** (a non-null value is rejected with `UnsupportedFallbackQueue`). Setting a Flow SessionHandler with a null FallbackQueue is rejected with *"A Fallback Queue must be specified when selecting a Flow routing method."* (verified live on sdb6c 2026-08-12). See `references/target-locate.md` for the full matrix. This is why the FallbackQueue-required paths write both fields in a single PATCH.
+
+7. **The `channelRouteTrafficModal.js` enforcement is UI-side only.** Server-side, activation readiness (`MessagingChannelReadinessChecker.isRoutingConfiguredForChannel`) requires a **SessionHandler-based** routing method — Queue-as-SessionHandler (`00G`), User (`005`), Flow (`300`+FallbackQueue), or ASA (`0Xx`+FallbackQueue). It inspects `SessionHandler`, **not** `TargetQueue`. A legacy Standard/SCRT1 channel could route via `TargetQueueId`, but that does not satisfy this Enhanced-channel readiness check — and these skills only create Enhanced channels, so always route via `SessionHandler`. Neither-set raises `LiveMessageSetupException` (`nullQueueId`) at activation.
+
+8. **Standard (SCRT1) channels only accept a Flow as SessionHandler; Enhanced (SCRT2) channels accept all five domains.** `validateSessionHandler` (the `PlatformType==STANDARD` branch) rejects any non-Flow SessionHandler on a Standard channel with *"Only flows of type Omni-Channel are supported for a Messaging Channel"* — verified live: a `00G` Queue and a `0Xx` ASA both failed with that exact message on a Standard channel, and both succeeded on an Enhanced one. These skills create only Enhanced channels, so Stage 2 confirms `PlatformType=Enhanced` and bails with `kind:"standard-channel"` if it ever sees otherwise.
+
+9. **`MessagingChannel.SessionHandler` polymorphism is org-shape-dependent.** The full domain is `[Group, FlowDefinition, User, BotDefinition, AgenticCtxtDecorDefinition]`, but `BotDefinition` (ASA) only materializes on Agentforce-licensed orgs and `AgenticCtxtDecorDefinition` (Digital Worker) only when `orgHasOmniChannelScrt2DigitalWorkerRouting` is enabled (not present on sdb6c). The ASA precondition check (Stage 3-ASA.0) and the Digital Worker `INVALID_TYPE` guard (`references/target-locate.md`) catch the missing-domain cases before a PATCH is attempted. Note the SOQL field surface is thinner than the internal representation: the Data-API `BotDefinition` sObject exposes only `Type`/`AgentType`/`AgentTemplate`, so the active-version check goes through the `BotVersions` child relationship, not an `ActiveVersionId` column.

package/skills/service-de-channel-routing-configure/references/queue-creation.md

@@ -0,0 +1,123 @@
+---
+name: service-de-channel-routing-configure-queue-creation
+description: "Load when the user picked 'create a new queue' on the Queue routing path of service-de-channel-routing-configure. Covers the full Metadata API creation flow: collecting queue inputs, scaffolding a minimal sfdx project with Queue + QueueRoutingConfig metadata, deploying it, looking up the new Queue's Id, and optionally adding the current user as a member. DO NOT load this when the user picked an existing queue from the enumerated list — that path skips straight to Stage 5 (PATCH)."
+metadata:
+  version: "1.0"
+  related-skills: service-de-channel-routing-configure
+---
+
+# Stage 3-Queue, continued: Create a new Queue via Metadata API
+
+*(Continuation of the Queue path. Skip if the user picked an existing queue above.)*
+
+We deploy a Queue + QueueRoutingConfig pair using a minimal scratch sfdx project. This mirrors the `help-agent-accelerator` pattern (`force-app-static/main/default/queues/Help_Support_Queue.queue-meta.xml`), which is the battle-tested route for MessagingSession queues.
+
+## Stage 3-Queue.1: Collect inputs
+
+Ask the user:
+
+```text
+New queue details:
+  Display name (e.g. "WhatsApp Support Queue"):
+  API name (DeveloperName, letters/digits/underscores, e.g. "WhatsApp_Support_Queue")
+    [press enter to derive from display name]:
+  Routing model [MostAvailable / LeastActive / HighestPriority] (default: MostAvailable):
+  Add the current user as a queue member? [Y/n]:
+```
+
+Derive `DeveloperName` by slugifying the display name if the user leaves it blank:
+- Replace any non-alphanumeric run with `_`
+- Collapse repeats: `__` → `_`
+- Trim leading/trailing `_`
+- If the result starts with a digit, prepend `X_`
+
+Validate `DeveloperName`: must match `^[A-Za-z][A-Za-z0-9_]*$`, length ≤ 40. If invalid, re-prompt.
+
+Record:
+- `{QUEUE_LABEL}` — display name
+- `{QUEUE_DEV_NAME}` — DeveloperName
+- `{ROUTING_MODEL}` — `MostAvailable` | `LeastActive` | `HighestPriority` (maps to `QueueRoutingConfig.routingModel`)
+- `{ADD_SELF}` — boolean
+
+## Stage 3-Queue.2: Write the sfdx project
+
+```bash
+TMP_DIR=/tmp/ccr-metadata-$(date +%s)
+mkdir -p "$TMP_DIR/force-app/main/default/queues"
+mkdir -p "$TMP_DIR/force-app/main/default/queueRoutingConfigs"
+
+# sfdx-project.json
+cat > "$TMP_DIR/sfdx-project.json" <<'JSON_EOF'
+{
+  "packageDirectories": [{"path": "force-app", "default": true}],
+  "namespace": "",
+  "sourceApiVersion": "66.0"
+}
+JSON_EOF
+
+# QueueRoutingConfig — named <DevName>_Routing so one config per queue
+cat > "$TMP_DIR/force-app/main/default/queueRoutingConfigs/{QUEUE_DEV_NAME}_Routing.queueRoutingConfig-meta.xml" <<'XML_EOF'
+<?xml version="1.0" encoding="UTF-8"?>
+<QueueRoutingConfig xmlns="http://soap.sforce.com/2006/04/metadata">
+    <capacityType>INHERITED</capacityType>
+    <capacityWeight>1.0</capacityWeight>
+    <isAttributeBased>false</isAttributeBased>
+    <label>{QUEUE_LABEL} Routing</label>
+    <routingModel>{ROUTING_MODEL}</routingModel>
+    <routingPriority>1</routingPriority>
+</QueueRoutingConfig>
+XML_EOF
+
+# Queue
+cat > "$TMP_DIR/force-app/main/default/queues/{QUEUE_DEV_NAME}.queue-meta.xml" <<'XML_EOF'
+<?xml version="1.0" encoding="UTF-8"?>
+<Queue xmlns="http://soap.sforce.com/2006/04/metadata">
+    <doesSendEmailToMembers>false</doesSendEmailToMembers>
+    <name>{QUEUE_LABEL}</name>
+    <queueRoutingConfig>{QUEUE_DEV_NAME}_Routing</queueRoutingConfig>
+    <queueSobject>
+        <sobjectType>MessagingSession</sobjectType>
+    </queueSobject>
+</Queue>
+XML_EOF
+```
+
+**Substitute** `{QUEUE_LABEL}`, `{QUEUE_DEV_NAME}`, `{ROUTING_MODEL}` into both files. Use `sed` or a Node script — watch the XML escape if the label contains `&`, `<`, `>`, `"`, `'`.
+
+## Stage 3-Queue.3: Deploy
+
+```bash
+(cd "$TMP_DIR" && sf project deploy start --target-org '{ORG_ALIAS}' --wait 5 --json) > /tmp/ccr-deploy.json 2>&1
+```
+
+Parse `/tmp/ccr-deploy.json`:
+- `result.status === "Succeeded"` → continue
+- anything else → emit `{ok:false, kind:"metadata-deploy-failed", message:<result.details.componentFailures[0].problem || raw tail>}` and return
+
+## Stage 3-Queue.4: Look up the new Queue's ID
+
+The deploy returns component results but not the Group sObject id. Query it:
+
+```bash
+sf data query --target-org '{ORG_ALIAS}' \
+  --query "SELECT Id FROM Group WHERE Type='Queue' AND DeveloperName='{QUEUE_DEV_NAME}' LIMIT 1" \
+  --json
+```
+
+Record the Id as `{QUEUE_ID}`. If the query returns 0 records, something is wrong (deploy reported success but row not visible) — halt with `Error: Deploy reported success but Queue {QUEUE_DEV_NAME} not findable — check user permissions for viewing Group.`
+
+## Stage 3-Queue.5: Optionally add current user as member
+
+If `{ADD_SELF}` is true:
+
+```bash
+# Get the current user id
+USER_ID=$(sf org display --target-org '{ORG_ALIAS}' --json | node -e 'console.log(JSON.parse(require("fs").readFileSync(0,"utf8")).result.id)')
+# Insert GroupMember
+sf data create record --target-org '{ORG_ALIAS}' --sobject GroupMember \
+  --values "GroupId={QUEUE_ID} UserOrGroupId=${USER_ID}" --json
+```
+
+A failure here (e.g. duplicate GroupMember) is not fatal — log it and continue.
+
+After this stage, jump to Stage 5 (PATCH).