@salesforce/afv-skills 1.65.0 → 1.66.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.

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

@@ -23,13 +23,30 @@ Configures `EmbeddedServiceConfig` metadata for Salesforce Messaging for In-App
 ## Scope
 
 - **In scope**: Creating new Embedded Service Deployments (API, Mobile, Web types) via Connect API; updating existing deployments with forms, branding, channel settings, and features via Metadata API; generating `EmbeddedServiceConfig` XML for updates
-- **Out of scope**: Creating the messaging channel itself (use `service-digital-engagement-channel-configure`), publishing deployments (Connect API post-step), creating Experience Sites (Connect API prerequisite for Web type)
+- **Out of scope**: Creating the messaging channel itself (use `service-digital-engagement-channel-configure`), generating the website code snippet (offered only as a next step, see `references/code_snippet.md`), creating Experience Sites (Connect API prerequisite for Web type)
+
+---
+
+## Entry points: delegated or standalone
+
+Decide this before asking anything.
+
+- **Delegated** — the invocation carries `{ values, context }` with `context.calledFrom == "service-onboarding"`. The admin already approved `values` in the onboarding plan. Ask nothing; skip Clarifying Questions. If a required key is missing, stop and return `failed` naming it — do not guess.
+- **Standalone** — no `context`. Run Clarifying Questions as written.
+
+Both paths run the same pre-scan, write and validate steps. Full contract (payload, wording rules, result shape, registration entry): `references/onboarding_contract.md`.
+
+---
+
+## Transport
+
+Org reads and writes go through the **headless-360 MCP `dispatch` / `dispatch_readonly`** tools on `/services/data/vXX.0/headless/metadata` (**Transport A, primary**). Use the **`sf` CLI** (**Transport B**) only for a type/verb that a read-only probe shows is not onboarded, or when the MCP is unavailable. Probe each type separately — never infer onboarding from a different type. Details, the GET → modify → full-document PUT rule, and the credential trap are in `references/onboarding_contract.md` §2. The `sf` commands in the steps below are the Transport B form. Exception: Web create always uses the `sf` CLI (step 17a).
 
 ---
 
 ## Clarifying Questions
 
-Before generating, ask the user if not already clear:
+Before generating, ask the user if not already clear (standalone only):
 
 - **Create or update?** Are you creating a new deployment or updating an existing one?
 - **Deployment type?** API (headless), Mobile (native apps), or Web (browser widget)?
@@ -46,7 +63,7 @@ Gather or infer before proceeding:
 
 - **Operation**: `create` or `update`
 - **Deployment type**: `API`, `Mobile`, or `Web`
-- **Deployment name**: Used for `masterLabel` and the API name
+- **Deployment name**: Used as `masterLabel`. Derive the API name (`fullName` / `DeveloperName`, Connect `name`) from it: replace each run of characters other than letters and digits with `_`, then trim leading/trailing `_` (`Acme Support Chat` → `Acme_Support_Chat`). The result must match `^[a-zA-Z][a-zA-Z0-9_]*$`. Use the API name for every lookup and write
 - **Channel name**: The `channelPlatformKey` of the associated messaging channel
 
 For **update** operations additionally:
@@ -69,12 +86,22 @@ All steps are sequential. Do not skip or reorder. Branch based on the operation
 
 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. **Determine operation** — ask whether the user wants to create a new deployment or update an existing one.
+2. **Determine operation** — standalone: ask whether the user wants to create a new deployment or update an existing one. Delegated: taken from `values.operation`, then confirmed by the pre-scan (step 4a).
 
-3. **Collect inputs** — gather deployment name, type, and channel name per Clarifying Questions above.
+3. **Collect inputs** — standalone: gather deployment name, type, and channel name per Clarifying Questions above. Delegated: bind them from `values`; stop with `failed` if `deploymentName`, `deploymentType` or `channelName` is missing.
+
+3a. **Probe transport** — read-only `GET` of `EmbeddedServiceConfig` via `dispatch_readonly`. Onboarded → Transport A. `UNSUPPORTED_OPERATION` or MCP unavailable → Transport B for that call. See `references/onboarding_contract.md` §2.
 
 4. **Read deployment settings reference** — load `references/deployment_settings.md` to understand all available configuration options.
 
