@salesforce/afv-skills 1.44.0 → 1.45.0

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

@@ -48,8 +48,8 @@ Microsoft Teams. Every operation dispatches through **headless-360**.
   afterward; explaining why the direct org-preference PATCH route fails and why this route
   works instead; disabling the feature if requested; giving the user step-by-step instructions
   for the Azure/Entra app registration (Step 4a) since no Salesforce API can perform that part;
-  once the user provides the resulting Client ID/Tenant ID (in chat) and the Client Secret (via the
-  `TEAMS_ENTRA_CLIENT_SECRET` env var / secret file, never in chat), writing them
+  once the user provides the resulting Client ID/Tenant ID (in chat) and the Client Secret (written
+  to a gitignored secret file via the copy-paste command in Step 4a, never in chat), writing them
   directly into the `MSTeamsSetupClientCredentialsEC` Named Credential via API — this
   Salesforce-side write is always automated by this skill, never deferred back to the user;
   registering the Experience Cloud site as the Teams "preferred site" extension via
@@ -160,13 +160,12 @@ inaccessible via direct PATCH — is now enabled as a side effect of the feature
 ### Step 4 — Report *interim* status (setup is NOT complete yet)
 
 Report feature status and whether `ITSMTeamsEnabled` reads `true` — but **frame this as progress,
-not completion.** Enabling the Go feature is only the first half. The integration is **not
-functional** until the Microsoft Entra app is registered, its credentials are written into the
-Named Credential + Auth Provider, and admin consent is granted (Step 4a). Do **not** call this an
-"optional manual tail," do **not** mark Teams "Done"/"configured"/"complete," and do **not** hand
-back to any coordinator as done. State plainly: *"The Salesforce feature is enabled; Teams
-integration is not yet complete — the required Microsoft Entra app registration comes next."* Then
-proceed directly into Step 4a. See the **Completion contract** below for what "complete" requires.
+not completion.** Enabling the Go feature is only the first half; the integration is **not
+functional** until the Microsoft Entra app is registered, its credentials are written into the Named
+Credential + Auth Provider, and admin consent is granted (Step 4a). Do **not** mark Teams
+"Done"/"complete" or hand back to a coordinator as done. State plainly: *"The Salesforce feature is
+enabled; Teams integration is not yet complete — the Microsoft Entra app registration comes next."*
+Then proceed into Step 4a. See the **Completion contract** below for what "complete" requires.
 
 ### Step 4a — Follow the Go page's own order: Create Entra app → Configure Named Credentials → Grant consent
 
@@ -182,26 +181,39 @@ order; do not skip ahead to Named Credentials before the Entra app exists, and d
    clicks and wait for them to provide the resulting values:
    - **portal.azure.com** → **Microsoft Entra ID** → **App registrations** → **New registration**.
      Name it something identifiable (e.g. `Salesforce ITSM Teams Integration`); single-tenant is
-     fine unless the user's org spans multiple tenants; no redirect URI is needed for the
-     client-credentials flow used here.
+     fine unless the user's org spans multiple tenants. Leave the redirect URI blank at creation —
+     the Delegated Graph permissions below require one, but it's added later as the Auth Provider
+     callback (Step 5; see `references/azure-credential-population.md`).
    - From the app's **Overview** page, note the **Application (client) ID** and **Directory
      (tenant) ID**.
    - **Certificates & secrets** → **New client secret** → copy the secret **value** immediately
      (unrecoverable after leaving the page).
-   - **API permissions** → **Add a permission** → **Microsoft Graph** → **Application
-     permissions** → add the Graph permissions this integration needs (at minimum
-     `ChannelMessage.Send`, `Team.ReadBasic.All`, `Channel.ReadBasic.All`,
-     `TeamworkAppSettings.ReadWrite.All` — confirm against the org's current Teams for Employee
-     Service documentation, since required scopes can change between releases).
-   - Provide the credentials **without exposing the secret in chat**: the **Client ID** and
-     **Tenant ID** are non-secret identifiers and may be given in the conversation, but the
-     **Client Secret is a confidential credential — NEVER ask for it in chat and never accept it
-     there.** The user places the secret in the `TEAMS_ENTRA_CLIENT_SECRET` environment variable
-     (or a gitignored secret file whose path they give you); you read it from that source at write
-     time and never print, echo, or log its value.
+   - **API permissions** → **Add a permission** → **Microsoft Graph** → **Delegated
+     permissions** → add all 17 below, then click **Grant admin consent** so every row reads
+     *Granted*. These are **Delegated** (not Application) — verified working set:
+     `Channel.Create`, `Channel.ReadBasic.All`, `ChannelMember.Read.All`,
+     `ChannelMember.ReadWrite.All`, `ChannelMessage.Edit`, `ChannelMessage.Read.All`,
+     `ChannelMessage.ReadWrite`, `ChannelMessage.Send`, `Team.Create`, `Team.ReadBasic.All`,
+     `Group.Read.All`, `Group.ReadWrite.All`, `openid`, `profile`, `email`, `offline_access`,
+     `User.Read`. Several require admin consent (*Admin consent required = Yes*), so the **Grant
+     admin consent** click is mandatory — ungranted consent-required rows make Teams calls fail
+     (see the AccessDenied gotcha). Do **not** add `TeamworkAppSettings.ReadWrite.All` (not in the
+     working set). Scopes can change between releases — if MS docs list more, add and re-grant.
+   - Provide the credentials **without exposing the secret in chat**: **Client ID** and **Tenant
+     ID** are non-secret and may be given in the conversation; the **Client Secret is confidential —
+     NEVER ask for it in chat.** Have the user write it to a **gitignored file**: substitute the
+     job/temp path for `<secret-file>` (e.g. `$CLAUDE_JOB_DIR/tmp/teams-secret`), then hand them exactly
+     this to copy-paste into the Claude Code prompt (secret Value, not the Secret ID, between the quotes):
+     ```bash
+     ! umask 077; printf '%s' 'PASTE-CLIENT-SECRET-HERE' > <secret-file> && echo written
+     ```
+     Keep the leading `!` — it runs the line in this session's Bash so the file persists. It prints
+     `written`; then read it from `<secret-file>` at write time (Step 5) and never echo or log it.
+     > **Note:** the `!`-prefix line is echoed into the chat transcript — if the secret shows up there,
+     > treat it as compromised and have the user rotate it in Azure after setup works.
 2. **Configure Setup Named Credentials** ("Go to Setup" button on the Go page — the manual
    equivalent of what this skill automates). **Once you have the Client ID / Tenant ID and the
