@salesforce/afv-skills 1.37.0 → 1.38.0

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

@@ -0,0 +1,260 @@
+# MCP Invocation Reference — CMDB User Access (Layer 3)
+
+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 standard `/query` and `/sobjects/...`
+REST routes this skill uses 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 `/query` and `/sobjects/…` REST endpoints are **standard REST** — the `dispatch*` tool returns the
+REST response singly wrapped:
+
+```json
+{ "status_code": 200, "body": { "totalSize": 1, "records": [ { "Id": "0PS..." } ] } }
+```
+
+Read the relevant field from `body`. (Only `/headless/invoke/…` Aura-controller routes are doubly
+wrapped as `body.body`; this skill uses none.) Status codes: `200` read success; `201` record created;
+`400` bad body or a business-rule rejection — read `body[0].errorCode` (e.g. `DUPLICATE_VALUE`); `403
+FUNCTIONALITY_NOT_ENABLED` the CMDB gate is closed (the org feature is not enabled, or this user has
+no CMDB access yet); `404` the endpoint/impl is not present on this org; `500` a downstream dependency
+issue. Minimum API version is **67.0** — `headless-360` currently only routes `v67.0+`.
+
+---
+
+## Discovery — optional, for confirmation
+
+```text
+mcp__headless-360__discover(query="permission set assignment")
+```
+
+`discover` returns matching operation ids; pipe one into `describe` to pull its input schema and
+canonical route:
+
+```text
+mcp__headless-360__describe(id="<operation id from discover>")
+```
+
+The `/query` and `/sobjects/...` routes this skill uses are standard REST — if `discover` returns
+nothing, dispatch the exact paths below directly; only treat a route as unavailable if the dispatch
+itself 404s.
+
+---
+
+## The four CMDB permission sets
+
+| Role | PermissionSet `Name` | Backing PSL `DeveloperName` |
+|------|----------------------|-----------------------------|
+| Reader | `ItSrvcCnfgItmReadPermissionSet` | `ItSrvcCnfgItmReadPsl` |
+| Owner | `ItSrvcCnfgItmOwnerPermissionSet` | `ItSrvcCnfgItmOwnerPsl` |
+| Type Reader | `ItSrvcCnfgItmTypReadPermissionSet` | `ItSrvcCnfgItmTypReadPsl` |
+| Type Manager | `ItSrvcCnfgItmTypManagerPermissionSet` | `ItSrvcCnfgItmTypMgrPsl` |
+
+Resolve the permission set's `Id` and its `LicenseId` at runtime (Step 3) rather than hardcoding IDs —
+IDs differ per org.
+
+---
+
+## Step 1 — Confirm the org feature is enabled (read, prerequisite)
+
+```json
+mcp__headless-360__dispatch_readonly({
+  "url":    "/services/data/v67.0/connect/setup/discovery/feature/service-cloud-itsm-cmdb-integration/status",
+  "method": "GET"
+})
+```
+
+Response: `{ apiName, status, enableBlockedReasons, ... }`. Proceed only when `status == ENABLED`. A
+`403 FUNCTIONALITY_NOT_ENABLED` here means the org gate is not lifted — stop and route the user to the
+feature-enable skill. User-level access assignment has no effect until this is `ENABLED`.
+
+---
+
+## Step 2 — Resolve the target user (read)
+
+### Resolve "the current user" / "me" / "my own user" — use the API-root identity URL
+
+Do **NOT** use `USER_ID()` (Apex-only — the REST query API rejects it with `MALFORMED_QUERY`), and do
+**NOT** depend on `/chatter/users/me` or `/connect/user-profiles/me` (they return `403
+FUNCTIONALITY_NOT_ENABLED` on orgs where Chatter/Communities are off). The always-available path is the
+API root, whose `identity` field carries the running user's Id:
+
+```json
+mcp__headless-360__dispatch_readonly({
+  "url":    "/services/data/v67.0/",
+  "method": "GET"
+})
+```
+
+Response `body.identity` is a URL like
+`https://login.../id/<orgId>/005SB00000jbY2QYAU` — the **last path segment** is the current user Id
+(18 chars, starts with `005`). Use it directly as `AssigneeId`, or confirm it:
+
+```json
+mcp__headless-360__dispatch_readonly({
+  "url":    "/services/data/v67.0/query",
+  "method": "GET",
+  "queryParams": { "q": "SELECT Id, Username, Name, IsActive FROM User WHERE Id = '<userId>'" }
+})
+```
+
+### Resolve a named user (username / email supplied)
+
+```json
+mcp__headless-360__dispatch_readonly({
+  "url":    "/services/data/v67.0/query",
+  "method": "GET",
+  "queryParams": { "q": "SELECT Id, Username, Name, IsActive FROM User WHERE Username = '<username>'" }
+})
+```
+
+- `totalSize == 1` → capture `records[0].Id`.
+- `totalSize == 0` → no such user; ask the user to confirm the username.
+- `totalSize > 1` → ambiguous; list `Name` + `Username` and ask which one.
+
+Escape single quotes in any user-supplied value.
+
+---
+
+## Step 3 — Resolve each requested permission set (read)
+
+```json
+mcp__headless-360__dispatch_readonly({
+  "url":    "/services/data/v67.0/query",
+  "method": "GET",
+  "queryParams": { "q": "SELECT Id, Name, LicenseId FROM PermissionSet WHERE Name = 'ItSrvcCnfgItmReadPermissionSet'" }
+})
+```
+
+Capture `records[0].Id` (permission set) and `records[0].LicenseId` (the PSL to assign). Repeat per
+requested role, or use `Name IN (...)` to resolve several at once. `totalSize == 0` for a role means
+the org is not CMDB-licensed — stop and report.
+
+---
+
+## Step 4 — Check existing assignments (read — idempotency)
+
+```json
+mcp__headless-360__dispatch_readonly({
+  "url":    "/services/data/v67.0/query",
+  "method": "GET",
+  "queryParams": { "q": "SELECT Id FROM PermissionSetAssignment WHERE AssigneeId = '<userId>' AND PermissionSetId = '<psId>'" }
+})
+```
+
+```json
+mcp__headless-360__dispatch_readonly({
+  "url":    "/services/data/v67.0/query",
+  "method": "GET",
+  "queryParams": { "q": "SELECT Id FROM PermissionSetLicenseAssign WHERE AssigneeId = '<userId>' AND PermissionSetLicenseId = '<pslId>'" }
+})
+```
+
+`totalSize == 1` on both → that role is already assigned; skip its writes. Otherwise assign what is
+missing (PSL and/or permission set).
+
+---
+
+## Step 5 — Assign the license, then the permission set (write — confirm first)
+
+### Assign the permission-set license first
+
+```json
+mcp__headless-360__dispatch({
+  "url":    "/services/data/v67.0/sobjects/PermissionSetLicenseAssign",
+  "method": "POST",
+  "body":   { "AssigneeId": "<userId>", "PermissionSetLicenseId": "<pslId>" }
+})
+```
+
+### Then assign the permission set
+
+```json
+mcp__headless-360__dispatch({
+  "url":    "/services/data/v67.0/sobjects/PermissionSetAssignment",
+  "method": "POST",
+  "body":   { "AssigneeId": "<userId>", "PermissionSetId": "<psId>" }
+})
+```
+
+Response on success: `{ "id": "0Pa...", "success": true }` (`201`). On `400`, read
+`body[0].errorCode`:
+
+- `DUPLICATE_VALUE` → the user already has it; treat as already-assigned success.
+- a limit/seat error → the CMDB license has no free seats (see the seat query below); stop for that
+  role and report. Do not retry.
+
+---
+
+## Step 6 — Verify (read)
+
+Re-run the Step 4 queries. A role counts as assigned only when **both** the `PermissionSetAssignment`
+and the `PermissionSetLicenseAssign` return `totalSize == 1` for the user. Report per role.
+
+---
+
+## License-seat query (for seat-exhaustion errors)
+
+```json
+mcp__headless-360__dispatch_readonly({
+  "url":    "/services/data/v67.0/query",
+  "method": "GET",
+  "queryParams": { "q": "SELECT DeveloperName, TotalLicenses, UsedLicenses FROM PermissionSetLicense WHERE DeveloperName = 'ItSrvcCnfgItmReadPsl'" }
+})
+```
+
+`UsedLicenses == TotalLicenses` → no free seats; a seat must be released (or more licenses added)
+before the assignment can succeed.
+
+---
+
+## Idempotency
+
+- Every read (Steps 1–4, 6) is safe to repeat.
+- Assignment (Step 5) is per-user: if the user already holds the permission set / license, the POST
+  returns `400 DUPLICATE_VALUE` — treat as already-assigned, not a failure. Always run Step 4 first so
+  you only POST what is missing.
+
+---
+
+## Dead ends — do NOT do these
+
+- **Do NOT:** assign the permission set without its license — a license-backed permission set will not
+  take effect (or the assign is rejected) unless the user holds the backing PSL seat.
+- **Do NOT:** create or edit a permission set to grant CMDB access — the four standard CMDB permission
+  sets already exist in a licensed org; this skill only assigns them.
+- **Do NOT:** assign CMDB access to work around a closed org gate — if the feature status is not
+  `ENABLED`, user access is inert; enable the feature first (separate skill).
+- **Do NOT:** retry a POST that failed with a seat/limit error — the seat shortage is real; surface it.
+- **Do NOT:** pass `dispatch` the `{operation_id, arguments}` shape — it takes raw HTTP
+  (`{url, method, body?, queryParams?}`).
+
+---
+
+## Error table
+
+| Status / code | Meaning | Resolution |
+|---------------|---------|------------|
+| Feature `status != ENABLED` / `403` on the status read | Org-level CMDB gate not lifted | Enable the CMDB feature for the org first (feature-enable skill), then return |
+| `400 DUPLICATE_VALUE` on assign | User already has that access | Idempotent success — report the role as already assigned |
+| `400` seat/limit error on assign | CMDB permission-set license seats exhausted | Report used vs total seats; free a seat or add licenses, then retry |
+| `PermissionSet` query `totalSize == 0` | Org not CMDB-licensed / not set up | CMDB is not available on this org; confirm it is licensed and enabled |
+| `User` query `totalSize == 0` / `> 1` | User not found / ambiguous | Ask the user to confirm the username, or pick from the listed candidates |
+| `403 FUNCTIONALITY_NOT_ENABLED` on a bundle-management read (`bundles/details`, `bundleListView`) after assign | User lacks **Type Manager** — bundle operations require it, Reader/Owner/Type Reader do not clear it | Assign the **Type Manager** role (PS `ItSrvcCnfgItmTypManagerPermissionSet` + its own PSL `ItSrvcCnfgItmTypMgrPsl`), then re-verify via Step 6 |
+| `dispatch*` 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 |

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

