@salesforce/afv-skills 1.65.1 → 1.66.0

package/skills/service-agentforce-contact-center-coordinate/SKILL.md

@@ -55,7 +55,7 @@ All steps are sequential. If a step fails, stop and report the error rather than
 
 2. **Gather configuration** — use `AskUserQuestion` to collect **Country** (`US`/`CA`) and **Phone Number Type** (`10DLC`/`Toll Free`). Do not mark any option as recommended or default — present the choices neutrally. Wait for both before continuing.
 
-3. **Fetch available numbers** — read `references/number_management_api.md` for the endpoint contract, then run `scripts/fetch-numbers.sh <alias> <country> <phoneType>`. Present the returned numbers as a numbered list and ask the user to select one — do not mark any number as recommended or default.
+3. **Fetch available numbers** — read `references/number_management_api.md` for the endpoint contract. Before fetching, use `AskUserQuestion` to offer an **optional** way to narrow results: ask whether the user wants numbers for a specific **area code** (when the type is `10DLC`) or **prefix** (when the type is `Toll Free`), or to list all available numbers. Present this neutrally with no recommended/default option; leaving it blank (or choosing to list all) preserves the unfiltered fetch. Then run `scripts/fetch-numbers.sh <alias> <country> <phoneType> [searchParam]`, passing the area code / prefix as the optional fourth argument only when the user supplied one. Present the returned numbers as a numbered list and ask the user to select one — do not mark any number as recommended or default. If a narrowed fetch returns no numbers, tell the user and offer to retry with a different area code / prefix or to list all available numbers.
 
 4. **Procure the selected number** — run `scripts/procure-number.sh <alias> <country> <phoneType> <number>`. On a non-2xx response, map the status via `references/number_management_api.md` and stop with a clear message.
 

package/skills/service-agentforce-contact-center-coordinate/references/number_management_api.md

@@ -21,11 +21,18 @@ Query parameters:
 |-------|--------|-------|
 | `countryCode` | `US`, `CA` | |
 | `phoneNumberType` | `10DLC`, `Toll Free` | URL-encode the space in `Toll Free` as `%20` |
+| `searchParam` | area code (`10DLC`) or prefix (`Toll Free`) | **Optional.** Narrows results to numbers matching the area code / prefix. Omit to list all available numbers for the type. Passed through as-is (the API returns `400 BAD_REQUEST` on an invalid value). |
 
 ```bash
+# All available Toll Free numbers for US
 sf api request rest \
   "/services/data/v68.0/connect/number-management/v1/numbers?countryCode=US&phoneNumberType=Toll%20Free" \
   --target-org <alias>
+
+# Optional: narrow 10DLC numbers to a specific area code via searchParam
+sf api request rest \
+  "/services/data/v68.0/connect/number-management/v1/numbers?countryCode=US&phoneNumberType=10DLC&searchParam=415" \
+  --target-org <alias>
 ```
 
 Response:
@@ -42,10 +49,13 @@ Response:
 sf api request rest \
   "/services/data/v68.0/connect/number-management/v1/number" \
   --method POST \
-  --body '{"phoneNumberType":"Toll Free","country":"US","phoneNumber":"+14155551234"}' \
+  --body '{"phoneNumberType":"Toll Free","country":"US","phoneNumber":"+14155551234","contactCenterType":"Agentforce Contact Center"}' \
   --target-org <alias>
 ```
 
+`contactCenterType` is a fixed internal value (`Agentforce Contact Center`) — always sent,
+never gathered from the user.
+
 Success (`201`):
 
 ```json

package/skills/service-agentforce-contact-center-coordinate/scripts/fetch-numbers.sh

@@ -1,8 +1,11 @@
 #!/usr/bin/env bash
 # Fetch available default phone numbers for a country + phone-number type.
-# Usage: fetch-numbers.sh <org-alias> <country> <phone-type>
-#   country:    US | CA
-#   phone-type: 10DLC | "Toll Free"
+# Usage: fetch-numbers.sh <org-alias> <country> <phone-type> [search-param]
+#   country:      US | CA
+#   phone-type:   10DLC | "Toll Free"
+#   search-param: optional — area code (10DLC) or prefix (Toll Free) to narrow
+#                 results. Appended as the API's `searchParam` query param. Omit
+#                 (or pass empty) to list all available numbers for the type.
 # Output: JSON { "phoneNumbers": [...] } on stdout.
 
 set -euo pipefail
