@salesforce/afv-skills 1.65.1 → 1.66.0

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

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

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

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

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

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

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

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

package/skills/service-itsm-agentic-setup-incident-management/references/incident-persona-psg.md

@@ -51,7 +51,7 @@ licensing is part of the orchestrator's **Major Incident Management** feature).
   existing assignments (idempotency); assigning the missing backing PSL(s) and then the PSG; verifying by
   read-back.
 - **Out of scope**: the **Major Incident Manager** PSG; creating / editing / recalculating a PSG or its
-  membership; enabling ITSM / incident-management features (`service-itsm-incident-mgmt-configure`); the
+  membership; enabling ITSM / incident-management features (the `IncidentMgmt` SOR's master-feature steps); the
   `IncidentFulfiller` permission **set** for the Fulfiller **agent's** access
   (`service-itsm-agentic-setup-itsm-agentforce-permset-assign`); CMDB access
   (`service-itsm-agentic-setup-cmdb-access-assign`); generic, non-incident permission-set / PSG assignment
@@ -60,7 +60,8 @@ licensing is part of the orchestrator's **Major Incident Management** feature).
 ## Preconditions
 
 - **ITSM Incident Management must be provisioned** — the incident persona PSGs must exist on the org. If
-  neither is found, **stop and hand off** to `service-itsm-incident-mgmt-configure`; assign nothing.
+  neither is found, **stop and report that the personas are not provisioned**; the master-feature
+  prerequisite is handled by the orchestrator, but enabling it does not prove the PSGs exist.
 - **The acting user must be able to assign permission sets** (the SOR gates writes on it). A write that
   fails with an access error that is not a duplicate → surface it plainly and stop; an admin must do it.
 - **Each backing license consumes a seat.** A seat-exhausted license blocks that persona; report it.
@@ -68,8 +69,8 @@ licensing is part of the orchestrator's **Major Incident Management** feature).
 ## Operations (shapes come from `describe`)
 
 1. **Resolve which incident persona PSGs exist (read).** Look up the two PSGs by `DeveloperName`
-   (`IncidentFulfillerPSG`, `IncidentManagerPSG`) with **no `NamespacePrefix` filter**. None found → hand
-   off to `service-itsm-incident-mgmt-configure` and stop. Capture each PSG's Id and status.
+   (`IncidentFulfillerPSG`, `IncidentManagerPSG`) with **no `NamespacePrefix` filter**. None found →
+   stop and report that the personas are not provisioned. Capture each PSG's Id and status.
 2. **Resolve the target user (read).** To exactly one active user. For "me" / "the current user", read the
    API root's identity (the running user's `005…` Id) — **not** the `USER_ID()` SOQL function (Apex-only)
    and **not** the Chatter current-user endpoint (fails when Chatter is off). Zero / multiple → disambiguate.