-   secret is available in the env var / file, do not tell the user to enter anything into Setup —
+   secret is available in the secret file, do not tell the user to enter anything into Setup —
    call the Named Credential APIs directly**, per "Populating `MSTeamsSetupClientCredentialsEC`
    given a user-supplied client ID/secret" under Step 5 below. **This same set of values must ALSO be written into the
    `microsoft_auth_provider` Auth Provider** (the inbound-SSO side, distinct from the outbound-Graph
@@ -225,7 +237,7 @@ order; do not skip ahead to Named Credentials before the Entra app exists, and d
 
 Everything the user does above (steps 1's Azure clicks and step 3's consent click) is their
 manual responsibility because no Salesforce API reaches Azure/Entra. Everything Salesforce-side —
-writing the supplied credential (secret read from the env var / secret file, never from chat) into
+writing the supplied credential (secret read from the gitignored secret file, never from chat) into
 the Named Credential in step 2 — is this skill's job to automate; that division of labor is the
 entire point of this skill.
 
@@ -281,27 +293,18 @@ If this returns `400 UNKNOWN_EXCEPTION "...external credential \"MSTeamsSetupCli
 might not exist"`, the Azure/Entra step (Gotchas) has not been completed yet — this is not a bug
 in the call itself.
 
-If instead it returns `AccessDenied` (or `400 UNKNOWN_EXCEPTION "Exception while creating Teams
-extension: Unable to fetch tenant ID"`) **even after** the external credential shows
-`authenticationStatus: "Configured"`, the cause is almost always the **Azure app's Graph
-permissions being of type _Delegated_ rather than _Application_** (client-credentials token flow
-cannot use delegated-only permissions). This is a **fixable Azure/Entra misconfiguration, not a
-hard license wall** — verified live this session: the same call went from `AccessDenied` to
-`201 Success` (`com_sf_itsm_teams_config`) after two changes on the Azure side, with no license
-change:
-
-1. In the Azure app registration → **API permissions**, ensure the Microsoft Graph permissions are
-   the **Application** type (not Delegated), then click **"Grant admin consent"** for the tenant.
-2. **Repopulate the credential** (see "Populating..." below) — re-provisioning or any feature
-   re-enable can leave the EC/Auth Provider empty; a freshly-populated `MSTeamsSetupClientCredentialsEC`
-   showing `authenticationStatus: "Configured"` is required at the moment of the retry.
-
-Retry Step 5 after both. Only treat this as a genuine org-license blocker (the `MsTeamsAppApiFamily`
-gotcha below) if the call **still** fails once Application-type Graph permissions + admin consent
-are confirmed and the credential is freshly `Configured`.
+If instead it returns `AccessDenied` (or `400 UNKNOWN_EXCEPTION "...Unable to fetch tenant ID"`)
+**even after** the EC shows `authenticationStatus: "Configured"`, the cause is almost always an
+**incomplete Azure/Entra grant** — fixable, not a license wall (verified: same call went
+`AccessDenied` → `201 Success` after these). Check, in order: (1) **admin consent not granted** —
+several Step 4a scopes read *Admin consent required = Yes* and surface as `AccessDenied` until an
+admin clicks **Grant admin consent**; confirm every row reads *Granted*. (2) **credential empty** —
+a re-provision can empty the EC; it must read `Configured` at retry, so **repopulate** it. Retry
+Step 5 after both. **Do not "fix" this by switching Delegated → Application** — the verified working
+integration is Delegated + admin consent; flipping to Application diverges from the known-good setup.
 
 Once you have the Azure Client ID and Tenant ID (given in chat) and the Client Secret (read from the
-`TEAMS_ENTRA_CLIENT_SECRET` env var / secret file — never requested in chat; Step 4a), do the
+gitignored secret file written in Step 4a — never requested in chat), do the
 Salesforce-side writes yourself — do not tell the user to enter values in Setup. The full verified
 recipe (populating `MSTeamsSetupClientCredentialsEC`, populating the `microsoft_auth_provider` Auth
 Provider for inbound SSO via the Metadata API, matching the portal user's `Username` to the Microsoft
@@ -324,8 +327,8 @@ optional tail. Report **complete only when every item below is verified** (not m
 1. **Feature enabled** — `service-cloud-itsm-teams-integration` reads `ENABLED` and
    `ITSMTeamsEnabled` reads `true` (Steps 1–3).
 2. **Microsoft Entra app registered** — the user has completed Step 4a's Azure clicks and provided
-   the Client ID and Tenant ID (in chat) with the Client Secret placed in the
-   `TEAMS_ENTRA_CLIENT_SECRET` env var / secret file (never pasted in chat). Until they do, **stop
+   the Client ID and Tenant ID (in chat) with the Client Secret written to the gitignored secret
+   file via the Step 4a copy-paste command (never pasted in chat). Until they do, **stop
    and wait** — this is a hard gate; you cannot proceed past it, and you must not report completion
    around it.
 3. **Credentials populated (Salesforce-side, automated by this skill)** — `MSTeamsSetupClientCredentialsEC`
@@ -375,8 +378,8 @@ not instead of, the Step 2 feature-enable call if the user wants both Hubs.
 ## Gotchas
 
 The verified, load-bearing pitfalls (direct-PATCH 401, empty Auth Provider, Azure Web-vs-SPA
-redirect, Username=UPN handler, portal API-Enabled, static consent link, `MsTeamsAppApiFamily`
-403 hard gate, version-prefix requirement, and more) are catalogued in
+redirect, Username=UPN handler, portal API-Enabled, static consent link, version-prefix
+requirement, and more) are catalogued in
 [`references/gotchas.md`](references/gotchas.md). Read it before reporting a step as failed or
 retrying an enablement guess.
 

package/skills/service-itsm-teams-configure/references/azure-credential-population.md

@@ -2,19 +2,21 @@
 
 Reference for `service-itsm-teams-configure` Step 5. Once the org has an external credential named
 `MSTeamsSetupClientCredentialsEC` and the user has supplied their Azure **Client ID** and **Tenant
-ID** (non-secret identifiers, given in chat) and placed the **Client Secret** in the
-`TEAMS_ENTRA_CLIENT_SECRET` environment variable or a gitignored secret file (Step 4a — **never ask
-for the secret in chat**), these are the Salesforce-side writes that populate the outbound Graph
-credential, the inbound-SSO Auth Provider, and the portal-user access that make the Teams IT Service
-/ IT Desk apps actually work. Read the secret from that env var / file at write time; never print,
-echo, or log its value, and never send the literal `$TEAMS_ENTRA_CLIENT_SECRET` token to an API —
-always resolve it to its actual value first (see the Secret-substitution note in Step 2). Do all of
-these yourself — the user's manual responsibility ends at the Azure admin center.
+ID** (non-secret identifiers, given in chat) and written the **Client Secret** to a **gitignored
+secret file** via the Step 4a copy-paste command (**never ask for the secret in chat**; do NOT use an
+`export`-to-env-var route — an interactive `!`-prefix export runs in a different shell than the
+agent's tool calls, so the value never reaches the agent), these are the Salesforce-side writes that
+populate the outbound Graph credential, the inbound-SSO Auth Provider, and the portal-user access
+that make the Teams IT Service / IT Desk apps actually work. Read the secret from that file at write
+time (`cat <secret-file>` into an in-memory variable); never print, echo, or log its value, and never
+send a literal `$TEAMS_ENTRA_CLIENT_SECRET` token to an API — always resolve it to its actual value
+first (see the Secret-substitution note in Step 2). Do all of these yourself — the user's manual
+responsibility ends at the Azure admin center.
 
 ## Populating `MSTeamsSetupClientCredentialsEC` given a user-supplied client ID/secret
 
 **Once the user supplies the Client ID and Tenant ID (in chat) and the Client Secret is available in
-the `TEAMS_ENTRA_CLIENT_SECRET` env var / secret file (Step 4a — never in chat), write them into
+the gitignored secret file (Step 4a — never in chat), write them into
 Salesforce yourself via the calls below. Do not respond by telling the user to open Setup and enter
 the values manually — that defeats the purpose of this skill.** The user's manual responsibility
 ends at the Azure admin center (Step 4a); every Salesforce-side write, including this one, is this
@@ -32,16 +34,17 @@ skill's job.
    This endpoint is full-replace — GET the EC first and mutate, don't send a partial body.
 2. Set the principal's client ID + secret (both required together in one call; there is no
    partial-update path for just the client ID):
-   **Secret substitution — read this first.** `mcp__headless-360__dispatch` is a JSON API call, **not
-   a shell**: it does **not** expand `$TEAMS_ENTRA_CLIENT_SECRET`. Passing the literal string
-   `"$TEAMS_ENTRA_CLIENT_SECRET"` in the body stores that literal text as the OAuth client secret and
-   Graph authentication then fails after an apparently-successful configuration. You must resolve the
-   env var to its **actual value** and place that value into `clientSecret.value` at call time. Read it
-   with a **non-logging** read (e.g. a single `printenv TEAMS_ENTRA_CLIENT_SECRET` captured into an
-   in-memory variable, or read the secret file) — never `echo`/print it, never place the resolved
-   secret in any text you emit to the user or into a log, and never write it to disk. The `<secret
-   value read from $TEAMS_ENTRA_CLIENT_SECRET>` placeholder below denotes that resolved value, not a
-   literal to send:
+   **Secret substitution — read this first.** The credential API body is JSON, **not a shell**: it
+   does **not** expand any `$TEAMS_ENTRA_CLIENT_SECRET`-style token. Passing such a literal string in
+   the body stores that literal text as the OAuth client secret and Graph authentication then fails
+   after an apparently-successful configuration. You must read the secret's **actual value from the
+   gitignored secret file** (Step 4a) and place that value into `clientSecret.value` at call time. Do
+   it with a **non-logging** read — `cat <secret-file>` captured into an in-memory variable, or build
+   the JSON body with a small script that reads the file (as done for the `MSTeamsSetupClientCredentialsEC`
+   POST) — never `echo`/print it, never place the resolved secret in any text you emit to the user or
+   into a log, and delete any temp body file that held it immediately after the call. The `<secret
+   value read from the secret file>` placeholder below denotes that resolved value, not a literal to
+   send:
    ```text
    mcp__headless-360__dispatch(
      method: "POST",   // or PUT (update-credential) if credentials already exist for this principal
@@ -52,10 +55,10 @@ skill's job.
        "principalType": "NamedPrincipal",
        "authenticationProtocol": "OAuth",
        "authenticationProtocolVariant": "ClientCredentialsClientSecretBasic",
-       // clientSecret.value MUST be the resolved secret read from the TEAMS_ENTRA_CLIENT_SECRET env
-       // var / secret file — NOT the literal "$TEAMS_ENTRA_CLIENT_SECRET" token (dispatch does not
-       // expand shell variables). Resolve in memory via a non-logging read; never echo it.
-       "credentials": { "clientId": {"value": "<client id>"}, "clientSecret": {"value": "<secret value read from $TEAMS_ENTRA_CLIENT_SECRET>"} }
+       // clientSecret.value MUST be the actual secret read from the gitignored secret file (Step 4a)
+       // — NOT a literal "$TEAMS_ENTRA_CLIENT_SECRET" token (the JSON body does not expand variables).
+       // Read it in memory via a non-logging read (cat the file); never echo it.
+       "credentials": { "clientId": {"value": "<client id>"}, "clientSecret": {"value": "<secret value read from the secret file>"} }
      }
    )
    ```
@@ -73,7 +76,7 @@ Enabling the Teams feature also provisions a Microsoft-type **Auth Provider** na
 Consumer Secret, or endpoint URLs). This is the **inbound SSO** side — it authenticates employees
 logging into the Experience Cloud portal that the Teams IT Service app embeds. It is a *separate
 artifact* from the outbound-Graph `MSTeamsSetupClientCredentialsEC` Named Credential, but takes the