@@ -10,12 +13,15 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/lib.sh"
 
 if [[ "${1:-}" == "--help" || $# -lt 3 ]]; then
-  echo "Usage: fetch-numbers.sh <org-alias> <country> <phone-type>" >&2
+  echo "Usage: fetch-numbers.sh <org-alias> <country> <phone-type> [search-param]" >&2
   [[ "${1:-}" == "--help" ]] && exit 0 || exit 2
 fi
 
-ALIAS="$1"; COUNTRY="$2"; PHONE_TYPE="$3"
+ALIAS="$1"; COUNTRY="$2"; PHONE_TYPE="$3"; SEARCH_PARAM="${4:-}"
+
+QUERY="countryCode=${COUNTRY}&phoneNumberType=$(urlenc_spaces "$PHONE_TYPE")"
+[[ -n "$SEARCH_PARAM" ]] && QUERY="${QUERY}&searchParam=$(urlenc "$SEARCH_PARAM")"
 
 sf api request rest \
-  "/${NM_BASE}/numbers?countryCode=${COUNTRY}&phoneNumberType=$(urlenc_spaces "$PHONE_TYPE")" \
+  "/${NM_BASE}/numbers?${QUERY}" \
   --target-org "$ALIAS"

package/skills/service-agentforce-contact-center-coordinate/scripts/lib.sh

@@ -13,6 +13,22 @@ NM_BASE="services/data/${API_VERSION}/connect/number-management/v1"
 # URL-encode a value's spaces (sufficient for country/phoneType query params).
 urlenc_spaces() { printf '%s' "${1// /%20}"; }
 
+# Percent-encode a full value for safe use as a URL query-parameter value: only
+# the RFC 3986 unreserved set stays literal, everything else becomes %XX. Needed
+# for free-text values (e.g. a user-supplied area code / prefix) so reserved
+# characters like & or = can't inject extra query parameters into the request.
+urlenc() {
+  local s="$1" i c out=""
+  for (( i=0; i<${#s}; i++ )); do
+    c="${s:i:1}"
+    case "$c" in
+      [a-zA-Z0-9.~_-]) out+="$c" ;;
+      *) printf -v c '%%%02X' "'$c"; out+="$c" ;;
+    esac
+  done
+  printf '%s' "$out"
+}
+
 # XML-escape a value for safe interpolation into flow-template stringValue/label nodes.
 # Free-text org data (queue names, agent labels) can contain &, <, >, ", ' — unescaped
 # they produce malformed XML and an opaque `sf project deploy start` parse error.

package/skills/service-agentforce-contact-center-coordinate/scripts/procure-number.sh

@@ -14,8 +14,9 @@ fi
 
 ALIAS="$1"; COUNTRY="$2"; PHONE_TYPE="$3"; NUMBER="$4"
 
+# contactCenterType is a fixed internal value, not a user-supplied input.
 BODY=$(jq -n --arg t "$PHONE_TYPE" --arg c "$COUNTRY" --arg p "$NUMBER" \
-  '{phoneNumberType:$t, country:$c, phoneNumber:$p}')
+  '{phoneNumberType:$t, country:$c, phoneNumber:$p, contactCenterType:"Agentforce Contact Center"}')
 
 sf api request rest \
   "/${NM_BASE}/number" \

package/skills/service-concierge-portal-generate/references/portal-deploy-runbook.md

@@ -6,9 +6,9 @@ Help Portal deploys an **Agentforce Concierge experience** on an LWR Experience
 
 The agent script does **not** change here — this is channel/site metadata around the agent.
 
-## Execution model — headless with one operator pause
+## Execution model — Headless first, UI fallback
 
-Every step in §A–§S below is executed headlessly via `sf` CLI + Data API + Metadata API + Tooling API. There is exactly **one** step that requires the operator to click a Setup toggle: enabling the **Agentforce Orchestrator** OrgPerm (see §F.4). When the flow reaches that step, pause, present the operator with a direct Setup URL and clear instructions, and wait for them to reply `done` before continuing. Every other Setup-URL fallback in this document is a *last resort* — attempt the headless path first, and only fall back to UI if the headless path returns an unrecoverable error.
+Every step in §A–§S below is executed headlessly via `sf` CLI + Data API + Metadata API + Tooling API. The Agentforce Orchestrator OrgPerm (§F.4) is enabled via a Connect API POST — no operator UI pause is required. Every Setup-URL fallback in this document is a *last resort* — attempt the headless path first, and only fall back to UI if the headless path returns an unrecoverable error.
 
 If a non-critical step fails (branding polish, suggestion themes, progressive-rendering toggle), log the failure, continue, and surface the gap to the operator at the end. Do NOT abort the deploy for cosmetic gaps.
 
@@ -50,7 +50,7 @@ At the end of the run, print the live customer-facing portal URL for the operato
 > | 4 | Channel + routing + escalation | §E — `sf agent activate` first; if `MESSAGING_CHANNEL_DEV_NAME` not passed in, delegate to `service-digital-engagement-channel-configure` to create the channel (deploy XML with `<sessionHandlerType>AgentforceServiceAgent</sessionHandlerType>` + `<sessionHandlerQueue>` only — `sessionHandlerAsa` is not accepted by the v67 Metadata API); then delegate to `service-agentforce-channel-configure` (Phase 1: queue, Phase 2: Data API PATCH of `SessionHandlerId` + `FallbackQueueId` on the MessagingChannel, Phase 3: escalation question) | SOQL confirms `SessionHandlerId=$BOT_ID`, `FallbackQueueId` set; `BotVersion.Status=Active`; escalation answered by operator |
 > | 6 | Retrieve + edit + deploy bundle | §F.0 — retrieve `DigitalExperienceBundle:site/$BUNDLE_NAME`; **edit `sfdc_cms__brandingSet/*/content.json` with the four colors from §A (§D)**; replace home placeholder with 4 Concierge components (empty `attributes: {}`); add `Conversation__c` route + `conversation` view (§F.0.a); flip `authenticationType`; deploy | Retrieve confirms components + route; branding JSON contains user-specified hex values |
 > | 7 | Wire Concierge runtime binding | §F.3.a–d — create `EmbeddedServiceConfig` via Connect API `POST /connect/embeddedmessaging/deployment/setup` (same as Web Chat §C.4, omit `hostDomain`; auto-generates `ESW_*` site + test page), insert NSSE, **deploy AND assign** guest permset to Site's `GuestUserId` | `/webruntime/api/…/concierge/config` returns `deploymentName + siteUrl + scrtUrl` **AND** `SELECT PermissionSet.Name FROM PermissionSetAssignment WHERE AssigneeId=<GuestUserId>` returns the `<Bundle>_Guest_Concierge` row |
-> | 8 | **⏸ Enable Agentforce Orchestrator (operator pause)** | §F.4 — preflight SOQL on `AgenticCtxtDecorDefinition`; if not supported, pause and ask operator to flip the toggle at the printed Setup URL; wait for `done` reply; then `POST /connect/self-service/setup/agentOrchestrator {name, developerName, agentId}` | Connect GET returns orchestrator with agentId |
+> | 8 | Enable Agentforce Orchestrator + create orchestrator binding | §F.4 — `POST /connect/self-service/setup/agentforceOrchestratorEnablement?includeAgentforceOrchestratorPerms=false` (headless, no operator pause); verify SOQL probe; then `POST /connect/self-service/setup/agentOrchestrator {name, developerName, agentId}` | Connect GET returns orchestrator with agentId |
 > | 9 | Deploy the bundle | §G — `sf project deploy start -m DigitalExperienceBundle:site/$BUNDLE_NAME` | Status: Succeeded |
 > | 10 | Publish the site | §I — `POST /connect/communities/$NETWORK_ID/publish`; PATCH `Network.Status=Live` | Site loads at `PUBLISHED_PORTAL_URL` |
 > | 11 | Network guest flags | §L.0 — PATCH `Network.OptionsGuestChatterEnabled=true AND OptionsGuestMemberVisibility=true` (single Data API call). ALSO verify auth ESC `AreGuestUsersAllowed=true` — flip via mdapi + republish if false. | `/concierge/config?asGuest=true` returns 200; SOQL confirms both Network flags + ESC flag true |
@@ -712,13 +712,13 @@ curl -sS "$PUBLISHED_PORTAL_URL/webruntime/api/services/data/v67.0/connect/self-
 
 All three fields must be non-null. If `deploymentName` is null, the bound ESC references a different site or MessagingChannel — verify the `<site>` in the ESC metadata is the LWR site (F.3.a).
 
-### F.4 — Wire the Agentforce Orchestrator *(one operator pause, then fully headless)*
+### F.4 — Wire the Agentforce Orchestrator *(Headless first, UI fallback)*
 
-The Agentforce Orchestrator provides the personalized greeting, Action/Object recommendations, and Concierge proactive routing. The "Enable Agentforce Orchestrator" OrgPerm gates the agent-binding surfaces (Connect POST, Data API sObject, SOQL). Detect the toggle state with a SOQL write-probe, prompt one manual click if off, then continue fully headless.
+The Agentforce Orchestrator provides the personalized greeting, Action/Object recommendations, and Concierge proactive routing. The "Enable Agentforce Orchestrator" OrgPerm gates the agent-binding surfaces (Connect POST, Data API sObject, SOQL). Enable it headlessly via `POST /connect/self-service/setup/agentforceOrchestratorEnablement`, verify with the SOQL probe, then create the orchestrator binding.
 
 **F.4.0 — Detection preflight.**
 
-Run the probe up to **2 times** before concluding the toggle is off. The `sf` CLI occasionally mixes warning output into stdout on the first call, which causes a false "not supported" parse. Re-running the identical query without waiting resolves the issue — no org state changes between attempts.
+Run the SOQL probe up to **2 times** before concluding the toggle is off. The `sf` CLI occasionally mixes warning output into stdout on the first call causing a false "not supported" parse. Re-running the identical query without waiting resolves the issue — no org state changes between attempts.
 
 ```bash
 TOGGLE_STATE="UNKNOWN"
@@ -735,11 +735,24 @@ done
 ```
 
 - ✅ `TOGGLE_STATE=ON` → proceed with §F.4.2.
-- ❌ `TOGGLE_STATE=OFF` (both attempts) → toggle is genuinely OFF, **pause and prompt the operator**.
+- ❌ `TOGGLE_STATE=OFF` (both attempts) → toggle is genuinely OFF → proceed to §F.4.1 (headless enable).
 
-**F.4.1 — ⏸ OPERATOR PAUSE: enable the Orchestrator OrgPerm.**
+**F.4.1 — Headless enable via Connect API (fully headless — no operator pause).**
 
-If the SOQL probe returned "not supported", send this message verbatim to the operator, then wait for their reply:
+Enable Agentforce Orchestrator headlessly:
+
+> **`min_api_version: 68.0`** — this endpoint is only available on API v68.0+. On v67 orgs the POST returns `NOT_FOUND`; fall through to the UI path below.
+
+```bash
+sf api request rest -o "$ORG" --method POST \
+  "/services/data/v68.0/connect/self-service/setup/agentforceOrchestratorEnablement?includeAgentforceOrchestratorPerms=false" \
+  --body '{}'
+# → {"isSuccess": true}
+```
+
+After the POST, re-run the §F.4.0 SOQL probe to confirm `TOGGLE_STATE=ON`. If the probe still returns "not supported" after a successful POST (can happen on a slow pod), wait 10 seconds and re-probe once more. If the probe is still off after that re-probe, fall back to the UI step below — do not continue to §F.4.2.
+
+If the org **genuinely does not have this surface** (the POST itself returns `NOT_FOUND` or `UNSUPPORTED_OPERATION`), fall through to the legacy UI path as a last resort:
 
 > **One manual step needed.** Please open this URL and enable Agentforce Orchestrator:
 >
@@ -749,7 +762,7 @@ If the SOQL probe returned "not supported", send this message verbatim to the op
 > 2. Wait for the confirmation banner.
 > 3. Reply `done` here and I'll continue.
 
-When the operator replies `done`, re-run the F.4.0 SOQL probe. If it still returns "not supported", either the toggle wasn't flipped or there's an org-shape gap. Ask them to double-check, then re-probe. If the org genuinely does not have this surface (older-API pod), fall through to the F.4 skip: continue the deploy without the Orchestrator, and log the gap in the operator handoff.
+If the org cannot enable this at all, skip §F.4 entirely and log the gap in the operator handoff.
 
 **F.4.2 — Bot prerequisite check.**
 
@@ -1419,7 +1432,7 @@ sf org open --target-org $ORG --path "/<url-path>/"
 | Guest curl to `/webruntime/api/.../connect/self-service/*` returns `HTTP 401 UNAUTHORIZED` | `Network.OptionsGuestChatterEnabled = False` on target | Run §L.0 diagnostic; PATCH to True via Data API — no republish required |
 | Portal loads, `/concierge/config` returns 200, prompt bar renders but says **"Agents are not available. Try again later."** | Bot-routing wiring missing. Typical gaps: `PresenceUserConfigUser`, `GroupMember`, `Group.QueueRoutingConfigId` | Run §N — three Data-API writes |
 | §N writes all succeed but chat *still* shows "Agents are not available" immediately | Automated-Process pickup path needs to spin up after routing wiring changes | Re-activate the BotVersion via CLI (`sf agent deactivate` + `sf agent activate`). Wait a few minutes. Do NOT rely on `UserServicePresence` COUNT as the readiness signal |
-| Prompt bar responses are ungrounded / navigate to `/error` on newer-API orgs | Agentforce Orchestrator not wired | See §F.4 — enable the OrgPerm (operator pause) then `POST /connect/self-service/setup/agentOrchestrator` |
+| Prompt bar responses are ungrounded / navigate to `/error` on newer-API orgs | Agentforce Orchestrator not wired | See §F.4 — `POST /connect/self-service/setup/agentforceOrchestratorEnablement?includeAgentforceOrchestratorPerms=false`, verify SOQL probe, then `POST /connect/self-service/setup/agentOrchestrator` |
 | Agentforce Orchestrator's "Add Tool → Agent" picker is empty | `BotDefinition.AgentTemplate` is `null` — Bot was created via headless Metadata deploy, not the Setup wizard | Delete the Bot and recreate via Setup → Agentforce Agents → New Agent → From Template → Agentforce Service Agent |
 
 ---

package/skills/service-digital-engagement-channel-configure/SKILL.md

@@ -28,9 +28,18 @@ Creates `MessagingChannel` metadata XML for Salesforce Messaging for In-App and
 
 ---
 
+## Entry points and transport
+
+- **Delegated** (`context.calledFrom == "service-onboarding"`): use the approved `values`, ask nothing, and return `failed` naming any missing required key. **Standalone** (no `context`): run Clarifying Questions.
+- **Transport A** (primary): headless-360 MCP `dispatch` / `dispatch_readonly` on `/headless/metadata`. **Transport B**: the `sf` commands below, only where a probe shows Transport A unavailable.
+
+Details: `references/onboarding_contract.md` (§1 entry points, §2 transport, §3 pre-scan, §5 result).
+
+---
+
 ## Clarifying Questions
 
-Before generating, ask the user if not already clear:
+Before generating, ask the user if not already clear (standalone only):
 
 - What is the channel name / label? (used for `masterLabel` and file name)
 - What routing type? (Omni-Channel Flow, Omni-Channel Queue, User, or Agentforce Service Agent)
@@ -80,19 +89,21 @@ All steps are sequential. Do not skip or reorder.
 
 1. **Verify org API version** — run `scripts/check-api-version.sh 67.0 <org-alias>` and report any errors it returns. If the script fails, generate a `sfdx-project.json` in the metadata output folder with `"sourceApiVersion": "67.0"`.
 
-2. **Collect inputs** — confirm the channel label, routing type, routing target, and verification settings from the user per Clarifying Questions above.
+2. **Collect inputs** — standalone: per Clarifying Questions. Delegated: from `values`. Then probe transport with a read-only `GET` of `MessagingChannel` (contract §2).
 
 3. **Determine file name** — run `scripts/normalize-channel-name.sh "<LABEL>"` and surface any errors it returns.
 
-4. **Verify routing target exists** — query the org to confirm the referenced routing target exists:
+3a. **Pre-scan** — `GET` `MessagingChannel` by the step 3 name (contract §3): none → create; matches and active → no write, `already-configured`, skip to Phase 4; matches but inactive → activate only (step 15); differs → announce each change, then write the full document (standalone: ask first).
+
+4. **Verify routing target exists** — skip when step 3a ended in `already-configured` or activate-only, so a re-run never creates a queue. Query the org to confirm the referenced routing target exists:
    - For Queue: `sf data query --query "SELECT Id, DeveloperName FROM Group WHERE Type='Queue' AND DeveloperName='<QUEUE_NAME>'" --target-org <org-alias>`
    - For Flow: `sf data query --query "SELECT Id, ApiName FROM FlowDefinitionView WHERE ApiName='<FLOW_NAME>' AND IsActive=true" --target-org <org-alias>`
    - For User: `sf data query --query "SELECT Id, Username FROM User WHERE Id='<USER_ID>' AND IsActive=true" --target-org <org-alias>`
    - For ASA: `sf data query --query "SELECT Id, DeveloperName FROM BotDefinition WHERE DeveloperName='<BOT_NAME>'" --target-org <org-alias>`
    - Also verify the fallback queue exists (required for Flow, User, and ASA routing)
    
-   If any target is not found, inform the user and ask whether to create it. If the user confirms:
-   - For Queue: generate a `.queue-meta.xml` with `MessagingSession` as the `queueSobject` type and deploy it before the channel. **A new queue is unusable for routing without a `QueueRoutingConfig` — a channel deployed against a queue with none fails at session-start with "Agents are not available. Try again later," even though the channel itself deploys and activates cleanly.** Immediately after the queue deploys, resolve or create its routing config by following `service-agentforce-channel-configure`'s `references/queue-resolution.md` Step 4 — do not defer this to a later skill invocation, since this may be the only place a newly created queue is ever touched.
+   If any target is not found: standalone — inform the user and ask whether to create it. Delegated — return `failed` naming the missing target; never create it. If the standalone user confirms creating:
+   - For Queue: generate a `.queue-meta.xml` with `MessagingSession` as the `queueSobject` type and deploy it before the channel. **A new queue needs a `QueueRoutingConfig`, or sessions fail with "Agents are not available. Try again later" even though the channel deploys and activates.** Right after the queue deploys, resolve or create one per `service-agentforce-channel-configure`'s `references/queue-resolution.md` Step 4 — do not defer it.
    - For Flow/User/ASA: inform the user that the flow, user, or bot must be created separately (out of scope for this skill)
 
 5. **Read the channel settings reference** — load `references/channel_settings.md` to understand all available configuration options and their valid values.
@@ -110,10 +121,7 @@ All steps are sequential. Do not skip or reorder.
    | User | `User` | `sessionHandlerUser` + `sessionHandlerQueue` (fallback) |
    | Agentforce Service Agent | `AgentforceServiceAgent` | `sessionHandlerQueue` (fallback) + `sessionHandlerAsa` (bot dev name — required, see v67 note below) |
 
-   > **v67 note — `<sessionHandlerAsa>` is required in the XML, not rejected.** Confirmed on a v67.0 org: omitting `<sessionHandlerAsa>` causes the deploy to fail with "Missing required Agentforce Service Agent." Include it and the deploy binds `SessionHandlerId` automatically — no post-deploy Data API PATCH needed.
-   > 1. **Verify the bot is Active before channel creation.** The Metadata API rejects binding with "Only active Agentforce Service Agents are supported." Run `sf agent activate -o <org> --api-name <BotDevName>` and confirm `BotVersion.Status = Active` first.
-   > 2. Deploy the XML with `<sessionHandlerType>AgentforceServiceAgent</sessionHandlerType>`, `<sessionHandlerQueue>` (fallback), and `<sessionHandlerAsa>{BotDevName}</sessionHandlerAsa>`.
-   > 3. Verify: `sf data query -o <org> -q "SELECT SessionHandlerId, FallbackQueueId FROM MessagingChannel WHERE DeveloperName='<ChannelDevName>'" --json` — both must be non-null after the deploy, with no separate PATCH step.
+   > **v67 note — `<sessionHandlerAsa>` is required** (omitting it fails with "Missing required Agentforce Service Agent"); the deploy then binds `SessionHandlerId`, no PATCH needed. The bot must be Active first: run `sf agent activate -o <org> --api-name <BotDevName>` and confirm `BotVersion.Status = Active`.
 
 8. **Apply user verification** — if enabled, set `embeddedConfig.authMode` to `Auth` and include `<messagingAuthorizations>`. If not enabled, set `embeddedConfig.authMode` to `UnAuth` and omit `<messagingAuthorizations>`.
 
@@ -142,21 +150,21 @@ All steps are sequential. Do not skip or reorder.
 
 ### Phase 3 — Deploy and Activate
 
-14. **Deploy the channel** — deploy the generated `.messagingChannel-meta.xml` file to the target org:
+14. **Write the channel** — Transport A: `POST` to create, `PUT` the **full** document to update (a minimal PUT drops `embeddedConfig`); check `results[].success`, then re-`GET`. Transport B:
     ```bash
     sf project deploy start --source-dir <path-to-messagingChannels-folder> --target-org <org-alias>
     ```
 
-15a. **ASA routing only — verify the bind landed.** Skip this step for Queue, Flow, and User routing types. Because `<sessionHandlerAsa>` was included in the deployed XML (step 7), the deploy itself binds `SessionHandlerId` — no separate Data API PATCH is needed.
+15a. **ASA routing only — verify the bind landed** (skip for Queue, Flow, User):
 
     ```bash
     sf data query -o <org> --json \
       -q "SELECT SessionHandlerId, FallbackQueueId FROM MessagingChannel WHERE DeveloperName='<CHANNEL_DEV_NAME>'"
     ```
 
-    Both `SessionHandlerId` and `FallbackQueueId` must be non-null. If either is null, confirm `<sessionHandlerAsa>` and `<sessionHandlerQueue>` were both present in the deployed XML and that the bot was Active before the deploy.
+    Both must be non-null; if not, check both handler elements were in the XML and the bot was Active before the deploy.
 
-15. **Activate the channel** — after successful deployment, activate the messaging channel:
+15. **Activate the channel** — after a successful write, activate the messaging channel (`IsActive` is not part of the metadata). Transport A: sObject update `{"IsActive": true}` through `dispatch`. Transport B:
     ```bash
     sf data update record --sobject MessagingChannel --where "DeveloperName='<CHANNEL_NAME>'" --values "IsActive=true" --target-org <org-alias>
     ```
@@ -165,7 +173,9 @@ All steps are sequential. Do not skip or reorder.
 
 16. **Verify against checklist** — confirm all items in the Verification Checklist below pass before presenting output.
 
-17. **Present output** — show the generated file to the user with a summary of configured settings and confirm activation status. Offer next steps:
+17. **Report** — delegated: return the contract §5 result and stop. Standalone: continue.
+
+18. **Present output** (standalone) — show the generated file to the user with a summary of configured settings and confirm activation status. Offer next steps:
     - **Automated responses** — ask if the user wants to configure `<automatedResponses>` (OptOutConfirmation, HelpResponse). If yes, generate elements with `autoResponseContentType: TextResponse`, `language`, and XML-escaped `response` text, then redeploy.
 
 ---
@@ -278,6 +288,7 @@ File structure follows the template in `assets/messaging_channel_template.xml`.
 
 | File | When to read |
 |------|-------------|
+| `references/onboarding_contract.md` | Delegated mode (`context.calledFrom == "service-onboarding"`), org writes (transport), module registration |
 | `assets/messaging_channel_template.xml` | Before generating — use as the starting structure |
 | `references/channel_settings.md` | When configuring channel options beyond defaults |
 | `scripts/check-api-version.sh` | Phase 1 — verify org API version meets the passed minimum (67.0) |

package/skills/service-digital-engagement-channel-configure/references/onboarding_contract.md

@@ -0,0 +1,143 @@
+# Onboarding contract — delegated mode, transport, pre-scan, registration
+
+Read this when the invocation carries a `context` object, before any org write, or when registering the skill in an
+onboarding module. It implements the Feature Setup Skill Guidelines (Conversational Onboarding, Service Cloud) for
+this skill. The sibling `service-digital-engagement-deployment-configure` has the same structure.
+
+## 1. Two entry points, one write procedure
+
+| | Delegated | Standalone |
+|---|---|---|
+| Detected by | `context.calledFrom == "service-onboarding"` | no `context` object |
+| Values come from | `values` in the payload — already approved in the plan table | you ask, using the defaults in SKILL.md |
+| Questions | none. A missing required key is a caller bug: stop and return `failed` naming the key. Never default a value the admin did not approve | the Clarifying Questions in SKILL.md |
+| Wording | `discoveryMode == "guided"` → plain business language (§4). `"pickAreas"` → Salesforce terminology | Salesforce terminology (the Clarifying Questions as written) |
+| Ends with | the structured result in section 5 | a plain-language summary of the same outcome |
+
+Delegated payload:
+
+```json
+{
+  "values": {
+    "channelLabel": "Acme Support Chat",
+    "routingType": "Queue",
+    "routingTarget": "Support_Queue",
+    "fallbackQueue": null,
+    "userVerification": true
+  },
+  "context": { "calledFrom": "service-onboarding", "discoveryMode": "guided" }
+}
+```
+
+Required `values`: `channelLabel`, `routingType`, `routingTarget`; `fallbackQueue` is required when `routingType` is
+`Flow`, `User` or `AgentforceServiceAgent`. `userVerification` defaults to `true`, matching SKILL.md. Every other
+channel setting uses the SKILL.md defaults unless a key is supplied.
+
+Missing routing target, delegated: return `failed`, `errorMessage` = "<Flow|User|Bot|Queue> <name> not found". Never
+create one — queues come from the `queues` feature this one depends on.
+
+## 2. Transport — `/headless/metadata` first, `sf` CLI as fallback
+
+**Transport A (primary): the headless-360 MCP `dispatch` / `dispatch_readonly` tools** against the synchronous
+Metadata-CRUD route, fully-qualified: `/services/data/vXX.0/headless/metadata/<Type>?type=<Type>&fullName=<Name>`.
+
+- `GET` = read (`dispatch_readonly`) → `{type, fullName, xmlRep}`. `POST` = create-only; re-POSTing an existing
+  `fullName` returns `DUPLICATE_VALUE`. `PUT` = update. On writes the body must carry `type`, `fullName` **and** `xmlRep`.
+- Response is synchronous: `{results:[{success, errors[], ...}]}`. HTTP 200 can still be a failure — inner `success` wins.
+- **Create once, then update.** Never re-run `POST` for a later change.
+- **A minimal PUT silently drops inline blocks.** On `MessagingChannel`, a PUT that omitted `embeddedConfig` cleared
+  it while `automatedResponses` and `messagingKeywords` survived. Always GET → modify → PUT the **full** document.
+  Re-GET after the PUT and diff.
+- Activation is not metadata: `IsActive` is absent from the `MessagingChannel` representation. Activate with an
+  sObject update (`{"IsActive": true}`) through `dispatch`, or `sf data update record` on Transport B.
+- Use the same `dispatch` tool for the probe and the write. `sf api request rest` / `curl` carry the `sf` CLI's separate
+  credential, which can be expired while the MCP token is valid — a REST URL called through the CLI is **not** Transport A.
+- Metadata references Flow/Queue by **API name** (`sessionHandlerFlow`, `sessionHandlerQueue`), not by runtime Id.
+
+**Probe per type, per operation — never infer from another type.** Run a read-only `GET` for each type you are about
+to touch (`MessagingChannel`; and `Queue` if you must create one).
+
+| Probe result | Meaning | Action |
+|---|---|---|
+| `xmlRep` returned, or "Metadata not found" style error | type is onboarded | Transport A |
+| `UNSUPPORTED_OPERATION` for the type or verb | not onboarded for that verb | Transport B for that call only |
+| auth / connection error | MCP unavailable | Transport B; say so |
+
+**Transport B (fallback): `sf` CLI** — `sf project deploy start` and `sf data query` / `sf data update record` as in
+SKILL.md. Use only when the probe says Transport A is unavailable for that type/verb.
+
+Routing-target existence checks (Queue, Flow, User, Bot) are SOQL: `dispatch_readonly` on the REST query endpoint first; `sf data query` only if that call returns a path/route error.
+
+## 3. Pre-scan (idempotency)
+
+Run before any write, both modes. `GET` `MessagingChannel` by `fullName` = the normalized channel name.
+
+| Finding | Outcome |
+|---|---|
+| No such channel | not set up → create (`POST`) |
+| Exists, and every targeted setting equals the target (routing type and target, fallback queue, `authMode`, plus each supplied key) **and** `IsActive = true` | **already configured** — no write, return `already-configured` |
+| Exists, matches, but `IsActive = false` | only activate; do not rewrite the metadata |
+| Exists, some targeted setting differs | **drift** — announce each change ("routing: Queue A → Queue B"), then write the full document. Standalone: ask for a yes first. Delegated: the plan approval covers it |
+| Exists but was created by Connect `channel/setup` (defaults populated: opt-out/help keywords, `embeddedConfig`) | you now own the whole document: GET, modify only targeted fields, PUT the full result |
+
+Standalone, channel exists: offer exactly three choices — no change / override / add to existing.
+
+## 4. Questions in the admin's language (guided mode)
+
+Ask about the outcome; state the default with each; keep it to a handful.
+
+| Instead of | Ask |
+|---|---|
+| "Routing type: Queue, Flow, User or Agentforce Service Agent?" | "When a customer starts a chat, who should get it first: a team (queue), a specific person, or your AI agent? (Default: a team.)" |
+| "Fallback queue developer name?" | "If that person or agent isn't available, which team should the chat go to?" |
+| "Enable User Verification (JWT)?" | "Will customers be signed in to your site when they chat, so you know who they are? (Default: yes.)" Yes → Auth mode; setting up the signing keys is a separate step |
+| "Pre-chat form / custom parameters" | "What should we ask customers before the chat starts? (Default: name and email.)" |
+| "`isAbandonedChatsEnabled`, `chatAbandonmentTimeout`…" | Not asked; use the SKILL.md defaults |
+
+## 5. Result returned to the coordinator
+
+```json
+{
+  "status": "success | already-configured | failed",
+  "errorMessage": "<empty unless failed>",
+  "outputs": {
+    "channelName": "Acme_Support_Chat",
+    "messagingChannelId": "<id or null>",
+    "isActive": true
+  }
+}
+```
+
+`status` and `errorMessage` are the contract. `outputs` is always returned; it is an addition to the documented shape.
+On `failed`: `errorMessage` names the failed step and the platform error; stop; do not retry.
+
+## 6. Registration entry (draft for the onboarding team to place in a module)
+
+```yaml
+- id: messagingChannel
+  title: "Customer messaging channel"
+  description: "Create and switch on the channel that receives customer chats from your website or app, and decide who answers first (a team, a person, or an AI agent)."
+  delegateSkill: service-digital-engagement-channel-configure
+  dependsOn: [queues]
+  revisionOwner: service-digital-engagement-channel-configure
+  # org perms: confirm exact names with Digital Engagement licensing (not yet confirmed)
+  values:
+    channelLabel:     { from: signal.messagingChannelName, default: "<company> Support Chat" }
+    routingType:      { from: signal.messagingRouting,     default: "Queue" }
+    routingTarget:    { from: signal.messagingRoutingTarget }
+    fallbackQueue:    { from: signal.messagingFallbackQueue }
+    userVerification: { from: signal.messagingSignedIn,    default: true }
+  writes: "MessagingChannel (Metadata CRUD); IsActive via sObject update"
+  gating:
+    irreversible: false
+    note: "Reversible by deactivating the channel. Pre-chat form fields can be deactivated but the form cannot be fully deleted; removing a channel custom parameter needs the form field removed and the deployment republished first."
+  validate:
+    check: check-messaging-channel
+    passWhen: "GET MessagingChannel fullName=<normalized name> returns the targeted sessionHandlerType and target and the intended authMode; SOQL SELECT IsActive, SessionHandlerId, FallbackQueueId FROM MessagingChannel WHERE DeveloperName=<name> returns IsActive=true, and non-null SessionHandlerId/FallbackQueueId where the routing type requires them"
+  alternative: "Setup > Messaging Settings > New Channel > Messaging for In-App and Web; choose routing, then activate."
+```
+
+Open items for the onboarding team: the `signal.*` keys do not exist in `onboarding-state.schema.json` yet
+(`channels` allows only email/web); `userVerification: true` makes an Auth channel, which also needs the
+user-verification step before signed-in customers can chat — decide if that is its own feature; the coordinator must
+accept `outputs`; org perm names are not yet confirmed.