@salesforce/afv-skills 1.41.0 → 1.43.0

package/skills/service-de-headless-channel-configure/references/inputs.md

@@ -0,0 +1,49 @@
+---
+name: service-de-headless-channel-configure-inputs
+description: "Load when you need the full input list for the headless channel setup orchestrator — the base MESSAGE_TYPE/ORG_ALIAS prompt plus the type-specific fields required for WhatsApp, LINE, AppleBusinessChat, Facebook, and Text (SMS). Covers exactly which fields are required vs optional per channel type and the prompt text shown when MESSAGE_TYPE is omitted. DO NOT load for Stage 0's preflight-key derivation logic, which lives inline in the parent skill."
+metadata:
+  version: "1.0"
+  related-skills: service-de-headless-channel-configure
+---
+
+# Inputs (from user)
+
+- `{MESSAGE_TYPE}` — one of `WhatsApp`, `Line`, `AppleBusinessChat`, `Facebook`, `Text` (`Text` is the enum value for SMS — there is no `SMS` type). If omitted, the orchestrator prompts:
+  ```text
+  Which channel type are you setting up?
+    1) WhatsApp
+    2) Line
+    3) AppleBusinessChat
+    4) Facebook
+    5) Text (SMS)
+  Pick [1-5]:
+  ```
+- `{ORG_ALIAS}` — optional. `sf` CLI target-org alias. Defaults to `sf config get target-org`.
+- Plus the type-specific inputs, which are forwarded to the dispatcher:
+
+## If `MESSAGE_TYPE=WhatsApp`
+- `{WABA_ID}` — WhatsApp Business Account ID
+- `{PHONE_NUMBER_ID}` — Meta phone number ID (not the display number)
+- `{CHANNEL_NAME}` — optional
+- `{ISO_COUNTRY_CODE}` — optional, default `US`
+
+## If `MESSAGE_TYPE=Line`
+- `{LINE_CHANNEL_ID}` — numeric LINE channel id
+- `{LINE_CHANNEL_SECRET}`, `{LINE_ACCESS_TOKEN}`
+- `{CHANNEL_NAME}` — optional
+
+## If `MESSAGE_TYPE=AppleBusinessChat`
+- `{APPLE_BC_ID}` — Apple Business Chat Account ID
+- `{CHANNEL_NAME}` — required
+
+## If `MESSAGE_TYPE=Facebook`
+- `{PAGE_ID}` — optional. Facebook Page ID (numeric string). If not provided, the insertion skill runs OAuth, fetches available pages, and prompts for selection.
+- `{CHANNEL_NAME}` — optional. If not provided, the insertion skill prompts for it.
+
+## If `MESSAGE_TYPE=Text` (SMS)
+- `{SMS_NUMBER}` — the phone number / short code / toll-free number the channel sends from, already provisioned to the org. It's the platform key. **Required.**
+- `{SMS_PROVIDER}` — optional. The code provider for the number (e.g. `Sinch`). The insertion skill always sends the `smsProvider` key to satisfy the Connect request shape (omitting it trips a `400`), but the value is neither validated nor persisted — it leaves no observable trace on the record. If the caller doesn't supply one it defaults to `""`; pass a real value only when you have it, since nothing downstream reads it.
+- `{CHANNEL_NAME}` — optional. Falls back to the number if omitted.
+- `{ISO_COUNTRY_CODE}` — optional, default `US`. Pass the real country if the number is non-US.
+
+The orchestrator validates type-specific inputs upfront; missing ones raise a prompt before we burn a Stage 0 SOQL.

package/skills/service-de-headless-channel-configure/references/output-envelopes.md

@@ -0,0 +1,53 @@
+---
+name: service-de-headless-channel-configure-output-envelopes
+description: "Load when you need the canonical JSON envelope shapes this orchestrator emits — success, step-annotated failure, and terms-declined — before wiring error handling or parsing a leaf skill's response. Covers the exact field names (channelId, mcuId, stepsRun, failedStep, resumeHint, etc.) for each of the three top-level outcomes. DO NOT load for the per-stage envelope-handling tables in Stage 2-4, which already reference these shapes."
+metadata:
+  version: "1.0"
+  related-skills: service-de-headless-channel-configure
+---
+
+# Output (to user)
+
+**Success:**
+```json
+{"ok": true, "messageType": "{MESSAGE_TYPE}", "channelId": "0Mj...",
+ "mcuId": "0gL...", "channelName": "...", "sessionHandlerId": "00G...",
+ "queueName": "...", "isActive": true,
+ "stepsRun": ["insert","route","activate"], "stepsSkipped": ["consent"],
+ "totalDurationMs": 12345}
+```
+
+On a typical fresh run `consent` lands in `stepsSkipped`, not `stepsRun`: the Connect insert
+auto-seeds `ConsentType=ImplicitOptIn` + a default opt-out keyword, so the consent leaf no-ops
+(`noop: true`) and the orchestrator appends `"consent"` to `stepsSkipped`. It appears in `stepsRun`
+only when the caller asked for an upgrade (ExplicitOptIn/DoubleOptIn) or custom keywords, which
+triggers a real write.
+
+**Failure** (with step annotation):
+```json
+{"ok": false, "failedStep": "route", "failedStepIndex": 2, "failedStepTotal": 4,
+ "leafEnvelope": { ...whatever the failing leaf skill returned... },
+ "stateSoFar": { "channelId": "0Mj...", "mcuId": "0gL...", "isActive": false,
+   "stepsRun": ["insert"], "stepsSkipped": [] },
+ "resumeHint": "fix the routing issue above, then re-run this skill — step 1 will be skipped automatically"}
+```
+
+`stateSoFar` carries only what landed *before* the failure — the failed step itself is NOT in
+`stepsRun`, and that step's output fields are absent. In this `failedStep: "route"` example routing
+never completed, so `stepsRun` is `["insert"]` and there is no `sessionHandlerId`/`queueName` (Stage 3
+records those and appends `"route"` only on a successful routing envelope). `stateSoFar` **always
+includes both `stepsRun` and `stepsSkipped`** (each an array, possibly empty) so the renderer can read
+either without a guard; here `stepsSkipped` is `[]` because the failure happened before Stage 3.5.
+`stepsRun` (the ordered list of *completed* steps) is what the partial-success renderer reads to
+report each step's status.
+**Consent is the exception:** there is no separate `consentConfigured` flag, but because the insert
+auto-seeds `ImplicitOptIn`, a consent-ready channel usually lands `"consent"` in `stepsSkipped`
+(no-op), not `stepsRun`. So to answer "is consent configured?", treat *either* list — a `"consent"`
+in `stepsRun` OR `stepsSkipped` means consent is activation-ready; only its total absence (a failure
+before Stage 3.5) means unconfigured.
+
+**Terms declined** (Stage 0.5 gate — returned before any org work):
+```json
+{"ok": false, "kind": "terms-not-accepted",
+ "hint": "user did not accept the Enhanced Messaging Terms and Conditions — channel setup cannot proceed. Re-run when ready to accept."}
+```

