@salesforce/afv-skills 1.37.0 → 1.38.0

package/skills/experience-ui-bundle-deploy/SKILL.md

@@ -1,10 +1,11 @@
 ---
 name: experience-ui-bundle-deploy
-description: "MUST activate when the project contains a uiBundles/*/src/ directory and the task involves deploying, pushing to an org, or post-deploy org setup. Use this skill to deploy a UI bundle app to a Salesforce org and run the full ordered setup: org authentication, pre-deploy build, metadata deploy, permission-set assignment, role assignment, Experience Cloud self-registration, seed-data import, and GraphQL schema fetch plus codegen. Activate when a uiBundles/ project also has files like *.network-meta.xml, org-setup.config.json, a data-plan.json in the data/ dir, or sfdx-project.json and the user mentions deploying, pushing, org setup, or post-deploy tasks. DO NOT TRIGGER when: creating a new UI bundle project from scratch (use experience-ui-bundle-project-generate); styling or editing pages in an existing app without deploying (use experience-ui-bundle-frontend-generate); adding a specific feature such as auth, search, or file upload without deploying (use the matching experience-ui-bundle-*-generate skill)."
+description: "MUST activate when the project has a uiBundles/*/src/ directory and the task involves deploying to an org or post-deploy org setup. Deploys a UI bundle app and runs ordered setup: org auth, build, metadata deploy, permission-set and role assignment, Experience Cloud self-registration, social login / SSO / IDP linking (Auth Providers + SAML SSO configs on a React site), seed-data import, and GraphQL schema fetch + codegen. Trigger signals: *.network-meta.xml, org-setup.config.json (with a socialLogin block), data-plan.json, sfdx-project.json, or mentions of deploy, org setup, or social login / SSO / IDP linking on an Experience site. DO NOT TRIGGER when: creating a new UI bundle project (use experience-ui-bundle-project-generate); styling pages without deploying (use experience-ui-bundle-frontend-generate); adding a feature such as auth, search, or file upload without deploying (use the matching experience-ui-bundle-*-generate skill); configuring MFA permission sets (use experience-ui-bundle-mfa-configure)."
 metadata:
-  version: "1.1"
+  version: "1.2"
   relatedSkills:
     - "experience-ui-bundle-frontend-generate"
+    - "experience-ui-bundle-mfa-configure"
     - "experience-ui-bundle-project-generate"
   cliTools:
     - tool: ["jq"]
@@ -43,10 +44,11 @@ Read these from the project; **ask the user** only for what's missing:
   source dir from `sfdx-project.json` (`packageDirectories[0].path` + `/main/default`).
   It exits non-zero if the project file is missing or malformed. Never hardcode
   `force-app/main/default`.