-**same three values** the user supplied (secret from the env var / file, never chat). Populate it automatically in the same pass — a previous run
+**same three values** the user supplied (secret read from the gitignored secret file, never chat). Populate it automatically in the same pass — a previous run
 of this skill forgot this step, leaving portal SSO login broken even though the Named Credential
 was configured.
 
@@ -90,7 +93,7 @@ deploy it (this sets every field, including the secret, with no UI):
 <AuthProvider xmlns="http://soap.sforce.com/2006/04/metadata">
     <authorizeUrl>https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/authorize</authorizeUrl>
     <consumerKey><CLIENT_ID></consumerKey>
-    <consumerSecret>${TEAMS_ENTRA_CLIENT_SECRET}</consumerSecret>
+    <consumerSecret>__SECRET_PLACEHOLDER__</consumerSecret>
     <defaultScopes>openid profile email offline_access https://graph.microsoft.com/.default</defaultScopes>
     <friendlyName>microsoft_auth_provider</friendlyName>
     <includeOrgIdInIdentifier>false</includeOrgIdInIdentifier>
@@ -106,9 +109,20 @@ sf project deploy start --source-dir force-app --target-org <org-alias>
 ```
 
 **Secret handling:** substitute `<TENANT_ID>` / `<CLIENT_ID>` (non-secret) directly, but inject the
-`<consumerSecret>` value from `$TEAMS_ENTRA_CLIENT_SECRET` at build time (e.g. `envsubst` into a
-gitignored temp copy under a scratch dir, deploy that, then delete it). **Never commit the populated
-file** and never echo the secret. The secret comes from the env var / secret file — not from chat.
+`<consumerSecret>` value **read from the gitignored secret file** (Step 4a) at build time into a
+gitignored temp copy under a scratch dir, deploy that, then delete the whole scratch dir. A verified
+non-logging way to do the substitution (the secret only ever lives in a transient shell var and the
+scratch file, never in emitted text):
+```bash
+# template has __SECRET_PLACEHOLDER__ where <consumerSecret> should be; <TENANT_ID>/<CLIENT_ID> already filled in
+SECRET="$(cat <secret-file>)" perl -pe 's/__SECRET_PLACEHOLDER__/$ENV{SECRET}/' template.xml \
+  > force-app/main/default/authproviders/microsoft_auth_provider.authprovider-meta.xml
+sf project deploy start --source-dir force-app --target-org <org-alias>
+rm -f force-app/main/default/authproviders/microsoft_auth_provider.authprovider-meta.xml   # shred secret-bearing file
+```
+**Never commit the populated file** and never echo the secret. The secret comes from the gitignored
+secret file — not from chat, and not from an env var (the interactive `!`-prefix export does not
+reach the agent's shell).
 
 Notes:
 - Use the **tenant-specific** `/…/<TENANT_ID>/oauth2/v2.0/…` endpoints, not `/common/` or

package/skills/service-itsm-teams-configure/references/gotchas.md

@@ -13,11 +13,10 @@ step as failed or retrying an enablement guess.
 | Azure redirect URI must be under the **Web** platform, not SPA | The `microsoft_auth_provider` Auth Provider is a **confidential client** (server-side token exchange using the ConsumerSecret). Azure rejects secret-based token requests against a redirect URI registered as **Single-page application (SPA)**. Symptom: login *appears* to start (Salesforce logs `LoginHistory` "Success" and mints `OauthToken` rows) but the callback fails at `.../services/authcallback/microsoft_auth_provider` with **`OAUTH_APPROVAL_ERROR_GENERIC`**. Fix (verified): register the callback URI under the Azure app's **Web** platform, not SPA. When emitting the callback URL to the user, always say **Web**. See the callback-URL note under "Populating the `microsoft_auth_provider` Auth Provider." |
 | Portal login "you don't have access to the Microsoft account in Salesforce" → Username must equal the MS email/UPN | A custom Apex registration handler **`MsTeamsItsmSSOHandler`** (Core `service-itsm-teams-impl`, bound to `microsoft_auth_provider`) resolves the signed-in Microsoft user by `SELECT Id FROM User WHERE Username = :data.email` — the **Microsoft `email`/UPN claim must exactly equal a Salesforce `User.Username`** (not `User.Email`, not `FederationIdentifier`); `canCreateUser` returns false (no JIT), and 0 or >1 matches both return null → login denied. **One handler serves BOTH the IT Service (Employee) and IT Desk (Fulfiller) apps.** Fix (verified): set the intended portal user's `Username` to the MS UPN (after confirming no duplicate) via `PATCH .../sobjects/User/<id>` `{"Username":"<ms-upn>"}`. See "Making a portal user resolvable..." under Step 5. |
 | Portal Connect API `API_DISABLED_FOR_ORG` / 403 → user needs API Enabled | The Teams IT Service (Employee) app calls Connect APIs on the embedded portal (e.g. `/connect/it-service/permissions/EmployeeApp`); without the **API Enabled** user permission these return `API_DISABLED_FOR_ORG` (403 in the Network tab) and the app fails to load data despite a successful login. The managed permission sets (`TeamsForEmployeeUser`, `EmployeeHubEmployeeUser`) don't grant `ApiEnabled` and **can't be edited** (managed-package: MDAPI retrieve "cannot be found", SObject PATCH "invalid record id"). Fix (verified): create + deploy a new **unmanaged** permission set with `ApiEnabled` only and assign it. **Do not add `ChatterInternalUser`** — the Unified Employee license forbids it (assignment fails "user license doesn't allow the permission: ChatterInternalUser"). See "Granting the portal user API Enabled..." under Step 5. |
-| Azure/Entra app registration + admin consent have no Salesforce API | Salesforce only exposes a consent URL via an internal Aura controller (no public REST contract) — the user must click through the Azure admin center themselves. Give them the exact steps in Step 4a rather than a vague pointer, and once they provide the Client ID/Tenant ID (in chat) with the Client Secret in the `TEAMS_ENTRA_CLIENT_SECRET` env var / secret file (**never request the secret in chat**), take over immediately and write the credential into Salesforce yourself (see "Populating `MSTeamsSetupClientCredentialsEC`..." under Step 5) — do not tell them to enter it manually in Setup. |
+| Azure/Entra app registration + admin consent have no Salesforce API | Salesforce only exposes a consent URL via an internal Aura controller (no public REST contract) — the user must click through the Azure admin center themselves. Give them the exact steps in Step 4a rather than a vague pointer, and once they provide the Client ID/Tenant ID (in chat) with the Client Secret written to a gitignored secret file via the Step 4a copy-paste command (**never request the secret in chat**; the `!`-prefix `export` route does not reach the agent's shell), take over immediately and write the credential into Salesforce yourself (see "Populating `MSTeamsSetupClientCredentialsEC`..." under Step 5) — do not tell them to enter it manually in Setup. |
 | Go page's real checklist order (verified from a live screenshot) | The "Integrate Salesforce with Teams" group on the feature's Go page has exactly 3 items, in this order: **Create Microsoft Entra ID App** → **Configure Setup Named Credentials** → **Grant Azure Administrator Consent**. This is a *separate* checklist group from "Set Up Salesforce IT Desk" / "Set Up Salesforce IT Service" (delegated to `service-itsm-teams-itdesk-configure` / `service-itsm-teams-itservice-configure`) — do not conflate the groups when reporting progress to the user. |
 | "Grant Azure Administrator Consent" consent link is static, not per-org | Clicking "Grant Consent" on the Go page opens a modal with this exact link: `https://login.microsoftonline.com/organizations/oauth2/v2.0/authorize?client_id=cd6bd63f-41ef-47cc-9465-86e986179a29&response_type=code&redirect_uri=https://salesforce.com&response_mode=query&scope=Organization.ReadWrite.All`. The `client_id` here is Salesforce's own multi-tenant Entra app (**not** the app the user registers in step 1, and **not** related to the Client ID/Secret that go into the Named Credential) — it requests `Organization.ReadWrite.All` from whichever Microsoft tenant the signed-in admin belongs to (`organizations` tenant segment, not a specific tenant ID). headless-360 has no operation that generates this link or reads the Go page's live checklist state (searched `discover` for "grant Azure administrator consent generate consent URL" and "guided setup checklist progress Salesforce Go" — no matching SOR) — paste the link above verbatim and tell the user to click it themselves, signed in as a Microsoft tenant admin. |
 | `preferredSite` / Teams extension registration **is** a public Connect API (verified) — corrects an earlier assumption | `POST /services/data/v67.0/connect/service-itsm-teams/graph-api/extensions` body `{"siteUrlPathPrefixes": ["<site urlPathPrefix>"]}` registers the Experience Cloud site as the Teams extension target; `PATCH .../extensions/{extensionId}` updates it. Verified live: it dispatches and reaches real logic (not a stub) — it fails with `400 UNKNOWN_EXCEPTION "We couldn't access the credential(s)... external credential \"MSTeamsSetupClientCredentialsEC\" might not exist"` until the Azure/Entra app registration is done and that named/external credential is wired up in Setup. Once the credential exists, call this to complete preferred-site selection — do not treat it as Aura-only. |
 | `service-itsm-teams-connect-api` SOR (headless-360 `discover`) | Also exposes `get-teams-get-teams-list`, `get-teams-get-channel-list`, `post-teams-channel-message-send`, `get-teams-get-permissions`, `get-service-itsm-teams-collaboration-app-settings` (valid `targetApplication` values are `TeamsFulfillerApp` / `TeamsEmployeeApp`, not `teams`) — useful for verifying end-to-end Teams connectivity after the manual tail is complete. |
