@salesforce/afv-skills 1.55.0 → 1.57.0

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

@@ -0,0 +1,148 @@
+# Feature: Incident Management Preferences (inline execution)
+
+How the orchestrator executes the **Preferences** feature — reading and setting the **six per-feature
+Incident Management preferences** (the feature toggles on the Incident Management setup page). This runs
+**inline** through the Salesforce-hosted **`headless-360`** MCP server (server key `headless-360`) via its
+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
+the Incident Priority Matrix (`service-itsm-incident-priority-configure`).
+
+## Delegate to the system of record
+
+Every operation is delegated to a system of record (SOR) and its exact shape is fetched at runtime:
+`discover` the operation by intent, `describe` the SOR for its **current** steps, routes, argument schema,
+the preference list, the on-screen labels, and its `agent_guidance`, then `dispatch_readonly` (reads) /
+`dispatch` (writes). **Hardcode no routes, preference names, labels, or request bodies — use what
+`describe` returns, and if it disagrees with anything here, `describe` wins.** Discover by intent, not by
+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 |
+
+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.
+
+## Operations (shapes come from `describe`)
+
+1. **Read a preference (read).** Given a preference name, return its Boolean state. Unknown names are **not
+   validated on read** — they return `false` rather than raising — so only ever read a preference the SOR
+   lists; a `false` read is not proof a name is valid.
+2. **Toggle a preference (write — confirm first).** Set a named preference enabled/disabled. An unknown
+   name raises. The two one-way preferences cannot be set to disabled.
+3. **Verify (read).** Read the changed preference back and expect it to equal the value just set.
+
+## The six preferences (name → label; `describe`/`agent_guidance` is authoritative)
+
+| Preference name | Setup label | One-way |
+|-----------------|-------------|---------|
+| `IncidentValidationsEnabled` | Default Field Validations for Incidents | No |
+| `AutoClosureChildIncidents` | Automatically Close Child Incidents | No |
+| `IncidentTriageAgentEnabled` | Automatically Triage Incidents | No |
+| `IncAssignWithAgentEnabled` | Assign Incidents with Einstein | No |
+| `AssignedGroupValidationEnabled` | Restrict Assigned Group to Regular Groups | **Yes** |
+| `RtaIncidentDescEnabled` | Enable Rich Text for Incident Descriptions | **Yes** |
+
+Read the live list and labels from `describe` at runtime — this table is the authoring snapshot for trigger
+phrasing and the known-name enumeration.
+
+## Invariants — the contract
+
+- **Two preferences are one-way / enable-only:** `RtaIncidentDescEnabled` and
+  `AssignedGroupValidationEnabled`. Once enabled they cannot be disabled. Never offer to disable them;
+  require an explicit "I understand this can't be undone" confirmation before enabling; never enable one
+  merely to test.
+- **`AssignedGroupValidationEnabled` also freezes once the org has any Incident record** — it is settable
+  only while the org has no incidents. An enable can therefore **fail outright** when incidents already
+  exist; surface pre-existing incidents as the likely cause and do **not** retry.
+- **Read does not validate the preference name** (unknown → `false`, no error); only the write is
+  allowlisted (unknown → raises). Enumerate only the six the SOR lists.
+- **Access gate:** the caller needs `IncidentMgmt.userHasITSMSetupAccess` (sysadmin OR Customize
+  Application + Modify All Data + View Setup). Without it every read and write is blocked by the controller.
+- **Idempotent** — read before every write; skip a write when the preference is already in the requested
+  state.
+- **Verify by read-back** — the write response alone is not proof the change persisted.
+
+## Preconditions
+
+- **Setup access**: the caller needs ITSM setup access. Without it every read and write is blocked —
+  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.
+
+## Workflow
+
+The SOR's `agent_guidance` (returned by `describe`) carries the detailed flow and current labels; follow
+it. In outline — **read before you write, confirm before every write, verify every write by read-back**,
+and act only on the preferences the user chose:
+
+1. **Read current state** — read each of the six preferences and report which are on and which are off,
+   flagging the two one-way ones.
+2. **Ask which to change** — never infer; for a one-way enable, take the explicit can't-be-undone
+   confirmation here. On any non-yes, stop without writing.
+3. **Apply only the chosen preferences** — skip any already in the requested state (idempotent no-op).
+4. **Verify** — read each changed preference back; report success only when it read back as set.
+
+## Clarifying questions
+
+- **Which preference(s)?** If unstated, present the six (by label, flagging the two one-way) and let the
+  user pick.
+- **Enable or disable?** Required for a change; never infer direction from current state. Disable is not
+  offered for the two one-way preferences.
+- **Which org?** Confirm it and state plainly the org will be **modified**. For production, get explicit
+  confirmation. Enabling a one-way preference is permanent.
+
+## Output expectations
+
+```text
+  Default Field Validations for Incidents ...... On | Off
+  Automatically Close Child Incidents .......... On | Off
+  Automatically Triage Incidents ............... On | Off
+  Assign Incidents with Einstein ............... On | Off
+  Restrict Assigned Group to Regular Groups .... On | Off  (one-way)
+  Enable Rich Text for Incident Descriptions ... On | Off  (one-way)
+
+Changed: <label> Off → On (SUCCEEDED | ALREADY-ON | FAILED)
+```
+
+Report only what read-back confirmed. On a failure, stop and say — in plain language — what did not succeed
+and what it means (e.g. "that setting can't be turned on once incidents exist").
+
+## Common failures (surface in plain language)
+
+| Symptom | Likely cause | What to tell the user |
+|---------|--------------|-----------------------|
+| 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`) |
+| 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 |
+
+## Reading `dispatch` results
+
+Responses come back wrapped as `{ status_code, body }`; read what you need from `body`. A preference read
+returns a Boolean in `body`. A write success persists (no meaningful body). A service error on a write =
+either a preference name outside the six, **or** a one-way freeze (e.g. `AssignedGroupValidationEnabled`
+with incidents already present) — surface the specific cause, do not retry blindly. A `401` / `403` =
+missing setup access or an unauthenticated session. A `404` = the operation is not available on this org
+(feature not enabled).
+
+## Dead ends — do NOT do these
+
+- Write an HTTP route or a request body here — delegate to the SOR and let `describe` carry the shape.
+- Offer to disable a one-way preference, or enable one just to "test" it.
+- 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
+  **Incident Priority Matrix** (`service-itsm-incident-priority-configure`).

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

@@ -0,0 +1,162 @@
+# Feature: Major Incident Management (inline execution)
+
+How the orchestrator executes the **Major Incident Management (MIM)** feature. MIM setup is **two surfaces**
+layered on top of base Incident Management: (1) the **major-incident approval group**, and (2) **two MIM org
+preferences**. This runs **inline** through the Salesforce-hosted
+**`headless-360`** MCP server (server key `headless-360`) via its 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**.
+
+## Delegate every operation to the MIM system of record
+
+The **Major Incident Management SOR** is the single source of truth for **how** each step is done — the
+route, method, request/response shape, field names, per-step `status`, and `depends_on` ordering. It is
+**actively evolving**, so **never hardcode a route or request body**. Carry only the **goal, scope,
+ordering, and invariants**, and at runtime:
+
+1. `discover` the operation by intent (e.g. `"set major incident approval group"`, `"validate major
+   incident approval group users"`, `"toggle major incident org preference"`).
+2. `describe` the returned SOR / operation for its **current** route, method, argument schema, and `status`.
+3. `dispatch_readonly` (reads) / `dispatch` (writes) the route the SOR names.
+
+**Use what `describe` returns — not any shape written here. If `describe` and this file disagree, `describe`
+wins.** A `discover` miss does not prove a route is absent — generic `/query` and `/sobjects/...` REST
+routes are not always ranked first; only a `404` from the dispatch itself means a route is unavailable.
+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.
+
+### Transports MIM uses (all via the same `dispatch*` tools)
+
+| Transport | Shape of the `url` | Used by |
+|-----------|--------------------|---------|
+| **Aura controller** | `/headless/invoke/platform/mim/<method>` | approval-group + org-preference + group-user-validation routes |
+| **sObject REST** | `/services/data/v67.0/sobjects/...` and `/services/data/v67.0/query` | license / public-group / member records used as **preconditions** |
+
+`dispatch` takes **raw HTTP** — a full `url`, `method`, and optional `body`/`queryParams`, not
+`{operation_id, arguments}`.
+
+## Scope
+
+- **In scope**: designating / clearing / reassigning the **major-incident approval group** (a User or a
+  public Group); **group-user validation**; reading and toggling the **two** MIM org preferences; and, as a
+  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
+  **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.
+
+## Preconditions
+
+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.
+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
+   approver to hold it. If a designated user lacks it (or the approvers group does not exist yet), prepare
+   that first — this is **precondition prep, not MIM activation**. A **Regular** public group; add each
+   **licensed** user; **license before membership**.
+
+If a `dispatch*` returns `401` / `403` / `404`, do **not** fabricate state — surface the raw error and
+stop. `403` usually means the acting user lacks ITSM setup access.
+
+## The two surfaces — SOR step map (targets for `describe`)
+
+Describe each before calling; the ids are stable handles, the shapes come from `describe`.
+
+### Surface 1 — approval group
+
+| Step id | Transport | Purpose |
+|---------|-----------|---------|
+| `validate-group-users` | Aura `PATCH .../validate-group-users` | Returns **true** only if every direct + transitive `005…` member of the group holds the Major Incident Manager license — **call before designating a Group** |
+| `create-major-incident-approval-group` | Aura `PATCH .../create-major-incident-approval-group` | Designate the approver — a **User (005…)** or **public Group (00G…)** — stored as `SrvcMgmntApprovalAssignment` with `OperationType=MAJOR_INCIDENT_APPROVAL`. **Idempotent** (silent no-op if one exists) |
+| `verify-approval-group` | Aura `GET .../get-major-incident-approval-group` | Read the designated approver back; expect it to equal the Id you set (null when none) |
+| `remove-major-incident-approval-group` | Aura `DELETE .../remove-major-incident-approval-group` | Clear the designation — **run first to reassign** |
+
+For a **Group** approver, run **group-user validation first**: it must return **true**. If false, fix
+licensing / membership and re-validate; do not designate a group that fails. Designation is **idempotent** —
+a create when one already exists is a **silent no-op**, so a "success" does not prove your approver is the
+one set — **verify by read-back**, and **remove-first to reassign**.
+
+### Surface 2 — org preferences
+
+| Step id | Transport | Purpose |
+|---------|-----------|---------|
+| `get-mim-setup-page-org-preference` | Aura `GET .../get-mimsetup-page-org-preference` | Read one MIM preference's current boolean value |
+| `toggle-mim-setup-page-org-preference` | Aura `PATCH .../toggle-mimsetup-page-org-preference` | Set one MIM preference on / off |
+
+**Preference allowlist — exactly two names:** **`AutoCreationOfProblem`** and **`AutoClosureChildIncidents`**.
+**Any other `prefName` raises a `ServiceException` without writing** — never pass a name outside this set.
+Require an explicit on/off direction from the user (do not infer it).
+
+## Ordering (follow the SOR's `depends_on`)
+
+1. **License before membership** — a user holds the Major Incident Manager license before being added to
+   the approvers group.
+2. **Validate before designating a group** — `validate-group-users` must return **true** before
+   `create-major-incident-approval-group` with a Group.
+3. **Remove before reassign** — `remove-major-incident-approval-group` before a second create.
+
+## Workflow
+
+Always **read before you write**, **confirm before every write**, and **verify every write by read-back**.
+
+1. **Preflight** — for each in-scope surface, `discover` and `describe` for the current route, schema, and
+   `status`. On `401` / `403` / `404`, surface and stop.
+2. **Prerequisites** — confirm base Incident Management is on (else hand off), and that the approver(s) hold
+   the Major Incident Manager license (prepare it, and the public group, if needed).
+3. **Read current state** — the current approval-group designation and each preference value.
+4. **Confirm** — present the exact plan (org, approver, preference + direction) via `AskUserQuestion`;
+   require an explicit yes. On no, stop with no writes.
+5. **Apply** — validate-before-designate (for a group), remove-before-reassign; toggle only allowlisted
+   preferences. Treat a duplicate / already-set as success.
+6. **Verify** — re-read the designation and each preference; report only what read-back confirms.
+
+## Clarifying questions
+
+Ask only what you cannot infer: **which surface** (approval group, preferences, or both); **who** the
+approver is (resolve to exactly one active User `005…` or a public Group `00G…`); **which preference and
+on/off**; and **which org** — state plainly this org will be **modified** (designation, license assignment
+which consumes a seat, group changes, preference writes). For production, get explicit confirmation.
+
+## Output expectations
+
+```text
+Major Incident Management
+
+  Approvers licensed (N) ............ Licensed N | M already held
+  Approval group designated ......... <user/group> | Already designated | Reassigned
+  Preferences ....................... Auto-create problem: on/off · Auto-close child incidents: on/off
+```
+
+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`.
+
+## Common failures (surface in plain language)
+
+| Symptom | Likely cause | What to tell the user |
+|---------|--------------|-----------------------|
+| Group validation returns false | A direct / nested member lacks the Major Incident Manager license | License every member first, then re-validate before designating the group |
+| Approval group "designated" but unchanged | A designation already existed — it is idempotent | To change the approver, the old designation is removed first, then the new one set |
+| Preference change rejected (`ServiceException`) | A preference name outside the allowlist was sent | Only auto-create problem and auto-close child incidents are configurable here |
+| Seat / limit error on the license | No free Major Incident Manager seats | A seat must free up (or more licenses added) before that user can be an approver |
+| `400 DUPLICATE_VALUE` on a license / group / member write | The record already exists | Idempotent success — report as already-done |
+| `403` on a MIM route | Acting user lacks ITSM setup access | An admin with ITSM setup access must perform this |
+| `dispatch*` auth error | headless-360 session not authenticated / expired | Re-authenticate the connection and confirm it points at the intended org |
+
+## Dead ends — do NOT do these
+
+- Hardcode any route / body — `describe` at runtime; the SOR is evolving.
+- Grant the Major Incident Manager license with a `PermissionSetAssignment` — it is a **license**
+  (`PermissionSetLicenseAssign`).
+- Add a user to the approvers group before licensing them.
+- 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`.
+- Pass `dispatch` the `{operation_id, arguments}` shape — it takes raw HTTP.

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

