@salesforce/afv-skills 1.40.0 → 1.41.0

package/skills/service-itsm-agentic-setup-incident-sla-configure/examples/milestone-patterns.md

@@ -0,0 +1,193 @@
+# Milestone Strategy Patterns — Incident SLA
+
+Phase 1.4 of the SLA workflow either infers the milestone strategy from the user's prompt (see
+"Phase 1.4 skip conditions" below) or asks the user to pick one. This file lists each option with
+its default configuration, MilestoneType-reuse rules, and the exact `Attach Milestone` payloads
+that Phase 2 step 10 dispatches. Every `filterItems.operator` value here uses the exact enum the
+server accepts — `Equals`, `NotEqual` — never `!=` or `Equal`.
+
+---
+
+## Phase 1.4 skip conditions (do NOT dispatch `AskUserQuestion` when any hold)
+
+Every SLA policy needs at least one milestone, but the strategy question is skipped when the
+milestone shape is already determined by the request:
+
+- **(a) The prompt / conversation already describes a concrete milestone shape** — e.g. "60-minute
+  first-response trigger", "Response + Resolution defaults", "per-priority tiers". Extract the
+  described milestone(s) verbatim (time, criteria, name) and use the pattern defaults below. Do
+  NOT re-ask.
+- **(b) The eventual branch is an idempotent no-op** — Phase 1 step 6 established `noOp=true`
+  (every requested artifact already exists with matching configuration). Skip Phase 1.4, skip
+  Phase 2, and report the no-op verbatim citing the read evidence.
+- **(c) Explicit up-front authorization** — a phrase that unambiguously waives the confirm gate
+  (`"you have my explicit authorization to create"`, `"do not re-ask me to confirm"`,
+  `"proceed without asking"`) **and** a concrete milestone shape is derivable per (a). A passing
+  mention ("build it", "go ahead") is NOT sufficient by itself. Waives the interactive confirm;
+  does NOT waive Phase 1.5 plan-narration — dispatch only after SLA Policy name, Account,
+  Entitlement date range, and per-milestone list have been written to the response.
+
+**Only when none of (a)/(b)/(c) apply** (generic "set up an SLA on Incidents" with no shape),
+dispatch `AskUserQuestion` with the five options below. Priority-tiered requires the
+`Incident.Priority` picklist — validate before offering.
+
+All strategies share these defaults unless overridden:
+
+- `businessHoursId`: the default BusinessHours resolved in Phase 1 step 4
+- `startTimeBasedOn`: `SlaProcessCreatedDate`
+- `milestoneState`: `Active`
+- `milestoneAgreementType`: `Warning`
+- `filterType`: `RuleFilter`
+- Base filter row: `Incident.Status NotEqual Closed` (keeps every milestone alive until the
+  Incident closes; ANDs with pattern-specific criteria below)
+
+---
+
+## AskUserQuestion prompt (Phase 1.4, only when no skip condition applies)
+
+```text
+Question: How many milestones do you want on this SLA policy?
+
+  1. Single milestone            — one 60-min First Response timer (simplest)
+  2. Response + Resolution       — 30-min response + 8-hour resolution (classic)
+  3. Priority-tiered response    — one timer per Priority (Critical/P1 15 / High/P2 60 / Moderate (a.k.a. Medium)/P3 240 / Low/P4 1440 min)
+  4. Escalation ladder           — Response (30) → Manager Escalation (120) → Executive Escalation (480 min)
+  5. Custom / mixed              — walk through each milestone individually (name, time, criteria)
+```
+
+For options 3 and 4, the concrete numbers are the defaults the skill uses if the user picks the
+option without customizing. Option 5 dispatches follow-up `AskUserQuestion` prompts.
+
+Before rendering options 3 and 5, confirm the live `Incident.Priority` picklist values (fetched in
+Phase 1 via the Incident describe) — if any value used in a default row is missing from the org's
+picklist, drop that milestone from the pattern and note it in the Phase-1.5 confirmation.
+
+---
+
+## Canonical Attach-Milestone payload
+
+Dispatch every pattern below via `mcp__headless-360__dispatch` with `method: "POST"` and
+`url: "/services/data/v67.0/connect/sla-management/sla-policies/<slaId>/milestones"` (substitute
+the SLA policy id captured in Phase 2 step 9). The reusable request-body template lives at
+`assets/attach-milestone.json` — load and populate it rather than reconstructing the JSON.
+
+Substitute per-pattern: `milestoneTypeId` is the id returned when you created the MilestoneType,
+`businessHoursId` is the id resolved in Phase 1, and `timeTrigger` + `order` come from the
+pattern's row. `filterItems` in the template carries the base "Status != Closed" row that every
+pattern shares; each pattern's table lists **additional** row objects to append to `filterItems`
+(same schema: `table`, `column`, `operator`, `order`, `value`) — do not replace the base row, add
+to it.
+
+---
+
+## Pattern 1 — Single milestone (default)
+
+**MilestoneTypes to create:** 1 — `Incident First Response`
+**Milestones to attach:** 1
+
+| # | MilestoneType | timeTrigger | Extra filter items |
+|---|---------------|-------------|--------------------|
+| 1 | Incident First Response | 60 | *(none — Status != Closed only)* |
+
+---
+
+## Pattern 2 — Response + Resolution
+
+**MilestoneTypes to create:** 2 — `Incident First Response`, `Incident Resolution`
+**Milestones to attach:** 2
+
+| # | MilestoneType | timeTrigger | Extra filter items |
+|---|---------------|-------------|--------------------|
+| 1 | Incident First Response | 30 | *(none)* |
+| 2 | Incident Resolution     | 480 (8 hours) | *(none)* |
+
+Both milestones only enforce `Status != Closed`. Response fires first (30 min); Resolution runs
+concurrently on its own 8-hour timer.
+
+---
+
+## Pattern 3 — Priority-tiered response
+
+**MilestoneTypes to create:** 1 — `Incident First Response` (reused across all four milestones)
+**Milestones to attach:** up to 4 (one per active Priority value)
+
+| # | Priority | timeTrigger | Extra filter items |
+|---|----------|-------------|--------------------|
+| 1 | Critical | 15  | `Incident.Priority Equals Critical` |
+| 2 | High     | 60  | `Incident.Priority Equals High` |
+| 3 | Moderate | 240 | `Incident.Priority Equals Moderate` |
+| 4 | Low      | 1440 | `Incident.Priority Equals Low` |
+
+Assumes the standard `Critical / High / Moderate / Low` picklist (some orgs and prompts label the
+mid tier `Medium` instead of `Moderate` — same P3 tier, different label). If the org has renamed /
+removed / added values (checked against the Phase-1 Incident describe), drop or rename milestones
+to match — do not send `Priority Equals <value>` for a value that is not in the live picklist (the
+server accepts it silently and the milestone never engages).
+
+The multi-item `filterItems` array combines with `AND` by default — both `Status != Closed` AND
+`Priority == Critical` must hold for the milestone to remain active. If Priority flips after
+Incident create (e.g. via the Priority Matrix), the milestone re-evaluates on the next server pass.
+
+---
+
+## Pattern 4 — Escalation ladder
+
+**MilestoneTypes to create:** 3 — `Incident First Response`, `Incident Manager Escalation`,
+`Incident Executive Escalation`
+**Milestones to attach:** 3
+
+| # | MilestoneType | timeTrigger | Extra filter items |
+|---|---------------|-------------|--------------------|
+| 1 | Incident First Response      | 30  | *(none)* |
+| 2 | Incident Manager Escalation  | 120 | *(none)* |
+| 3 | Incident Executive Escalation | 480 | *(none)* |
+
+All three run concurrently from `SlaProcessCreatedDate` — the "ladder" is enforced by the timers,
+not by chaining. Strictly sequential escalation requires workflow SLA actions
+(`POST /connect/workflow-sla-actions/execute-actions`), which is out of scope for this skill.
+
+---
+
+## Pattern 5 — Custom / mixed
+
+For genuinely custom setups, the skill walks the user through each milestone one at a time with
+`AskUserQuestion`.
+
+For each milestone `i` from 1 to N (where N is confirmed up front):
+
+1. **Milestone name** — used as the MilestoneType label. Reuse an existing MilestoneType if the
+   name matches one already created in this run; otherwise create a new one.
+2. **Time trigger (minutes)** — integer, business-hours-aware.
+3. **Criteria field** — the `Incident.*` field to filter on (default `Status`). For custom
+   fields, use the `Incident.<Field>__c` API name.
+4. **Criteria operator** — one of `Equals`, `NotEqual`, `LessThan`, `GreaterThan`, `Contains`,
+   `StartsWith`, `Includes` (server enum — no `!=`, no `Equal`).
+5. **Criteria value** — validated against the live picklist for picklist fields; free-form
+   otherwise.
+
+After collecting all N milestones, render the full list in Phase 1.5 confirmation and require an
+explicit "yes" before dispatching the create loop.
+
+**Custom-mixed example** (Response for all + per-category resolution):
+
+| # | Name                        | timeTrigger | Filter items |
+|---|-----------------------------|-------------|--------------|
+| 1 | Incident First Response     | 30  | `Status NotEqual Closed` |
+| 2 | Outage Resolution           | 240 | `Status NotEqual Closed`, `Category Equals Availability` |
+| 3 | Request Resolution          | 1440 | `Status NotEqual Closed`, `Category Equals Request` |
+
+For rows 2 and 3, first confirm `Category` is present on the org's Incident picklist and that the
+values are active — if not, ask the user which category values they actually want to filter on
+before creating the MilestoneType or attaching the milestone.
+
+---
+
+## Gotchas across all patterns
+
+| Issue | Detail |
+|-------|--------|
+| MilestoneType reuse vs. create | Priority-tiered = 1 MilestoneType reused 4 times. Response + Resolution = 2 types. Escalation ladder = 3 types. |
+| Priority-tiered needs a Priority | The test Incident in Phase 3 must have a `Priority` value matching one of the milestones — otherwise no EntityMilestone spawns. Set the Priority explicitly, or create one test Incident per Priority. |
+| Multi-milestone partial-failure | If milestone #2 of N fails to attach, halt and surface the raw error. Do NOT continue attaching #3..N — the policy will be half-configured. |
+| `order` field | Numeric 1..N. Not load-bearing for runtime evaluation (all milestones fire independently), but controls display order in the UI. |
+| Priority-tiered + Priority Matrix skill | If the Priority Matrix skill is also running, its Impact × Urgency grid decides `Incident.Priority`. Enable the matrix first if you want new Incidents to derive Priority from the matrix. |