-| `ms-teams-app-connect-api` (`/connect/ms-teams-app/tenant-config`) gates Step 5 and has **no known unlock path** | `GET`/`PUT`/`DELETE` all return `403 FUNCTIONALITY_NOT_ENABLED [MsTeamsAppApiFamily]`, even after `service-cloud-itsm-teams-integration` is enabled and `MSTeamsSetupClientCredentialsEC` is fully configured. **Verified this is the same blocker as Step 5's "Unable to fetch tenant ID" error** — `post-teams-extension`/`patch-teams-extension-update` internally depend on this tenant-config lookup. Checked and ruled out: (a) no Go feature-enablement API name unlocks it — tried `ms-teams-app`, `ms-teams-app-integration`, `microsoft-teams-app-integration`, `teams-app-connect-api`, `msteams-app-api`, `service-cloud-ms-teams-app-api`, `MsTeamsAppApiFamily` itself, all `400 NOT_FOUND "Could not find the requested feature"`; (b) no `PermissionSetLicense` among all 112 in the org grants it — only `TeamsForEmployeePsl`/`TeamsForITSrvcsPsl` relate to Teams, and neither gates this family. This appears to be a hard org/edition-level license gate with no self-service unlock via headless-360 — if a user hits this, Step 5 cannot be completed in this org; do not keep retrying enablement guesses. |
 | A `MSTeamsSetupAutomationAccess` ("Automate Microsoft Teams Setup") permission set also auto-provisions | Was unassigned in this session — assign it to the Setup admin driving this flow if further automation steps need it. (The IT Desk/IT Service checklist permission sets — `TeamsForITSrvcsUser`, `TeamsForEmployeeUser`, `MicrosoftGraphAccess` — are documented in the child skills.) |
 | Version prefix required | headless-360 `dispatch`/`dispatch_readonly` do not resolve API versions — always pass the full `/services/data/vXX.0/...` prefix. |

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