+4a. **Pre-scan** — using the step 3a read, look for a deployment whose API name is the one derived from `deploymentName` (Required Inputs):
+   - none → operation is `create` (Phase 2A)
+   - exists and every targeted field already matches → **make no write**; return `already-configured` (delegated) or say so plainly (standalone). Skip to Phase 3
+   - exists with differences → operation is `update` (Phase 2B); announce each change, then write (standalone: ask for a yes first)
+   - exists but linked to a different channel → standalone: ask before repointing; delegated: return `failed`
+
+   Standalone with an existing deployment: offer no change / override / add to existing.
+
 ### Phase 2A — Create New Deployment
 
 Use this path when the operation is `create`.
@@ -99,11 +126,11 @@ Use this path when the operation is `create`.
 9. **Present output and next steps** — show the generated file and summarize what was configured. Recommend as next steps:
    - **Publish** the deployment via Connect API to make it live:
      ```bash
-     sf api request rest "/services/data/v67.0/connect/embeddedservice/embeddedserviceconfig/publish/<EMBEDDED_SERVICE_CONFIG_ID>" -X POST -o <org-alias>
+     sf api request rest "/services/data/v67.0/connect/embeddedservice/embeddedserviceconfig/publish/<EMBEDDED_SERVICE_CONFIG_ID>" -X POST -b '{}' -o <org-alias>
      ```
      To obtain the `EMBEDDED_SERVICE_CONFIG_ID`:
      ```bash
-     sf data query --query "SELECT Id FROM EmbeddedServiceConfig WHERE DeveloperName = '<DEPLOYMENT_NAME>'" --target-org <org-alias>
+     sf data query --use-tooling-api --query "SELECT Id FROM EmbeddedServiceConfig WHERE DeveloperName = '<DEPLOYMENT_NAME>'" --target-org <org-alias>
      ```
    - **Generate code snippet** for integration — see `references/code_snippet.md`
 
@@ -111,11 +138,11 @@ Use this path when the operation is `create`.
 
 Use this path when the operation is `update`.
 
-10. **Retrieve the existing deployment** — retrieve the current `EmbeddedServiceConfig` metadata from the org before making changes:
+10. **Retrieve the existing deployment** — take the current `EmbeddedServiceConfig` from the org before making changes. Transport A: the `xmlRep` from the step 3a/4a `GET`. Transport B:
     ```bash
     sf project retrieve start --metadata EmbeddedServiceConfig:<DEPLOYMENT_NAME> --target-org <org-alias>
     ```
-    Use the retrieved file as the starting structure. If retrieval is not possible, load `assets/esd_web_update_template.xml` as a fallback reference.
+    Use it as the starting structure — the update is always a **full document**, never a minimal payload (omitted inline blocks can be silently cleared). If retrieval is not possible, load `assets/esd_web_update_template.xml` as a fallback reference.
 
 11. **Apply messaging channel settings** — configure `<embeddedServiceMessagingChannel>` with:
     - `messagingChannel` — the channel's `channelPlatformKey`
@@ -146,18 +173,34 @@ Use this path when the operation is `update`.
 17. **Present output and next steps** — show the generated file and summarize what was configured. Recommend as next steps:
     - **Publish** the deployment via Connect API to make changes live:
       ```bash
-      sf api request rest "/services/data/v67.0/connect/embeddedservice/embeddedserviceconfig/publish/<EMBEDDED_SERVICE_CONFIG_ID>" -X POST -o <org-alias>
+      sf api request rest "/services/data/v67.0/connect/embeddedservice/embeddedserviceconfig/publish/<EMBEDDED_SERVICE_CONFIG_ID>" -X POST -b '{}' -o <org-alias>
       ```
       To obtain the `EMBEDDED_SERVICE_CONFIG_ID`:
       ```bash
-      sf data query --query "SELECT Id FROM EmbeddedServiceConfig WHERE DeveloperName = '<DEPLOYMENT_NAME>'" --target-org <org-alias>
+      sf data query --use-tooling-api --query "SELECT Id FROM EmbeddedServiceConfig WHERE DeveloperName = '<DEPLOYMENT_NAME>'" --target-org <org-alias>
       ```
     - **Generate code snippet** for integration — see `references/code_snippet.md`
 
