@salesforce/afv-skills 1.40.0 → 1.41.0

package/skills/service-itsm-teams-itdesk-configure/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: service-itsm-teams-itdesk-configure
+description: "Configure the \"Set Up Salesforce IT Desk\" checklist for Microsoft Teams Employee Service (ITSM) — the fulfiller/agent side, covering app enablement, marketplace install guidance, user access assignment, and Swarming collaboration-tool setup. Use this for: 'turn on Salesforce IT Desk', 'set up IT Desk on Teams', 'assign Teams for IT Desk permission set', 'set Teams as collaboration tool for swarming', 'install Salesforce IT Desk app on Teams', or any request to complete the IT Desk half of the Teams ITSM Go page checklist. DO NOT TRIGGER for the base Teams Salesforce Go page toggle or Azure/Entra app setup (service-itsm-teams-configure) or for the IT Service/employee half of the checklist (service-itsm-teams-itservice-configure)."
+metadata:
+  version: "1.0"
+  domains: ["Service"]
+  minApiVersion: "67.0"
+  relatedSkills:
+    - "service-itsm-channels-coordinate"
+    - "service-itsm-swarming-configure"
+    - "service-itsm-teams-configure"
+    - "service-itsm-teams-itservice-configure"
+  mcpTools:
+    headless-360:
+      tools: ["describe", "discover", "dispatch", "dispatch_readonly"]
+      semver: ">=1.0.0"
+  accessCheck:
+    - type: "orgPref"
+      value: "ITSMTeamsEnabled"
+allowed-tools: |
+  Read AskUserQuestion
+  mcp__headless-360__discover
+  mcp__headless-360__describe
+  mcp__headless-360__dispatch
+  mcp__headless-360__dispatch_readonly
+---
+
+# Set Up Salesforce IT Desk (Microsoft Teams)
+
+Complete the **"Set Up Salesforce IT Desk"** checklist group on the Teams ITSM Go page
+(`service-cloud-itsm-teams-integration`'s feature page) — the fulfiller/agent side of Teams
+ITSM integration, for IT agents to swarm on and resolve tickets from Teams. Every operation
+dispatches through **headless-360**.
+
+## Scope
+
+- **In scope**: Turning on the `OrgHasITSMFulfillerTeams` preference; giving the user the exact
+  Teams marketplace link + help doc for the IT Desk app install; assigning
+  `TeamsForITSrvcsUser`/`MicrosoftGraphAccess` permission sets to confirmed users; delegating
+  "Set Teams as Collaboration Tool for Swarming" to `service-itsm-swarming-configure`.
+- **Out of scope**: The base Teams Salesforce Go page toggle (`ITSMTeamsEnabled`), Azure/Entra app
+  registration, Named Credential population, and Teams extension/preferred-site registration —
+  use `service-itsm-teams-configure` (a prerequisite for this skill). The IT Service/employee
+  half of the checklist — use `service-itsm-teams-itservice-configure`. Enabling the
+  `service-cloud-swarming` Go feature itself — delegate to `service-itsm-swarming-configure`.
+
+**Prerequisite:** run `service-itsm-teams-configure` first (or alongside) — this skill assumes
+the `service-cloud-itsm-teams-integration` Go feature is already enabled.
+
+> **Execute one step at a time.** These steps make real, state-changing API calls. Run a single
+> operation, show its result, confirm it succeeded, then proceed — do not batch multiple setup
+> calls into one parallel block.
+
+---
+
+## Workflow
+
+### Step 1 — Turn on Salesforce IT Desk
+
+This is a straight org-preference toggle (unlike `ITSMTeamsEnabled`, this one supports direct
+`PATCH`) — enable it yourself via API, do not ask the user to click the Setup toggle:
+
+```text
+mcp__headless-360__dispatch(
+  method: "PATCH",
+  url:    "/services/data/v67.0/setup/org/preferences/OrgHasITSMFulfillerTeams",
+  body:   { "desiredState": true }
+)
+```
+
+Expect `200 {"isPreferenceEnabled": true}`. Tell the user it's enabled — do not ask them to flip
+the toggle themselves.
+
+### Step 2 — Install Salesforce IT Desk App on Teams (user's responsibility)
+
+There is no Salesforce or Microsoft API this skill can call to install a Teams app into a
+tenant's app catalog — this always requires a human clicking "Add" in the Microsoft Teams admin
+center / AppSource, signed in with sufficient tenant permissions. Give the user the exact
+marketplace link and help doc; do not attempt to automate this step.
+
+- Marketplace (verified live from the Go page's "Go to Microsoft Marketplace" button):
+  ```text
+  https://marketplace.microsoft.com/en-us/product/teams-app/WA200009869?tab=Overview
+  ```
+- Help doc: `https://help.salesforce.com/s/articleView?id=service.it_srvce_msteams_cnfig_fulfilerhub_app.htm&type=5`
+
+Print both together so the user has a self-service reference alongside the install link. Also tell
+the user that **the Azure/Microsoft account email the fulfiller signs into Teams with must match
+that Salesforce user's email / `Username`** — SSO resolves the Microsoft UPN to the Salesforce
+`Username`, so a mismatch causes a silent login failure.
+
+**Then HALT and wait** for the user to confirm the app is installed (they reply **"installed"**).
+This is a human-only action; do not proceed to Step 3's user-access assignment as if it were done,
+and do not fabricate the confirmation — wait for the real reply.
+
+### Step 3 — Manage User Access
+
+"Manage User Access" ("Manage" button on the Go page) assigns two permission sets — verified
+live from the "Manage Microsoft Teams for Employee Service User Access" dialog:
+
+- `TeamsForITSrvcsUser` (label **"Microsoft Teams for IT Services"**, backed by PSL
+  `TeamsForITSrvcsPsl`)
+- `MicrosoftGraphAccess` (label **"MicrosoftGraphAccess"**) — assigned alongside it in the same
+  dialog.
+
+**Do not just assign every active user.** Ask the user which specific user(s) should get access.
+If they want to see the list of users first (rather than naming them), page it — **show at most
+10 users per page**, then ask "want to see more?" before showing the next page, since orgs can
+have hundreds or thousands of users:
+
+```text
+mcp__headless-360__dispatch_readonly(
+  method: "GET",
+  url:    "/services/data/v67.0/query",
+  queryParams: { "q": "SELECT Id, Name, Username, Email FROM User WHERE IsActive = true ORDER BY Name LIMIT 10 OFFSET <page * 10>" }
+)
+```
+
+**Verified gotcha:** in scratch/test orgs (and possibly some real orgs), the first page(s) of
+this query are often dominated by non-employee system/integration accounts — e.g. `Automated
+Process`, `Bot User`, `Insights Integration`, `*.ext` integration users, `ESW_*` / `*Site Guest
+User` guest users, and `DigitalAgent.*` agent users. When presenting a page to the user, flag
+these as likely-not-employee accounts (don't silently filter them out of the list — the user may
+still want one assigned — but call out which rows look like system accounts so the user doesn't
+have to guess). If the user says a listed batch is "not employee users, skip," move on to the
+next page rather than assigning any of them.
+
+Once the user confirms specific user(s), look up each permission set's `Id` (they are stable per
+org but don't hardcode them — query fresh):
+
+```text
+mcp__headless-360__dispatch_readonly(
+  method: "GET",
+  url:    "/services/data/v67.0/query",
+  queryParams: { "q": "SELECT Id, Name FROM PermissionSet WHERE Name IN ('TeamsForITSrvcsUser','MicrosoftGraphAccess')" }
+)
+```
+
+Then assign both permission sets to each confirmed user via `PermissionSetAssignment` (one record
+per user/permset pair — batch with as many calls as needed, there is no bulk-assign endpoint
+exposed here):
+
+```text
+mcp__headless-360__dispatch(
+  method: "POST",
+  url:    "/services/data/v67.0/sobjects/PermissionSetAssignment",
+  body:   { "AssigneeId": "<user id>", "PermissionSetId": "<permission set id>" }
+)
+```
+
+Verify by re-querying `PermissionSetAssignment` for that `AssigneeId`, or simply trust the `201`
+from the assignment call plus a `SELECT ... FROM PermissionSetAssignment WHERE AssigneeId =
+'<user id>' AND PermissionSetId = '<permset id>'` readback.
+
+#### Login prerequisite — the two Manage-User-Access permsets are NOT enough to sign in (verified)
+
+Assigning `TeamsForITSrvcsUser` + `MicrosoftGraphAccess` provisions the IT Desk *surface*, but a
+fulfiller who opens the IT Desk app in Teams can still hit **"server not reachable"** on the login
+page. The verified root cause is the **`ServiceCloudMSTeamsEca` External Client App OAuth
+authorize being denied** — `LoginHistory` for the user shows
+`Application = ServiceCloudMSTeamsEca`, `Status = Failed: Not approved for access`
+(`LoginType = Remote Access 2.0`). Neither `TeamsForITSrvcsUser` nor `MicrosoftGraphAccess` clears
+this, because:
+
+1. **They are not pre-authorized to the ECA.** The ECA's policy is `AdminApprovedPreAuthorized`
+   (verified: `SELECT PermittedUsersPolicyType FROM ExtlClntAppOauthPlcyCnfg WHERE
+   ExternalClientApplicationId = '<ecaId>'` — Tooling), so **only** users holding a permission set
+   explicitly pre-authorized on the ECA can complete OAuth. Check which permset that is:
+   `SELECT ParentId, Parent.Name FROM SetupEntityAccess WHERE SetupEntityId = '<ecaId>'` — in the
+   verified org the sole authorized set was **`Teams_Employee_ApiAccess`**, and the IT Desk agent did
+   not hold it.
+2. **They do not grant API Enabled.** Both read `PermissionsApiEnabled = false`; the embedded app's
+   Connect calls need the **API Enabled** system permission or they 403.
+
+**Fix (verified to resolve the login):** also assign the fulfiller the **`Teams_Employee_ApiAccess`**
+permission set — it is simultaneously the ECA-pre-authorized set **and** carries
+`PermissionsApiEnabled = true`, so it clears both blockers in one assignment:
+
+```text
+mcp__headless-360__dispatch(
+  method: "POST",
+  url:    "/services/data/v67.0/sobjects/PermissionSetAssignment",
+  body:   { "AssigneeId": "<user id>", "PermissionSetId": "<Teams_Employee_ApiAccess Id>" }
+)
+```
+
+After assigning, have the user **fully close and reopen the Teams app** (the ECA authorize is cached
+client-side). Also confirm **CORS Allowed Origins** contains both `https://teams.cloud.microsoft`
+and `https://cdn.scs.static.lightning.force.com` (`SELECT UrlPattern FROM CorsWhitelistEntry`). If
+login still fails in a fresh session after the ECA-authorized permset is assigned, the remaining
+suspect is the **"Allow OAuth for employees"** profile checkbox (Setup-UI-only — no API write path).
+See `service-itsm-teams-itservice-configure`'s *Login prerequisites* and its Troubleshooting
+section D (ECA self-authorization) for the full pass/fail diagnostic chain — the same ECA gates both
+the fulfiller (IT Desk) and employee (IT Service) apps.
+
+### Step 4 — Set Teams as Collaboration Tool for Swarming (delegate)
+
+This 4th checklist item requires the `service-cloud-swarming` Go feature to be enabled first.
+**Do not enable that feature inline here — invoke the dedicated
+`service-itsm-swarming-configure` skill** instead of duplicating feature-enablement logic:
+
+```text
+Invoke the service-itsm-swarming-configure skill.
+```
+
+That skill enables `service-cloud-swarming` **and** writes `SWARM_COLLABORATION_TOOL` to `"Teams"`
+via `PATCH /services/data/v67.0/setup/org/values/SWARM_COLLABORATION_TOOL` — this checklist item
+is now fully automated end-to-end, no manual "Go to Feature Page" click required.
+
+---
+
+## Gotchas
+
+| Issue | Detail |
+|-------|--------|
+| Requires the Teams Salesforce Go page feature first | `OrgHasITSMFulfillerTeams` does not gate or depend on `ITSMTeamsEnabled` directly, but the Go page checklist only appears once `service-cloud-itsm-teams-integration` is enabled — run `service-itsm-teams-configure` first. |
+| `OrgHasITSMFulfillerTeams` does not unblock `ITSMTeamsEnabled` | These are separate bits — enabling this preference does not itself unblock the Teams Salesforce Go page toggle preference, and vice versa. |
+| "Set Teams as Collaboration Tool for Swarming" needs `service-cloud-swarming` enabled first | Delegate to `service-itsm-swarming-configure` rather than enabling that feature inline. That skill both enables the feature and writes `SWARM_COLLABORATION_TOOL` to `"Teams"` — the whole checklist item is API-reachable, not just the base feature enable. |
+| Permission sets / PSLs | `TeamsForITSrvcsUser`, `MicrosoftGraphAccess` (permission sets) and PSL `TeamsForITSrvcsPsl` auto-provisioned and were confirmed `Active` (10 licenses) immediately after the feature-enable in this session — no manual PSL/permset creation needed once `TeamsITSrvcsAddOn`+`IncidentManagementAddOn` are licensed. |
+| Manage-User-Access permsets don't cover login — assign `Teams_Employee_ApiAccess` too | Verified: after assigning `TeamsForITSrvcsUser` + `MicrosoftGraphAccess`, the IT Desk agent still failed Teams login with **"server not reachable"**; `LoginHistory` showed `ServiceCloudMSTeamsEca` = **"Failed: Not approved for access."** The `ServiceCloudMSTeamsEca` ECA is `AdminApprovedPreAuthorized` and its only pre-authorized permset was `Teams_Employee_ApiAccess`; neither Manage-User-Access set is authorized on the ECA, and both have `PermissionsApiEnabled = false`. Assigning `Teams_Employee_ApiAccess` (ECA-pre-authorized **and** grants API Enabled) resolved the login. See [Step 3 → Login prerequisite](#login-prerequisite--the-two-manage-user-access-permsets-are-not-enough-to-sign-in-verified). |
+| Version prefix required | headless-360 `dispatch`/`dispatch_readonly` do not resolve API versions — always pass the full `/services/data/vXX.0/...` prefix. |
+
+---
+
+## Related Skills
+
+| Skill | When to use instead / alongside |
+|-------|---------------------|
+| `service-itsm-teams-configure` | Enabling the base Teams Salesforce Go page toggle, Azure/Entra app registration, Named Credential population, and Teams extension registration — a prerequisite for this skill |
+| `service-itsm-teams-itservice-configure` | The IT Service/employee half of the checklist (Turn on IT Service, Install IT Service app, Manage User Access, Select a Digital Experience Site) |
+| `service-itsm-swarming-configure` | Enabling the `service-cloud-swarming` Go feature for "Set Teams as Collaboration Tool for Swarming" — this skill delegates to it rather than duplicating that logic |
+| `service-itsm-channels-coordinate` | Top-level menu across Teams, Slack, Swarming, Notifications, Portal |

package/skills/service-itsm-teams-itservice-configure/SKILL.md

@@ -0,0 +1,391 @@
+---
+name: service-itsm-teams-itservice-configure
+description: "Configure the \"Set Up Salesforce IT Service\" checklist for Microsoft Teams Employee Service (ITSM) — the employee side, covering app enablement, marketplace install guidance, user access assignment, and Digital Experience Site selection. Use this for: 'turn on Salesforce IT Service', 'set up IT Service on Teams', 'assign Teams for Employee permission set', 'give employees access to Teams for Employee Service', 'manage user access for Teams ITSM', 'grant users the permission sets needed for Teams Employee Service', 'select a digital experience site for Teams', 'install Salesforce IT Service app on Teams', or any request to complete the IT Service half of the Teams ITSM Go page checklist (including the Manage User Access step). DO NOT TRIGGER for the base Teams Salesforce Go page toggle or Azure/Entra app setup (service-itsm-teams-configure) or for the IT Desk/fulfiller half of the checklist (service-itsm-teams-itdesk-configure)."
+metadata:
+  version: "1.0"
+  domains: ["Service", "Experience"]
+  minApiVersion: "67.0"
+  relatedSkills:
+    - "service-itsm-channels-coordinate"
+    - "service-itsm-teams-configure"
+    - "service-itsm-teams-debug"
+    - "service-itsm-teams-employee-agent-configure"
+    - "service-itsm-teams-itdesk-configure"
+  mcpTools:
+    headless-360:
+      tools: ["describe", "discover", "dispatch", "dispatch_readonly"]
+      semver: ">=1.0.0"
+  accessCheck:
+    - type: "orgPref"
+      value: "ITSMTeamsEnabled"
+allowed-tools: |
+  Read AskUserQuestion
+  mcp__headless-360__discover
+  mcp__headless-360__describe
+  mcp__headless-360__dispatch
+  mcp__headless-360__dispatch_readonly
+---
+
+# Set Up Salesforce IT Service (Microsoft Teams)
+
+Complete the **"Set Up Salesforce IT Service"** checklist group on the Teams ITSM Go page
+(`service-cloud-itsm-teams-integration`'s feature page) — the employee side of Teams ITSM
+integration, for employees to create and manage their own tickets from Teams. Every operation
+dispatches through **headless-360**.
+
+## Scope
+
+- **In scope**: Turning on the `OrgHasEmployeeServiceTeams` preference; giving the user the
+  exact Teams marketplace link + help doc for the IT Service app install; assigning
+  `TeamsForEmployeeUser`/`MicrosoftGraphAccess` permission sets to confirmed users; selecting the
+  Digital Experience Site to link with Teams via the `SLACK_PREFERRED_SITE` org value.
+- **Out of scope**: The base Teams Salesforce Go page toggle (`ITSMTeamsEnabled`), Azure/Entra app
+  registration, Named Credential population, and Teams extension/preferred-site registration —
+  use `service-itsm-teams-configure` (a prerequisite for this skill). The IT Desk/fulfiller half
+  of the checklist — use `service-itsm-teams-itdesk-configure`.
+
+**Prerequisite:** run `service-itsm-teams-configure` first (or alongside) — this skill assumes
+the `service-cloud-itsm-teams-integration` Go feature is already enabled.
+
+> **Execute one step at a time.** These steps make real, state-changing API calls. Run a single
+> operation, show its result, confirm it succeeded, then proceed — do not batch multiple setup
+> calls into one parallel block.
+
+---
+
+## Workflow
+
+### Step 1 — Turn on Salesforce IT Service
+
+This is a straight org-preference toggle (unlike `ITSMTeamsEnabled`, this one supports direct
+`PATCH`) — enable it yourself via API, do not ask the user to click the Setup toggle:
+
+```text
+mcp__headless-360__dispatch(
+  method: "PATCH",
+  url:    "/services/data/v67.0/setup/org/preferences/OrgHasEmployeeServiceTeams",
+  body:   { "desiredState": true }
+)
+```
+
+Expect `200 {"isPreferenceEnabled": true}`. Tell the user it's enabled — do not ask them to flip
+the toggle themselves.
+
+### Step 2 — Install Salesforce IT Service App on Teams (user's responsibility)
+
+There is no Salesforce or Microsoft API this skill can call to install a Teams app into a
+tenant's app catalog — this always requires a human clicking "Add" in the Microsoft Teams admin
+center / AppSource, signed in with sufficient tenant permissions. Give the user the exact
+marketplace link and help doc; do not attempt to automate this step.
+
+- Marketplace (verified live from the Go page's "Go to Microsoft Marketplace" button):
+  ```text
+  https://marketplace.microsoft.com/en-us/product/teams-app/WA200009838?tab=Overview
+  ```
+- Help doc: `https://help.salesforce.com/s/articleView?id=service.it_srvcs_msteams_config_emplye_srvcs_app.htm&type=5`
+
+Print both together. Also tell the user **the Microsoft email the employee signs in with must match
+that Salesforce user's `Username`** (SSO maps MS UPN → `Username`; a mismatch fails login silently).
+**Then HALT** until the user replies **"installed"** — a human-only action; do not proceed or
+fabricate the confirmation.
+
+### Step 3 — Manage User Access
+
+"Manage User Access" ("Manage" button on the Go page) assigns two permission sets — verified
+live from the "Manage Microsoft Teams for Employee Service User Access" dialog:
+
+- `TeamsForEmployeeUser` (label **"Teams for Employee"**, backed by PSL `TeamsForEmployeePsl`)
+- `MicrosoftGraphAccess` (label **"MicrosoftGraphAccess"**) — assigned alongside it in the same
+  dialog.
+
+**Do not just assign every active user.** Ask the user which specific user(s) should get access.
+If they want to see the list of users first (rather than naming them), page it — **show at most
+10 users per page**, then ask "want to see more?" before showing the next page, since orgs can
+have hundreds or thousands of users:
+
+```text
+mcp__headless-360__dispatch_readonly(
+  method: "GET",
+  url:    "/services/data/v67.0/query",
+  queryParams: { "q": "SELECT Id, Name, Username, Email FROM User WHERE IsActive = true ORDER BY Name LIMIT 10 OFFSET <page * 10>" }
+)
+```
+
+**Verified gotcha:** in scratch/test orgs (and possibly some real orgs), the first page(s) of
+this query are often dominated by non-employee system/integration accounts — e.g. `Automated
+Process`, `Bot User`, `Insights Integration`, `*.ext` integration users, `ESW_*` / `*Site Guest
+User` guest users, and `DigitalAgent.*` agent users. When presenting a page to the user, flag
+these as likely-not-employee accounts (don't silently filter them out of the list — the user may
+still want one assigned — but call out which rows look like system accounts so the user doesn't
+have to guess). If the user says a listed batch is "not employee users, skip," move on to the
+next page rather than assigning any of them.
+
+Once the user confirms specific user(s), look up each permission set's `Id` (they are stable per
+org but don't hardcode them — query fresh):
+
+```text
+mcp__headless-360__dispatch_readonly(
+  method: "GET",
+  url:    "/services/data/v67.0/query",
+  queryParams: { "q": "SELECT Id, Name FROM PermissionSet WHERE Name IN ('TeamsForEmployeeUser','MicrosoftGraphAccess')" }
+)
+```
+
+Then assign both permission sets to each confirmed user via `PermissionSetAssignment` (one record
+per user/permset pair — batch with as many calls as needed, there is no bulk-assign endpoint
+exposed here):
+
+```text
+mcp__headless-360__dispatch(
+  method: "POST",
+  url:    "/services/data/v67.0/sobjects/PermissionSetAssignment",
+  body:   { "AssigneeId": "<user id>", "PermissionSetId": "<permission set id>" }
+)
+```
+
+Verify by re-querying `PermissionSetAssignment` for that `AssigneeId`, or simply trust the `201`
+from the assignment call plus a `SELECT ... FROM PermissionSetAssignment WHERE AssigneeId =
+'<user id>' AND PermissionSetId = '<permset id>'` readback.
+
+#### Login prerequisites (required for the user to actually sign in to IT Service in Teams)
+
+Assigning the two permission sets above is necessary but **not sufficient** — a UEL user who
+opens the IT Service app in Teams can still hit a silent login failure unless all three of the
+following are also in place. Verify (and set) these as part of enabling a user:
+
+1. **"Allow OAuth for employees"** on the employee login profile (e.g. **Unified Employee**) —
+   Setup → Profiles → *(profile)* → Session Settings → check **Allow OAuth for employees**.
+   **Set this in the Setup UI.** It is **not** a Profile SObject field (no OAuth field appears in
+   `Profile` describe) and it is **not** the Metadata element `Profile.sessionSettings.allowOauthForEmployees`
+   — a Profile metadata deploy containing `<sessionSettings><allowOauthForEmployees>` **fails
+   validation**: `Element {…}sessionSettings invalid at this location in type Profile` (verified
+   Aug 2026). Nor is it readable/writable via the headless-360 Connect/REST/Tooling dispatch. Use
+   the Setup UI checkbox. Confirmed blocker: with it off, the OAuth handshake for the embedded app
+   fails and login silently does not complete — the community **login succeeds** (LoginHistory
+   "Employee Login to Community" = Success) but **no `OauthToken` is ever minted** for the user, and
+   the Teams app re-pops its "Single Sign-On / Login with URL" chooser (often with a
+   `/…/setup/secur/RemoteAccessAuthorizationPage` "Service Not Available" popup).
+
+2. **CORS Allowed Origins** must include **both** Teams origins. Check with
+   `dispatch_readonly GET /services/data/v67.0/query` on
+   `SELECT Id, UrlPattern FROM CorsWhitelistEntry`, and create any that are missing with
+   `dispatch POST /services/data/v67.0/sobjects/CorsWhitelistEntry` body
+   `{"UrlPattern": "<origin>"}` (this is a **data-API sobject**, not a Tooling type — a Tooling
+   `POST`/query returns `NOT_FOUND`/`INVALID_TYPE`):
+   - `https://teams.cloud.microsoft`
+   - `https://cdn.scs.static.lightning.force.com` — the Lightning static-resource CDN the embedded
+     IT Service surface loads from. Confirmed blocker: with this origin missing (even when
+     `teams.cloud.microsoft` is present), the browser blocks the asset/OAuth preflight and login
+     silently fails. After adding it, have the user hard-refresh / clear the Teams app cache.
+
+3. **"API Enabled"** system permission on the user. The UEL user must have the **API Enabled**
+   system permission — grant it via a permission set (create/choose a permission set → **System
+   Settings** → check **API Enabled** → assign to the user), not just the base profile. Without
+   it the embedded app's API calls are rejected and the user can't sign in.
+
+If a user reports "can't log in to IT Service in Teams" and Steps 1–4 all look done, walk these
+three prerequisites first — they are the most common silent-login blockers. For the full pass/fail
+diagnostic sequence (including the OAuth-token-mint check that isolates a portal-user OAuth failure),
+see [Troubleshooting: Teams for Employee Service login & agent](#troubleshooting-teams-for-employee-service-login--agent) below.
+
+### Step 4 — Select a Digital Experience Site
+
+This checklist item ("Digital Experience Site Name" dropdown, currently "None" until set) is
+**not** the same API as `service-itsm-teams-configure`'s Teams extension registration
+(`/connect/service-itsm-teams/graph-api/extensions`) — that one requires the Azure/Entra
+credential and is gated by the `MsTeamsAppApiFamily` license blocker (see that skill's Gotchas).
+This checklist item instead reads/writes the org-value `SLACK_PREFERRED_SITE` — the same
+`OrgValueUtil.OrgValues` Java-enum mechanism as Swarming's `SWARM_COLLABORATION_TOOL` — and is
+**not gated by any Teams license**, so it works even when the extension registration is blocked.
+
+1. List all Digital Experience sites in the org:
+   ```text
+   mcp__headless-360__dispatch_readonly(method: "GET", url: "/services/data/v67.0/connect/communities")
+   ```
+2. Present the full list to the user and ask them to pick one. **If they don't choose, pick one
+   yourself** (the only site if there's exactly one, otherwise a sensible default such as the most
+   recently modified `Live` site) **and explicitly tell the user which one you picked** — don't
+   proceed silently.
+3. Check the current value first (skip the write if already set to the chosen site's Id):
+   ```text
+   mcp__headless-360__dispatch_readonly(method: "GET", url: "/services/data/v67.0/setup/org/values/SLACK_PREFERRED_SITE")
+   ```
+   `stringValue` holds the current selection — the chosen site's `Id`, or `"None"`.
+4. Write the selection using the site's `Id` (from step 1's `connect/communities` response — the
+   `Network` record Id, **not** `urlPathPrefix`):
+   ```text
+   mcp__headless-360__dispatch(
+     method: "PATCH",
+     url:    "/services/data/v67.0/setup/org/values/SLACK_PREFERRED_SITE",
+     body:   { "orgValue": "<site Id>" }
+   )
+   ```
+   Verified live: `PATCH` with a site's Network `Id` (e.g. `0DBSB000002EYwj4AG`) returned
+   `200 {"stringValue": "<that Id>", ...}`, and a follow-up `GET` confirmed the same value
+   persisted.
+5. Re-run step 3's `GET` to confirm.
+
+### Step 5 — Make the embedded Agentforce agent reply in Teams
+
+Completing Steps 1–4 provisions the IT Service surface, but it does **not** make the embedded
+Agentforce agent actually **reply** inside the Teams custom client ("Salesforce Employee Assist" /
+"Ask AI Agent"). That is the final, hardest part of IT Service agent setup and is covered by a
+dedicated skill:
+
+**→ `service-itsm-teams-employee-agent-configure`**
+
+Invoke it (or hand off to it) after Step 4 when the user wants the in-Teams agent to respond. It
+covers the verified architecture — a Web channel with **User Verification ON + a `JWKS_URL` Key
+Set**, the `Teams_AgentForce` deployment, an Omni-Flow routing flow to a **real, Active** agent, and
+an **Agent Access permission set** on the portal user — plus the diagnostic for the common "agent
+joins then leaves" symptom (auth ON but no Key Set, or missing Agent Access). The
+per-user Agent Access assignment there is the natural follow-on to the Manage User Access step
+(Step 3) above.
+
+**Verified gotcha — UI shows stale "None" after the API write.** The Go page's dropdown is a wired
+LDS cache over this org-value; a raw Connect `PATCH` doesn't invalidate it. The write is real and
+durable (a follow-up `GET` confirms it) — if the Setup page is open, tell the user to **hard-refresh
+the tab** to see the new selection.
+
+**Naming is misleading — this is a shared, cross-feature setting, not Teams-exclusive.** Despite
+the `SLACK_` prefix (a holdover from this org-value's original Slack-ITSM use case), it backs
+the "Select a Digital Experience Site" picker on **both** the Teams ITSM Go page and the
+equivalent Slack ITSM Go page — writing it from one surface changes what the other surface
+shows. If the user has also configured Slack ITSM, flag that setting this will also change
+Slack's preferred site.
+
+---
+
+## Gotchas
+
+| Issue | Detail |
+|-------|--------|
+| Requires the Teams Salesforce Go page feature first | `OrgHasEmployeeServiceTeams` does not gate or depend on `ITSMTeamsEnabled` directly, but the Go page checklist only appears once `service-cloud-itsm-teams-integration` is enabled — run `service-itsm-teams-configure` first. |
+| `OrgHasEmployeeServiceTeams` does not unblock `ITSMTeamsEnabled` | These are separate bits — enabling this preference does not itself unblock the Teams Salesforce Go page toggle preference, and vice versa. |
+| "Select a Digital Experience Site" ≠ Teams extension registration — two different site-related APIs, don't conflate | This checklist item writes the org-value `SLACK_PREFERRED_SITE` via `PATCH /services/data/v67.0/setup/org/values/SLACK_PREFERRED_SITE` (body `{"orgValue": "<site Id>"}`) — **not gated by `MsTeamsAppApiFamily`**, works with no Azure/Entra credential required. `service-itsm-teams-configure`'s `POST /connect/service-itsm-teams/graph-api/extensions` is a *different* mechanism (Teams "extension" registration) that **does** require the Azure credential and **is** gated by `MsTeamsAppApiFamily`. Verified live: `PATCH .../setup/org/values/SLACK_PREFERRED_SITE` with a site's Network `Id` succeeded (`200`) in an org where `post-teams-extension` was still blocked with "Unable to fetch tenant ID." Also note despite the `SLACK_` name, this org-value is shared with the Slack ITSM integration's equivalent picker — not Teams-exclusive. |
+| Permission sets / PSLs | `TeamsForEmployeeUser`, `MicrosoftGraphAccess` (permission sets) and PSL `TeamsForEmployeePsl` auto-provisioned and were confirmed `Active` (10 licenses) immediately after the feature-enable in this session — no manual PSL/permset creation needed once `TeamsITSrvcsAddOn`+`IncidentManagementAddOn` are licensed. |
+| Version prefix required | headless-360 `dispatch`/`dispatch_readonly` do not resolve API versions — always pass the full `/services/data/vXX.0/...` prefix. |
+| UEL user can't log in to IT Service in Teams | Assigning `TeamsForEmployeeUser`/`MicrosoftGraphAccess` is not enough. Three additional prerequisites gate login (see [Step 3 → Login prerequisites](#login-prerequisites-required-for-the-user-to-actually-sign-in-to-it-service-in-teams)): **Allow OAuth for employees** on the login profile (**Setup-UI-only** — no working Metadata/SObject/Tooling write path; verified all fail), CORS Allowed Origins containing both `https://teams.cloud.microsoft` **and** `https://cdn.scs.static.lightning.force.com`, and the **API Enabled** system permission on the user. Each is independently a confirmed silent-login blocker. |
+
+---
+
+## Troubleshooting: Teams for Employee Service login & agent
+
+When a user reports a Teams for Employee Service failure (can't log in, "Service Not Available"
+popup, agent won't reply), run these checks **in order** — each is a pass/fail gate with an exact
+query and remediation. Stop at the first one that fails; they are ordered from most-common and
+cheapest to deepest.
+
+> For a **broader** guided diagnosis across all Teams ITSM symptoms (IT Desk login, feature
+> enablement, tab loading, service catalog, Agentforce, Swarming, SSO — not just IT Service login),
+> use the dedicated **`service-itsm-teams-debug`** skill, which routes the reported problem
+> to the matching pass/fail checklist. The sequence below is the IT-Service-login-focused subset.
+
+> Run the read-only checks with `dispatch_readonly` (a Tooling-object check is noted where the
+> query needs the Tooling API). Convert the placeholder ids to the real ones you find as you go.
+
+### A. Community login itself
+
+```text
+SELECT LoginTime, Status, LoginType FROM LoginHistory
+  WHERE UserId='<userId>' ORDER BY LoginTime DESC LIMIT 5
+```
+
+- **`No community access`** → the site's `Network.OptionsAllowInternalUserLogin` is off for an
+  internal/UEL user. Enable "Allow internal users to log in directly" on the site's login settings
+  (see the portal-create skill's internal-login flag). **Different failure** from the ones below —
+  fix this first if present.
+- **`Employee Login to Community` = `Success`** → login works; the failure is downstream in OAuth
+  or agent runtime. Continue to B.
+
+### B. The three silent-login prerequisites (see [Step 3 → Login prerequisites](#login-prerequisites-required-for-the-user-to-actually-sign-in-to-it-service-in-teams))
+
+1. **Allow OAuth for employees** on the login profile (Setup-UI-only checkbox). No API read path —
+   verify by the OAuth-token check in **C** below (its real symptom).
+2. **CORS Allowed Origins** — must contain **both** origins:
+   ```text
+   SELECT Id, UrlPattern FROM CorsWhitelistEntry
+   ```
+   Missing `https://teams.cloud.microsoft` **or** `https://cdn.scs.static.lightning.force.com` →
+   create it (`POST /sobjects/CorsWhitelistEntry` `{"UrlPattern":"<origin>"}`), then hard-refresh.
+3. **API Enabled** system permission on the user (via a permission set, not just the profile).
+
+### C. OAuth token mint — the decisive portal-user check
+
+This is the check that isolates a portal/UEL OAuth failure from a login failure. After the user
+retries login from a **fresh** Teams chat:
+
+```text
+SELECT Id, AppName, UserId, User.Username, CreatedDate FROM OauthToken
+  WHERE AppName='ServiceCloudMSTeamsEca'
+```
+
+- **A token row exists for the failing user** → OAuth succeeded; the problem is agent-runtime, not
+  login — jump to **E**.
+- **No token for the failing user, but community login shows `Success` (B)** → the OAuth
+  **authorize** step never minted a token. This is the "Service Not Available" popup on
+  `/<sitePrefix>/setup/secur/RemoteAccessAuthorizationPage`. Work through **D**.
+
+> **Diagnostic tell (verified):** if a **Standard-profile** user mints a `ServiceCloudMSTeamsEca`
+> token but a **Unified Employee (UEL) / portal** user does not — even with identical permission
+> sets — the blocker is specific to the portal-user OAuth authorize path (profile OAuth flag, or
+> the ECA self-authorization page being served on the community host), **not** the ECA
+> authorization grant. In the verified org the Standard user minted a token *without* even holding
+> the ECA-authorizing permission set, while the UEL user holding everything did not — so an
+> identical permission-set/SetupEntityAccess config does **not** explain the difference.
+
+### D. ECA (External Client App) OAuth self-authorization
+
+The `ServiceCloudMSTeamsEca` External Client App gates the OAuth authorize. Symptom: the Teams
+popup titled **"Service Not Available / An unexpected connection error occurred"** at
+`/<sitePrefix>/setup/secur/RemoteAccessAuthorizationPage`, and/or an access-check error body
+**`{"acc":8}`** on the streaming endpoint.
+
+1. **Policy must be `AdminApprovedPreAuthorized`** (not `AllSelfAuthorized`):
+   ```text
+   SELECT Id, PermittedUsersPolicyType FROM ExtlClntAppOauthPlcyCnfg
+     WHERE ExternalClientApplicationId='<ecaId>'   (Tooling)
+   ```
+   `AllSelfAuthorized` forces every user through the self-approval page, which **communities
+   cannot serve** (`/setup/secur/*` is a Setup page) → the connection error. Fix by editing the
+   `ExternalClientApplication`'s OAuth policy **via Metadata** (the Tooling object is read-only —
+   `update` → `CANNOT_INSERT_UPDATE_ACTIVATE_ENTITY`): retrieve
+   `ExtlClntAppOauthConfigurablePolicies:<Eca>_oauth_defaultPolicy`, set
+   `<permittedUsersPolicyType>AdminApprovedPreAuthorized</permittedUsersPolicyType>`, redeploy.
+   (Valid enum values are only `AllSelfAuthorized` and `AdminApprovedPreAuthorized` — `AdminApproved`
+   is invalid.)
+2. **Pre-authorize the ECA to a permission set the user holds** — `AdminApprovedPreAuthorized`
+   denies everyone not explicitly authorized (surfaces as `{"acc":8}`):
+   ```text
+   SELECT ParentId, SetupEntityType FROM SetupEntityAccess WHERE SetupEntityId='<ecaId>'
+   ```
+   If missing, create `SetupEntityAccess {ParentId=<permsetId the user has>, SetupEntityId=<ecaId>}`
+   (no `SetupEntityType` — it auto-resolves to `ExternalClientApplication`).
+3. **If policy is `AdminApprovedPreAuthorized`, the user holds an authorized permission set, and
+   "Allow OAuth for employees" is on — yet the token still doesn't mint for the portal user
+   (per C):** the remaining suspect is that the OAuth authorize is being routed to the
+   **community host** (`https://<org>.my.site.com/<prefix>/setup/secur/...`), which cannot render
+   the authorization page, rather than to My Domain. This ECA is **packaged/first-party** — do NOT
+   hand-edit its `callbackUrl`/`isFirstPartyAppEnabled`/`oauthLink`. At this point capture the exact
+   popup URL + any `acc` code and escalate to the Teams ITSM / ECA product team; it is beyond a
+   configurable-setting fix.
+
+### E. Embedded Agentforce agent joins then leaves (no reply)
+
+If login + OAuth succeed but the "Ask AI Agent" agent won't reply, hand off to
+`service-itsm-teams-employee-agent-configure` — the two verified fixes are (1) the `Teams_AgentForce`
+channel's **User Verification ON backed by a `JWKS_URL` Key Set** and (2) an **Agent Access** permission set enabling the IT
+Service Employee Agent on the portal user. That skill's reference has the full runtime-chain
+diagnostics (scrt2 token, SSE 401, `ConversationEntry` queries).
+
+---
+
+## Related Skills
+
+| Skill | When to use instead / alongside |
+|-------|---------------------|
+| `service-itsm-teams-configure` | Enabling the base Teams Salesforce Go page toggle, Azure/Entra app registration, Named Credential population, and Teams extension registration — a prerequisite for this skill |
+| `service-itsm-teams-itdesk-configure` | The IT Desk/fulfiller half of the checklist (Turn on IT Desk, Install IT Desk app, Manage User Access, Set Teams as Collaboration Tool for Swarming) |
+| `service-itsm-teams-employee-agent-configure` | The final part of IT Service agent setup — making the embedded Agentforce agent actually **reply** in the Teams custom client (Web channel, User Verification ON + `JWKS_URL` Key Set, `Teams_AgentForce` deployment, routing flow to a real Active agent, Agent Access permission set). Hand off to it after Step 4. |
+| `service-itsm-teams-debug` | Diagnosing a failing Teams ITSM setup across any symptom (login, feature enablement, tab loading, Agentforce, Swarming, SSO) — routes the problem to a pass/fail checklist and reports remediation |
+| `service-itsm-channels-coordinate` | Top-level menu across Teams, Slack, Swarming, Notifications, Portal |