@salesforce/afv-skills 1.40.0 → 1.41.0

package/skills/service-agentforce-channel-configure/references/live-traffic-gate.md

@@ -0,0 +1,86 @@
+# Live-traffic warning gate (Phase 2)
+
+Runs once, before any branch, whenever Phase 2 begins. Prevents an unattended re-route of live traffic on a channel that already has active inbound routing.
+
+## Detect existing routing
+
+- **Branch A (Enhanced Chat / Enhanced Messaging):** retrieve the MessagingChannel and inspect `SessionHandlerType`. If it is non-empty, routing is live.
+- **Branches B/C (Voice / Email-to-Case):** query `FlowDefinitionView WHERE ProcessType='RoutingFlow'` for any flow assigned to this service channel with a non-null `ActiveVersionId`.
+
+If the channel has no existing routing, skip this gate entirely and proceed directly to the branch.
+
+## Infer from the user's prompt before asking
+
+Before raising `AskUserQuestion`, re-read the user's original prompt. If it already resolves the timing choice unambiguously, honor it silently — do NOT ask.
+
+- **Defer intent already stated** — treat as if the user picked **"Set up, then wire manually"**. Set `DEFER_INBOUND_ROUTING=true` and proceed to the deferred path (below) without raising the question. Non-exhaustive trigger phrases: "do not cut over", "don't cut over", "do not cut live traffic over", "don't switch live traffic yet", "wire manually", "wire it manually when I'm ready", "review first", "let me review", "hold off on activating", "set up but don't activate", "prepare but don't route", "leave live traffic alone".
+- **Cutover intent already stated** — treat as if the user picked **"Re-route now"**. Leave `DEFER_INBOUND_ROUTING` unset and proceed with immediate re-routing without raising the question. Non-exhaustive trigger phrases: "go ahead and cut over now", "re-route immediately", "cut over now", "switch live traffic now", "activate immediately", "just do it now".
+
+Only fall through to `AskUserQuestion` when the prompt is silent or genuinely ambiguous about timing.
+
+## If existing routing detected and prompt is silent, ask
+
+```yaml
+AskUserQuestion:
+  question: "'{CHANNEL_MASTER_LABEL}' already has active inbound routing configured.
+             Deploying will re-route live traffic immediately — any in-progress
+             conversations or calls on this channel will be affected.
+             How would you like to proceed?"
+  header: "Live traffic"
+  options:
+    - label: "Re-route now"
+      description: "Deploy immediately. Live traffic will be affected."
+    - label: "Set up, then wire manually"
+      description: "Create the queue and RoutingFlow (Voice/Email) now, but skip activating
+                   inbound routing. Manual wiring instructions will be provided at the end."
+```
+
+### Safe default on ambiguous / no-selection response
+
+If `AskUserQuestion` returns without a clear selection — timeout, empty answer, unrecognized reply, or any headless-run auto-resolution — default to **"Set up, then wire manually"** (set `DEFER_INBOUND_ROUTING=true`). Never default to a live re-route: the deferred path is non-destructive and recoverable; an unintended cutover is not.
+
+## If the user chooses "Set up, then wire manually"
+
+Set `DEFER_INBOUND_ROUTING=true` and continue:
+
+- **Branch A:** create the queue normally. Skip the `sf project deploy start` for the MessagingChannel entirely.
+- **Branches B/C:** create the queue and write + deploy the RoutingFlow normally (the flow is safe to deploy — it only becomes live when assigned to the channel). Skip any step that assigns the flow as the active routing flow for the channel.
+
+After Phase 2 completes, if `DEFER_INBOUND_ROUTING=true`, print manual wiring instructions before the Phase 3 prompt.
+
+### Branch A — activate when ready
+
+`sessionHandlerAsa` is not accepted by the Metadata API at v67 — deploy `sessionHandlerType` + `sessionHandlerQueue` only, then bind the bot via a Data API PATCH. The bot must be Active before the PATCH ("Only active Agentforce Service Agents are supported" otherwise).
+
+```bash
+sf project retrieve start --metadata "MessagingChannel:{CHANNEL_DEVELOPER_NAME}" --target-org {ORG}
+# In the retrieved XML, set ONLY:
+#   <sessionHandlerType>AgentforceServiceAgent</sessionHandlerType>
+#   <sessionHandlerQueue>{QUEUE_DEVELOPER_NAME}</sessionHandlerQueue>
+# Do NOT add <sessionHandlerAsa> — the Metadata API silently rejects it at v67.
+sf project deploy start --metadata "MessagingChannel:{CHANNEL_DEVELOPER_NAME}" --target-org {ORG}
+
+# Resolve Ids, then bind the bot via Data API PATCH:
+CHAN_ID=$(sf data query -o {ORG} --json \
+  -q "SELECT Id FROM MessagingChannel WHERE DeveloperName='{CHANNEL_DEVELOPER_NAME}'" \
+  | python3 -c "import sys,json; print(json.load(sys.stdin)['result']['records'][0]['Id'])")
+BOT_ID=$(sf data query -o {ORG} --json \
+  -q "SELECT Id FROM BotDefinition WHERE DeveloperName='{AGENT_DEVELOPER_NAME}'" \
+  | python3 -c "import sys,json; print(json.load(sys.stdin)['result']['records'][0]['Id'])")
+QUEUE_ID=$(sf data query -o {ORG} --json \
+  -q "SELECT Id FROM Group WHERE Type='Queue' AND DeveloperName='{QUEUE_DEVELOPER_NAME}'" \
+  | python3 -c "import sys,json; print(json.load(sys.stdin)['result']['records'][0]['Id'])")
+
+sf api request rest --method PATCH -o {ORG} \
+  "/services/data/v67.0/sobjects/MessagingChannel/${CHAN_ID}" \
+  --body "{\"SessionHandlerId\":\"${BOT_ID}\",\"FallbackQueueId\":\"${QUEUE_ID}\"}"
+# Expected: HTTP 204
+
+# Verify — both must be non-null:
+sf data query -o {ORG} --json \
+  -q "SELECT SessionHandlerId, FallbackQueueId FROM MessagingChannel WHERE Id='${CHAN_ID}'"
+```
+
+### Branches B/C — activate when ready
+
+> The RoutingFlow `{FLOW_DEVELOPER_NAME}` is deployed and active. To assign it as the inbound routing flow, go to **Setup → Omni-Channel → Service Channels** and point the channel at this flow — or re-run this skill against the same channel; the existing flow will be detected and reused, and only the channel assignment step will run.