+### Phase 2C — Apply to the org
+
+Runs for both Phase 2A and 2B, except when the pre-scan returned `already-configured`. Standalone: confirm before writing. Delegated: the plan approval is the confirmation; still announce each write.
+
+17a. **Write the deployment** —
+    - Web create: Connect API (see `references/connect_api_creation.md`) via `sf api request rest` — always, not `dispatch` (MCP `dispatch` fails with `INTERNAL_ERROR` during site creation).
+    - API/Mobile create: Transport A `POST` `EmbeddedServiceConfig` (body carries `type`, `fullName`, `xmlRep`); Transport B `sf project deploy start`.
+    - Update: Transport A `PUT` of the **full** document; Transport B `sf project deploy start`.
+    Check `results[].success`, not just HTTP status. On failure stop and report the step — no silent retry.
+
+17b. **Re-read and diff** — `GET` the component again and confirm every intended field landed and no inline block (`embeddedServiceMessagingChannel`, forms) was dropped.
+
+17c. **Publish (Web only, only if something was written)** — `dispatch` `POST` on the fully-qualified publish path; if it returns a path/route error, run the `sf` publish command from the next-steps block above. Skip after a Web create alone when the create response has `isPublishSuccess: true` — the create already published.
+
 ### Phase 3 — Validate
 
 18. **Verify against checklist** — confirm all items in the Verification Checklist below pass.
 
+19. **Report** — delegated: return `{ "status": "success" | "already-configured" | "failed", "errorMessage": "...", "outputs": { ... } }` (shape in `references/onboarding_contract.md` §5). Standalone: the same outcome in plain language.
+
 ---
 
 ## Rules / Constraints
@@ -174,7 +217,9 @@ Use this path when the operation is `update`.
 | Pre-chat form fields must reference valid channel custom parameters | ChoiceList fields need the parameter deployed on the channel first |
 | File extension is `.EmbeddedServiceConfig-meta.xml` | Metadata API uses this specific extension |
 | Do not hardcode file paths — respect `sfdx-project.json` package directories | Customer orgs customize source paths |
-| Never include deploy/push commands in generated output | This skill produces artifacts only |
+| Do not embed deploy/push commands inside generated files or artifacts | Artifacts stay portable; in-session writes happen in Phase 2C through the chosen transport |
+| Update with the full retrieved document, never a minimal PUT | Omitted inline blocks can be silently cleared by the update |
+| Pre-scan before every write; no write when the org already matches | Makes re-runs idempotent and keeps "already configured" honest |
 | Publish step (Connect API) required after Web ESD updates | Changes are not live until published |
 
 ---
@@ -188,6 +233,9 @@ Use this path when the operation is `update`.
 | Branding overrides not applied | Use Tooling API to update individual BrandingSet properties after the deployment is created |
 | Pre-chat ChoiceList not showing | ChoiceList requires two-step deploy: create ChoiceList first, then assign to form field |
 | Changes not appearing in widget | Web ESDs must be published via Connect API after any update |
+| `sf api request rest` POST fails with "No 'mode' found in 'body' entry" | The CLI rejects a POST with no body (and `-b ""`). Pass `-b '{}'` — the publish endpoint takes no input |
+| `sf api request rest` fails with "Nonexistent flag: --url" | The URL is a positional argument, not a flag, and must be fully qualified (`/services/data/vXX.0/connect/...`) |
+| Web create via MCP `dispatch` returns `INTERNAL_ERROR` | Platform limitation of the MCP route during site creation — use `sf api request rest` for Web create. API/Mobile create and publish work via `dispatch` |
 | `embeddedServiceFlowConfig.enabled` error | Set to `false` unless you specifically need embedded flows (not routing flows) |
 | reCAPTCHA configuration rejected | reCAPTCHA is `@HideInWsdl` — must use Tooling API |
 | Business hours not taking effect | Only updating existing business hours works; creation is managed separately |
@@ -246,6 +294,7 @@ File structure follows the templates in `assets/`.
 
 | File | When to read |
 |------|-------------|
+| `references/onboarding_contract.md` | Delegated mode (`context.calledFrom == "service-onboarding"`), org writes (transport), module registration |
 | `assets/esd_api_mobile_template.xml` | Before generating API or Mobile type deployments |
 | `assets/esd_web_update_template.xml` | Before generating Web type updates |
 | `references/deployment_settings.md` | When configuring deployment options beyond defaults |

package/skills/service-digital-engagement-deployment-configure/references/connect_api_creation.md

