@salesforce/afv-skills 1.47.0 → 1.48.0

package/skills/service-omni-service-channel-configure/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: service-omni-service-channel-configure
+description: "Use to ensure exactly one ServiceChannel exists on a Salesforce org for a routable sObject (Case | Incident | MessagingSession | VoiceCall), reusing any standard or custom channel already bound to that sObject and only deploying a canonical template when none exists. Salesforce enforces one ServiceChannel per RelatedEntity, so the skill detects via the Tooling API first. Standard channels ship for Case (Cases), MessagingSession (sfdc_livemessage), VoiceCall (sfdc_phone); Incident has none. Triggers: configure ServiceChannel for Case/Incident/Messaging/Voice routing, add Incident or Voice routing to Omni. Do not use to tune per-sObject capacity (use PresenceUserConfig.Capacity), to reset a mis-configured channel to canonical shape, or for sObjects outside Case/Incident/MessagingSession/VoiceCall."
+allowed-tools: Bash Read Write Edit Glob Grep
+metadata:
+  version: "1.0"
+  domains: ["Service"]
+  minApiVersion: "66.0"
+  relatedSkills:
+    - "service-omni-base-settings-configure"
+  accessCheck:
+    - type: license
+      value: ServiceCloud
+  cliTools:
+    - tool: ["jq"]
+      semver: ">=1.6"
+    - tool: ["sf"]
+      semver: ">=2.139.6"
+---
+
+# service-omni-service-channel-configure
+
+Ensure exactly one `ServiceChannel` is present for a routable sObject, reusing whatever is already bound (Salesforce standard or a pre-existing custom channel) and deploying the skill's canonical v66 template only when none exists. Salesforce enforces one ServiceChannel per `RelatedEntity`, so the skill detects first and never deploys blindly — deploying a second channel for an sObject that already has one fails with "This Salesforce object is already in use by another Service channel." It handles one sObject per call; callers configuring multiple sObjects invoke it once for each sObject, after `service-omni-base-settings-configure` has enabled Omni-Channel.
+
+| sObject | Standard channel (if any) | Canonical asset |
+|---|---|---|
+| `Case` | `Cases` | `Cases.serviceChannel-meta.xml` |
+| `Incident` | none (Incident Management sObject) | `Incidents.serviceChannel-meta.xml` — deployed on first run |
+| `MessagingSession` | `sfdc_livemessage` | `MessagingSessions.serviceChannel-meta.xml` — deployed only if the standard channel is missing |
+| `VoiceCall` | `sfdc_phone` | `VoiceCalls.serviceChannel-meta.xml` — deployed only if the standard channel is missing |
+
+## Inputs
+
+```bash
+bash scripts/deploy-and-report.sh <org-alias> [Case|Incident|MessagingSession|VoiceCall]
+```
+
+- `org-alias` (required).
+- `sobject_type` (optional, default `Case`) — one of `Case | Incident | MessagingSession | VoiceCall`.
+
+## Preconditions and safety
+
+- Target org authenticated via `sf` CLI (My Domain URL), Service Cloud license, `sf` CLI ≥ 2.139.6.
+- Omni-Channel base settings enabled (`service-omni-base-settings-configure`) — `ServiceChannel` is only queryable/writable when `enableOmniChannel=true`; a `INVALID_TYPE` on deploy means base settings are off.
+- `Incident` requires the Incident Management feature enabled; `MessagingSession` requires Enhanced Messaging. The skill verifies `EntityDefinition` first and blocks with a click-path when the target sObject is absent.
+
+## Run
+
+`deploy-and-report.sh` performs the prereq check, discovery, and (only when needed) deploy, then emits the report:
+
+1. **Prereq** — confirm the target sObject is queryable via `EntityDefinition`; block with a click-path otherwise.
+2. **Discover** — query the Tooling API for a `ServiceChannel` with `RelatedEntity = <sobject_type>`. `ServiceChannel` is a Tooling entity on v66; the standard Data API returns `INVALID_TYPE`. A hit means reuse.
+3. **Deploy** (only when nothing was found) — `sf project deploy start` of the canonical XML (`Cases` | `Incidents` | `MessagingSessions` | `VoiceCalls`); a `Changed` state is `created`, `Unchanged` is `reused`.
+
+## Behavior
+
+**Detect-then-reuse-or-deploy.** Because Salesforce rejects a second channel per `RelatedEntity`, deploy-first is unsafe: an operator who renamed the standard `Cases` channel would hit the "already in use" error instead of gracefully reusing. Tooling discovery is fast and returns both the reuse decision and the discovered `DeveloperName` in one call. The trade-off is that the skill cannot tell "our canonical shape matches" from "some custom channel is bound" — an operator with a non-canonical channel gets `reused` and their channel is left untouched (v1 never overwrites operator state).
+
+**Capacity model.** The canonical assets use `TAB_BASED` for every variant. `STATUS_BASED` requires companion fields whose full schema is undocumented, so it is out of scope; per-agent capacity tuning belongs to `PresenceUserConfig.Capacity`, not this skill.
+
+**Concurrency.** If a deploy fails with "already in use," another process created the channel between discovery and deploy; the skill soft-fails and a re-run reuses it.
+
+## Output contract
+
+A single JSON object per invocation with `status` ∈ `created` | `reused` | `blocked`, plus `sobject_type`, `channel_developer_name`, `channel_id`, `channel_origin`, `target_capacity_model`, `target_related_entity_type`, `before_state`, `deploy_id`, `manual_actions`, and `blocking_issue`.
+
+- `reused` — an existing channel was found (discovery hit, or a deploy returned `Unchanged`).
+- `created` — no channel existed; the canonical XML deployed with `Changed`.
+- `blocked` — the sObject is not on the org, base settings are off (`INVALID_TYPE`), or a race left the channel already in use.
+- `channel_origin` is one of `salesforce_standard` (an `sfdc_*` name or `Cases`), `canonical_asset` (a shipped asset name), `canonical_template` (freshly deployed this run), or `custom` (a pre-existing org-specific channel).
+- `channel_id` is populated whenever a channel exists (`null` on `blocked`); `deploy_id` is populated only on the deploy branch; `blocking_issue` is non-null only when `status: blocked`.
+
+## Limitations
+
+- One sObject per invocation.
+- Only `Case`, `Incident`, `MessagingSession`, `VoiceCall` are supported — extend by adding an `assets/force-app/main/default/serviceChannels/<Name>.serviceChannel-meta.xml` file and a dispatcher branch.
+- Always reuses an existing channel; it does not reset a mis-configured channel to canonical shape.
+
+## References
+
+| File | When to read |
+|---|---|
+| `references/api-notes.md` | On unexpected discovery results, deploy failures, or sObject-specific schema questions |

