@salesforce/afv-skills 1.32.0 → 1.34.0

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

@@ -0,0 +1,289 @@
+---
+name: service-digital-engagement-messaging-site-integrate
+description: "Integrates a Messaging for In-App and Web (MIAW) Embedded Messaging chat widget into an Experience Cloud site by patching the site's LWR or Aura page bundle, deploying, publishing, and verifying guest access. Use when the user wants to embed messaging on an Experience site, add a chat widget to a community, place the Embedded Messaging component on an LWR or Aura page, wire an embedded service deployment to a site, references the retrieved bundle artifacts (`content.json`, `homeGuestLayout.json`, or a `*.site-meta.xml` file), or automates the retrieve/patch-JSON/deploy/publish flow instead of clicking through Experience Builder. DO NOT TRIGGER when creating the messaging channel (use service-digital-engagement-channel-configure), when creating or updating the EmbeddedServiceConfig deployment (use service-digital-engagement-deployment-configure), or when generating a standalone JavaScript snippet for a non-Experience website."
+metadata:
+  version: "1.0"
+  minApiVersion: "62.0"
+  relatedSkills:
+    - "experience-lwr-site-generate"
+    - "service-digital-engagement-channel-configure"
+    - "service-digital-engagement-deployment-configure"
+  cliTools:
+    - tool: ["curl"]
+      semver: ">=7.0.0"
+    - tool: ["jq"]
+      semver: ">=1.6.0"
+    - tool: ["python3"]
+      semver: ">=3.10.0"
+    - tool: ["sf"]
+      semver: ">=2.0.0"
+---
+
+# Embed Messaging Widget on an Experience Cloud Site
+
+Wires an existing Embedded Messaging (MIAW) deployment onto an Experience Cloud site by retrieving the site's bundle (LWR `DigitalExperienceBundle` or Aura `ExperienceBundle`), patching the home page JSON to place the `experience_messaging:embeddedMessaging` component, staging the bundle into the local project, deploying it, publishing the site, and verifying guest access.
+
+The operation is idempotent: if the component is already present it is updated in place (its `id` is preserved), so re-running with different ESD coordinates cleanly updates.
+
+## 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.
+- **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.
+
+---
+
+## Clarifying Questions
+
+Before executing, ask the user if not already clear:
+
+- **Site name?** The `DeveloperName` of the Experience Cloud site (the metadata folder name under `digitalExperiences/site/<siteName>/` or `experiences/<siteName>/`).
+- **Deployment coordinates?** The `deploymentName` (Embedded Service Deployment `DeveloperName`), the `scrtUrl`, and the `siteEndpoint` (Experience site base URL). All three come from the published `EmbeddedServiceConfig` — obtain from `service-digital-engagement-deployment-configure` output if not provided.
+- **Target org alias?** For the `sf` commands.
+- **URL path prefix?** The site's `UrlPathPrefix` (needed to resolve `Network.Name` for publish and to hit the guest URL for verification).
+
+---
+
+## Required Inputs
+
+Gather or infer before proceeding:
+
+- **Site name** — `DeveloperName` of the site
+- **Deployment name** — `DeveloperName` of the `EmbeddedServiceConfig`
+- **scrtUrl** — SCRT2 endpoint URL from the deployment
+- **siteEndpoint** — Base URL of the Experience site
+- **Target org alias**
+- **URL path prefix** — Site's public URL path segment (e.g. `esw-site`)
+
+Defaults applied to the component's attributes when writing:
+
+- `isExpSiteAuthMode`: `false`
+- `hideChatButtonOnLoad`: `"Default"`
+- `clientVersion`: `"WebV1"`
+
+---
+
+## Workflow
+
+Steps are sequential. If any automated step fails, proceed to the manual fallback (Phase 6) and do not claim the widget is "live" until either the guest-URL smoke test returns `200` or the user confirms manual publish.
+
+### Phase 1 — Detect Bundle Type
+
+1. **Retrieve both candidate bundles** into `<retrieve-dir>`. The script only performs a deterministic path check, so the retrieve calls must run first:
+
+   ```bash
+   sf project retrieve start --metadata "DigitalExperienceBundle:site/<siteName>" \
+     --target-org <org-alias> --target-metadata-dir <retrieve-dir>
+   sf project retrieve start --metadata "ExperienceBundle:<siteName>" \
+     --target-org <org-alias> --target-metadata-dir <retrieve-dir>
+   ```
+
+   Either call may return "no metadata found" — that is expected; the missing bundle simply means the site is the other type.
+
+2. **Run `scripts/detect_bundle_type.sh <retrieve-dir> <siteName>`.** It emits exactly one token to stdout:
+
+   - `LWR` → the LWR marker file exists (`digitalExperiences/site/<siteName>/sfdc_cms__view/home/content.json`). Go to Phase 2.
+   - `AURA` → the Aura marker file exists (`experiences/<siteName>/views/homeGuestLayout.json`). Go to Phase 3.
+   - `UNKNOWN` (exit code 1) → neither marker exists. Skip to the manual fallback in Phase 6.
+
+Read `references/bundle_detection.md` for retrieval command shapes and troubleshooting.
+
+### Phase 2 — Patch the LWR Bundle
+
+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:
+
+   ```bash
+   scripts/patch_lwr_bundle.sh \
+     <retrieve-dir>/digitalExperiences/site/<siteName>/sfdc_cms__view/home/content.json \
+     <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.
+
+5. Proceed to Phase 4.
+
+### Phase 3 — Patch the Aura Bundle
+
+6. **Patch the home guest layout** by running:
+
+   ```bash
+   scripts/patch_aura_bundle.sh \
+     <retrieve-dir>/experiences/<siteName>/views/homeGuestLayout.json \
+     <deploymentName> <scrtUrl> <siteEndpoint>
+   ```
+
+   The script iterates `.regions[]`, picks the first region whose `.components[]` is non-empty, recurses through any `forceCommunity:section` wrappers, and either updates the existing `.componentName == "experience_messaging:embeddedMessaging"` component in place (preserving `id`) or appends a fresh `forceCommunity:section` wrapper. Aura uses `componentName` / `componentAttributes` (not `definition` / `attributes`) and has no `dxpStyle`. See `references/aura_patch.md` for JSON shapes and verification steps.
+
+7. Proceed to Phase 4.
+
+### Phase 4 — Stage and Deploy
+
+8. **Copy the modified bundle into the project's default package.** Use `cp -R` so unchanged files travel with the modified one:
+
+   - LWR: `cp -R <retrieve-dir>/digitalExperiences force-app/main/default/`
+   - Aura: `cp -R <retrieve-dir>/experiences force-app/main/default/` **and also copy** the sibling `<siteName>.site-meta.xml` file — Aura deploys are rejected without it.
+
+9. **Async deploy and poll**:
+
+    ```bash
+    sf project deploy start --source-dir force-app/main/default \
+      --target-org <org-alias> --async
+    ```
+
+    Poll every 15 seconds up to 10 minutes:
+
+    ```bash
+    sf project deploy report --job-id <job-id> --target-org <org-alias>
+    ```
+
+    Stop when status is `Succeeded`, `Failed`, `SucceededPartial`, or `Canceled`. On failure, surface the deploy report and do not proceed to publish. See `references/deploy_and_publish.md` for the full polling loop and common failure modes.
+
+### Phase 5 — Publish and Verify
+
+10. **Resolve the `Network.Name`.** `Network.Name` frequently differs from the site `DeveloperName`, so query it by the URL path prefix rather than guessing:
+
+    ```bash
+    sf data query --query \
+      "SELECT Name FROM Network WHERE UrlPathPrefix='<urlPath>' LIMIT 1" \
+      --target-org <org-alias>
+    ```
+
+11. **Publish the community** with the resolved name:
+
+    ```bash
+    sf community publish --name "<resolved-Name>" --target-org <org-alias>
+    ```
+
+12. **Smoke-test guest access** by hitting the public URL:
+
+    ```bash
+    curl -sL -o /dev/null -w "%{http_code}" \
+      https://<domainHostname>/<urlPath>
+    ```
+
+    Report success only when the response is `200`.
+
+### Phase 6 — Manual Fallback
+
+13. If any automated step fails (bundle undetectable, patch write blocked, deploy fails, publish fails, or guest URL not `200`), print the Experience Builder deep link and verbatim instructions from `references/manual_fallback.md`. Do **not** claim the widget is live until the user confirms.
+
+    The deep link is:
+
+    ```text
+    https://<MyDomain>.lightning.force.com/sfsites/picasso/core/config/commeditor.apexp?...networkId=<Network.Id>
+    ```
+
+    Resolve `<MyDomain>` via `sf org display --target-org <org-alias>` and `<Network.Id>` via:
+
+    ```bash
+    sf data query --query \
+      "SELECT Id FROM Network WHERE UrlPathPrefix='<urlPath>' LIMIT 1" \
+      --target-org <org-alias>
+    ```
+
+    **Do not hardcode either value.** Instruct the user to open Experience Builder, drag the Embedded Messaging component onto the target page, pick the deployment from the property panel, and click Publish.
+
+---
+
+## Rules / Constraints
+
+| Constraint | Rationale |
+|-----------|-----------|
+| Detect bundle type from retrieval output, do not assume | LWR and Aura sites need different files patched with different key names |
+| 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 |
+| 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 |
+| Do not claim "live on the site" until the guest URL returns `200` or the user confirms | Publish is asynchronous; premature success reports mislead |
+| Never hardcode `MyDomain` or `Network.Id` in the manual fallback link | Values are org-specific and must be queried |
+| Idempotency: re-running with new ESD coordinates must update in place | Users iterate on `deploymentName`, `scrtUrl`, `siteEndpoint` during setup |
+
+---
+
+## Gotchas
+
+| Issue | Resolution |
+|-------|------------|
+| `too-many-requests` route missing during LWR deploy | Scaffold the missing route+view pair per `references/lwr_route_scaffolding.md` |
+| Aura deploy rejected with missing site metadata | Copy the sibling `<siteName>.site-meta.xml` from the retrieve dir |
+| Component appended but not rendering | Confirm the region wrapper uses the correct `type: "region"` key and that Aura components use `componentName` (not `definition`) |
+| `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 |
+| `sectionConfig` written as an object | Serialize it as a JSON string; the CMS parser will not accept an object |
+
+---
+
+## Verification Checklist
+
+### Bundle Detection
+- [ ] Was exactly one of `sfdc_cms__view/home/content.json` (LWR) or `views/homeGuestLayout.json` (Aura) found?
+- [ ] If neither was found, did the workflow route to the manual fallback?
+
+### Patch Correctness
+- [ ] For LWR, are the messaging component's keys `definition` and `attributes`?
+- [ ] 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`?
+
+### Deploy
+- [ ] For Aura, was `<siteName>.site-meta.xml` copied alongside the bundle?
+- [ ] Was the async deploy polled until a terminal status?
+- [ ] Is the terminal status `Succeeded` or `SucceededPartial` before proceeding to publish?
+
+### Publish
+- [ ] Was `Network.Name` resolved via `UrlPathPrefix`, not reused from site `DeveloperName`?
+- [ ] Did `sf community publish` complete without error?
+
+### Verify
+- [ ] Did the guest URL curl return `200`?
+- [ ] Did the workflow refrain from claiming success until `200` was observed or the user confirmed manual publish?
+
+---
+
+## Output Expectations
+
+Deliverables:
+
+- Modified home-page JSON in the retrieval directory and in `force-app/main/default/...`
+- (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
+- Guest URL smoke-test HTTP status
+- On failure: the Experience Builder deep link and manual instructions
+
+Do not produce the `EmbeddedServiceConfig` or the `MessagingChannel` metadata — those are the responsibilities of the deployment and channel skills below.
+
+---
+
+## Cross-Skill Integration
+
+| Need | Delegate to |
+|------|-------------|
+| Create or update the Embedded Service Deployment | `service-digital-engagement-deployment-configure` |
+| Create the underlying MIAW messaging channel | `service-digital-engagement-channel-configure` |
+| Create the Experience Cloud LWR site itself | `experience-lwr-site-generate` |
+| Scaffold a missing LWR route + view pair (e.g. `too-many-requests`) | `experience-lwr-site-generate` (route/view creation, ID handling) |
+
+---
+
+## Reference File Index
+
+| File | When to read |
+|------|-------------|
+| `references/bundle_detection.md` | Phase 1 — LWR vs Aura retrieval and disambiguation |
+| `references/lwr_route_scaffolding.md` | Phase 2 — delegation pointer for scaffolding missing LWR template routes (owned by `experience-lwr-site-generate`) |
+| `references/lwr_patch.md` | Phase 2 — what `patch_lwr_bundle.sh` does and how to verify its output |
+| `references/aura_patch.md` | Phase 3 — what `patch_aura_bundle.sh` does and how to verify its output |
+| `references/deploy_and_publish.md` | Phases 4–5 — staging into `force-app`, async deploy polling, publish, and guest-URL smoke test |
+| `references/manual_fallback.md` | Phase 6 — Experience Builder deep link and manual drag-drop-publish instructions |
+| `scripts/detect_bundle_type.sh` | Phase 1 — deterministic LWR/Aura/UNKNOWN detection over a retrieved bundle |
+| `scripts/patch_lwr_bundle.sh` | Phase 2 — idempotent LWR `content.json` patch (insert or update in place) |
+| `scripts/patch_aura_bundle.sh` | Phase 3 — idempotent Aura `homeGuestLayout.json` patch (insert or update in place) |

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

@@ -0,0 +1,54 @@
+# Aura — Patching `homeGuestLayout.json`
+
+Target file:
+
+```text
+experiences/<siteName>/views/homeGuestLayout.json
+```
+
+The patch is applied by `scripts/patch_aura_bundle.sh`. Invoke as:
+
+```bash
+scripts/patch_aura_bundle.sh <homeGuestLayout.json> <deploymentName> <scrtUrl> <siteEndpoint>
+```
+
+Aura differs from LWR: component keys are `componentName` / `componentAttributes` (not `definition` / `attributes`), and there is no `dxpStyle` field. See `manual_fallback.md` if the script cannot run.
+
+## What the script does
+
+1. Reads `<homeGuestLayout.json>` with `jq`.
+2. Iterates `.regions[]` and selects the first region whose `.components[]` is non-empty.
+3. Recursively searches components (descending through every level of `forceCommunity:section` wrapper's `componentAttributes.regions[].components[]`) for `.componentName == "experience_messaging:embeddedMessaging"`.
+4. **If found** — updates that node's `.componentAttributes` to the six standard values and **preserves the existing `.id`**:
+   - `deploymentName`, `scrtUrl`, `siteEndpoint` (from CLI args)
+   - `isExpSiteAuthMode: false`, `hideChatButtonOnLoad: "Default"`, `clientVersion: "WebV1"`
+5. **If absent** — appends a fresh `forceCommunity:section` wrapper. The nested region carries `id`, `type: "region"`, `regionLabel: "Column"`, `regionName: "column"`, `renditionMap: {}`.
+6. Writes the file back with jq's 2-space indentation.
+
+Re-running is idempotent — the script updates in place rather than appending a second wrapper.
+
+## How to verify
+
+- Exactly one messaging node exists:
+
+  ```bash
+  jq '[.. | select(.componentName? == "experience_messaging:embeddedMessaging")] | length' <homeGuestLayout.json>
+  # → 1
+  ```
+
+- All new IDs are UUIDs (no reused IDs from the fixture):
+
+  ```bash
+  jq '[.. | .id? // empty] | unique | length' <homeGuestLayout.json>
+  ```
+
+- The sibling `<siteName>.site-meta.xml` still exists in the retrieve directory — it must be copied at deploy time or the deploy will be rejected.
+
+## Common failures
+
+| Symptom | Cause |
+|---------|-------|
+| Deploy succeeds but chat button never appears | Wrote `definition` instead of `componentName` |
+| Section deployed but empty | Nested region missing `type: "region"` or `renditionMap` |
+| Deploy fails with "site metadata not found" | Sibling `<siteName>.site-meta.xml` was not copied alongside the `experiences/` bundle |
+| Two chat buttons after re-run | Detection did not recurse through `forceCommunity:section` wrappers' nested regions |

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

@@ -0,0 +1,56 @@
+# Bundle Detection — LWR vs Aura
+
+Experience Cloud sites ship in two bundle shapes. Detect which one the target site uses by trying to retrieve each in turn and inspecting the resulting directory tree — the shape of the bundle uniquely identifies the framework.
+
+## LWR retrieve
+
+LWR (Lightning Web Runtime) sites live under `DigitalExperienceBundle`. Each site is stored as `site/<siteName>`.
+
+```bash
+sf project retrieve start \
+  --metadata "DigitalExperienceBundle:site/<siteName>" \
+  --target-org <org-alias> \
+  --target-metadata-dir <retrieve-dir>
+```
+
+Success indicator — the following file exists:
+
+```text
+<retrieve-dir>/digitalExperiences/site/<siteName>/sfdc_cms__view/home/content.json
+```
+
+If present, the site is LWR. The bundle also contains sibling directories like `sfdc_cms__route/<RouteApiName>/`, `sfdc_cms__view/<viewId>/`, and `sfdc_cms__theme/`.
+
+## Aura retrieve
+
+Aura Experience sites live under `ExperienceBundle`.
+
+```bash
+sf project retrieve start \
+  --metadata "ExperienceBundle:<siteName>" \
+  --target-org <org-alias> \
+  --target-metadata-dir <retrieve-dir>
+```
+
+Success indicator — the following file exists:
+
+```text
+<retrieve-dir>/experiences/<siteName>/views/homeGuestLayout.json
+```
+
+If present, the site is Aura. Look for a sibling `<siteName>.site-meta.xml` at `<retrieve-dir>/sites/<siteName>.site-meta.xml`. That file must be copied alongside the Aura bundle at deploy time.
+
+## Neither
+
+If retrieval succeeds for both but neither indicator file exists, the site is likely a Salesforce Tabs + Visualforce or Site.com site — the automated JSON patching path does not apply. Route to the manual Experience Builder fallback.
+
+If both retrievals fail (site not found, permission denied), surface the error to the user and stop before attempting to patch anything.
+
+## Troubleshooting
+
+| Symptom | Likely cause | Resolution |
+|---------|--------------|------------|
+| `INVALID_METADATA` for both retrievals | Site `DeveloperName` is wrong | Query the org: `sf data query --query "SELECT DeveloperName, UrlPathPrefix FROM Network"` |
+| LWR retrieve succeeds but has no `content.json` | Site template is minimal or corrupt | Ask the user to open Experience Builder once so the platform materializes the default views |
+| Aura retrieve succeeds but no `homeGuestLayout.json` | Guest access disabled on the site | Fall back to `homeLayout.json` for authenticated-only sites, but note that the messaging widget then requires `isExpSiteAuthMode: true` |
+| Retrieve hangs | Large bundle | Use `--wait 30` and confirm with the user that retrieval is in-flight |

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

@@ -0,0 +1,101 @@
+# Deploy, Publish, and Verify
+
+Once the home page JSON has been patched (and any missing LWR routes scaffolded), stage the bundle into the project's default package, deploy asynchronously with polling, resolve the community's `Network.Name`, publish, and smoke-test the guest URL.
+
+## Stage into `force-app`
+
+The retrieval directory is not directly deployable — the modified bundle must live inside the project's default package.
+
+- **LWR**:
+
+  ```bash
+  cp -R <retrieve-dir>/digitalExperiences force-app/main/default/
+  ```
+
+- **Aura** — copy the bundle **and** the sibling site metadata (deploy fails without it):
+
+  ```bash
+  cp -R <retrieve-dir>/experiences force-app/main/default/
+  cp <retrieve-dir>/sites/<siteName>.site-meta.xml force-app/main/default/sites/
+  ```
+
+  If `force-app/main/default/sites/` does not exist, create it first.
+
+## Async deploy
+
+Start the deploy in the background so subsequent polling can report progress:
+
+```bash
+sf project deploy start \
+  --source-dir force-app/main/default \
+  --target-org <org-alias> \
+  --async
+```
+
+Capture the returned `job-id`.
+
+## Poll to completion
+
+Every 15 seconds, up to 10 minutes:
+
+```bash
+sf project deploy report \
+  --job-id <job-id> \
+  --target-org <org-alias>
+```
+
+Terminal statuses:
+
+| Status | Meaning | Next action |
+|--------|---------|-------------|
+| `Succeeded` | Deploy complete | Proceed to publish |
+| `SucceededPartial` | Some components skipped | Inspect the report; proceed if messaging component was among the succeeded set |
+| `Failed` | Deploy failed | Surface the error and stop; do not publish |
+| `Canceled` | User or platform canceled | Surface and stop |
+
+If the timeout elapses without a terminal status, surface the last report and stop — publishing a partially deployed bundle can leave the site in an inconsistent state.
+
+## Resolve `Network.Name`
+
+`Network.Name` differs from the site `DeveloperName` in most orgs. Query by URL path prefix:
+
+```bash
+sf data query \
+  --query "SELECT Name FROM Network WHERE UrlPathPrefix='<urlPath>' LIMIT 1" \
+  --target-org <org-alias>
+```
+
+Capture the `Name` value.
+
+## Publish
+
+```bash
+sf community publish \
+  --name "<resolved-Name>" \
+  --target-org <org-alias>
+```
+
+Publishing is asynchronous on the platform side even though the CLI call returns quickly — the guest smoke test may need a short delay before the new render is served.
+
+## Guest URL smoke test
+
+```bash
+curl -sL -o /dev/null -w "%{http_code}" \
+  https://<domainHostname>/<urlPath>
+```
+
+- `200` → the site is rendering; the messaging widget should be visible.
+- `403` or `503` → publish likely still propagating. Retry once after 60 seconds before falling back to manual.
+- Any other status → surface as failure and route to the manual fallback.
+
+Report success only when the response is `200`. Do not claim the widget is "live on the site" based solely on the deploy report.
+
+## Common failures
+
+| Symptom | Likely cause | Resolution |
+|---------|--------------|------------|
+| Deploy fails with missing route type (LWR) | Template requires an unresolved route | Scaffold per `lwr_route_scaffolding.md` |
+| Deploy fails with "site metadata not found" (Aura) | `<siteName>.site-meta.xml` not staged | Copy the sibling `.site-meta.xml` |
+| `sf community publish` returns "community not found" | Used site `DeveloperName` instead of `Network.Name` | Re-run the `Network.Name` query |
+| Guest URL stays 403 after retry | Public access disabled on the site | Enable public access in Experience Builder, or set `isExpSiteAuthMode: true` on the messaging component |
+| Async deploy hangs indefinitely | Large bundle | Extend the polling window; do not silently succeed |

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

@@ -0,0 +1,55 @@
+# LWR — Patching `home/content.json`
+
+Target file:
+
+```text
+digitalExperiences/site/<siteName>/sfdc_cms__view/home/content.json
+```
+
+The patch is applied by `scripts/patch_lwr_bundle.sh`. Invoke as:
+
+```bash
+scripts/patch_lwr_bundle.sh <content.json> <deploymentName> <scrtUrl> <siteEndpoint>
+```
+
+The manual JSON walk is preserved below in `manual_fallback.md` for cases where the script cannot run (jq missing, unusual template shape, etc.).
+
+## What the script does
+
+1. Reads `<content.json>` with `jq`.
+2. Walks `.contentBody.component.children[]` and locates the region where `.type == "region"` and `.name == "content"`.
+3. Recursively checks whether any descendant node already has `.definition == "experience_messaging:embeddedMessaging"`.
+4. **If found** — updates that node's `.attributes` to the six standard values and **preserves the existing `.id`**:
+   - `deploymentName`, `scrtUrl`, `siteEndpoint` (from CLI args)
+   - `isExpSiteAuthMode: false`, `hideChatButtonOnLoad: "Default"`, `clientVersion: "WebV1"`
+5. **If absent** — appends a fresh `community_layout:section` wrapper. The wrapper's `sectionConfig` is a **JSON string** (not a nested object), and the UUID inside `sectionConfig.columns[0].id` matches the child region's `id`. The nested region carries `id`, `name: "column"`, `title: "Column"`, `type: "region"`.
+6. Writes the file back with jq's 2-space indentation.
+
+Re-running with the same arguments is a no-op (idempotent); re-running with new deployment coordinates refreshes the attributes in place without changing the component's `id`.
+
+## How to verify
+
+- Exactly one messaging node exists:
+
+  ```bash
+  jq '[.. | select(.definition? == "experience_messaging:embeddedMessaging")] | length' <content.json>
+  # → 1
+  ```
+
+- `sectionConfig` is a string, not an object:
+
+  ```bash
+  jq '.. | select(.definition? == "community_layout:section") | .sectionConfig | type' <content.json>
+  # → "string"
+  ```
+
+- The section's `id` and the child region's `id` both appear inside the `sectionConfig` string.
+
+## Common failures
+
+| Symptom | Cause |
+|---------|-------|
+| Deploy succeeds but chat button never appears | `sectionConfig` was written as an object, not a JSON string |
+| Two chat buttons on the page after re-run | Detection did not descend into nested `community_layout:section` wrappers; the script's recursive check avoids this |
+| Deploy error "component not registered" | Used `componentName` (Aura shape) instead of `definition` (LWR shape) |
+| Section renders but is empty | Nested region is missing `type: "region"` |

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

@@ -0,0 +1,31 @@
+# LWR Route Scaffolding — Delegation
+
+Some LWR site templates declare route types in their theme that the retrieved bundle does not contain (commonly `too-many-requests`). If a required route is missing at deploy time, the deploy fails with a route-type validation error.
+
+Route + view creation is owned by **`experience-lwr-site-generate`**. This skill does not duplicate that procedure. Delegate to that skill and pass through the messaging-specific context.
+
+## When to invoke the delegate
+
+Trigger the delegation when the messaging-widget deploy in Phase 4 fails with a missing-route or missing-view error mentioning a `routeType` that is not present under `digitalExperiences/site/<siteName>/sfdc_cms__route/`.
+
+## What to hand off
+
+Give `experience-lwr-site-generate` these three items:
+
+- **Site name** — `<siteName>` (same value used throughout this skill).
+- **Route type reported by the deploy error** — e.g. `too-many-requests`.
+- **Retrieve directory** — `<retrieve-dir>` so the scaffolded pair lands next to the existing route/view directories.
+
+The delegate skill covers the full procedure: `configure-content-route.md` (route file shape), `configure-content-view.md` (view file shape), and `handle-component-and-region-ids.md` (fresh-UUID stamping so the scaffolded view does not collide with existing IDs).
+
+## Messaging-specific delta
+
+After the delegate returns, verify the specific deploy error is cleared before proceeding:
+
+```bash
+sf project deploy validate --source-dir force-app/main/default --target-org <org-alias>
+```
+
+If the validation surfaces additional missing route types, re-invoke the delegate for each. Only proceed to Phase 4's real deploy once validation passes.
+
+If the delegate is unavailable, fall back to Phase 6's manual Experience Builder path — do **not** attempt to scaffold routes ad-hoc from this skill.

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

@@ -0,0 +1,65 @@
+# Manual Fallback — Experience Builder Deep Link
+
+Use this fallback when any automated step fails: bundle undetectable, patch write blocked, deploy fails and cannot be repaired, publish fails, or the guest URL smoke test never returns `200`.
+
+Print the deep link and verbatim instructions below to the user. Do **not** claim the messaging widget is live on the site until the user has confirmed they completed the Publish step in Experience Builder.
+
+## Resolve org-specific values
+
+Never hardcode either value. Query them per run:
+
+- **`MyDomain`** — take the `Instance URL` (or `Login URL`) from:
+
+  ```bash
+  sf org display --target-org <org-alias>
+  ```
+
+  Strip protocol and trailing slash. Typical form: `<mydomain>.lightning.force.com`.
+
+- **`Network.Id`** — query by URL path prefix:
+
+  ```bash
+  sf data query --query \
+    "SELECT Id FROM Network WHERE UrlPathPrefix='<urlPath>' LIMIT 1" \
+    --target-org <org-alias>
+  ```
+
+## Deep link template
+
+Substitute the resolved values into:
+
+```text
+https://<MyDomain>.lightning.force.com/sfsites/picasso/core/config/commeditor.apexp?...networkId=<Network.Id>
+```
+
+The `...` in the path represents any additional query-string parameters the org may require (some orgs redirect through an intermediate SSO step); take them from the org's own Experience Builder URL rather than fabricating them.
+
+## Verbatim user instructions
+
+Provide the user the following steps (adapt the deployment name to the one they supplied):
+
+1. Open the deep link above. Salesforce may prompt for login; use an admin credential for the target org.
+2. Once Experience Builder opens on the target site's home page, use the left-hand **Components** panel and drag the **Embedded Messaging** component onto the page. Drop it into the main content region — most templates render it at the bottom right regardless of exact drop position.
+3. In the right-hand **Property panel** that appears after the drop:
+   - **Deployment** — pick the deployment named `<deploymentName>` from the picklist. If it is not listed, confirm the Embedded Service Deployment has been published via Connect API.
+   - Leave `Hide Chat Button on Load` set to **Default** unless the user needs the button hidden.
+   - Leave `Auth Mode` unchecked for public sites (equivalent to `isExpSiteAuthMode: false`).
+4. Click **Publish** in the top-right of Experience Builder. Confirm the publish dialog.
+5. Wait 30–60 seconds for propagation, then reload the site's public URL. The chat button should appear.
+
+## Reporting back
+
+Once the user confirms publish in Experience Builder, re-run the guest URL smoke test:
+
+```bash
+curl -sL -o /dev/null -w "%{http_code}" \
+  https://<domainHostname>/<urlPath>
+```
+
+Report success only when the response is `200`. If the user reports the button still does not appear, gather:
+
+- The specific step where the automated flow failed.
+- The `sf project deploy report` output (if a deploy was attempted).
+- The `Network.Name` and `Network.Id` values used.
+
+These are the minimum context needed to escalate to platform support.