@salesforce/afv-skills 1.40.0 → 1.41.0

package/skills/service-helpagent-coordinate/references/channel-voice.md

@@ -1,17 +1,46 @@
-# Channel branch — Voice *(Coming soon)*
+# Channel branch — Voice
 
-> **When to read this file.** Load it only if the user selected **Voice** at Checkpoint 3.
+> **When to read this file.** Load it only when the user has selected **Voice** at Checkpoint 3 of `assets/help-agent-spec.md`. If they selected Web Chat, read `channel-web-chat.md` instead. If they selected Help Portal, delegate to the sibling skill `service-concierge-portal-generate` — do not inline portal steps here.
 
-## Coming-soon channel — do not build supporting metadata
+Voice wires the Help Agent to an existing `PstnVoice` MessagingChannel via an inbound RoutingFlow. It does **not** provision a new phone number — number acquisition puts the org in a state that isn't cleanly retrievable, so it's out of scope for this skill. If the user has no `PstnVoice` channel yet, tell them to provision the number in Setup (Service Cloud Voice / Number Management) first, then come back.
 
-Voice is **not yet supported** as a first-class channel. Do not provision a phone number, stand up routing, configure Amazon Connect, or create adjacent objects "toward" the feature — that produces broken half-configurations. **Do not write a Voice setup plan, a "here's what I would do" outline, or a "planning-only" scaffold either** — describing the steps is still treating a coming-soon channel as a build target. The only correct output for a Voice selection is the verbatim hard-stop message below, followed by re-presenting the channel options. The channel-selection step treats Voice as a coming-soon option alongside Help Portal; the safe response is to steer the user to Web Chat:
+---
 
-> *"This feature is coming soon, please select Web Chat."*
+## Existing number path
 
-## If the user insists on an existing number
+Query existing channels:
 
-If the user provides an **existing** phone number and asks you to wire it up, you may attempt it — but exit gracefully the moment the APIs aren't there:
+```bash
+sf data query --target-org $ORG --json \
+  --query "SELECT Id, DeveloperName, MasterLabel, MessagingPlatformKey, IsActive FROM MessagingChannel WHERE MessageType='PstnVoice' ORDER BY MasterLabel"
+```
 
-- If the org's APIs to procure or attach a phone number are not available, **gracefully exit this branch.** Say something like: *"I can't set up Voice automatically in this org right now, so I'll skip it. You can add Voice later from Setup."* — then continue with any other selected channels.
+If none are returned, stop and tell the user to provision a phone number and `PstnVoice` MessagingChannel in Setup first — this skill does not create one.
 
-Do not abort the whole setup over Voice. If Voice was one of several selected channels, report the skip plainly and proceed with the others.
+If any are returned, present them and let the user choose. Capture the channel's `DeveloperName` as `CHANNEL_DEV_NAME`, then continue to **Step 8 — Wire the channel to the agent**. Fallback queue resolution (including the `SobjectType='VoiceCall'` requirement) is owned by `service-agentforce-channel-configure` — do not resolve or create the queue here.
+
+---
+
+## Step 8 — Wire the channel to the agent
+
+Delegate to `service-agentforce-channel-configure` Branch B. Pass:
+- **Agent DeveloperName** — the Help Agent
+- **Channel type** — Voice
+- **Channel identifier** — `CHANNEL_DEV_NAME`
+
+The delegated skill resolves and configures the fallback queue itself.
+
+---
+
+## Step 9 — Loop
+
+Return to the Checkpoint 3 loop — offer the user the option to add another channel or proceed to go-live.
+
+---
+
+## Rules / constraints
+
+| Rule | Rationale |
+|---|---|
+| This skill never acquires a phone number | Provisioning puts the org in a state that isn't cleanly retrievable — must be done in Setup before this skill runs |
+| Never resolve or create the fallback queue here | `service-agentforce-channel-configure` owns queue resolution end to end — resolving it twice can double-prompt the user |

package/skills/service-helpagent-coordinate/references/channel-web-chat.md

@@ -1,6 +1,6 @@
 # Channel branch — Web Chat
 
-> **When to read this file.** Load it only when the user has selected **Web Chat** at Checkpoint 3. If they selected Help Portal or Voice, read the matching `channel-help-portal.md` / `channel-voice.md` instead. You do not need all three channel files in context at once — read only the branch the user chose.
+> **When to read this file.** Load it only when the user has selected **Web Chat** at Checkpoint 3. If they selected Voice, read `channel-voice.md` instead. If they selected Help Portal, delegate to the sibling skill `service-concierge-portal-generate` — do not inline portal steps here. You do not need every channel file in context at once — read only the branch the user chose.
 
 Web Chat embeds a chat widget on a website. This branch provisions a messaging channel + omni-channel routing, a new Embedded Service Deployment (`Help Chat`), and a prepared LWR Experience Cloud site. The agent script does **not** change here — this is channel/site metadata around the agent.
 