@@ -11,10 +11,6 @@ metadata:
     - "service-itsm-teams-employee-agent-configure"
     - "service-itsm-teams-itdesk-configure"
     - "service-itsm-teams-itservice-configure"
-  # No accessCheck gate: this orchestrator's Stage 1 is what enables ITSMTeamsEnabled,
-  # so it must be invokable on a brand-new org before that preference exists. Downstream
-  # child skills retain their own accessCheck. Empty array = applies to any org.
-  accessCheck: []
 allowed-tools: Read AskUserQuestion
 ---
 
@@ -43,9 +39,11 @@ There are exactly **three mandatory halts** and **one branch** in the whole flow
 - **HALT 1 — Azure/Entra app** (Stage 2): you give the user the app-registration instructions and
   **wait** for them to register the app and provide the credentials. No Salesforce API can do this.
   The **Client ID** and **Tenant ID** are non-secret identifiers and may be given in chat; the
-  **Client Secret is a confidential credential — NEVER ask for it in the conversation.** The user
-  places it in the `TEAMS_ENTRA_CLIENT_SECRET` environment variable (or a gitignored secret file the
-  agent is told the path to); the agent reads it from there and never prints, echoes, or logs it.
+  **Client Secret is a confidential credential — NEVER ask for it in the conversation.** The agent
+  gives the user one exact copy-paste command that writes the secret to a gitignored secret file
+  (`! umask 077; printf '%s' 'PASTE-SECRET' > <secret-file> && echo written`) and reads it from that
+  file. Keep the leading `!` — it runs the line in this session's Bash so the file persists. The agent
+  never prints, echoes, or logs the value.
 - **HALT 2 — IT Desk app install** (Stage 3): you give the Microsoft Marketplace link and **wait**
   for the user to reply **"installed"**. No API installs a Teams app into a tenant catalog.
 - **HALT 3 — IT Service app install** (Stage 4): same as HALT 2, for the IT Service app.