@@ -0,0 +1,149 @@
+# Feature: Service Management Privilege (inline execution)
+
+How the orchestrator executes the **Service Management Privilege** feature — ITSM **privilege escalation**
+setup: the org-wide **escalation level**, the **Service Management Privilege** definitions (each with a
+name, description, tag, access level, and function type), and **bulk employee ↔ privilege assignments**, all
+behind the **Enable Privilege Assignment** master toggle. This runs **inline** through the Salesforce-hosted
+**`headless-360`** MCP server (server key `headless-360`) via its 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**.
+
+## Delegate every operation to the system of record
+
+The **Service Management Privilege setup SOR** is the single source of truth for **how** each step is done —
+the route, method, request/response shape, field names, per-step `status`, and `depends_on`. It is **draft
+and actively evolving**, so **never hardcode a route or request body**. Carry only the **goal, scope,
+ordering, and invariants**, and at runtime:
+
+1. `discover` the operation by intent (e.g. `"enable privilege assignment toggle"`, `"set ITSM escalation
+   level"`, `"create a service management privilege"`, `"assign employees to a service privilege"`).
+2. `describe` the returned SOR / operation for its **current** route, method, argument schema, and `status`.
+3. `dispatch_readonly` (reads) / `dispatch` (writes) the route the SOR names.
+
+**Use what `describe` returns — not any shape written here. If `describe` and this file disagree, `describe`
+wins.** Read each step's `status` from `describe`: `implemented` = live; `proposed` = not served on every org
+yet. **There is no public Connect / Tooling / Metadata / sObject substitute for this feature** — the setup
+controller is the only surface. So if `discover`/`describe` does not surface a step or a `dispatch` returns
+`404`, the surface is **not available on this org yet** — surface that plainly and stop; **never fabricate a
+fallback route.**
+
+## The four surfaces — SOR step map (targets for `describe`)
+
+Describe each before calling; the step ids are stable handles, the shapes come from `describe`.
+
+### Surface 1 — the Enable Privilege Assignment master toggle (`implemented`)
+
+Backed by the generic **SetupMetadata** org-preference batch operations (not the privilege controller),
+keyed on the org preference **`PrivilegeAssignmentEnabled`**.
+
+| Step id | Purpose |
+|---------|---------|
+| `check-privilege-assignment-enabled` | Read whether `PrivilegeAssignmentEnabled` is on |
+| `set-privilege-assignment-enabled` | Turn the feature on / off — **reversible** |
+| `verify-set-privilege-assignment-enabled` | Read `PrivilegeAssignmentEnabled` back to confirm the write |
+
+### Surface 2 — escalation level
+
+| Step id | Purpose |
+|---------|---------|
+| `fetch-escalation-level` | Read the org-wide ITSM escalation level |
+| `save-escalation-level` | Set the escalation level (`escalationLevel`) |
+| `verify-save-escalation-level` | Read the level back to confirm |
+
+### Surface 3 — Service Management Privilege definitions
+
+| Step id | Purpose |
+|---------|---------|
+| `get-service-privileges` | List every privilege (id, name, description, tag, access level, function type) — **drives verify** |
+| `create-service-privilege` | Add a privilege from a field map |
+| `update-service-privilege` | Edit a privilege (field map keyed by its id) |
+| `delete-service-privilege` | Remove a privilege by id — **destructive, no rollback** |
+
+### Surface 4 — employee assignments
+
+| Step id | Purpose |
+|---------|---------|
+| `save-privilege-assignments` | Bulk add / remove employees for one privilege (add-list + remove-list, both in one call) — **no read-back** |
+
+## Scope
+
+- **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
+  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.
+
+## Preconditions
+
+- **ITSM setup access** — the SOR gates every route on it (`IncidentMgmt.userHasITSMSetupAccess`). A `403`
+  means the acting user lacks it; an admin with ITSM setup access must perform this.
+- **The Enable Privilege Assignment master toggle is the UI entry gate**, not a server precondition. The
+  privilege controller does **not** re-check it, so turning it on is **workflow ordering** — enable it first
+  so the escalation and privilege-management surfaces are coherent, but it does not hard-block the other
+  writes. It is **reversible** (it can be turned back off — unlike the one-way incident preferences).
+
+## Ordering (follow the SOR's `depends_on`)
+
+1. **Toggle first** — if `PrivilegeAssignmentEnabled` is off and the user wants to configure the feature,
+   enable it before touching escalation level or privileges (workflow ordering, not a hard gate).
+2. **Read before every write** — the current toggle state, escalation level, or privilege list.
+3. **Verify definition writes** — re-read via `get-service-privileges` after each create / update / delete.
+4. **Assignments have no read-back** — you cannot confirm them by re-read; report them as **applied**, never
+   as verified.
+
+## Workflow
+
+Always **read before you write**, **confirm before every write**, and **verify every write by read-back**
+where a read-back exists.
+
+1. **Preflight** — for each in-scope surface, `discover` and `describe` for the current route, schema, and
+   `status`. On `401` / `403` / `404`, surface and stop.
+2. **Read current state** — the toggle, the escalation level, and/or the current privileges.
+3. **Confirm** — present the exact plan (org, toggle direction, escalation value, privilege change, or the
+   employees to add/remove) via `AskUserQuestion`; require an explicit yes. On no, stop with no writes.
+4. **Apply** — toggle first if needed; then the requested write. Treat a duplicate / already-set as success.
+5. **Verify** — re-read the toggle, the escalation level, and the privilege list; for assignments, state
+   plainly they were applied but cannot be read back.
+
+## Clarifying questions
+
+Ask only what you cannot infer: **which surface** (master toggle, escalation level, privilege definitions,
+or employee assignments); for a **privilege**, its fields (name, description, tag, access level, function
+type); for **assignments**, the target privilege and exactly which employees to add / remove; and **which
+org** — state plainly this org will be **modified**. For production, get explicit confirmation.
+
+## Output expectations
+
+```text
+Service Management Privilege
+  Enable Privilege Assignment ....... On | Off | Enabled now
+  Escalation level .................. <value> | Unchanged
+  Privileges ........................ Created/Updated/Deleted <name> | N configured
+  Employee assignments .............. Applied: +N / -M (not read-back verifiable)
+```
+
+Report only what read-back confirmed; for assignments, report them as applied and say they cannot be
+verified by re-read. Omit lines for surfaces out of the requested scope.
+
+## Common failures (surface in plain language)
+
+| Symptom | Likely cause | What to tell the user |
+|---------|--------------|-----------------------|
+| `403` on any route | Acting user lacks ITSM setup access | An admin with ITSM setup access must perform this |
+| `404` / step not discoverable | The surface is `proposed`, not served on this org yet | This feature isn't available on this org yet — there is no alternative API path |
+| Delete rejected or unexpected | Wrong privilege id, or it no longer exists | Re-list privileges and confirm the exact one to remove |
+| Assignment "done" but can't confirm | Assignments have no read-back | The change was applied; it cannot be confirmed by re-reading — check in Setup if needed |
+| `dispatch*` auth error | headless-360 session not authenticated / expired | Re-authenticate the connection and confirm it points at the intended org |
+
+## Dead ends — do NOT do these
+
+- Hardcode any route / body — `discover` + `describe` at runtime; the SOR is draft and evolving.
+- Fabricate a Connect / Tooling / Metadata / sObject fallback — **none exists**; a `404` means the surface
+  isn't served on this org yet, so surface and stop.
+- Delete a Service Management Privilege to test, or without an explicit confirmation — it is **irreversible**.
+- Claim an employee assignment is **verified** — `save-privilege-assignments` has **no read-back**.
+- Treat the Enable Privilege Assignment toggle as a hard server gate — it is the UI entry gate (reversible)
+  and the controller does not re-check it; enabling it is workflow ordering.
+- Pass `dispatch` the `{operation_id, arguments}` shape — it takes raw HTTP.