@salesforce/afv-skills 1.65.1 → 1.67.0

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>`.
 
@@ -136,27 +144,27 @@ All steps are sequential. Do not skip or reorder.
 
 11. **Apply standard parameters** — if the user needs standard pre-chat fields, generate `<standardParameters>` elements with `parameterType`. If the channel uses Flow-based routing and the user specifies flow variable mappings, include `<actionParameterMappings>` with `actionParameterName` to map each parameter to a flow input variable.
 
-12. **Apply custom parameters** — if the user needs pre-chat data collection, generate `<customParameters>` elements with `name`, `masterLabel`, `parameterDataType`, `externalParameterName`, and `maxLength`. If the channel uses Flow-based routing and the user specifies flow variable mappings, include `<actionParameterMappings>` with `actionParameterName` to map each parameter to a flow input variable.
+12. **Apply custom parameters** — if the user needs pre-chat data collection, generate `<customParameters>` elements with `name`, `masterLabel`, `parameterDataType`, `externalParameterName`, and `maxLength`. Always set `parameterDataType` to `String` — the channel accepts no other value (the field's actual type, including Checkbox/Number/dropdown, is set at the deployment level via `formFieldType`, not here). If the channel uses Flow-based routing and the user specifies flow variable mappings, include `<actionParameterMappings>` with `actionParameterName` to map each parameter to a flow input variable.
 
 13. **Generate the file** — produce the `.messagingChannel-meta.xml` file following the template structure. Place at the path the user specifies, or default to the project's metadata source path under `messagingChannels/`.
 
 ### 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.
 
 ---
@@ -206,7 +216,9 @@ All steps are sequential. Do not skip or reorder.
 | "Only active Agentforce Service Agents are supported" on deploy | Bot is inactive — run `sf agent activate` before deploying |
 | Flow or ASA routing fails without fallback queue | `sessionHandlerQueue` is mandatory when `sessionHandlerType` is `Flow` or `AgentforceServiceAgent` |
 | JWT verification not working | Connected app and certificate must be configured for the org |
-| Custom parameters not collected | `name` must be unique per channel; `parameterDataType` defaults to `Text` |
+| Custom parameters not collected | `name` must be unique per channel |
+| `<customParameters>` deploy fails: "bad value for restricted picklist field" | `parameterDataType` was set to something other than `String`. Channel custom parameters are always `String`; set the field's actual type (Number, Checkbox, dropdown) at the deployment level, not here |
+| Removing a custom parameter: "can't be deleted as it is referenced elsewhere" | **Check before deploying, not after.** Every deployment on this channel whose pre-chat form uses the param must first drop that field and be published (user-approved); remove the param's `actionParameterMappings` in a separate deploy first. See `references/channel_settings.md` §Removing a Custom Parameter |
 | Automated responses not showing | Use exact `type` values (`OptOutConfirmation`, `HelpResponse`); XML-escape special characters |
 | Channel deployed but messages not routing | Channel must be activated after deployment — it defaults to inactive |
 | "You can't enable Session-Based Chat for verified users" | Set `isSynchronousChatEnabled` to `false` for Auth channels — session-based chat is only valid for UnAuth |
@@ -278,6 +290,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/channel_settings.md

@@ -196,11 +196,13 @@ Repeatable element — one block per pre-chat field for data collection.
 |-------|------|----------|-------------|
 | `name` | String | Yes | Unique API name for the parameter |
 | `masterLabel` | String | Yes | Display label shown to agent/user |
-| `parameterDataType` | Enum | Yes | `String`, `Number`, `Boolean` |
+| `parameterDataType` | String | Yes | **Always `String`** — see note below |
 | `externalParameterName` | String | Yes | External mapping name for the parameter |
-| `maxLength` | Integer | No | Max chars for Text type (default 255) |
+| `maxLength` | Integer | No | Max chars (default 255) |
 | `actionParameterMappings` | Object | No | Maps this parameter to an Omni-Channel Flow action input variable |
 
+> **`parameterDataType` is always `String`.** Every channel custom parameter deploys as `String`, regardless of the field's logical type. The metadata field's declared type is the broad `FlowDataType` enum (`Apex`, `Boolean`, `Currency`, `Date`, `DateTime`, `Multipicklist`, `Number`, `Picklist`, `SObject`, `String`, `Time`), but `MessagingChannel` restricts it at deploy time to `String` only — any other value fails with *"bad value for restricted picklist field."* The parameter's actual data type (Number, Checkbox/Boolean, dropdown, etc.) is not set on the channel; it is chosen at the **deployment** level in the pre-chat New Custom Parameter screen — i.e. via the Embedded Service form field's `formFieldType` (see `service-digital-engagement-deployment-configure`).
+
 ### Action Parameter Mappings
 
 When the channel uses Flow-based routing, `actionParameterMappings` maps a custom parameter to a flow input variable so the value collected from the user is passed into the routing flow.
@@ -222,6 +224,15 @@ When the channel uses Flow-based routing, `actionParameterMappings` maps a custo
 </customParameters>
 ```
 