@@ -124,13 +125,13 @@ Persona: <Incident Fulfiller | Incident Manager>
 ```
 
 Repeat the `Persona:` block per PSG if both were chosen. Report only what read-back confirmed. If the
-personas are not on the org, say so and name `service-itsm-incident-mgmt-configure`.
+personas are not on the org, say so without claiming master enablement will provision them.
 
 ## Common failures (surface in plain language)
 
 | Symptom | Likely cause | What to tell the user |
 |---------|--------------|-----------------------|
-| No incident PSG on the org | ITSM Incident Management not provisioned | The incident personas aren't set up yet — that's a separate step (`service-itsm-incident-mgmt-configure`) |
+| No incident PSG on the org | Incident persona PSGs not provisioned | The incident personas aren't set up yet — stop and report the missing PSGs |
 | Duplicate on assign | User already has that grant | Not an error — report as already assigned |
 | Seat / limit error on a license | An incident license has no free seats | A seat must free up (or more licenses added); the persona is incomplete without it |
 | PSG assigned but some actions missing | A backing license wasn't assigned, or the PSG is still recalculating | Confirm every backing license is assigned; if it's settling, retry in a moment |

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

@@ -6,7 +6,7 @@ Incident Management preferences** (the feature toggles on the Incident Managemen
 four meta-tools (`discover`, `describe`, `dispatch_readonly`, `dispatch`). The org comes from the OAuth JWT
 on the MCP session — never handle an org id, alias, or credentials. Minimum API version **67.0**.
 
-This is **not** the master Incident Management on/off switch (`service-itsm-incident-mgmt-configure`) nor
+This is **not** the master Incident Management on/off switch (the master-feature steps of the `IncidentMgmt` SOR) nor
 the Incident Priority Matrix (`service-itsm-incident-priority-configure`).
 
 ## Delegate to the Setup Operation Recipe
@@ -20,17 +20,16 @@ id; a `discover` miss is not proof an operation is unavailable.
 
 | SOR | Owns | Status |
 |-----|------|--------|
-| **`IncidentMgmt`** (owning team ITSM-Aditya; controller `IPCManagementSetupController`) | Read a preference; toggle a preference; verify a preference read-back | Served |
+| **`IncidentMgmt`** | Read a preference; toggle a preference; verify a preference read-back | Served |
 
 Discover by intent — e.g. `discover("configure ITSM incident management preferences: automatically triage
 incidents, assign incidents with Einstein, enable rich text for incident descriptions")`.
 
 > **Resolve the right node — load-bearing.** Two setup nodes share the "Incident" name. Target the
-> **ITSM Incident Management org-preferences** node (controller `IPCManagementSetupController`) whose
-> toggles are the six below — **not** the Service-Foundation "Incident Management" node
-> (`IncidentMgmtSetupController`), whose toggles are broadcast/notification channels (Email/Sites/Alerts/
-> Slack) and a master switch. If a `discover` result is about broadcast channels or a master on/off, it is
-> the wrong node.
+> **ITSM Incident Management org-preferences** node whose toggles are the six below — **not** the
+> Service-Foundation "Incident Management" node, whose toggles are broadcast/notification channels
+> (Email/Sites/Alerts/Slack). The `IncidentMgmt` SOR also owns the master on/off switch; a `discover`
+> result about broadcast channels is the wrong node.
 
 ## Operations (shapes come from `describe`)
 
@@ -78,7 +77,7 @@ phrasing and the known-name enumeration.
   surface the raw access error and stop.
 - **Incident Management provisioned**: these preferences are writable only when Incident Management is
   enabled at the feature/license level. If reads or writes fail with an availability error, say the feature
-  must be enabled first (`service-itsm-incident-mgmt-configure`) and stop.
+  must be enabled first (the `IncidentMgmt` SOR's master-feature steps) and stop.
 
 ## Workflow
 
@@ -124,7 +123,7 @@ and what it means (e.g. "that setting can't be turned on once incidents exist").
 |---------|--------------|-----------------------|
 | Enable of "Restrict Assigned Group…" fails | The org already has Incident records (server freezes it) | That setting can only be turned on before any incidents exist; it can't be enabled now |
 | Read/write blocked with an access error | Caller lacks ITSM setup access | An admin with setup access must make this change |
-| Read/write unavailable on the org | Incident Management not enabled | Enable Incident Management first (`service-itsm-incident-mgmt-configure`) |
+| Read/write unavailable on the org | Incident Management not enabled | Enable Incident Management first through the `IncidentMgmt` SOR's master-feature steps |
 | Change didn't persist on read-back | Write did not take | Report it as failed and show the current state; do not claim success |
 | `dispatch*` auth error | headless-360 session not authenticated / expired | Re-authenticate the connection and confirm it points at the intended org |
 
@@ -144,5 +143,5 @@ missing setup access or an unauthenticated session. A `404` = the operation is n
 - Read or write against the Service-Foundation `IncidentManagement` node (broadcast channels) — wrong node.
 - Read or write any preference name the SOR does not list — an unknown name reads as `false` and is
   rejected on write.
-- Toggle the **master** Incident Management switch here (`service-itsm-incident-mgmt-configure`) or the
+- Toggle the **master** Incident Management switch as part of this preferences feature (use the orchestrator's prerequisite over the `IncidentMgmt` SOR) or the
   **Incident Priority Matrix** (`service-itsm-incident-priority-configure`).

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

@@ -25,7 +25,7 @@ routes are not always ranked first; only a `404` from the dispatch itself means
 Read each step's `status` from `describe`: `implemented` = live; `proposed` = not served on every org yet.
 
 > **MIM is configured by the two surfaces below.** The only feature that must be *on* first is **base**
-> Incident Management (`service-itsm-incident-mgmt-configure`) — see Preconditions.
+> Incident Management (the master-feature steps of the `IncidentMgmt` SOR) — see Preconditions.
 
 ### Transports MIM uses (all via the same `dispatch*` tools)
 
@@ -44,7 +44,7 @@ Read each step's `status` from `describe`: `implemented` = live; `proposed` = no
   precondition, licensing approvers with the **Major Incident Manager permission-set license** and standing
   up the approvers **public group**. Verify every write by read-back.
 - **Out of scope**: base Incident Management enablement
-  (`service-itsm-incident-mgmt-configure` — a prerequisite); the Incident Fulfiller / Incident Manager
+  (the `IncidentMgmt` SOR's master-feature steps — a prerequisite); the Incident Fulfiller / Incident Manager
   **persona** PSG (the orchestrator's **Persona** feature — see `references/incident-persona-psg.md`);
   Problem / Change / Case Management; the Priority Matrix; SLA / entitlement setup; any MIM org preference
   **other than** the two allowlisted.
@@ -53,8 +53,8 @@ Read each step's `status` from `describe`: `implemented` = live; `proposed` = no
 
 The acting user needs **ITSM setup access** (the SOR gates every MIM route on it), and:
 
-1. **Base Incident Management must be enabled** — MIM layers on it. If it is off, **stop and hand off** to
-   `service-itsm-incident-mgmt-configure`; do not configure MIM without base Incident Management.
+1. **Base Incident Management must be enabled** — MIM layers on it. The orchestrator first follows the
+   `IncidentMgmt` SOR's read/confirm/enable/verify prerequisite; stop if it cannot confirm ENABLED.
 2. **Approvers must hold the Major Incident Manager permission-set license.** This is a **LICENSE** —
    granted via `PermissionSetLicenseAssign` (`{AssigneeId, PermissionSetLicenseId}`), **never** a
    `PermissionSetAssignment`. Group-user validation requires every direct and transitive user of a group
@@ -135,7 +135,7 @@ Major Incident Management
 ```
 
 Report only what read-back confirmed; omit lines for surfaces out of the requested scope. If base Incident
-Management is off, say so and name `service-itsm-incident-mgmt-configure`.
+Management cannot be confirmed on, say so and stop without configuring MIM.
 
 ## Common failures (surface in plain language)
 
@@ -158,5 +158,5 @@ Management is off, say so and name `service-itsm-incident-mgmt-configure`.
 - Designate a **group** approver without `validate-group-users` returning **true** first.
 - Reassign without removing the existing designation first (create is a silent no-op).
 - Send any preference name other than `AutoCreationOfProblem` / `AutoClosureChildIncidents`.
-- Attempt MIM setup when base Incident Management is off — hand off to `service-itsm-incident-mgmt-configure`.
+- Attempt MIM setup when base Incident Management is off — first complete the `IncidentMgmt` master-feature prerequisite.
 - Pass `dispatch` the `{operation_id, arguments}` shape — it takes raw HTTP.

package/skills/service-itsm-agentic-setup-incident-management/references/service-mgmt-privilege.md

@@ -70,7 +70,7 @@ keyed on the org preference **`PrivilegeAssignmentEnabled`**.
 - **In scope**: read / set the **Enable Privilege Assignment** master toggle; read / set the org-wide
   **escalation level**; list / create / update / delete **Service Management Privilege** definitions; bulk
   **add / remove employee assignments** for a privilege; verify by read-back where one exists.
-- **Out of scope**: base Incident Management enablement (`service-itsm-incident-mgmt-configure`); the
+- **Out of scope**: base Incident Management enablement (the `IncidentMgmt` SOR's master-feature steps); the
   Incident Fulfiller / Incident Manager **persona** PSG (the orchestrator's **Persona** feature); the Major
   Incident Manager approver licensing (the **Major Incident Management** feature); Problem / Change / Case
   Management; the Priority Matrix; SLA setup.