package/skills/service-itsm-agentic-setup-incident-sla-configure/examples/output-templates.md

@@ -0,0 +1,57 @@
+# Output Templates — Incident SLA Setup
+
+Canonical result-report strings for the SLA setup skill. Fill in the placeholders — do **not** substitute Salesforce record IDs into the user-facing output.
+
+## Failure
+
+Display the error from the `dispatch` response (`{status_code, body}`) exactly as returned, name the step that failed, and refer to `references/mcp-invocation.md` for known workarounds.
+
+## Success — single milestone
+
+```text
+Incident SLA Setup Complete (via service-itsm-agentic-setup-incident-sla-configure)
+
+Artifacts created:
+  Milestone Type: <name> (OneTime)
+  SLA Policy:     <name> (Active, Incident)
+  Milestone:      <time> min, criteria: <criteria summary>
+  Entitlement:    <name> -> Account: <account name>
+
+Verification:
+  Incident:  <IncidentNumber> — "<Subject>"
+  SLA Start: <timestamp>
+  Milestone: <MilestoneType name>
+  Target:    <TargetDate> (Start + <timeTrigger> min)
+  Status:    EntityMilestone auto-created — SLA is active
+
+Chain: MilestoneType > SLA Policy > Milestone > Entitlement > Incident > EntityMilestone
+```
+
+## Success — multi-milestone (list every attached milestone)
+
+```text
+Incident SLA Setup Complete (via service-itsm-agentic-setup-incident-sla-configure)
+
+Strategy: <Response + Resolution | Priority-tiered | Escalation ladder | Custom>
+
+Artifacts created:
+  Milestone Types: <name1>, <name2>, ... (OneTime)
+  SLA Policy:      <name> (Active, Incident)
+  Milestones:
+    #1  <MilestoneType name>   <time> min   criteria: <summary>
+    #2  <MilestoneType name>   <time> min   criteria: <summary>
+    ...
+  Entitlement:     <name> -> Account: <account name>
+
+Verification:
+  Incident:  <IncidentNumber> — "<Subject>" (Priority=<value>)
+  SLA Start: <timestamp>
+  EntityMilestones fired:
+    - <MilestoneType name>   Target: <TargetDate>   (Start + <timeTrigger> min)
+    - ...
+  Status:    <N> EntityMilestone(s) auto-created — SLA is active
+
+Chain: MilestoneTypes > SLA Policy > Milestones > Entitlement > Incident > EntityMilestones
+```
+
+No record IDs in user-facing output. No files are produced — the skill mutates org configuration in place through headless-360 MCP dispatch.