+### Removing a Custom Parameter
+
+A parameter still used by a pre-chat form can't be deleted ("can't be deleted as it is referenced elsewhere"). Several deployments can share one channel, so **check every deployment before writing**: retrieve all `EmbeddedServiceConfig` and find each one whose `<messagingChannel>` is this channel and whose form has `<formField>` = the param `name`. Don't use a failed channel deploy to find them.
+
+1. If another deployment the user didn't mention still uses the param, stop and ask; changing it is outside the request.
+2. Each referencing deployment: remove the field (via `service-digital-engagement-deployment-configure`) and publish it after the user approves.
+3. If the param has `actionParameterMappings`, deploy the channel with the mapping removed first.
+4. Deploy the channel without that parameter's `<customParameters>` block; keep every other parameter.
+
 ---
 
 ## Automated Responses (`<automatedResponses>`)

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,19 +23,29 @@ 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 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 `/services/data/vXX.0/headless/metadata`. **Transport B**: the `sf` commands below, only where a probe shows Transport A unavailable. Exception: Web create always uses the `sf` CLI (step 17a).
+
+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):
 
 - **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)?
 - **Channel name?** What is the `channelPlatformKey` of the messaging channel to associate?
 - For **create**: What should the deployment be named?
 - For **update**: What features to configure? (pre-chat forms, business hours, T&C, UI toggles)
+- For **pre-chat** (if requested): the questions in `references/prechat_forms.md` §Inputs to Gather
 - For **update (Web)**: What is the Experience Site name? Branding overrides needed?
 
 ---
@@ -46,13 +56,13 @@ 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:
 - **Site name** (Web only): The Experience Site name (format `ESW_<name>_<timestamp>`)
 - **Branding name** (optional): Reference to existing `BrandingSet`
-- **Pre-chat form fields** (optional): Field names and required status
+- **Pre-chat form fields** (optional): see `references/prechat_forms.md` §Inputs to Gather
 - **Business hours** (optional): Name of existing `BusinessHours` record
 
 Defaults unless specified:
@@ -69,23 +79,21 @@ 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** — standalone: per Clarifying Questions. Delegated: from `values` (`deploymentName`, `deploymentType`, `channelName` required).
 
-3. **Collect inputs** — gather deployment name, type, and channel name per Clarifying Questions above.
+3a. **Probe transport** — read-only `GET` of `EmbeddedServiceConfig` (contract §2).
 
 4. **Read deployment settings reference** — load `references/deployment_settings.md` to understand all available configuration options.
 
+4a. **Pre-scan** — look up the deployment by its derived API name (contract §3): none → `create` (Phase 2A); matches → no write, `already-configured`, skip to Phase 3; differs → `update` (Phase 2B), announce each change (standalone: ask first); linked to a different channel → standalone: ask before repointing, delegated: `failed`. Standalone, deployment exists: offer exactly three choices — no change / override / add to existing.
+
 ### Phase 2A — Create New Deployment
 
 Use this path when the operation is `create`.
 
-5. **Determine API method by type**:
-
-   | Deployment Type | Creation Method | Prerequisites |
-   |----------------|-----------------|---------------|
-   | API | Metadata API deploy | Channel must exist |
-   | Mobile | Metadata API deploy | Channel must exist |
-   | Web | Connect API | Channel must exist + Experience Site required |
+5. **Determine API method by type** — API/Mobile: Metadata API deploy. Web: Connect API (creates the Experience Site). All types need the channel to exist.
 
 6. **For API/Mobile types** — read the template `assets/esd_api_mobile_template.xml` and generate the `EmbeddedServiceConfig` XML with:
    - `deploymentType` set to `API` or `Mobile`
