@salesforce/afv-skills 1.41.0 → 1.43.0

package/skills/service-agentforce-channel-configure/assets/email/unfiled$public/AgentforceForServiceEmailTemplate.email-meta.xml

@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Fallback ASA-compliant email template for Email-to-Case Agentforce replies.
+  Deployed by Branch C ONLY when the user does not name an existing template.
+
+  Placed under email/unfiled$public/ so it lands in the org-wide PUBLIC email
+  template folder — BotEmailDefinition rejects a template in a private (user)
+  folder. The companion AgentforceForServiceEmailTemplate.email holds the HTML
+  body with the required [[[GENERATED_CONTENT]]] and [[[LEGAL_DISCLOSURE]]] tokens.
+
+  Key required attributes for ASA validity (see references/botemaildefinition.md):
+    uiType = SFX     -> Lightning email template (a classic 'Aloha' template is rejected).
+                        uiType is SET-ONCE: it cannot be changed after create.
+    type   = custom  -> HTML/custom body (not 'text' or 'visualforce').
+    style  = none    -> REQUIRED by the deploy ("Required field is missing: style").
+                        'none' is valid for a custom HTML template.
+
+  The deploying user needs Lightning (SFX) email-template permission and write
+  access to public templates (editPublicTemplates), plus org HTML email enabled.
+-->
+<EmailTemplate xmlns="http://soap.sforce.com/2006/04/metadata">
+    <name>Agentforce for Service Email Template</name>
+    <uiType>SFX</uiType>
+    <type>custom</type>
+    <style>none</style>
+    <encodingKey>UTF-8</encodingKey>
+    <subject>Re: your support request</subject>
+    <available>true</available>
+</EmailTemplate>

package/skills/service-agentforce-channel-configure/assets/mdapi-package.xml

@@ -0,0 +1,25 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Metadata-format manifest for deploying a BotEmailDefinition.
+
+  WHY metadata format: BotEmailDefinition is NOT in the Salesforce CLI's
+  source-deploy-retrieve (SDR) registry, so a source deploy naming the type
+  directly fails with:
+    "Missing metadata type definition in registry for id 'BotEmailDefinition'".
+  Deploy it in METADATA format instead (the deploy "metadata-dir" path), with
+  this package.xml and the component file placed as:
+    (dir)/package.xml
+    (dir)/botEmailDefinitions/(DeveloperName).botEmailDefinition
+  Note the metadata-format file has NO "meta.xml" suffix.
+
+  Substitute {BOT_EMAIL_DEFINITION_DEVELOPER_NAME} with the fullName (file name)
+  and {API_VERSION} with the org's resolved API version — which MUST be 68.0 or
+  higher, since BotEmailDefinition is only exposed to the Metadata API at v68.0+.
+-->
+<Package xmlns="http://soap.sforce.com/2006/04/metadata">
+    <types>
+        <members>{BOT_EMAIL_DEFINITION_DEVELOPER_NAME}</members>
+        <name>BotEmailDefinition</name>
+    </types>
+    <version>{API_VERSION}</version>
+</Package>

package/skills/service-agentforce-channel-configure/assets/settings-mdapi-package.xml

