@salesforce/afv-skills 1.37.0 → 1.38.0

package/skills/service-itsm-agentic-setup-cmdb-bundle-deploy/references/mcp-invocation.md

@@ -0,0 +1,204 @@
+# MCP Invocation Reference — CMDB Bundle Deploy (Layer 4)
+
+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)` — pull the schema and canonical route for one operation
+- `mcp__headless-360__dispatch_readonly({url, method, queryParams?, body?})` — GET / read-only HTTP
+- `mcp__headless-360__dispatch({url, method, body?, queryParams?})` — 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 `queryParams` (camelCase — the
+tool rejects `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.
+
+**A `discover` miss does NOT mean the route is absent.** The `/connect/cmdb/...` routes this skill
+uses are documented core Connect APIs but are not always ranked first (or indexed) in the discovery
+corpus — `describe` on the canonical operation still returns the schema, and `dispatch*` on the exact
+path still works. Only if the GET/POST itself returns 404 should you treat the route as unavailable on
+this org.
+
+## Response envelope
+
+The CMDB Connect API, `/sobjects/…` REST endpoints, and `/query` are **standard REST** — the
+`dispatch*` tool returns the REST response singly wrapped:
+
+```json
+{ "status_code": 200, "body": { "success": true, "latestVersion": "v3.0", "installedVersion": "" } }
+```
+
+Read fields from `body`. (Only `/headless/invoke/…` Aura-controller routes are doubly wrapped as
+`body.body`; this skill uses none.) Status codes: `200/201` success; `400` bundle/version doesn't exist
+(or bad body); `403 FUNCTIONALITY_NOT_ENABLED` the CMDB gate is closed — either the org feature is not
+enabled, or the running user has no CMDB access (Step 1 disambiguates); `404` the endpoint/impl is not
+present on this org; `500` a downstream dependency issue.
+
+All three CMDB endpoints below are implemented core Connect APIs in module
+`shared-service-itom-connect-api` and are gated by `orgHasCMDBEnabled`. Minimum API version is
+**67.0** — `headless-360` currently only routes `v67.0+`.
+
+---
+
+## Discovery — run first
+
+```text
+mcp__headless-360__discover(query="cmdb bundle installation")
+```
+
+`discover` returns matching operation ids. Pipe the install operation id into `describe` to pull its
+input schema and canonical HTTP route:
+
+```text
+mcp__headless-360__describe(id="<bundleInstallation operation id from discover>")
+```
+
+If `discover` returns nothing at all after rewording the query, the org's `headless-360` corpus does
+not index this surface — dispatch the exact `/connect/cmdb/...` paths below directly; only treat the
+route as unavailable if the dispatch itself 404s.
+
+---
+
+## Step 1 — Enablement gate + catalog: bundleListView (read)
+
+```json
+mcp__headless-360__dispatch_readonly({
+  "url":    "/services/data/v67.0/connect/cmdb/bundleListView",
+  "method": "GET"
+})
+```
+
+- `200` → CMDB is enabled and the running user has access. `body` includes availability + installation
+  status per bundle.
+- `403 FUNCTIONALITY_NOT_ENABLED` → ambiguous; this read enforces both the org gate and the user's own
+  CMDB access. Disambiguate via the feature status:
+  ```json
+  mcp__headless-360__dispatch_readonly({
+    "url":    "/services/data/v67.0/connect/setup/discovery/feature/service-cloud-itsm-cmdb-integration/status",
+    "method": "GET"
+  })
+  ```
+  - `status != ENABLED` → CMDB feature not enabled. STOP; route to
+    `service-itsm-agentic-setup-cmdb-configure`.
+  - `status == ENABLED` → feature is on; the user lacks CMDB permission sets. STOP; route to
+    `service-itsm-agentic-setup-cmdb-access-assign` (read set at minimum; Type Manager for bundle
+    management), then retry.
+
+Identify the base bundle (CMDB Foundation) and note its `currentInstalledVersion`.
+
+---
+
+## Step 2 — Resolve the exact base version: bundles/details (read)
+
+```json
+mcp__headless-360__dispatch_readonly({
+  "url":    "/services/data/v67.0/connect/cmdb/bundles/details",
+  "method": "GET",
+  "queryParams": { "bundleIdentifier": "base" }
+})
+```
+
+Response fields include: `name`, `latestVersion`, `installedVersion`, `installedDate`,
+`publishedDate`, `dependsOnBaseVersion`, `bundleDescription`, `listOfVersions`.
+
+- **Pass the version string verbatim.** `bundles/details` reports the version exactly as the registry
+  stores it (e.g. `latestVersion: "v3.0"`). The `bundleInstallation` endpoint matches the requested
+  version by **exact string equality** against that registry — it does no normalization — so send the
+  catalog's `latestVersion` through unchanged. Do NOT strip, add, or reformat any characters (including
+  a leading `v`); altering the string makes it fail the equality check.
+- **You may only install the latest version.** The endpoint rejects any non-latest version
+  (`"Target version <x> is not the latest available version"`) and cannot install or roll back to an
+  older version — always resolve `latestVersion` and install exactly that.
+- If `installedVersion == latestVersion`, the base bundle is already up to date — stop.
+
+`versionNumber` is an optional query param to inspect a specific version; omit it to get the latest.
+
+> **If `bundles/details` returns `403 FUNCTIONALITY_NOT_ENABLED`** while `bundleListView` (Step 1)
+> returned `200`: the org gate is fine, but the running user lacks the bundle-management permission.
+> `bundles/details` requires the **`ItSrvcCnfgItmTypManagerPermissionSet`** (Type Manager) set — the
+> read / owner / type-read sets are not sufficient. Have Type Manager assigned via
+> `service-itsm-agentic-setup-cmdb-access-assign`, then retry. As a fallback, `bundleListView` already
+> returns the base bundle's `currentInstalledVersion` and `latestVersion`, so resolve the version from
+> Step 1's response if Type Manager cannot be assigned.
+
+---
+
+## Step 3 — Install the base bundle: bundleInstallation (write)
+
+Confirm the input schema first:
+
+```text
+mcp__headless-360__discover(query="cmdb bundle installation")
+mcp__headless-360__describe(id="<bundleInstallation operation id>")
+```
+
+Then install:
+
+```json
+mcp__headless-360__dispatch({
+  "url":    "/services/data/v67.0/connect/cmdb/bundleInstallation",
+  "method": "POST",
+  "body":   { "bundleIdentifier": "base", "version": "<Step 2's latestVersion, verbatim>" }
+})
+```
+
+Both `bundleIdentifier` and `version` are **required**. Response:
+`{ "success": true, "message": "...", "error": null }`. `success: true` means installation was
+**initiated** (may complete asynchronously).
+
+---
+
+## Step 4 — Verify (read)
+
+```json
+mcp__headless-360__dispatch_readonly({
+  "url":    "/services/data/v67.0/connect/cmdb/bundles/details",
+  "method": "GET",
+  "queryParams": { "bundleIdentifier": "base" }
+})
+```
+
+Confirm `installedVersion` equals the version you installed. If installation is async and it has not
+updated yet, report in-progress and tell the user to re-check.
+
+---
+
+## Idempotency
+
+- All reads (Steps 1, 2, 4) are safe to repeat.
+- Before installing, compare `installedVersion` to `latestVersion` — skip if already up to date.
+- Re-installing the same version is unnecessary; always resolve + compare first.
+
+---
+
+## Dead ends — do NOT do these
+
+- **Do NOT:** hard-code, guess, or reformat a version string — always read `latestVersion` from the
+  catalog and post it verbatim (including any leading `v`, e.g. `"v3.0"`). The endpoint matches by
+  exact string equality against the registry; stripping or altering the string breaks the match.
+- **Do NOT:** attempt to install a non-latest version — the endpoint only accepts the latest
+  (`"Target version <x> is not the latest available version"`) and cannot roll back.
+- **Do NOT:** install an optional add-on bundle — this skill is scoped to `base` (CMDB Foundation)
+  only.
+- **Do NOT:** treat a `403` on `bundleListView` as "feature off" without checking the feature status —
+  it may instead be the running user lacking CMDB access.
+- **Do NOT:** report the install as done on `success: true` alone — installation can be async; verify
+  via `bundles/details`.
+- **Do NOT:** pass `dispatch` the `{operation_id, arguments}` shape — it takes raw HTTP
+  (`{url, method, body?, queryParams?}`).
+
+---
+
+## Error table
+
+| Status / message | Meaning | Resolution |
+|------------------|---------|------------|
+| `403 FUNCTIONALITY_NOT_ENABLED` on `bundleListView`, feature `status != ENABLED` | CMDB feature not enabled for the org | Enable the CMDB feature first (`service-itsm-agentic-setup-cmdb-configure`), then return |
+| `403 FUNCTIONALITY_NOT_ENABLED` on `bundleListView`, feature `status == ENABLED` | Feature on; running user lacks CMDB access | Grant the user CMDB access (`service-itsm-agentic-setup-cmdb-access-assign`), then retry — do NOT run configure |
+| `403 FUNCTIONALITY_NOT_ENABLED` on `bundles/details`, `bundleListView` was `200` | User lacks Type Manager (`ItSrvcCnfgItmTypManagerPermissionSet`); org gate is fine | Assign Type Manager via the access-assign skill, or read the version from `bundleListView` instead |
+| `400` bundle/version doesn't exist on install | Wrong `version` string | Re-read `bundles/details`; post `latestVersion` verbatim (do not strip or reformat) |
+| `Target version <x> is not the latest available version` on install | Attempted to install a non-latest version | Re-read `bundles/details`, resolve `latestVersion`, and install exactly that — older versions/rollback are not supported |
+| `success: true`, version unchanged | Async install in progress | Re-check `bundles/details` shortly |
+| `500` on install (verbatim latest version) | Downstream/backend issue on the org, not a bad request | Retry; if persistent, capture the support `ErrorId` and escalate to Salesforce support |
+| `dispatch*` auth error | The headless-360 MCP session isn't authenticated or the token expired | Re-authenticate the headless-360 MCP connection; confirm the session points at the intended org |