@@ -96,86 +104,71 @@ Use this path when the operation is `create`.
 
 8. **Generate output** — produce the `.EmbeddedServiceConfig-meta.xml` file (for API/Mobile) or Connect API instructions (for Web).
 
-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>
-     ```
-     To obtain the `EMBEDDED_SERVICE_CONFIG_ID`:
-     ```bash
-     sf data query --query "SELECT Id FROM EmbeddedServiceConfig WHERE DeveloperName = '<DEPLOYMENT_NAME>'" --target-org <org-alias>
-     ```
-   - **Generate code snippet** for integration — see `references/code_snippet.md`
+9. **Present output and next steps** — as in step 17.
 
 ### Phase 2B — Update Existing Deployment (Metadata API)
 
 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** (see Rules). 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`
-    - `shouldShowAgentforceTagline` — Agentforce branding
-    - `shouldShowDeliveryReceipts` — delivery receipts
-    - `shouldShowEmojiSelection` — emoji picker
-    - `shouldShowReadReceipts` — read receipts
-    - `shouldShowTypingIndicators` — typing indicators
-    - `shouldStartNewLineOnEnter` — Enter key behavior
-    - `isChatInvitationCustomizable` / `isInvitationEnabled` — chat invitation settings
+11. **Apply messaging channel settings** — in `<embeddedServiceMessagingChannel>` set `messagingChannel` (the channel's `channelPlatformKey`) and the UI toggles (`shouldShow*`, `shouldStartNewLineOnEnter`, invitation flags). Include every boolean, even when `false`; full list in `references/deployment_settings.md`. Leave each `shouldShow*` / `shouldStartNewLineOnEnter` at its retrieved value (default `false` if nothing was retrieved); set one to `true` only when the user explicitly asks for that feature — never infer it from an example.
 
-12. **Apply pre-chat forms** — if the user needs pre-chat data collection, generate `<embeddedServiceForms>` with `<embeddedServiceFormFields>` elements containing `embeddedServiceFormFieldName` and `isRequired`.
+12. **Apply pre-chat forms** — pre-chat is OFF by default: omit `<embeddedServiceForms>` unless the user asks to collect data before the conversation. If they do, **read `references/prechat_forms.md` first** and follow it (field attributes, hidden fields, ChoiceList, `displayNameFormat`, deactivate vs. remove).
+    - **Before generating**, run the checks in its §Validating and Remediating Prerequisites against the *retrieved* channel. Channel fixes go through `service-digital-engagement-channel-configure`; never hand-edit the channel here.
+    - Delta to graft onto a base deployment: `examples/esd_web_prechat_fields.xml`.
 
 13. **Apply branding customization** (Web only) — a BrandingSet is automatically created with defaults when the deployment is created via Connect API. If the user wants to override specific branding properties (colors, fonts, dimensions), read `references/branding_and_tooling.md` for the Tooling API steps to update individual properties.
 
-14. **Apply invitation** (Web only) — if the user wants the widget to proactively invite visitors based on conditions:
-    - Set `isInvitationEnabled` to `true` in `<embeddedServiceMessagingChannel>`
-    - Generate repeatable `<embdMsgChannelInvitationConditions>` elements with `sequence`, `conditionType`, `operand`, `value`, and optionally `customVariableName`
-    - Update the `formula` field in `<embeddedServiceMessagingChannel>` to reference the condition sequences (e.g., `1 AND 2`, `1 OR 2`). The formula must be updated whenever conditions are added or removed to stay in sync with the `sequence` numbers
-    - See `references/deployment_settings.md` for available condition types and operators
+14. **Apply invitation** (Web only) — set `isInvitationEnabled` to `true`, add `<embdMsgChannelInvitationConditions>` (fields and operators in `references/deployment_settings.md`), and keep `formula` (e.g. `1 AND 2`) in sync with the condition `sequence` numbers whenever conditions change.
 
 15. **Apply additional settings**:
     - `isTermsAndConditionsEnabled` / `isTermsAndConditionsRequired` — T&C in pre-chat
-    - **Do NOT update `site`** — the site name is auto-generated during creation and must never be modified
+    - `site` — Web: the retrieved value, unchanged (see Rules); omit for API/Mobile
 
 16. **Generate the file** — produce the `.EmbeddedServiceConfig-meta.xml` file at the path the user specifies, or default to `EmbeddedServiceConfig/` in the project's metadata source path.
 
 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>
-      ```
-      To obtain the `EMBEDDED_SERVICE_CONFIG_ID`:
-      ```bash
-      sf data query --query "SELECT Id FROM EmbeddedServiceConfig WHERE DeveloperName = '<DEPLOYMENT_NAME>'" --target-org <org-alias>
-      ```
+    - **Publish** (Web) — only after the user approves, per step 17c
     - **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) — never automatic.** Publishing makes the changes live to customers; the deploy only saves a draft. After 17b, stop: summarize what changed, give the plain Setup link `<instanceUrl>/lightning/setup/EmbeddedServiceDeployments/<EmbeddedServiceConfigId>/view` so the user can review the draft, and ask whether to publish now. Publish only on an explicit yes in that turn (a "publish" in the original request does not count). Then `dispatch` `POST` on the fully-qualified publish path; if it returns a path/route error, or on Transport B, run the `sf` publish command from `references/connect_api_creation.md`. Delegated: do not publish; return `published: false`. Note: a Web create via Connect API publishes by itself (`isPublishSuccess: true`); say so in the plan before creating.
+
 ### Phase 3 — Validate
 
 18. **Verify against checklist** — confirm all items in the Verification Checklist below pass.
 
+19. **Report** — delegated: return the contract §5 result. Standalone: the same outcome in plain language.
+
 ---
 
 ## Rules / Constraints
 
 | Constraint | Rationale |
 |-----------|-----------|
-| Always retrieve existing deployment before updating | Ensures current settings are preserved and only intended changes are applied |
 | `deploymentType` must be `API`, `Mobile`, or `Web` | Platform rejects other values |
-| Never update the `site` field on a Web deployment | Site name is auto-generated at creation and must not be changed |
-| Web deployments cannot be created via Metadata API | Circular dependency between Network and CustomSite — use Connect API |
+| Web updates must include `site`, set to the retrieved value unchanged | Site (`ESW_<name>_<timestamp>`) is auto-generated at creation; the platform rejects a missing or changed value |
 | `embeddedServiceMessagingChannelName` must reference an existing channel | Deployment fails if channel doesn't exist |
-| `site` field required for Web type updates | Web widget must be associated with an Experience Site |
-| BrandingSet is auto-created with defaults by Connect API | To override branding properties, use Tooling API — see `references/branding_and_tooling.md` |
-| 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 |
-| Publish step (Connect API) required after Web ESD updates | Changes are not live until published |
+| 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 |
 
 ---
 
@@ -183,16 +176,11 @@ Use this path when the operation is `update`.
 
 | Issue | Resolution |
 |-------|------------|
-| Web ESD creation fails via Metadata API | Web type requires Connect API for initial creation; use Metadata API only for updates |
-| Site name not found | Site must exist before Web ESD update; format is `ESW_<name>_<timestamp>` |
 | 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 |
-| `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 |
-| Deploy fails with "required field missing" or "upsert failed null" | All attributes are mandatory: boolean fields in `embeddedServiceMessagingChannel` (include all even with default `false`), and all form field attributes (`formField`, `formFieldType`, `isHidden`, `isRequired`, `displayOrder`, `messagingChannelParameterType`) |
-| Standard pre-chat field not found | Use `_` prefix for standard fields in `formField`: `_FirstName`, `_LastName`, `_Email`, `_Subject` |
+| Pre-chat form, field, ChoiceList, or `displayNameFormat` issues | See the Gotchas table in `references/prechat_forms.md` |
+| Changes not appearing in widget | The deploy is a draft until published (step 17c) |
+| `sf api request rest` fails ("No 'mode' found", "Nonexistent flag: --url") | See `references/connect_api_creation.md` §Publishing After Updates |
+| Deploy fails with "required field missing" or "upsert failed null" | All attributes are mandatory: boolean fields in `embeddedServiceMessagingChannel` (include all even with default `false`), and all pre-chat form field attributes |
 
 ---
 
@@ -208,7 +196,7 @@ Use this path when the operation is `update`.
 ### Web Type Checks
 - [ ] Is `site` populated with the Experience Site name?
 - [ ] If branding is configured, does `embeddedServiceBrandingName` reference an existing BrandingSet?
-- [ ] Are pre-chat form field names valid (match channel custom parameters)?
+- [ ] Pre-chat (if configured): does every item in the `references/prechat_forms.md` Verification Checklist pass?
 - [ ] If `isInvitationEnabled` is `true`, is `formula` populated and consistent with all `sequence` numbers in `<embdMsgChannelInvitationConditions>`?
 
 ### API/Mobile Type Checks
@@ -216,17 +204,15 @@ Use this path when the operation is `update`.
 - [ ] Is `deploymentType` correctly set to `API` or `Mobile`?
 
 ### Post-Deploy Checks
-- [ ] Is user reminded to publish (Connect API) for Web deployments?
-- [ ] Is user reminded to activate components (Tooling API) if messaging components were deployed?
+- [ ] Web: did you stop before publishing, give the review link, and publish only after the user's explicit yes? Is the user reminded to activate any deployed messaging components (Tooling API)?
 
 ---
 
 ## Output Expectations
 
 Deliverables:
-- **For API/Mobile create**: `<source-path>/EmbeddedServiceConfig/<DeploymentName>.EmbeddedServiceConfig-meta.xml`
-- **For Web create**: Connect API payload and instructions (no XML file)
-- **For update**: `<source-path>/EmbeddedServiceConfig/<DeploymentName>.EmbeddedServiceConfig-meta.xml`
+- **API/Mobile create, and any update**: `<source-path>/EmbeddedServiceConfig/<DeploymentName>.EmbeddedServiceConfig-meta.xml`
+- **Web create**: Connect API payload and instructions (no XML file)
 
 File structure follows the templates in `assets/`.
 
@@ -237,6 +223,7 @@ File structure follows the templates in `assets/`.
 | Need | Delegate to |
 |------|-------------|
 | Creating the messaging channel | `service-digital-engagement-channel-configure` skill |
+| Channel custom parameters, flow-variable mappings, or Queue → Omni-Flow routing | `service-digital-engagement-channel-configure` skill (pass the retrieved channel; see step 12) |
 | Creating Omni-Channel routing flows | `automation-flow-generate` skill |
 | Creating permission sets for agents | `platform-permission-set-generate` skill |
 
@@ -246,13 +233,12 @@ File structure follows the templates in `assets/`.
 
 | File | When to read |
 |------|-------------|
-| `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 |
-| `references/connect_api_creation.md` | When creating Web type deployments (Connect API required) |
+| `references/onboarding_contract.md` | Pre-scan (§3, both modes); delegated mode (`context.calledFrom == "service-onboarding"`), org writes (transport), module registration |
+| `assets/esd_api_mobile_template.xml`, `assets/esd_web_update_template.xml` | Before generating API/Mobile deployments and Web updates, respectively |
+| `references/deployment_settings.md` | When configuring deployment options beyond defaults; less common gotchas (embedded flow, reCAPTCHA, business hours) |
+| `references/prechat_forms.md` | Whenever pre-chat is requested — inputs, field rules, ChoiceList, `displayNameFormat`, deactivate vs. remove, pre-chat gotchas and checklist |
+| `references/connect_api_creation.md` | When creating Web type deployments (Connect API required); publish command and ID query |
 | `references/branding_and_tooling.md` | When user asks about branding configuration |
 | `references/code_snippet.md` | When user wants the JavaScript embed code snippet for their website |
 | `scripts/check-api-version.sh` | Phase 1 — verify org API version meets the passed minimum (67.0) |
-| `examples/esd_api.xml` | To verify output for API type deployment |
-| `examples/esd_mobile.xml` | To verify output for Mobile type deployment |
-| `examples/esd_web_full.xml` | To verify output for fully configured Web deployment |
+| `examples/esd_api.xml`, `esd_mobile.xml`, `esd_web_full.xml`, `esd_web_prechat_fields.xml` | To verify output per type; the pre-chat file is a forms delta to graft onto `esd_web_full.xml` |