@@ -15,9 +15,11 @@ Web-type Embedded Service Deployments cannot be created via Metadata API due to
 ## Connect API Endpoint
 
 ```text
-POST /connect/embeddedmessaging/deployment/setup
+POST /services/data/vXX.0/connect/embeddedmessaging/deployment/setup
 ```
 
+Always use the fully-qualified path (minimum `v67.0`). A bare `/connect/...` path is not routed.
+
 ### Request Body (Web)
 
 ```json
@@ -55,10 +57,13 @@ POST /connect/embeddedmessaging/deployment/setup
 
 ### Using Salesforce CLI (Web)
 
+Always create Web deployments with the CLI. The same call through the headless-360 MCP `dispatch` fails with an
+`INTERNAL_ERROR` server error during site creation.
+
 ```bash
 sf api request rest \
+  "/services/data/v67.0/connect/embeddedmessaging/deployment/setup" \
   --method POST \
-  --url "/connect/embeddedmessaging/deployment/setup" \
   --body '{"name":"<NAME>","masterLabel":"<LABEL>","deploymentType":"Web","clientVersion":"WebV2","hostDomain":"<DOMAIN>","messagingChannelId":"<CHANNEL_ID>"}' \
   --target-org <org-alias>
 ```
@@ -67,8 +72,8 @@ sf api request rest \
 
 ```bash
 sf api request rest \
+  "/services/data/v67.0/connect/embeddedmessaging/deployment/setup" \
   --method POST \
-  --url "/connect/embeddedmessaging/deployment/setup" \
   --body '{"name":"<NAME>","masterLabel":"<LABEL>","deploymentType":"API","messagingChannelId":"<CHANNEL_ID>"}' \
   --target-org <org-alias>
 ```
@@ -123,16 +128,20 @@ After creating the Web ESD via Connect API:
 After any update to a Web ESD (branding, forms, labels, settings), publish to make changes live:
 
 ```text
-POST /connect/embeddedservice/embeddedserviceconfig/publish/<EMBEDDED_SERVICE_CONFIG_ID>
+POST /services/data/vXX.0/connect/embeddedservice/embeddedserviceconfig/publish/<EMBEDDED_SERVICE_CONFIG_ID>
 ```
 
 ```bash
 sf api request rest \
-  /services/data/v67.0/connect/embeddedservice/embeddedserviceconfig/publish/<EMBEDDED_SERVICE_CONFIG_ID> \
+  "/services/data/v67.0/connect/embeddedservice/embeddedserviceconfig/publish/<EMBEDDED_SERVICE_CONFIG_ID>" \
   --method POST \