-- **`org-setup.config.json`** (optional) — drives permset assignment, role, and
-  self-registration. Absent keys mean "skip that step". **Exception:** if the
-  file is missing but `permissionsets/` has permsets to assign, don't silently
-  skip — scaffold the config or gather equivalent inputs (see step 4).
+- **`org-setup.config.json`** (optional) — drives permset assignment, role,
+  self-registration, and social login. Absent keys mean "skip that step".
+  **Exception:** if the file is missing but `permissionsets/` has permsets to
+  assign, don't silently skip — scaffold the config or gather equivalent inputs
+  (see step 4).
 - **`data-plan.json`** (optional, in the project's `data/` dir) — presence enables the data step.
 
 ## Step 1 — Org authentication (always)
@@ -168,6 +170,67 @@ running.** Sequence (full detail in `references/self-registration.md`):
    `assets/network-selfreg.apex` (idempotent; both are query-then-create; run 4a
    and 4b as two separate `sf apex run` invocations).
 
+## Step 6b — Enable social login (config-gated)
+
+Run only when `org-setup.config.json` has a `socialLogin` block. If the block is
+absent, `loadSocialLoginConfig` returns null and the step is hidden — no-op
+cleanly and say so. This step is **non-destructive and idempotent** (it only adds
+missing links/members), so — unlike self-registration and data import — it does
+**not** require asking first.
+
+This links the site's configured **Auth Providers** (OAuth) and **SAML SSO
+configs** to the site so the built-in Social Login component renders their
+buttons on the React login page. On React (Site Container) sites the SSO admin UI
+is hidden, so the linking is done programmatically via `AuthConfig` /
+`AuthConfigProviders` records — you cannot do it by clicking through Setup. Full
+detail, sub-steps, and port-provenance: `references/social-login.md`.
+
+Config shape (see `references/config-scaffold.md` for the full schema):
+
+```json
+{ "socialLogin": {
+    "communityMemberProfile": "Customer Community User",
+    "authProviderNames": ["Google", "My_SAML_Provider"],
+    "communityUserPermset": "myapp_Guest_User_Api_Access"
+} }
+```
+
+Sequence (mirrors reference `org-setup.mjs` `main()` social-login step, which runs
+**after** self-registration and **before** the data/GraphQL steps):
+
+Apply the `assets/` templates **verbatim** (like the self-reg/data steps) — full
+runnable commands for each sub-step are in `references/social-login.md`:
+
+1. **Derive the site** — run `scripts/derive-site-name.sh` (single
+   `*.network-meta.xml`; stop if zero/ambiguous). Social login needs the site to
+   resolve its `AuthConfig`.
+2. **Enable "Allow standard external profiles"** — deploy
+   `assets/Communities.settings-meta.xml` via Metadata API (from a throwaway
+   minimal project; see the reference). Required so the SSO registration handler
+   can create users on standard community profiles; without it auth providers fail
+   user insert with `FIELD_INTEGRITY_EXCEPTION`. A "already active" warning is a
+   non-fatal skip.
+3. **Link Auth Providers to the site `AuthConfig`** — run
+   `assets/social-login-auth-providers.apex` verbatim (substitute `<siteName>`,
+   `<ProviderNamesList>`, `<ApiVersion>`) to create the missing
+   `AuthConfigProviders` junctions, then read its `|DEBUG|` lines (table in the
+   reference). All-or-nothing: if any configured `authProviderNames` entry has no
+   matching `AuthProvider` (OAuth) or `SamlSsoConfig` (SAML) record, it emits
+   `MISSING_PROVIDERS` and links nothing — create/fix them in Setup first.
+   Already-linked providers are skipped (idempotent).
+4. **Add the community member profile to `NetworkMemberGroup`** — resolve the
+   Network + Profile Ids and create the membership if absent (`sf data` commands in
+   the reference). Without it, SSO-registered users hit `NO_ACCESS: User was not
+   authorized for the community`.
+5. **(Optional) Assign `communityUserPermset` to community users** — only when
+   configured. Grants `ApiEnabled` so `getCurrentUser()` (`/chatter/users/me`)
+   works for SSO-created users.
+
+> **IMPORTANT:** A `socialLogin` block present but skipped is a silent-failure
+> trap — the app deploys fine, but no social-login buttons ever appear on the
+> login page and there is no error explaining why. Do not silently skip: run the
+> step when the block is present, or state clearly that it was absent.
+
 ## Step 7 — Data import (presence-driven) — ask first
 
 Run `scripts/find-data-plan.sh` first. If it exits non-zero, **skip this step** —
@@ -211,9 +274,10 @@ that changes objects, fields, or permissions.
 
 ## Done
 
-Setup ends here — the 8 steps above are the complete sequence. Local dev preview
-(`npm run dev:preview`) is a separate developer action, not part of setup; if the
-user asks to preview the site, see `references/dev-preview.md`.
+Setup ends here — the steps above (including the config-gated 6b social login)
+are the complete sequence. Local dev preview (`npm run dev:preview`) is a separate
+developer action, not part of setup; if the user asks to preview the site, see
+`references/dev-preview.md`.
 
 ## Critical rules
 
@@ -222,14 +286,18 @@ user asks to preview the site, see `references/dev-preview.md`.
 - Assign permissions **before** schema fetch — the caller may lack FLS otherwise.
 - Re-run schema fetch + codegen **after every** metadata deploy that changes
   objects, fields, or permissions.
-- Never silently skip permission assignment, self-registration, or data import —
-  either the convention file is present (run it, asking first for the destructive
-  ones) or it's absent (skip cleanly and say so).
+- Never silently skip permission assignment, self-registration, social login, or
+  data import — either the convention file/config block is present (run it, asking
+  first for the destructive ones) or it's absent (skip cleanly and say so). A
+  present-but-skipped `socialLogin` block means no login buttons appear with no
+  error to explain it.
 - Discover the source path from `sfdx-project.json`; never hardcode
   `force-app/main/default`.
 - Apply the `assets/` Apex and XML templates **verbatim** — they encode
-  duplicate-rule bypass, `allOrNone=false` deletes, idempotency, and SOQL-safety
-  that are easy to get wrong by hand.
+  duplicate-rule bypass, `allOrNone=false` deletes, idempotency, SOQL-safety, and
+  (for social login) the all-or-nothing provider pre-check and the
+  DML-not-allowed-on-`AuthConfigProviders` REST-callout insert — all easy to get
+  wrong by hand.
 
 ## Interaction order (summary)
 
@@ -239,5 +307,6 @@ user asks to preview the site, see `references/dev-preview.md`.
 4. Assign permission sets (config-driven assignee)
 5. Assign role (if configured)
 6. Enable self-registration (if configured — ask first)
+6b. Enable social login (if `socialLogin` configured — idempotent, no ask needed)
 7. Import data (if data plan exists — ask first)
 8. Fetch GraphQL schema + codegen + final build

package/skills/experience-ui-bundle-deploy/assets/Communities.settings-meta.xml

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Enables the "Allow using standard external profiles for self-registration,
+  user creation, and login" org setting (field enableOotbProfExtUserOpsEnable).
+
+  Ported VERBATIM from reference org-setup.mjs enableExternalProfiles (lines
+  581-586). Required so SSO registration handlers can create users on standard
+  community profiles (e.g. "Customer Community User"); without it, auth providers
+  fail user insert with FIELD_INTEGRITY_EXCEPTION.
+
+  This is sub-step 1 of SKILL.md step 6b. Deploy this file via Metadata API
+  (the REST/Tooling approaches fail on many org types). See
+  references/social-login.md for the exact deploy invocation and the throwaway
+  minimal-project layout it needs. If the deploy warns that the setting is
+  already active, treat it as a non-fatal skip.
+-->
+<CommunitiesSettings xmlns="http://soap.sforce.com/2006/04/metadata">
+    <enableOotbProfExtUserOpsEnable>true</enableOotbProfExtUserOpsEnable>
+</CommunitiesSettings>

package/skills/experience-ui-bundle-deploy/assets/org-setup.config.template.json

@@ -13,5 +13,10 @@
   "selfRegistration": {
     "selfRegProfile": "<Profile API name>",
     "accountName": "<display name>"
+  },
+  "socialLogin": {
+    "communityMemberProfile": "<Profile name, e.g. Customer Community User>",
+    "authProviderNames": ["<AuthProvider or SamlSsoConfig DeveloperName>"],
+    "communityUserPermset": "<PermissionSet API name (optional)>"
   }
 }