package/skills/service-omni-service-channel-configure/assets/force-app/main/default/serviceChannels/Cases.serviceChannel-meta.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ServiceChannel xmlns="http://soap.sforce.com/2006/04/metadata">
+    <capacityModel>TAB_BASED</capacityModel>
+    <doesMinimizeWidgetOnAccept>false</doesMinimizeWidgetOnAccept>
+    <hasAutoAcceptEnabled>false</hasAutoAcceptEnabled>
+    <isInterruptible>false</isInterruptible>
+    <label>Cases</label>
+    <relatedEntityType>Case</relatedEntityType>
+</ServiceChannel>

package/skills/service-omni-service-channel-configure/assets/force-app/main/default/serviceChannels/Incidents.serviceChannel-meta.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ServiceChannel xmlns="http://soap.sforce.com/2006/04/metadata">
+    <capacityModel>TAB_BASED</capacityModel>
+    <doesMinimizeWidgetOnAccept>false</doesMinimizeWidgetOnAccept>
+    <hasAutoAcceptEnabled>false</hasAutoAcceptEnabled>
+    <isInterruptible>false</isInterruptible>
+    <label>Incidents</label>
+    <relatedEntityType>Incident</relatedEntityType>
+</ServiceChannel>

package/skills/service-omni-service-channel-configure/assets/force-app/main/default/serviceChannels/MessagingSessions.serviceChannel-meta.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ServiceChannel xmlns="http://soap.sforce.com/2006/04/metadata">
+    <capacityModel>TAB_BASED</capacityModel>
+    <doesMinimizeWidgetOnAccept>false</doesMinimizeWidgetOnAccept>
+    <hasAutoAcceptEnabled>false</hasAutoAcceptEnabled>
+    <isInterruptible>true</isInterruptible>
+    <label>Messaging Sessions</label>
+    <relatedEntityType>MessagingSession</relatedEntityType>
+</ServiceChannel>

package/skills/service-omni-service-channel-configure/assets/force-app/main/default/serviceChannels/VoiceCalls.serviceChannel-meta.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ServiceChannel xmlns="http://soap.sforce.com/2006/04/metadata">
+    <capacityModel>TAB_BASED</capacityModel>
+    <doesMinimizeWidgetOnAccept>false</doesMinimizeWidgetOnAccept>
+    <hasAutoAcceptEnabled>false</hasAutoAcceptEnabled>
+    <isInterruptible>false</isInterruptible>
+    <label>Voice Calls</label>
+    <relatedEntityType>VoiceCall</relatedEntityType>
+</ServiceChannel>