+  --body '{}' \
   --target-org <org-alias>
 ```
 
+The `--body '{}'` is required: a POST with no body (or `--body ""`) fails in the CLI with
+"No 'mode' found in 'body' entry" before any request is sent.
+
 ---
 
 ## Known Limitations

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

@@ -0,0 +1,146 @@
+# Onboarding contract — delegated mode, transport, pre-scan, registration
+
+Read this when the invocation carries a `context` object, when you are about to write to the org, or when the
+skill is being registered in an onboarding module. It implements the Feature Setup Skill Guidelines (Conversational
+Onboarding, Service Cloud) for this skill.
+
+## 1. Two entry points, one write procedure
+
+| | Delegated | Standalone |
+|---|---|---|
+| Detected by | invocation has `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 report `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 |
+
+Both paths converge on the same pre-scan → write → validate procedure. The only difference is where values come from.
+
+Delegated payload:
+
+```json
+{
+  "values": {
+    "operation": "create",
+    "deploymentType": "Web",
+    "deploymentName": "Acme Support Chat",
+    "channelName": "Acme_Support_Channel",
+    "siteName": "ESW_AcmeSupport_1700000000000"
+  },
+  "context": { "calledFrom": "service-onboarding", "discoveryMode": "guided" }
+}
+```
+
+Required `values`: `deploymentName`, `deploymentType`, `channelName`. `deploymentName` is the label; the API name is
+derived from it (SKILL.md Required Inputs: `Acme Support Chat` → `Acme_Support_Chat`). `operation` defaults to `create` when the pre-scan
+finds nothing and `update` when it finds a deployment. `siteName` is required for Web updates. Optional feature keys
+(pre-chat fields, business hours, T&C, branding) are applied only when present — do not invent them.
+
+## 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 (duplicate → `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.
+- **PUT is not a safe merge for `EmbeddedServiceConfig`.** Child collections survive an omitted block but inline
+  complex blocks can be silently cleared. Always GET → modify → PUT the **full** document. Never PUT a minimal payload.
+  Re-GET after the PUT and diff, so a dropped block is caught here and not in the widget.
+- Use the same `dispatch` tool for the probe and for 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.
+
+**Probe per type, per operation — do not infer from another type.** Before the first write run a read-only
+`GET` for `EmbeddedServiceConfig` (and for any other type you are about to touch).
+
+| 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** — the retrieve/deploy commands already in SKILL.md. Use it only when the probe
+says Transport A is unavailable for that type/verb, never as a convenience.
+
+What is not a transport choice:
+- **Web deployment creation is a Connect API call — send it with `sf api request rest`, not `dispatch`.** Through
+  `dispatch` it always fails with an `INTERNAL_ERROR` server error while building the ESW site; the same body via the CLI
+  succeeds. Do not try `dispatch` first.
+- **Publish is a Connect API call.** Send it with `dispatch` on the fully-qualified path. If `dispatch` returns a
+  path/route error (not a business error), repeat that one call with `sf api request rest`.
+- **Tooling API** work (custom labels, branding, reCAPTCHA) is not verified through `dispatch`. Use `sf` CLI.
+
+## 3. Pre-scan (idempotency)
+
+Run before any write, both modes. Read `EmbeddedServiceConfig` by `fullName` = the API name derived from `deploymentName` (Transport A GET).
+
+| Finding | Outcome |
+|---|---|
+| No such deployment | not set up → create path |
+| Exists, and every targeted field already equals the target (channel link, `isEnabled`, type, and each optional feature supplied) | **already configured** — make no write, return `already-configured` |
+| Exists, some targeted field differs | **drift** — announce each change ("pre-chat form: on → off"), then write. Standalone: ask for a yes first. Delegated: the plan approval covers it |
+| Exists but links a different channel than `channelName` | Standalone: ask before repointing. Delegated: return `failed`, `errorMessage` = "deployment <name> already uses channel <other>" |
+
+Standalone, deployment exists: offer exactly three choices — no change / override / add to existing.
+
+The metadata read does not say whether the latest edits are **published**. After any write to a Web deployment,
+publish. If nothing was written, do not publish.
+
+## 4. Questions in the admin's language (guided mode)
+
+Ask about the outcome, not the Salesforce feature. Keep it to a handful; state the default with each.
+
+| Instead of | Ask |
+|---|---|
+| "Which deployment type: API, Mobile or Web?" | "Where will customers chat with you — on your website, in a mobile app, or through your own custom app?" (website=Web, mobile app=Mobile, custom=API) |
+| "Associate which `channelPlatformKey`?" | Not asked. Delegated: comes from the channel step. Standalone: "Which messaging channel should this chat use?" listing existing ones |
+| "Enable pre-chat form fields?" | "Do you want to ask customers for their name and email before the chat starts? (Default: yes — name and email.)" |
+| "Enable `isTermsAndConditionsEnabled`?" | "Do customers need to accept terms before chatting? (Default: no.)" |
+| "Business hours record?" | "Should the chat only be offered during your business hours? (Default: no.)" |
+| "Chat invitation conditions" | Skip in guided mode unless the admin raises it. It is a pickAreas/expert option |
+
+## 5. Result returned to the coordinator
+
+```json
+{
+  "status": "success | already-configured | failed",
+  "errorMessage": "<empty unless failed>",
+  "outputs": {
+    "deploymentName": "Acme_Support_Chat",
+    "embeddedServiceConfigId": "<id or null>",
+    "published": 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: messagingDeployment
+  title: "Chat widget for your website or app"
+  description: "Create the chat widget (embedded messaging deployment) that customers use to start a messaging conversation: where it appears, what it asks before chat starts, and publishing it live."
+  delegateSkill: service-digital-engagement-deployment-configure
+  dependsOn: [messagingChannel]
+  revisionOwner: service-digital-engagement-deployment-configure
+  # org perms: confirm exact names with Digital Engagement licensing (not yet confirmed)
+  values:
+    deploymentType:  { from: signal.messagingSurface,   default: "Web" }
+    deploymentName:  { from: signal.messagingWidgetName, default: "<company> Support Chat" }
+    channelName:     { from: outputs.messagingChannel.channelName }
+  writes: "EmbeddedServiceConfig (Metadata CRUD); Web create via Connect API embeddedmessaging/deployment/setup (sf CLI); publish via Connect API; optional BrandingSet / custom labels via Tooling API"
+  gating:
+    irreversible: false
+    note: "Reversible by disabling the deployment (isEnabled=false). Pre-chat form fields can be deactivated but the form cannot be fully deleted."
+  validate:
+    check: check-messaging-deployment
+    passWhen: "GET EmbeddedServiceConfig fullName=<derived API name> returns isEnabled=true and the embeddedServiceMessagingChannel links values.channelName; for Web, the deployment has been published"
+  alternative: "Setup > Embedded Service Deployments > New Deployment > Messaging for In-App and Web; choose the channel, set pre-chat, then Publish."
+```
+
+Open items for the onboarding team: the `signal.*` keys do not exist in `onboarding-state.schema.json` yet
+(`channels` allows only email/web); the coordinator must accept `outputs` and pass `outputs.messagingChannel.channelName`
+to this skill; org perm names are not yet confirmed.