package/skills/experience-ui-bundle-deploy/assets/social-login-auth-providers.apex

@@ -0,0 +1,158 @@
+/*
+ * Anonymous Apex — link Auth Providers (OAuth + SAML) to a site's AuthConfig
+ * by creating AuthConfigProviders junction records (idempotent, all-or-nothing).
+ *
+ * Ported VERBATIM from reference org-setup.mjs enableAuthProvidersForSite
+ * (the generated `apex` template, lines 650-772). Apply this template as-is; do
+ * NOT invent your own AuthConfigProviders Apex — DML is not allowed on
+ * AuthConfigProviders, the linking must be an HTTP callout to the REST API, and
+ * the all-or-nothing failure check must run BEFORE any junction is created. These
+ * are easy to get wrong by hand.
+ *
+ * This is sub-step 2 of SKILL.md step 6b. It runs as a SINGLE `sf apex run`
+ * invocation. See references/social-login.md for how to read the |DEBUG| output
+ * lines this emits (AUTHCONFIG_FOUND / MISSING_PROVIDERS / INSERTED / etc.).
+ *
+ * Why programmatic: React (Site Container) sites hide the SSO admin UI, so
+ * providers cannot be linked via Setup -> Digital Experiences -> Login &
+ * Registration. AuthConfig.AuthOptionsAuthProvider auto-flips to true when the
+ * junctions are inserted — no separate update needed.
+ *
+ * PLACEHOLDERS — substitute before running:
+ *   <siteName>            = the derived site name (base name of the single
+ *                          networks/<siteName>.network-meta.xml). Used in the
+ *                          AuthConfig.Url LIKE match and the log header.
+ *   <ProviderNamesList>   = the socialLogin.authProviderNames values as a
+ *                          comma-separated Apex string-literal list, e.g.
+ *                          'Google', 'My_SAML_Provider'. Each name MUST be
+ *                          validated against the SOQL-name whitelist first
+ *                          (reject any value containing ' \ or a control char —
+ *                          same guard the permset/self-reg paths use) and then
+ *                          single-quoted. This exact literal is used in BOTH the
+ *                          `DeveloperName IN (...)` clauses AND the requested-name
+ *                          loop below; keep them identical.
+ *   <ApiVersion>         = REST API version for the callout endpoint (e.g. 62.0).
+ */
+
+// Enable Auth Providers (OAuth + SAML) for community "<siteName>"
+Http http = new Http();
+String baseUrl = Url.getOrgDomainUrl().toExternalForm();
+String token = UserInfo.getSessionId();
+
+// Step 1: Find the AuthConfig for this site
+List<AuthConfig> authConfigs = [
+    SELECT Id, Url
+    FROM AuthConfig
+    WHERE Url LIKE '%<siteName>%'
+    LIMIT 1
+];
+if (authConfigs.isEmpty()) {
+    System.debug('ERROR_NO_AUTHCONFIG');
+    return;
+}
+AuthConfig ac = authConfigs[0];
+System.debug('AUTHCONFIG_FOUND:' + ac.Id + ':' + ac.Url);
+
+// Step 2: Query AuthProvider records by DeveloperName (OAuth providers)
+List<AuthProvider> oauthProviders = [
+    SELECT Id, DeveloperName, FriendlyName
+    FROM AuthProvider
+    WHERE DeveloperName IN (<ProviderNamesList>)
+];
+System.debug('OAUTH_PROVIDERS_FOUND:' + oauthProviders.size());
+
+// Step 3: Query SamlSsoConfig records by DeveloperName (SAML providers)
+List<SamlSsoConfig> samlProviders = [
+    SELECT Id, DeveloperName
+    FROM SamlSsoConfig
+    WHERE DeveloperName IN (<ProviderNamesList>)
+];
+System.debug('SAML_PROVIDERS_FOUND:' + samlProviders.size());
+
+// Combine both into a unified list with (Id, DeveloperName, Type)
+List<Map<String, String>> allProviders = new List<Map<String, String>>();
+for (AuthProvider ap : oauthProviders) {
+    allProviders.add(new Map<String, String>{
+        'Id' => ap.Id,
+        'DeveloperName' => ap.DeveloperName,
+        'Type' => 'OAuth'
+    });
+}
+for (SamlSsoConfig sp : samlProviders) {
+    allProviders.add(new Map<String, String>{
+        'Id' => sp.Id,
+        'DeveloperName' => sp.DeveloperName,
+        'Type' => 'SAML'
+    });
+}
+
+if (allProviders.isEmpty()) {
+    System.debug('ERROR_NO_PROVIDERS');
+    return;
+}
+System.debug('TOTAL_PROVIDERS_FOUND:' + allProviders.size());
+
+// Fail fast if any requested provider name did not resolve to an AuthProvider
+// (OAuth) or SamlSsoConfig (SAML) record. The isEmpty() check above only catches
+// the case where NONE resolve; comparing the found DeveloperNames against the
+// requested list also catches the strict-subset case (e.g. ["Google","Typo"]
+// links Google but must not silently drop "Typo"). This runs BEFORE any junction
+// record is created, so linking is all-or-nothing. Case-insensitive because SOQL
+// "DeveloperName IN (...)" matches case-insensitively, so a stored DeveloperName
+// may differ in case from the configured value and must not read as "missing".
+Set<String> foundProviderNames = new Set<String>();
+for (AuthProvider ap : oauthProviders) {
+    foundProviderNames.add(ap.DeveloperName.toLowerCase());
+}
+for (SamlSsoConfig sp : samlProviders) {
+    foundProviderNames.add(sp.DeveloperName.toLowerCase());
+}
+List<String> missingProviderNames = new List<String>();
+for (String requestedName : new List<String>{<ProviderNamesList>}) {
+    if (!foundProviderNames.contains(requestedName.toLowerCase())) {
+        missingProviderNames.add(requestedName);
+    }
+}
+if (!missingProviderNames.isEmpty()) {
+    System.debug('MISSING_PROVIDERS:' + String.join(missingProviderNames, ','));
+    return;
+}
+
+// Step 4: Check existing AuthConfigProviders to avoid duplicates
+Set<Id> existingProviderIds = new Set<Id>();
+for (AuthConfigProviders acp : [
+    SELECT AuthProviderId FROM AuthConfigProviders WHERE AuthConfigId = :ac.Id
+]) {
+    existingProviderIds.add(acp.AuthProviderId);
+}
+
+// Step 5: Create missing junction records via REST API
+Integer inserted = 0;
+for (Map<String, String> provider : allProviders) {
+    String providerId = provider.get('Id');
+    String providerName = provider.get('DeveloperName');
+    String providerType = provider.get('Type');
+
+    if (existingProviderIds.contains(providerId)) {
+        System.debug('ALREADY_LINKED:' + providerName + ':' + providerType);
+        continue;
+    }
+    HttpRequest req = new HttpRequest();
+    req.setEndpoint(baseUrl + '/services/data/v<ApiVersion>/sobjects/AuthConfigProviders');
+    req.setMethod('POST');
+    req.setHeader('Authorization', 'Bearer ' + token);
+    req.setHeader('Content-Type', 'application/json');
+    req.setBody('{"AuthConfigId":"' + ac.Id + '","AuthProviderId":"' + providerId + '"}');
+    HttpResponse res = http.send(req);
+    if (res.getStatusCode() == 201 || res.getStatusCode() == 200) {
+        System.debug('INSERTED:' + providerName + ':' + providerType);
+        inserted++;
+    } else {
+        System.debug('INSERT_FAILED:' + providerName + ':' + providerType + ':' + res.getStatusCode() + ':' + res.getBody());
+    }
+}
+if (inserted == 0 && existingProviderIds.size() >= allProviders.size()) {
+    System.debug('ALL_ALREADY_LINKED');
+} else {
+    System.debug('TOTAL_INSERTED:' + inserted);
+}