package/skills/service-itsm-agentic-setup-cmdb-configure/SKILL.md

@@ -0,0 +1,259 @@
+---
+name: service-itsm-agentic-setup-cmdb-configure
+description: "Enable the CMDB (Configuration Management Database) feature in Service Cloud ITSM against a production or sandbox org: verify the CMDB org SKU, provision the ITOM tenant, and enable the service-cloud-itsm-cmdb-integration feature that lifts the CMDB access gate. Use when the user asks to enable CMDB, turn on the Configuration Management Database, provision the ITOM tenant, enable the CMDB feature, or fix a CMDB 403 FUNCTIONALITY_NOT_ENABLED error. Triggers on: enable CMDB feature, provision ITOM tenant, turn on CMDB, CMDB not enabled, CMDB 403 error, service-cloud-itsm-cmdb-integration. DO NOT TRIGGER when: the user only wants to assign CMDB permission sets to users, only install a CMDB content bundle, or work with CMDB records directly."
+metadata:
+  version: "1.0"
+  minApiVersion: "67.0"
+  relatedSkills:
+    - "service-itsm-agentic-setup-cmdb-access-assign"
+    - "service-itsm-agentic-setup-cmdb-bundle-deploy"
+  mcpTools:
+    headless-360:
+      tools: ["describe", "discover", "dispatch", "dispatch_readonly"]
+      semver: ">=1.0.0"
+  accessCheck:
+    - type: "orgPerm"
+      value: "ITSrvcsCnfgMgmnt"
+allowed-tools: |
+  Read AskUserQuestion
+  mcp__headless-360__discover
+  mcp__headless-360__describe
+  mcp__headless-360__dispatch
+  mcp__headless-360__dispatch_readonly
+---
+
+# Enable the CMDB Feature (Service Cloud ITSM)
+
+Takes an org from "CMDB off" to "CMDB feature enabled" by walking the first three layers of the
+CMDB prerequisite stack in order. Every call runs through the **Salesforce-hosted Headless-360 MCP
+server** (server key `headless-360`) via its four meta-tools (`discover`, `describe`,
+`dispatch_readonly`, `dispatch`). The org is derived from the OAuth JWT bound to the current MCP
+session — the skill never handles an org id, alias, or credentials — so this works identically
+against **production** and sandbox with no per-user MCP install.
+
+This skill covers **Layers 0–2**. User access (Layer 3) and content bundles (Layer 4) are separate
+skills — see the end of this file.
+
+## The gate this skill lifts
+
+Every CMDB Connect API checks:
+
+```text
+orgHasCMDBEnabled = orgHasCMDBPermission (org perm ITSrvcsCnfgMgmnt)  &&  OrgPreferences.CMDBEnabled
+```
+
+Until `orgHasCMDBEnabled` is true, CMDB APIs return `403 FUNCTIONALITY_NOT_ENABLED`. `CMDBEnabled`
+is NOT a directly settable preference — it is flipped as a side effect of enabling the feature in
+Layer 2. This skill's job is to make that gate return true.
+
+> **Necessary but not always sufficient for a given user.** Lifting this org gate does not by itself
+> let a *specific* user read CMDB data. Some CMDB reads (e.g. `bundleListView`) also enforce
+> **user-level** CMDB access and return the same `403 FUNCTIONALITY_NOT_ENABLED` ("not enabled for
+> this user") when the running user holds no CMDB permission sets — even though the feature is
+> correctly ENABLED. That is Layer 3 (`service-itsm-agentic-setup-cmdb-access-assign`), not a failure
+> of this skill. Confirm this skill's success via the feature `status == ENABLED`, never via a CMDB
+> data read.
+
+## Scope
+
+- **In scope**: verifying the CMDB org permission (Layer 0), triggering + polling ITOM tenant
+  provisioning (Layer 1), pre-checking + enabling + verifying the CMDB feature (Layer 2).
+- **Out of scope**: permission-set assignment (Layer 3 — `service-itsm-agentic-setup-cmdb-access-assign`),
+  bundle installation (Layer 4 — `service-itsm-agentic-setup-cmdb-bundle-deploy`), CMDB record CRUD,
+  Discovery / Service Graph Connector, identification rules.
+
+## Mechanism
+
+All operations dispatch through **headless-360** MCP tools. Reads go through
+`mcp__headless-360__dispatch_readonly`, writes through `mcp__headless-360__dispatch` — both take raw
+HTTP: `{"url": "<path>", "method": "GET|POST", "body"?: {...}, "queryParams"?: {...}}` — **not**
+`{operation_id, arguments}`. See `references/mcp-invocation.md` for the exact `url` / `method` /
+`body` of every call. The four tools:
+
+- `mcp__headless-360__discover` — semantic search over the indexed operation catalog. The Setup/Connect
+  routes this skill uses are not always ranked first (or indexed), so a miss does **not** mean the
+  route is absent — dispatch the exact path directly (see `references/mcp-invocation.md`).
+- `mcp__headless-360__describe` — pull the full input schema and canonical route before any POST.
+- `mcp__headless-360__dispatch_readonly` — the dispatcher for every read (GET).
+- `mcp__headless-360__dispatch` — the dispatcher for every write (POST/PATCH).
+
+The skill never handles credentials — the org is bound to the current OAuth session. If a `dispatch*`
+call returns an auth error, tell the user to re-authenticate the headless-360 MCP connection (and
+confirm the session points at the intended org), then stop.
+
+---
+
+## Clarifying questions
+
+Ask only what you cannot infer from conversation:
+
+- **Which org?** Confirm the target org and state plainly that **this org will be modified**
+  (tenant provisioning and feature enable are writes). For production, get explicit confirmation.
+
+Do not re-ask for anything the user already provided; pre-populate and note "(from conversation)".
+
+---
+
+## Workflow
+
+All steps are sequential and gated — **do not advance past a failed layer.** Always read before you
+write: run the read-only check before every mutation.
+
+### Layer 0 — Verify the CMDB org SKU (read-only, hard gate)
+
+CMDB requires the org permission `ITSrvcsCnfgMgmnt`, granted only by edition / license / org
+template. **No API can set it.** The most reliable, universally-available way to verify the org
+carries the CMDB SKU is to probe for the CMDB permission-set license — it exists **only** in orgs
+provisioned with that license:
+
+```text
+dispatch_readonly({ "url": "/services/data/v63.0/query", "method": "GET", "queryParams": { "q": "SELECT Id FROM PermissionSetLicense WHERE DeveloperName = 'ItSrvcCnfgItmReadPsl'" } })
+→ totalSize == 1  (licensed)   |   totalSize == 0  (not licensed)
+```
+
+- **totalSize == 1** → org is CMDB-licensed; proceed to Layer 1.
+- **totalSize == 0** → STOP. Tell the user in plain language (no developer names or API references
+  in the message they see):
+  > This org isn't licensed for CMDB. CMDB availability is determined by the org's edition or
+  > license and can't be turned on through setup — it has to be included when the org is
+  > provisioned. Please have the org set up with CMDB (or use one that already has it), then run
+  > this again.
+
+The core Connect API `GET /services/data/v63.0/setup/org/permissions/ITSrvcsCnfgMgmnt`
+(`{"isPermissionEnabled": true|false}`) is an alternative, but it **404s on some org types
+(including orgfarm test orgs)**, so prefer the PSL probe above. See
+`references/mcp-invocation.md` for the details. If no probe resolves, report that the org perm could
+not be verified and ask the user to confirm the org has CMDB licensed before continuing.
+
+### Layer 1 — Provision the ITOM tenant
+
+CMDB runs on an ITOM tenant that must reach status `PROVISIONED` (asynchronous).
+
+1. **Check current status** (read):
+   ```text
+   dispatch_readonly({ "url": "/services/data/v67.0/connect/tenantProvisioningStatus", "method": "GET" })
+   ```
+   - If `status` is already `PROVISIONED` → skip to Layer 2.
+2. **Trigger provisioning** (write) — only if not already provisioned/in-progress. Confirm with the
+   user first:
+   ```text
+   dispatch({ "url": "/services/data/v67.0/connect/tenantProvisioningStatus", "method": "POST" })
+   ```
+3. **Poll** the GET until `status == PROVISIONED`. This is async and can take several minutes. Poll
+   **every 30 seconds for up to 10 minutes** (≈20 attempts). Tell the user provisioning is in
+   progress on each poll. Exit the loop as soon as:
+   - `status == PROVISIONED` → success, advance to Layer 2.
+   - `status == FAILED` → stop immediately. Do NOT retry via the API — surface the failure to the
+     user in plain language with three things:
+     1. **The failure reason, decoded to human-readable text.** Read it from the response body (the
+        FAILED payload carries a detail field such as `error` / `failureReason` / `message` —
+        unescape any HTML entities like `&lt;`/`&gt;` and strip markup). If the response carries no
+        detail, say the tenant provisioning failed without a returned reason.
+     2. **A link to the org's tenant provisioning Setup page**, built from the target org's instance
+        URL: `<org instance URL>/lightning/setup/CMDBProvisionalSettings/home`.
+     3. **Ask the user to open that page and try provisioning manually**, then re-run this skill once
+        the tenant shows `PROVISIONED`. Only if the manual retry also fails does it need Salesforce
+        support.
+   - the 10-minute window elapses → stop, report the last-seen status, and let the user decide
+     whether to keep waiting (re-run) or investigate. Never spin past the 10-minute bound.
+
+### Layer 2 — Enable the CMDB feature (this lifts the 403 gate)
+
+The feature api name is `service-cloud-itsm-cmdb-integration`.
+
+1. **Pre-check status** (read):
+   ```text
+   dispatch_readonly({ "url": "/services/data/v67.0/connect/setup/discovery/feature/service-cloud-itsm-cmdb-integration/status", "method": "GET" })
+   ```
+   - `status == ENABLED` → already done; skip to verification.
+   - `status == NOT_ENABLED` with `enableBlockedReasons: []` → clear to enable.
+   - `enableBlockedReasons` non-empty → STOP and relay each reason to the user in plain language
+     (these are prerequisites the org still needs — do not attempt the enable).
+2. **Confirm with the user**, then **enable** (write):
+   ```text
+   dispatch({ "url": "/services/data/v67.0/connect/setup/discovery/feature/service-cloud-itsm-cmdb-integration/enable", "method": "POST", "body": {} })
+   → {"success": true}
+   ```
+3. **Verify** (read) — do NOT trust the POST response alone:
+   ```text
+   dispatch_readonly({ "url": "/services/data/v67.0/connect/setup/discovery/feature/service-cloud-itsm-cmdb-integration/status", "method": "GET" })
+   → expect status == ENABLED
+   ```
+   **`status == ENABLED` is the definitive — and only — confirmation this skill needs.** Layer 2
+   succeeds or fails on this check alone; it does **not** perform any CMDB data read to confirm the
+   gate. A CMDB data read (e.g. `bundleListView`) also depends on the *running user's* own CMDB
+   access, so it cannot cleanly confirm the org-level enable — see the note under "The gate this
+   skill lifts". Once the feature shows `ENABLED`, Layer 2 is done.
+
+---
+
+## Rules / Constraints
+
+| Constraint | Rationale |
+|-----------|-----------|
+| Verify Layer 0 before anything else | If `ITSrvcsCnfgMgmnt` is off, no later step can succeed — fail fast with a clear message |
+| Never try to set `ITSrvcsCnfgMgmnt` via API | There is no setter; it is license/edition/template only |
+| Never set `CMDBEnabled` directly (e.g. via `updateDefaultOrgPrefs`) | It is not in any settable-pref allowlist; the server rejects it with 500. It flips only as a side effect of the Layer 2 feature enable |
+| Read before every write; verify after every write | Tenant + feature are async/stateful; the POST response can lag the real state |
+| Confirm the target org and each write with the user | These are real, hard-to-reverse changes on a live org |
+| Do not advance past a failed or blocked layer | Later layers depend on earlier ones and will 403 |
+| Poll tenant provisioning every 30s for up to 10 min (≈20 attempts) | It is async; never spin past the 10-min bound — exit on PROVISIONED/FAILED, else report status and let the user decide |
+| On `FAILED`, never retry via API — decode the reason, give the Setup URL, ask for a manual retry | The API trigger has already failed; the user can retry from the CMDB provisioning Setup page, which surfaces the real error and any manual remediation |
+| Never expose internal jargon to the user | Keep record IDs, org IDs, HTTP status codes (403/500/…), API error codes (`FUNCTIONALITY_NOT_ENABLED`, …), endpoint names (`bundleListView`, `tenantProvisioningStatus`), developer names (`ITSrvcsCnfgMgmnt`, `CMDBEnabled`), and tooling internals (`dispatch`, `headless-360`) out of user-facing output. Translate to plain language; use human-readable names and statuses |
+
+---
+
+## Verification checklist
+
+- [ ] Layer 0: `ITSrvcsCnfgMgmnt` confirmed `true` (or stopped with a clear license message)?
+- [ ] Layer 1: tenant `status == PROVISIONED`?
+- [ ] Layer 2: pre-check showed `enableBlockedReasons: []` before enabling?
+- [ ] Layer 2: enable returned `success: true`?
+- [ ] Layer 2: verification GET shows `status == ENABLED`? **(this is the sole success criterion — no CMDB data read is used to confirm)**
+- [ ] Confirmed the target org and each write with the user first?
+
+---
+
+## Output expectations
+
+```text
+CMDB Feature Enable — Complete (via service-itsm-agentic-setup-cmdb-configure)
+
+Target org: <org>
+
+  CMDB license .................. Present
+  ITOM tenant ................... Provisioned
+  CMDB feature .................. Enabled
+
+CMDB is now enabled on this org. Next steps:
+  • Assign user access  → service-itsm-agentic-setup-cmdb-access-assign
+  • Install base bundle  → service-itsm-agentic-setup-cmdb-bundle-deploy
+```
+
+Keep internal jargon out of user-facing output (no record IDs, HTTP status codes, error codes,
+endpoint or developer names). If any step fails, stop and tell the user — in plain language — which
+part of setup didn't succeed and what it means for them, then point to the relevant fix. Translate
+any raw error (e.g. a 403 or `FUNCTIONALITY_NOT_ENABLED`) into what it means ("CMDB isn't enabled
+yet"), rather than echoing the code.
+
+---
+
+## Common failures (surface these in plain language)
+
+| Symptom | Likely cause | What to tell the user |
+|---------|--------------|-----------------------|
+| Layer 0 returns `false` | Org lacks the CMDB SKU | License/edition prerequisite — no API can grant it; provision the org with CMDB |
+| `403 FUNCTIONALITY_NOT_ENABLED` on CMDB reads **while feature `status != ENABLED`** | Feature not yet enabled (Layer 2 incomplete) | Finish Layer 2; the gate lifts only after the feature is ENABLED |
+| `403 FUNCTIONALITY_NOT_ENABLED` on `bundleListView` **while feature `status == ENABLED`** | Feature IS enabled; the running user lacks CMDB permission sets (`bundleListView` also enforces user-level access) | Not a Layer 2 failure — this is Layer 3; run `service-itsm-agentic-setup-cmdb-access-assign` to grant the user CMDB access |
+| Feature enable blocked (`enableBlockedReasons` non-empty) | Missing dependency the org still needs | Relay each reason; resolve those first, then retry |
+| Tenant stuck `NOT_PROVISIONED` / long-running | Provisioning is async | It can take minutes; keep polling or retry the trigger |
+| Tenant `FAILED` | Provisioning job failed Salesforce-side | Share the decoded failure reason + the org's `/lightning/setup/CMDBProvisionalSettings/home` link and ask the user to retry provisioning manually there; escalate to Salesforce support only if the manual retry also fails |
+| `dispatch*` auth error | headless-360 MCP session not authenticated / token expired | Re-authenticate the headless-360 MCP connection and confirm the session points at the intended org |
+
+---
+
+## Reference file index
+
+| File | When to read |
+|------|--------------|
+| `references/mcp-invocation.md` | Exact `dispatch*` url/method/body for every Layer 0–2 call, response envelopes, and error table |

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

@@ -0,0 +1,188 @@
+# MCP Invocation Reference — CMDB Feature Enable (Layers 0–2)
+
+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)` — pull the schema and canonical route for one operation
+- `mcp__headless-360__dispatch_readonly({url, method, queryParams?, body?})` — GET / read-only HTTP
+- `mcp__headless-360__dispatch({url, method, body?, queryParams?})` — 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 `queryParams` (camelCase — the
+tool rejects `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.
+
+**A `discover` miss does NOT mean the route is absent.** The Setup / Connect API routes this skill
+uses (`/connect/setup/discovery/feature/.../status`, `/connect/tenantProvisioningStatus`, the
+`/setup/org/permissions/...` and PSL-query paths) are documented core Connect APIs but are **not
+always ranked first (or indexed)** in the discovery corpus — `discover` may return nothing, or only
+tangential specs, for them. That is not a signal they don't exist. Dispatch on the exact path
+directly; only if the GET/POST itself returns 404 should you treat the route as unavailable on this
+org.
+
+## Response envelope
+
+The `dispatch*` tool returns the HTTP status plus the parsed body, e.g.:
+
+```json
+{ "status_code": 200, "body": { "isPermissionEnabled": true } }
+```
+
+Read the relevant field from `body`. Status codes: `200/201` success; `400` bad body (re-check
+schema via `describe`); `403 FUNCTIONALITY_NOT_ENABLED` the CMDB gate is still closed (finish
+Layer 2); `404` the endpoint/impl is not present on this org; `500` a downstream dependency issue.
+
+---
+
+## Layer 0 — Verify the CMDB org SKU (read-only, hard gate)
+
+**Preferred: probe for the CMDB permission-set license (works on every org type, including
+orgfarm/sandbox).** The PSL `ItSrvcCnfgItmReadPsl` exists in an org **only if that org carries the
+CMDB SKU** — it is provisioned by the same license/edition that grants `ITSrvcsCnfgMgmnt`. Querying
+for it is a reliable, universally-available Layer 0 signal (and it is the exact check the
+`service-itsm-agentic-setup-cmdb-access-assign` skill already relies on):
+
+```text
+dispatch_readonly({
+  "url":         "/services/data/v63.0/query",
+  "method":      "GET",
+  "queryParams": { "q": "SELECT Id, DeveloperName, MasterLabel FROM PermissionSetLicense WHERE DeveloperName = 'ItSrvcCnfgItmReadPsl'" }
+})
+```
+
+- `totalSize == 1` → org is CMDB-licensed; proceed to Layer 1.
+- `totalSize == 0` → STOP. This is a license/edition prerequisite. No API can grant the CMDB SKU.
+
+**Fallback: the core org-permission Connect API** (only where it is present — it **404s on some
+org types, including orgfarm test orgs**, so it is not the primary check):
+
+```text
+dispatch_readonly({
+  "url":    "/services/data/v63.0/setup/org/permissions/ITSrvcsCnfgMgmnt",
+  "method": "GET"
+})
+```
+
+Response: `{"isPermissionEnabled": true|false}`. `true` → Layer 1; `false`/404 → rely on the preferred
+PSL probe above. If no probe resolves, report that the org perm could not be verified and ask the
+user to confirm CMDB is licensed before proceeding.
+
+> A useful cross-check regardless of which probe you use: a `GET` on the Layer 2 feature-status
+> endpoint that returns `200` (rather than `403 FUNCTIONALITY_NOT_ENABLED`) is itself evidence the
+> org carries the CMDB surface.
+
+---
+
+## Layer 1 — Provision the ITOM tenant
+
+### Check current provisioning status (read)
+
+```text
+dispatch_readonly({ "url": "/services/data/v67.0/connect/tenantProvisioningStatus", "method": "GET" })
+```
+
+Response includes `status` (e.g. `NOT_PROVISIONED`, `IN_PROGRESS`, `PROVISIONED`, `FAILED`),
+`triggeredAt`, `callbackReceivedAt`. If `status == PROVISIONED`, skip to Layer 2.
+
+### Trigger provisioning (write — confirm with the user first)
+
+```text
+dispatch({ "url": "/services/data/v67.0/connect/tenantProvisioningStatus", "method": "POST" })
+```
+
+No request body. Response echoes the status object. Provisioning is **asynchronous** — the callback
+arrives later.
+
+### Poll until PROVISIONED
+
+Re-issue the GET above **every 30 seconds for up to 10 minutes** (≈20 attempts). Exit the loop on:
+
+- `status == PROVISIONED` → success; advance to Layer 2.
+- `status == FAILED` → stop. Do NOT retry via the API. Surface to the user, in plain language:
+  1. **The decoded failure reason** — read the detail field from the FAILED response body (e.g.
+     `error` / `failureReason` / `message`), unescape HTML entities (`&lt;` → `<`, `&gt;` → `>`,
+     `&quot;` → `"`, `&amp;` → `&`) and strip any `<a>`/markup so the text is readable. If no detail
+     is present, say the tenant provisioning failed without a returned reason.
+  2. **The org's tenant provisioning Setup page URL**: `<org instance URL>/lightning/setup/CMDBProvisionalSettings/home`
+     (this is the same page the Layer 2 `enableBlockedReasons` `CMDB_NOT_PROVISIONED` message links to).
+  3. **Ask the user to provision manually from that page**, then re-run this skill once the tenant
+     reads `PROVISIONED`. Escalate to Salesforce support only if the manual retry also fails.
+- 10-minute window elapsed → stop, report the last-seen status, let the user decide whether to
+  keep waiting or investigate.
+
+Never spin past the 10-minute bound. Report progress to the user on each poll.
+
+---
+
+## Layer 2 — Enable the CMDB feature
+
+Feature api name: `service-cloud-itsm-cmdb-integration`.
+
+### Pre-check feature status (read)
+
+```text
+dispatch_readonly({ "url": "/services/data/v67.0/connect/setup/discovery/feature/service-cloud-itsm-cmdb-integration/status", "method": "GET" })
+```
+
+Response: `{ apiName, status, enableBlockedReasons: [...], disableBlockedReasons: [...],
+dependencyStatuses: [...], blockedByApexLock }`.
+
+- `status == ENABLED` → already enabled; skip to verify.
+- `status == NOT_ENABLED` and `enableBlockedReasons` is empty → clear to enable.
+- `enableBlockedReasons` non-empty → STOP; relay each reason. Do not attempt the enable.
+
+### Enable the feature (write — confirm with the user first)
+
+```text
+dispatch({ "url": "/services/data/v67.0/connect/setup/discovery/feature/service-cloud-itsm-cmdb-integration/enable", "method": "POST", "body": {} })
+```
+
+Response: `{"success": true}`. The optional query param `solutionApiName` is not needed — omit it.
+
+### Verify (read — do not trust the POST response alone)
+
+```text
+dispatch_readonly({ "url": "/services/data/v67.0/connect/setup/discovery/feature/service-cloud-itsm-cmdb-integration/status", "method": "GET" })
+```
+
+Expect `status == ENABLED`. This is the definitive — and only — confirmation the skill needs.
+Do NOT perform a CMDB data read (e.g. `bundleListView`) to confirm the gate: that read also
+enforces the *running user's* CMDB access, so it can 403 even when the feature is correctly
+ENABLED (that is Layer 3, `service-itsm-agentic-setup-cmdb-access-assign`, not a failure here).
+
+---
+
+## Idempotency
+
+- Layer 0 is read-only — safe to repeat.
+- Layer 1: if already `PROVISIONED`, do not re-trigger; the GET is safe to repeat.
+- Layer 2: if `status == ENABLED`, do not re-POST; enabling an already-enabled feature is
+  unnecessary. Always pre-check.
+
+---
+
+## Dead ends — do NOT do these
+
+- **Do NOT:** use `updateDefaultOrgPrefs` / `ItServiceSetupController` with pref `CMDBEnabled` —
+  rejected with `500 Unknown preference name`. `CMDBEnabled` is not a settable pref; it flips only
+  as a side effect of the Layer 2 feature enable.
+- **Do NOT:** treat `tenantProvisioningStatus` as the feature toggle — provisioning is necessary
+  infra (Layer 1) but does NOT set `CMDBEnabled`. An org can be `PROVISIONED` and still 403 until
+  Layer 2.
+- **Do NOT:** try to grant `ITSrvcsCnfgMgmnt` via any API — no setter exists.
+
+---
+
+## Error table
+
+| Status | Meaning | Resolution |
+|--------|---------|------------|
+| 403 `FUNCTIONALITY_NOT_ENABLED` | CMDB gate still closed | Finish Layer 2; verify `status == ENABLED` |
+| 404 on `/setup/org/permissions/...` | Endpoint not on this org | Rely on the preferred PSL-query probe (Layer 0) |
+| 404 on `/connect/...` CMDB paths | Impl/dispatcher not present on this org | Confirm the org type; CMDB core APIs require a real (non-scratch-stub) org |
+| 400 on feature enable | Wrong body/shape | Body is `{}`; re-confirm the path via `describe` |
+| Tenant `status == FAILED` | Provisioning job failed Salesforce-side | Do NOT retry via API. Decode the reason from the body, give the user `<org instance URL>/lightning/setup/CMDBProvisionalSettings/home`, and ask them to provision manually; support only if that also fails |
+| 500 | Downstream dependency missing | Retry; if persistent, needs Salesforce support |
+| Auth error | headless-360 MCP session not authenticated / token expired | Re-authenticate the headless-360 MCP connection; confirm the session points at the intended org |