package/skills/service-de-headless-channel-configure/references/partial-success.md

@@ -0,0 +1,24 @@
+---
+name: service-de-headless-channel-configure-partial-success
+description: "Load when the orchestrator fails mid-way through Stage 2-4 and you need to render the partial-success/resume message to the user. Covers the stateSoFar rendering template showing which of insert/route/consent/activate landed before the failure and the retry instructions. DO NOT load for the success-path Stage 5 final summary or the terms-not-accepted envelope."
+metadata:
+  version: "1.0"
+  related-skills: service-de-headless-channel-configure
+---
+
+# Partial-success and resume reporting
+
+If the orchestrator fails mid-way, the envelope always includes `stateSoFar` describing what landed. Render as:
+
+```text
+Error: Step {N} of 4 ({stepName}) failed: {leafEnvelope.kind} — {leafEnvelope.message or hint}
+
+   What's already in place:
+   - Channel inserted: {channelId ? "yes — " + channelId : "no"}
+   - Routing configured: {sessionHandlerId ? "yes — " + queueName : "no"}
+   - Consent configured: {(stepsRun.includes("consent") || (stepsSkipped || []).includes("consent")) ? "yes" : "no"}
+   - Activation: {isActive ? "yes" : "no"}
+
+   To retry: fix the issue above, then re-run this skill with the same
+   inputs. The orchestrator will skip completed steps.
+```

package/skills/service-de-headless-channel-configure/references/terms-and-conditions.md

@@ -0,0 +1,54 @@
+---
+name: service-de-headless-channel-configure-terms-and-conditions
+description: "Load when rendering the Stage 0.5 Enhanced Messaging Terms and Conditions disclaimer and certification prompt for any channel type (WhatsApp, LINE, Facebook Messenger, Apple Messages for Business, SMS/Text). Covers the verbatim disclaimer text, the per-type CHANNEL_LABEL/THIRD_PARTY substitution table, and the certification prompt wording. DO NOT load for the gate's accept/decline behavior or the terms-not-accepted envelope — those stay inline in the parent skill's Stage 0.5 section."
+metadata:
+  version: "1.0"
+  related-skills: service-de-headless-channel-configure
+---
+
+# Enhanced Messaging Terms and Conditions — disclaimer text and mappings
+
+Render the disclaimer verbatim, substituting the human-readable channel name for `{MESSAGE_TYPE}` (`Facebook Messenger`, `WhatsApp`, `LINE`, `Apple Messages for Business`, `SMS (Text)`):
+
+```text
+────────────────────────────────────────────────────────────────────
+  Terms and Conditions
+────────────────────────────────────────────────────────────────────
+
+The {CHANNEL_LABEL} channel you have selected is part of the service
+branded as Enhanced Messaging. Enhanced Messaging features are provided
+using infrastructure technology different from Messaging. Any service
+level commitments and any security, privacy, data storage or processing
+locations or data recovery measures that are specific to Messaging do
+not apply to Enhanced Messaging features, and such information for
+Enhanced Messaging features is as described in the applicable Trust and
+Compliance Documentation available at
+https://www.salesforce.com/company/legal/trust-and-compliance-documentation/.
+
+The {CHANNEL_LABEL} channel integrates with third-party functionality
+powered by {THIRD_PARTY}. By enabling an integration with such
+functionality, you acknowledge and agree that the {CHANNEL_LABEL}
+channel is a Non-SFDC Application (as defined in your main services
+agreement), and your use of the {CHANNEL_LABEL} channel is subject to
+the applicable third-party terms in the Enhanced Messaging Notices and
+License Information Documentation.
+
+Enhanced Messaging is also subject to the relevant Documentation and
+terms on your order form for Digital Engagement.
+────────────────────────────────────────────────────────────────────
+
+Do you certify that you have the authority to accept and bind your
+organization to these terms? [yes/no]
+```
+
+`{CHANNEL_LABEL}` and `{THIRD_PARTY}` by type:
+
+| `{MESSAGE_TYPE}` | `{CHANNEL_LABEL}` | `{THIRD_PARTY}` |
+| --- | --- | --- |
+| `Facebook` | `Facebook Messenger` | `Meta Platforms, Inc. or its affiliates` |
+| `WhatsApp` | `WhatsApp` | `Meta Platforms, Inc. or its affiliates` |
+| `Line` | `LINE` | `LINE Corporation or its affiliates` |
+| `AppleBusinessChat` | `Apple Messages for Business` | `Apple Inc. or its affiliates` |
+| `Text` | `SMS (Text)` | the supplied `{SMS_PROVIDER}` (e.g. `Sinch`), else `your SMS provider` |
+
+The certification prompt mirrors the wizard's checkbox — *"I hereby certify that I have the authority to accept and bind my organization to these terms."*