package/skills/service-itsm-agentic-setup-incident-management/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: service-itsm-agentic-setup-incident-management
-description: "Orchestrator for Incident Management setup in Service Cloud ITSM: presents the features, tracks progress, and configures each — SLA & Milestones, Priority Matrix, Incident preferences, Major Incident Management, Incident persona PSG assignment, Service Management Privilege, and Incident audit tracking. Use for: set up or configure incident management, incident management walkthrough, what incident features can I configure; the incident preference toggles (default field validations, auto-close child incidents, auto-triage, assign with Einstein, restrict assigned group, rich text descriptions); Major Incident Management (approval group + MIM preferences); assigning the Incident Fulfiller or Incident Manager persona PSG; Service Management Privilege / privilege escalation setup. DO NOT TRIGGER for: the master on/off switch (service-itsm-incident-mgmt-configure), the Priority Matrix, SLA, or field history tracking alone, the Major Incident Manager PSG, creating/editing PSGs, or Problem/Change/Case Management."
+description: "Orchestrator for Incident Management setup in Service Cloud ITSM: presents the features, tracks progress, and configures each — SLA & Milestones, Priority Matrix, Incident preferences, Major Incident Management, Incident persona PSG assignment, Service Management Privilege, and Incident audit tracking. Use for: set up or configure incident management, incident management walkthrough, what incident features can I configure; the incident preference toggles (default field validations, auto-close child incidents, auto-triage, assign with Einstein, restrict assigned group, rich text descriptions); Major Incident Management (approval group + MIM preferences); assigning the Incident Fulfiller or Incident Manager persona PSG; Service Management Privilege / privilege escalation setup. DO NOT TRIGGER for: the master on/off switch alone (use the IncidentMgmt SOR), the Priority Matrix, SLA, or field history tracking alone, the Major Incident Manager PSG, creating/editing PSGs, or Problem/Change/Case Management."
 metadata:
   version: "2.1"
   domains: ["Service"]
@@ -10,7 +10,6 @@ metadata:
     - "service-itsm-agentic-setup-cmdb-access-assign"
     - "service-itsm-agentic-setup-incident-sla-configure"
     - "service-itsm-agentic-setup-itsm-agentforce-permset-assign"
-    - "service-itsm-incident-mgmt-configure"
     - "service-itsm-incident-priority-configure"
   mcpTools:
     headless-360:
@@ -52,7 +51,7 @@ until the user is done.
 
 **Delegated** features hand off to their child skill or SOR. A child skill runs its own confirmations and
 read-backs, so this skill only coordinates. A SOR is a recipe, not an agent: for a SOR hand-off this skill
-runs the SOR's steps itself and owns the confirmation and read-back (see Audit Tracking below).
+runs the SOR's steps itself and owns the confirmation and read-back (see the master switch and Audit Tracking below).
 **Inline** features are run by this skill directly through the `headless-360` MCP server — **read the
 matching reference file before executing that feature** and follow it. Every inline operation is fetched at
 runtime: `discover` by intent, `describe` for the current route/schema/labels, then `dispatch_readonly`
@@ -105,10 +104,21 @@ and business context that informs which features are relevant.
 ### 2. Ensure the Incident Management master switch is on (prerequisite)
 
 Every feature below depends on the org-level `service-cloud-itsm-incident` master switch being enabled.