@@ -70,16 +68,17 @@ then continue straight into Stage 2 — do **not** stop here.
 
 ### Stage 2 — Microsoft Entra app + Named Credentials  ⟶ HALT 1
 Still within **`service-itsm-teams-configure`** (its Step 4a): give the user the exact Azure/Entra
-app-registration clicks **including the Microsoft Graph Application permissions** it lists, and
+app-registration clicks **including the Microsoft Graph permissions** it lists, and
 **HALT** until they provide the credentials. The **Client ID** and **Tenant ID** are non-secret
 identifiers — accept them in chat. The **Client Secret is confidential: never request it in the
-conversation.** Instruct the user to set it in the `TEAMS_ENTRA_CLIENT_SECRET` environment variable
-(or a gitignored secret file, and tell you the path); read it from there. Never print or echo it.
-The moment the identifiers are given and the secret is in the env/file:
+conversation.** Give the user one exact copy-paste command that writes it to a gitignored secret file
+(`! umask 077; printf '%s' 'PASTE-SECRET' > <secret-file> && echo written`) and read it from that
+file. Keep the leading `!` — it runs the line in this session's Bash so the file persists. Never
+print or echo it. The moment the identifiers are given and the secret is in the file:
 - Write those values into the `MSTeamsSetupClientCredentialsEC` Named Credential **and** the
   `microsoft_auth_provider` Auth Provider **yourself, via API — nothing manual** (the child skill's
-  Step 5 and its azure-credential-population reference carry the exact API bodies). Reference the
-  secret by its env var / file path in the API call — do not inline the raw value into any logged text.
+  Step 5 and its azure-credential-population reference carry the exact API bodies). Read the
+  secret from the file at call time — do not inline the raw value into any logged text.
 - Give the user the static **Grant Admin Consent** link and register the preferred site (child Step 5).
 Then continue to Stage 3 automatically.
 