package/skills/service-agentforce-channel-configure/references/queue-resolution.md

@@ -0,0 +1,135 @@
+# Queue resolution
+
+Run this before any channel wiring. The fallback queue must exist and have the correct `QueueSobject` record for the channel type's SobjectType.
+
+## Step 1 — Query existing compatible queues
+
+Determine the SobjectType from the channel type (see `references/channel-types.md`), then query:
+
+```bash
+sf data query --target-org $ORG --json \
+  --query "SELECT Queue.Name, Queue.DeveloperName, Queue.Id
+           FROM QueueSobject
+           WHERE SobjectType='{SOBJECT_TYPE}'"
+```
+
+## Step 2 — Present to user via AskUserQuestion
+
+- **One or more found** → present each as an option: `{Queue.Name} ({Queue.DeveloperName})`, plus a final option *"Create a new queue"*. If the user picks an existing queue, capture its `DeveloperName` and `Id` and skip queue creation.
+- **Zero found** → inform the user no compatible queue exists; proceed directly to create one.
+
+## Step 3 — Create a new queue (if needed)
+
+**Naming:** `{ChannelTypeLabel} Queue` / DeveloperName `{Channel_Type_Label}_Queue`
+
+Examples:
+- Voice → `Voice Queue` / `Voice_Queue`
+- Enhanced Chat → `Enhanced Chat Queue` / `Enhanced_Chat_Queue`
+- Email → `Email Queue` / `Email_Queue`
+
+### 1. Create the Group record
+```bash
+QUEUE_ID=$(sf data create record --target-org $ORG \
+  --sobject Group \
+  --values "Type='Queue' Name='{QUEUE_NAME}' DeveloperName='{QUEUE_DEVELOPER_NAME}'" \
+  --json | python3 -c "import sys,json; print(json.load(sys.stdin)['result']['id'])")
+```
+
+### 2. Grant queue access to the correct SobjectType
+```bash
+sf data create record --target-org $ORG \
+  --sobject QueueSobject \
+  --values "QueueId='$QUEUE_ID' SobjectType='{SOBJECT_TYPE}'"
+```
+
+### 3. Add the running user as a queue member
+```bash
+ORG_USERNAME=$(sf org display --target-org $ORG --json \
+  | python3 -c "import sys,json; print(json.load(sys.stdin)['result']['username'])")
+RUNNING_USER_ID=$(sf data query --target-org $ORG --json \
+  --query "SELECT Id FROM User WHERE Username='$ORG_USERNAME'" \
+  | python3 -c "import sys,json; print(json.load(sys.stdin)['result']['records'][0]['Id'])")
+sf data create record --target-org $ORG \
+  --sobject GroupMember \
+  --values "GroupId='$QUEUE_ID' UserOrGroupId='$RUNNING_USER_ID'"
+```
+
+## Step 4 — Resolve or create a Routing Configuration
+
+The queue must have a `QueueRoutingConfig` so Omni-Channel knows how to handle capacity. Query first:
+
+```bash
+sf data query --target-org $ORG --json \
+  --query "SELECT Id, DeveloperName, CapacityPercentage, RoutingModel FROM QueueRoutingConfig WHERE QueueId='{QUEUE_ID}'"
+```
+
+- **Found** → use it as-is; skip creation.
+- **Not found** → create one using the capacity percentage for the channel type:
+
+| Channel type | `CapacityPercentage` |
+|---|---|
+| Enhanced Chat / Enhanced Messaging | `50` |
+| Voice | `100` |
+| Email-to-Case | `25` |
+
+All use `RoutingModel: LeastActive`.
+
+```bash
+sf data create record --target-org $ORG \
+  --sobject QueueRoutingConfig \
+  --values "Name='{QUEUE_NAME} Routing' DeveloperName='{QUEUE_DEVELOPER_NAME}_Routing' QueueId='{QUEUE_ID}' CapacityPercentage={CAPACITY_PERCENTAGE} RoutingModel='LeastActive' IsAttributeBased=false"
+```
+
+Verify the record was created:
+```bash
+sf data query --target-org $ORG --json \
+  --query "SELECT Id, CapacityPercentage FROM QueueRoutingConfig WHERE QueueId='{QUEUE_ID}'"
+```
+
+## Step 5 — Capture for use in Phase 2
+
+Store:
+- `QUEUE_DEVELOPER_NAME` — used in the MessagingChannel XML (Branch A) or RoutingFlow `queueId` lookup (Branches B/C)
+- `QUEUE_NAME` (the `Name` field, e.g. `Voice Queue`) — used as `queueLabel` in the RoutingFlow XML
+- `QUEUE_ID` (18-char record Id) — used as `queueId` in the RoutingFlow XML
+
+If an existing queue was chosen, query its Id if not already available:
+```bash
+QUEUE_ID=$(sf data query --target-org $ORG --json \
+  --query "SELECT Id FROM Group WHERE Type='Queue' AND DeveloperName='{QUEUE_DEVELOPER_NAME}'" \
+  | python3 -c "import sys,json; print(json.load(sys.stdin)['result']['records'][0]['Id'])")
+```
+
+---
+
+## Step 6 — Escalation queue resolution (Phase 3 only)
+
+Run this step when the user opts into outbound escalation (Branches A/B). The escalation queue is the human queue that receives escalated conversations — it may be the same as the inbound fallback queue, or a different one.
+
+### Check whether other compatible queues exist
+
+Query for queues with the correct SobjectType, excluding the inbound fallback queue already selected:
+
+```bash
+sf data query --target-org $ORG --json \
+  --query "SELECT Queue.Name, Queue.DeveloperName, Queue.Id
+           FROM QueueSobject
+           WHERE SobjectType='{SOBJECT_TYPE}'
+           AND Queue.DeveloperName != '{QUEUE_DEVELOPER_NAME}'"
+```
+
+### Branch on results
+
+**Zero other queues exist** → no choice to offer; reuse the inbound fallback queue. Set `ESCALATION_QUEUE_DEVELOPER_NAME = QUEUE_DEVELOPER_NAME` and `ESCALATION_QUEUE_ID = QUEUE_ID`. Continue without asking.
+
+**One or more other queues exist** → ask the user via `AskUserQuestion`:
+
+> *"Which queue should receive escalated conversations from the agent?"*
+> - *Use the same queue as inbound fallback: `{QUEUE_NAME}` ({QUEUE_DEVELOPER_NAME})* **(Recommended)**
+> - *{OtherQueue.Name} ({OtherQueue.DeveloperName})* — one option per additional compatible queue
+
+If the user picks the fallback: `ESCALATION_QUEUE_DEVELOPER_NAME = QUEUE_DEVELOPER_NAME`, `ESCALATION_QUEUE_ID = QUEUE_ID`.
+
+If the user picks a different queue: capture its `DeveloperName` and `Id` as `ESCALATION_QUEUE_DEVELOPER_NAME` and `ESCALATION_QUEUE_ID`.
+
+Use `ESCALATION_QUEUE_DEVELOPER_NAME` (not `QUEUE_DEVELOPER_NAME`) when writing the outbound RoutingFlow XML in Phase 3.