@@ -10,6 +10,11 @@ Ask the user for **the domain** where the widget will live (e.g. `support.acme.c
 
 ## Step B — CRITICAL, DO NOT SKIP: ask who will be chatting
 
+**Step B checklist (do all three, in order):**
+1. **Audience** — ask (or infer from the prompt) who will chat: `Public / anonymous`, `Both anonymous and authenticated (default)`, or `Authenticated only`.
+2. **`authMode`** — map audience → `authMode`: anonymous or mixed → `UnAuth`; authenticated-only → `Auth`. Name the chosen value explicitly in the settled-facts report as a bare value (`authMode: UnAuth`).
+3. **Post-deploy assertion** — after the channel is deployed in Step C, re-fetch the MessagingChannel and assert `embeddedConfig.authMode` matches the chosen value; if it doesn't, surface the discrepancy and stop the Web Chat branch. Always run this assertion.
+
 This determines the MessagingChannel's `embeddedConfig.authMode`, which is set when the channel is deployed in Step C below. Choosing wrong silently breaks the deployment: the widget refuses to render on the Setup → ESD → "Test Enhanced Web Chat" page and for any anonymous visitor on the live site, with no error surfaced to the user. This is the single highest-risk decision in the Web Chat branch — previous runs defaulted to `Auth` and shipped a non-functional deployment that took manual debugging to discover. Ask explicitly and confirm the answer back to the user before proceeding.
 
 Present three options:
@@ -17,59 +22,178 @@ Present three options:
 2. **Both anonymous and authenticated visitors** *(default — recommended for any customer-facing portal)* → `authMode = UnAuth`. Despite the name, `UnAuth` *allows* both: guests chat anonymously, and signed-in users can upgrade the session by passing an `identityToken` at runtime.
 3. **Authenticated visitors only** (no guests) → `authMode = Auth`. **Warn the user verbatim:** *"This requires your host app to mint a verified-user JWT for every visitor. The Setup → ESD → 'Test Enhanced Web Chat' button will not work because it loads the widget as a guest, and anonymous visitors on your Experience site will fail to load the chat. Pick this only if you have JWT issuance in place."*
 
-Default to option 2 if the user is unsure. Never silently pick `Auth`. After the channel is deployed in Step C, fetch the MessagingChannel back and assert `embeddedConfig.authMode` matches the chosen value; if it doesn't, surface the discrepancy and stop the Web Chat branch. Always run the post-deploy re-fetch assertion. **The final `report.md` names the chosen `authMode` as a bare value (`authMode: UnAuth`) — do not narrate the rationale or the assertion in the report.** Never emit a legacy `esw.min.js` / Live Agent V1 bootstrap snippet — the V2 widget mounts via the `experience_messaging:embeddedMessaging` LWR component (Step C.3, Checkpoint 3.5 Check 3b).
+Default to option 2 if the user is unsure. Never silently pick `Auth`. Never emit a legacy `esw.min.js` / Live Agent V1 bootstrap snippet — the V2 widget mounts via the `experience_messaging:embeddedMessaging` LWR component (Step C.3, Checkpoint 3.5 Check 3b).
 
 ## Step C — Provision (in order)
 
-1. Deploy the messaging channel + omni-channel routing (`service-digital-engagement-channel-configure`, channel deploys INACTIVE). **Set `embeddedConfig.authMode` from the choice in Step B.** For `UnAuth`, also set `anonymousUserJwtExpirationTime` (e.g. `360`). For `Auth`, set `verifiedUserJwtExpirationTime` (e.g. `60`).
-   > **Note on the ASA routing field.** The MessagingChannel field that binds an AgentforceServiceAgent as the session handler is `sessionHandlerAsa` — **not** `sessionHandlerFlow`. If you see `sessionHandlerFlow` in an older template or reference, that's for Flow-backed routing, not agent-backed. `service-digital-engagement-channel-configure` should set `sessionHandlerAsa` when the channel's routing type is `AgentforceServiceAgent`; verify this in the deployed channel before continuing.
-2. Activate the MessagingChannel after the agent is Active (and re-verify at Checkpoint 4 — see step 4 below).
-3. **Create a NEW Embedded Service Deployment named `Help Chat`** (DeveloperName `HelpChat`, MasterLabel `Help Chat`) bound to the user's domain (`service-digital-engagement-deployment-configure`). **Do NOT re-point or re-use any existing ESD from a prior deployment** — the Experience Builder dropdown must show `Help Chat` as a distinct option that the user can select when dragging the Embedded Messaging component onto the page. If creating the ESD requires a Connect API endpoint that's not available in this org, surface the gap to the user and stop the Web Chat branch — do not silently fall back to mutating an existing deployment.
-
-   > **MANDATORY: Create as V2 (`WebV2`) via the Connect API — never via bare Metadata deploy.** The Metadata API path for `EmbeddedServiceConfig` defaults to legacy V1 (Live Agent-shaped), which shows up in the Setup UI as *"Web (v1)"* with a *"Switch to V2"* button and **does not work with Enhanced Web Chat / MIAW / Agentforce Service Agent routing**. Enhanced Web Chat requires V2. Use the Connect API on API v67.0+ (older versions return 404 for this endpoint):
-   >
-   > ```http
-   > POST /services/data/v67.0/connect/embeddedmessaging/deployment/setup
-   > {
-   >   "name": "HelpChat",
-   >   "masterLabel": "Help Chat",
-   >   "deploymentType": "Web",
-   >   "clientVersion": "WebV2",
-   >   "hostDomain": "<the domain from Step A, e.g. support.acme.com>",
-   >   "messagingChannelId": "<18-char MessagingChannel record Id from Step C.1>"
-   > }
-   > ```
-   >
-   > **CRITICAL — `messagingChannelId` is REQUIRED and is the single most common cause of an ESD that won't publish.** The `deployment/setup` call only publishes when a messaging channel is bound to it. Omit `messagingChannelId` and the ESD is created but stays **unpublished** — the Setup UI shows the deployment with *Published on:* / *Version:* **empty** and a red banner *"Select a Messaging Channel and then try publishing again."* on the Publish button. This is not fixable by clicking Publish in the UI (there is no channel to select on a V2 deployment there); it must be bound at creation time. Because Step C.1 creates the channel first (INACTIVE), its record Id is already available here — query it and pass it:
-   > ```bash
-   > sf data query --query "SELECT Id FROM MessagingChannel WHERE DeveloperName = 'HelpChat'" --target-org <alias>
-   > ```
-   > Also pass `hostDomain` (the domain from Step A) — it ties the widget's security key to that domain.
-   >
-   > **With the channel bound, the successful response includes `"isPublishSuccess": true` — the ESD is created *and* published in a single call.** There is no separate "publish" step to run afterwards. `EmbeddedServiceConfigPub` (the internal published-snapshot sObject) is not exposed via REST/Tooling/Metadata/Apex, so there is no other supported API to trigger publish; do not attempt bare `sf project deploy start -m EmbeddedServiceConfig:HelpChat` and expect it to publish (it deploys the config but leaves *Published on:* / *Version:* empty, which reads as unpublished in the Setup UI even though `IsEnabled=true`). **If the response comes back with `"isPublishSuccess": false` or the UI shows the "Select a Messaging Channel" banner, the channel was not bound — delete the ESD and recreate with `messagingChannelId` in the body.**
-   >
-   > If a legacy V1 `HelpChat` ESD already exists (e.g. from a prior run before this fix), **delete it first** (`sf project delete source -m EmbeddedServiceConfig:HelpChat`), then recreate via the Connect API path above — the V1→V2 in-place upgrade is a UI-only "Switch to V2" button that has no supported API equivalent, so recreation is the reliable path.
-
-   > **Note on the auto-generated `<site>` field on the ESD itself.** The Connect API `deployment/setup` call auto-generates an internal site (two rows in `Site`, e.g. `ESW_HelpChat_<timestamp>` and `ESW_HelpChat_<timestamp>1`) for the ESD's own endpoint. Attempting to overwrite the site field via a Metadata deploy fails with an immutable-field error — the ESD's own site cannot be re-pointed. The ESD's endpoint URL (`https://<myDomainStem>.my.site.com/<UrlPathPrefix>`, where `<UrlPathPrefix>` is the row **without** the `vforcesite` suffix) IS the value the V2 LWR component takes as `siteEndpoint` — capture it from `SELECT Name, UrlPathPrefix FROM Site WHERE Name LIKE 'ESW_<EsdDeveloperName>%'` and hand it to Checkpoint 3.5 Check 3(b). **The customer-facing widget on the LWR site is embedded via the `experience_messaging:embeddedMessaging` LWR component in `homeGuestLayout.json` (+ `homeAuthenticated.json` if needed), with a six-attribute `componentAttributes` payload built around `deploymentName: "<EsdDeveloperName>"` and `clientVersion: "WebV2"`.** Do not embed via a bootstrap `<script>` in `mainAppPage.json` `headMarkup`; the correct key is `deploymentName` (not `configurationName`, which is stripped on deploy), and the six-attribute V2 shape round-trips cleanly through metadata deploy/retrieve. See Checkpoint 3.5 Check 3(b) for the full shape and end-to-end path.
-
-   > **Note on patching an existing V2 ESD (guest access, branding, etc.).** Do NOT use the Metadata API to patch an existing V2 ESD — even a no-op deploy that passes the current `site` value unchanged fails with an immutable-field error. Use the **Tooling API** instead: `PATCH /services/data/v67.0/tooling/sobjects/EmbeddedServiceConfig/<id>` with a `{"Metadata": {...}}` body. GET the current `Metadata` object first and include **every** field on the PATCH — omitting `clientVersion`, `branding`, `masterLabel`, or `deploymentType` nulls them out. Successful PATCH returns HTTP 204. Common use cases: setting `areGuestUsersAllowed: true` for a public-visitor site, updating `branding` to point at a customized BrandingSet, or toggling `isTermsAndConditionsEnabled`.
-
-   > **Verifying V2 published state after creation.**
-   > - **In the UI:** open Setup → Embedded Service Deployments → **Help Chat**. The title should read *"Embedded Service Deployment Settings - Web"* with **no `(v1)` suffix** and **no "Switch to V2" button**. The top-right should show *"Published on: {date}"* and *"Version: 1"* (not empty).
-   > - **Via API:** query the ESD and confirm the underlying metadata has `clientVersion: WebV2`. If `Published on:` is empty in the UI or the response shows `WebV1`, the Connect API path was not taken — delete and recreate.
-4. Locate an existing LWR Experience Cloud site (or create one) and prepare it for the user to drop the widget on in Checkpoint 4. **Query-first pattern — do not hardcode a site name:**
-   ```sql
-   SELECT Id, Name, UrlPathPrefix, SiteType, Status
-   FROM Site
-   WHERE SiteType = 'ChatterNetworkPicasso'
-     AND Status = 'Live'
+### C.0 — Resolve escalation queue
+
+Run immediately after Step B (before any deploy), once the channel type is known.
+
+**Query existing queues that already support the relevant SobjectType for this channel:**
+
+| Channel | SobjectType |
+|---|---|
+| Web Chat / Help Portal / WhatsApp / SMS / Messaging | `MessagingSession` |
+| Voice / Phone | `VoiceCall` |
+| Email / Case | `Case` |
+
+```bash
+sf data query --target-org $ORG --json \
+  --query "SELECT Queue.Name, Queue.DeveloperName, Queue.Id
+           FROM QueueSobject
+           WHERE SobjectType='MessagingSession'"
+```
+
+Branch via `AskUserQuestion`:
+- **One or more queues found** → present each as an option (`{Name} ({DeveloperName})`), plus a final option *"Create a new queue for this agent"*. If the user picks an existing queue, capture its `DeveloperName` and skip queue-creation below.
+- **Zero queues found** → inform the user no compatible queue exists and proceed to create one.
+
+**If creating a new queue:**
+
+1. Name: `{AgentLabel} Queue`, DeveloperName: `{AgentDevName}_Queue`
+2. Create the `Group` record:
+   ```bash
+   QUEUE_ID=$(sf data create record --target-org $ORG \
+     --sobject Group \
+     --values "Type='Queue' Name='{AgentLabel} Queue' DeveloperName='{AgentDevName}_Queue'" \
+     --json | python3 -c "import sys,json; print(json.load(sys.stdin)['result']['id'])")
+   ```
+3. Grant the queue access to `MessagingSession`:
+   ```bash
+   sf data create record --target-org $ORG \
+     --sobject QueueSobject \
+     --values "QueueId='$QUEUE_ID' SobjectType='MessagingSession'"
    ```
-   - **Zero Live LWR sites found** → defer to `experience-lwr-site-generate` to create one. Ask the user for a site name and URL path prefix; recommend the *Help Center* template as the natural default for this use case, since it's built around Knowledge browsing + a chat widget.
-   - **Exactly one Live LWR site found** → **do not silently use it. Confirm with the user first.** Present the found site (Name + UrlPathPrefix + Id) and ask explicitly: *"Use this existing site for the Help Agent, or create a new one via `experience-lwr-site-generate`?"* — never assume the sole Live site is the right target. On a customer production org, an existing Experience Cloud site may be dedicated to a different audience (partner community, employee portal, marketing site) and wiring the Help Agent onto it would be intrusive. Only proceed once the user has explicitly confirmed which path to take.
-   - **Multiple Live LWR sites found** → list them (Name + UrlPathPrefix) and ask the user which one to target. Do not silently pick. Include a "create a new site instead" option in the list.
+4. Add the executing user to the queue:
+   ```bash
+   RUNNING_USER_ID=$(sf org display --target-org $ORG --json \
+     | python3 -c "import sys,json; print(json.load(sys.stdin)['result']['userId'])")
+   sf data create record --target-org $ORG \
+     --sobject GroupMember \
+     --values "GroupId='$QUEUE_ID' UserOrGroupId='$RUNNING_USER_ID'"
+   ```
+
+Capture the resolved `QUEUE_DEVELOPER_NAME` (either from an existing queue or the one just created). It is used in both Step C.1 (MessagingChannel `sessionHandlerQueue`) and Step C.2 (RoutingFlow queue lookup).
+
+---
+
+### C.1 — Create the Outbound (Escalation) RoutingFlow
+
+> **This step is owned by `service-agentforce-channel-configure` Phase 3.** The full template, naming convention, check-before-create logic, and deploy/verify steps are in that skill's `routing-flow.md` Part 2. Follow that reference — do not duplicate the XML here.
+
+For Web Chat, the channel type label is **Enhanced Chat**, so:
+- Flow label: `{AgentLabel} Outbound Enhanced Chat Flow`
+- DeveloperName: `{AgentDevName}_Outbound_Enhanced_Chat_Flow`
+- `SERVICE_CHANNEL_DEV_NAME`: `sfdc_livemessage`, `SERVICE_CHANNEL_LABEL`: `Messaging`
+- Queue: `QUEUE_DEVELOPER_NAME` from Step C.0
+
+Follow the template and steps in `service-agentforce-channel-configure`'s `routing-flow.md` Part 2. Capture `{FLOW_DEVELOPER_NAME}` for use in the agent's `connection customer_web_client:` block at Checkpoint 4 (`outbound_route_name: "flow://{FLOW_DEVELOPER_NAME}"`). Note: Web Chat uses `connection customer_web_client:` — not `connection messaging:` — see `service-agentforce-channel-configure`'s `agent-wiring.md`.
+
+---
+
+### C.2 — Deploy MessagingChannel
+
+Deploy the messaging channel + omni-channel routing (`service-digital-engagement-channel-configure`, channel deploys INACTIVE). **Set `embeddedConfig.authMode` from the choice in Step B.** For `UnAuth`, also set `anonymousUserJwtExpirationTime` (e.g. `360`). For `Auth`, set `verifiedUserJwtExpirationTime` (e.g. `60`). Set `sessionHandlerQueue` to the `QUEUE_DEVELOPER_NAME` resolved in Step C.0.
+
+   > **v67 ASA routing note.** `service-digital-engagement-channel-configure` handles the v67 limitation automatically for ASA routing: it deploys the XML without `sessionHandlerAsa` (rejected by the Metadata API), then binds `SessionHandlerId` + `FallbackQueueId` via Data API PATCH (its step 15a). Verify both fields are non-null after the skill completes. Also ensure the bot is Active before invoking the skill — the PATCH is rejected with "Only active Agentforce Service Agents are supported" otherwise.
+
+### C.3 — Activate MessagingChannel
+
+Activate the MessagingChannel after the agent is Active (and re-verify at Checkpoint 4).
+
+### C.4 — Create a NEW Embedded Service Deployment named `Help Chat`
+
+Delegate to **`service-digital-engagement-deployment-configure`** with these inputs:
+
+- **Operation**: `create`
+- **Deployment type**: `Web`
+- **Deployment name / DeveloperName**: `HelpChat` / MasterLabel `Help Chat`
+- **Channel**: MessagingChannel DeveloperName from Step C.1 (skill will query the record Id)
+- **hostDomain**: the customer domain from Step A (e.g. `support.acme.com`) — ties the widget's security key to that domain
+
+The skill creates the ESD via `POST /connect/embeddedmessaging/deployment/setup` (V2, Connect API), binds the messaging channel at creation time so `isPublishSuccess: true` is returned, and auto-generates the `ESW_*` scaffolding site. **Do NOT re-point or re-use any existing ESD from a prior deployment.**
+
+After the skill completes, capture the ESC Id:
+
+```bash
+sf data query --target-org $ORG --use-tooling-api \
+  -q "SELECT Id FROM EmbeddedServiceConfig WHERE DeveloperName='HelpChat'" --json \
+  | python3 -c "import sys,json;print(json.load(sys.stdin)['result']['records'][0]['Id'])"
+```
+
+The ESD's endpoint URL (needed for the `siteEndpoint` attribute on the LWR component) is the `ESW_HelpChat_*` site row **without** the `vforcesite` suffix:
+
+```bash
+sf data query --target-org $ORG \
+  -q "SELECT Name, UrlPathPrefix FROM Site WHERE Name LIKE 'ESW_HelpChat%' AND SiteType='ChatterNetworkPicasso'" --json
+```
+
+Pass `siteEndpoint` (`https://<myDomainStem>.my.site.com/<UrlPathPrefix>`) to Checkpoint 3.5 Check 3(b).
+### C.5 — Resolve deployment target (Experience Cloud site or own website)
+
+Ask the user where they want to deploy the chat widget via `AskUserQuestion`:
+- **"I'll embed it on my own website"** *(Recommended for most customers)* — skip Experience Cloud site creation. The ESD was already created above without a `<site>` reference; skip widget injection (Steps D.1–D.7). Proceed to Step D.8 for the embed snippet instructions.
+- **"Deploy on a Salesforce Experience Cloud site"** — continue with the site resolution below.
+
+**If Experience Cloud path:** Query for real (non-auto-generated) sites — both LWR and Aura:
+
+```bash
+sf data query --target-org $ORG --json \
+  --query "SELECT Id, Name, MasterLabel, UrlPathPrefix, SiteType, Status FROM Site WHERE Status='Active' AND SiteType IN ('ChatterNetworkPicasso','ChatterNetwork') ORDER BY SiteType, Name" \
+  | python3 -c "
+import sys, json
+recs = json.load(sys.stdin)['result']['records']
+real = [r for r in recs if not r['Name'].startswith('ESW_')]
+esw  = [r for r in recs if r['Name'].startswith('ESW_')]
+
+for r in real:
+    r['_type'] = 'LWR' if r['SiteType'] == 'ChatterNetworkPicasso' else 'Aura'
+
+print(f'Real sites: {len(real)} ({sum(1 for r in real if r[\"_type\"]==\"LWR\")} LWR, {sum(1 for r in real if r[\"_type\"]==\"Aura\")} Aura) | ESW-filtered: {len(esw)}')
+for r in real:
+    print(f'  {r[\"MasterLabel\"]:40} ({r[\"_type\"]}) | /{r[\"UrlPathPrefix\"]}')
+"
+```
+
+> **ESW filtering — why and how:** Every ESD auto-creates a pair of `Site` records named `ESW_{EsdName}_{timestamp}` (one Aura, one LWR). These are internal endpoint scaffolding, not real Experience Cloud destinations. SOQL `NOT LIKE` cannot be combined with `AND` in the `sf data query` CLI without a shell-quoting error, so filter them out in Python post-processing as shown above. If all sites after filtering are ESW-prefixed, treat as "zero real sites found."
+>
+> **Duplicate MasterLabels:** Each real Experience Cloud site generates two `Site` records with the same `MasterLabel` — one `ChatterNetwork` (Aura) and one `ChatterNetworkPicasso` (LWR). Both are shown to the user. The `SiteType` on the record the user picks determines which metadata layout path `service-digital-engagement-messaging-site-integrate` follows (LWR: patches `sfdc_cms__themeLayout/*/content.json` footer regions; Aura: patches `homeGuestLayout.json`).
+>
+> **Status value:** `Site.Status` is `'Active'` (not `'Live'`) on all org shapes tested. Using `'Live'` returns zero rows.
+
+**Branch by what's found:**
+
+- **Zero real sites found** → ask: deploy on own website (give snippet), or create a new LWR Experience Cloud site via `experience-lwr-site-generate` (recommend *Help Center* template).
+
+- **Real sites found** → present using the **long-list presentation rules** from SKILL.md. Do not label sites as LWR/Aura — show each as `{MasterLabel} (/{UrlPathPrefix})`. Always include "Create a new Experience Cloud site" and "Deploy on my own website (get snippet)" as fixed options on the final page.
+
+**After the user selects:**
+
+- **Site selected (either type)** → delegate to `service-digital-engagement-messaging-site-integrate`. The skill reads `SiteType` from the selected site's record and patches the correct layout automatically (LWR: `sfdc_cms__themeLayout/*/content.json` footer regions; Aura: `homeGuestLayout.json` and `homeAuthenticated.json`). After the skill completes, confirm: *"The chat widget has been added to [site name] and will appear as a floating overlay on every page."* Publish the site and verify the smoke-test URL returns 200.
+- **Own website selected** → proceed to Step D.8 snippet instructions.
+
+Do not filter by any hardcoded site name or `UrlPathPrefix` value — the correct site depends on the customer's org and is not knowable up front.
+
+### C.6 — Wire up knowledge citations The script's `knowledge:` block ships with `citations_enabled: True` and `citations_url: ""` (the URL isn't knowable until a site exists). Once the target site's public URL is resolved here, set `citations_url` to that URL so knowledge answers cite working links. If no customer-facing site URL can be resolved, set `citations_enabled: False` instead — do not leave citations enabled with an empty URL, or answers render broken/empty citation links.
+
+## Step D.8 — Post-setup next steps (Checkpoint 4, after go-live)
+
+Print these after the ESD is published and the channel is Active.
+
+**If deployed on an Experience Cloud site:**
+- Test URL: `https://{siteBaseUrl}/{siteUrlPathPrefix}/s` — open in an incognito browser as a guest. The floating chat launcher should appear. Send a message to confirm the agent responds.
+- Test escalation: say *"I need to speak to a human"* — the agent should transfer to the queue resolved in Step C.0. This requires at least one agent to be available in the Omni-Channel widget in the Service Console; set your own status to Available to test.
+
+**If deploying on own website:**
+- Direct the user to Setup → Embedded Service Deployments → {ESD Name} → **Get Code** to copy the JavaScript snippet. The snippet is org-specific and must be retrieved from Setup — do not attempt to generate or reconstruct it.
+- The snippet goes in the `<head>` or before `</body>` of any page where the widget should appear. It must be served over HTTPS.
 
-   Do not filter by any hardcoded site name or `UrlPathPrefix` value — the correct site depends on the customer's org and is not knowable up front.
-5. **Wire up knowledge citations.** The script's `knowledge:` block ships with `citations_enabled: True` and `citations_url: ""` (the URL isn't knowable until a site exists). Once the target site's public URL is resolved here, set `citations_url` to that URL so knowledge answers cite working links. If no customer-facing site URL can be resolved, set `citations_enabled: False` instead — do not leave citations enabled with an empty URL, or answers render broken/empty citation links.
+**Testing checklist (both paths):**
+1. Agent responds to a greeting → channel is live
+2. Agent answers a question from the knowledge source → grounding is working
+3. Agent escalates to a human when asked → RoutingFlow and queue are wired correctly (requires an agent available in Omni-Channel)
+4. Widget closes and reopens without losing session → widget state is healthy
 
 ## Handoff to Checkpoint 3.5 and Checkpoint 4
 