package/skills/service-de-headless-channel-configure/references/worked-examples.md

@@ -0,0 +1,108 @@
+# Worked examples: `service-de-headless-channel-configure`
+
+Four reference traces: a fresh WhatsApp run (the most common path), a resume after a mid-flow failure, an Apple Business Chat dispatch (to show type-agnostic flow), and an unsupported-type rejection. Read these when you need to see the exact envelope shapes the orchestrator emits at each outcome.
+
+---
+
+## Worked example: fresh WhatsApp channel on test1
+
+Input (hypothetical, against `test1`):
+- `MESSAGE_TYPE=WhatsApp`
+- `WABA_ID=1558753535400324`
+- `PHONE_NUMBER_ID=1005595132638768`
+- `CHANNEL_NAME` = (omitted)
+
+**Stage 0**: type known from input. `{PLATFORM_KEY} = PHONE_NUMBER_ID`. Required WhatsApp inputs (`WABA_ID`, `PHONE_NUMBER_ID`) both present — proceed.
+
+**Stage 1**: preflight SOQL keyed off `MessagingPlatformKey=1005595132638768 AND MessageType='WhatsApp'` returns 0 records → `CURRENT_STATE=fresh`. First step: insert.
+
+**Stage 2** (insert): `service-de-channel-create` runs (with `MESSAGE_TYPE=WhatsApp`):
+  - Its Stage 1 preflight (same SOQL; still empty)
+  - Its Stage 2 linking prereq (`service-de-waba-integrate`) — user confirms Meta partnership is in place
+  - Its Stage 3 Connect API POST — inserts `MessagingChannel 0MjSG...` + MCU `0gLSG...`
+  - Its Stage 4 verify — MCU subquery returns one row with `DeploymentType=Conversation`, `DeploymentStatus=Disabled`
+
+Returns `{ok:true, channelId:"0MjSG...", mcuId:"0gLSG...", developerName:"WHATSAPP_US_...", isActive:false, messageType:"WhatsApp", path:"connect", created:true, durationMs:3210}` to the orchestrator. `STEPS_RUN=["insert"]`.
+
+**Stage 3** (route): `service-de-channel-routing-configure` prompts user. User picks existing `Messaging_Queue` (`00GSG0000000LSf2AM`). PATCH lands. `STEPS_RUN=["insert","route"]`.
+
+**Stage 3.5** (consent): `service-de-channel-consent-configure` runs. The insert auto-seeded `ConsentType=ImplicitOptIn` + a default opt-out `MsgChannelLanguageKeyword` (STOP-family + confirmation), so the leaf's Stage 1 finds the channel already activation-ready and returns `noop:true` — no write needed. (Had the user asked for ExplicitOptIn/DoubleOptIn or custom keywords, the leaf would upgrade it here.) `STEPS_RUN=["insert","route"]`, `STEPS_SKIPPED=["consent"]`.
+
+**Stage 4** (activate): `service-de-channel-activate` PATCHes `MessagingChannelUsage.DeploymentStatus='Provisioning'` via REST. The PATCH blocks synchronously until the server-side observer chain finishes, then returns 204 with `DeploymentStatus=Active` → `channel.IsActive=true` in ~15-21s (Meta `/register` round-trip). `STEPS_RUN=["insert","route","activate"]`.
+
+**Stage 5**: Emits:
+```json
+{"ok":true, "messageType":"WhatsApp", "channelId":"0MjSG...", "mcuId":"0gLSG...",
+ "channelName":"+1 650-555-0199", "sessionHandlerId":"00GSG0000000LSf2AM",
+ "queueName":"Messaging Queue", "isActive":true,
+ "stepsRun":["insert","route","activate"], "stepsSkipped":["consent"], "totalDurationMs":8421}
+```
+
+User sees `Success — WhatsApp channel '+1 650-555-0199' is live on test1.` plus the detail lines.
+
+---
+
+## Worked example: resume after routing failure
+
+Same inputs as above, but imagine Stage 3 failed the first time because the user's session lost permission to deploy Queue metadata.
+
+**First run** — orchestrator gets through stages 0-2, stage 3 fails:
+```json
+{"ok":false, "failedStep":"route", "failedStepIndex":2, "failedStepTotal":4,
+ "leafEnvelope":{"ok":false,"kind":"metadata-deploy-failed","message":"INSUFFICIENT_ACCESS_OR_READONLY"},
+ "stateSoFar":{"channelId":"0MjSG...", "mcuId":"0gLSG...",
+               "sessionHandlerId":null, "isActive":false,
+               "stepsRun":["insert"], "stepsSkipped":[]},
+ "resumeHint":"fix the routing issue above, then re-run this skill — step 1 will be skipped automatically"}
+```
+
+User fixes the permission, re-runs with the same inputs.
+
+**Second run**:
+- **Stage 0** type known (user provided `WhatsApp` again). Inputs validated.
+- **Stage 1** preflight now returns 1 record: `{channelId, IsActive:false, SessionHandlerId:null, FallbackQueueId:null, ...}` → `CURRENT_STATE=inserted-no-routing`. First step: route.
+- **Stage 2** (insert): skipped. `STEPS_SKIPPED=["insert"]`. The dispatcher + all per-type prereqs (including the WABA linking prompt) are skipped entirely, which is the whole point of preflight short-circuiting.
+- **Stage 3** (route): runs fresh, succeeds this time. `STEPS_RUN=["route"]`.
+- **Stage 3.5** (consent): the channel was inserted on the *first* run, so its consent was auto-seeded then (`ConsentType=ImplicitOptIn` + default opt-out keyword). The leaf's Stage 1 finds it already activation-ready and returns `noop:true` — no write. `STEPS_SKIPPED=["consent"]`. (Only an explicit Explicit/DoubleOptIn or custom-keyword request would make this a real write.)
+- **Stage 4** (activate): runs. `STEPS_RUN=["route","activate"]`.
+- **Stage 5**: success, with `stepsRun: ["route","activate"]` and `stepsSkipped: ["insert","consent"]` visible in the report.
+
+The user sees that resume happened, and the total time reflects only what was re-done.
+
+---
+
+## Worked example: Apple Business Chat dispatch
+
+Shows the type-agnostic flow — same orchestrator, different leaf via the dispatcher.
+
+Input:
+- `MESSAGE_TYPE=AppleBusinessChat`
+- `APPLE_BC_ID=abc123-def456-...` (GUID)
+- `CHANNEL_NAME="Acme Apple Support"`
+
+**Stage 0**: type known. `{PLATFORM_KEY} = APPLE_BC_ID`. Apple-required inputs (`APPLE_BC_ID`, `CHANNEL_NAME`) present — proceed.
+
+**Stage 1**: preflight SOQL keyed off `MessagingPlatformKey='abc123-...' AND MessageType='AppleBusinessChat'` returns 0 records → `CURRENT_STATE=fresh`.
+
+**Stage 2** (insert): `service-de-channel-create` runs with `MESSAGE_TYPE=AppleBusinessChat`. The user supplies the Apple BC Account ID (obtained on the Apple Business Register side beforehand), and the skill inserts the channel. Returns with `messageType:"AppleBusinessChat"`.
+
+**Stages 3-5**: routing and activation are identical to the WhatsApp path — they operate on `MessagingChannel.Id` + `MessagingChannelUsage.Id`, which don't care about message type.
+
+Final envelope identical shape to the WhatsApp run but with `messageType: "AppleBusinessChat"`.
+
+---
+
+## Worked example: unsupported type rejection
+
+User invokes without specifying a type, gets the prompt, then types `wechat`.
+
+**Stage 0**: prompt shows `1) WhatsApp / 2) Line / 3) AppleBusinessChat / 4) Facebook / 5) Text (SMS)`. Input `wechat` doesn't match any — orchestrator re-prompts or halts with:
+```json
+{"ok":false, "kind":"unsupported-type", "messageType":"wechat",
+ "supportedTypes":["WhatsApp","Line","AppleBusinessChat","Facebook","Text"],
+ "hint":"WeChat needs its own insertion leaf, not yet built — supported types are WhatsApp, Line, AppleBusinessChat, Facebook, Text"}
+```
+
+Alternatively, if the orchestrator forwards `WeChat` directly to the dispatcher without validating upfront, the dispatcher (`service-de-channel-create`) emits the same `unsupported-type` envelope and the orchestrator passes it through with `failedStep: "insert"`.
+
+Either way the user gets a clear "this type isn't supported" message rather than a confusing mid-flow error.