@@ -87,8 +86,8 @@ Then continue to Stage 3 automatically.
 Invoke **`service-itsm-teams-itdesk-configure`**. Drive its whole checklist:
 - Turn on the `OrgHasITSMFulfillerTeams` org preference (via API).
 - **Manage User Access** — assign the fulfiller permission sets to the confirmed user(s):
-  `TeamsForITSrvcsUser` + `MicrosoftGraphAccess`, **plus `Teams_Employee_ApiAccess`** (the ECA-
-  pre-authorized set that also grants **API Enabled** — required for login, not optional).
+  `TeamsForITSrvcsUser` + `MicrosoftGraphAccess`, **plus the API Enabled login permission set**
+  (commonly `Teams_Employee_ApiAccess`) — required for login, not optional.
 - **Turn on Swarming** — this stage includes `service-itsm-swarming-configure`
   (enables `service-cloud-swarming` and sets `SWARM_COLLABORATION_TOOL = "Teams"`).
 - Give the **IT Desk Microsoft Marketplace link** + help doc, tell the user **the Azure account
@@ -98,9 +97,9 @@ Invoke **`service-itsm-teams-itdesk-configure`**. Drive its whole checklist:
 ### Stage 4 — Set up IT Service (employee side)  ⟶ HALT 3
 Invoke **`service-itsm-teams-itservice-configure`**. Drive its whole checklist:
 - Turn on the `OrgHasEmployeeServiceTeams` org preference (via API).
-- **Manage User Access** — assign the employee permission sets to the confirmed UEL user(s):
-  `TeamsForEmployeeUser` + `MicrosoftGraphAccess`, **plus the API Enabled + ECA-authorized access**
-  the child's login prerequisites require.
+- **Manage User Access** — assign the employee permission set to the confirmed UEL user(s):
+  `TeamsForEmployeeUser` (the dialog assigns only this one — **not** `MicrosoftGraphAccess`), **plus
+  the API Enabled login permission set** the child's login prerequisites require.
 - **Select the Digital Experience Site** (`SLACK_PREFERRED_SITE`) via API.
 - Give the **IT Service Microsoft Marketplace link** + help doc, repeat the **email-must-match** note,
   and **HALT** until the user replies **"installed."** Then continue to Stage 5.
@@ -133,6 +132,11 @@ portal user. Then tell the user to **retest from a brand-new Teams chat** to con
   the Entra app is unregistered, or a halt awaiting "installed"), keep that stage **`Blocked`/waiting**
   and hold at the halt — do not mark it done and do not skip ahead.
 - Do not re-present a menu. State what just finished and what you're doing next, then do it.
+- **Keep the report tight — summarize, don't transcribe.** Report each stage as a one-line status in
+  the stage-progress table plus at most a short sentence of context; do **not** paste the child skill's
+  API request/response bodies, tool-call logs, or step-by-step internals into the report — that detail
+  lives in the child skill, and re-narrating it here is the single biggest source of a bloated,
+  low-signal report. The reader needs *what happened and what's next*, not a replay of every call.
 
 ## Completion summary
 

package/skills/service-itsm-teams-coordinate/examples/output-templates.md

@@ -26,10 +26,12 @@ Microsoft Teams for ITSM Setup (via service-itsm-teams-coordinate)
 │ 8 │ Build IT Service embedded agent (optional) │ Not started          │
 └───┴────────────────────────────────────────────┴──────────────────────┘
 
-Next: send me the Azure app's Client ID and Tenant ID, and put the Client Secret in the
-TEAMS_ENTRA_CLIENT_SECRET environment variable (or a secret file — tell me the path). Don't paste
-the secret here. I'll read it from there and write everything into the Named Credential and Auth
-Provider automatically.
+Next: send me the Azure app's Client ID and Tenant ID here. For the Client Secret, DON'T paste it in
+chat — instead copy-paste this one command into the prompt (put your secret's Value between the
+single quotes), then tell me it's done:
+  ! umask 077; printf '%s' 'PASTE-CLIENT-SECRET-HERE' > <secret-file> && echo written
+I'll read it from that file and write everything into the Named Credential and Auth Provider
+automatically.
 ```
 
 Status values: `Not started`, `In progress`, `Waiting (<what for>)`, `Blocked`, `Done`.
@@ -37,11 +39,12 @@ Status values: `Not started`, `In progress`, `Waiting (<what for>)`, `Blocked`,
 ## Halt messages
 
 - **HALT 1 (Stage 2 — Azure/Entra app):** deliver the child's app-registration instructions
-  (including the Microsoft Graph Application permissions) and end with: *"Send me the **Client ID**
-  and **Tenant ID** here, and put the **Client Secret** in the `TEAMS_ENTRA_CLIENT_SECRET`
-  environment variable (or a secret file — tell me the path). Please don't paste the secret in chat.
-  I'll read it from there and populate the Named Credential and Auth Provider automatically — no
-  manual Setup entry needed."* Then wait.
+  (including the Microsoft Graph permissions) and end with: *"Send me the **Client ID**
+  and **Tenant ID** here. For the **Client Secret**, please don't paste it in chat — copy-paste this
+  one command into the prompt with your secret's Value between the single quotes, then tell me it's
+  done: `! umask 077; printf '%s' 'PASTE-CLIENT-SECRET-HERE' > <secret-file> && echo written`. I'll
+  read it from that file and populate the Named Credential and Auth Provider automatically — no
+  manual Setup entry needed."* (Substitute the real job/temp path for `<secret-file>`.) Then wait.
 - **HALT 2 / HALT 3 (Stages 3 & 4 — app install):** deliver the Microsoft Marketplace link + help
   doc, then: *"Install the app in your Microsoft Teams admin center, then reply **installed** and
   I'll continue. Note: the Azure/Microsoft email the user signs in with must match that Salesforce

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

@@ -36,8 +36,9 @@ dispatches through **headless-360**.
 
 - **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`.