-Before showing the menu, delegate to `service-itsm-incident-mgmt-configure` to read current state; if on,
-it is a no-op — otherwise it confirms with the user before flipping it. **Skip only when the master switch
-was already confirmed *enabled* in this session** (see step 0). A cached "off"/unknown state MUST fall
-through to the delegation.
+Before showing the menu, `discover` the `IncidentMgmt` SOR by intent and `describe` its master-feature
+steps (`read-itsm-incident-feature-status`, `enable-itsm-incident-feature`,
+`verify-itsm-incident-feature-status`). Follow its current invocation and prefix the stored path as its
+version note says (`v67.0` is the minimum and a safe default). A `404` from a version above the org's
+maximum is a version mismatch: retry once at `v67.0` before treating `404` as unavailable.
+Do not use the Service-Foundation `IncidentManagement` look-alike or its broadcast toggles.
+Read the master status via `dispatch_readonly` and decide on `status` first: `ENABLED` is an idempotent
+no-op even if `enableBlockedReasons` is non-empty; `NOT_AVAILABLE` means halt (do not attempt enable);
+for `NOT_ENABLED`, surface any `enableBlockedReasons` as plain text (their messages are HTML-escaped
+markup) and halt if present. Otherwise show the exact off → on change and ask for explicit confirmation before
+running the SOR's enable step via `dispatch`. Re-read via the SOR's verify step and require
+`ENABLED` before continuing. On a declined confirmation, unexpected status, `401`/`403`/`404`,
+failed write, or read-back mismatch, stop without showing the menu; never infer success from
+the write response. **Skip only when the master switch was already confirmed *enabled* in this
+session** (see step 0). A cached "off"/unknown state MUST fall through to the live read.
 
 ### 3. Present the feature menu as a multi-select
 
@@ -144,8 +154,8 @@ Apply these whenever an inline feature runs; the **Everywhere** rules also apply
 hand-off. They are irreversible or silently-wrong if missed.
 
 - **Resolve the right node (Preferences).** Target the ITSM Incident Management org-preferences node
-  (controller `IPCManagementSetupController`), **not** the Service-Foundation look-alike
-  (`IncidentMgmtSetupController`, broadcast channels + a master switch).
+  (the one with the six per-feature toggles), **not** the Service-Foundation look-alike whose toggles
+  are broadcast channels plus its own master switch.
 - **Two preferences are one-way / enable-only (Preferences).** *Restrict Assigned Group to Regular Groups*
   and *Enable Rich Text for Incident Descriptions* cannot be turned off once on. Never offer to disable
   them; require an explicit "I understand this can't be undone" confirmation before enabling; never enable
@@ -189,8 +199,8 @@ hand-off. They are irreversible or silently-wrong if missed.
 ## Rules
 
 - ALWAYS show "(via service-itsm-agentic-setup-incident-management)" in the setup header
-- ALWAYS run the master-switch prerequisite (Behavior step 2) before showing the menu, unless the user
-  already confirmed the switch is on earlier in this conversation
+- ALWAYS run the master-switch prerequisite (Behavior step 2) before showing the menu, unless a live
+  status read already confirmed the switch ENABLED on this org earlier in this session
 - ALWAYS present the feature menu before configuring any selected feature (the master-switch prerequisite
   is the only permitted action before the menu) — do not assume which feature the user wants, **except**
   when the user named a specific feature, in which case go straight to it (single-select is fine)
@@ -214,8 +224,8 @@ hand-off. They are irreversible or silently-wrong if missed.
 Before emitting any menu or summary, confirm each; adjust the output before sending if any is unchecked.
 
 - [ ] The header line ends with `(via service-itsm-agentic-setup-incident-management)`
-- [ ] The master switch was confirmed on (via `service-itsm-incident-mgmt-configure`) before the menu,
-      unless already confirmed earlier in this conversation
+- [ ] The master switch was confirmed on (via the `IncidentMgmt` SOR status/verify steps) before the menu,
+      unless a live read already confirmed it ENABLED on this org earlier in this session
 - [ ] The feature menu emitted BOTH the ASCII table AND an `AskUserQuestion` (`multiSelect: true`) in the
       same response (single-select only if the user already named a specific feature)
 - [ ] Each feature row's `Status` reflects the actual tracked state (`Not done`, `In progress`, `Done`)