package/skills/service-helpagent-coordinate/references/output-report-format.md

@@ -0,0 +1,126 @@
+# Output Report Format — Help Agent Setup
+
+> **When to read this file.** Load it right before you write the final `report.md` for a run. This file is the full specification for the two report shapes (settled-facts and guided-decision), the templates, and the failure modes to avoid. `SKILL.md` links here from its Output Expectations section.
+
+## The one deliverable
+
+A single `report.md`: a **status report of what was decided and done**, not a design doc, plan, or architecture write-up. Two rules govern quality:
+
+1. **Report concrete outcomes, never intentions.** Write what *is* — the decided value, the created resource, the resolved ID — not what you *would* or *plan to* do. If a step could not run to completion because this is a non-interactive run, **decide the sensible default, state it as the decision, and report it as such** — do not stall on "awaiting confirmation," "to be resolved," "pending user input," or "please provide…". Hedging language ("will create", "to be executed", "once confirmed") reads as an unfinished plan and is scored as incomplete. Name the agent, the locale, the grounding source, `authMode`, the ADL name, the `rag_feature_config_id`, the site `UrlPathPrefix`, the ESD publish state — as settled facts.
+2. **No padding, no scaffolding prose.** No preamble, no design-doc sections, no restating the prompt. Dense, declarative lines only.
+
+**Density bar (web-chat / portal flows are the usual offenders).** The whole report is the two tables plus the two short sections — target well under ~40 lines total. A table cell is a **value or a short clause, never a sentence with a subject and verb**: `UnAuth` not "The authMode was set to UnAuth"; `Help_Agent_Knowledge (indexing COMPLETED)` not "A dedicated Agentforce Data Library named Help_Agent_Knowledge was created and its indexing completed". Do not restate a decided value across multiple cells, do not narrate the mechanics of how a resource was created (which API, which CLI call, which retrieve/deploy sequence) — that belongs in the skill, not the report — and do not append explanatory prose after a table. State the reasoning callout (readiness ordering, `authMode`) only when the request centers on that one decision; otherwise the value alone suffices.
+
+## Choosing a report shape
+
+**Before writing, choose the report shape by what the run actually did. There are two:**
+
+- **A settled-facts report** — the flow *executed a step*: the user directed a concrete action ("set up the grounding", "put it on <named site>") and every input was supplied or has a sensible skill-owned default. Report what was decided and done.
+- **A guided-decision report** — the flow is at a *decision the user owns*: an opening request with no agent details yet ("set up a help agent", "add a chat widget"), **or** a checkpoint surfacing multiple real alternatives the skill must not invent (e.g. several Live LWR sites). Presenting the checkpoint's questions/options *is* the deliverable; stay draft-first.
+
+Use the settled-facts report, not the guided-decision one, when the missing value is a mechanical default the skill can just pick (data category → org default) — decide it and report it done. Use the guided-decision report only when the choice genuinely belongs to the user (identity at an opener; which of several existing sites). The guided-decision report is **not** an escape hatch for hedging on an execute request.
+
+## Settled-facts report
+
+**Settled-facts report — the flow ran (completed, or blocked mid-execution).** Start with the exact H1 `# Help Agent Setup Report`, then the two tables and two short sections below, in order. Every cell is a **concrete, decided value** — a bare value, not a sentence. Keep prose out.
+
+**Report DECISIONS as settled facts, never placeholders or intentions.** This is a non-interactive run: you do not get to defer. Do NOT emit "to be captured", "not yet reached", "flow is paused", "awaiting", "once confirmed", or "will create". For a value the flow **decides** (agent name, locale, tone, ADL name, `authMode`, data category), state the concrete decision as done — a cell with nothing decided gets `None`. For an **opaque ID the run generates** (the `rag_feature_config_id`, a Salesforce record Id, a site's URL path prefix), report the **actual value produced this run** — never invent a plausible-looking one and never copy an ID from this template; if the run genuinely did not produce it, name that in Blocking Issues rather than fabricating. Hedging is scored as incomplete; fabricated IDs are scored as inaccurate. Include every value below and nothing else.
+
+**Scope the report to the checkpoint(s) the request targeted — do not narrate checkpoints the run never entered.** When the user directs a single checkpoint ("set up the grounding", "ground it on Knowledge" → Checkpoint 2 only), the report centers on that checkpoint. Fill its row with settled facts; give each checkpoint the run did **not** reach a bare `Not started` in its Decision cell — no plan, no "pending", no "not yet reached", no downstream detail. Do **not** manufacture a `Blocking Issues` entry or a `Next Action` about a later checkpoint you were never asked to run: if the targeted checkpoint completed, `Blocking Issues` is `None` and `Next Action` is the single next checkpoint by name (e.g. "Checkpoint 3 (channel) when you're ready"). A report that sprawls into unrequested checkpoints and hedges there is scored as incomplete even when the targeted checkpoint is perfect.
+
+**When the request centers on one decision, carry that decision's reasoning — not a bare value.** Some requests are about a single load-bearing choice: *why the readiness steps run in a specific order*, or *which `authMode` to pick and why*. For these, the targeted cell (or a short `## <Topic>` section right after the tables) must state the **decision, its rationale, and the concrete failure it avoids** — because that reasoning is the deliverable, not scaffolding:
+
+- **Readiness ordering** — give the ordered sequence (licenses / Einstein Agent User → **enable Data Cloud** → **assign Data Cloud permission sets**), say *why* the order is load-bearing (the permission sets do not exist until Data Cloud is enabled — assigning first fails with `PermissionSet not found: GenieUserEnhancedSecurity`), and warn that skipping the assignment yields empty runtime grounding even when ADL indexing reports SUCCESS. Do not compress this to "perm sets assigned". If Data Cloud is not yet enabled on this org, the Readiness row must say so — never assert "Data Cloud enabled; perm sets assigned" while `Blocking Issues` says it isn't; that contradiction is scored as inaccurate.
+- **`authMode` choice** — name the value (`UnAuth` for an anonymous-or-mixed audience), state the rationale (`UnAuth` allows **both** guests and authenticated upgrades via `identityToken`; `Auth` is authenticated-only and silently breaks the guest widget and the Setup "Test Enhanced Web Chat" page), confirm the audience it was chosen for, and state the assertion as a settled part of the flow — "the deployed MessagingChannel is re-fetched and `embeddedConfig.authMode = UnAuth` is asserted" — **present tense, not "will be re-fetched"**. Do not compress this to "authMode UnAuth". The `authMode` decision is complete once chosen: do **not** frame it as pending ("to be confirmed"), and do **not** manufacture a `Blocking Issues` entry or `Next Action` about the *adjacent* site-resolution step — a scoped `authMode` request is not blocked on the LWR site. If nothing stopped the scoped decision, `Blocking Issues` is `None`.
+
+The `‹…›` slots below mark where **this run's** real values go — replace each slot, never emit the slot text itself:
+
+```markdown
+# Help Agent Setup Report
+
+## Setup Summary
+| Field | Value |
+|---|---|
+| Readiness | Data Cloud enabled; perm sets assigned (GenieUserEnhancedSecurity, GenieAnalytics, DataSpacePermSet); Einstein Agent User assigned |
+| Failure mode guarded | Stock NOT_SCHEDULED ADL → empty knowledgeSummary; guarded via dedicated ADL, indexing gated to COMPLETED |
+| Delegation | agentforce-generate → agent + ADL; dx-org-permission-set-assign → Data Cloud perms; service-digital-engagement-* → channel + ESD |
+
+## Checkpoint Outcomes
+| # | Checkpoint | Decision |
+|---|---|---|
+| 1 | Identity | ‹agent name› (‹DeveloperName›), ‹locale›, ‹tone› |
+| 2 | Grounding | Salesforce Knowledge via agentforce-generate; dedicated ADL ‹library name› (stock All_Records_and_Fields_Default not wired); indexing gated to COMPLETED before wiring; rag_feature_config_id ‹ARFPC_ id from this run's adl publish› captured |
+| 3 | Channel | Web Chat; authMode ‹UnAuth or Auth›; site ‹target site UrlPathPrefix›; ESD HelpChat WebV2 — *or* `Not started` if the run never entered this checkpoint |
+| 4 | Go-live | ESD Published; channel Active; escalation flow wired — *or* `Not started` |
+
+## Blocking Issues
+‹the one thing that actually stopped the flow — one line — or `None`›
+
+## Next Action
+One line — the single next step for the user.
+```
+
+Non-slot values above (Data Cloud, perm-set names, `HelpChat WebV2`, delegation targets) are the skill's canonical defaults — reproduce them as-is. Fill the `‹…›` slots from this run (including `authMode`, which is decided per run from the Step B choice — do not default it in the report). **Any checkpoint the run did not reach gets a bare `Not started` — not a plan, forecast, or "pending" note.** For a request scoped to one checkpoint (e.g. Checkpoint 2 grounding), only that row carries settled facts; rows 3 and 4 read `Not started`, `Blocking Issues` is `None`, and `Next Action` names the next checkpoint (e.g. "Checkpoint 3 (channel) when you're ready").
+
+**Blocked run?** `Blocking Issues` is the one sanctioned place to state a real blocker — one honest line there (e.g. "multiple Live LWR sites — asked user to choose"; "Knowledge data category not specified — chose the org's default group") is **required and is not hedging**. It records what stopped a checkpoint the run *actually entered* — never a checkpoint the request never targeted (a scoped Checkpoint-2 run is not "blocked" on Checkpoint 3). Keep the checkpoint cells decisive for what *was* settled; put the single unresolved thing here. What is scored as incomplete is hedging *inside the decision cells* ("to be captured", "not yet", "pending") — not a clear one-line blocker in this section.
+
+### Multi-channel run — trace the loop, don't report one channel
+
+When the request names **two or more channels** ("web chat first, then Voice — add both"), the settled-facts report must show every named channel was wired. One `Not started` in the Channel row, or a Channel cell that names only the first channel with the second framed as "next step" / "to be added", is scored as an incomplete loop. The up-front request authorizes all the named channels, so the flow wires them in order **without** a between-branch `AskUserQuestion` — report that prompt-level authorization, never a user reply that did not occur. Expand the Channel row into a short trace right after the `## Checkpoint Outcomes` table — one row per named channel:
+
+```markdown
+## Channel Loop
+| Step | Outcome |
+|---|---|
+| Channel 1 — ‹type› | ‹settled facts: authMode for Web Chat, resolved site/UrlPathPrefix or phone number, ESD/routing state› |
+| Advance | ‹next named type› named up front in the request → wired next without a between-branch prompt |
+| Channel 2 — ‹type› | re-entered Checkpoint 3; ‹settled facts for this branch› |
+| Go-live | all named channels wired; proceed to go-live |
+```
+
+Only when the prompt did **not** name a channel does the between-branch `AskUserQuestion` run — in that case report the options offered and the actual selection. Every named channel gets a settled outcome (or a one-line blocker in `Blocking Issues` if a branch genuinely could not complete). Do not stop the trace after Channel 1.
+
+## Guided-decision report
+
+**Guided-decision report — a decision the user owns.** Here the deliverable is *the decision point itself*, presented cleanly. This is not hedging: at an opener or a genuine fork, asking with sensible defaults is the correct, complete response. Do **not** provision, deploy, or fabricate the value the user still owns. Orient, present the current checkpoint's choices with defaults, sketch what the remaining checkpoints will cover, and confirm nothing is live yet. Use exactly these sections:
+
+```markdown
+# Help Agent Setup Report
+
+## Guided Setup
+Help Agent setup runs as four checkpoints: identity → grounding → channel → go-live. Nothing is created, deployed, or published until you confirm at each step.
+
+## Current Checkpoint
+Checkpoint ‹n — name›. This agent will ‹map the user's stated needs to the design in one line: knowledge-grounded Q&A from Salesforce Knowledge, support-case create/update, and escalation to a live human when needed›, delivered as ‹the channel the user named, e.g. a Web Chat widget on their site›.
+
+## Decisions Needed
+- ‹Question 1 — offered default› (e.g. Agent name — `Help Agent`, API name `Help_Agent`)
+- ‹Question 2 — offered default› (e.g. Language — `en_US`)
+- ‹Question 3 — offered default› (e.g. Greeting, Tone)
+- ‹…the real choices for THIS checkpoint only; for a multi-option fork, list the actual alternatives found (e.g. each Live LWR site by Name + UrlPathPrefix) and never pick for the user›
+
+## Checkpoint Roadmap
+- Readiness (silent, before provisioning): confirm licenses / Einstein Agent User → enable Data Cloud → assign the Data Cloud permission sets, in that order.
+- 2 Grounding: connect Salesforce Knowledge via a dedicated Agentforce Data Library, indexing gated to COMPLETED.
+- 3 Channel: deploy the chosen channel + Embedded Service Deployment; confirm `authMode` from who will be chatting.
+- 4 Go-live: embed, publish, and verify with a live round-trip — only after you confirm.
+
+## Next Action
+Reply with your choices (or accept the defaults) and I'll proceed to the next checkpoint. Nothing is created, grounded, embedded, or published until you confirm at each step.
+```
+
+Fill every `‹…›` from this run's context. Keep to these five sections — the Roadmap names what later checkpoints will do (it is not a settled-fact table and must not claim any of it is done); no provisioning tables, no settled-fact cells for steps not yet reached.
+
+## Never include
+
+Each of the following is a scored failure:
+
+- A preamble restating the prompt or the request
+- The skills-inventory pre-flight roll call (the eight `OK:` / `resolve-at-runtime:` dependency lines). That check is silent and for your own awareness — it is **not** part of the deliverable. Only name a sibling skill in the report if a delegation step actually reached it and it could not be resolved, and then only that one skill, as a one-line `Blocking Issues` entry.
+- "End of report." trailers
+- Decorative `---` / `===` rules
+- `Scope`, `Assumptions`, `Out-of-Scope`, `Architecture`, `Options Considered`, `Next Steps`, `Steps:`, or `Outcome Gate:` sections
+- The checkpoints re-listed as questions
+- The agent script or reference-file contents pasted inline
+- Emoji
+- Marketing adjectives ("seamless", "robust", "powerful", "comprehensive")

package/skills/service-itsm-agentic-setup-agentforce-coordinate/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: service-itsm-agentic-setup-agentforce-coordinate
+description: "Orchestrator for setting up Agentforce in Salesforce Service Cloud ITSM — Agentforce Studio enablement, the IT Service Fulfiller agent lifecycle, and the IT Service Employee agent lifecycle. Use when the user asks to set up Agentforce for ITSM, enable Studio and the Fulfiller/Employee agents together, wants a guided Agentforce ITSM walkthrough, or asks what Agentforce features are available for IT Service. Presents available Agentforce capabilities and delegates each selection to a specialized child skill while tracking progress. Triggers on: set up agentforce for itsm, configure agentforce studio and fulfiller, agentforce itsm walkthrough, what agentforce features for it service. DO NOT TRIGGER when: the user asks to enable Agentforce Studio alone, asks to create or activate the Fulfiller or Employee agent alone, or asks about CMDB, Incident Management, Teams, or general ITSM setup without Agentforce intent."
+metadata:
+  version: "1.2"
+  domains: ["Service", "Agentforce"]
+  relatedSkills:
+    - "service-itsm-agentic-setup-agentforce-studio-configure"
+    - "service-itsm-agentic-setup-agentforce-studio-validate"
+    - "service-itsm-agentic-setup-employee-agent-configure"
+    - "service-itsm-agentic-setup-fulfiller-agent-configure"
+  cliTools:
+    - tool: ["node"]
+      semver: ">=18.0.0"
+  accessCheck:
+    - type: "license"
+      value: "Agentforce"
+allowed-tools: Read Bash Write AskUserQuestion
+---
+
+# Agentforce for ITSM Setup Orchestrator
+
+Guide the user through setting up Agentforce Studio, the IT Service Fulfiller agent, and the IT Service Employee agent in Salesforce Service Cloud ITSM by presenting the available capabilities, delegating to specialized child skills, and tracking progress.
+
+## Goal
+
+Act as the coordinator for Agentforce feature configuration in ITSM. Present the user with a menu of configurable features, invoke the appropriate child skill for each selection, and after each feature completes, return to the menu with updated progress until the user is done.
+
+## Behavior
+
+### 1. Extract context from conversation
+
+Before presenting options, scan chat history for:
+
+- Which features the user has already set up (skip or mark as done)
+- Any preferences or constraints mentioned (e.g., "just enable Agentforce Studio", "we already have Studio on")
+- The target org (if mentioned)
+- Business context that informs which features are relevant
+
+### 2. Confirm the target org
+
+Agentforce setup performs **writes against a real org** (feature-toggle enablement, agent creation
+and activation). Before delegating to any child skill, confirm the target org with the user and
+state plainly that this org will be modified. Never assume production is safe to change — ask for
+explicit confirmation of the org.
+
+### 3. Present the Agentforce feature menu as a multi-select
+
+Show the user what's available and what's done. Only features with a working child skill appear in the menu — use the **Feature menu** template in `examples/output-templates.md`. Collect the user's selections through a single multi-select prompt (use `AskUserQuestion` with `multiSelect: true` when tooling permits, otherwise ask the user to reply with a list of numbers such as `1, 2`). Do NOT show placeholder features that cannot be executed.
+
+**Report file (harness / non-interactive runs).** If a `${outputDir}` is provided (via the harness's generated-file location directive), write the menu emission (attribution header + feature table with status + delegation targets + dependency signal + the multi-select prompt itself) to `${outputDir}/report.md` **before** raising `AskUserQuestion` — so the report file always exists even when the harness parks at the confirmation gate. Overwrite the same file after each feature completes with the updated status table. Skip these writes when running interactively for a user in a chat surface — write only when `${outputDir}` was passed as an explicit destination.
+
+### 4. Delegate to child skills in dependency order
+
+**Studio-first rule (unconditional).** If Agentforce Studio enablement (#1) is in the user's selection and not already done, run it **first**, always — regardless of the order the user listed their numbers in. Both the Fulfiller Agent (#2) and Employee Agent (#3) lifecycles depend on Studio being enabled and will fail if attempted first. Reorder the queue silently so Studio runs before either agent lifecycle. This rule is non-negotiable and applies whether the user selected two features (Studio + one agent) or all three.
+
+**User-order rule (between #2 and #3 only).** Fulfiller Agent (#2) and Employee Agent (#3) are independent of each other — neither depends on the other. If **both** are selected, run them in the order the user listed them (default 2 → 3 when unspecified). This rule applies **only** to the ordering between #2 and #3; it never overrides the Studio-first rule above.
+
+| # | Feature | Child Skill |
+|---|---------|-------------|
+| 1 | Agentforce Studio enablement | `service-itsm-agentic-setup-agentforce-studio-configure` |
+| 2 | Fulfiller Agent lifecycle | `service-itsm-agentic-setup-fulfiller-agent-configure` |
+| 3 | Employee Agent lifecycle (broad or specialized template) | `service-itsm-agentic-setup-employee-agent-configure` |
+
+`service-itsm-agentic-setup-agentforce-studio-configure` performs its own read-and-classify
+preflight (reading live toggle state before writing) rather than delegating to
+`service-itsm-agentic-setup-agentforce-studio-validate` — that skill is a separate, read-only entry
+point a user can invoke directly to check readiness without writes. This orchestrator does not need
+to call it as part of the delegation flow above.
+
+### 5. After each feature completes
+
+Once a child skill finishes:
+
+1. **Verify** the child skill's own deterministic verdict by running
+   `node "<skill_dir>/scripts/verify-child-verdict.mjs" <studio|fulfiller|employee> <verdict>` — never
+   re-derive the success/failure comparison in prose. Pass Studio's `overall` field from
+   `classify-final-report.mjs`, or Fulfiller/Employee Agent's Phase 8 aggregate verdict, as
+   `<verdict>`. Exit code `0` means advance; exit code `1` means **stop and surface the failure in
+   plain language — do not advance to the next feature in the queue.** A partially-enabled Studio
+   (e.g. Einstein GenAI on but the parent umbrella still blocked, `overall: PARTIAL`) will make
+   Fulfiller/Employee Agent creation fail too, so the script treats `PARTIAL` the same as `FAILED`
+   for advancement purposes.
+2. **Update the status** — mark the completed feature as "Done"
+3. **Suggest the next logical step** — if another feature is available, recommend it based on the dependency order
+4. **Re-present the menu** with updated status — use the **Post-feature progress** template in `examples/output-templates.md`
+
+### 6. Completion summary
+
+When the user says they're done (or all available features are configured), present a final summary using the **Completion summary** template in `examples/output-templates.md`.
+
+---
+
+## Feature Dependencies & Recommended Order
+
+```text
+1. Agentforce Studio enablement   (foundation — org-level Agentforce and Einstein GenAI toggles)
+2. Fulfiller Agent lifecycle      (create, commit, activate the IT Service Fulfiller agent)
+3. Employee Agent lifecycle       (create, commit, activate the IT Service Employee agent)
+```
+
+Agentforce Studio enablement is the foundation: it turns on the org-level Agentforce and Einstein GenAI features that both the Fulfiller and Employee agents depend on. Configure Studio first — attempting to create or activate either agent before Studio is enabled will fail. Fulfiller and Employee are independent siblings (neither depends on the other) — both can be selected together and run in either order after Studio.
+
+---
+
+## Rules
+
+- ALWAYS show "(via service-itsm-agentic-setup-agentforce-coordinate)" in the setup header
+- ALWAYS present the feature menu before doing anything — do not assume which feature the user wants
+- ALWAYS present the feature menu as a multi-select — accept a set of one or more features in a single interaction
+- NEVER set up a feature without the user selecting it. (Explicit selection ensures the user confirms intent and avoids partial configurations if they cancel mid-flow; use the sequential-confirmation loop in the "set up everything" rule for bulk requests.)
+- NEVER show features that do not have a working child skill
+- If the user says "set up everything" or "all", walk through each available feature sequentially in the recommended order, confirming between each step
+- Track progress across the conversation — do not re-present completed features as "Not done"
+- NEVER advance to the next feature in the queue if the current one failed or only partially
+  succeeded — stop and surface the failure in plain language instead
+- If Agentforce Studio enablement reports the org lacks the Agentforce license (`accessCheck`), STOP
+  the whole flow — this is a license/edition prerequisite no API can grant, and neither the
+  Fulfiller nor the Employee Agent lifecycle can succeed without it
+- ALWAYS confirm the target org before delegating to any child skill, and state that the org will be modified
+- Do NOT expose internal technical jargon in user-facing output. This includes Salesforce record
+  IDs and org IDs, raw HTTP status codes (403, 500, …), API error codes (`FUNCTIONALITY_NOT_ENABLED`,
+  `DUPLICATE_VALUE`, …), internal endpoint/API names, developer names (feature apiNames like
+  `sales-cloud-agent-studio`), and CLI/tooling internals. Translate everything to plain, human-readable
+  language. Child-skill names shown as next-step pointers are fine.
+- If the user asks about Agentforce features that are not yet available (e.g., Requester agent, custom topic packs, agent metrics dashboards), tell them those features are not yet available in this orchestrator and will be added as their child skills merge
+
+---
+
+## Verification checklist
+
+Before emitting any menu or summary in this skill, mentally confirm each of the following. If any box is unchecked, adjust the output before sending.
+
+- [ ] The header line ends with `(via service-itsm-agentic-setup-agentforce-coordinate)`
+- [ ] The target org was confirmed with the user, and they were told it will be modified, before any child skill ran
+- [ ] The current feature's child-skill result was verified as a full success before advancing to the next queued feature — a failed or partial result stopped the queue instead
+- [ ] Only features with a working child skill are shown; placeholder features are hidden
+- [ ] The feature menu is presented as a multi-select (single-select only if the user has already named a specific feature)
+- [ ] Each feature row's `Status` column reflects the actual tracked state from the conversation (`Not done`, `In progress`, or `Done`) — not a hard-coded default
+- [ ] For a completion summary, the header line and closing line are chosen by the rubric in `examples/output-templates.md` (all `Done` → *Complete*; any `Not done`/`In progress` → *Finished*)
+- [ ] A feature is being configured only because the user explicitly selected it (or is being walked through sequentially with confirmation under an "all" / "everything" request)
+- [ ] Studio enablement is verified done before delegating to the Fulfiller Agent or Employee Agent child skill
+- [ ] The next action delegates to a child skill, never configures a feature inline
+- [ ] No Salesforce record IDs appear in the output — human-readable names only
+
+---
+
+## Reference File Index
+
+| File | When to read |
+|------|--------------|
+| `examples/output-templates.md` | Behavior steps 2, 4, and 5 — feature menu (multi-select), post-feature progress, and completion summary text blocks |
+| `scripts/verify-child-verdict.mjs` | Behavior step 5 — run via `Bash` (`node`) to check a child skill's verdict deterministically before advancing the queue |