package/skills/service-agentforce-channel-configure/references/routing-flow.md

@@ -0,0 +1,384 @@
+# RoutingFlows — inbound and outbound
+
+Two distinct RoutingFlows are used when wiring an agent to a channel:
+
+| Flow | `processType` | `routingType` | Purpose |
+|---|---|---|---|
+| Inbound | `RoutingFlow` | `Copilot` | Routes arriving work items *to* the agent; queue is fallback when agent unavailable |
+| Outbound | `RoutingFlow` | `QueueBased` | Routes *from* the agent to a human queue when the customer requests escalation |
+
+Both flows reference the same fallback queue resolved in Phase 1. The inbound flow is created in Phase 2 (Branches B/C only — Branch A uses `sessionHandlerAsa` instead). The outbound flow is created in Phase 3 if the user opts into outbound escalation.
+
+---
+
+## Part 1 — Inbound RoutingFlow (Copilot routing)
+
+Used for Voice (Branch B) and Email-to-Case (Branch C). When a work item arrives on the channel, it routes directly to the Agentforce Agent, with the fallback queue used when the agent is unavailable.
+
+The `routingType` is `Copilot` (the platform token for Agentforce Agent routing). The agent is referenced by its **label** (`copilotLabel`), not its DeveloperName. The queue fallback is expressed via `queueLabel` (the queue's `Name` field) and `queueId` (the queue's 18-char record Id).
+
+## Naming convention
+
+| Channel | Flow Label | DeveloperName |
+|---|---|---|
+| Voice | `{AgentLabel} Inbound Voice Flow` | `{AgentDevName}_Inbound_Voice_Flow` |
+| Email-to-Case | `{AgentLabel} Inbound Email Flow` | `{AgentDevName}_Inbound_Email_Flow` |
+
+## Lookup the queue Id before writing the XML
+
+The `queueId` parameter must be a hardcoded 18-char Id in the XML. Query it from the `QUEUE_DEVELOPER_NAME` resolved in Phase 1:
+
+```bash
+QUEUE_ID=$(sf data query --target-org $ORG --json \
+  --query "SELECT Id FROM Group WHERE Type='Queue' AND DeveloperName='{QUEUE_DEVELOPER_NAME}'" \
+  | python3 -c "import sys,json; print(json.load(sys.stdin)['result']['records'][0]['Id'])")
+```
+
+## XML template
+
+Substitute: `{FLOW_LABEL}`, `{FLOW_DEVELOPER_NAME}`, `{AGENT_LABEL}`, `{AGENT_DEV_NAME}` (BotDefinition DeveloperName), `{QUEUE_LABEL}` (the queue's `Name`, e.g. `Voice Queue`), `{QUEUE_ID}` (18-char Id), `{SERVICE_CHANNEL_DEV_NAME}`, `{SERVICE_CHANNEL_LABEL}`.
+
+> **`copilotId` is required.** Without it the platform cannot resolve the agent at runtime and routes to the fallback queue instead. Use a `<setupReference>` pointing to the `BotDefinition` by DeveloperName — do not use a hardcoded Salesforce Id.
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<Flow xmlns="http://soap.sforce.com/2006/04/metadata">
+    <actionCalls>
+        <name>Route_to_Agent</name>
+        <label>Route to Agent</label>
+        <locationX>0</locationX>
+        <locationY>0</locationY>
+        <actionName>routeWork</actionName>
+        <actionType>routeWork</actionType>
+        <flowTransactionModel>CurrentTransaction</flowTransactionModel>
+        <inputParameters>
+            <name>recordId</name>
+            <value><elementReference>recordId</elementReference></value>
+        </inputParameters>
+        <inputParameters>
+            <name>serviceChannelLabel</name>
+            <value><stringValue>{SERVICE_CHANNEL_LABEL}</stringValue></value>
+        </inputParameters>
+        <inputParameters>
+            <name>serviceChannelDevName</name>
+            <value><stringValue>{SERVICE_CHANNEL_DEV_NAME}</stringValue></value>
+        </inputParameters>
+        <inputParameters>
+            <name>routingType</name>
+            <value><stringValue>Copilot</stringValue></value>
+        </inputParameters>
+        <inputParameters>
+            <name>copilotLabel</name>
+            <value><stringValue>{AGENT_LABEL}</stringValue></value>
+        </inputParameters>
+        <inputParameters>
+            <name>copilotId</name>
+            <value>
+                <setupReference>{AGENT_DEV_NAME}</setupReference>
+                <setupReferenceType>BotDefinition</setupReferenceType>
+            </value>
+        </inputParameters>
+        <inputParameters>
+            <name>queueLabel</name>
+            <value><stringValue>{QUEUE_LABEL}</stringValue></value>
+        </inputParameters>
+        <inputParameters>
+            <name>queueId</name>
+            <value><stringValue>{QUEUE_ID}</stringValue></value>
+        </inputParameters>
+        <inputParameters>
+            <name>serviceChannelId</name>
+            <value>
+                <setupReference>{SERVICE_CHANNEL_DEV_NAME}</setupReference>
+                <setupReferenceType>ServiceChannel</setupReferenceType>
+            </value>
+        </inputParameters>
+        <nameSegment>routeWork</nameSegment>
+        <offset>0</offset>
+        <versionString>2.0.0</versionString>
+    </actionCalls>
+    <apiVersion>67.0</apiVersion>
+    <areMetricsLoggedToDataCloud>false</areMetricsLoggedToDataCloud>
+    <environments>Default</environments>
+    <interviewLabel>{FLOW_DEVELOPER_NAME} {!$Flow.CurrentDateTime}</interviewLabel>
+    <label>{FLOW_LABEL}</label>
+    <processMetadataValues>
+        <name>BuilderType</name>
+        <value><stringValue>LightningFlowBuilder</stringValue></value>
+    </processMetadataValues>
+    <processMetadataValues>
+        <name>CanvasMode</name>
+        <value><stringValue>AUTO_LAYOUT_CANVAS</stringValue></value>
+    </processMetadataValues>
+    <processMetadataValues>
+        <name>OriginBuilderType</name>
+        <value><stringValue>LightningFlowBuilder</stringValue></value>
+    </processMetadataValues>
+    <processType>RoutingFlow</processType>
+    <start>
+        <locationX>50</locationX>
+        <locationY>0</locationY>
+        <connector><targetReference>Route_to_Agent</targetReference></connector>
+    </start>
+    <status>Active</status>
+    <variables>
+        <name>recordId</name>
+        <dataType>String</dataType>
+        <isCollection>false</isCollection>
+        <isInput>true</isInput>
+        <isOutput>false</isOutput>
+    </variables>
+</Flow>
+```
+
+## Deploy and verify
+
+Write the XML to `force-app/main/default/flows/{FLOW_DEVELOPER_NAME}.flow-meta.xml`, then deploy:
+
+```bash
+sf project deploy start -m "Flow:{FLOW_DEVELOPER_NAME}" --target-org $ORG
+```
+
+Verify the flow is active:
+```bash
+sf data query --target-org $ORG --json \
+  --query "SELECT ApiName, ActiveVersionId FROM FlowDefinitionView WHERE ApiName='{FLOW_DEVELOPER_NAME}'"
+```
+
+`ActiveVersionId` must be non-null. If it is null, the deploy did not produce an active version — check the deploy report for errors.
+
+## Common failures (inbound)
+
+| Symptom | Cause |
+|---|---|
+| `ActiveVersionId` is null after deploy | Flow saved as inactive draft — check for XML validation errors in the deploy report |
+| Work items route to queue instead of agent | `copilotId` is missing (most common), `routingType` is `QueueBased` instead of `Copilot`, or `copilotLabel` doesn't match the agent's exact label — all three must be present and correct |
+| Flow deploys but doesn't appear in Omni-Channel routing config | The flow is not yet referenced in a routing config — this skill doesn't create the routing config; the channel's own routing config must reference this flow |
+
+---
+
+## Part 2 — Outbound RoutingFlow (QueueBased escalation)
+
+Used in Phase 3 for all channel types. When the agent escalates to a human, this flow routes the conversation to the fallback queue resolved in Phase 1.
+
+### Naming convention
+
+| Channel | Flow Label | DeveloperName |
+|---|---|---|
+| Enhanced Chat | `{AgentLabel} Outbound Enhanced Chat Flow` | `{AgentDevName}_Outbound_Enhanced_Chat_Flow` |
+| Enhanced Messaging | `{AgentLabel} Outbound Messaging Flow` | `{AgentDevName}_Outbound_Messaging_Flow` |
+| Voice | `{AgentLabel} Outbound Voice Flow` | `{AgentDevName}_Outbound_Voice_Flow` |
+
+### Check before creating
+
+```bash
+sf data query --target-org $ORG --json \
+  --query "SELECT ApiName, ActiveVersionId FROM FlowDefinitionView WHERE ApiName='{FLOW_DEVELOPER_NAME}' AND ProcessType='RoutingFlow'"
+```
+
+If a row exists with non-null `ActiveVersionId`, reuse it — capture the `ApiName` and skip creation. If `ActiveVersionId` is null (inactive draft / OOB platform flow), create a new flow anyway — do not attempt to activate an existing draft.
+
+### Service channel values by channel type
+
+| Channel | `SERVICE_CHANNEL_DEV_NAME` | `SERVICE_CHANNEL_LABEL` |
+|---|---|---|
+| Enhanced Chat / Enhanced Messaging | `sfdc_livemessage` | `Messaging` |
+| Voice | `sfdc_phone` | `Phone` |
+
+### XML template
+
+Substitute: `{FLOW_LABEL}`, `{FLOW_DEVELOPER_NAME}`, `{QUEUE_DEVELOPER_NAME}` (from Phase 1), `{SERVICE_CHANNEL_DEV_NAME}`, `{SERVICE_CHANNEL_LABEL}`.
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<Flow xmlns="http://soap.sforce.com/2006/04/metadata">
+    <actionCalls>
+        <name>Check_Availability</name>
+        <label>Check Availability for Routing</label>
+        <locationX>0</locationX>
+        <locationY>0</locationY>
+        <actionName>checkAvailabilityForRouting</actionName>
+        <actionType>checkAvailabilityForRouting</actionType>
+        <connector>
+            <targetReference>Are_Reps_Available</targetReference>
+        </connector>
+        <flowTransactionModel>CurrentTransaction</flowTransactionModel>
+        <inputParameters>
+            <name>serviceChannelId</name>
+            <value>
+                <setupReference>{SERVICE_CHANNEL_DEV_NAME}</setupReference>
+                <setupReferenceType>ServiceChannel</setupReferenceType>
+            </value>
+        </inputParameters>
+        <inputParameters>
+            <name>serviceChannelLabel</name>
+            <value><stringValue>{SERVICE_CHANNEL_LABEL}</stringValue></value>
+        </inputParameters>
+        <inputParameters>
+            <name>serviceChannelDevName</name>
+            <value><stringValue>{SERVICE_CHANNEL_DEV_NAME}</stringValue></value>
+        </inputParameters>
+        <inputParameters>
+            <name>routingType</name>
+            <value><stringValue>QueueBased</stringValue></value>
+        </inputParameters>
+        <inputParameters>
+            <name>queueId</name>
+            <value><elementReference>Lookup_Queue_by_Name.Id</elementReference></value>
+        </inputParameters>
+        <inputParameters>
+            <name>isQueueVariable</name>
+            <value><booleanValue>true</booleanValue></value>
+        </inputParameters>
+        <inputParameters>
+            <name>selectedOutputs</name>
+            <value><stringValue>GET_AVAILABILITY</stringValue></value>
+        </inputParameters>
+        <nameSegment>checkAvailabilityForRouting</nameSegment>
+        <outputParameters>
+            <assignToReference>onlineAgentsCount</assignToReference>
+            <name>onlineAgentsCount</name>
+        </outputParameters>
+        <versionString>2.0.0</versionString>
+    </actionCalls>
+    <actionCalls>
+        <name>Route_to_Queue</name>
+        <label>Route to Queue</label>
+        <locationX>0</locationX>
+        <locationY>0</locationY>
+        <actionName>routeWork</actionName>
+        <actionType>routeWork</actionType>
+        <flowTransactionModel>CurrentTransaction</flowTransactionModel>
+        <inputParameters>
+            <name>recordId</name>
+            <value><elementReference>recordId</elementReference></value>
+        </inputParameters>
+        <inputParameters>
+            <name>serviceChannelLabel</name>
+            <value><stringValue>{SERVICE_CHANNEL_LABEL}</stringValue></value>
+        </inputParameters>
+        <inputParameters>
+            <name>serviceChannelDevName</name>
+            <value><stringValue>{SERVICE_CHANNEL_DEV_NAME}</stringValue></value>
+        </inputParameters>
+        <inputParameters>
+            <name>routingType</name>
+            <value><stringValue>QueueBased</stringValue></value>
+        </inputParameters>
+        <inputParameters>
+            <name>serviceChannelId</name>
+            <value>
+                <setupReference>{SERVICE_CHANNEL_DEV_NAME}</setupReference>
+                <setupReferenceType>ServiceChannel</setupReferenceType>
+            </value>
+        </inputParameters>
+        <inputParameters>
+            <name>queueId</name>
+            <value><elementReference>Lookup_Queue_by_Name.Id</elementReference></value>
+        </inputParameters>
+        <inputParameters>
+            <name>isQueueVariable</name>
+            <value><booleanValue>true</booleanValue></value>
+        </inputParameters>
+        <nameSegment>routeWork</nameSegment>
+        <versionString>2.0.0</versionString>
+    </actionCalls>
+    <apiVersion>67.0</apiVersion>
+    <areMetricsLoggedToDataCloud>false</areMetricsLoggedToDataCloud>
+    <decisions>
+        <name>Are_Reps_Available</name>
+        <label>Are Reps Available?</label>
+        <locationX>0</locationX>
+        <locationY>0</locationY>
+        <defaultConnectorLabel>No</defaultConnectorLabel>
+        <rules>
+            <name>Reps_Available</name>
+            <conditionLogic>and</conditionLogic>
+            <conditions>
+                <leftValueReference>onlineAgentsCount</leftValueReference>
+                <operator>GreaterThan</operator>
+                <rightValue><numberValue>0.0</numberValue></rightValue>
+            </conditions>
+            <connector><targetReference>Route_to_Queue</targetReference></connector>
+            <label>Yes</label>
+        </rules>
+    </decisions>
+    <environments>Default</environments>
+    <interviewLabel>{FLOW_DEVELOPER_NAME} {!$Flow.CurrentDateTime}</interviewLabel>
+    <label>{FLOW_LABEL}</label>
+    <processMetadataValues>
+        <name>BuilderType</name>
+        <value><stringValue>LightningFlowBuilder</stringValue></value>
+    </processMetadataValues>
+    <processMetadataValues>
+        <name>CanvasMode</name>
+        <value><stringValue>AUTO_LAYOUT_CANVAS</stringValue></value>
+    </processMetadataValues>
+    <processMetadataValues>
+        <name>OriginBuilderType</name>
+        <value><stringValue>LightningFlowBuilder</stringValue></value>
+    </processMetadataValues>
+    <processType>RoutingFlow</processType>
+    <recordLookups>
+        <name>Lookup_Queue_by_Name</name>
+        <label>Lookup Queue by Name</label>
+        <locationX>0</locationX>
+        <locationY>0</locationY>
+        <assignNullValuesIfNoRecordsFound>false</assignNullValuesIfNoRecordsFound>
+        <connector><targetReference>Check_Availability</targetReference></connector>
+        <filterLogic>and</filterLogic>
+        <filters>
+            <field>DeveloperName</field>
+            <operator>EqualTo</operator>
+            <value><stringValue>{QUEUE_DEVELOPER_NAME}</stringValue></value>
+        </filters>
+        <filters>
+            <field>Type</field>
+            <operator>EqualTo</operator>
+            <value><stringValue>Queue</stringValue></value>
+        </filters>
+        <getFirstRecordOnly>true</getFirstRecordOnly>
+        <object>Group</object>
+        <storeOutputAutomatically>true</storeOutputAutomatically>
+    </recordLookups>
+    <start>
+        <locationX>0</locationX>
+        <locationY>0</locationY>
+        <connector><targetReference>Lookup_Queue_by_Name</targetReference></connector>
+    </start>
+    <status>Active</status>
+    <variables>
+        <name>onlineAgentsCount</name>
+        <dataType>Number</dataType>
+        <isCollection>false</isCollection>
+        <isInput>false</isInput>
+        <isOutput>false</isOutput>
+        <scale>0</scale>
+    </variables>
+    <variables>
+        <name>recordId</name>
+        <dataType>String</dataType>
+        <isCollection>false</isCollection>
+        <isInput>true</isInput>
+        <isOutput>false</isOutput>
+    </variables>
+</Flow>
+```
+
+### Deploy and verify
+
+```bash
+sf project deploy start -m "Flow:{FLOW_DEVELOPER_NAME}" --target-org $ORG
+sf data query --target-org $ORG --json \
+  --query "SELECT ApiName, ActiveVersionId FROM FlowDefinitionView WHERE ApiName='{FLOW_DEVELOPER_NAME}'"
+```
+
+`ActiveVersionId` must be non-null. Capture `{FLOW_DEVELOPER_NAME}` for use in the agent's connection block (`outbound_route_name: "flow://{FLOW_DEVELOPER_NAME}"`).
+
+## Common failures (outbound)
+
+| Symptom | Cause |
+|---|---|
+| `ActiveVersionId` is null after deploy | Flow saved as inactive draft — check XML for validation errors |
+| Escalation goes nowhere / agent hangs | Connection block uses wrong key (`messaging:` instead of `customer_web_client:` for EmbeddedMessaging, etc.) — see `agent-wiring.md` |
+| No agents available — queue not receiving work | Queue lacks a `QueueSobject` for the correct SobjectType — recheck Phase 1 |