package/skills/service-de-waba-integrate/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: service-de-waba-integrate
+description: "Confirm the customer's WhatsApp Business Account is shared with Salesforce on Meta's side. Pure instruction + one user-confirmation prompt — no API calls, no token handling. The actual sharing happens in Meta Business Suite (UI-only; Meta provides no Graph endpoint to automate this step). Renders step-by-step instructions with Salesforce's Business Manager ID substituted in, then asks the user to confirm whether \"Salesforce\" appears in the WABA's Partners list."
+metadata:
+  version: "1.0"
+  minApiVersion: "67.0"
+  domains: ["Service"]
+  relatedSkills:
+    - "service-de-channel-create"
+---
+
+# Linking a WABA to Salesforce
+
+## What this skill does
+
+Gets the customer from "I have a WABA" to "my WABA is linked to Salesforce" — entirely by instruction. Meta intentionally gates this behind the human-approval UI at business.facebook.com; there's no Graph write endpoint that scripts the partnership. The two GET endpoints that would let us probe state (`/{waba-id}/subscribed_apps`, `/{waba-id}/assigned_users`) need a Meta access token with `whatsapp_business_management` scope that the customer would have to generate — a bigger ask than just "check your Partners tab."
+
+So the skill is 100% instruction rendering + one confirmation prompt. No API calls. No SF DB writes. No Meta tokens.
+
+After this skill returns success, downstream insertion (`service-de-channel-create`) can proceed: the SF-side `setupLiveMessageChannelEnhanced` path doesn't require us to have proven the partnership — it'll fail with a clear Meta-precondition error if the customer lied, and our skill trusts the customer's confirmation.
+
+## When NOT to use this skill
+
+- **You've already confirmed the partnership on a previous run.** The orchestrator's resume logic doesn't short-circuit Stage 1 (no cheap SF-side probe exists), so this skill always runs — but it's just text + a prompt, no round trip.
+- **You're inserting a non-WhatsApp channel.** Line / Apple / Facebook don't use Meta Business Manager partnerships. Skip this skill entirely for those paths.
+- **The customer is using the Embedded Signup popup instead.** That's a different flow (popup-driven, SF-UI-side OAuth); this skill is specifically the headless alternative.
+
+## Inputs (from caller)
+
+- `{WABA_ID}` — WhatsApp Business Account ID. Used only for rendering (so the instructions say "open YOUR WABA" with the right id visible).
+- `{SF_BM_ID}` — optional. Defaults to `10152614792574154` (Salesforce's Business Manager ID, confirmed by user 2026-04-29; see IMPLEMENTATION.md §13 journey log). Override only if Salesforce issues a different BM ID for a specific partner program.
+
+## Output (to caller)
+
+**Success — user confirmed the partnership is in place:**
+```json
+{"ok": true, "linked": true, "path": "user-confirmed",
+ "note": "partnership confirmed by user; subsequent channel insert will
+          surface any server-side issues clearly"}
+```
+
+**Failure — partnership not yet in place:**
+```json
+{"ok": false, "kind": "partnership-blocked",
+ "hint": "customer reported Salesforce is not in the Partners tab;
+          most likely causes: (a) WABA ID typo, (b) user lacks admin
+          role in the Business Manager, (c) partnership request still
+          pending Meta approval. Retry this skill after resolving."}
+```
+
+**Failure — user-declined or dropped:**
+```json
+{"ok": false, "kind": "user-declined",
+ "hint": "user cancelled the linking step; re-run the orchestrator
+          when the customer is ready to click through Business Suite"}
+```
+
+---
+
+## Stage 1: Render the instructions
+
+Substitute `{WABA_ID}` and `{SF_BM_ID}` and **output the following directly as markdown text to the user** (do NOT use `cat`, `echo`, or any Bash command that would collapse the output):
+
+```markdown
+──────────────────────────────────────────────────────────────
+**Before we can insert the WhatsApp channel in Salesforce, your
+WhatsApp Business Account must be shared with Salesforce on
+Meta's side.** Meta gates this step behind business.facebook.com —
+there's no API we can call to automate it.
+
+## One-time steps (takes ~2 minutes):
+
+1. Go to https://business.facebook.com
+2. In the left nav, open "WhatsApp Accounts" and click your
+   WABA (ID: **{WABA_ID}**)
+3. Click the "Partners" tab at the top of the WABA page
+4. Look at the list:
+   - **If "Salesforce" (or "Salesforce.com") is already listed
+     with Full control** — you're done, nothing to do.
+   - **If NOT listed** (or listed with only partial access):
+     
+     a. Click "Add partners" → "Share account with partner"
+     
+     b. Paste this Business Manager ID in "Enter partner
+        business ID":
+     
+     ```
+     {SF_BM_ID}
+     ```
+     
+     c. Scroll to the "Full control" section at the bottom
+        and toggle ON "Everything":
+     
+     ```
+     [x] Everything — manage all settings, assign users,
+         view payment information and send messages
+     ```
+     
+     This is the option Salesforce needs. The Partial
+     access toggles above (Phone numbers / Message
+     templates / Messages) do NOT cover assigning users
+     or managing webhook subscriptions — those require
+     the Full control option. Don't try to grant access
+     piecemeal through Partial access.
+     
+     d. Click "Assign"
+
+## Notes:
+- Your Meta Business Manager must be business-verified for Meta
+  to accept the partnership. If it's not verified, Meta will
+  block the "Assign" step with a clear error.
+- You need admin role on the Business Manager to assign partners.
+  If you're a regular employee, ask an admin on your team.
+- Max 2 partners per WABA. If you've already shared with another
+  BSP, Salesforce would be the second — which is fine.
+──────────────────────────────────────────────────────────────
+```
+
+**CRITICAL:** Output this text directly in your response to the user, not via Bash/cat/echo. Tool results get collapsed; direct text output stays visible.
+
+---
+
+## Stage 2: Ask for confirmation
+
+Use AskUserQuestion to prompt:
+
+```text
+Question: Is "Salesforce" now showing in the Partners tab for this WABA?
+Header: Partnership
+Options:
+  1. Yes — already there or just added it
+     (Salesforce appears in the Partners tab with Full control)
+  2. No — still not showing
+     (Partnership not yet in place after attempting to add it)
+  3. Skip — abort setup for now
+     (Not going to complete this step right now)
+```
+
+Do not try to validate the answer with Meta. Trust the user. If they said yes and lied, downstream `service-de-channel-create` will fail with a `meta-precondition` envelope that clearly names the issue — that's a cleaner failure than fabricating a probe here that would need a customer Meta token.
+
+---
+
+## Stage 3: Emit the envelope
+
+Based on the user's answer, construct the appropriate envelope and **write it to `/tmp/linking-waba-result.json`** so the calling skill can parse it:
+
+| User's answer | Envelope to write |
+| --- | --- |
+| `y` | `{"ok":true, "linked":true, "path":"user-confirmed", "note":"partnership confirmed by user; subsequent channel insert will surface any server-side issues clearly"}` |
+| `n` | `{"ok":false, "kind":"partnership-blocked", "hint":"customer reported Salesforce is not in the Partners tab; most likely causes: (a) WABA ID typo, (b) user lacks admin role in the Business Manager, (c) partnership request still pending Meta approval. Retry this skill after resolving."}` |
+| `s` | `{"ok":false, "kind":"user-declined", "hint":"user cancelled the linking step; re-run the orchestrator when the customer is ready to click through Business Suite"}` |
+
+Write the envelope using:
+```bash
+echo '{envelope json}' > /tmp/linking-waba-result.json
+```
+
+Then display the human-readable summary to the user:
+
+- For `y`: `Success — WABA linked — Salesforce confirmed as a partner on WABA {WABA_ID}. Proceed to service-de-channel-create.`
+- For `n`: `Error: Partnership not yet in place — fix the issue on Meta's side (see instructions above) and re-run. Common fixes: check WABA ID, confirm your Business Manager is business-verified, confirm you have admin role.`
+- For `s`: `⏸  Linking skipped by user — re-run when ready.`
+
+---
+
+## Worked example: customer already has Salesforce shared
+
+Input: `{WABA_ID}=1558753535400324`
+
+**Stage 1**: skill renders the instructions with the WABA ID visible. Customer opens Business Suite → WhatsApp Accounts → 1558753535400324 → Partners. Sees "Salesforce" in the list.
+
+**Stage 2**: customer answers `y`.
+
+**Stage 3**: emits:
+```json
+{"ok":true, "linked":true, "path":"user-confirmed",
+ "note":"partnership confirmed by user; subsequent channel insert will surface any server-side issues clearly"}
+```
+
+Orchestrator continues to `service-de-channel-create`.
+
+## Worked example: customer needs to add the partnership
+
+Same input. Customer opens Business Suite, doesn't see Salesforce in Partners, clicks Add partners → Share account with partner → pastes `10152614792574154` → scrolls down to the "Full control" section → toggles ON "Everything" → Assign. Meta shows "Partnership request sent" or similar. Partnership lands (usually instant; occasionally pending for a few minutes if Meta needs to review).
+
+Customer answers `y` after confirming Salesforce now shows up.
+
+Orchestrator continues.
+
+## Worked example: Business Manager not business-verified
+
+Customer clicks Assign and Meta rejects with "Your business must be verified to assign partners." Customer answers `n` in our prompt.
+
+**Stage 3**: emits:
+```json
+{"ok":false, "kind":"partnership-blocked",
+ "hint":"customer reported Salesforce is not in the Partners tab; most likely causes: (a) WABA ID typo, (b) user lacks admin role in the Business Manager, (c) partnership request still pending Meta approval. Retry this skill after resolving."}
+```
+
+Orchestrator emits a step-annotated failure pointing at this skill; user pursues business verification through Meta separately and re-runs later.
+
+---
+
+## Gotchas
+
+1. **We can't probe state without a customer Meta token.** `GET /{waba-id}/subscribed_apps` and `GET /{waba-id}/assigned_users` would confirm SF's app is subscribed / user is assigned, but both need a token the customer would have to generate in a Meta app — a 20-minute detour to save one prompt. Not worth it. Trust the customer's eyeballs.
+
+2. **"Salesforce in Partners" ≠ "SF webhook subscription landed."** Subscription is a separate server-side event that happens *after* the partnership is in place, when SF's BSP app notices and calls its own internal setup. The customer's confirmation in this skill is about the *partnership*, not subscription state — subscription will catch up by the time `service-de-channel-create` runs. If it hasn't, the insert fails clearly with a Meta-precondition error and we retry.
+
+3. **The `SF_BM_ID` is a single static value.** `10152614792574154` is Salesforce's Business Manager ID, the same for every customer in every org. Confirmed 2026-04-29 (IMPLEMENTATION.md §13). Don't let callers override it casually — if someone passes a different value, they've likely misunderstood what the field is for. Keep the override capability for edge cases (SF issuing a partner-specific BM ID at some future date), but don't document it prominently.
+
+4. **The "Users" tab and the "Partners" tab are different.** Older IMPLEMENTATION.md drafts used the "add SF admin user" framing (users tab); the current canonical flow is "add SF as Partner" with the BM ID above. Both end up granting Salesforce access to the WABA, but the Partners flow is cleaner (no per-user maintenance, permission scoping is by partner role). Stick with Partners.
+
+5. **Embedded Signup is an alternative, not a complement.** Customers using the Embedded Signup popup skip this skill entirely — the popup handles partnership grant inline via Meta's OAuth flow. This skill is for the headless path (customer prefers Business Suite click-through over a browser popup). Don't try to run both.
+
+6. **Orchestrator calls this skill even on resume.** There's no SF-side state to check (the subscription landing is silent), so re-runs re-render the instructions and re-prompt. That's fine — the prompt is near-instant if the customer already confirmed before, and this skill produces no side-effects. Idempotency is inherent.
+
+7. **No `sf` CLI commands, no SOQL, no HTTP.** This skill should be pure text + one prompt. If a future version wants to probe state (customer-supplied Meta token via env var, etc.), that's an additive enhancement — don't let it crowd the happy path. The instruction-only design is the feature.
+
+8. **Max 2 partners per WABA.** If the customer is already sharing with another BSP (Twilio, 360dialog, etc.), Salesforce would be partner #2 — fine. If they've got 2 BSPs already, Meta blocks the Assign — customer would need to remove one first. This is rare but documented in the Stage 1 rendered text so customers hit a known error message rather than a mysterious failure.
+
+9. **"Full control / Everything" is required, not just the Partial access toggles.** Meta's partner-share dialog has two sections: "Partial access" (individual toggles: Phone numbers view/manage, Message templates view/manage, Manage phone numbers and message templates, Messages) and "Full control" (a single "Everything" toggle). Salesforce needs **Full control / Everything** because:
+   - **Assigning users** — SF provisions service accounts on the WABA to operate it. Only the Everything toggle grants this; none of the Partial access toggles cover it.
+   - **Webhook subscription management** — `POST /{waba-id}/subscribed_apps` (which lets SF's BSP app receive inbound messages) requires `whatsapp_business_management` scope, which maps to Full control, not the partial toggles.
+   - **Credit-line / payment method visibility** — needed so SF can route sends through the customer's own billing. Explicitly only in the "Everything" description ("view payment information").
+
+   If a customer grants only partial access (e.g. just "Manage phone numbers and message templates"), the channel *may* insert successfully on the SF side but activation/send will fail later with opaque Meta errors about missing permissions. The Partial access path is for non-BSP integrations (marketing tools that only need to send templated messages, etc.), not BSPs. Don't let anyone "optimize" the rendered instructions toward narrower permissions — it's a false economy that surfaces as a confusing failure much later in the flow.

package/skills/service-digital-engagement-channel-configure/scripts/check-api-version.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+# Verifies the target org's API version meets the minimum requirement.
+# Usage: check-api-version.sh <min-version> <org-alias>
+# Exits 0 if version >= min-version, exits 1 with error message otherwise.
+
+MIN_VERSION="${1:?Usage: check-api-version.sh <min-version> <org-alias>}"
+ORG_ALIAS="${2:?Usage: check-api-version.sh <min-version> <org-alias>}"
+
+API_VERSION=$(sf org display --target-org "$ORG_ALIAS" --json 2>/dev/null | python3 -c "
+import json, sys
+try:
+    data = json.load(sys.stdin)
+    print(data.get('result', {}).get('apiVersion', ''))
+except Exception:
+    print('')
+")
+
+if [ -z "$API_VERSION" ]; then
+  echo "ERROR: Could not determine API version for org '$ORG_ALIAS'."
+  exit 1
+fi
+
+if python3 -c "import sys; sys.exit(0 if float(sys.argv[1]) >= float(sys.argv[2]) else 1)" "$API_VERSION" "$MIN_VERSION"; then
+  echo "OK: Org API version $API_VERSION meets minimum $MIN_VERSION."
+  exit 0
+else
+  echo "ERROR: Org API version $API_VERSION is below minimum $MIN_VERSION. Generate a sfdx-project.json with \"sourceApiVersion\": \"$MIN_VERSION\" in the metadata output folder."
+  exit 1
+fi

package/skills/service-digital-engagement-messaging-site-integrate/SKILL.md

@@ -28,7 +28,7 @@ The operation is idempotent: if the component is already present it is updated i
 
 ## Scope
 
-- **In scope**: Detecting LWR vs Aura bundle type; scaffolding missing LWR template routes required by the site template (e.g. `too-many-requests`); patching the home-page JSON to insert or update the Embedded Messaging component; staging the bundle into `force-app`; async deploy with polling; resolving the `Network.Name` and publishing the site; guest-URL smoke test; manual Experience Builder fallback with a deep link.
+- **In scope**: Detecting LWR vs Aura bundle type; scaffolding missing LWR template routes required by the site template (e.g. `too-many-requests`); patching all `sfdc_cms__themeLayout/*/content.json` files to insert or update the Embedded Messaging component in the footer region (site-wide placement); staging the bundle into `force-app`; async deploy with polling; resolving the `Network.Name` and publishing the site; guest-URL smoke test; manual Experience Builder fallback with a deep link.
 - **Out of scope**: Creating the `EmbeddedServiceConfig` (Embedded Service Deployment) itself — use `service-digital-engagement-deployment-configure`; creating the `MessagingChannel` — use `service-digital-engagement-channel-configure`; creating the Experience Cloud site itself — use `experience-lwr-site-generate`; generating a standalone JS snippet for a non-Experience website.
 
 ---
@@ -92,15 +92,15 @@ Read `references/bundle_detection.md` for retrieval command shapes and troublesh
 
 3. **Scaffold any missing LWR template routes** (commonly `too-many-requests`) before patching — missing routes fail the deploy. Route+view scaffolding is owned by `experience-lwr-site-generate` (see its `configure-content-route.md`, `configure-content-view.md`, and `handle-component-and-region-ids.md`). Delegate to that skill for the actual scaffold; this skill only supplies the messaging-specific context (which route the deploy is complaining about, and confirmation that the scaffolded pair resolves that specific deploy error). See `references/lwr_route_scaffolding.md` for the delegation pointer.
 
-4. **Patch the home page** by running:
+4. **Patch all themeLayout files** by running:
 
    ```bash
    scripts/patch_lwr_bundle.sh \
-     <retrieve-dir>/digitalExperiences/site/<siteName>/sfdc_cms__view/home/content.json \
+     <retrieve-dir>/digitalExperiences/site/<siteName> \
      <deploymentName> <scrtUrl> <siteEndpoint>
    ```
 
-   The script deterministically walks `.contentBody.component.children[]`, targets the region with `.type == "region"` and `.name == "content"`, and either updates the existing `.definition == "experience_messaging:embeddedMessaging"` component in place (preserving its `id`) or appends a fresh `community_layout:section` wrapper with a JSON-string `sectionConfig`. See `references/lwr_patch.md` for the JSON shapes it emits and how to verify.
+   The script iterates every `sfdc_cms__themeLayout/*/content.json` file. For each, it locates the `footer` region at `.contentBody.component.children[]`, walks into the existing `community_layout:section` wrapper's inner slot region, and either updates the existing `experience_messaging:embeddedMessaging` component in place (preserving its `id`) or appends a fresh component node. Targeting the themeLayout footer makes the widget site-wide (floating overlay on every page), equivalent to the Aura themeFooter placement. See `references/lwr_patch.md` for the JSON shapes and how to verify.
 
 5. Proceed to Phase 4.
 
@@ -195,7 +195,7 @@ Read `references/bundle_detection.md` for retrieval command shapes and troublesh
 | Preserve the existing component `id` when updating in place | Ensures idempotency; the Experience runtime keys off `id` |
 | Every new `id` must be a fresh UUID | Duplicate IDs corrupt the layout and can fail render |
 | LWR uses `definition` / `attributes`; Aura uses `componentName` / `componentAttributes` | Wrong key names silently drop the component from render |
-| LWR `community_layout:section` `sectionConfig` is a JSON string, not a nested object | The Experience CMS serializer expects a string |
+| LWR `community_layout:section` `sectionConfig` lives inside `.attributes` as a JSON string (not a top-level property, not a nested object) | Top-level placement violates the schema's `additionalProperties: false` constraint; the serializer also expects a string not an object |
 | Aura sibling `<siteName>.site-meta.xml` must be copied alongside the bundle | Deploy is rejected without it |
 | Poll the async deploy; do not fire-and-forget | Publish must run only after deploy succeeds |
 | Resolve `Network.Name` from `UrlPathPrefix`, do not reuse site `DeveloperName` | The two are frequently different |
@@ -215,7 +215,7 @@ Read `references/bundle_detection.md` for retrieval command shapes and troublesh
 | `sf community publish` fails with "community not found" | The `Network.Name` differs from site `DeveloperName`; resolve via `UrlPathPrefix` query |
 | Guest URL returns `403` or `503` after publish | Publish is async — retry the smoke test after 60s before falling back to manual |
 | Re-run adds a second messaging component | The recursive search matched on the wrong key name; component detection must use `definition` (LWR) or `componentName` (Aura) |
-| Deploy succeeds but widget does not appear | The messaging component is present in a region that is not on the site's home page — patch `home/content.json` (LWR) or `homeGuestLayout.json` (Aura), not another view |
+| Deploy succeeds but widget does not appear on all pages | For LWR, confirm the component was injected into `sfdc_cms__themeLayout/*/content.json` footer (not `sfdc_cms__view/home/content.json` — that is page-specific). For Aura, confirm `homeGuestLayout.json` was patched (themeFooter region). |
 | `sectionConfig` written as an object | Serialize it as a JSON string; the CMS parser will not accept an object |
 
 ---
@@ -231,8 +231,9 @@ Read `references/bundle_detection.md` for retrieval command shapes and troublesh
 - [ ] For Aura, are the keys `componentName` and `componentAttributes`?
 - [ ] When updating in place, was the existing `id` preserved?
 - [ ] When appending, are all new `id` values fresh UUIDs?
-- [ ] For LWR, is `sectionConfig` a JSON *string* (not a nested object)?
-- [ ] For LWR, do the UUIDs referenced inside `sectionConfig` match the section `id` and child region `id`?
+- [ ] For LWR, did the script patch every `sfdc_cms__themeLayout/*/content.json` (not just `home/content.json`)?
+- [ ] For LWR, does the messaging node appear inside the `footer` region's subtree in each themeLayout?
+- [ ] For LWR, is `clientVersion` set to `"WebV2"` in the messaging node attributes?
 
 ### Deploy
 - [ ] For Aura, was `<siteName>.site-meta.xml` copied alongside the bundle?
@@ -253,7 +254,7 @@ Read `references/bundle_detection.md` for retrieval command shapes and troublesh
 
 Deliverables:
 
-- Modified home-page JSON in the retrieval directory and in `force-app/main/default/...`
+- Modified `sfdc_cms__themeLayout/*/content.json` files (one per themeLayout) in the retrieval directory and in `force-app/main/default/...` (LWR); or modified `homeGuestLayout.json` (Aura)
 - (LWR only, if needed) new `sfdc_cms__route/<RouteApiName>/` + `sfdc_cms__view/<viewId>/` pair for any scaffolded missing route
 - Deploy `job-id` and the final deploy report
 - Publish confirmation