package/skills/service-omni-service-channel-configure/assets/package.xml

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Package xmlns="http://soap.sforce.com/2006/04/metadata">
+    <types>
+        <members>Cases</members>
+        <members>Incidents</members>
+        <members>MessagingSessions</members>
+        <members>VoiceCalls</members>
+        <name>ServiceChannel</name>
+    </types>
+    <version>66.0</version>
+</Package>

package/skills/service-omni-service-channel-configure/assets/sfdx-project.json

@@ -0,0 +1,12 @@
+{
+  "packageDirectories": [
+    {
+      "path": "force-app",
+      "default": true
+    }
+  ],
+  "name": "service-omni-service-channel-configure",
+  "namespace": "",
+  "sfdcLoginUrl": "https://login.salesforce.com",
+  "sourceApiVersion": "66.0"
+}

package/skills/service-omni-service-channel-configure/references/api-notes.md

@@ -0,0 +1,84 @@
+# ServiceChannel — API notes
+
+Load this reference only when the deploy fails or Salesforce reports unexpected state. Under normal operation the skill's deploy-and-report script just runs and emits its JSON; this doc is for troubleshooting and extensions.
+
+**Metadata type:** `ServiceChannel` (queryable via the Tooling API for basic fields; Metadata-only for `capacityModel` and other tuning fields). **API version:** v66.
+
+---
+
+## The six fields in the shipped Cases XML
+
+| Field | Value | Semantics |
+|---|---|---|
+| `capacityModel` | `TAB_BASED` | Capacity accounting model. `TAB_BASED` = each open Console tab = 1 unit of an agent's total capacity. Alternative: `STATUS_BASED` (capacity varies by presence status) |
+| `doesMinimizeWidgetOnAccept` | `false` | Whether the Omni widget minimizes when an agent accepts work. `false` = widget stays visible |
+| `hasAutoAcceptEnabled` | `false` | Whether work is auto-accepted (no click). `false` = agent must manually accept |
+| `isInterruptible` | `false` | Whether new work can interrupt an active work item. `false` = agents finish current work first |
+| `label` | `Cases` | UI display name. Must be `Cases` for the standard Case channel |
+| `relatedEntityType` | `Case` | The sObject type this channel routes. Must be `Case` for Case routing |
+
+**Fields not in the shipped XML (Salesforce uses defaults):**
+- `secondaryRoutingPriorityField` — set only when secondary priority sorting is needed.
+- `customEventChannel` / `customEventPayloadField` — only for custom-event-driven channels.
+- `dispatcherClass` — only for advanced routing customization.
+
+Fork the skill's XML to set any of these.
+
+## Capacity is not tunable at the channel level on v66
+
+Per-item weighted capacity (`capacityWeight` on older API versions) is no longer a ServiceChannel field on v66; the schema exposes `capacityModel` (`TAB_BASED` | `STATUS_BASED`) instead. For per-agent totals use `PresenceUserConfig.Capacity` at the agent level, or switch `capacityModel` to `STATUS_BASED` for status-dependent behavior. Related renames on v66: `masterLabel` → `label`, `relatedEntity` → `relatedEntityType`; `isCustomerVisible` was removed (customer visibility is now inferred from channel type).
+
+**Implication for this skill:** on a fresh v66 CDO the `Cases` channel already has all six fields at their defaults, so this skill's deploy usually returns `state: Unchanged` / `status: reused`. It is most useful for recovering a mis-configured `Cases` channel, migrating from an older API version's config, or documenting the canonical v66 state in a git-controlled asset. It cannot change per-Case weighted capacity, and enabling auto-accept or minimizing behavior requires forking the XML.
+
+---
+
+## Standard channels' DeveloperNames
+
+Salesforce ships several standard ServiceChannels on Service Cloud orgs:
+
+| DeveloperName | MasterLabel | RelatedEntity | Purpose |
+|---|---|---|---|
+| `Cases` | `Cases` | `Case` | Standard Case routing (**this skill's target**) |
+| `sfdc_liveagent` | `Chat` | `LiveChatTranscript` | Live Agent chat |
+| `sfdc_livemessage` | `Messaging` | `MessagingSession` | Messaging (WhatsApp, SMS, etc.) |
+| `sfdc_phone` | `Phone` | `VoiceCall` | Voice/telephony |
+
+The standard Case channel's DeveloperName is `Cases` (plural), not `Case` (singular). To configure a different standard channel, fork this skill's XML and package.xml so the file path and package member both match the target DeveloperName.
+
+---
+
+## ServiceChannel's Metadata field is not Tooling-SOQL queryable
+
+`capacityModel` and the other tuning fields cannot be read via Tooling SOQL as a pre-check:
+
+```text
+SELECT Id, DeveloperName, MasterLabel, CapacityWeight FROM ServiceChannel WHERE DeveloperName='Cases'
+-- INVALID_FIELD: No such column 'CapacityWeight' on entity 'ServiceChannel'.
+
+SELECT Id, DeveloperName, MasterLabel, Metadata FROM ServiceChannel WHERE DeveloperName='Cases'
+-- INVALID_FIELD: No such column 'Metadata' on entity 'ServiceChannel'.
+```
+
+`GET /services/data/vXX.0/tooling/sobjects/ServiceChannel/<id>` also returns `{Metadata: null}` even when the metadata exists. The workaround is a Metadata API retrieve (`sf project retrieve start --metadata "ServiceChannel:Cases"`) — slow (~90 sec) but reliable. This skill avoids the retrieve entirely by relying on the deploy's own `files[0].state` signal.
+
+Behavior is entity-specific: `WorkSkillRouting` exposes a queryable `Metadata` field, `ServiceChannel` does not. Always describe first (or test with a small query) before assuming Tooling SOQL is a viable read path.
+
+---
+
+## Deploy failure modes
+
+| Symptom | Root cause | Skill behavior |
+|---|---|---|
+| `INVALID_TYPE` for ServiceChannel | OmniChannelSettings not enabled (`enableOmniChannel=false`) | Translates to: "OmniChannelSettings is not enabled on this org. Run service-omni-base-settings-configure first." |
+| `FIELD_INTEGRITY_EXCEPTION` for relatedEntity | Attempted to change `relatedEntity` (immutable on the standard Case channel) | Block; do not change relatedEntity via this skill — write a separate custom-channel-create skill |
+| `DUPLICATE_DEVELOPER_NAME` | Tried to create a channel with an existing DeveloperName | Should not happen (this skill updates the existing `Cases`, not creates) — indicates a bug or org corruption |
+| `state: Unchanged` | Payload matched existing state | Success — `status: reused` |
+| `state: Changed, success: true` | Payload modified state | Success — `status: created` |
+
+---
+
+## Alternative approaches (evaluated, not chosen)
+
+- **Tooling API PATCH on `Metadata`** — fails at the read step (see above), so a PATCH cannot be validated. The Metadata API is the reliable canonical path.
+- **Retrieve → parse XML → decide → deploy** — rejected because the ~90-second retrieve latency is not justified when the deploy's own `state: Unchanged` signal is authoritative. If before-state visibility becomes important, add an optional `--with-detect` flag.
+- **`sf api request rest` GET → PATCH** — the GET works but returns `Metadata: null` for ServiceChannel, so it is not a viable read path.

package/skills/service-omni-service-channel-configure/scripts/deploy-and-report.sh

@@ -0,0 +1,383 @@
+#!/usr/bin/env bash
+# deploy-and-report.sh - ensure a ServiceChannel exists for the requested sObject, reusing any existing (standard/custom) one and deploying the canonical template only if none exists (Salesforce allows one channel per RelatedEntity). Args, exit codes: SKILL.md.
+
+set -euo pipefail
+
+if [ $# -lt 1 ]; then
+  echo '{"error":"Missing required argument: org-alias","usage":"bash deploy-and-report.sh <org-alias> [Case|Incident|MessagingSession|VoiceCall]"}' >&2
+  exit 1
+fi
+
+ORG="$1"
+SOBJECT_TYPE="${2:-Case}"
+
+case "$SOBJECT_TYPE" in
+  Case)
+    CANONICAL_DEVELOPER_NAME="Cases"
+    TARGET_CAPACITY_MODEL="TAB_BASED"
+    ;;
+  Incident)
+    CANONICAL_DEVELOPER_NAME="Incidents"
+    TARGET_CAPACITY_MODEL="TAB_BASED"
+    ;;
+  MessagingSession)
+    CANONICAL_DEVELOPER_NAME="MessagingSessions"
+    TARGET_CAPACITY_MODEL="TAB_BASED"
+    ;;
+  VoiceCall)
+    CANONICAL_DEVELOPER_NAME="VoiceCalls"
+    TARGET_CAPACITY_MODEL="TAB_BASED"
+    ;;
+  *)
+    echo "{\"error\":\"Unsupported sobject_type: '$SOBJECT_TYPE'. Supported: Case, Incident, MessagingSession, VoiceCall\"}" >&2
+    exit 2
+    ;;
+esac
+
+if ! sf org display --target-org "$ORG" --json >/dev/null 2>&1; then
+  echo "{\"error\":\"Org alias '$ORG' is not authenticated.\"}" >&2
+  exit 1
+fi
+
+# Write guard: can deploy a ServiceChannel, so self-enforce the production-org guard (directly invokable).
+ORG_JSON=$(sf data query --target-org "$ORG" \
+  --query "SELECT IsSandbox, TrialExpirationDate, OrganizationType FROM Organization LIMIT 1" \
+  --json 2>/dev/null) || {
+  echo "{\"error\":\"Failed to query Organization for safe_to_write guard: $(printf '%s' "$ORG_JSON" | head -c 300)\"}" >&2
+  exit 1
+}
+IS_SANDBOX=$(echo "$ORG_JSON" | jq -r '.result.records[0].IsSandbox')
+TRIAL_EXP=$(echo "$ORG_JSON"  | jq -r '.result.records[0].TrialExpirationDate // "null"')
+ORG_TYPE=$(echo "$ORG_JSON"   | jq -r '.result.records[0].OrganizationType')
+
+SAFE_TO_WRITE=false
+if [ "$IS_SANDBOX" = "true" ] \
+   || [ "$TRIAL_EXP" != "null" ] \
+   || [ "$ORG_TYPE" = "Developer Edition" ] \
+   || [ "$ORG_TYPE" = "Base Edition" ]; then
+  SAFE_TO_WRITE=true
+fi
+
+if [ "$SAFE_TO_WRITE" != "true" ]; then
+  # Structured `blocked` results go to stdout so the coordinator/caller can parse them (stderr would look like empty output).
+  echo "{\"skill\":\"service-omni-service-channel-configure\",\"status\":\"blocked\",\"blocking_issue\":\"Refusing to deploy a ServiceChannel to a real production customer org (IsSandbox=$IS_SANDBOX, TrialExpirationDate=$TRIAL_EXP, OrganizationType=$ORG_TYPE). Target a sandbox, trial CDO, or Developer Edition org.\",\"safe_to_write\":false}"
+  exit 1
+fi
+
+# emit read-only plan preview JSON and exit 0 (PLAN_ONLY mode)
+emit_plan() {
+  local status="$1"
+  local detail="$2"
+  jq -n \
+    --arg status "$status" \
+    --arg detail "$detail" \
+    --arg sobject "$SOBJECT_TYPE" \
+    --arg dn "$CANONICAL_DEVELOPER_NAME" \
+    '{
+      skill: "service-omni-service-channel-configure",
+      status: $status,
+      plan_mode: true,
+      plan_detail: $detail,
+      sobject_type: $sobject,
+      channel_developer_name: $dn,
+      manual_actions: [],
+      blocking_issue: null
+    }'
+  exit 0
+}
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ASSETS_DIR="$(cd "$SCRIPT_DIR/../assets" && pwd)"
+
+# Prereq: target sObject exists on the org.
+ENTITY_CHECK=$(sf data query --target-org "$ORG" \
+  --query "SELECT QualifiedApiName FROM EntityDefinition WHERE QualifiedApiName = '$SOBJECT_TYPE'" \
+  --json 2>/dev/null | jq -r '.result.totalSize // 0')
+
+if [ "$ENTITY_CHECK" != "1" ]; then
+  jq -n --arg sobject "$SOBJECT_TYPE" \
+    '{
+      skill: "service-omni-service-channel-configure",
+      status: "blocked",
+      sobject_type: $sobject,
+      channel_developer_name: null,
+      channel_origin: null,
+      target_capacity_model: null,
+      target_related_entity_type: $sobject,
+      before_state: "unknown",
+      deploy_id: null,
+      manual_actions: [{
+        id: "prereq-entity-missing",
+        title: ("sObject " + $sobject + " not available on this org"),
+        click_path: (
+          if $sobject == "Incident" then "Enable the Incident Management feature via Setup, then re-run"
+          elif $sobject == "MessagingSession" then "Enable Enhanced Messaging via Setup → Messaging, then re-run"
+          else "Contact your admin - expected sObject missing"
+          end
+        )
+      }],
+      blocking_issue: ("Target sObject " + $sobject + " is not queryable on this org")
+    }'
+  exit 1
+fi
+
+# Step 1: Discover an existing ServiceChannel (Tooling API only). Treat the result as authoritative
+# only when it parses to a numeric totalSize - an inconclusive read must not deploy a duplicate.
+EXISTING_JSON=$(sf data query --use-tooling-api --target-org "$ORG" \
+  --query "SELECT Id, DeveloperName, MasterLabel FROM ServiceChannel WHERE RelatedEntity = '$SOBJECT_TYPE' ORDER BY DeveloperName LIMIT 1" \
+  --json 2>/dev/null || true)
+
+if ! echo "$EXISTING_JSON" | jq -e '.result.totalSize | numbers' >/dev/null 2>&1; then
+  jq -n --arg sobject "$SOBJECT_TYPE" --arg raw "$(printf '%s' "$EXISTING_JSON" | head -c 400)" \
+    '{
+      skill: "service-omni-service-channel-configure",
+      status: "blocked",
+      sobject_type: $sobject,
+      channel_developer_name: null,
+      channel_origin: null,
+      before_state: "unknown",
+      deploy_id: null,
+      manual_actions: [],
+      blocking_issue: ("Could not determine whether a ServiceChannel already exists for " + $sobject + " - the discovery query was inconclusive. Not deploying on an inconclusive read. Raw: " + $raw)
+    }'
+  exit 1
+fi
+
+EXISTING_COUNT=$(echo "$EXISTING_JSON" | jq -r '.result.totalSize // 0')
+
+if [ "$EXISTING_COUNT" = "1" ]; then
+  # Step 2a: REUSE the existing channel - no deploy.
+  EXISTING_DEV_NAME=$(echo "$EXISTING_JSON" | jq -r '.result.records[0].DeveloperName')
+  EXISTING_ID=$(echo "$EXISTING_JSON"       | jq -r '.result.records[0].Id')
+  # Origin taxonomy: salesforce_standard (OOTB), canonical_asset (matches our asset names), custom (else).
+  CHANNEL_ORIGIN="custom"
+  case "$EXISTING_DEV_NAME" in
+    sfdc_*|Cases) CHANNEL_ORIGIN="salesforce_standard" ;;
+    Incidents|MessagingSessions) CHANNEL_ORIGIN="canonical_asset" ;;
+  esac
+
+  jq -n \
+    --arg sobject "$SOBJECT_TYPE" \
+    --arg dev_name "$EXISTING_DEV_NAME" \
+    --arg existing_id "$EXISTING_ID" \
+    --arg origin "$CHANNEL_ORIGIN" \
+    --arg cap_model "$TARGET_CAPACITY_MODEL" \
+    '{
+      skill: "service-omni-service-channel-configure",
+      status: "reused",
+      sobject_type: $sobject,
+      channel_developer_name: $dev_name,
+      channel_id: $existing_id,
+      channel_origin: $origin,
+      target_capacity_model: $cap_model,
+      target_related_entity_type: $sobject,
+      before_state: "Unchanged",
+      deploy_id: null,
+      manual_actions: [],
+      blocking_issue: null
+    }'
+  exit 0
+fi
+
+# PLAN_ONLY: reaching here means no channel exists for this sObject (the reuse path above already
+# returned). A --run would deploy the canonical template. Report that and stop before the deploy.
+if [ "${PLAN_ONLY:-}" = "1" ]; then
+  emit_plan "action_needed" "No ServiceChannel bound to $SOBJECT_TYPE; would deploy canonical '$CANONICAL_DEVELOPER_NAME'."
+fi
+
+# Step 2b: No existing channel - deploy our canonical XML.
+if [ ! -f "$ASSETS_DIR/sfdx-project.json" ]; then
+  echo "{\"error\":\"Assets DX project not found at $ASSETS_DIR\"}" >&2
+  exit 1
+fi
+
+CHANNEL_XML="$ASSETS_DIR/force-app/main/default/serviceChannels/${CANONICAL_DEVELOPER_NAME}.serviceChannel-meta.xml"
+if [ ! -f "$CHANNEL_XML" ]; then
+  echo "{\"error\":\"ServiceChannel asset not found for sobject_type=$SOBJECT_TYPE at $CHANNEL_XML\"}" >&2
+  exit 1
+fi
+
+DEPLOY_JSON=$(cd "$ASSETS_DIR" && sf project deploy start --target-org "$ORG" --metadata "ServiceChannel:${CANONICAL_DEVELOPER_NAME}" --json 2>/dev/null || true)
+
+DEPLOY_SUCCESS=$(echo "$DEPLOY_JSON" | jq -r '.result.success // false' 2>/dev/null)
+DEPLOY_ID=$(echo "$DEPLOY_JSON"     | jq -r '.result.id     // null'  2>/dev/null)
+
+translate_deploy_error() {
+  local raw="$1"
+  case "$raw" in
+    *INVALID_TYPE*"ServiceChannel"*)
+      echo "OmniChannelSettings is not enabled on this org. Run service-omni-base-settings-configure first."
+      ;;
+    *"already in use by another Service channel"*)
+      echo "Race condition: another process created a ServiceChannel for $SOBJECT_TYPE between our detect and deploy. Re-run to reuse it."
+      ;;
+    *)
+      echo "$raw"
+      ;;
+  esac
+}
+
+if [ "$DEPLOY_SUCCESS" != "true" ]; then
+  FAILURES=$(echo "$DEPLOY_JSON" | jq -r '.result.details.componentFailures // [] | map(.problem) | join("; ")' 2>/dev/null)
+  if [ -z "$FAILURES" ] || [ "$FAILURES" = "null" ]; then
+    FAILURES=$(echo "$DEPLOY_JSON" | jq -r '.message // .result.errorMessage // "Unknown deploy error"' 2>/dev/null)
+  fi
+  FRIENDLY=$(translate_deploy_error "$FAILURES")
+  jq -n \
+    --arg sobject "$SOBJECT_TYPE" \
+    --arg dev_name "$CANONICAL_DEVELOPER_NAME" \
+    --arg cap_model "$TARGET_CAPACITY_MODEL" \
+    --arg deploy_id "$DEPLOY_ID" \
+    --arg blocking "$FRIENDLY" \
+    --arg raw "$FAILURES" \
+    '{
+      skill: "service-omni-service-channel-configure",
+      status: "blocked",
+      sobject_type: $sobject,
+      channel_developer_name: $dev_name,
+      channel_id: null,
+      channel_origin: "canonical_template",
+      target_capacity_model: $cap_model,
+      target_related_entity_type: $sobject,
+      before_state: "unknown",
+      deploy_id: (if $deploy_id == "null" or $deploy_id == "" then null else $deploy_id end),
+      manual_actions: [],
+      blocking_issue: $blocking,
+      raw_error: $raw
+    }'
+  exit 1
+fi
+
+# Require a clean Succeeded (SucceededPartial / anything else is not success).
+DEPLOY_STATUS=$(echo "$DEPLOY_JSON" | jq -r '.result.status // "unknown"' 2>/dev/null)
+if [ "$DEPLOY_STATUS" != "Succeeded" ]; then
+  jq -n \
+    --arg sobject "$SOBJECT_TYPE" \
+    --arg dev_name "$CANONICAL_DEVELOPER_NAME" \
+    --arg cap_model "$TARGET_CAPACITY_MODEL" \
+    --arg deploy_id "$DEPLOY_ID" \
+    --arg deploy_status "$DEPLOY_STATUS" \
+    '{
+      skill: "service-omni-service-channel-configure",
+      status: "blocked",
+      sobject_type: $sobject,
+      channel_developer_name: $dev_name,
+      channel_id: null,
+      channel_origin: "canonical_template",
+      target_capacity_model: $cap_model,
+      target_related_entity_type: $sobject,
+      before_state: "unknown",
+      deploy_id: (if $deploy_id == "null" or $deploy_id == "" then null else $deploy_id end),
+      manual_actions: [],
+      blocking_issue: ("Deploy did not fully succeed (result.status=" + $deploy_status + "). Refusing to report success on a partial/ambiguous deploy.")
+    }'
+  exit 1
+fi
+
+# Component state must be a recognized idempotency signal (Created/Changed/Unchanged); else block.
+BEFORE_STATE=$(echo "$DEPLOY_JSON" | jq -r '.result.files[0].state // "unknown"' 2>/dev/null)
+case "$BEFORE_STATE" in
+  Created|Changed) STATUS="created" ;;
+  Unchanged)       STATUS="reused"  ;;
+  *)
+    jq -n \
+      --arg sobject "$SOBJECT_TYPE" \
+      --arg dev_name "$CANONICAL_DEVELOPER_NAME" \
+      --arg cap_model "$TARGET_CAPACITY_MODEL" \
+      --arg deploy_id "$DEPLOY_ID" \
+      --arg before_state "$BEFORE_STATE" \
+      '{
+        skill: "service-omni-service-channel-configure",
+        status: "blocked",
+        sobject_type: $sobject,
+        channel_developer_name: $dev_name,
+        channel_id: null,
+        channel_origin: "canonical_template",
+        target_capacity_model: $cap_model,
+        target_related_entity_type: $sobject,
+        before_state: $before_state,
+        deploy_id: (if $deploy_id == "null" or $deploy_id == "" then null else $deploy_id end),
+        manual_actions: [],
+        blocking_issue: ("Unrecognized component deploy state \"" + $before_state + "\" - expected Created, Changed, or Unchanged. Not reporting success.")
+      }'
+    exit 1
+    ;;
+esac
+
+# Post-deploy verify: re-query via Tooling API to confirm the channel exists, capture its Id, and
+# check RelatedEntity matches the target (a deploy state alone isn't proof of correct binding).
+VERIFY_JSON=$(sf data query --use-tooling-api --target-org "$ORG" \
+  --query "SELECT Id, DeveloperName, MasterLabel, RelatedEntity FROM ServiceChannel WHERE DeveloperName = '$CANONICAL_DEVELOPER_NAME' LIMIT 1" \
+  --json 2>/dev/null || true)
+
+if ! echo "$VERIFY_JSON" | jq -e '.result.totalSize | numbers' >/dev/null 2>&1 \
+   || [ "$(echo "$VERIFY_JSON" | jq -r '.result.totalSize')" != "1" ]; then
+  jq -n \
+    --arg sobject "$SOBJECT_TYPE" \
+    --arg dev_name "$CANONICAL_DEVELOPER_NAME" \
+    --arg deploy_id "$DEPLOY_ID" \
+    --arg raw "$(printf '%s' "$VERIFY_JSON" | head -c 300)" \
+    '{
+      skill: "service-omni-service-channel-configure",
+      status: "blocked",
+      sobject_type: $sobject,
+      channel_developer_name: $dev_name,
+      channel_id: null,
+      channel_origin: "canonical_template",
+      target_related_entity_type: $sobject,
+      before_state: "unknown",
+      deploy_id: (if $deploy_id == "null" or $deploy_id == "" then null else $deploy_id end),
+      manual_actions: [],
+      blocking_issue: ("Deploy reported success but post-deploy re-query could not confirm the ServiceChannel exists. Raw: " + $raw)
+    }'
+  exit 1
+fi
+
+VERIFIED_ID=$(echo "$VERIFY_JSON"      | jq -r '.result.records[0].Id')
+VERIFIED_RELATED=$(echo "$VERIFY_JSON" | jq -r '.result.records[0].RelatedEntity // "null"')
+
+if [ "$VERIFIED_RELATED" != "$SOBJECT_TYPE" ]; then
+  jq -n \
+    --arg sobject "$SOBJECT_TYPE" \
+    --arg dev_name "$CANONICAL_DEVELOPER_NAME" \
+    --arg channel_id "$VERIFIED_ID" \
+    --arg related "$VERIFIED_RELATED" \
+    '{
+      skill: "service-omni-service-channel-configure",
+      status: "blocked",
+      sobject_type: $sobject,
+      channel_developer_name: $dev_name,
+      channel_id: $channel_id,
+      channel_origin: "canonical_template",
+      target_related_entity_type: $sobject,
+      before_state: "unknown",
+      manual_actions: [],
+      blocking_issue: ("ServiceChannel exists but RelatedEntity=\"" + $related + "\" does not match the requested sObject \"" + $sobject + "\".")
+    }'
+  exit 1
+fi
+
+jq -n \
+  --arg status "$STATUS" \
+  --arg sobject "$SOBJECT_TYPE" \
+  --arg dev_name "$CANONICAL_DEVELOPER_NAME" \
+  --arg channel_id "$VERIFIED_ID" \
+  --arg related "$VERIFIED_RELATED" \
+  --arg cap_model "$TARGET_CAPACITY_MODEL" \
+  --arg before_state "$BEFORE_STATE" \
+  --arg deploy_id "$DEPLOY_ID" \
+  '{
+    skill: "service-omni-service-channel-configure",
+    status: $status,
+    sobject_type: $sobject,
+    channel_developer_name: $dev_name,
+    channel_id: $channel_id,
+    channel_origin: "canonical_template",
+    target_capacity_model: $cap_model,
+    target_related_entity_type: $sobject,
+    related_entity_verified: $related,
+    before_state: $before_state,
+    deploy_id: $deploy_id,
+    manual_actions: [],
+    blocking_issue: null
+  }'