@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Metadata-format manifest for deploying the Case settings singleton
+  (member name is always "Case" — CaseSettings is a per-org singleton).
+
+  WHY metadata format (not a source deploy that names Settings:Case directly):
+  a source deploy reads sourceApiVersion from sfdx-project.json, which the
+  api-version flag does NOT override. Deploying in metadata format lets this
+  manifest pin the version instead, so the user's sfdx-project.json is never
+  mutated (a source deploy would otherwise force a permanent sourceApiVersion
+  bump affecting all their later deploys).
+
+  NOTE: keep this comment free of double-hyphen tokens. This file is copied
+  verbatim (via sed) into the deploy package.xml, and the Metadata API rejects
+  a double-hyphen sequence inside an XML comment ("not permitted within
+  comments"), which fails the deploy.
+
+  Substitute {API_VERSION} with the org's resolved API version — which MUST be
+  68.0 or higher, since botEmailDefinition on a routing address is only exposed
+  to the Metadata API at v68.0+. The Case settings file is placed as:
+    (dir)/package.xml
+    (dir)/settings/Case.settings          (metadata format: NO -meta.xml suffix)
+-->
+<Package xmlns="http://soap.sforce.com/2006/04/metadata">
+    <types>
+        <members>Case</members>
+        <name>Settings</name>
+    </types>
+    <version>{API_VERSION}</version>
+</Package>

package/skills/service-agentforce-channel-configure/references/agent-wiring.md

@@ -13,6 +13,7 @@ The connection block name depends on the channel type being wired:
 | Enhanced Chat (EmbeddedMessaging) | `connection customer_web_client:` | `OmniChannelFlow` |
 | Enhanced Messaging (3rd-party) | `connection messaging:` | `OmniChannelFlow` |
 | Voice | `connection telephony:` | `OmniChannelFlow` |
+| Email-to-Case | `connection service_email:` | `OmniChannelFlow` |
 
 ## Prerequisite
 
@@ -72,6 +73,15 @@ connection telephony:
     adaptive_response_allowed: True
 ```
 
+For **Email-to-Case** (`connection service_email:`):
+
+```yaml
+connection service_email:
+    outbound_route_type: "OmniChannelFlow"
+    outbound_route_name: "flow://{OUTBOUND_FLOW_DEVELOPER_NAME}"
+    adaptive_response_allowed: True
+```
+
 If a block for the relevant connection type already exists in the file, **add the outbound fields to the existing block** rather than creating a duplicate. Do not overwrite fields that are already present. If `modality voice:` already exists, leave it as-is — do not overwrite existing voice tuning values.
 
 ## Republish and activate the agent
@@ -93,5 +103,15 @@ grep -n "outboundRouteName\|outboundRouteType" \
 Both `outboundRouteName` and `outboundRouteType` must be present in the correct `<plannerSurfaces>` entry. The compiled XML maps the connection blocks as:
 - `connection customer_web_client:` → `<surfaceType>CustomerWebClient</surfaceType>`
 - `connection messaging:` → `<surfaceType>Messaging</surfaceType>`
+- `connection service_email:` → `<surfaceType>ServiceEmail</surfaceType>`
 
 If absent, the connection block was not serialised correctly — re-retrieve the `.agent` file and confirm the YAML was written before publishing.
+
+> **AiAuthoringBundle / Email-to-Case caveat (`connection service_email:`).** For an agent authored as an **AiAuthoringBundle** — the `ExternalCopilot` Agentforce Service Agent used by Email-to-Case (Branch C) — `sf project retrieve start --metadata "GenAiPlannerBundle:{AGENT_DEVELOPER_NAME}"` can report `files: 1` yet write **nothing** under `genAiPlannerBundles/`. With no compiled file to grep, the command above returns empty — a **false negative**, not a wiring failure. Do not conclude the surface is missing. Verify instead by:
+> - **Grepping the `AiAuthoringBundle` source** (the source of truth), which retains the block through publish:
+>   ```bash
+>   sf project retrieve start --metadata "AiAuthoringBundle:{AGENT_DEVELOPER_NAME}" --target-org $ORG
+>   grep -n "connection service_email:" \
+>     force-app/main/default/aiAuthoringBundles/{AGENT_DEVELOPER_NAME}/{AGENT_DEVELOPER_NAME}.agent
+>   ```
+> - **Treating the `BotEmailDefinition` deploy as the definitive `ServiceEmail`-surface check.** Its save-time validation fires `SurfaceMissingForSave` **last**, so a successful `Created` deploy (Branch C, Step 4c) proves the surface is live on the active version — authoritative over the empty GenAiPlannerBundle grep.

package/skills/service-agentforce-channel-configure/references/botemaildefinition.md

@@ -0,0 +1,107 @@
+# BotEmailDefinition — field, validation, and deploy reference
+
+`BotEmailDefinition` is the Metadata API type (available **API v68.0+**) that connects an Agentforce Service Agent to Service Email, so the agent can respond to Email-to-Case messages. It backs the "Agentforce for Service on Email" Setup feature (`/lightning/setup/AsaForEmail/home`). Branch C deploys it headlessly instead of asking the user to fill in that Setup form.
+
+It is a top-level component (`keyPrefix 1NY`, `isTopLevel=true`), but it is **not registered in the Salesforce CLI's source-deploy-retrieve (SDR) registry** — a source deploy that names the type directly (`sf project deploy start --metadata BotEmailDefinition:<name>`) fails with `Missing metadata type definition in registry for id 'BotEmailDefinition'`. Deploy it in **metadata format** with `--metadata-dir` instead (see "Deploying" below). It is not the `CaseSettings` singleton, so it does not use the two-phase `updateMetadata` CRUD call.
+
+## Fields (WSDL complexType, extends `Metadata`)
+
+All six are **required on create** — the WSDL marks none of them `minOccurs="0"` — and none are platform-generated/read-only.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `botDefinition` | string | **Required.** Developer/API name of the `AgentforceServiceAgent` (Bot) to link. Resolved to the Bot's ID at deploy. The agent must be **active**, of type `EinsteinServiceAgent`, have a bot user, and that bot user must hold `agentforceServiceAgentUser`. |
+| `emailTemplate` | string | **Required.** Reference to the reply email template. **Must be folder-qualified** — e.g. `unfiled$public/AgentforceForServiceEmailTemplate`, not a bare `AgentforceForServiceEmailTemplate` (a bare name fails with `no EmailTemplate named X found`). Must satisfy the ASA rules below. |
+| `label` | string | **Required.** Display label for the email definition. |
+| `legalDisclaimer` | string | **Required.** Legal disclosure / footer text appended to replies. **Minimum 10 characters** (`MinLengthNotMet`). |
+| `replyAll` | boolean | **Required.** `true` = reply-all; `false` = reply to sender only. |
+| `signature` | string | **Required.** Email signature block. **Minimum 10 characters** (`MinLengthNotMet`). |
+
+`fullName` is **not** a child element — for a top-level component it is the file name (`<DeveloperName>.botEmailDefinition-meta.xml`). The routing address references this `fullName`.
+
+## Save-time validation order (verified against Core, release 266)
+
+The org validates the fields in this exact order — note the surface/active-version check (step 5) fires **last**, after the two text-length checks and all the agent/template checks. Following the same order in preflight surfaces the most likely blocker first.
+
+1. **`legalDisclaimer` length** — must be ≥10 chars, else `MinLengthNotMet`.
+2. **`signature` length** — must be ≥10 chars, else `MinLengthNotMet`.
+3. **`botDefinition`** — in order:
+   - empty → `RequiredFieldMissing`;
+   - not found → `BotDefinitionInvalid`;
+   - agent type ≠ `EinsteinServiceAgent` → `BotDefinitionAgentTypeIncorrect`;
+   - bot user null/invalid → `BotUserNull` / `BotUserInvalid`;
+   - bot user missing the `agentforceServiceAgentUser` permission → `BotUserHasNoAgentforceServiceAgentUserPerm`.
+4. **`emailTemplate`** — in order:
+   - `uiType` ≠ SFX → `EmailTemplateUiTypeIncorrect`;
+   - blank HTML body → `EmailTemplateDoesntContainHtmlValue`;
+   - missing `[[[GENERATED_CONTENT]]]` → `EmailTemplateMissingGeneratedContent`;
+   - missing `[[[LEGAL_DISCLOSURE]]]` → `EmailTemplateMissingLegalDisclosure`;
+   - private/user folder (id prefix `005`, or folder `AccessType` ≠ `PUBLIC`) → `EmailTemplateIsPrivate`.
+5. **Surface / active-version check** — fires **last**:
+   - the agent has no **active version** → `AgentMustBeActive`;
+   - the active version does not have the **`ServiceEmail` surface** enabled → `SurfaceMissingForSave` (label section `AsaForEmail`).
+   The check uses the **active-version** id, not the bot id.
+
+## Prerequisite: the `ServiceEmail` surface (`connection service_email:`)
+
+The save checks that the agent's **active version** has the `ServiceEmail` surface enabled. That surface is enabled by a `connection service_email:` block in the agent's `.agent` (AiAuthoringBundle) file, which compiles to `<plannerSurfaces><surfaceType>ServiceEmail</surfaceType><surface>SurfaceAction__ServiceEmail</surface></plannerSurfaces>`. Branch C **Step 3** adds this block and republishes before the deploy, so the active version already carries the surface — enabling it after publish would require deactivate → deploy → reactivate.
+
+Detect an existing surface on the published agent:
+```bash
+sf project retrieve start --metadata "AiAuthoringBundle:{AGENT_DEVELOPER_NAME}" --target-org $ORG
+# then grep the retrieved .agent file for:  connection service_email:
+```
+
+## Case assignment — why the binding alone is not enough
+
+The routing address's `botEmailDefinition` child only selects *which agent/template generates the reply*; it does **not** route the case to the agent. Branch C does that with one of two mechanisms (Step 2), written onto the routing address in Step 4d:
+
+- **Direct case-owner assignment (default):** set `caseOwner` = the bot user's Username with `caseOwnerType: User`. The agent replies only when `Case.Owner` equals its bot user **at the moment the inbound email is processed**, and that owner must be assigned **synchronously during the case save** — a delayed/async assignment (e.g. a late-running assignment rule) prevents the reply until the customer emails again. Setting `caseOwner` satisfies this: it is copied onto every new case at save time, no extra infrastructure.
+- **Omni-Channel flow (advanced):** set `routingFlow` (an inbound Copilot RoutingFlow) + `fallbackQueue`; the flow routes each case to the agent via Omni-Channel.
+
+Set one path's fields, not both. An empty `caseOwner` with no `routingFlow` → the case falls to the org default owner and the agent stays silent.
+
+## The email template (ASA-valid `EmailTemplate`)
+
+A template is ASA-valid only if **all** of these hold (each maps to an error in step 4 above):
+
+1. **`uiType = SFX`** — a Lightning email template; classic (`Aloha`) is rejected. `uiType` is **set-once** (create SFX; cannot flip later).
+2. **HTML body present** — the `.email` body must be non-blank.
+3. **Both literal ASA tokens** — the HTML body must contain, verbatim, `[[[GENERATED_CONTENT]]]` and `[[[LEGAL_DISCLOSURE]]]`. These are raw substrings, **not** `{!...}` merge fields.
+4. **Public** — the org-wide public bucket (`unfiled$public`) or a folder whose `AccessType` is `Public`. A private/user folder is rejected.
+5. **Exists** — the FK is `Restrict`, so the template must pre-exist the deploy.
+
+Branch C validates the fallback template with `python3 scripts/validate-emailtemplate.py <path-to-.email-meta.xml>` before deploying. Deploying the fallback requires the deploying user to have Lightning (SFX) email-template permission, write access to public templates (`editPublicTemplates`), and org HTML email enabled.
+
+## Deploying (metadata format)
+
+Because `BotEmailDefinition` is not in the CLI's SDR registry, deploy it in **metadata format**. Build a metadata-format package directory from `assets/mdapi-package.xml` and the component file (renamed to drop `-meta.xml`):
+
+```text
+<mdapi-dir>/
+├── package.xml                                       # from assets/mdapi-package.xml
+└── botEmailDefinitions/
+    └── <DeveloperName>.botEmailDefinition            # same XML as the source file, NO -meta.xml suffix
+```
+
+Set `package.xml` `<version>` to the org's resolved API version. Then:
+
+```bash
+sf project deploy start --metadata-dir <mdapi-dir> --target-org $ORG --json
+```
+
+Confirm `success: true` with the component listed. `BotEmailDefinition` is **not SOQL-queryable** and may not read/retrieve back cleanly, so treat a successful deploy result as authoritative — do not treat a failed read-back as a failed deploy.
+
+## Org gate (composite)
+
+Everything here is gated by a **composite** capability, not a single permission:
+
+```text
+orgHasAgentforceServiceAgentEmail =
+      OrgPermissions.AgentforceServiceAgent
+   && OrgPermissions.HasEmailToCase
+   && (OrgPermissions.UniversalCreditMetering || OrgPermissions.ASAEmailEarlyAccess)
+   && EinsteinBot.orgHasChatbotFoundationEnabled
+```
+
+Create/edit/delete of the component additionally requires `UserPermissions.CustomizeApplication`. If the composite gate is not satisfied, the type is unavailable and the deploy fails — stop and surface the error.

package/skills/service-agentforce-channel-configure/references/channel-branch-email.md

@@ -1,6 +1,24 @@
 # Branch C — Email-to-Case inbound routing
 
-Same inbound RoutingFlow shape as Branch B, but using the org-specific Case-based ServiceChannel. Also includes the mandatory outbound `connection service_email:` and a mandatory manual BotEmailDefinition step (Email Configuration in Setup).
+Inbound routing gets each new case to the agent's bot user by one of two mechanisms (Step 2) — direct case-owner assignment (default) or an Omni-Channel flow. Also includes the mandatory `connection service_email:` surface block and a mandatory BotEmailDefinition step (Email Configuration).
+
+## Precondition — org must be on API v68.0+
+
+`BotEmailDefinition` (the Email Configuration that links the agent to Service Email — Step 4) is exposed to the Metadata API only at **API v68.0+**. Gate the entire branch on this **before configuring anything** — do not enable Email-to-Case, create routing addresses, deploy the inbound flow, or modify the agent on an org that can't complete the wiring.
+
+Resolve the org's **true max** supported API version and stop if it is below 68.0. Query `/services/data` (the live version list) rather than `sf org display`'s `apiVersion` — that value is a cached `instanceApiVersion` that can lag the org's real max, so an upgraded-but-not-re-authed v68 org could wrongly fail this gate:
+
+```bash
+ORG_API_VERSION=$(sf api request rest --target-org "$ORG" "/services/data" \
+  | python3 -c "import sys, json; print(max((v['version'] for v in json.load(sys.stdin)), key=float))")
+
+python3 -c "import sys; sys.exit(0 if float('$ORG_API_VERSION') >= 68.0 else 1)" || {
+  echo "Org API version $ORG_API_VERSION is below 68.0 — Agentforce Email-to-Case (BotEmailDefinition) is not available on this org. Stopping without making changes."
+  exit 1
+}
+```
+
+If the check fails, **stop and tell the user** their org's API version does not support Agentforce Email-to-Case, and configure nothing. **There is no manual Setup fallback for this branch** — if the org can't complete the wiring headlessly, stop. If it passes, carry `ORG_API_VERSION` forward for the Step 4 deploy manifest.
 
 ## Step 0 — Enable Email-to-Case
 
@@ -49,10 +67,10 @@ Ask the user via `AskUserQuestion`:
    a. Read current CaseSettings from the Tooling API:
    ```bash
    sf api request rest -o "$ORG" --method GET \
-     "/services/data/v67.0/tooling/query?q=SELECT+Metadata+FROM+CaseSettings+LIMIT+1"
+     "/services/data/v{ORG_API_VERSION}/tooling/query?q=SELECT+Metadata+FROM+CaseSettings+LIMIT+1"
    ```
 
-   b. In the returned `Metadata.caseEmailRoutingAddresses` array, find the entry whose `emailAddress` matches `{SUPPORT_EMAIL}`. Patch that entry:
+   b. In the returned `Metadata.emailToCase.routingAddresses` array (not a top-level `caseEmailRoutingAddresses`), find the entry whose `emailAddress` matches `{SUPPORT_EMAIL}`. Patch that entry:
    - `caseOrigin`: query `Case.Origin` picklist values and select `Email` if present, otherwise the closest match
    - `saveEmailHeaders`: `true`
    - `addressType`: `EmailToCase`
@@ -60,10 +78,10 @@ Ask the user via `AskUserQuestion`:
    c. Deploy the patched Metadata back:
    ```bash
    sf api request rest -o "$ORG" --method PATCH \
-     "/services/data/v67.0/tooling/sobjects/CaseSettings/{CASE_SETTINGS_ID}" \
+     "/services/data/v{ORG_API_VERSION}/tooling/sobjects/CaseSettings/{CASE_SETTINGS_ID}" \
      --body '{"Metadata": {<patched metadata object>}}'
    ```
-   Run this from `/tmp/sfskills` (a valid SFDX project directory). If the Tooling API PATCH fails, fall back to Metadata API deploy via `sf project deploy start --metadata Settings:Case`.
+   If the Tooling API PATCH fails, fall back to a **metadata-format** `Settings:Case` deploy — the same `--metadata-dir` pattern as Step 4d point 3 (assemble a package from `assets/settings-mdapi-package.xml` pinned to `ORG_API_VERSION`, drop the `Case.settings` file under `settings/`, and deploy with `sf project deploy start --metadata-dir`). Do **not** fall back to a source deploy (`sf project deploy start --metadata Settings:Case`): it reads `sourceApiVersion` from the project's `sfdx-project.json` (which the api-version flag does not override), so v68-only fields fail on a project pinned lower, and pinning it there mutates the user's project permanently. As in Step 4d, a settings deploy replaces the whole `routingAddresses` collection, so the deployed file must carry every existing address.
 
 4. Inform the user about email verification — then continue without waiting:
 
@@ -80,66 +98,201 @@ Set `ROUTING_ADDRESS_ID` to the selected record's `Id` and continue. No provisio
 
 ---
 
-## Step 2 — Inbound RoutingFlow
+## Step 2 — Inbound routing to the agent
 
-1. **Query the ServiceChannel** — see `channel-types.md`. Stop if zero rows; ask user if multiple rows.
+Each new case must reach the agent's bot user. There are two mechanisms — ask the user which to use (`AskUserQuestion`):
 
-2. **Determine names:**
-   - Flow label: `{AgentLabel} Inbound Email Flow`
-   - DeveloperName: `{AgentDevName}_Inbound_Email_Flow`
-   - `SERVICE_CHANNEL_DEV_NAME` / `SERVICE_CHANNEL_LABEL` from the queried ServiceChannel
+- **Direct case-owner assignment (default)** — set the agent's bot user as the routing address's `caseOwner`. It is copied straight onto every new case during save. No extra org configuration.
+- **Omni-Channel flow (advanced)** — an inbound routing flow routes each case to the agent via Omni-Channel, with a fallback queue when the agent is unavailable.
 
-3. **Write the RoutingFlow XML** to `force-app/main/default/flows/{AgentDevName}_Inbound_Email_Flow.flow-meta.xml` using the template in `routing-flow.md`. Substitute all tokens including `{QUEUE_ID}` from Phase 1.
+Either way, resolve the agent's **bot user** first — the record Setup surfaces as the "Agent User" / context user (Agent Details tab), which also equals the `.agent` file's `default_agent_user`. It is `BotDefinition.BotUserId` resolved to its `Username`:
+```bash
+sf data query --target-org $ORG --json \
+  --query "SELECT BotUserId FROM BotDefinition WHERE DeveloperName='{AGENT_DEVELOPER_NAME}'"
+sf data query --target-org $ORG --json \
+  --query "SELECT Username FROM User WHERE Id='{BOT_USER_ID}'"
+```
+Capture `BOT_USER_USERNAME`.
+
+### Path A — Direct case-owner assignment (default)
 
-4. **Deploy and verify `ActiveVersionId` is non-null** (see `routing-flow.md`).
+The bot user must own the case **at the moment the inbound email is processed**, and the owner must be assigned **synchronously during the case save** — a delayed/async assignment (e.g. a late-running assignment rule) prevents the automated reply until the customer emails again. Setting `caseOwner` = `BOT_USER_USERNAME` (`caseOwnerType: User`) satisfies this. Write it in the Step 4d settings deploy — do not deploy twice.
 
-No agent file changes from inbound routing.
+### Path B — Omni-Channel flow (advanced)
+
+1. Resolve the org's **Case-based `ServiceChannel`** (`RelatedEntity='Case'`); provision one if absent — see `references/channel-types.md`. Capture `SERVICE_CHANNEL_DEV_NAME` / `SERVICE_CHANNEL_LABEL`.
+2. Create the inbound `Copilot` RoutingFlow that routes to the agent with the Phase 1 queue as fallback, using the template in `references/routing-flow.md` **Part 1**. Deploy and verify `ActiveVersionId` is non-null. Capture `INBOUND_FLOW_DEVELOPER_NAME`.
+3. In the Step 4d settings deploy, set `routingFlow` = `INBOUND_FLOW_DEVELOPER_NAME` and `fallbackQueue` = `QUEUE_DEVELOPER_NAME` on the routing address — **instead of** `caseOwner` (set one path's fields, not both).
 
 ---
 
-## Step 3 — Mandatory outbound escalation: `connection service_email:`
+## Step 3 — Mandatory ServiceEmail surface: `connection service_email:`
 
-Unlike other channel types where outbound escalation is optional, Email-to-Case requires the `connection service_email:` block to be on the agent before the BotEmailDefinition (Email Configuration) can be created in Setup — the Setup UI requires the agent to already have this connection wired.
+Email-to-Case requires the agent to carry the **ServiceEmail surface** before the BotEmailDefinition (Step 4) can be created. The `connection service_email:` block is what enables that surface; its **presence** is what's mandatory (not any escalation wiring). Do not offer this as optional or skip it.
 
-Do not offer this as optional or skip to Phase 3. Run these steps now:
+This is a surface-only add with no outbound flow, so it is self-contained here — it does **not** go through the escalation path in `agent-wiring.md`.
 
-1. **Determine the outbound flow name:**
-   - Flow label: `{AgentLabel} Outbound Email Flow`
-   - DeveloperName: `{AgentDevName}_Outbound_Email_Flow`
+1. Retrieve the agent's authoring bundle:
+   ```bash
+   sf project retrieve start --metadata "AiAuthoringBundle:{AGENT_DEVELOPER_NAME}" --target-org $ORG
+   ```
 
-2. **Check if an active outbound flow already exists:**
+2. Add the block to the `.agent` YAML with a single `description` field (an empty block fails validation):
+   ```yaml
+   connection service_email:
+       description: "Replies to inbound Email-to-Case messages."
+   ```
+
+3. Republish and activate. The agent is already active at this point (Phase 1), and **publishing a surface/connection change onto an active agent fails** with `We couldn't find the default agent user <username>` — the active version holds the agent user, so it must be released first. Deactivate → publish → activate:
    ```bash
-   sf data query --target-org $ORG --json \
-     --query "SELECT ApiName, ActiveVersionId FROM FlowDefinitionView WHERE ApiName='{AgentDevName}_Outbound_Email_Flow' AND ProcessType='RoutingFlow'"
+   echo "Y" | sf agent deactivate     --api-name {AGENT_DEVELOPER_NAME} --json
+   sf agent validate authoring-bundle --api-name {AGENT_DEVELOPER_NAME} --json
+   sf agent publish  authoring-bundle --api-name {AGENT_DEVELOPER_NAME} --json
+   echo "Y" | sf agent activate       --api-name {AGENT_DEVELOPER_NAME} --json
    ```
-   - Row exists with non-null `ActiveVersionId` → reuse it; skip to step 3.
-   - Row missing or `ActiveVersionId` null → create using the QueueBased template in `routing-flow.md` Part 2, with the `SERVICE_CHANNEL_DEV_NAME` / `SERVICE_CHANNEL_LABEL` queried above and `QUEUE_DEVELOPER_NAME` from Phase 1. Deploy and verify `ActiveVersionId` is non-null.
 
-3. **Add `connection service_email:` to the agent and republish** — follow `agent-wiring.md`. Verify the connection block is present in the deployed bundle before continuing.
+   **Batch escalation here to avoid a second publish cycle.** Each surface/connection change on an active agent costs a full deactivate → publish → activate. If the user will also want outbound escalation (Phase 3), wire it in *this* edit instead of republishing again later: resolve the escalation queue and create the outbound `QueueBased` RoutingFlow first (`references/queue-resolution.md`, `references/routing-flow.md`), then add the outbound-route fields to this same `connection service_email:` block (per `references/agent-wiring.md`) before the single publish/activate above — the surface `description` and the outbound route then go live together.
+
+Verify the block is present in the deployed bundle before continuing. Escalation is separate from this surface step — if the user wants it, add it via Phase 3 (`agent-wiring.md`), exactly like the other channels. It is not required to save the BotEmailDefinition.
 
 ---
 
-## Step 4 — Mandatory manual step: BotEmailDefinition (cannot be automated)
-
-The `BotEmailDefinition` metadata type is not yet deployable via `sf project deploy`. Surface this step only after the outbound connection block is confirmed deployed:
-
-> *"The inbound routing flow and outbound escalation are now configured. One final manual step is required: you must create an **Email Configuration for Agentforce Service Agent** in Setup.*
->
-> *Go to: `{ORG_INSTANCE_URL}/lightning/setup/AsaForEmail/home` → New*
->
-> *Fill in the following fields:*
-> - *Label / DeveloperName: use the agent name for identification, e.g. `{AgentLabel} Email Configuration`*
-> - *Agent: select **{AgentLabel}***
-> - *Reply Template: an email template containing `[[[GENERATED_CONTENT]]]` (the agent's reply body) and `[[[LEGAL_DISCLOSURE]]]` (required legal footer placeholder)*
-> - *Legal Disclaimer: the legal text shown at the bottom of every agent reply email (required)*
-> - *Signature: the agent's sign-off text, e.g. agent name and title (required)*
->
-> *If you don't have suitable email templates yet, open the App Launcher and search for **Email Templates** to create them. The reply template must include `[[[GENERATED_CONTENT]]]` and `[[[LEGAL_DISCLOSURE]]]` as literal placeholder strings.*
->
-> *Once the Email Configuration is saved, open your Email-to-Case configuration (Setup → Feature Settings → Service → Email-to-Case → edit the relevant routing address) and set the **Agentforce Configuration** field to the configuration you just created.*
->
-> *Reference: [Email Configurations for Agentforce Service Agent](https://help.salesforce.com/s/articleView?id=ai.service_agent_email_configuration.htm&type=5)*
->
-> Please confirm when this setup step is complete."*
-
-Branch C is complete once the user confirms. Phase 3 outbound escalation has already been handled above — skip Phase 3 for Email-to-Case.
+## Step 4 — BotEmailDefinition (Email Configuration)
+
+The `BotEmailDefinition` component links the agent to Service Email (the "Agentforce for Service on Email" feature). Read `references/botemaildefinition.md` in full before this step. Run this only after Step 3 confirmed `connection service_email:` is deployed on the agent.
+
+### Step 4a — Preflight the save-time gates (fail fast, in Core's order)
+
+`BotEmailDefinition`'s save-time validation runs in a fixed order (see `references/botemaildefinition.md`). Check the agent-side gates now so a deploy failure isn't the first signal:
+
+1. **Bot user + perm.** The agent must have a bot user that holds `agentforceServiceAgentUser`:
+   ```bash
+   sf data query --target-org $ORG --json \
+     --query "SELECT Id, BotUserId FROM BotDefinition WHERE DeveloperName='{AGENT_DEVELOPER_NAME}'"
+   ```
+   Confirm `BotUserId` is non-null. Then confirm the bot user has the perm:
+   ```bash
+   sf data query --target-org $ORG --json \
+     --query "SELECT Id FROM PermissionSetAssignment WHERE AssigneeId='{BOT_USER_ID}' AND PermissionSet.PermissionsAgentforceServiceAgentUser = true LIMIT 1"
+   ```
+   Querying `PermissionSetAssignment` (not standalone `PermissionSet`) covers all three grant paths at once — the profile's own permission set, a directly assigned permission set, and a permission-set-group member. If it returns no row, stop with a clear message — the deploy would fail `BotUserHasNoAgentforceServiceAgentUserPerm`.
+
+2. **Active version + ServiceEmail surface.** Phase 1 already confirmed an active version. Confirm the active version carries the surface (added in Step 3):
+   ```bash
+   sf project retrieve start --metadata "AiAuthoringBundle:{AGENT_DEVELOPER_NAME}" --target-org $ORG
+   ```
+   Grep the retrieved `.agent` file for `connection service_email:`. If absent, return to Step 3 — the deploy would fail `AsaForEmail/SurfaceMissingForSave`.
+
+3. **No customer-verification topic (safety net).** In the same retrieved `.agent` file, check for a `ServiceCustomerVerification` subagent / topic (or a router branch gated on `isVerified`). If present, **stop and warn** — an email agent carrying customer verification dead-ends inbound email at the verification step (a fresh sender is never `isVerified`, and verification can't complete over async email). Do not auto-remove it here — this skill only wires an already-authored agent, and the topic may be legitimate for a multi-surface agent that also serves chat.
+
+### Step 4b — Provide the reply email template
+
+The agent needs an ASA-valid `EmailTemplate` (`uiType=SFX`, HTML, public, containing both `[[[GENERATED_CONTENT]]]` and `[[[LEGAL_DISCLOSURE]]]`). Ask the user whether they have one:
+
+- **User names an existing template** → confirm it is SFX, HTML-bodied, in a public folder, and contains both tokens. Use its **folder-qualified** name (e.g. `unfiled$public/<Name>`) as `EMAIL_TEMPLATE`.
+- **User has none** → deploy the fallback from `assets/email/unfiled$public/AgentforceForServiceEmailTemplate.email` + `.email-meta.xml`. Validate first, then deploy:
+  ```bash
+  python3 scripts/validate-emailtemplate.py "assets/email/unfiled\$public/AgentforceForServiceEmailTemplate.email-meta.xml"
+  # The asset is already source-format (email/<folder>/<name>) — deploy it by path, not by --metadata
+  # (a named-type deploy resolves only components in the project's package directories, not this skill's assets/).
+  sf project deploy start --source-dir "assets/email" --target-org $ORG --json
+  ```
+  Use `unfiled$public/AgentforceForServiceEmailTemplate` as `EMAIL_TEMPLATE`.
+
+### Step 4c — Build, validate, and deploy the BotEmailDefinition
+
+Elicit `label`, `legalDisclaimer` (≥10 chars), `signature` (≥10 chars), and `replyAll` (reply-all vs reply-to-sender) from the user. Choose a `DeveloperName`, e.g. `{AgentDevName}_Email_Config`.
+
+1. Copy `assets/BotEmailDefinition.botEmailDefinition-meta.xml` to `/tmp/sfskills/{DeveloperName}.botEmailDefinition-meta.xml` and substitute `{AGENT_DEVELOPER_NAME}`, `{EMAIL_TEMPLATE_FOLDER}/{EMAIL_TEMPLATE_DEVELOPER_NAME}` (= `EMAIL_TEMPLATE`), `{LABEL}`, `{LEGAL_DISCLAIMER_TEXT}`, `{SIGNATURE_TEXT}`, and `replyAll`.
+
+2. Validate:
+   ```bash
+   python3 scripts/validate-botemaildefinition.py /tmp/sfskills/{DeveloperName}.botEmailDefinition-meta.xml
+   ```
+   Resolve any errors before deploying.
+
+3. Assemble the metadata-format package and deploy (source deploy naming the type directly fails — it is absent from the SDR registry):
+   ```bash
+   MDDIR=/tmp/sfskills/botemaildef-mdapi
+   mkdir -p "$MDDIR/botEmailDefinitions"
+   # package.xml: from assets/mdapi-package.xml, substituting the member name and
+   # {API_VERSION} = ORG_API_VERSION from the Precondition.
+   sed -e "s/{BOT_EMAIL_DEFINITION_DEVELOPER_NAME}/{DeveloperName}/" \
+       -e "s/{API_VERSION}/{ORG_API_VERSION}/" \
+       assets/mdapi-package.xml > "$MDDIR/package.xml"
+   # component file: same XML as the source file, WITHOUT the -meta.xml suffix
+   cp /tmp/sfskills/{DeveloperName}.botEmailDefinition-meta.xml \
+      "$MDDIR/botEmailDefinitions/{DeveloperName}.botEmailDefinition"
+   sf project deploy start --metadata-dir "$MDDIR" --target-org $ORG --json
+   ```
+   Confirm `status: Succeeded` / `success: true` with the component listed. `BotEmailDefinition` is not SOQL-queryable, so treat a successful deploy as authoritative — do not treat a failed read-back as failure. Capture the `fullName` as `BOT_EMAIL_DEFINITION_NAME`.
+
+   **If the deploy fails**, stop and surface the error to the user — the agent cannot be wired to email on this org.
+
+### Step 4d — Bind the routing address (BotEmailDefinition + inbound routing)
+
+In one `Settings:Case` metadata deploy, set on the routing address (`{SUPPORT_EMAIL}` from Step 1): the `botEmailDefinition` binding to `BOT_EMAIL_DEFINITION_NAME`, **plus** the Step 2 inbound-routing fields — either `caseOwner` = `BOT_USER_USERNAME` + `caseOwnerType: User` (Path A), or `routingFlow` = `INBOUND_FLOW_DEVELOPER_NAME` + `fallbackQueue` = `QUEUE_DEVELOPER_NAME` (Path B). `casePriority` is **required** on every routing address — carry it, or the deploy fails with `Missing casePriority`. A settings deploy **replaces** the `emailToCase.routingAddresses` collection, so the deployed file must carry **every** existing address — dropping one unbinds it. There is no pre-existing `Case.settings-meta.xml` in the project; you must generate it from the current org state first.
+
+1. **Read the current CaseSettings** to get the full `emailToCase` block, including all routing addresses:
+   ```bash
+   sf api request rest -o "$ORG" --method GET \
+     "/services/data/v{ORG_API_VERSION}/tooling/query?q=SELECT+Metadata+FROM+CaseSettings+LIMIT+1"
+   ```
+
+2. **Write `Case.settings-meta.xml`** to the project's settings directory (e.g. `force-app/main/default/settings/Case.settings-meta.xml`). Include the `emailToCase` toggles and **one `<routingAddresses>` entry per existing address** from the read. For each address, carry over **every** field the read returned except the read-only `emailServicesAddress`/`isVerified` — preserve whatever the org actually set (e.g. `addressType`, `caseOrigin`, `emailAddress`, `routingName`, and fields like `casePriority`), rather than a fixed subset. On the entry whose `emailAddress` matches `{SUPPORT_EMAIL}`, add `<botEmailDefinition>{BOT_EMAIL_DEFINITION_NAME}</botEmailDefinition>` plus the Step 2 path's fields. The example below shows **Path A** (case owner); for **Path B**, swap in `<routingFlow>`+`<fallbackQueue>` instead:
+   ```xml
+   <?xml version="1.0" encoding="UTF-8"?>
+   <CaseSettings xmlns="http://soap.sforce.com/2006/04/metadata">
+       <emailToCase>
+           <enableEmailToCase>true</enableEmailToCase>
+           <enableOnDemandEmailToCase>true</enableOnDemandEmailToCase>
+           <routingAddresses>
+               <addressType>EmailToCase</addressType>
+               <botEmailDefinition>{BOT_EMAIL_DEFINITION_NAME}</botEmailDefinition>
+               <caseOrigin>Email</caseOrigin>
+               <casePriority>Medium</casePriority>
+               <caseOwner>{BOT_USER_USERNAME}</caseOwner>
+               <caseOwnerType>User</caseOwnerType>
+               <emailAddress>{SUPPORT_EMAIL}</emailAddress>
+               <routingName>{ROUTING_NAME}</routingName>
+           </routingAddresses>
+           <!-- Path B: replace <caseOwner>/<caseOwnerType> with
+                <fallbackQueue>{QUEUE_DEVELOPER_NAME}</fallbackQueue> + <routingFlow>{INBOUND_FLOW_DEVELOPER_NAME}</routingFlow>.
+                casePriority is required. Include whatever else the read returned (minus emailServicesAddress/isVerified).
+                Repeat <routingAddresses> for every OTHER existing address, without botEmailDefinition/caseOwner/routingFlow. -->
+       </emailToCase>
+   </CaseSettings>
+   ```
+
+3. **Deploy in metadata format** so the version comes from the manifest — do **not** mutate `sfdx-project.json`. A source deploy of `Settings:Case` reads `sourceApiVersion` (which `--api-version` does not override), so pinning it there would persist to every later deploy in the user's project. Assemble a metadata-format package versioned at `ORG_API_VERSION` (already ≥68.0 from the Precondition — `botEmailDefinition` on a routing address needs v68.0+):
+   ```bash
+   MDDIR=/tmp/sfskills/casesettings-mdapi
+   mkdir -p "$MDDIR/settings"
+   # package.xml: from assets/settings-mdapi-package.xml, {API_VERSION} = ORG_API_VERSION.
+   sed -e "s/{API_VERSION}/{ORG_API_VERSION}/" \
+       assets/settings-mdapi-package.xml > "$MDDIR/package.xml"
+   # component file: the Case.settings-meta.xml from step 2, WITHOUT the -meta.xml suffix
+   cp <path-from-step-2>/Case.settings-meta.xml "$MDDIR/settings/Case.settings"
+   sf project deploy start --metadata-dir "$MDDIR" --target-org $ORG --json
+   ```
+
+Verify the read-back (`emailToCase.routingAddresses`): the **set of `emailAddress` values matches the pre-deploy set** — not just that the count is unchanged, since a dropped-and-added swap preserves the count — and the target address (`{SUPPORT_EMAIL}`) now carries `<botEmailDefinition>{BOT_EMAIL_DEFINITION_NAME}</botEmailDefinition>` and the chosen path's fields (`<caseOwner>` with `caseOwnerType` `User`, or `<routingFlow>`+`<fallbackQueue>`). If any pre-deploy address is missing from the read-back, stop and surface it — a live routing address was unbound.
+
+Branch C is complete once the binding is verified. Outbound escalation is added via Phase 3 (`agent-wiring.md`) exactly like the other channels — offer it rather than skipping it (the user can decline; it does not block inbound completion). If you already batched the outbound route into the Step 3 `connection service_email:` block, escalation is done — just confirm `outboundRouteName`/`outboundRouteType` round-tripped (per `agent-wiring.md`) instead of republishing.
+
+### If escalation was wired — surface the runtime prerequisites
+
+If (and only if) outbound escalation was set up for this agent — batched into the Step 3 `connection service_email:` block, or added later via Phase 3 (`agent-wiring.md`) — present this note to the user **verbatim** after the agent is republished:
+
+> **Escalation is now wired to your agent — but a few org-level Omni-Channel settings must be in place before an escalated case can actually reach a human.** This skill configured the agent and the routing flow; the rest is runtime setup an admin controls:
+> - **Omni-Channel is enabled** in the org.
+> - A **Service Presence Status** exists that includes the **Case-based service channel**, and your human agents can access it (granted via permission set or profile).
+> - Agents are assigned to a **Presence Configuration** (the org's *Default* covers all users unless you've narrowed it) with **capacity** to spare.
+> - The human agent is a **member of the queue** that the flow routes to.
+> - The human agent is **Online in Omni-Channel** under that presence status and **accepts** the incoming work when it's offered.
+
+## Next steps — recommend authoring topics and actions
+
+After confirming the agent is published and wired to Email-to-Case, surface this recommendation to the user:
+
+> Your agent is now published and wired to Email-to-Case, so it can reply to inbound email. To give it real capabilities — reading or updating records, creating cases, escalating, or answering from knowledge — author its topics and actions with the `agentforce-generate` skill, which creates topics and actions along with the Flows, Apex, or prompt templates that back them. Consider how each data-touching action should authorize the requester — for example, scope reads and changes to records tied to the inbound sender's email address.

package/skills/service-agentforce-channel-configure/references/channel-types.md

@@ -7,7 +7,7 @@
 | Enhanced Chat | `MessagingSession` | Branch A — set `sessionHandlerAsa` on MessagingChannel | `sfdc_livemessage` | `Messaging` |
 | Enhanced Messaging (3rd-party: WhatsApp, SMS, etc.) | `MessagingSession` | Branch A — set `sessionHandlerAsa` on MessagingChannel | `sfdc_livemessage` | `Messaging` |
 | Voice | `VoiceCall` | Branch B — create inbound RoutingFlow (`routingType: Copilot`) | `sfdc_phone` | `Phone` |
-| Email-to-Case | `Case` | Branch C — create inbound RoutingFlow (`routingType: Copilot`) | *(query required — see below)* | *(query required)* |
+| Service Email (Email-to-Case) | `Case` | Branch C — create inbound RoutingFlow (`routingType: Copilot`) | *(query required — see below)* | *(query required)* |
 
 ## Email-to-Case: query the org-specific ServiceChannel
 
@@ -15,13 +15,40 @@ The Case-based ServiceChannel DeveloperName and Label are not system-generated a
 
 ```bash
 sf data query --target-org $ORG --json \
-  --query "SELECT DeveloperName, MasterLabel FROM ServiceChannel WHERE RelatedEntityType='Case'"
+  --query "SELECT DeveloperName, MasterLabel FROM ServiceChannel WHERE RelatedEntity='Case'"
 ```
 
-- **Zero rows** → stop; surface gap to user. The channel cannot be wired until a Case-based ServiceChannel exists.
+The SObject column is `RelatedEntity` — `RelatedEntityType` is the *metadata* field name (used in the deploy below) and errors as `No such column` in SOQL.
+
+- **Zero rows** → no Case-based ServiceChannel exists yet. This is **provisionable, not a dead end** — tell the user one is required for routing and provision it (see "Provision a Case ServiceChannel" below), then continue with the new channel's `DeveloperName`/`MasterLabel`.
 - **One row** → use its `DeveloperName` as `SERVICE_CHANNEL_DEV_NAME` and `MasterLabel` as `SERVICE_CHANNEL_LABEL`.
 - **Multiple rows** → ask user to choose via `AskUserQuestion`.
 
+### Provision a Case ServiceChannel (Branch C only)
+
+This applies **only to Branch C (Email-to-Case)** — Branches A and B use the fixed system channels `sfdc_livemessage`/`sfdc_phone`, which always exist and never reach this path.
+
+When none exists, deploy one. `ServiceChannel` is in the SDR registry and has no v68-only fields, so a source deploy is fine (no `sourceApiVersion` concern). Write `serviceChannels/Case_Channel.serviceChannel-meta.xml` under the project's package directory:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<ServiceChannel xmlns="http://soap.sforce.com/2006/04/metadata">
+    <doesMinimizeWidgetOnAccept>false</doesMinimizeWidgetOnAccept>
+    <hasAutoAcceptEnabled>false</hasAutoAcceptEnabled>
+    <isInterruptible>false</isInterruptible>
+    <label>Cases</label>
+    <relatedEntityType>Case</relatedEntityType>
+</ServiceChannel>
+```
+
+The *metadata* field is `relatedEntityType` (here), while the SOQL column queried above is `RelatedEntity` — don't conflate them. Deploy:
+
+```bash
+sf project deploy start --metadata "ServiceChannel:Case_Channel" --target-org $ORG --json
+```
+
+Then use `Case_Channel` as `SERVICE_CHANNEL_DEV_NAME` and `Cases` as `SERVICE_CHANNEL_LABEL`. Deploy-time only needs the channel to exist; live Omni routing additionally needs presence configuration (reps online) before work actually routes.
+
 ## Voice: native vs partner — MUST CHECK before Branch B
 
 Branch B only works with **native Service Cloud Voice**. Partner telephony providers (Amazon Connect, Genesys, Avaya, etc.) manage their own routing pipelines and do not honour Salesforce RoutingFlows — wiring the agent via `routingType: Copilot` on a partner channel will have no effect.