package/skills/service-itsm-agentic-setup-incident-sla-configure/references/mcp-invocation.md

@@ -0,0 +1,394 @@
+# MCP Invocation Reference — Incident SLA
+
+Every operation dispatches through the **Salesforce-hosted `headless-360`** MCP server, which
+exposes four meta-tools:
+
+- `mcp__headless-360__discover(query)` — semantic search over the indexed operation catalog
+- `mcp__headless-360__describe(id)` — pulls the schema and canonical route for one operation
+- `mcp__headless-360__dispatch_readonly({url, method, query_params?, body?})` — GET / read-only HTTP
+- `mcp__headless-360__dispatch({url, method, body?, query_params?})` — POST / PATCH / DELETE HTTP
+
+**Dispatch takes raw HTTP**, not `{operation_id, arguments}`. Give it the full `url`
+(`/services/data/v67.0/...`), `method`, optional `body`, and optional `query_params` — the server
+signs the request with the JWT bound to the current MCP session and forwards it to the org. The
+skill never handles credentials or an org alias — everything is derived from the session.
+
+## Response envelope
+
+The SLA Management Connect API, `/sobjects/…` REST endpoints, and `/query` are **standard REST** —
+singly wrapped:
+
+```json
+{ "status_code": 200, "body": <REST/Connect response> }
+```
+
+Read `body`. (Only `/headless/invoke/…` Aura-controller routes are doubly wrapped as `body.body`;
+this skill uses none.)
+
+---
+
+## Routes
+
+| Method + path | Purpose |
+|---------------|---------|
+| `GET  /services/data/v67.0/connect/setup/discovery/feature/service-cloud-itsm-manage-sla-policies/status` | Phase 0.5 — read the SLA Management for IT Service feature status |
+| `POST /services/data/v67.0/connect/setup/discovery/feature/service-cloud-itsm-manage-sla-policies/enable` | Phase 0.5 — enable the feature (flips Simplified SLA Setup) |
+| `GET  /services/data/v67.0/tooling/query` | Phase 0.5 — read SLA Versioning (`EntitlementSettings.IsEntitlementVersioningEnabled`) via `query_params.q` |
+| `PATCH /services/data/v67.0/tooling/sobjects/EntitlementSettings/000000000000000AAA` | Phase 0.5 — turn on SLA Versioning if off |
+| `GET  /services/data/v67.0/sobjects/Incident/describe` | Preflight — Incident Management on + SLA fields present |
+| `GET  /services/data/v67.0/query` | SOQL reads (BusinessHours, SlaProcess, EntityMilestone) via `query_params.q` |
+| `POST /services/data/v67.0/connect/sla-management/milestone-types` | Create MilestoneType |
+| `POST /services/data/v67.0/connect/sla-management/sla-policies` | Create SLA Policy (SlaProcess) |
+| `POST /services/data/v67.0/connect/sla-management/sla-policies/<slaId>/milestones` | Attach Milestone |
+| `POST /services/data/v67.0/sobjects/Entitlement` | Create Entitlement (standard sObject) |
+| `POST /services/data/v67.0/sobjects/Incident` | Create a test Incident |
+
+Minimum API version is **67.0** — `headless-360` currently only routes `v67.0+`.
+
+---
+
+## Phase 0.5 — SLA Management for IT Service prerequisite gate
+
+"SLA Management for IT Service" is a Salesforce Go Setup Discovery feature — verified apiName
+`service-cloud-itsm-manage-sla-policies`. **Do not guess other apiNames for this** — every other
+guess returns `400 NOT_FOUND`; this exact string is the correct one. If it ever needs re-confirming
+for a different org/release, the list-all route `GET /services/data/v67.0/connect/setup/discovery/features`
+returns every feature's apiName + status in one call.
+
+Enabling this feature flips `EntitlementSettings.IsEntitlementsEnabled` and **Simplified SLA
+Setup** together — Simplified SLA Setup has **no Tooling/Metadata API exposure**, so a Tooling
+PATCH to `EntitlementSettings` alone can never complete it.
+
+**SLA Versioning is separate and NOT touched by the feature enable call.** It maps to
+`EntitlementSettings.IsEntitlementVersioningEnabled` (Tooling object, singleton, fixed Id
+`000000000000000AAA`, keyPrefix `0HE`, one row per org) and must be checked/enabled independently.
+
+### Read — feature status
+
+```json
+mcp__headless-360__dispatch_readonly({
+  "url":    "/services/data/v67.0/connect/setup/discovery/feature/service-cloud-itsm-manage-sla-policies/status",
+  "method": "GET"
+})
+```
+
+```json
+{
+  "apiName": "service-cloud-itsm-manage-sla-policies",
+  "status": "NOT_ENABLED",
+  "enableBlockedReasons": [],
+  "disableBlockedReasons": [],
+  "blockedByApexLock": false,
+  "dependencyStatuses": []
+}
+```
+
+- `status == "ENABLED"` → the feature (and Simplified SLA Setup) is on — move to the SLA Versioning
+  read below.
+- `status == "NOT_ENABLED"` with non-empty `enableBlockedReasons` → **stop**, relay the reasons, do
+  not attempt to enable.
+- `status == "NOT_ENABLED"` with empty `enableBlockedReasons` → confirm with the user, then enable.
+
+### Read — SLA Versioning
+
+```json
+mcp__headless-360__dispatch_readonly({
+  "url": "/services/data/v67.0/tooling/query",
+  "method": "GET",
+  "query_params": { "q": "SELECT IsEntitlementVersioningEnabled FROM EntitlementSettings" }
+})
+```
+
+```json
+{
+  "size": 1, "totalSize": 1, "done": true,
+  "records": [{ "IsEntitlementVersioningEnabled": true }]
+}
+```
+
+**SLA Versioning is a one-way switch.** Once `IsEntitlementVersioningEnabled` is `true`, Salesforce
+does not support flipping it back — even if SLA Management is later turned off. Always surface this
+to the user before enabling it — never enable silently.
+
+### Enable — feature (only after explicit user confirmation)
+
+```json
+mcp__headless-360__dispatch({
+  "url":    "/services/data/v67.0/connect/setup/discovery/feature/service-cloud-itsm-manage-sla-policies/enable",
+  "method": "POST",
+  "body":   {}
+})
+→ 201 { "success": true }
+```
+
+Do not trust `success: true` alone — re-run the status GET above and require `"status": "ENABLED"`
+before moving on.
+
+### Enable — SLA Versioning (only after explicit user confirmation, separately)
+
+```json
+mcp__headless-360__dispatch({
+  "url":    "/services/data/v67.0/tooling/sobjects/EntitlementSettings/000000000000000AAA",
+  "method": "PATCH",
+  "body": {
+    "FullName": "EntitlementSettings",
+    "Metadata": { "enableEntitlementVersioning": true }
+  }
+})
+→ 204 No Content (empty body)
+```
+
+`FullName` is mandatory — the PATCH is rejected without it. The PATCH response body is empty on
+success — **re-run the Tooling query above and require `IsEntitlementVersioningEnabled: true`**
+before moving on, same rule as the SLA Policy create response later in this flow (never trust a
+write response alone).
+
+---
+
+## Discovery — always run first
+
+```text
+mcp__headless-360__discover(query="sla-management milestone")
+```
+
+`discover` returns matching operation ids. Pipe each id into `describe` to pull its input schema
+and canonical HTTP route:
+
+```text
+mcp__headless-360__describe(id="<operation_id_from_discover>")
+```
+
+| Operation | Method | Purpose |
+|-----------|--------|---------|
+| `…connect.sla-management.milestone-types` (create) | POST | Create MilestoneType |
+| `…connect.sla-management.sla-policies` (create) | POST | Create SLA Policy |
+| `…connect.sla-management.sla-policies.{id}.milestones` (create) | POST | Attach Milestone |
+
+**Corpus ≠ registry**: `discover` may only surface adjacent SLA endpoints (e.g. workflow-fields /
+workflow-sla-actions) because the SLA Management POST routes are documented but not always ranked
+first. The routes are known-good — `describe` on the `milestone-types` / `sla-policies` operations
+still returns the schema, and `dispatch` still works even if `discover` didn't rank them at the top.
+If `discover` returns nothing at all after rewording the query, the org's `headless-360` corpus
+does not index this surface — direct the user to Setup and stop.
+
+---
+
+## Preflight A — Master Incident Management pref (direct read)
+
+The master ITSM Incident Management pref is exposed on the **Setup Discovery Connect API**
+under `apiName = service-cloud-itsm-incident`. The setup-org-preferences endpoint does not
+expose the master (`IncidentMgmtEnabled` / `ITSMIncidentMgmtEnabled` both 404) — read via
+Setup Discovery instead.
+
+```json
+mcp__headless-360__dispatch_readonly({
+  "url":    "/services/data/v67.0/connect/setup/discovery/features",
+  "method": "GET"
+})
+```
+
+The endpoint returns the full feature catalog (~763 entries, ~1.1 MB) and does not honor
+`?apiName=` server-side. Filter `body.features[]` client-side to the element where
+`apiName == "service-cloud-itsm-incident"` and read its `status` (`ENABLED` / `NOT_ENABLED`).
+
+**Auto-delegate rule**: if `status != "ENABLED"`, delegate to
+`service-itsm-incident-mgmt-configure` inline before continuing — that skill runs its own
+confirm-to-write against the enable route (`POST .../setup/discovery/feature/service-cloud-itsm-incident/enable`)
+and returns after the flip. Re-read this step to verify `status == "ENABLED"` before
+continuing. If the user declines the delegation, halt — every downstream SLA artifact
+depends on the master being on.
+
+## Preflight B — SLA fields on the Incident sObject
+
+```json
+mcp__headless-360__dispatch_readonly({
+  "url":    "/services/data/v67.0/sobjects/Incident/describe",
+  "method": "GET"
+})
+```
+
+Confirm `body.fields[]` includes `EntitlementId`, `SlaStartDate`, and `SlaExitDate`. If the
+describe 404s or the fields are missing, Entitlement Management is not enabled for Incident —
+stop and direct the user to **Setup → Incident Management / Entitlement Settings**. This is
+a **secondary sanity check on the SLA-field surface**, not the master-pref state signal;
+Preflight A above is the master-state signal.
+
+The response is large (~86 KB). If your host truncates it, filter with a grep-style search rather
+than reading the whole body — you only need to confirm those three field names exist.
+
+---
+
+## Default BusinessHours
+
+```json
+mcp__headless-360__dispatch_readonly({
+  "url":    "/services/data/v67.0/query",
+  "method": "GET",
+  "query_params": { "q": "SELECT Id, Name FROM BusinessHours WHERE IsActive = true AND IsDefault = true" }
+})
+```
+
+`body.records[0].Id` is the `BusinessHoursId` used on the SLA Policy, Milestone, and Entitlement.
+If `body.records` is empty, stop — the user must create default Business Hours in Setup.
+
+---
+
+## Create MilestoneType
+
+```json
+mcp__headless-360__dispatch({
+  "url":    "/services/data/v67.0/connect/sla-management/milestone-types",
+  "method": "POST",
+  "body": {
+    "name":          "Incident First Response",
+    "description":   "Incident First Response",
+    "recurrenceType": "OneTime"
+  }
+})
+```
+
+`recurrenceType` = `OneTime` | `Recurring`. Success: `body.id` is the new MilestoneType Id. If
+absent, the create failed — surface `body`.
+
+---
+
+## Create SLA Policy (SlaProcess)
+
+```json
+mcp__headless-360__dispatch({
+  "url":    "/services/data/v67.0/connect/sla-management/sla-policies",
+  "method": "POST",
+  "body": {
+    "name":                    "Incident SLA Policy",
+    "description":             "Incident SLA Policy",
+    "processType":             "Incident",
+    "businessHourId":          "<BusinessHoursId>",
+    "createdDateEntryCriteria": true,
+    "closedExitCriteria":       true,
+    "active":                   true,
+    "versionDefault":           true
+  }
+})
+```
+
+**The response body echoes most fields as `null`.** Do not trust it — capture `body.id` and
+verify state via SOQL:
+
+```json
+mcp__headless-360__dispatch_readonly({
+  "url":    "/services/data/v67.0/query",
+  "method": "GET",
+  "query_params": { "q": "SELECT Id, Name, SObjectType, IsActive, BusinessHoursId FROM SlaProcess WHERE Id = '<slaId>'" }
+})
+```
+
+---
+
+## Attach Milestone
+
+`slaProcessId` is carried by the URL path — **omit it from the body** (the server returns
+`JSON_PARSER_ERROR: Unrecognized field "slaProcessId"`).
+
+```json
+mcp__headless-360__dispatch({
+  "url":    "/services/data/v67.0/connect/sla-management/sla-policies/<slaId>/milestones",
+  "method": "POST",
+  "body": {
+    "milestoneTypeId":  "<MilestoneTypeId>",
+    "businessHoursId":  "<BusinessHoursId>",
+    "timeTrigger":      60,
+    "order":            1,
+    "startTimeBasedOn": "SlaProcessCreatedDate",
+    "milestoneCriteria": [
+      {
+        "milestoneState":         "Active",
+        "milestoneAgreementType": "Warning",
+        "filterType":             "RuleFilter",
+        "filterItems": [
+          { "table": "Incident", "column": "Status", "operator": "NotEqual", "order": 1, "value": "Closed" }
+        ]
+      }
+    ]
+  }
+})
+```
+
+`milestoneCriteria` is mandatory. Success: `body.id` is the new Milestone Id.
+
+---
+
+## Create Entitlement (standard sObject)
+
+Entitlement is NOT part of the `/connect/sla-management/` surface — create it via the sObject
+endpoint.
+
+```json
+mcp__headless-360__dispatch({
+  "url":    "/services/data/v67.0/sobjects/Entitlement",
+  "method": "POST",
+  "body": {
+    "Name":            "Incident SLA Entitlement",
+    "AccountId":       "<AccountId>",
+    "SlaProcessId":    "<slaId>",
+    "BusinessHoursId": "<BusinessHoursId>",
+    "StartDate":       "<YYYY-MM-DD>",
+    "EndDate":         "<YYYY-MM-DD + 1 year>"
+  }
+})
+```
+
+`Entitlement.Status` is date-computed: `StartDate` in the future → `Inactive`; `StartDate` ≤ today
+AND `EndDate` ≥ today → `Active`. For immediate SLA engagement, backdate `StartDate` to yesterday.
+Success: `body.id`.
+
+---
+
+## Verify SLA engagement
+
+Create a test Incident:
+
+```json
+mcp__headless-360__dispatch({
+  "url":    "/services/data/v67.0/sobjects/Incident",
+  "method": "POST",
+  "body":   { "Subject": "SLA test incident", "EntitlementId": "<EntitlementId>" }
+})
+```
+
+Then confirm the Incident stamped an SLA start and an EntityMilestone:
+
+```json
+mcp__headless-360__dispatch_readonly({
+  "url":    "/services/data/v67.0/query",
+  "method": "GET",
+  "query_params": { "q": "SELECT Id, IncidentNumber, Subject, Status, SlaStartDate FROM Incident WHERE Id = '<incidentId>'" }
+})
+```
+
+```json
+mcp__headless-360__dispatch_readonly({
+  "url":    "/services/data/v67.0/query",
+  "method": "GET",
+  "query_params": { "q": "SELECT Id, MilestoneType.Name, TargetDate, IsCompleted, IsViolated FROM EntityMilestone WHERE ParentEntityId = '<incidentId>'" }
+})
+```
+
+`SlaStartDate` populated + at least one `EntityMilestone` row with a `TargetDate` = SLA engaged.
+`TargetDate` should equal `SlaStartDate + timeTrigger minutes` (business-hours-adjusted).
+
+---
+
+## Gotchas
+
+| Issue | Detail |
+|-------|--------|
+| `dispatch` shape is raw HTTP | Pass `{url, method, body?, query_params?}` — NOT `{operation_id, arguments}`. |
+| Response wrapper | Connect/`/sobjects`/`/query` are singly wrapped — read `body`. Aura `/headless/invoke/…` routes (not used here) are doubly wrapped. |
+| Corpus vs. registry drift | `discover` may not rank the SLA POST routes at the top — the routes are still known-good; `describe` + `dispatch` on the canonical path works either way. |
+| SLA Policy create response is null | `POST /sla-policies` echoes most fields as `null` — always verify via SOQL on `SlaProcess`. |
+| Milestone criteria mandatory | Omitting `milestoneCriteria` returns `400: Criteria details cannot be empty`. |
+| Formula filter → 500 | `filterType: "Formula"` triggers an internal server error. Use `filterType: "RuleFilter"` with concrete `filterItems[]`. |
+| Filter operator enum | Use `Equals` (not `Equal`), `NotEqual` (not `NotEquals`/`NotEqualTo`/`!=`). Wrong shape → `POST_BODY_PARSE_ERROR: Invalid value for Filter Operation Enum`. |
+| `slaProcessId` rejected in body | The server returns `JSON_PARSER_ERROR: Unrecognized field "slaProcessId"` — the id is in the path only. |
+| Entitlement status date-computed | Future `StartDate` → `Inactive`. Backdate `StartDate` to yesterday for immediate SLA engagement in testing. |
+| Entitlement is standard sObject | Create via `POST /sobjects/Entitlement`, not the Connect surface. |