package/skills/experience-ui-bundle-deploy/references/config-scaffold.md

@@ -32,7 +32,10 @@ Every top-level key is optional; each object is strict (no extra keys).
   },
   "role": { "assignee": "currentUser", "roleName": "<UserRole name>" },
   "selfRegistration": { "selfRegProfile": "<Profile API name>",
-                        "accountName": "<display name>" }
+                        "accountName": "<display name>" },
+  "socialLogin": { "communityMemberProfile": "<Profile name>",
+                   "authProviderNames": ["<DeveloperName>", "..."],
+                   "communityUserPermset": "<PermissionSet API name>" }
 }
 ```
 
@@ -48,6 +51,15 @@ Every top-level key is optional; each object is strict (no extra keys).
   `roleName` is a non-empty `UserRole` name.
 - **`selfRegistration`** has no license field — the required license is derived
   from `selfRegProfile` (see `references/license-checks.md`).
+- **`socialLogin`** drives step 6b. `communityMemberProfile` (required) is the
+  profile added to `NetworkMemberGroup` so SSO-registered users can access the
+  site. `authProviderNames` (required, non-empty) are the **DeveloperNames** of
+  `AuthProvider` (OAuth) or `SamlSsoConfig` (SAML) records to link to the site's
+  `AuthConfig`. `communityUserPermset` (optional) is assigned to SSO-created
+  community users so `getCurrentUser()` works (needs `ApiEnabled`). Like
+  `selfRegistration`, there is **no `siteName`** — the site is derived from the
+  single `networks/<siteName>.network-meta.xml`. Full step detail:
+  `references/social-login.md`.
 
 ## Scaffolding flow (permset folder present, config missing)
 

package/skills/experience-ui-bundle-deploy/references/social-login.md

@@ -0,0 +1,179 @@
+# Social login — auth-provider linking, external profiles, community access
+
+Detail for the **socialLogin** step (SKILL.md step 6b). Source of truth: reference
+`org-setup.mjs` `loadSocialLoginConfig` (547-555), `enableExternalProfiles`
+(569-617), `enableAuthProvidersForSite` (638-833), `addCommunityMemberProfile`
+(847-917), `assignPermsetToCommunityUsers` (929-991), and the `main()` social-login
+step (2124-2168). Config schema: `org-setup-config-schema.mjs` (65-81, strict).
+
+Verbatim assets this step applies (do not hand-write — parity with the self-reg /
+data steps): `assets/Communities.settings-meta.xml` (sub-step 1) and
+`assets/social-login-auth-providers.apex` (sub-step 2). Sub-steps 3–4 are plain
+`sf data query`/`create record` calls, given below.
+
+Run this step **only** when `socialLogin` is configured in `org-setup.config.json`.
+If the block is absent, `loadSocialLoginConfig` returns null and the step is hidden
+— no-op cleanly. Unlike self-registration and data import, this step is
+**non-destructive and idempotent**, so it does **not** require asking first.
+
+## Why this is programmatic (not a Setup click-path)
+
+On React (Site Container) Experience sites the SSO admin UI is hidden, so auth
+providers cannot be linked to the site by clicking through Setup → Login &
+Registration. The linking is done by creating `AuthConfigProviders` junction
+records that tie each `AuthProvider`/`SamlSsoConfig` to the site's `AuthConfig`.
+DML is not allowed on `AuthConfigProviders`, so the linking is done via Anonymous
+Apex issuing REST callouts — shipped verbatim as
+`assets/social-login-auth-providers.apex` (ported from `enableAuthProvidersForSite`,
+638-833). `AuthConfig.AuthOptionsAuthProvider` auto-flips to true when the
+junctions are inserted — no separate update needed.
+
+Apply the `assets/` templates **verbatim**, exactly like the self-reg and data
+steps — the Apex encodes the all-or-nothing pre-check, REST-callout insert
+(DML-not-allowed workaround), and idempotency that are easy to get wrong by hand.
+Do NOT invent your own social-login Apex.
+
+Once linked, the site's built-in Social Login component (shipped in 264) renders a
+button per configured provider on the React login page.
+
+## Config shape
+
+```json
+{ "socialLogin": {
+    "communityMemberProfile": "Customer Community User",
+    "authProviderNames": ["Google", "My_SAML_Provider"],
+    "communityUserPermset": "myapp_Guest_User_Api_Access"
+} }
+```
+
+- **`communityMemberProfile`** (required) — profile added to
+  `NetworkMemberGroup` so SSO-registered users can access the community. Also the
+  profile whose community users receive `communityUserPermset` (if set).
+- **`authProviderNames`** (required, non-empty) — the **DeveloperNames** of
+  `AuthProvider` (OAuth) and/or `SamlSsoConfig` (SAML) records to link. These are
+  DeveloperNames, not friendly labels.
+- **`communityUserPermset`** (optional) — permset assigned to SSO-created community
+  users so `getCurrentUser()` (`/chatter/users/me`, via `/sf/api/`) works; the
+  standard community profile lacks `ApiEnabled`. Typically the app's
+  `*_Guest_User_Api_Access` permset.
+
+There is **no `siteName`** — the site is derived (below). All three string values
+are validated against the SOQL-name whitelist before use in any query or generated
+Apex (same guard the permset/self-reg paths use); a `'`, `\`, or control char is a
+config error.
+
+## Site derivation (`deriveSiteName`, 418-441)
+
+The site is the base name of the **single** `*.network-meta.xml` under
+`<packageDir>/main/default/networks/`. Zero or more than one → STOP (ambiguous; the
+reference throws rather than guessing). Social login needs the site to resolve its
+`AuthConfig` (matched via `AuthConfig.Url LIKE '%<siteName>%'`).
+
+## Enablement sequence (mirrors `main()` 2124-2168)
+
+Runs **after** self-registration (step 6) and **before** data import / GraphQL.
+Every sub-step is idempotent — run its query first and skip work that already
+exists. Substitute `<org>` with the target-org alias throughout. All three config
+string values (`communityMemberProfile`, each `authProviderNames` entry,
+`communityUserPermset`) MUST be validated against the SOQL-name whitelist before
+use in any query/Apex below — reject any value containing `'`, `\`, or a control
+char (same guard the permset/self-reg paths use); such a value is a config error.
+
+### 1. Enable "Allow standard external profiles" (`enableExternalProfiles`, 569-617)
+
+An org setting required so SSO registration handlers can create users on standard
+community profiles; without it, auth providers return `FIELD_INTEGRITY_EXCEPTION`
+on user insert. It deploys via Metadata API (REST/Tooling approaches fail on many
+org types), so the `CommunitiesSettings` file needs a minimal throwaway sfdx
+project. Read `assets/Communities.settings-meta.xml` and stage it in a temp dir:
+
+```bash
+TMP=$(mktemp -d)
+mkdir -p "$TMP/force-app/main/default/settings"
+printf '{"packageDirectories":[{"path":"force-app","default":true}],"sourceApiVersion":"68.0"}' > "$TMP/sfdx-project.json"
+cp skills/experience-ui-bundle-deploy/assets/Communities.settings-meta.xml \
+   "$TMP/force-app/main/default/settings/Communities.settings-meta.xml"
+sf project deploy start --target-org <org> --source-dir "$TMP/force-app" --json
+rm -rf "$TMP"
+```
+
+A deploy warning that the setting is already active is a **non-fatal skip** — the
+setting may already be on. Continue to sub-step 2.
+
+### 2. Link Auth Providers to the site `AuthConfig` (`enableAuthProvidersForSite`, 638-833)
+
+Apply `assets/social-login-auth-providers.apex` **verbatim** — do not hand-write
+this. Substitute its placeholders: `<siteName>` (derived above), `<ProviderNamesList>`
+(the whitelisted `authProviderNames` as a comma-separated single-quoted list, e.g.
+`'Google', 'My_SAML_Provider'` — identical in both the `IN (...)` clauses and the
+requested-name loop), and `<ApiVersion>` (e.g. `62.0`). Then run it as ONE call:
+
+```bash
+sf apex run --target-org <org> --file assets/social-login-auth-providers.apex
+```
+
+Read the `|DEBUG|` output lines (match `|DEBUG|` only — `sf apex run` echoes the
+source, which would otherwise false-positive):
+
+| `|DEBUG|` line | Meaning → action |
+|----------------|------------------|
+| `ERROR_NO_AUTHCONFIG` | No `AuthConfig` for the site → **fail**: "no AuthConfig found for site `<siteName>`". Publish/activate the site; confirm the derived name matches the org Network. |
+| `ERROR_NO_PROVIDERS` | None of the names resolved → **fail**: none found for those names; create them in Setup first. |
+| `MISSING_PROVIDERS:<names>` | Strict subset resolved → **fail**: "some configured auth providers were not found: `<names>`". Nothing was linked (all-or-nothing; the check runs before any insert). Create/fix them or fix the DeveloperName(s) and re-run. |
+| `INSERT_FAILED:<name>:<type>:<code>:<body>` | A junction insert failed → **fail** after reporting each; `<code>`/`<body>` explain why. |
+| `INSERTED:<name>:<type>` | Newly linked (report `+ <name>`). |
+| `ALREADY_LINKED:<name>:<type>` / `ALL_ALREADY_LINKED` | Idempotent skip — already linked; report and continue. |
+| `TOTAL_INSERTED:<n>` | Success — `<n>` providers newly linked. |
+
+Matching is **case-insensitive** (SOQL `DeveloperName IN (...)` is), so a stored
+name differing only in case is not "missing."
+
+### 3. Add the community member profile to `NetworkMemberGroup` (`addCommunityMemberProfile`, 847-917)
+
+Without it, users created by the SSO registration handler hit `NO_ACCESS: User was
+not authorized for the community`. Resolve the Network + Profile Ids, skip if the
+membership already exists, else create it (idempotent):
+
+```bash
+# Resolve Ids (<siteName> derived above; <communityMemberProfile> from config)
+sf data query --target-org <org> --json \
+  --query "SELECT Id FROM Network WHERE Name = '<siteName>'"                 # -> <NetworkId>
+sf data query --target-org <org> --json \
+  --query "SELECT Id FROM Profile WHERE Name = '<communityMemberProfile>'"   # -> <ProfileId>
+# Idempotency check — skip the create if this returns any record
+sf data query --target-org <org> --json \
+  --query "SELECT Id FROM NetworkMemberGroup WHERE NetworkId = '<NetworkId>' AND ParentId = '<ProfileId>'"
+# Create only if absent
+sf data create record --target-org <org> --sobject NetworkMemberGroup \
+  --values "NetworkId='<NetworkId>' ParentId='<ProfileId>'" --json
+```
+
+### 4. (Optional) Assign `communityUserPermset` to community users (`assignPermsetToCommunityUsers`, 929-991)
+
+Only when `communityUserPermset` is configured. Grants `ApiEnabled` so
+`getCurrentUser()` (`/chatter/users/me` via `/sf/api/`) works for SSO-created
+users. Find active community users on `communityMemberProfile` who lack the
+permset, and assign it (idempotent; no users yet → skip, not fatal):
+
+```bash
+# Resolve the permset Id
+sf data query --target-org <org> --json \
+  --query "SELECT Id FROM PermissionSet WHERE Name = '<communityUserPermset>'"   # -> <PermSetId>
+# Find users on the profile who do NOT already have it
+sf data query --target-org <org> --json \
+  --query "SELECT Id, Username FROM User WHERE Profile.Name = '<communityMemberProfile>' AND IsActive = true AND UserType IN ('CspLitePortal','CustomerSuccess','PowerCustomerSuccess') AND Id NOT IN (SELECT AssigneeId FROM PermissionSetAssignment WHERE PermissionSetId = '<PermSetId>')"
+# For each returned user Id, assign (treat DUPLICATE_VALUE as an already-assigned skip)
+sf data create record --target-org <org> --sobject PermissionSetAssignment \
+  --values "PermissionSetId='<PermSetId>' AssigneeId='<UserId>'" --json
+```
+
+## Gotchas
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| No social-login buttons on the login page | `socialLogin` block absent or step skipped | Add the block and run step 6b; it links providers to the site `AuthConfig` |
+| "some configured auth providers were not found: X" | A DeveloperName in `authProviderNames` has no `AuthProvider`/`SamlSsoConfig` record | Create it in Setup first, or fix the DeveloperName. Nothing is linked until all resolve |
+| `no AuthConfig found for site "<name>"` | Site not published/active, or name mis-derived | Publish the site; confirm the single `*.network-meta.xml` base name matches the org's Network name |
+| SSO user: `NO_ACCESS: User was not authorized for the community` | `communityMemberProfile` not in `NetworkMemberGroup` | Ensure sub-step 3 ran (profile added to member groups) |
+| SSO user insert fails with `FIELD_INTEGRITY_EXCEPTION` | "Allow standard external profiles" org setting off | Ensure sub-step 1 ran (`enableExternalProfiles`) |
+| `getCurrentUser()` / `/chatter/users/me` fails for SSO users | Community profile lacks `ApiEnabled` | Set `communityUserPermset` so sub-step 4 assigns API access |

package/skills/experience-ui-bundle-frontend-generate/SKILL.md

@@ -5,6 +5,7 @@ metadata:
   version: "1.1"
   relatedSkills:
     - "experience-ui-bundle-app-coordinate"
+    - "experience-ui-bundle-features-generate"
     - "experience-ui-bundle-metadata-generate"
     - "experience-ui-bundle-salesforce-data-access"
   cliTools:
@@ -51,6 +52,19 @@ A request to rename/rebrand the app (e.g. "call it X everywhere a user would see
 
 ---
 
+## Pre-built Features (Check Before Hand-Building)
+
+Some capabilities ship as pre-built, tested feature packages. The catalog **evolves and is not something you can know from memory** — never decide from the request wording alone whether a capability "is" or "isn't" a feature. Before hand-writing any non-trivial capability (anything beyond a plain page, component, or styling change) in this skill:
+
+1. **Consult the authoritative catalog.** Invoke `experience-ui-bundle-features-generate`, which runs `list` to show the *current* set of installable features. Do not rely on a hardcoded or remembered list — this skill deliberately names none, because any names it listed would go stale.
+2. **Detect whether a matching feature is already installed** in the bundle — inspect `package.json` dependencies and existing `src/` files. If present, use it as-is; do not reinstall or re-implement.
+3. **If a matching feature exists in the catalog but isn't installed**, let `experience-ui-bundle-features-generate` install the tested package. Do not build it from scratch here.
+4. **Only hand-build** a capability that has no matching catalog feature.
+
+This gate is **idempotent**: when this skill runs as a phase of `experience-ui-bundle-app-coordinate` (which installs features earlier in its sequence), step 2 finds the feature already present and this collapses to a no-op. It only does real work when the skill was reached directly — the path that would otherwise skip feature detection.
+
+---
+
 ## Layout and Navigation
 
 `appLayout.tsx` is the source of truth for navigation and layout. Every page shares this shell.

package/skills/experience-ui-bundle-mfa-configure/SKILL.md

@@ -2,21 +2,22 @@
 name: experience-ui-bundle-mfa-configure
 description: "Configure Multi-Factor Authentication (MFA) for Salesforce Experience Site users. TRIGGER when: user wants to enable MFA on a community, enforce two-factor authentication for portal users, add MFA to a React Experience Site / Web App, configure ForceTwoFactor permission, create MFA permission sets for external users, or troubleshoot MFA not appearing on login. Also triggers on: MFA community, two-factor portal, ForceTwoFactor permission set, MFA Experience Cloud, MFA React site, identity verification community, MFA experience site, ForceTwoFactor permissionset-meta.xml, MFA permissionset-meta.xml. DO NOT TRIGGER when: configuring org-wide MFA for internal users (that's Setup > Identity Verification), building custom login UI components (use experience-ui-bundle-frontend-generate), or generating generic permission sets without MFA context (use platform-permission-set-generate)."
 metadata:
-  version: "1.0"
+  version: "1.1"
   minApiVersion: "47.0"
   cliTools:
-    - tool: ["sf"]
-      semver: ">=2.0.0"
     - tool: ["jq"]
       semver: ">=1.6"
+    - tool: ["sf"]
+      semver: ">=2.0.0"
   accessCheck:
     - type: "license"
       value: "Experience Cloud (Customer Community / Customer Community Login)"
   relatedSkills:
-    - "platform-permission-set-generate"
     - "dx-org-permission-set-assign"
+    - "experience-ui-bundle-deploy"
     - "experience-ui-bundle-frontend-generate"
     - "platform-metadata-deploy"
+    - "platform-permission-set-generate"
 ---
 
 # Enabling MFA on Experience Sites
@@ -370,7 +371,7 @@ Files generated in the user's project:
 | User needs to deploy all project metadata | `platform-metadata-deploy` |
 | User wants to customize the login page UI | `experience-ui-bundle-frontend-generate` |
 | User needs to create a new generic permission set | `platform-permission-set-generate` |
-| User wants IDP/Social Login (different from MFA) | Supported on React sites — the built-in Social Login component renders configured Auth Providers on the login page automatically (shipped in 264). Configure Auth Providers in Setup; no custom code needed. See `references/social-login.md`. |
+| User wants IDP/Social Login (different from MFA) | Supported on React sites — the built-in Social Login component renders linked Auth Providers on the login page automatically. Create the Auth Providers in Setup, then link them to the React site via the `experience-ui-bundle-deploy` social login step (`socialLogin` in `org-setup.config.json`) — the React SSO admin UI is hidden, so linking is programmatic, not a Setup click-path. See `references/social-login.md`. |
 
 ---
 

package/skills/experience-ui-bundle-mfa-configure/references/social-login.md

@@ -24,12 +24,20 @@ writing a component.
 
 ## How to enable
 
-1. **Configure the Auth Provider(s)** in Setup → Identity → Auth. Providers
-   (e.g. Google, Facebook, Salesforce, or a SAML/OpenID Connect provider).
-2. **Add the provider(s) to the site's login configuration** so they are
-   exposed to the community — Setup → Digital Experiences → *(site)* → 
-   Administration → Login & Registration.
-3. **Publish** the site. The React login page renders a button per configured
+1. **Create the Auth Provider(s)** in Setup → Identity → Auth. Providers
+   (e.g. Google, Facebook, Salesforce, or a SAML/OpenID Connect provider). This
+   part is done in Setup as usual.
+2. **Link the provider(s) to the React site.** Do **not** use Setup → Digital
+   Experiences → Login & Registration for this — on React (Site Container) sites
+   that SSO admin UI is **hidden**, so the provider cannot be attached to the site
+   by clicking through Setup. The link is created programmatically by writing
+   `AuthConfigProviders` junction records against the site's `AuthConfig`. Use the
+   `experience-ui-bundle-deploy` skill's **social login step** (a `socialLogin`
+   block in `org-setup.config.json` with `communityMemberProfile` +
+   `authProviderNames`), which runs the shipped org-setup automation and also adds
+   the community profile to the site's `NetworkMemberGroup`. See that skill's
+   `references/social-login.md` for the mechanism and config.
+3. **Publish** the site. The React login page renders a button per linked
    provider automatically.
 
 ## How the redirect works (for troubleshooting)
@@ -56,7 +64,7 @@ writing a component.
 
 | Symptom | Cause | Fix |
 |---------|-------|-----|
-| No provider buttons on React login page | No Auth Providers configured, or not added to the site's Login & Registration settings | Configure Auth Providers and add them to the site, then re-publish |
+| No provider buttons on React login page | No Auth Providers created, or created but not linked to the site's `AuthConfig` (React sites can't be linked via the Login & Registration UI — it's hidden) | Create the Auth Providers, then link them via the `experience-ui-bundle-deploy` social login step (`socialLogin` in `org-setup.config.json`), and re-publish |
 | Buttons appear but SSO fails to start | `startURL` points at `/` or `/login` | Set `startURL` to the site home path |
 | Redirect loop after SSO | `startURL` misconfigured | Point `startURL` at the site home path, not the login page |
 | Provider button missing an icon | Auth Provider icon not set | Set the icon on the Auth Provider definition |