@salesforce/afv-skills 1.32.0 → 1.34.0

package/skills/service-helpagent-coordinate/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: service-helpagent-coordinate
+description: "Use to set up, configure, ground, or go live with a Salesforce Help Agent (an Agentforce Service Agent in Service Cloud) via a guided four-checkpoint flow. Use whenever a user says any of: set up / create / build / add a help agent, service agent, or support chat agent; add or embed a chat widget on a website or Experience Cloud / LWR site; put a help agent on a channel (web chat, voice, phone, help portal), even while rejecting web chat; ground a help agent on Salesforce Knowledge; or wants an AI to answer customer questions, manage support cases, and escalate to a human. The right skill even when the request names only one part, names a coming-soon channel this skill hard-stops on, or references help-agent-spec.md or the Agentforce Quick Setup wizard. DO NOT TRIGGER when authoring a brand-new agent with no Help Agent lineage (use agentforce-generate), configuring OAuth/ECAs (use integration-connectivity-connected-app-configure), or only deploying metadata (use platform-metadata-deploy)."
+allowed-tools: Bash Read Write Edit Glob Grep WebFetch AskUserQuestion TodoWrite
+metadata:
+  version: "0.9"
+  minApiVersion: "67.0"
+  relatedSkills:
+    - "agentforce-generate"
+    - "dx-org-permission-set-assign"
+    - "experience-lwr-site-generate"
+    - "integration-connectivity-connected-app-configure"
+    - "platform-metadata-deploy"
+    - "service-digital-engagement-channel-configure"
+    - "service-digital-engagement-deployment-configure"
+    - "service-digital-engagement-messaging-site-integrate"
+  cliTools:
+    - tool: ["curl"]
+      semver: ">=7.0.0"
+    - tool: ["sf"]
+      semver: ">=2.139.6"
+---
+
+# service-helpagent-coordinate: Service Cloud Help Agent, guided setup
+
+Use this skill to stand up a **Service Cloud Help Agent** (an Agentforce Service Agent) on a Salesforce org from Claude Code, following the same guided flow as the Help Agent Quick Setup wizard. This is a **coordinate** skill: it orchestrates existing skills against a canonical spec — it does **not** author a new agent primitive.
+
+## Why this skill exists
+
+Salesforce's official Help Agent template-creation API is not yet shipped. Without it, Claude has no built-in concept of "Help Agent" and would otherwise generate a generic agent. `assets/help-agent-spec.md` substitutes for the missing API: its agent script is the canonical template the eventual Quick Start UI will produce. Treat the spec as source of truth for the agent's lineage (topics, actions, instructions).
+
+## Scope
+
+**In scope:**
+- Guided, four-checkpoint Help Agent setup (identity → grounding → channel → go-live)
+- Knowledge grounding via Agentforce Data Library (ADL)
+- Web Chat / Help Portal channel setup and Experience Cloud site embed
+- Readiness checks (licenses, Einstein Agent User, Data Cloud permission sets)
+
+**Out of scope — delegate elsewhere:**
+- OAuth / External Client App setup → [integration-connectivity-connected-app-configure](../integration-connectivity-connected-app-configure/SKILL.md)
+- Raw agent authoring with no Help Agent lineage → `agentforce-generate`
+- Metadata deploy/retrieve → `platform-metadata-deploy`
+
+## Prerequisites
+
+- Claude Code + Salesforce CLI installed and an authenticated org (see repo `README.md`)
+- MCP servers registered: `salesforce-api-context`, `metadata-experts`, `sobject-reads`
+- Salesforce Skills installed into `.agents/skills/` (or `.claude/skills/`)
+- **A Salesforce org with the required features enabled (or enable-able via metadata):** Agentforce, Einstein Generative AI, Knowledge, Experience Cloud, and Data Cloud. Any org shape that meets this bar works — production, sandbox, scratch, or Developer Edition. The readiness check in `assets/help-agent-spec.md` §4.0 detects each feature and enables what can be enabled; it stops with a clear message if a required capability is missing and cannot be turned on.
+
+## Skills this coordinates
+
+The spec feeds these existing skills — do **not** author a new Help Agent skill:
+
+| Skill | Role |
+|---|---|
+| `agentforce-generate` | Agent authoring + ADL provisioning/grounding (see its `references/data-library-reference.md`, `references/org-setup-for-adl.md`) |
+| `dx-org-permission-set-assign` | Data Cloud permission-set assignment |
+| `service-digital-engagement-channel-configure` | Messaging channel setup (uses `sessionHandlerAsa` for AgentforceServiceAgent routing — see `references/channel-web-chat.md`) |
+| `service-digital-engagement-deployment-configure` | Embedded Service Deployment (targets `SiteType = 'ChatterNetworkPicasso'` sites — Aura won't work) |
+| `experience-lwr-site-generate` | Experience Cloud (LWR) site — used when the org has no Live LWR site yet |
+| `service-digital-engagement-messaging-site-integrate` | Widget placement + embed (Checkpoint 3.5 / 4) |
+
+## Workflow
+
+Read `assets/help-agent-spec.md` first — it is the authoritative flow and is intentionally kept small. **Do not pre-load the rest.** The heavy or conditional material is split into `references/` and read only when the flow reaches it (progressive disclosure — this is deliberate, to keep token usage low):
+
+- **`references/agent-script.md`** — the ~500-line canonical agent script + placeholder list. Load it **only when you are ready to create the agent, after Checkpoint 2** — not during Checkpoints 1, 3, or 4.
+- **`references/channel-web-chat.md`** — Web Chat provisioning detail. Load **only if the user picks Web Chat** at Checkpoint 3.
+- **`references/channel-help-portal.md`** / **`references/channel-voice.md`** — coming-soon channel hard-stops. Load only if the user picks that channel.
+
+Read the one channel file that matches the user's selection — never all three. Then run the interactive setup **without one-shotting**: walk the user through four checkpoints in order, waiting for a reply at each.
+
+### Readiness check (silent, MANDATORY, do not reorder)
+Order is load-bearing — running step 3 before step 2 fails with `PermissionSet not found: GenieUserEnhancedSecurity` because the Data Cloud permission sets do not exist in the org until Data Cloud itself is turned on:
+1. Verify licenses + Einstein Agent User.
+2. **Enable Data Cloud** — must complete before step 3 (permission sets don't exist until Data Cloud is on). If Data Cloud is not yet provisioned, offer the user the choice up front — enable and come back later, or wait through it now.
+3. **CRITICAL — Assign the Data Cloud permission sets immediately after enablement.** Non-negotiable — skipping it ships an agent whose grounding returns empty `knowledgeSummary` at runtime even though ADL indexing reports SUCCESS.
+
+Also verify the `SvcCopilotTmpl` and `EmployeeCopilot` namespaces are present. These are Salesforce out-of-the-box platform artifacts surfaced by `enableEinsteinGptPlatform: true` — not AppExchange managed packages — and will not appear in `sf package installed list`. Probe the namespace directly (e.g. `SELECT DeveloperName FROM Flow WHERE NamespacePrefix = 'SvcCopilotTmpl' LIMIT 1`).
+
+### Recognizing where the user is entering
+Do not assume every run starts at Checkpoint 1. Read the opening prompt and enter at the right checkpoint: if identity is already decided, start at Checkpoint 2 (grounding); if grounding is already in place, start at Checkpoint 3 (channel). Never restart at Checkpoint 1 or re-ask decisions the user already stated. If the opening prompt names **Voice / phone / telephony / IVR / Amazon Connect**, asks to "reach" or "contact" the agent "by phone" / "by call", or asks for it "as a Voice channel" (even phrased as a rejection of web chat), or **Help Portal** as the channel, take the coming-soon hard stop immediately: respond verbatim *"This feature is coming soon, please select Web Chat."* and re-present the channel options — do not run the checkpoints or write any Voice/Help-Portal plan.
+
+### Checkpoint 1 — Meet Your Agent
+Agent name, language, greeting, tone. Offer defaults.
+
+### Checkpoint 2 — Give Your Agent Context (grounding)
+Ask which knowledge source (Salesforce Knowledge / files / website sync). Grounding is **provisioning an Agentforce Data Library**, not designing a search — the agent's `knowledge:` block does the retrieval at runtime. This checkpoint MUST produce all five of:
+1. **Delegate provisioning to `agentforce-generate`** — it owns ADL create/index/publish. Do not hand-roll data-library metadata.
+2. **A dedicated, named library** — create `Help_Agent_Knowledge`. **Never wire the stock `All_Records_and_Fields_Default`** (it sits in `NOT_SCHEDULED` on trial or preloaded sample-data orgs and returns empty `knowledgeSummary` with no error).
+3. **Category selection** — for Salesforce Knowledge, query the org's Data Category Groups and ask which categories to ground on. Do not assume "all."
+4. **Wait-for-indexing gate** — poll and only proceed once `indexingStatus.status ∈ {COMPLETED, READY, SUCCESS}`. `NOT_SCHEDULED` is not success.
+5. **Capture the `rag_feature_config_id`** (format `ARFPC_<libraryId>`) and wire it into the agent script's `knowledge:` block — never hardcode.
+
+**Anti-rule:** never respond to a grounding request by designing a SOQL/SOSL/GraphQL/Apex search over Knowledge articles. Grounding is ADL provisioning; retrieval is the agent's job at runtime.
+
+### Checkpoint 3 — Add to Channels
+Web Chat / Help Portal / Voice. Create messaging channel + Embedded Service Deployment; locate the target site via a **query-first pattern**:
+
+```sql
+SELECT Id, Name, UrlPathPrefix, SiteType, Status
+FROM Site
+WHERE SiteType = 'ChatterNetworkPicasso' AND Status = 'Live'
+```
+
+Only ever present or target `ChatterNetworkPicasso` (LWR) sites — never Aura (`ChatterNetwork`). Resolve the site **in the same turn**, do not defer:
+- **Zero Live LWR sites** → create one via `experience-lwr-site-generate` (recommend the Help Center template).
+- **Exactly one** → confirm it with the user before using (an existing site may serve a different audience); do not silently adopt it.
+- **Multiple** → in the SAME turn, show the executed SOQL, enumerate the results as a table (`Name | UrlPathPrefix | Id`), state plainly "no site is created or modified until you choose," then ask which one to target (include a "create a new site instead" option). Do not answer "I'll query and get back to you" — run the query and present results now.
+
+Do not filter by hardcoded name or URL path prefix — the correct site depends on the customer's org.
+
+**Coming-soon channels are hard stops.** If the user selects **Help Portal** or **Voice**, respond verbatim *"This feature is coming soon, please select Web Chat."*, re-present the channel options, and wait. Never write a provisioning plan, phone number, portal site, or "planning-only" scaffold for these channels — even adjacent objects produce broken half-configurations. See `references/channel-voice.md` / `references/channel-help-portal.md`.
+
+### Checkpoint 3.5 — Silent pre-flight (INTERNAL — never announce)
+Run silently; surface output only on failure. Every check must pass before Checkpoint 4:
+1. Data Cloud access in place for running user **and** Einstein Agent User (defer to `agentforce-generate`).
+2. ADL is Activated **and** grounded — run a canary retrieval with the captured `rag_feature_config_id`; if empty despite SUCCESS, surface the **Known manual step** (Data Space scope on the permission set) verbatim, wait for confirmation, re-run.
+3. Messaging channel is **Active** (assert status; activation is `service-digital-engagement-channel-configure`'s job, not the site-integrate skill's), **and** the widget is actually placed — independently re-read the deployed guest-layout JSON for the `experience_messaging:embeddedMessaging` node rather than trusting the site-integrate skill's 200-only signal; inject if missing.
+
+### Checkpoint 4 — Review & Go Live
+Embed (LWR + Aura), then complete four explicit go-live steps: (a) wire the **Escalation Flow** to the agent (reuse `Help_Agent_Escalation_Flow` if it already exists — do not create a duplicate); (b) confirm the **Messaging Channel is Active** in Setup → Messaging Settings; (c) **Publish the Embedded Service Deployment** in Setup → Embedded Service Deployments; (d) offer to test together. An unpublished deployment or an inactive channel silently ships a dead widget.
+
+## Rules / Constraints
+
+| Rule | Rationale |
+|---|---|
+| Never one-shot the setup | It is a guided conversation; wait for user input at each checkpoint |
+| Never skip or reorder the readiness steps | Permission sets don't exist before Data Cloud enablement — you'll see `PermissionSet not found: GenieUserEnhancedSecurity` |
+| Never advance past 3.5 with empty ADL retrieval | Ships a silently-broken agent |
+| Never hardcode a site name or URL path prefix | The correct target LWR site depends on the customer's org — query first, then decide |
+| Never assume `SvcCopilotTmpl` / `EmployeeCopilot` are packages | They are OOB namespaces surfaced by `enableEinsteinGptPlatform`; probe the namespace directly |
+| Never wire an Embedded Service Deployment to an Aura (`ChatterNetwork`) site | It must target `ChatterNetworkPicasso` (LWR) or the widget will fail silently |
+| Create the Embedded Service Deployment as V2 via the Connect API, never bare Metadata deploy — and embed the V2 ESD via the `experience_messaging:embeddedMessaging` LWR component | Metadata API defaults to legacy V1 (`WebV1`, *"Web (v1)"* in Setup) which breaks Enhanced Web Chat; create via Connect API on v67.0+ with `clientVersion: WebV2`. The customer widget mounts via the LWR component keyed on `deploymentName` (not a bootstrap `<script>`). Full six-attribute shape, the Tooling-API patch path, and guest-browser verification are in `references/channel-web-chat.md` — do NOT verify with <!-- skill-validate: ignore-start -->`curl \| grep`<!-- skill-validate: ignore-end --> |
+| Always create a dedicated ADL for the Help Agent — never wire the stock `All_Records_and_Fields_Default` library | On trial or preloaded sample-data orgs the stock library is stuck in `NOT_SCHEDULED` and never indexes; wiring the agent to it produces empty `knowledgeSummary` at runtime with no visible error. Create `Help_Agent_Knowledge` at Checkpoint 2 and wait for `indexingStatus ∈ {COMPLETED, READY, SUCCESS}` before wiring |
+| Never leave Checkpoint 4 without publishing the Embedded Service Deployment and activating the channel | Both are required for the widget to actually serve on the site. If the ESD was created via the Connect API `deployment/setup` call, it is already published — verify *"Published on:"* is stamped (not empty) and the title has no `(v1)` suffix |
+| Web Chat is the only buildable channel; Voice and Help Portal are hard stops | Coming-soon channels have no supporting skill — respond verbatim *"This feature is coming soon, please select Web Chat."* and re-present options; never scaffold. For Web Chat, always run the post-deploy assertion (re-fetch the MessagingChannel, assert `embeddedConfig.authMode`; default `UnAuth`) — a wrong choice silently ships a widget that won't render for guests. The report names `authMode` as a bare value (`authMode: UnAuth`); do not narrate the rationale or the assertion in the report. Never emit a legacy `esw.min.js` / Live Agent V1 snippet |
+
+## Output Expectations
+
+The one deliverable is a single `report.md`: a **status report of what was decided and done**, not a design doc, plan, or architecture write-up. Two rules govern quality:
+
+1. **Report concrete outcomes, never intentions.** Write what *is* — the decided value, the created resource, the resolved ID — not what you *would* or *plan to* do. If a step could not run to completion because this is a non-interactive run, **decide the sensible default, state it as the decision, and report it as such** — do not stall on "awaiting confirmation," "to be resolved," "pending user input," or "please provide…". Hedging language ("will create", "to be executed", "once confirmed") reads as an unfinished plan and is scored as incomplete. Name the agent, the locale, the grounding source, `authMode`, the ADL name, the `rag_feature_config_id`, the site `UrlPathPrefix`, the ESD publish state — as settled facts.
+2. **No padding, no scaffolding prose.** No preamble, no design-doc sections, no restating the prompt. Dense, declarative lines only.
+
+**Before writing, choose the report shape by what the run actually did. There are three:**
+- **A coming-soon stop** — the run hard-stopped on a coming-soon channel (Voice / Help Portal).
+- **A settled-facts report** — the flow *executed a step*: the user directed a concrete action ("set up the grounding", "put it on <named site>") and every input was supplied or has a sensible skill-owned default. Report what was decided and done.
+- **A guided-decision report** — the flow is at a *decision the user owns*: an opening request with no agent details yet ("set up a help agent", "add a chat widget"), **or** a checkpoint surfacing multiple real alternatives the skill must not invent (e.g. several Live LWR sites). Presenting the checkpoint's questions/options *is* the deliverable; stay draft-first.
+
+Use the settled-facts report, not the guided-decision one, when the missing value is a mechanical default the skill can just pick (data category → org default) — decide it and report it done. Use the guided-decision report only when the choice genuinely belongs to the user (identity at an opener; which of several existing sites). The guided-decision report is **not** an escape hatch for hedging on an execute request.
+
+**Coming-soon stop — the flow hard-stopped on a coming-soon channel (Voice / Help Portal).** Short and fixed — the four H2 sections below, nothing more. Do NOT describe how Voice/Portal would be built, do NOT list architecture options, telephony, IVR, Amazon Connect, or "planning-only" steps — that content is an automatic fail. Write exactly:
+
+```markdown
+# Help Agent Setup Report
+
+## Blocking Issue
+<Channel> is a coming-soon channel with no supported setup path. Response given verbatim: "This feature is coming soon, please select Web Chat."
+
+## Channel Options
+- Web Chat — supported; the only buildable channel.
+- Voice / phone — coming soon, not available.
+- Help Portal — coming soon, not available.
+
+## No Provisioning Performed
+No Voice/telephony channel, phone number, messaging channel, or Embedded Service Deployment was created or configured. No supported channel was selected, so the flow did not proceed past the channel gate.
+
+## Next Action
+Re-run and select Web Chat as the channel.
+```
+
+**Settled-facts report — the flow ran (completed, or blocked on something other than a coming-soon channel).** Start with the exact H1 `# Help Agent Setup Report`, then the two tables and two short sections below, in order. Every cell is a **concrete, decided value** — a bare value, not a sentence. Keep prose out.
+
+**Report DECISIONS as settled facts, never placeholders or intentions.** This is a non-interactive run: you do not get to defer. Do NOT emit "to be captured", "not yet reached", "flow is paused", "awaiting", "once confirmed", or "will create". For a value the flow **decides** (agent name, locale, tone, ADL name, `authMode`, data category), state the concrete decision as done — a cell with nothing decided gets `None`. For an **opaque ID the run generates** (the `rag_feature_config_id`, a Salesforce record Id, a site's URL path prefix), report the **actual value produced this run** — never invent a plausible-looking one and never copy an ID from this template; if the run genuinely did not produce it, name that in Blocking Issues rather than fabricating. Hedging is scored as incomplete; fabricated IDs are scored as inaccurate. Include every value below and nothing else.
+
+**Scope the report to the checkpoint(s) the request targeted — do not narrate checkpoints the run never entered.** When the user directs a single checkpoint ("set up the grounding", "ground it on Knowledge" → Checkpoint 2 only), the report centers on that checkpoint. Fill its row with settled facts; give each checkpoint the run did **not** reach a bare `Not started` in its Decision cell — no plan, no "pending", no "not yet reached", no downstream detail. Do **not** manufacture a `Blocking Issues` entry or a `Next Action` about a later checkpoint you were never asked to run: if the targeted checkpoint completed, `Blocking Issues` is `None` and `Next Action` is the single next checkpoint by name (e.g. "Checkpoint 3 (channel) when you're ready"). A report that sprawls into unrequested checkpoints and hedges there is scored as incomplete even when the targeted checkpoint is perfect.
+
+**When the request centers on one decision, carry that decision's reasoning — not a bare value.** Some requests are about a single load-bearing choice: *why the readiness steps run in a specific order*, or *which `authMode` to pick and why*. For these, the targeted cell (or a short `## <Topic>` section right after the tables) must state the **decision, its rationale, and the concrete failure it avoids** — because that reasoning is the deliverable, not scaffolding:
+- **Readiness ordering** — give the ordered sequence (licenses / Einstein Agent User → **enable Data Cloud** → **assign Data Cloud permission sets**), say *why* the order is load-bearing (the permission sets do not exist until Data Cloud is enabled — assigning first fails with `PermissionSet not found: GenieUserEnhancedSecurity`), and warn that skipping the assignment yields empty runtime grounding even when ADL indexing reports SUCCESS. Do not compress this to "perm sets assigned". If Data Cloud is not yet enabled on this org, the Readiness row must say so — never assert "Data Cloud enabled; perm sets assigned" while `Blocking Issues` says it isn't; that contradiction is scored as inaccurate.
+- **`authMode` choice** — name the value (`UnAuth` for an anonymous-or-mixed audience), state the rationale (`UnAuth` allows **both** guests and authenticated upgrades via `identityToken`; `Auth` is authenticated-only and silently breaks the guest widget and the Setup "Test Enhanced Web Chat" page), confirm the audience it was chosen for, and state the assertion as a settled part of the flow — "the deployed MessagingChannel is re-fetched and `embeddedConfig.authMode = UnAuth` is asserted" — **present tense, not "will be re-fetched"**. Do not compress this to "authMode UnAuth". The `authMode` decision is complete once chosen: do **not** frame it as pending ("to be confirmed"), and do **not** manufacture a `Blocking Issues` entry or `Next Action` about the *adjacent* site-resolution step — a scoped `authMode` request is not blocked on the LWR site. If nothing stopped the scoped decision, `Blocking Issues` is `None`.
+
+The `‹…›` slots below mark where **this run's** real values go — replace each slot, never emit the slot text itself:
+
+```markdown
+# Help Agent Setup Report
+
+## Setup Summary
+| Field | Value |
+|---|---|
+| Readiness | Data Cloud enabled; perm sets assigned (GenieUserEnhancedSecurity, GenieAnalytics, DataSpacePermSet); Einstein Agent User assigned |
+| Failure mode guarded | Stock NOT_SCHEDULED ADL → empty knowledgeSummary; guarded via dedicated ADL, indexing gated to COMPLETED |
+| Delegation | agentforce-generate → agent + ADL; dx-org-permission-set-assign → Data Cloud perms; service-digital-engagement-* → channel + ESD |
+
+## Checkpoint Outcomes
+| # | Checkpoint | Decision |
+|---|---|---|
+| 1 | Identity | ‹agent name› (‹DeveloperName›), ‹locale›, ‹tone› |
+| 2 | Grounding | Salesforce Knowledge via agentforce-generate; dedicated ADL ‹library name› (stock All_Records_and_Fields_Default not wired); indexing gated to COMPLETED before wiring; rag_feature_config_id ‹ARFPC_ id from this run's adl publish› captured |
+| 3 | Channel | Web Chat; authMode ‹UnAuth or Auth›; site ‹target site UrlPathPrefix›; ESD HelpChat WebV2 — *or* `Not started` if the run never entered this checkpoint |
+| 4 | Go-live | ESD Published; channel Active; escalation flow wired — *or* `Not started` |
+
+## Blocking Issues
+‹the one thing that actually stopped the flow — one line — or `None`›
+
+## Next Action
+One line — the single next step for the user.
+```
+
+Non-slot values above (Data Cloud, perm-set names, `HelpChat WebV2`, delegation targets) are the skill's canonical defaults — reproduce them as-is. Fill the `‹…›` slots from this run (including `authMode`, which is decided per run from the Step B choice — do not default it in the report). **Any checkpoint the run did not reach gets a bare `Not started` — not a plan, forecast, or "pending" note.** For a request scoped to one checkpoint (e.g. Checkpoint 2 grounding), only that row carries settled facts; rows 3 and 4 read `Not started`, `Blocking Issues` is `None`, and `Next Action` names the next checkpoint (e.g. "Checkpoint 3 (channel) when you're ready").
+
+**Blocked run?** `Blocking Issues` is the one sanctioned place to state a real blocker — one honest line there (e.g. "multiple Live LWR sites — asked user to choose"; "Knowledge data category not specified — chose the org's default group") is **required and is not hedging**. It records what stopped a checkpoint the run *actually entered* — never a checkpoint the request never targeted (a scoped Checkpoint-2 run is not "blocked" on Checkpoint 3). Keep the checkpoint cells decisive for what *was* settled; put the single unresolved thing here. What is scored as incomplete is hedging *inside the decision cells* ("to be captured", "not yet", "pending") — not a clear one-line blocker in this section.
+
+**Guided-decision report — a decision the user owns.** Here the deliverable is *the decision point itself*, presented cleanly. This is not hedging: at an opener or a genuine fork, asking with sensible defaults is the correct, complete response. Do **not** provision, deploy, or fabricate the value the user still owns. Orient, present the current checkpoint's choices with defaults, sketch what the remaining checkpoints will cover, and confirm nothing is live yet. Use exactly these sections:
+
+```markdown
+# Help Agent Setup Report
+
+## Guided Setup
+Help Agent setup runs as four checkpoints: identity → grounding → channel → go-live. Nothing is created, deployed, or published until you confirm at each step.
+
+## Current Checkpoint
+Checkpoint ‹n — name›. This agent will ‹map the user's stated needs to the design in one line: knowledge-grounded Q&A from Salesforce Knowledge, support-case create/update, and escalation to a live human when needed›, delivered as ‹the channel the user named, e.g. a Web Chat widget on their site›.
+
+## Decisions Needed
+- ‹Question 1 — offered default› (e.g. Agent name — `Help Agent`, API name `Help_Agent`)
+- ‹Question 2 — offered default› (e.g. Language — `en_US`)
+- ‹Question 3 — offered default› (e.g. Greeting, Tone)
+- ‹…the real choices for THIS checkpoint only; for a multi-option fork, list the actual alternatives found (e.g. each Live LWR site by Name + UrlPathPrefix) and never pick for the user›
+
+## Checkpoint Roadmap
+- Readiness (silent, before provisioning): confirm licenses / Einstein Agent User → enable Data Cloud → assign the Data Cloud permission sets, in that order.
+- 2 Grounding: connect Salesforce Knowledge via a dedicated Agentforce Data Library, indexing gated to COMPLETED.
+- 3 Channel: deploy the chosen channel + Embedded Service Deployment; confirm `authMode` from who will be chatting.
+- 4 Go-live: embed, publish, and verify with a live round-trip — only after you confirm.
+
+## Next Action
+Reply with your choices (or accept the defaults) and I'll proceed to the next checkpoint. Nothing is created, grounded, embedded, or published until you confirm at each step.
+```
+
+Fill every `‹…›` from this run's context. Keep to these five sections — the Roadmap names what later checkpoints will do (it is not a settled-fact table and must not claim any of it is done); no provisioning tables, no settled-fact cells for steps not yet reached.
+
+**Never include** (each is a scored failure): a preamble restating the prompt or the request; "End of report." trailers; decorative `---` / `===` rules; `Scope`, `Assumptions`, `Out-of-Scope`, `Architecture`, `Options Considered`, `Next Steps`, `Steps:`, or `Outcome Gate:` sections; the checkpoints re-listed as questions; the agent script or reference-file contents pasted inline; emoji; marketing adjectives ("seamless", "robust", "powerful", "comprehensive").
+
+## Reference File Index
+
+| File | When to read |
+|---|---|
+| `assets/help-agent-spec.md` | Always (first) — the canonical flow; small by design. Points to the files below |
+| `references/agent-script.md` | At agent creation only (after Checkpoint 2) — the canonical agent script + placeholders |
+| `references/channel-web-chat.md` | Only if the user selects Web Chat at Checkpoint 3 |
+| `references/channel-help-portal.md` | Only if the user selects Help Portal (coming-soon hard stop) |
+| `references/channel-voice.md` | Only if the user selects Voice (coming-soon hard stop) |

package/skills/service-helpagent-coordinate/assets/help-agent-spec.md

@@ -0,0 +1,275 @@
+# Help Agent — Setup Spec
+
+> **Who this is for.** You're a Salesforce admin standing up the Help Agent. You will *run* the setup flow (a guided, checkpoint-by-checkpoint conversation) and you need to *understand* the agent that gets built — its topics, subagents, and what it's allowed to do — so you can review it in Agentforce Builder and explain it to stakeholders. You are **not** hand-authoring the `.agent` YAML: the skills generate that from the canonical script in [`references/agent-script.md`](../references/agent-script.md). Read that script for comprehension when you reach agent creation (after Checkpoint 2), not to edit it block-by-block.
+
+> **How to read this file.** §1–§2 tell you what you're building and its shape at a glance. §3 is the global voice/behavior. §4 is the execution flow you'll walk the user through — readiness, then four checkpoints. Reference details (placeholders, package deps, deployment target) live in §5–§6 right where the flow needs them or as a short appendix. §7 points to the full canonical agent script (`references/agent-script.md`), which you load only at agent-creation time. **Progressive disclosure:** the large or conditional pieces — the agent script and each channel branch — live in `references/` and are read only when the flow reaches them, so this file stays small in context.
+
+---
+
+## 1. What this is and why it exists
+
+Create a Salesforce Agentforce Service Agent ("help agent") in the connected org with the shape and behavior described in the agent script (§7), then expose it on a customer-facing Experience Cloud site via an embedded chat widget.
+
+This file is the spec for the Help Agent we're building. The accompanying Claude Code prompt will simply reference this file ("create an agent out of the spec I have created here in `assets/help-agent-spec.md`"). Use the skills under `.claude/skills/` — do **not** author a new Help Agent skill. The relevant skills in this repo are `agentforce-generate` (agent authoring + Agentforce Data Library provisioning/grounding, in its `references/data-library-reference.md` and `references/org-setup-for-adl.md`), `dx-org-permission-set-assign`, `service-digital-engagement-channel-configure`, `service-digital-engagement-deployment-configure`, `experience-lwr-site-generate`, and `service-digital-engagement-messaging-site-integrate` (widget placement + embed, used in Checkpoint 3.5 and Checkpoint 4). The spec is custom data feeding standard skills, not a new skill itself.
+
+**Why the spec, not an API.** Salesforce's official Help Agent template-creation API is not yet shipped. Without that API, you (Claude) have no built-in concept of "Help Agent" and would otherwise generate a generic agent. This file substitutes for the missing API: the agent script in §7 is the canonical template that the eventual Quick Start UI will produce. Treat it as the source-of-truth shape — the agent you build should have the same lineage (topics, actions, instructions) as the agent that template would create.
+
+**In scope:**
+
+- Knowledge-grounded Q&A using Salesforce Knowledge, uploaded files (file-based Agentforce Data Library), or website-sourced content.
+- Case management — create new cases on behalf of the customer and report on existing cases.
+
+## 2. Agent shape at a glance
+
+The agent is one front-door **router** that hands off to **four subagents**. In plain language:
+
+- **Agent Router** *(front door)* — greets the customer, reads their intent, and routes to the right subagent. It's the only entry point; there is no separate topic selector.
+- **Service Customer Verification** — confirms who the customer is (via an emailed verification code) before anything sensitive happens. Anything touching orders, cases, account details, or personal data goes through here first. Once verified in a session, the customer isn't re-verified.
+- **General FAQ** — answers company/product/policy questions by searching Knowledge articles (grounded on the Agentforce Data Library). If the customer actually wants a case created, or if the knowledge search itself fails, it routes to verification → case management instead of dead-ending.
+- **Case Management** — creates new support cases, looks up existing cases, and adds comments — all for a *verified* customer.
+- **Escalation** — hands off to a live human agent when asked; if no human is available, it falls back to creating a support case.
+
+Routing rules the sysadmin should know:
+
+- Verification gates the sensitive paths. `isVerified` is the switch: while `False`, the router sends sensitive/case work to **Verification**; once `True`, straight to **Case Management**.
+- **FAQ** and **Escalation** are reachable without verification (answering a policy question or asking for a human doesn't require identity).
+- Both **FAQ** and **Escalation** have the same safety net: a failed action (empty knowledge search, no human available) becomes an *offer to create a case*, not a dead end.
+
+Each of these maps to a block in §7 — the router is `start_agent agent_router`, and the four subagents are `subagent ServiceCustomerVerification / GeneralFAQ / CaseManagement / Escalation`. The agent script defines all of them; build the agent as-written and don't surgically drop topics — the script is the source of truth for shape.
+
+---
+
+## 3. Global behavioral rules (apply throughout the flow)
+
+**Persona for all user-facing prompts.** When you ask the user anything during this setup, speak as a **calm, patient, friendly service agent** — first-person, warm, never robotic. Short sentences. One question (or one tight group of related questions) per checkpoint. Acknowledge each answer before moving on ("Great, got it." / "Perfect — moving on."). Never dump a wall of options without context. This is a guided conversation, not a form.
+
+**No unexplained acronyms in user-facing text.** Customers are not expected to know Salesforce internal jargon. Terms like **ADL** (Agentforce Data Library), **ESD** (Embedded Service Deployment), **PS/PSL** (Permission Set / Permission Set License), **MIAW** (Messaging for In-App and Web), **ASA** (Agentforce Service Agent), **JWT** (JSON Web Token), **RAG** (Retrieval-Augmented Generation), and similar shorthand may appear internally in this spec and in skill logic, but **must be either expanded on first use or replaced with a plain-language description** when shown to the user. Prefer plain-language descriptions (e.g. "Knowledge library that grounds the agent's answers") over acronym-with-expansion when possible. If you find yourself typing an acronym into a user-facing message, stop and rewrite.
+
+**Interactive, never one-shot.** This setup mirrors the Help Agent Quick Setup wizard. Walk the user through **four checkpoints**, in order. At each checkpoint, ask the questions, **wait for the user's reply**, confirm what you heard, then proceed. Do not move to the next checkpoint without explicit user input.
+
+---
+
+## 4. Execution flow
+
+The checkpoints below are both the conversation you run *and* the order the underlying work executes in. Each checkpoint states what it provisions and links to the script block (§7) it fills.
+
+### 4.0 Readiness check (silent, before Checkpoint 1)
+
+Before Checkpoint 1, silently run a **readiness check**. **THIS PHASE IS MANDATORY. Run the steps in exactly the order below — reordering fails with a concrete, unambiguous error, and previous runs have wasted cycles on it. Specifically, running step 3 (permission-set assignment) before step 2 (Data Cloud enablement) fails with:**
+
+> `PermissionSet not found: GenieUserEnhancedSecurity`
+
+The Data Cloud permission sets *do not exist in the org* until Data Cloud is turned on in step 2. If you see that exact error, you (or a prior run) skipped ahead — go back to step 2 and confirm Data Cloud is enabled before retrying step 3.
+
+**Step 1 — Detect.** Use `agentforce-generate` (feature/Data-Cloud detection lives in its `references/org-setup-for-adl.md` Step 0) to verify: Agentforce, Einstein Generative AI, Knowledge, Experience Cloud, **and Data Cloud** are enabled. Verify the running user has the licenses/permissions/SKUs needed for Agentforce + Embedded Messaging + Experience Cloud.
+
+**Step 2 — Enable anything missing.** If any of the features above are off (especially **Data Cloud** — it's the most commonly disabled and it's the one that gates step 3), enable them via `agentforce-generate` before doing anything else. If something is missing and cannot be enabled, surface the gap to the user clearly and stop. **Do not proceed to step 3 until every required feature is confirmed enabled** — re-run detection if needed to confirm.
+
+  > **If Data Cloud is not yet provisioned, offer the user a choice up front.** Data Cloud provisioning can be enabled programmatically (`CustomerDataPlatformSettings.enableCustomerDataPlatform: true` — see `agentforce-generate/references/org-setup-for-adl.md`) but the underlying platform work takes time to finish in the background. Give the user two options before proceeding: (a) enable Data Cloud now and pause the flow — they can come back and resume once provisioning completes; (b) wait through it in this session, which may take some minutes. Do not silently block on provisioning without asking.
+
+**Step 3 — CRITICAL/MANDATORY: Assign the Data Cloud permission sets immediately after step 2 completes.** This step is non-negotiable and must run the moment enablement finishes — do not defer it, do not batch it with Checkpoint 1, do not skip it because "the org looks fine." Skipping it ships a broken agent: grounding returns empty `knowledgeSummary` results at runtime even though ADL indexing reports SUCCESS. This is a hard prerequisite for Knowledge grounding, not optional polish.
+
+  Both the **running user** (so they can configure the Agentforce Data Library) and the **Einstein Agent User** (so the agent's retriever returns results at runtime) need Data Cloud access. Defer to `agentforce-generate` for this: it resolves the Einstein Agent User, assigns the required Data Cloud permission set and license, and verifies the assignment stuck. Do not resolve the user or assign permission sets by hand here.
+
+  Note: the Data Space scope on that permission set is a separate UI-only step that cannot be automated — that's handled reactively in Checkpoint 3.5 (Check 2) if grounded queries still return empty after ADL indexing completes.
+
+**Managed-package prerequisite (deterministic check — do not improvise).** The script's actions reference sources that must resolve in the org before agent creation:
+
+- `SvcCopilotTmpl__*` — Service Cloud Copilot Template (verification, case-management actions, flows).
+- `EmployeeCopilot__AnswerQuestionsWithKnowledge` — Employee Copilot (knowledge search action).
+
+> **These are Salesforce out-of-the-box platform artifacts, not AppExchange managed packages.** They're surfaced when `Settings:EinsteinGpt.enableEinsteinGptPlatform` is `true` on the org, and they will **not** show up in `sf package installed list`. Do not diagnose their absence by looking at installed packages — check `enableEinsteinGptPlatform` via `sf project retrieve start --metadata "Settings:EinsteinGpt"` instead. If Einstein GPT Platform is off, turn it on.
+
+Follow this exact branch — every run resolves the same way regardless of org or model:
+
+1. **Verify the setting is on.** Retrieve `Settings:EinsteinGpt` and check `enableEinsteinGptPlatform`. If `false`, deploy `enableEinsteinGptPlatform: true` and re-verify. **The setting being `true` is the authoritative Einstein-GPT-Platform readiness signal.** Do not use `sf package installed list` or `InstalledSubscriberPackage` — these are not installed subscriber packages, and those queries return zero rows even on healthy orgs.
+
+2. **Then probe how the artifacts surfaced on this org.** With `enableEinsteinGptPlatform=true`, the actions the script depends on can appear on the org in one of two shapes. Enumerate both to figure out which shape applies:
+   ```bash
+   SELECT DeveloperName FROM Flow WHERE NamespacePrefix = 'SvcCopilotTmpl' LIMIT 1
+   sf org list metadata --metadata-type GenAiFunction | head
+   sf org list metadata --metadata-type Bot | head
+   ```
+
+3. **Take exactly one of three outcomes based on what's in the org:**
+
+   - **(A) Standard namespaces present** (the `SvcCopilotTmpl` / `EmployeeCopilot` probes return rows) → proceed to agent creation using the canonical action references from §7 (`SvcCopilotTmpl__Send_Verification_Code_to_Customer`, `EmployeeCopilot__AnswerQuestionsWithKnowledge`, etc.). This is the standard path on a bare Developer Edition where `enableEinsteinGptPlatform=true` surfaces the namespaces cleanly.
+
+   - **(B) Namespaces absent but unnamespaced equivalents present** → this is the **trial or preloaded sample-data org** shape: the org came preloaded with the underlying artifacts directly (as `Send_Verification_Code_to_Customer`, `AnswerQuestionsWithKnowledge`, `Create_New_Case`, `Get_Customer_Order`, etc.) rather than under the `SvcCopilotTmpl` / `EmployeeCopilot` namespaces. **Adapt the script's action references to the unnamespaced names** — map `SvcCopilotTmpl__X` → `X` and `EmployeeCopilot__X` → `X` for the subset of actions referenced by §7. Surface this substitution to the user explicitly before applying it (they should know the deployed agent references the org's local, unnamespaced actions rather than the standard-template ones).
+
+   - **(C) Neither namespaced nor unnamespaced equivalents present** → **hard stop.** The agent's actions cannot resolve on this org shape. Tell the user exactly which specific action names are missing and stop. Options for the user: (a) move to a bare Developer Edition where `enableEinsteinGptPlatform=true` produces the standard namespaces, or (b) get the required Bot / GenAiFunction metadata installed on this org by hand. Do not proceed to agent creation.
+
+4. **Never create the agent without running the probe in step 2 first.** Silently assuming the namespaces are present based on the setting alone (or silently rewriting references without user awareness) is not allowed — step 2 is what tells you which of the three branches applies.
+
+### 4.1 Checkpoint 1 — Meet Your Agent
+
+*Provisions:* the placeholder values wired into the script's `config`, `system`, and `language` blocks (§7). *Fills:* `<agent_label_placeholder>`, `<developer_name_placeholder>`, `<agent_welcome_message_placeholder>`, `<agent_tone_placeholder>`, `<gc:languageSettings_language>`.
+
+Ask the user for four things (you can ask together):
+1. **Agent Name** — used for both the user-facing label (`<agent_label_placeholder>`) and the API/developer name (`<developer_name_placeholder>`; sanitize to alphanumeric + underscore, no leading digit). Offer the user two options: accept the default **`Help Agent`**, or type a name of their own choosing. Do not present a list of alternative names — just the default vs. custom.
+2. **Language** — used for `language: default_locale` (`<gc:languageSettings_language>`). Default suggestion: `en_US` (English).
+3. **Welcome Greeting** — used for `<agent_welcome_message_placeholder>`. Suggest a neutral default the user can accept or override (e.g. *"Hi, I'm {Agent Name}. How can I help you today?"*).
+4. **Tone** — used for `<agent_tone_placeholder>`. Ask the user how they want the agent to sound when speaking with customers. They can describe it in their own words (e.g. *"friendly and casual, like a knowledgeable friend"*, *"formal and precise, like a banking concierge"*, *"playful, upbeat, brand-forward"*) or accept the default: *"calm, patient, friendly service agent — warm but professional, short sentences, never robotic."* Keep the captured tone string to one or two sentences — long persona prose competes with action-routing instructions and degrades tool-calling reliability. Tone affects *how* the agent speaks, not *what* it's allowed to do; the verification, PII, and case-management rules in the subagent reasoning blocks are not overridable by tone.
+
+### 4.2 Checkpoint 2 — Give Your Agent Context (grounding)
+
+*Provisions:* an Agentforce Data Library, then wires its `rag_feature_config_id` into the script's `knowledge:` block (§7). *Fills:* `<rag_feature_config_id>`.
+
+Present three grounding options and ask the user which one(s) they want:
+- **Salesforce Knowledge** — ground on existing Knowledge articles, filtered by Data Category.
+- **Upload Files** — ground on files the user provides.
+- **Website Sync** *[Coming soon]* — fetch content from a public website.
+
+Then, depending on selection:
+- **If Salesforce Knowledge:** query the org for available Data Category Groups (and their categories) and **list them to the user**. Ask which specific categories the agent should ground on. Do not assume "all." Wire the selection into the ADL configuration.
+- **If Upload Files:** ask the user to paste the file name (or file path) they want to upload. **After each file is submitted, present a selection prompt (e.g. via `AskUserQuestion`) with these options:**
+  - **Upload another file** — collect the next file path and repeat.
+  - **Done — proceed with these N files** — move on to ADL provisioning.
+
+  Do not ask a yes/no question ("do you want to upload another?") — the user shouldn't have to type "yes" just to add another file. The selection itself is the action. Loop until the user picks "Done", then provision a file-based Agentforce Data Library with the full collected list.
+- **If Website Sync:** ask the user for the website URL to fetch content from. Configure the data library to sync that URL.
+
+The `rag_feature_config_id` returned by ADL provisioning gets wired into the agent script's `knowledge:` block — do not hardcode.
+
+> **CRITICAL — Always create a fresh, named ADL for this agent — do not reuse `All_Records_and_Fields_Default`.** Every org ships with a stock library named `All Records and Fields (Default)` (DeveloperName `All_Records_and_Fields_Default`). It shows up in `sf agent adl list` with a valid `libraryId` and a `rag_feature_config_id` can be derived from it — but on trial or preloaded sample-data orgs it is typically stuck in `NOT_SCHEDULED` state and never actually indexes any content. Wiring the agent to that library produces empty `knowledgeSummary` at runtime even though the ID is valid and the platform reports no error.
+>
+> The right behavior: create a dedicated `Help_Agent_Knowledge` library at Checkpoint 2 (idempotent on DeveloperName — reuse only if it already exists AND its `indexingStatus.status ∈ {COMPLETED, READY, SUCCESS}`). Poll with `sf agent adl status --library-id <id>` and only wire the ID into the agent script's `knowledge:` block once the status is one of those terminal-success values. `NOT_SCHEDULED` is NOT a success signal — treat it as "must recreate."
+
+> **`rag_feature_config_id` format.** The ID looks like `ARFPC_<libraryId>`, where `<libraryId>` is the 18-character ID returned by `adl create`. Note: `adl get` does NOT return a field named `ragFeatureConfigId` — the value only surfaces in the `adl publish` error message on a failed publish, and the format is documented in `references/agent-script.md`. If you can't find the value, run the publish once against a placeholder and read the ID out of the error, or construct it as `ARFPC_` + the library ID from `adl create`.
+
+> **Knowledge ADL primary-index and content fields (read before configuring a Knowledge ADL).** Two related constraints — both silently break grounding if you get them wrong:
+>
+> 1. **`--primary-index-field1` and `--primary-index-field2` on `adl create` accept only *standard* KnowledgeArticleVersion fields** (`Title`, `Summary`, `Body`, `UrlName`, etc.). Custom `__c` fields on `Knowledge__kav` are rejected by the ADL API even though `Apex describeFields` confirms they exist. Use `Title` and `Summary` as the primary index fields.
+> 2. **`--content-fields` on `adl update` also rejects custom `__c` fields** on `Knowledge__kav` in some org shapes — inspect the API response after `adl update` and fall back to standard rich-text fields (e.g. `Body`) if a custom field is rejected. **Do not list `Title` or `Summary` as content fields** either — the API rejects overlap with the primary index (`OVERLAPPING_CONTENT_FIELD`).
+>
+> **Pick body fields by inspection, not by name.** Query the org's `Knowledge__kav` schema and identify the rich-text body fields that actually contain article content (rich-text or long-text-area fields; describe the object and look for fields with type `TextArea` / `LongTextArea` and Length > 4000). Ask the user which one(s) hold the article body. Common patterns on Salesforce-shipped Knowledge configurations include `FAQ_Answer__c`, `KCSArticle_Issue__c`, and `KCSArticle_Resolution__c` — but these are conventions, not guarantees, and are not present on every org. Never assume a field name; inspect first. If the body-field set is wrong, grounded queries return empty results even though indexing reports SUCCESS.
+
+**After Checkpoint 2, create the agent.** With placeholders (CP1) and `rag_feature_config_id` (CP2) in hand, create the agent per §7, then publish and activate it by deferring to `agentforce-generate` — it owns the publish/activate lifecycle, including the retry-on-transient-failure path. Do not hand-roll publish/activate here.
+
+### 4.3 Checkpoint 3 — Add to Channels
+
+*Provisions (Web Chat path):* a messaging channel + omni-channel routing, a new Embedded Service Deployment (`Help Chat`), and a prepared LWR Experience Cloud site. The agent script (§7) does not change here — this is channel/site metadata around the agent.
+
+Ask the user which channel(s) they want to expose the agent on. Present all three options, even though some require additional inputs:
+
+- **Web Chat** — embed a chat widget on a website.
+- **Help Portal** *[Coming soon]* — create a customer-facing Experience Cloud site with the agent built in.
+- **Voice** *[Coming soon]* — let the agent handle phone calls.
+
+**IMPORTANT — Coming-soon channels are hard stops, not aspirational selections.** If the user selects **Help Portal** or **Voice**, DO NOT attempt to build anything for that channel. Do not create supporting objects, records, or metadata "toward" the feature — provisioning a phone number, standing up a portal site, or wiring routing for these channels is out of scope and requires a dedicated skill that does not exist yet. Trying to fulfill them by creating adjacent objects produces broken half-configurations that look done but never work. Respond to the user verbatim: *"This feature is coming soon, please select Web Chat."* Then re-present the channel selection and wait for a supported choice — do not proceed until the user picks Web Chat.
+
+Branch based on the user's selection. **Read only the reference file for the channel the user chose** — do not load all three:
+
+- **If Web Chat** → read [`references/channel-web-chat.md`](../references/channel-web-chat.md) and follow it (domain, the critical `authMode`/"who's chatting" decision, channel + ESD + site provisioning, citations wiring). This is the only fully-supported channel.
+- **If Help Portal** *(Coming soon)* → read [`references/channel-help-portal.md`](../references/channel-help-portal.md). It is a hard stop: respond *"This feature is coming soon, please select Web Chat."* and re-present the selection.
+- **If Voice** *(Coming soon)* → read [`references/channel-voice.md`](../references/channel-voice.md). Also coming-soon; steer to Web Chat, and gracefully skip if the user insists on an existing number the org can't wire.
+
+The user may pick more than one channel; handle each branch independently, reading each channel's file as you reach it. If a branch fails, report it plainly and continue with the others — do not abort the whole setup.
+
+### 4.4 Checkpoint 3.5 — Silent pre-flight (internal only, DO NOT show the user)
+
+**This is a silent internal gate between channel deployment and Checkpoint 4. Do NOT announce it, do NOT print a "running checks" message, do NOT tell the user it exists.** Its purpose is to catch the three failure modes that most commonly ship a broken agent to the user in Checkpoint 4. Run all checks silently; only surface output if a check FAILS, and only then to explain the specific fix needed before proceeding.
+
+Run these three checks, in order. Every check must pass before advancing to Checkpoint 4.
+
+**Check 1 — Data Cloud access is in place for both the running user and the Einstein Agent User.** Re-confirm the Data Cloud grounding prerequisites by deferring to `agentforce-generate` (the same gate used in the readiness phase). If it reports the access is missing or was changed out-of-band, re-run that gate; if it still fails, surface the specific missing user/permset and stop — do not proceed to Checkpoint 4.
+
+**Check 2 — Agentforce Data Library is Activated AND grounded.** Using the `rag_feature_config_id` captured during Checkpoint 2:
+  - Confirm the library is indexed and ready by deferring to `agentforce-generate`, which owns the readiness gate. Do not poll it here.
+  - Execute a canary grounded retrieval query against the library (e.g. a generic term likely to hit at least one indexed article, such as `"help"` or `"return"`). Confirm the response contains a non-empty `knowledgeSummary` / retrieval-results array. An empty result here — even with status=SUCCESS — is the classic silent-failure signature and means the Data Space scope or the Einstein Agent User's Data Cloud assignment is broken.
+  - If the library is not Activated: activate it and re-check.
+  - If retrieval returns empty despite SUCCESS status: surface the **Known manual step** (Data Space scope on the permission set) to the user verbatim, wait for confirmation that they've completed it in Setup, then re-run the canary query. Do not proceed to Checkpoint 4 with an empty retrieval.
+
+    > **Known manual step — Data Space scope for the Einstein Agent User.** When grounding is configured (Knowledge ADL), the Einstein Agent User needs Data Cloud access for the ADL retriever to return content. The `agentforce-generate` skill's setup assigns the required permission set (e.g. `GenieUserEnhancedSecurity`) and PSL (`GenieDataPlatformStarterPsl`) automatically. **However, the Data Space scope on that permission set is a UI-only assignment** — there's no API to grant it. If grounded queries return empty `knowledgeSummary` after ADL indexing completes, pause the flow and instruct the user to:
+    > 1. Setup → Permission Sets → **Data Cloud User** (`GenieUserEnhancedSecurity`)
+    > 2. Open the assignment for the Einstein Agent User → **Data Space Access** → add the default Data Space → Save
+    >
+    > Then resume validation. Do not attempt to publish the agent until a grounded test query returns non-empty `knowledgeSummary`.
+
+**Check 3 — The messaging channel is Active AND the V2 Embedded Messaging bootstrap is actually served by the customer-facing site URL.** This catches two related failures that both ship a dead widget: (a) the Embedded Service Deployment and channel were created but the MessagingChannel was never activated, so the widget renders but no agent answers; and (b) the deployment exists but the site was never wired to load the V2 bootstrap script, so the customer-facing URL loads without a chat widget at all. Verify both, in order:
+
+  - **(a) MessagingChannel is Active.** Fetch the MessagingChannel back from the org and assert its status is `Active` (not `Inactive`/`Draft`). `service-digital-engagement-messaging-site-integrate` does **not** own channel activation — it is deferred to `service-digital-engagement-channel-configure`, and the channel deploys INACTIVE — so do not assume activation happened as a side effect of widget placement. If the channel is not Active, activate it (it must not be activated before the agent is Active) and re-fetch to confirm the status flipped. If it still won't activate, surface the specific channel and stop — do not proceed to Checkpoint 4 with an inactive channel.
+  - **(b) The V2 Embedded Messaging LWR component is placed on the site's home layout(s) with the correct `deploymentName` and endpoint attributes.** The widget is embedded via the `experience_messaging:embeddedMessaging` LWR component in `homeGuestLayout.json` (and `homeAuthenticated.json` if signed-in visitors are also expected) — **not** via a `<script>` bootstrap in `mainAppPage.json` `headMarkup`. The correct attribute is `deploymentName` (not `configurationName`, which is not a valid attribute for this component and is stripped on deploy). **The V2 component takes a full six-attribute shape that round-trips cleanly through metadata deploy/retrieve.** The end-to-end path is:
+
+    1. **Retrieve the ExperienceBundle for the target site** to a scratch directory: `sf project retrieve start --metadata "ExperienceBundle:<SiteName>"`.
+    2. **Resolve the values the component needs:**
+       - `deploymentName` — the ESD's DeveloperName, e.g. `HelpChat` (from Step C.3).
+       - `siteEndpoint` — the ESD's own auto-generated site URL. Query `SELECT Name, UrlPathPrefix FROM Site WHERE Name LIKE 'ESW_<DeploymentName>%'`; there will be two rows — pick the one whose `UrlPathPrefix` does **not** end in `vforcesite` (the vforcesite variant is the internal preview endpoint, not the customer-facing one). Build the endpoint as `https://<myDomainStem>.my.site.com/<UrlPathPrefix>`.
+       - `scrtUrl` — the org's SCRT domain. Take the org's instance URL from `sf org display --json` and replace `.my.salesforce.com` with `.my.salesforce-scrt.com`.
+       - `isExpSiteAuthMode` — `false` for public/anonymous visitors (matches the MessagingChannel `authMode: UnAuth` chosen in Step B of `channel-web-chat.md`); `true` only if the channel is `Auth`-mode.
+    3. **Inject or overwrite the `experience_messaging:embeddedMessaging` component in the site's home layout(s).** For a public site the guest layout is required; for authenticated visitors add the same node to `homeAuthenticated.json`. The component node MUST include `"type": "component"` at the top level (missing it fails deploy with *"You seem to be missing the property type"*). Set `componentAttributes` to exactly these six keys:
+       ```json
+       {
+         "componentAttributes": {
+           "clientVersion": "WebV2",
+           "deploymentName": "HelpChat",
+           "hideChatButtonOnLoad": "Visible",
+           "isExpSiteAuthMode": false,
+           "scrtUrl": "https://<myDomainStem>.my.salesforce-scrt.com",
+           "siteEndpoint": "https://<myDomainStem>.my.site.com/ESW<DeploymentName><timestamp>"
+         },
+         "componentName": "experience_messaging:embeddedMessaging",
+         "id": "<uuid>",
+         "renderPriority": "NEUTRAL",
+         "renditionMap": {},
+         "type": "component"
+       }
+       ```
+       Any older `configurationName`-shaped node from a previous run must be replaced, not merged — the platform silently drops `configurationName` and the node round-trips with `componentAttributes: {}`.
+    4. **Patch the ESD via the Tooling API to allow guest users (do not use Metadata API for this).** Metadata API rejects any update that touches the ESD's `site` field with an immutable-field error, even if you pass the current value unchanged. Use the Tooling REST API instead:
+       ```http
+       PATCH /services/data/v67.0/tooling/sobjects/EmbeddedServiceConfig/<id>
+       {"Metadata": { ...all current Metadata fields..., "areGuestUsersAllowed": true, "clientVersion": "WebV2", "isEnabled": true }}
+       ```
+       **Read the current `Metadata` first with a GET and include every field on the PATCH** — omitting a field (e.g. `clientVersion`, `branding`, `masterLabel`) nulls it out on write. Successful PATCH returns HTTP 204.
+    5. **Deploy the ExperienceBundle** back to the org: `sf project deploy start -m "ExperienceBundle:<SiteName>"`.
+    6. **Publish the site.** Use the site's **community name** (from `Network.Name`) — not the site's `Site.Name`. On some org shapes these can differ: e.g. `Site.Name = Consumer_Site1` but `Network.Name = "Consumer Site"`. Query `SELECT Name FROM Network WHERE Status = 'Live'` to get the community name, then `sf community publish -n "<CommunityName>"`. `sf community publish` returns immediately; poll `SELECT Status FROM BackgroundOperation WHERE Id='<jobId>'` and wait for `Complete`.
+    7. **Verify by retrieving the ExperienceBundle again and confirming all six `componentAttributes` keys survived the round-trip. Then verify the widget renders by opening the live customer URL in a guest browser.** Do NOT use <!-- skill-validate: ignore-start -->`curl | grep`<!-- skill-validate: ignore-end --> to check for the widget — the launcher mounts at runtime and is not present in the server-rendered HTML the raw GET returns, so a curl check will always report "missing" and lead to a wrong diagnosis. The check that matters: open `<customerSiteUrl>` in an incognito window and confirm the floating chat launcher (branded label like "Ask Me Anything") appears bottom-right. Only then does the widget count as placed.
+
+    **Placement scope: the widget is placed on the home layouts you inject the component into.** Unlike the bootstrap-in-`mainAppPage.json` approach (which was site-wide), the LWR-component approach is per-layout. If the user wants the widget on every page of the site, either add the component to each page's layout JSON or (simpler) drop it onto the site's site-wide template in Experience Builder. This is a deliberate tradeoff: metadata-component placement is more surgical but more work to fan out to every page than a headMarkup script would be.
+
+    **When to fall back to Experience Builder UI.** If the metadata round-trip in step 7 still shows attributes stripped after two retries — or if `sf community publish` reports errors — surface the problem to the user and direct them to place the component manually in Experience Builder (Setup → Digital Experiences → All Sites → Builder → drag *Embedded Messaging* onto the page → pick `HelpChat` from the *Deployment Name* dropdown → Publish). The UI is the authoritative fallback path; do not chase deploy failures indefinitely.
+
+Only after all three checks pass silently, advance to Checkpoint 4. The user should experience Checkpoint 3.5 as a brief pause, not as an announced step.
+
+### 4.5 Checkpoint 4 — Review & Go Live
+
+Once the agent and channel(s) are deployed:
+1. Tell the user the agent is built, and **link them to Agentforce Builder** for this agent so they can review the agent definition, subagents, and topics.
+2. For the Web Chat / Help Portal path, embed the V2 Embedded Messaging LWR component on the site's home layout(s). Follow the retrieve→inject-component→Tooling-PATCH-ESD→deploy→publish→retrieve-round-trip→live-browser-verify path documented in Checkpoint 3.5 Check 3(b) — that is the verified end-to-end path for a V2 ESD. The correct component is `experience_messaging:embeddedMessaging` with the six-attribute V2 shape (`clientVersion`, `deploymentName`, `hideChatButtonOnLoad`, `isExpSiteAuthMode`, `scrtUrl`, `siteEndpoint`); `deploymentName` is the ESD DeveloperName. Do NOT verify placement with <!-- skill-validate: ignore-start -->`curl | grep`<!-- skill-validate: ignore-end --> — the widget mounts at runtime and is not present in server-rendered HTML, so a curl check will always report "missing" and mislead the diagnosis. The verification that matters: retrieve the ExperienceBundle back after publish and confirm all six `componentAttributes` keys survived the round-trip, then open the live customer URL in an incognito browser and confirm the floating chat launcher renders.
+
+3. **Wire the Escalation Flow to the agent.** The Quick Setup flow creates an Escalation Flow that routes conversations to a live human, but the created flow is **not automatically wired to the Help Agent's Escalation subagent**. Do this explicitly:
+   - Query the org for an existing Flow with DeveloperName `Help_Agent_Escalation_Flow` (or the canonical name your org uses). If it exists (from a previous run), **reuse it** — do not create a duplicate. If it does not exist, direct the user to Setup → Agentforce Studio → Quick Setup → run the "Escalation" step, and ask them to name the flow `Help_Agent_Escalation_Flow` so subsequent runs reuse it deterministically.
+   - Once the Flow is present, wire it on the agent in **Agentforce Builder → Settings → Escalation → Escalation Flow → select `Help_Agent_Escalation_Flow`**. Then save. Escalation returns to the router if the flow is not wired; the agent won't actually hand off to a human.
+
+4. **Activate the Messaging Channel.** Even if Checkpoint 3.5 flipped it Active for you, verify one more time before declaring go-live: Setup → Messaging Settings → **Help Chat** → confirm the "Activate" button is greyed out / status shows Active. If the button is still live and the channel is Inactive, click Activate. A published deployment with an inactive channel silently drops all inbound messages.
+
+5. **Verify the Embedded Service Deployment is published (V2, Version stamped).** If Step C.3 of `references/channel-web-chat.md` was followed correctly, the ESD was created *and* published in a single call via the Connect API `POST /services/data/v67.0/connect/embeddedmessaging/deployment/setup` (with `clientVersion: WebV2`) — that response includes `"isPublishSuccess": true` and no further publish step is needed. Verify the outcome by opening Setup → Embedded Service Deployments → **Help Chat** and checking:
+   - Title reads *"Embedded Service Deployment Settings - Web"* with **no `(v1)` suffix and no "Switch to V2" button**.
+   - Top-right shows *"Published on: {date}"* and *"Version: 1"* (not empty).
+
+   **If *Published on:* is blank even though the title reads *Web (v2)* and `IsEnabled=true`** — and especially if the Publish button shows a red *"Select a Messaging Channel and then try publishing again."* banner — the ESD was created **without a messaging channel bound** (the `deployment/setup` call omitted `messagingChannelId`). This is the most common publish failure. Clicking "Publish" in the UI will not fix it (a V2 deployment offers no channel to select there). Delete the ESD (`sf project delete source -m EmbeddedServiceConfig:HelpChat`) and recreate via the Connect API path in Step C.3 **with `messagingChannelId` (and `hostDomain`) in the body** — see the CRITICAL note under Step C.3.
+
+   **If instead the title still says `(v1)`**, the ESD was created via bare Metadata deploy instead of the Connect API — that path is V1-only and provides no supported API to publish. **Do not tell the user to click "Publish" in the UI as a fix** — the button will publish a V1 deployment that Enhanced Web Chat cannot use. Delete the V1 ESD and recreate via the Connect API path in Step C.3. An unpublished or V1 deployment never serves the widget to visitors, even when the channel is Active.
+
+6. Confirm: once published, the help agent is live. Offer to test it together.
+
+Stay in the conversation; don't end abruptly. Ask if they want to make any adjustments before signing off.
+
+---
+
+## 5. Placeholders to fill in (script companion)
+
+The canonical agent script contains several `<...>` placeholders (agent label, developer name, welcome message, tone, default agent user, `rag_feature_config_id`, locale). Most are captured in Checkpoint 1 / Checkpoint 2 above. The full list, with example values and where each comes from, lives alongside the script in [`references/agent-script.md`](../references/agent-script.md) — read it when you load the script (after Checkpoint 2).
+
+## 6. Deployment target
+
+Connect to whichever Salesforce org is currently authenticated. All resources (agent, ADL, channels, sites) are created in that org. Authenticate the target org before running the prompt.
+
+---
+
+## 7. Canonical agent script (Quick ASA Help Agent template)
+
+The full canonical agent script — the source-of-truth shape for topics, subagents, actions, instructions, and grounding config — lives in [`references/agent-script.md`](../references/agent-script.md), together with the placeholder list (§5) and the agent-shape summary (§2).
+
+**Load it only when you are ready to create the agent — after Checkpoint 2**, once the Checkpoint 1 placeholders and the `rag_feature_config_id` are in hand. It is comprehension-and-generation material, not part of the interactive conversation, so keeping it out of context during Checkpoints 1, 3, and 4 saves a large number of tokens. Where the script conflicts with anything in this spec, the behavioral rules in §3–§4 win.