@salesforce/afv-skills 1.40.0 → 1.41.0

package/skills/service-itsm-channels-coordinate/SKILL.md

@@ -0,0 +1,472 @@
+---
+name: service-itsm-channels-coordinate
+description: "Top-level interactive coordinator for Employee Service (ITSM) channel setup. Presents menu of channel setup options (Teams, Slack, Swarming, Notifications, Portal) and delegates to the corresponding skill. Use this for: 'setup ITSM channels', 'configure employee service channels', 'set up service cloud communication channels', 'I want to configure ITSM integrations', or any general request for ITSM channel/integration setup where the user hasn't specified exactly which channel they want. DO NOT TRIGGER for requests that already name a specific channel or child skill (e.g. 'configure Teams', 'set up Slack', 'enable Swarming', 'configure ITSM notifications', 'create an employee portal') — route directly to the matching child skill instead."
+metadata:
+  version: "1.0"
+  domains: ["Service"]
+  mcpTools:
+    headless-360:
+      tools: ["dispatch"]
+      semver: ">=1.0.0"
+  relatedSkills:
+    - "experience-portal-create"
+    - "service-itsm-swarming-configure"
+    - "service-itsm-teams-configure"
+    - "service-itsm-teams-debug"
+    - "service-itsm-teams-employee-agent-configure"
+    - "service-itsm-teams-itdesk-configure"
+    - "service-itsm-teams-itservice-configure"
+---
+
+# Employee Service (ITSM) Channels Setup Coordinator
+
+Interactive coordinator that presents a menu of ITSM channel setup options and delegates to the appropriate child skill based on user selection.
+
+## Scope
+
+- **In scope**: Presenting the channel setup menu to the user. Delegating to child skills based on selection (Teams, Swarming, Portal). Validating prerequisites before delegation. Providing clear descriptions of each channel capability. **Notifications is the one exception** — no dedicated notifications child skill exists yet, so this coordinator enables the notification-channel org preferences inline for that choice (see Choice 4); those are the only setup-API writes it performs itself.
+- **Out of scope**: Directly calling setup APIs for any channel that has a dedicated child skill (Teams, Swarming, Portal — always delegate). Channel-specific configuration details beyond the initial enablement. User permission assignment. Post-setup testing.
+
+---
+
+## Available Channel Setup Skills
+
+This coordinator can invoke five distinct channel setup skills:
+
+### 1. Microsoft Teams Setup
+**Skill:** `service-itsm-teams-configure`
+
+**What it does:**
+- Enables the `service-cloud-itsm-teams-integration` Salesforce Go feature via headless-360's
+  feature-enablement Connect API — the only verified path that flips `ITSMTeamsEnabled` (direct
+  PATCH of the org preference is blocked with 401)
+- Optionally enables the sibling `OrgHasITSMFulfillerTeams` / `OrgHasEmployeeServiceTeams` preferences
+- Verifies `ITSMTeamsEnabled` afterward and reports the remaining manual (Microsoft-side) steps
+
+**Prerequisites:**
+- Teams ITSM add-on licenses
+- Setup admin permissions
+
+**Use when:** User wants Microsoft Teams integration for IT Service Desk or Employee Service apps.
+
+**Teams sub-skills** `service-itsm-teams-configure` delegates to (surface these if the user asks for
+a specific half): `service-itsm-teams-itdesk-configure` (fulfiller/IT Desk checklist),
+`service-itsm-teams-itservice-configure` (employee/IT Service checklist),
+`service-itsm-teams-employee-agent-configure` (embedded "Ask AI Agent"), and
+`service-itsm-teams-debug` (diagnose a failing Teams setup — login, tab loading, agent, swarming, SSO).
+
+---
+
+### 2. Slack Setup
+**Skill:** the installed Slack ITSM setup skill — resolve it from the skills catalog at delegation
+time by name pattern (see Choice 2 in the workflow); do not hardcode a single skill name.
+
+**What it does:**
+- Enables Slack integration for ITSM (Employee Service / IT Service on Slack)
+- Configures the Slack workspace connection and required org preferences/permission sets
+
+**Prerequisites:**
+- Slack workspace with admin access
+- Org has Slack integration enabled
+
+**Use when:** User wants Slack integration for ITSM.
+
+---
+
+### 3. Swarming Setup
+**Skill:** `service-itsm-swarming-configure`
+
+**What it does:**
+- Enables the `service-cloud-swarming` Salesforce Go feature via headless-360's feature-enablement
+  Connect API
+- Sets the "Select a Collaboration Tool" picklist to `Teams` via
+  `PATCH /services/data/v67.0/setup/org/values/SWARM_COLLABORATION_TOOL` — fully automated, no
+  manual click required
+
+**Prerequisites:**
+- Microsoft Teams integration (Swarming requires Teams — run `service-itsm-teams-configure` first)
+
+**Use when:** User wants collaborative problem-solving for ITSM.
+
+---
+
+### 4. Notifications Setup
+**Skill:** none yet — handled inline by this coordinator (see Choice 4)
+
+**What it does:**
+- Enables the master Notifications feature
+- Configures notification channels: Email, In-App, Slack, Teams
+
+**Prerequisites:**
+- Multi-channel Notifications feature enabled
+- View Setup + Customize Application permissions
+
+**Use when:** User wants to enable multi-channel notifications for ITSM events.
+
+**Note:** For demo, execute inline until dedicated skill is created.
+
+---
+
+### 5. Portal Setup
+**Skill:** `experience-portal-create`
+
+**What it does:**
+- Creates a Digital Experience portal for employee self-service
+- Supports Employee Service, Partner, and Customer portals
+
+**Prerequisites:**
+- Vary by portal type
+
+**Use when:** User wants to create a portal for employee self-service.
+
+---
+
+## Workflow
+
+### Step 1: Present Menu to User
+
+**Always present the menu** before proceeding:
+
+```text
+I can help you set up ITSM channels. Which channel would you like to configure?
+
+**Choose one:**
+
+1. **Microsoft Teams Setup**
+   - Enable Teams integration master toggle
+   - Provision authentication infrastructure
+   - Prerequisites: Teams ITSM licenses required
+
+2. **Slack Setup**
+   - Enable Slack integration for ITSM
+   - Configure Slack workspace connection
+   - Prerequisites: Slack workspace with admin access
+
+3. **Swarming Setup**
+   - Enable Swarming for collaborative problem-solving
+   - Configure Swarming channels (requires Teams)
+   - Prerequisites: Teams integration + Swarming feature
+
+4. **Notifications Setup**
+   - Enable multi-channel notifications (Email, In-App, Slack, Teams)
+   - Configure notification delivery channels
+   - Prerequisites: Multi-channel Notifications feature
+
+5. **Portal Setup**
+   - Create Digital Experience portal for employee self-service
+   - Choose portal type during setup
+   - Prerequisites: Vary by portal type
+
+Please respond with the number (1, 2, 3, 4, or 5) of your choice.
+```
+
+**Do NOT proceed** until the user provides a choice.
+
+---
+
+### Step 2: Validate Prerequisites
+
+Based on user's choice, check prerequisites **before** delegating to child skills:
+
+#### For Choice 1 or 3 (Teams Integration):
+1. Check if Teams master toggle API is accessible
+2. Attempt to query current toggle state
+3. If prerequisites fail, inform user about missing Teams ITSM licenses
+
+#### For Choice 2 or 4 (Notifications):
+1. Check if Notifications preference APIs are accessible
+2. Verify Multi-channel Notifications feature is available
+
+**If prerequisites fail:**
+- Explain what's missing (licenses, features, permissions)
+- Offer alternative choices (e.g., suggest #4 if Teams licenses missing)
+- Do NOT attempt to execute the chosen configuration
+
+---
+
+### Step 3: Delegate to Child Skill
+
+#### Choice 1: Microsoft Teams Setup
+
+**Delegation:**
+```text
+Invoke the service-itsm-teams-configure skill.
+```
+
+**On success:**
+"Success: Microsoft Teams integration master toggle is enabled. Background provisioning in progress (2-5 minutes).
+
+Next steps:
+- Configure Azure AD application
+- Set up Salesforce IT Desk and/or IT Service apps"
+
+**On failure:**
+"Failed: Teams integration failed: [error details]
+
+Resolution:
+- Verify org has Teams ITSM licenses
+- Try option #4 (Notifications) instead"
+
+---
+
+#### Choice 2: Slack Setup
+
+**Resolve the delegation target deterministically from the skills catalog, then invoke the result.**
+Do not decide by prose guesswork — look the skill up:
+
+```text
+1. Query the installed skills catalog for a Slack ITSM setup skill, in priority order:
+     a. any skill whose name matches ^service-itsm-slack-.*-configure$   (preferred)
+     b. any skill whose name matches ^(setup|service)-.*slack.*(configure|enable)$
+2. If the lookup returns a skill → invoke that exact skill and stop.
+3. If the lookup returns nothing → fall through to the manual instructions below.
+```
+
+**Manual instructions (only if the catalog lookup returned no Slack skill):**
+"No Slack ITSM setup skill is installed in this environment. To configure Slack manually:
+1. Navigate to: Setup → Integrations → Slack
+2. Connect your Slack workspace
+3. Configure Slack apps for ITSM"
+
+---
+
+#### Choice 3: Swarming Setup
+
+**Delegation:**
+```text
+Invoke the service-itsm-swarming-configure skill.
+```
+
+**On success:**
+"Success: Swarming feature enabled, and the Collaboration Tool is now set to Teams — 'Set Teams as
+Collaboration Tool for Swarming' is fully complete, no manual click needed."
+
+**On failure:**
+"Failed: Swarming setup failed: [error details]
+
+Resolution:
+- Ensure Microsoft Teams integration is enabled first (use option #1)
+- Verify org has the Swarming feature entitlement"
+
+---
+
+#### Choice 4: Notifications Setup
+
+**Inline enablement (in-scope exception — no dedicated notifications child skill exists yet).**
+Unlike the other choices, this branch enables the notification-channel org preferences itself. Issue
+the writes with `mcp__headless-360__dispatch` (`PATCH`, full `/services/data/vXX.0/...` path). When a
+dedicated `setup-itsm-notifications-*` child skill lands, delegate to it and drop this inline block.
+
+**Step 4.1: Enable Master Notifications Preference**
+```text
+PATCH /services/data/v66.0/setup/org/preferences/Notifications
+Body: {"desiredState": true}
+```
+
+**Step 4.2: Enable Individual Channels**
+```text
+PATCH /services/data/v66.0/setup/org/preferences/EmailNotifications
+Body: {"desiredState": true}
+
+PATCH /services/data/v66.0/setup/org/preferences/InAppNotifications
+Body: {"desiredState": true}
+
+PATCH /services/data/v66.0/setup/org/preferences/SlackNotifications
+Body: {"desiredState": true}
+
+PATCH /services/data/v66.0/setup/org/preferences/TeamsNotifications
+Body: {"desiredState": true}
+```
+
+**On success:**
+"Success: All notification channels enabled:
+- Email Notifications
+- In-App Notifications
+- Slack Notifications
+- Teams Notifications
+
+Next steps:
+- Create notification definitions at: Setup → Service → Notifications
+- Configure ITSM event triggers
+- Customize message templates"
+
+**On failure:**
+"Failed: Notification channels setup failed: [error details]
+
+Resolution:
+- Verify org has Multi-channel Notifications feature
+- Confirm you have Customize Application permission"
+
+---
+
+#### Choice 5: Portal Setup
+
+**Delegation:**
+```text
+Invoke the experience-portal-create skill.
+```
+
+The portal creation skill will handle all clarifying questions (portal type, name, URL prefix, etc.).
+
+**After delegation:**
+"Success: Portal setup delegated to experience-portal-create skill. Follow the prompts to complete portal creation."
+
+---
+
+## Decision Tree
+
+```text
+User requests ITSM channel setup
+  ↓
+Present menu (5 options)
+  ↓
+User selects option (1-5)
+  ↓
+Validate prerequisites (optional)
+  ↓
+  ├─ Choice 1: Invoke service-itsm-teams-configure
+  ├─ Choice 2: Resolve the Slack skill from the catalog, then invoke it (or manual instructions)
+  ├─ Choice 3: Invoke service-itsm-swarming-configure
+  ├─ Choice 4: Execute notifications setup inline (demo mode)
+  └─ Choice 5: Invoke experience-portal-create
+  ↓
+Report outcome to user
+  ↓
+Suggest next steps
+```
+
+---
+
+## Rules / Constraints
+
+| Constraint | Rationale |
+|---|---|
+| Always present options before proceeding | User may not know what's possible or what their org supports |
+| Validate prerequisites before delegating | Catch licensing/feature gaps early before invoking child skills |
+| Choice 4 uses manual API calls, not a child skill | No existing skill for "notifications without specific channels" |
+| Do not retry failed delegations | Child skills handle their own retries; surfacing error to user for decision |
+| Partial success is acceptable | If Teams succeeds but Notifications fails, user can retry Notifications separately |
+
+---
+
+## Prerequisites by Choice
+
+### Choice 1: Teams Setup
+- Teams ITSM licenses
+- Setup admin permissions
+
+### Choice 2: Slack Setup
+- Slack workspace with admin access
+- Org has Slack integration enabled
+
+### Choice 3: Swarming Setup
+- Microsoft Teams integration (required for Swarming — run Choice 1 first)
+
+### Choice 4: Notifications Setup
+- Multi-channel Notifications feature enabled
+- View Setup + Customize Application permissions
+
+### Choice 5: Portal Setup
+- Vary by portal type (see experience-portal-create skill)
+
+---
+
+## Error Handling
+
+### If user provides invalid choice:
+"Please choose a valid option: 1, 2, 3, 4, or 5."
+
+### If prerequisites check fails:
+"I've detected that your org is missing [specific requirement]. 
+
+I recommend choosing [alternative option] instead, which works with your current org configuration."
+
+### If delegation fails:
+"The [child skill name] encountered an error: [error message]
+
+[Provide specific resolution steps based on error]"
+
+### If user is unsure which to choose:
+"Let me help you decide:
+
+- **Do you want to enable communication channels?**
+  - Microsoft Teams → Choose #1
+  - Slack → Choose #2
+  - Both → Run #1, then #2
+
+- **Do you want collaborative problem-solving?**
+  - Swarming (requires Teams) → Choose #1 first, then #3
+
+- **Do you want notifications for ITSM events?**
+  - Multi-channel notifications → Choose #4
+
+- **Do you want a portal for employee self-service?**
+  - Digital Experience portal → Choose #5"
+
+---
+
+## Related Operations
+
+After completing channel setup via this coordinator:
+
+- **Configure channel-specific settings** — customize each channel's behavior
+- **Create notification definitions** — configure ITSM event triggers (if Notifications selected)
+- **Set up Azure AD** — required for Teams (if Teams selected)
+- **Test channels** — verify each channel is working
+
+To modify later:
+- **Enable additional channels** — rerun this coordinator with different option
+- **Disable channels** — use corresponding disable skills
+- **Update channel settings** — navigate to Setup → [Channel] → Settings
+
+---
+
+## Embedded Agentforce Agent in Microsoft Teams
+
+Making the embedded Agentforce agent actually **reply** inside the Teams custom client
+("Salesforce Employee Assist" / "Ask AI Agent") is the hardest, most under-documented part of
+Teams ITSM. It is now a dedicated skill:
+
+**→ `service-itsm-teams-employee-agent-configure`**
+
+The verified architecture is a **Web** Enhanced-messaging channel with **User Verification OFF
+(auth mode false)** — the Teams client uses the scrt2 *unauthenticated* token endpoint — the
+**`Teams_AgentForce`** custom-client Embedded Service Deployment, an Omni-Flow routing flow
+targeting a **real, Active** Agentforce Employee Agent, and an **Agent Access permission set**
+enabling that agent for the portal user. That skill also covers the key diagnostic: "agent joins
+then leaves without replying" has two fixable causes — auth mode left ON (→ `/eventrouter/v1/sse`
+401) and the portal user missing Agent Access — not an unfixable agent-runtime failure.
+
+---
+
+## API Type Classification
+
+This coordinator:
+- **Does NOT call APIs directly** (except for Choice 4 demo mode) — it delegates to child skills
+- **Uses interactive menu** for user selection
+- **Child skills handle all API calls**
+
+Child skills used:
+- `service-itsm-teams-configure` — headless-360 (Salesforce Go feature-enablement Connect API)
+- Slack ITSM setup skill (resolved from catalog by name pattern) — child skill handles its own API calls
+- `service-itsm-swarming-configure` — headless-360 (Salesforce Go feature-enablement Connect API)
+- Notifications — no dedicated child skill yet; handled inline via Connect API (see Choice 4)
+- `experience-portal-create` — Connect API
+
+---
+
+## Important Notes
+
+1. **This is an interactive coordinator** — it MUST present the menu and wait for user choice before executing anything.
+
+2. **Always delegate to child skills** — this coordinator doesn't implement channel-specific logic; it only routes to the appropriate skill.
+
+3. **Some skills may not exist yet** — if a skill is not found, provide manual setup instructions so the user isn't blocked.
+
+4. **Choice 4 (Notifications) executes inline** — no dedicated notifications child skill exists yet, so this coordinator enables the notification-channel preferences directly (see Choice 4). When such a skill lands, delegate to it and drop the inline block.
+
+5. **Prerequisites vary by channel** — each channel has different licensing and feature requirements.
+
+6. **No retry logic** — this coordinator doesn't retry failed operations. Surface the error and let user decide next steps.
+
+7. **Educational role** — help users understand what each channel does and which prerequisites they need.

package/skills/service-itsm-incident-mgmt-configure/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: service-itsm-incident-mgmt-configure
+description: "Reads and toggles the master Incident Management setting on a Salesforce ITSM org — the org-level switch that turns Incident Management on or off. Reads current state before writing, is idempotent, and requires explicit user confirmation before any change. Use when the user wants to enable, disable, toggle, view, or turn on/off Incident Management (Service ITSM) at the org level. DO NOT TRIGGER for Default Field Validations for Incidents, Auto Closure of Child Incidents, Email-to-Incident sub-toggles, Problem Management, Change Management, Case Management, ITSM External Client App setup, or Incident Priority Matrix configuration (use the service-itsm-incident-priority-configure skill)."
+metadata:
+  version: "1.1"
+  domains: ["Service"]
+  minApiVersion: "67.0"
+  mcpTools:
+    headless-360:
+      tools: ["describe", "discover", "dispatch", "dispatch_readonly"]
+      semver: ">=1.0.0"
+  accessCheck:
+    - type: "userPerm"
+      value: "CustomizeApplication"
+    - type: "orgPerm"
+      value: "IncidentMgmt.orgHasITSMOrgPermission"
+allowed-tools: |
+  Read AskUserQuestion
+  mcp__headless-360__discover
+  mcp__headless-360__describe
+  mcp__headless-360__dispatch
+  mcp__headless-360__dispatch_readonly
+---
+
+# Configuring ITSM Incident Management (master toggle)
+
+Read and toggle the **master Incident Management** setting on a Salesforce ITSM org. This is the org-level switch that turns Incident Management on or off. Enabling it also brings up its sub-features on the server side, so a full enablement is a single operation on the master.
+
+Writes are **idempotent** (skipped when the current status already matches the requested state), the skill always **reads before it writes**, and an explicit **confirm-to-write** checkpoint is required before any mutation.
+
+## What this skill controls
+
+| Preference (Setup UI label) | In scope |
+|-----------------------------|----------|
+| Incident Management enablement (master) | Yes — read and toggle |
+| Default Field Validations for Incidents, Auto Closure of Child Incidents, Email-to-Incident sub-toggles, Incident Priority Matrix, Problem/Change/Case Management, ITSM External Client App setup | No |
+
+For the exact URLs, wire shapes, and worked examples for the master read and write, see `references/mcp-invocation.md`.
+
+## Scope
+
+- **In scope**: read and toggle the master Incident Management preference.
+- **Out of scope**: Default Field Validations for Incidents (`IncidentValidationsEnabled`); Incident Priority Matrix configuration; Auto Closure of Child Incidents and Email-to-Incident sub-toggles; Problem Management; Change Management; Case Management; ITSM External Client App setup; other ITSM prefs (`IncidentTriageAgentEnabled`, `IncAssignWithAgentEnabled`, `AssignedGroupValidationEnabled`); broadcast-channel prefs; creation or configuration of Incident, Problem, or ChangeRequest records.
+
+---
+
+## Preconditions
+
+Before the skill can call anything on `headless-360`, the target org and MCP client must be configured. If any of these are unmet, the tools will surface as `401`, `403`, or `404` on the first call; **do not fabricate state — surface the raw error and stop**.
+
+1. **Server activated on the org**: Setup → MCP Servers → `headless-360` → **Activate**. Activation can take up to ~2 minutes.
+2. **External Client App wired**: an ECA in the org with OAuth scopes `mcp_api` and `refresh_token`, JWT-based access tokens enabled, PKCE required. ECA propagation can take up to 30 minutes.
+3. **API v67.0+**: required for the read and write routes this skill uses.
+4. **MCP client registration**: the client (adk-eval / Claude Code) has an `additionalServers.headless-360` entry pointing to the correct env URL (see `references/mcp-invocation.md`).
+
+If any precondition fails, the tools return one of:
+- `401 Unauthorized` → ECA not propagated, wrong scopes, or expired token.
+- `403 Forbidden` → user lacks perm, or org missing `IncidentMgmt.orgHasITSMOrgPermission`.
+- `404 Not Found` → server not activated on the org.
+
+Report the raw response verbatim rather than guessing which precondition failed.
+
+---
+
+## Architecture — How configuration works
+
+| Step | What happens | Tool |
+|------|--------------|------|
+| Preflight | Confirm the target routes are reachable | `describe`, `dispatch_readonly` |
+| Read schema | Fetch the request/response contract for the read and the write | `describe` |
+| Read current state | Fetch the current status of the master preference | `dispatch_readonly` |
+| Decide operation | View / enable / disable — inferred from the prompt | — |
+| Confirm-to-write | Present `(status: current → requested)` and require explicit "yes" | — |
+| Apply change | Enable or disable the master via the write route | `dispatch` |
+| Verify | Re-read and compare against the requested state | `dispatch_readonly` |
+
+**Idempotency**: after the Phase-3 read, if the current state already matches the requested state, skip Phase 5 and treat the operation as a no-op. `references/mcp-invocation.md` documents the exact status field and match rule.
+
+**Read-only tool selection**: use `dispatch_readonly` for the read. Use `dispatch` for the write. The server refuses mutating operations through `dispatch_readonly`.
+
+**Wire shape**: `dispatch` and `dispatch_readonly` both take `{"url": "/services/data/...", "method": "GET|POST|PATCH|...", "body"?: {...}, "query_params"?: {...}}`. See `references/mcp-invocation.md` for the exact request/response shapes; call `describe` at runtime to confirm.
+
+---
+
+## Clarifying Questions
+
+Ask only what is not already in conversation context:
+
+| Field | Description | Default |
+|-------|-------------|---------|
+| Requested direction | Explicit `enable` / `disable` (or `on` / `off`) | REQUIRED — no defaults; ask if the user only said "toggle" without a direction |
+| Confirm write | Explicit "yes" before any `dispatch` mutation | **REQUIRED** — see Phase 4 |
+
+If the user says "toggle" without specifying a direction, ask for the direction before Phase 4. Do not infer it from the current state.
+
+---
+
+## Workflow
+
+All steps run against the `headless-360` MCP server; the tool namespace is `mcp__headless-360__<tool-name>`.
+
+### Phase 0 — Reuse what the session already knows
+
+Each preflight read below carries a **skip-if-already-known** clause. Before calling any
+read endpoint, check whether an earlier turn in this session already produced the same
+fact from a successful tool response tied to the current org (a prior invocation of this
+skill, a parent orchestrator's live read, or an earlier `dispatch_readonly` this run).
+**An explicit user statement is NOT a substitute** for a live read of the master
+preference — user assertions can be stale or mistaken, and this skill relies on the read
+being the source of truth for the confirmation payload and the Phase-6 idempotency verify.
+When the only source is a user statement, re-read.
+
+- **`describe` of the master read/write routes** — if the request/response schemas were
+  already fetched against the current org this session, skip Phase 1 and Phase 2 and
+  reuse the cached schema. `describe` output is stable within a session.
+- **Current master preference state** — if the master `IncidentMgmtEnabled` value for
+  the current org was already read this session **via a successful `dispatch_readonly`
+  response** (Phase 3 result from an earlier run of this skill, or a parent orchestrator
+  that already asked us to check), skip Phase 3 and reuse the recorded "before" value.
+  A user's verbal claim that the switch is on or off is **not** cache-eligible.
+
+**When in doubt, re-check.** Skip only when the earlier fact is unambiguously in context
+AND you have not switched orgs — the `headless-360` MCP session binds to one org via the
+JWT, so an org change is only possible if the session was re-authed mid-conversation. If
+the user hints at a different org, or you cannot tell which org the earlier fact came
+from, re-run the read. Note: any `dispatch` write elsewhere in the session that could
+have flipped the master (this skill's Phase 5, or an admin change via another tool) also
+invalidates the cache — re-read. A wrong skip on a live org write is worse than a
+duplicated read.
+
+### Phase 1 — Preflight (`discover` / `describe`)
+
+1. *(Skip if the operation schemas were already verified this session — see Phase 0.)*
+   Call `describe` on the read/write routes (or `discover` with a query like `"ITSM incident management setup discovery"` if the operation IDs are unknown). Confirm the operations exist and their argument schemas match `references/mcp-invocation.md`.
+2. If any tool call returns `401` / `403` / `404`, halt and surface the raw error — the org or client is not configured correctly (see Preconditions).
+
+### Phase 2 — Load Schemas (`describe`)
+
+3. *(Skip if the schema for each operation is already cached this session — see Phase 0.)*
+   For each operation the invocation will use, call `describe` and cache the returned request/response schema. **Do not hard-code the argument shape from the reference doc** — read it from `describe`; the docs are a working expectation, the runtime contract is whatever `describe` returns.
+
+### Phase 3 — Read Current State (`dispatch_readonly`)
+
+4. *(Skip if the current master state for this org was already read this session AND no
+   write has flipped it since — see Phase 0.)*
+   Read the current state of the master preference using the read route documented in `references/mcp-invocation.md`. Record the value as the "before" state for the Phase-4 confirmation and the Phase-6 verify.
+
+   For a view-only request, stop after Phase 3 and go to Phase 7 to report.
+
+### Phase 4 — Decide Operation + Confirm-to-Write (REQUIRED for any write)
+
+5. Decide the operation from the user's prompt (view / enable / disable). If the user said "toggle" without a direction, ask for the direction first.
+
+6. **Present the target payload** via `AskUserQuestion` as `(Master Incident Management: <current> → <requested>)`. Require an explicit "yes" before proceeding. **Proceed to Phase 5 ONLY on explicit "yes".** On "no", stop and report the current state without writing.
+
+### Phase 5 — Apply the Change (skip for view-only)
+
+7. Apply the idempotency rule from `references/mcp-invocation.md`: if the current state already matches the requested state, skip Phase 5 and mark the operation as an idempotent no-op.
+
+8. Otherwise, dispatch the write via `dispatch` using the enable or disable route documented in `references/mcp-invocation.md`. Enabling the master brings up the Incident Management sub-features on the server side — no separate calls are needed to turn them on. Disabling the master leaves those sub-features at their last-set values.
+
+9. On error (`4xx`, `5xx`), record the raw response verbatim and stop.
+
+### Phase 6 — Verify (`dispatch_readonly`)
+
+10. Re-issue the Phase-3 read and compare against the requested state per the rule in `references/mcp-invocation.md`. If they differ, treat it as a failed write and report the raw server response verbatim.
+
+### Phase 7 — Report
+
+11. Present a before/after summary:
+    - View: `Master Incident Management: <current-status>`.
+    - Toggle: `Master Incident Management: <before> → <after>` with verdict `SUCCEEDED` / `ALREADY-<state>` / `FAILED`.
+    - On Phase-6 mismatch: `write FAILED — server state differs from request. Server response: <verbatim>`.
+
+---
+
+## Rules / Constraints
+
+| Constraint | Rationale |
+|-----------|-----------|
+| All operations run through the four hosted `headless-360` tools | The hosted MCP is the required transport |
+| Read the argument schema for each operation via `describe` before calling `dispatch` / `dispatch_readonly` | The runtime contract is what `describe` returns; do not hard-code |
+| Use `dispatch_readonly` for the read; use `dispatch` for the write | The server refuses mutating operations through `dispatch_readonly` |
+| Always set/expect API **v67.0** minimum | The read and write routes require v67+ |
+| Read live state before writing | The Phase-3 fetch is the source of truth for the confirmation prompt, the idempotency check, and the Phase-6 verify |
+| **REQUIRED confirm-to-write checkpoint** before any `dispatch` mutation | Toggling this pref mutates org state; user must approve the exact plan |
+| Idempotent — skip `dispatch` when the current state already matches the requested state | Avoids no-op writes; see `references/mcp-invocation.md` for the exact match rule |
+| Report exact error text from the MCP tool response | The server surfaces the underlying error message verbatim |
+| On `401` / `403` / `404` in Phase 1, halt and surface the raw error | The failing precondition is diagnosable only from the raw response |
+| Do not put an orgId or Core URL in the `dispatch` arguments | The server derives the target org from the JWT issuer on the request |
+
+---
+
+## Verification Checklist
+
+Before reporting completion of any mutation, confirm each of the following. If any item is unchecked, do not report success — surface what is missing.
+
+- [ ] Phase 1 preflight (`describe` / `discover`) returned the operation without a `401` / `403` / `404`; if any was returned, the raw error was surfaced and the run halted.
+- [ ] Phase 3 read against the master preference returned a status and that value was recorded as the "before" state.
+- [ ] Phase 4 confirm-to-write presented `(Master Incident Management: <current> → <requested>)` via `AskUserQuestion` and the user replied with an explicit "yes" — no write dispatched on any other response (silence, "maybe", "looks good", implicit approval).
+- [ ] Idempotency: if the current state already matched the requested state, Phase 5 was skipped and the run was reported as an idempotent no-op — no `dispatch` write was issued.
+- [ ] Phase 5 write used `dispatch` (not `dispatch_readonly`) with the wire shape from `references/mcp-invocation.md`; on any `4xx` / `5xx`, the raw response was surfaced and the run halted.
+- [ ] Phase 6 verify re-issued the Phase-3 read and the post-write state matched the user-approved target; any diff was reported as `write FAILED — server state differs from request`.
+- [ ] The final report gave a before/after for the master preference with verdict `SUCCEEDED` / `ALREADY-<state>` / `FAILED`.
+
+---
+
+## Reference File Index
+
+| File | When to read |
+|------|--------------|
+| `references/mcp-invocation.md` | Exact tool call shapes for the master read and write, MCP-client registration recipe for `headless-360` in `mcp-config.json`, External Client App setup checklist (`mcp_api` scope, PKCE, JWT), Headless-360 error taxonomy, and a worked enable/disable example |