+  `TeamsForITSrvcsUser`/`MicrosoftGraphAccess` permission sets to confirmed users **plus
+  provisioning the org-wide API-Enabled login permission set** (created once, required to sign in);
+  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
@@ -103,6 +104,17 @@ live from the "Manage Microsoft Teams for Employee Service User Access" dialog:
 - `MicrosoftGraphAccess` (label **"MicrosoftGraphAccess"**) — assigned alongside it in the same
   dialog.
 
+**A third, "login" permission set is also required — one you provision once per org.** The two
+dialog permsets provision the IT Desk *surface* but **do not let the fulfiller sign in**: both read
+`PermissionsApiEnabled = false`, so the embedded app's Connect calls 403 and login fails with
+"server not reachable." The fulfiller needs a permission set carrying the **API Enabled** system
+permission. Some orgs already have one named `Teams_Employee_ApiAccess` (a **custom** permset — do
+**not** assume a fresh customer org has it); otherwise create it. It is a **shared, org-wide
+artifact** — the same permset also covers IT Service login, so **create it only once** and just
+*assign* it wherever needed. The resolve-or-create-then-assign recipe is in
+[Login prerequisite](#login-prerequisite--provision-the-login-permission-set-verified) below. Do
+this as part of this step; don't wait for login to break.
+
 **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
@@ -125,8 +137,9 @@ still want one assigned — but call out which rows look like system accounts so
 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):
+Once the user confirms specific user(s), look up the two dialog permission sets' `Id`s (they are
+stable per org but don't hardcode them — query fresh; the third "login" permset is resolved in the
+Login prerequisite below):
 
 ```text
 mcp__headless-360__dispatch_readonly(
@@ -152,46 +165,49 @@ Verify by re-querying `PermissionSetAssignment` for that `AssigneeId`, or simply
 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
+#### Login prerequisite — provision the login permission set (verified)
+
+With only `TeamsForITSrvcsUser` + `MicrosoftGraphAccess` the IT Desk *surface* is provisioned, but a
+fulfiller who opens the IT Desk app in Teams hits **"server not reachable"** on the login page. The
+verified blocker is **API Enabled**: both dialog permsets read `PermissionsApiEnabled = false`
+(verified live), so the embedded app's Connect calls 403. Assigning the fulfiller a permission set
+with `PermissionsApiEnabled = true` resolves the login. That permset is **org-wide, created once**
+and shared with IT Service — resolve-or-create, then assign:
+
+1. **Reuse if it already exists** (an API-Enabled permset — commonly `Teams_Employee_ApiAccess`):
+   `SELECT Id, Name, PermissionsApiEnabled FROM PermissionSet WHERE Name = 'Teams_Employee_ApiAccess'`.
+   If found with `PermissionsApiEnabled = true`, take its `Id` and skip to step 3.
+2. **Otherwise create it once** (`PermissionsApiEnabled` is createable — verified):
+   ```text
+   mcp__headless-360__dispatch(
+     method: "POST",
+     url:    "/services/data/v67.0/sobjects/PermissionSet",
+     body:   { "Name": "Teams_Employee_ApiAccess", "Label": "Teams Employee API Access", "PermissionsApiEnabled": true }
+   )
+   ```
+   Capture the returned `Id`. Because it's shared org-wide, don't recreate it if a later run (or the
+   IT Service skill) already made it — step 1's query is the guard.
+3. **Assign it** to each confirmed fulfiller, alongside the two dialog permsets:
+   ```text
+   mcp__headless-360__dispatch(
+     method: "POST",
+     url:    "/services/data/v67.0/sobjects/PermissionSetAssignment",
+     body:   { "AssigneeId": "<user id>", "PermissionSetId": "<login permset Id>" }
+   )
+   ```
+
+After assigning, have the user **fully close and reopen the Teams app** (the OAuth 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`).
+
+The `ServiceCloudMSTeamsEca` External Client App that backs Teams login is **auto-installed by the
+Go-page toggle and needs no configuration** — `Teams_Employee_ApiAccess` grants API Enabled and is
+unrelated to the ECA. Do not add `SetupEntityAccess` rows or change the ECA's OAuth policy.
+
+If login still fails in a fresh session after the API-Enabled 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.
+See `service-itsm-teams-itservice-configure`'s *Login prerequisites* for the full pass/fail
+diagnostic chain.
 
 ### Step 4 — Set Teams as Collaboration Tool for Swarming (delegate)
 
@@ -217,7 +233,7 @@ is now fully automated end-to-end, no manual "Go to Feature Page" click required
 | `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). |
+| Manage-User-Access permsets don't cover login — assign an API-Enabled permset | Verified: after assigning `TeamsForITSrvcsUser` + `MicrosoftGraphAccess`, the IT Desk agent still failed Teams login with **"server not reachable"** — both dialog permsets have `PermissionsApiEnabled = false`, so the embedded app's Connect calls 403. The fix is an **API-Enabled** permission set (`PermissionsApiEnabled = true`), commonly `Teams_Employee_ApiAccess` — a **custom, org-wide** permset shared with IT Service, so **create it once** then assign. A test org may already have it; **a fresh customer org won't**, so resolve-or-create. (The `ServiceCloudMSTeamsEca` ECA is auto-installed by the Go-page toggle and needs no configuration — it does not gate login and `Teams_Employee_ApiAccess` is unrelated to it.) See [Step 3 → Login prerequisite](#login-prerequisite--provision-the-login-permission-set-verified). |
 | Version prefix required | headless-360 `dispatch`/`dispatch_readonly` do not resolve API versions — always pass the full `/services/data/vXX.0/...` prefix. |
 
 ---