@@ -0,0 +1,252 @@
+---
+name: service-itsm-agentic-setup-cmdb-bundle-deploy
+description: "Deploy (install) the CMDB Foundation base content bundle in Service Cloud ITSM against a production or sandbox org, after the CMDB feature is enabled. Use when the user asks to install the CMDB bundle, deploy CMDB Foundation, set up the CMDB base content, install CMDB out-of-the-box content, or finish CMDB setup with the base bundle. Triggers on: install CMDB bundle, deploy CMDB Foundation, CMDB base content, CMDB content bundle, bundleInstallation, finish CMDB setup. DO NOT TRIGGER when: the user wants to enable the CMDB feature for the org (that is the CMDB feature-enable skill), assign CMDB permission sets to a user (that is the CMDB access-assign skill), install optional non-base add-on bundles, deploy general (non-CMDB) metadata or packages, 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-configure"
+  mcpTools:
+    headless-360:
+      tools: ["describe", "discover", "dispatch", "dispatch_readonly"]
+      semver: ">=1.0.0"
+  accessCheck:
+    - type: "orgPerm"
+      value: "ITSrvcsCnfgMgmnt"
+    - type: "orgPref"
+      value: "CMDBEnabled"
+allowed-tools: |
+  Read AskUserQuestion
+  mcp__headless-360__discover
+  mcp__headless-360__describe
+  mcp__headless-360__dispatch
+  mcp__headless-360__dispatch_readonly
+---
+
+# Deploy the CMDB Foundation Bundle (Service Cloud ITSM)
+
+Installs the **CMDB Foundation (base)** content bundle — the out-of-the-box configuration-item types,
+schema, and content that make CMDB usable. This is **Layer 4**, the final layer of the CMDB setup
+stack, and it requires the CMDB feature to already be enabled (Layer 2). 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.
+
+## Scope
+
+- **In scope**: confirming CMDB is enabled, reading the live bundle catalog, resolving the exact
+  version of the base bundle, installing the **base** (`CMDB Foundation`) bundle, and verifying.
+- **Out of scope**: enabling the CMDB feature / provisioning the ITOM tenant (Layers 0–2 —
+  `service-itsm-agentic-setup-cmdb-configure`), assigning permission sets (Layer 3 —
+  `service-itsm-agentic-setup-cmdb-access-assign`), installing **optional add-on** bundles (e.g.
+  Component Identification Rules), CMDB record CRUD, or Discovery.
+
+This skill installs the **base bundle only**. Optional add-ons are intentionally out of scope.
+
+## Why order matters
+
+The bundle Connect APIs (`bundleListView`, `bundles/details`, `bundleInstallation`) are gated by
+`orgHasCMDBEnabled`. Until the CMDB feature is enabled they return `403 FUNCTIONALITY_NOT_ENABLED`, so
+this skill **must** run after the CMDB feature-enable skill has turned the feature on.
+
+On top of the org gate, these reads also enforce the **running user's own CMDB access**, so a
+`403 FUNCTIONALITY_NOT_ENABLED` here has two distinct causes — feature-off **or** user-has-no-access.
+Step 1 disambiguates them via the feature status before sending the user anywhere; never assume a 403
+means the feature is off.
+
+## 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 (discovery /
+  confirmation only).
+- `mcp__headless-360__describe` — pull the full input schema and canonical route before the install 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 **content will be installed into this
+  org** (a write). For production, get explicit confirmation.
+
+Do not re-ask for anything the user already provided; pre-populate and note "(from conversation)".
+
+---
+
+## Workflow
+
+Sequential. **Always read before you write** — read the catalog and resolve the exact version before
+installing. Never guess a version string.
+
+### Step 1 — Confirm CMDB is enabled (read, gate)
+
+```text
+dispatch_readonly({ "url": "/services/data/v67.0/connect/cmdb/bundleListView", "method": "GET" })
+```
+
+- `200` → CMDB is enabled; the response lists available bundles and their install status. Proceed.
+- `403 FUNCTIONALITY_NOT_ENABLED` → **ambiguous — disambiguate before telling the user CMDB is off.**
+  This read enforces **both** the org gate **and** the running user's own CMDB access, so a 403 has
+  two possible causes. Check the feature status to tell them apart:
+  ```text
+  dispatch_readonly({ "url": "/services/data/v67.0/connect/setup/discovery/feature/service-cloud-itsm-cmdb-integration/status", "method": "GET" })
+  ```
+  - `status != ENABLED` → the **CMDB feature isn't enabled**. STOP and route the user to the CMDB
+    feature-enable skill (`service-itsm-agentic-setup-cmdb-configure`) first.
+  - `status == ENABLED` → the feature **is** enabled; the running user simply **lacks CMDB permission
+    sets**. STOP and route the user to the CMDB access-assign skill
+    (`service-itsm-agentic-setup-cmdb-access-assign`) to grant themselves CMDB access — at minimum the
+    read set, plus **Type Manager** for bundle management — then retry. Do NOT send them to the
+    feature-enable skill; CMDB is already enabled.
+
+From the `bundleListView` response, identify the base bundle (CMDB Foundation) and note its
+`currentInstalledVersion`. If it is already installed at the latest version, tell the user there is
+nothing to do.
+
+### Step 2 — Resolve the exact base version (read)
+
+Do NOT guess or hard-code the version. Read the authoritative version from bundle details:
+
+```text
+dispatch_readonly({ "url": "/services/data/v67.0/connect/cmdb/bundles/details", "method": "GET", "queryParams": { "bundleIdentifier": "base" } })
+```
+
+Read `latestVersion` from the catalog and use that string **verbatim** for the install — do NOT strip,
+add, or reformat any characters (including a leading `v`). The install endpoint matches the version by
+exact string equality against the registry, and the registry stores versions exactly as the catalog
+reports them (e.g. `"v3.0"`), so the value must be passed through unchanged.
+
+**You may only install the latest version.** The install endpoint rejects any non-latest version
+(`"Target version <x> is not the latest available version"`) — it does not support installing or
+rolling back to an older version, so always resolve `latestVersion` and install exactly that. If
+`installedVersion` already equals `latestVersion`, stop — the base bundle is up to date.
+
+> **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 **Type Manager** role — the Reader / Owner / Type Reader sets are not
+> sufficient. Route the user to the CMDB access-assign skill to grant Type Manager, then retry. As a
+> fallback, `bundleListView` already returns the base bundle's `currentInstalledVersion` and
+> `latestVersion`, so you can resolve the version from Step 1's response if Type Manager cannot be
+> assigned.
+
+### Step 3 — Confirm with the user (before the write)
+
+Show the base bundle name, the version to be installed, and the target org. Get explicit confirmation
+before the write. State plainly that this installs out-of-the-box CMDB content into the org.
+
+### Step 4 — Install the base bundle (write)
+
+Call `discover(query="cmdb bundle installation")` then `describe(id=<bundleInstallation operation id>)`
+to confirm the input schema, then install:
+
+```text
+dispatch({ "url": "/services/data/v67.0/connect/cmdb/bundleInstallation", "method": "POST", "body": { "bundleIdentifier": "base", "version": "<latestVersion from Step 2, verbatim>" } })
+```
+
+Both `bundleIdentifier` and `version` are required, and `version` must be the catalog's `latestVersion`
+string passed through unchanged. A `success: true` response means the installation was **initiated** —
+it may complete asynchronously.
+
+### Step 5 — Verify (read — do NOT trust the install response alone)
+
+Re-read bundle details and confirm the base bundle now reports the installed version:
+
+```text
+dispatch_readonly({ "url": "/services/data/v67.0/connect/cmdb/bundles/details", "method": "GET", "queryParams": { "bundleIdentifier": "base" } })
+```
+
+`installedVersion` should equal the version you installed. If installation is async and it has not
+updated yet, tell the user it is in progress and how to re-check.
+
+---
+
+## Rules / Constraints
+
+| Constraint | Rationale |
+|-----------|-----------|
+| Read `bundleListView` first as the enablement gate | A 403 here means either CMDB isn't enabled or the user lacks CMDB access — disambiguate via feature status before acting |
+| Resolve the version from `bundles/details`; never guess; pass `latestVersion` verbatim | The install endpoint matches the version by exact string equality against the registry, which stores it exactly as the catalog reports (e.g. `"v3.0"`) — do not strip or reformat any characters |
+| Install only the latest version | The endpoint rejects any non-latest version (`"Target version <x> is not the latest available version"`); it cannot install or roll back to an older version |
+| Install `base` only | This skill is scoped to the CMDB Foundation base bundle; optional add-ons are out of scope |
+| Confirm the target org and the install with the user | Installing content is a real, hard-to-reverse write on a live org |
+| Skip if already installed at latest | Avoid redundant installs; report "already up to date" |
+| Treat `success: true` as "initiated"; verify separately | Installation can be asynchronous |
+| Never expose internal jargon to the user | Keep record IDs, HTTP status codes (403/400/500), API error codes (`FUNCTIONALITY_NOT_ENABLED`, …), endpoint names (`bundleListView`, `bundles/details`, `bundleInstallation`), developer names, and tooling internals (`dispatch`, `headless-360`) out of user-facing output. Use bundle names and versions and plain language |
+
+---
+
+## Verification checklist
+
+- [ ] `bundleListView` returned `200` (CMDB is enabled and the user has access)?
+- [ ] Resolved `latestVersion` for `base` from `bundles/details` (not guessed)?
+- [ ] Skipped if already at the latest version?
+- [ ] Confirmed the target org + install with the user before writing?
+- [ ] `bundleInstallation` returned `success: true`?
+- [ ] Verified `installedVersion` matches (or reported async in-progress)?
+
+---
+
+## Output expectations
+
+```text
+CMDB Bundle Deploy — Complete (via service-itsm-agentic-setup-cmdb-bundle-deploy)
+
+Target org: <org>
+
+  Bundle:   CMDB Foundation (base)
+  Version:  <version>
+  Status:   Installation initiated — success
+
+CMDB now has its base content installed. Combined with the enabled feature and assigned user
+access, CMDB is ready end-to-end.
+```
+
+Keep internal jargon out of user-facing output (no record IDs, HTTP status codes, error codes, or
+endpoint names). If any step fails, stop and tell the user — in plain language — what didn't succeed
+and what it means for them (e.g. "CMDB isn't turned on for this org yet, so the content can't be
+installed" rather than echoing a 403 code), then point to the fix.
+
+---
+
+## Common failures (surface these in plain language)
+
+| Symptom | Likely cause | What to tell the user |
+|---------|--------------|-----------------------|
+| `403` on the catalog read **and** feature not enabled | CMDB feature not enabled for the org | CMDB must be turned on for the org first; that's a separate setup step — point to the feature-enable skill |
+| `403` on the catalog read **but** feature is enabled | Feature is on; the running user lacks CMDB access (this read enforces user-level access too) | Grant the user CMDB access first (a separate setup step), then try again — the feature itself is already on |
+| `403` on the version read **but** the catalog read succeeded | The user lacks the CMDB bundle-management role (Type Manager) | Grant the user the CMDB Type Manager role (a separate access step), then retry; the org itself is set up correctly |
+| Install rejected — bundle/version doesn't exist | Wrong version string | Re-read the catalog and use the exact latest version it reports |
+| Install reported success but the version hasn't changed | Installation is running in the background | It's in progress; check again shortly to confirm it finished |
+| Downstream error on install | Temporary platform dependency issue | Try again; if it keeps failing, this needs Salesforce support |
+| Connection/authentication error | The org connection isn't set up or has expired | Re-authenticate the org connection and confirm it points at the intended org, then retry |
+
+---
+
+## Cross-skill integration
+
+| When | Skill |
+|------|-------|
+| The org CMDB feature is not enabled yet (org gate still closed) | `service-itsm-agentic-setup-cmdb-configure` (Layers 0–2 — enable the feature first, then return here) |
+| The running user lacks CMDB access, or lacks **Type Manager** for bundle management | `service-itsm-agentic-setup-cmdb-access-assign` (Layer 3 — grant the user CMDB access, including Type Manager, then return here) |
+
+---
+
+## Reference file index
+
+| File | When to read |
+|------|--------------|
+| `references/mcp-invocation.md` | Exact `mcp__headless-360__*` call shapes for the bundle catalog + install calls, response envelopes, the install schema lookup, and the error table |