@salesforce/afv-skills 1.63.0 → 1.65.0

package/skills/health-cloud-referral-management-coordinate/SKILL.md

@@ -0,0 +1,513 @@
+---
+name: health-cloud-referral-management-coordinate
+description: "Guided end-to-end setup of Health Cloud Referral Management. Ties the individual Setup pages, features, and integrations an admin would otherwise navigate by hand into one ordered, resumable, seven-act workflow: Act 0 foundation & preconditions (Health Cloud license, Person Accounts prereq, OmniStudio runtime, Clinical Service Request discovery), Act 1 turn on Referral Management (the ClinicalServiceRequest core — configure the CSR record page, configure the referral path, and set up Actionable Segmentation follow-up lists), Act 2 internal referral creation & routing (Create Referral flow, Include Referral Action in Provider Search via Criteria-Based Search & Filter, Case record type + Create-Case-from-CSR flow, Patient Referral expression set + decision table, Action Plans, CSR status/status-reason picklists, flow orchestration), Act 3 eligibility / prior auth / predictive scoring (EBV & PA Apex, MuleSoft FHIR named credential, Data Cloud scoring data kit), Act 4 outreach + appointment sync, Act 5 external document intake (Document AI for Health), and Act 6 the public referral portal (Experience Cloud guest site, reCAPTCHA verification, Web-to-Case, Create Referral OmniScript, analytics, and the guest referral record owner). Triggers on \"set up Referral Management\", \"configure Referral Management\", \"enable Referral Management\", \"set up patient referrals\", \"configure clinical referrals\", \"set up referral intake\", \"enable the referral portal\", \"set up the guest referral form\", \"configure referral management and the public intake site\". Encodes the hard ordering the UI does not surface (the backing feature must be ON before its component binds) and is explicit about which steps are live-dispatchable via the project-codey MCP versus which are GAPS (MDAPI-zip-only components, external systems, StandardValueSet-backed standard-field picklists). State-aware and resumable: re-read current org state before acting on any step."
+metadata:
+  version: "1.0"
+  cliTools:
+  - tool:
+    - "sf"
+    semver: ">=2.0.0"
+---
+
+**Setting up Referral Management means running all seven acts in order — Act 0 (foundation), Act 1 (turn on Referral Management), Act 2 (internal referral creation & routing), Act 3 (eligibility / prior auth / scoring), Act 4 (outreach + appointment sync), Act 5 (external document intake), and Act 6 (public referral portal).**
+
+Guide an admin through standing up **Health Cloud Referral Management** in the **strict order** the underlying preferences and platform features require, with a validate-only stance on anything genuinely external to Salesforce (Health Cloud license, Person Accounts, MuleSoft, Marketing Cloud, Google reCAPTCHA, Data Cloud kits).
+
+This skill drives the **project-codey MCP** (`discover` → `describe` → `dispatch`) against the target org. Most steps are live-dispatchable: the Referral Management org-preference toggles, Criteria-Based Search & Filter, the guest-referral record owner, appointment sync, reCAPTCHA verification, the Case record type (Tooling `RecordType`), the Business Rules Engine routes (expression set + decision table), and the flow/Apex/OmniScript/Experience-site surfaces. The rest are GAPS — external systems, user-level entitlements the running identity lacks, multipart-only transports `dispatch` can't send, **or Metadata-API types the Core MetadataCrud allowlist rejects (`PathAssistant`, `BusinessProcess`, `NamedCredential` — live-verified `UNSUPPORTED_OPERATION`), which are deployed via the Salesforce-CLI MDAPI fallback (rule 3/3a/5)**. **Surface every gap with its remediation; never fake a call for one.** Gate every write on an independent read-back, never the write's own echo.
+
+## Scope & definition of done — READ THIS FIRST
+
+**An unqualified "set up / configure / enable Referral Management" means run ALL SEVEN ACTS in order (Act 0 → … → Act 6).** The setup is complete only when every non-gapped step has reached its verified end state (gate on the `verify-*` read-back, never the write echo) and every gapped step has been surfaced with its manual remediation. A run that ends partway through is a *partial* run — say so plainly if you must stop early.
+
+**Deferred / gapped steps are NOT stop signals. Never fabricate a call for a gapped step — but before declaring a gap, try a second transport (Tooling sObject / metadata xmlRep / Connect).**
+
+### Manual-step documentation contract — ALWAYS cite the Help link
+
+When you finish (or stop) and enumerate the **manual / out-of-band steps the admin must complete by hand** (MDAPI-zip component binds, `StandardValueSet` multipart deploys, Flow-Builder "Save As New Flow" clones, Setup-UI-only designers, external systems, or entitlement/license gaps), you **MUST include the Salesforce Help link for each one**. Never present a bare "you'll need to do X manually" without the doc that tells the admin *how*. The links live in two places, both authoritative — use whichever you have in hand:
+
+1. The **`manual_step_references`** map in this skill's structured data (a step-id → `{label, why_manual, help_urls}` table, where `help_urls` is a **list** — a step may need more than one doc, so cite **every** URL in it) — the canonical, queryable source.
+2. The per-capability tables in Acts 0–6 below, where each step's Help article is linked inline.
+
+The manual steps and their Help articles (keep this in sync with the `manual_step_references` overlay):
+
+| Manual step (id) | Why it's manual | Help article |
+|---|---|---|
+| `assign-clinical-service-request-page-layout` | CSR Lightning-page industries-component binds: try a whole-page read-modify-write `/headless/metadata` PUT first (a live check bound patientCard/timeline this way; earlier "silently dropped" reports were partial-page PUTs), fall back to an MDAPI zip deploy only if a read-back shows the bind didn't persist | [hc_admin_referral_management_clinical_service_request_layout](https://help.salesforce.com/s/articleView?id=ind.hc_admin_referral_management_clinical_service_request_layout.htm&type=5) |
+| `configure-referral-actionable-lists` | DPE / actionable-list **definition** is authored in the Actionable Segmentation designer (Setup-UI) | [actionable_segmentation_setup_lists](https://help.salesforce.com/s/articleView?id=ind.actionable_segmentation_setup_lists.htm&type=5) |
+| `create-referral-screen-flow` | "Save As New Flow" clone of the packaged flow is Flow-Builder-UI-only (managed flow opaque to the API) | [hc_admin_referral_management_flow](https://help.salesforce.com/s/articleView?id=ind.hc_admin_referral_management_flow.htm&type=5) |
+| `include-referral-action-in-provider-search` | Search-criteria / searchable-object / search-action authoring is in the CBS&F designer (Setup-UI) | [hc_admin_provider_search_criteria_based](https://help.salesforce.com/s/articleView?id=ind.hc_admin_provider_search_criteria_based.htm&type=5) |
+| `create-case-from-csr-flow` | "Save As New Flow" clone is Flow-Builder-UI-only | [hc_admin_referral_management_case_creation_flow](https://help.salesforce.com/s/articleView?id=ind.hc_admin_referral_management_case_creation_flow.htm&type=5) |
+| `add-csr-status-picklist-values` | CSR `Status` = `StandardValueSet` **multipart** MDAPI deploy (rule 3c); `dispatch` can't send it — drive via a Metadata API deploy (Salesforce CLI; concrete command in the execution-policy notes) or the Setup UI | *(no dedicated article — StandardValueSet transport, skill Transport rule 3c; feeds the BRE decision table, [hc_admin_referral_management_configure_use_bre_flow](https://help.salesforce.com/s/articleView?id=ind.hc_admin_referral_management_configure_use_bre_flow.htm&type=5))* |
+| `add-csr-status-reason-picklist-values` | CSR `StatusReason` = `StandardValueSet` multipart MDAPI deploy (rule 3c), same mechanics as above | *(no dedicated article — StandardValueSet transport, skill Transport rule 3c)* |
+| `activate-referral-flow-orchestration` | In-place activation of the packaged orchestrator is Flow-Builder-UI-only | [hc_admin_referral_management_configure_csr_flow_orchestration](https://help.salesforce.com/s/articleView?id=ind.hc_admin_referral_management_configure_csr_flow_orchestration.htm&type=5) |
+| `install-datacloud-referral-scoring-data-kit` | External Data Cloud data kit — no cold-install route | [hc_admin_referral_management_predictive_scoring_setup](https://help.salesforce.com/s/articleView?id=ind.hc_admin_referral_management_predictive_scoring_setup.htm&type=5) |
+| `place-outbound-engagement-home-component` | Industries component binds via an MDAPI **FlexiPage** deploy (Salesforce CLI), not `dispatch`/`/headless/metadata` PUT | [hc_admin_referral_management_configure_patient_provider_outreach_template](https://help.salesforce.com/s/articleView?id=ind.hc_admin_referral_management_configure_patient_provider_outreach_template.htm&type=5) |
+| `prepare-external-referral-fax-intake` | Document AI for Health guided setup + IDP extraction-definition authoring (Setup-UI) + Agentforce for Health Cloud add-on license | [hc_admin_referral_management_process_received_document](https://help.salesforce.com/s/articleView?id=ind.hc_admin_referral_management_process_received_document.htm&type=5) · [hc_admin_disease_surveillance_set_up_pdf_ingestion_idp](https://help.salesforce.com/s/articleView?id=ind.hc_admin_disease_surveillance_set_up_pdf_ingestion_idp.htm&type=5) |
+| `provision-referral-experience-cloud-site` (site finish) | Public Access, guest profile, Security & Privacy, Activate are Experience-Builder-UI-only | [hc_admin_referral_management_guest_users_site_build](https://help.salesforce.com/s/articleView?id=ind.hc_admin_referral_management_guest_users_site_build.htm&type=5) |
+| `register-recaptcha-site-key` | External Google reCAPTCHA console (v2 checkbox) sign-up | [hc_admin_referral_management_guest_users_recaptcha](https://help.salesforce.com/s/articleView?id=ind.hc_admin_referral_management_guest_users_recaptcha.htm&type=5) |
+| `generate-web-to-case-html` | Setup-UI Web-to-Case HTML Generator (registers the reCAPTCHA key-pair nickname) | [hc_admin_referral_management_guest_users_recaptcha](https://help.salesforce.com/s/articleView?id=ind.hc_admin_referral_management_guest_users_recaptcha.htm&type=5) |
+| `activate-create-referral-omniscript` | OmniStudio OmniScript editor "New Version" (Setup-UI) | [hc_admin_referral_management_guest_users_omniscript_configure](https://help.salesforce.com/s/articleView?id=ind.hc_admin_referral_management_guest_users_omniscript_configure.htm&type=5) |
+| Act 6 Phase A — get org ready | Perms + Digital Experiences + org Trusted URL setup (Setup-UI) | [hc_admin_referral_management_guest_users_org_ready](https://help.salesforce.com/s/articleView?id=ind.hc_admin_referral_management_guest_users_org_ready.htm&type=5) |
+| Act 6 Phase E — customize the site | Guest access + head markup + OmniScript placement (Experience-Builder-UI) | [hc_admin_referral_management_guest_users_site](https://help.salesforce.com/s/articleView?id=ind.hc_admin_referral_management_guest_users_site.htm&type=5) · [_config](https://help.salesforce.com/s/articleView?id=ind.hc_admin_referral_management_guest_users_config.htm&type=5) · [recaptcha_markup](https://help.salesforce.com/s/articleView?id=ind.hc_admin_recaptcha_markup.htm&type=5) · [_site_omniscript](https://help.salesforce.com/s/articleView?id=ind.hc_admin_referral_management_guest_users_site_omniscript.htm&type=5) |
+| `review-guest-referral-security-exposure` | **PHI safety gate** — guest object access + sharing-rule scope is reviewed by hand in Experience Builder / Setup (Sharing Settings) **before** Publish; no served API enumerates the guest-visible surface | [hc_admin_referral_management_guest_users_site](https://help.salesforce.com/s/articleView?id=ind.hc_admin_referral_management_guest_users_site.htm&type=5) · [_config](https://help.salesforce.com/s/articleView?id=ind.hc_admin_referral_management_guest_users_config.htm&type=5) |
+| `verify-guest-site-published-and-scoped` | Post-publish validation — confirming the live public site renders only the referral form (and enforces reCAPTCHA) requires an unauthenticated guest load; no served API performs a guest load | [hc_admin_referral_management_guest_users_site_build](https://help.salesforce.com/s/articleView?id=ind.hc_admin_referral_management_guest_users_site_build.htm&type=5) · [_org_ready](https://help.salesforce.com/s/articleView?id=ind.hc_admin_referral_management_guest_users_org_ready.htm&type=5) |
+
+## Mandatory pre-write plan — state this before your FIRST write
+
+Before you execute a single write operation (any toggle, any deploy), post a short plan to the admin that makes your scope decision **explicit and reviewable**:
+
+1. **The full journey is seven acts** — list them: Act 0 (foundation), Act 1 (turn on Referral Management), Act 2 (creation & routing), Act 3 (eligibility/PA/scoring), Act 4 (outreach + appointment sync), Act 5 (external intake), Act 6 (public portal).
+2. **Which steps are live-dispatchable vs GAP.** Most steps are live-dispatchable via `dispatch` across four transport families (Aura toggles, Tooling sObjects, the metadata xmlRep master transport, and Connect APIs — see Prerequisites §B). Name the toggles + creates you will perform, and the gaps you will only surface: external systems (Data Cloud kit, Marketing Cloud, Google reCAPTCHA), manual-UI (Web-to-Case HTML), and entitlement/feature/context blocks (Document AI for Health license; runtime feature; guest-only context; unprovisioned analytics template). The CSR `Status`/`StatusReason` picklist adds (steps 18/19) are achievable but out-of-band — a `StandardValueSet` MDAPI deploy (multipart, so not via `dispatch`), driven via the Salesforce CLI or the Setup UI. Call out that `enable-person-accounts` is IRREVERSIBLE and fired only on explicit authorization.
+3. **Person Accounts is a MANDATORY prerequisite** (HC platform docs + the RM PRD; see Prerequisites §A.2). State your stance: read PA state first; if ON, proceed; if OFF, the setup is BLOCKED until it is enabled — delegate to initial-setup, or drive the IRREVERSIBLE `enable-person-accounts` chain (Transport rule 7) only on explicit authorization. Never report the setup complete with PA off.
+4. **Where you will start.** For an unqualified request this is Act 0, step 1 — never mid-flow.
+
+## Supported utterances
+
+- "Set up Referral Management" / "Configure Referral Management" / "Enable Referral Management"
+- "Set up patient referrals" / "Configure clinical referrals" / "Set up referral intake"
+- "Enable the referral portal" / "Set up the guest referral form" / "Configure the public referral intake site"
+- "Turn on the Referral Management app" (narrow → Act 1, but confirm the Act 0 prereqs first)
+- "Set the guest referral record owner" (narrow → Act 6 owner step)
+
+## Session state (track across the conversation)
+
+- `target_org_alias` — the org being configured; confirmed explicitly before any write (never silently inherited). All org interaction is through the project-codey MCP against the connected org.
+- `person_accounts_confirmed` — bool; Person Accounts is confirmed ON (`Account.IsPersonAccount` exists / a PersonAccount record type is present). **Person Accounts is a MANDATORY RM prerequisite** (HC platform docs + the RM PRD). This gate must be `true` before any Act 1–6 write; if PA is OFF, the setup is BLOCKED until it is enabled (here, on explicit authorization of the irreversible enable, or via [[health-cloud-initial-setup]]).
+- `act0_complete` … `act6_complete` — bool per act; acts run strictly 0→1→…→6. For an unqualified request, all seven must reach `true` (or be explicitly reported as gate-blocked/gapped) before you report the setup complete.
+- `gaps_surfaced` — the running list of gapped steps you have reported to the admin. **Each entry is a triple `{step, remediation, help_urls}` — the Salesforce Help link(s) are a REQUIRED field of every entry, not an optional extra. `help_urls` is a list: most steps have one doc, but some (e.g. `prepare-external-referral-fax-intake`, `act6-phase-e-customize-site`) have several — carry ALL of them.** Look the `help_urls` up by step id in the Manual-step documentation contract table above (mirrored in the `manual_step_references` map). The final summary enumerates this list, so a missing (or dropped) link here becomes a missing link in the summary — never append a gap without its full link set.
+
+## Entry point — route on the admin's actual ask
+
+**Default rule:** unless the admin's ask *explicitly narrows the scope*, treat it as the full setup and **run Acts 0→6 in order.** When in doubt, run the full journey.
+
+| Signal | Where to start |
+|---|---|
+| **"Set up Referral Management" / "configure referral management" / "enable patient referrals" / no narrowing qualifier / no prior state known** | **Run the FULL journey: `verify-health-cloud-license` (Act 0 step 1), then Acts 0→1→…→6 in order. Not done until every non-gapped step is verified and every gap is surfaced.** |
+| "Just turn on the Referral Management app" | Narrow → Act 1, but first run the Act 0 prereq reads (license, Person Accounts, current settings). |
+| "Set up the public / guest referral form" | Narrow → Act 6 — the portal steps depend on the Act 1 CSR core being configured. |
+| "Set the guest referral record owner" | Narrow → Act 6 owner steps (`read-guest-referral-record-owner-candidates` → `set-guest-referral-record-owner`). |
+| Person Accounts is OFF | **BLOCKER** (see Prerequisites §A.2 / Transport rule 7). Enable via the IRREVERSIBLE `enable-person-accounts` chain only on explicit authorization, else redirect to [[health-cloud-initial-setup]]. Do not proceed through Acts 1–6 or report "done" while PA is off. |
+
+## Decision points (confirm before Act 1 writes; drive optional steps)
+
+This workflow's optional surfaces are driven by the admin's answer to two questions. Confirm them up front; they gate which later steps run vs are skipped.
+
+### 1. Portal scope — default `internal-only`
+
+> Do you need the **public guest referral portal** (Experience Cloud site + reCAPTCHA + Web-to-Case + guest OmniScript), or **internal referral creation only**?
+
+- **`internal-only` (default):** Run Acts 0–5 plus the internal parts of Act 6 you can reach. **Skips** the Experience Cloud site provisioning, reCAPTCHA key registration, and Web-to-Case generation gaps.
+- **`with-public-portal`:** Run all of Act 6. The guest-site provisioning, reCAPTCHA site-key registration, and Web-to-Case HTML are GAPS (external/manual) — surfaced, not automated. The `enable-captcha-verification` toggle and the `set-guest-referral-record-owner` write ARE live-dispatchable.
+
+### 2. Advanced modules — default `defer-external`
+
+> Do you need the advanced modules — eligibility/prior-auth (EBV, MuleSoft FHIR), predictive scoring (Data Cloud), Marketing Cloud outreach, document/fax intake — configured now?
+
+- **`defer-external` (default):** Surface Acts 3–5 as GAPS with their external-dependency remediation and move on. Acts 3–4 are not live-dispatchable via the MCP; in Act 5, the Disease Surveillance and Batch Document AI org-preference toggles ARE live-dispatchable — the gaps there are the Agentforce for Health Cloud add-on license, the IDP guided-setup authoring, and the flow/queue wiring (see Act 5).
+- **`configure-now`:** Same behaviour — Acts 3–4 remain GAPS regardless (external systems / MDAPI-zip Apex), and Act 5 still gaps on license + IDP authoring + flows — but you will fire Act 5's live preference toggles and walk the admin through each remaining remediation in detail rather than a one-line summary.
+
+## Prerequisites
+
+### A. True prerequisites — validate before anything else (Act 0)
+
+Act 0 has exactly **two** prerequisites. Validate both up front, surface each as a discrete checked line (✅/❌ + the value you queried), and if **either is unmet, STOP** — fire no Act 1–6 write and redirect. Don't try to fix a foundational gap from inside this skill.
+
+1. **Health Cloud Initial Setup is complete.** Do NOT re-implement the foundational Health Cloud checks in this skill — **delegate to the [[health-cloud-initial-setup]] SOR and run only its READ / verify steps (never any WRITE)** to confirm Health Cloud basic setup is done. That verification is the real gate; it subsumes: the Health Cloud license (the RM-side confirmation is `verify-health-cloud-license`), the **Health Cloud Platform Permission Set License** on the running admin, and the OmniStudio metadata runtime. **If Health Cloud is not set up, STOP the referral management setup and direct the user to complete Health Cloud initial setup first.**
+   - A Life Sciences Cloud license does NOT satisfy this — the gate keys on the Health Cloud license entitlement, not the license's marketing name. Name the prerequisite permission-set license exactly **"Health Cloud Platform Permission Set License"** in admin-facing output (not "Health Cloud Foundation").
+   - *OmniStudio:* the prerequisite is a **two-setting toggle** on the OmniStudio Settings page — **disable "Managed Package Runtime" AND enable "OmniStudio Metadata"** — so components run as native metadata. It is not on by default. Only the Create Referral OmniScript (Act 6) hard-depends on it; Act 0's `check-omnistudio-runtime` read seeds that (it reads only `standardOmniStudioRuntime`, the metadata-enabled half, and does NOT confirm Managed Package Runtime is off).
+   - *Admin access* (Modify All Data, or Customize Application + View/Modify Setup) for the running identity is required — the dispatcher `/headless/invoke/...` routes require it.
+2. **Person Accounts is enabled and configured correctly.** Referral Management resolves its Clinical Service Request patient as a PersonAccount, so PA must be ON and set up. **This may already have been covered by the Health Cloud Initial Setup checks in (1)** — if the delegated reads already confirmed PA, don't re-check. If PA is OFF, it is an IRREVERSIBLE platform feature owned by [[health-cloud-initial-setup]]: either redirect there, or — **only on explicit authorization of the irreversible enablement** — drive the readiness-gated `enable-person-accounts` chain (Transport rule 7). **Never proceed with PA off.**
+
+### B. Automatable by this skill (via the project-codey MCP)
+
+Most steps are live-dispatchable via `dispatch` across four transport families:
+
+- **Aura toggles + reads** (`/headless/invoke/...`): `enable-criteria-based-search-and-filter`, `enable-appointment-sync`, `enable-captcha-verification`, `read-guest-referral-record-owner-candidates` → `set-guest-referral-record-owner`, plus the Act-0 reads and `enable-person-accounts` (irreversible; readiness-gated — Transport rule 7).
+- **Tooling sObjects**: `assign-clinical-service-request-page-layout` (`Layout`), `create-case-record-type` (`RecordType`, needs a Case BusinessProcess deployed first), the three Flows + orchestration activation (`Flow`/`FlowDefinition`), `create-ebv-prior-auth-apex-classes` (`ApexClass`).
+- **Metadata xmlRep master transport** (`/services/data/v67.0/headless/metadata`, Transport rule 3): `activate-create-referral-omniscript` (`OmniProcess`) and Settings singletons. **NOT** `configure-referral-management-path` (`PathAssistant`), `create-case-business-process` (`BusinessProcess`), or `create-mulesoft-fhir-named-credential` (`NamedCredential`) — the Core MetadataCrud allowlist rejects those three (`UNSUPPORTED_OPERATION`, live-verified), so they go via the **Salesforce-CLI MDAPI deploy** fallback (rule 3/3a/5).
+- **Connect APIs**: `configure-patient-referral-expression-set` + `load-patient-referral-decision-table` (Business Rules Engine, rule 4a), `provision-referral-experience-cloud-site` + `provision-ebv-callback-experience-site` (`POST /connect/communities`, rule 4), `assign-action-plans-permission-set` (Data-API `PermissionSetAssignment`), and the `create-referral-runtime` / `create-guest-referral-runtime` smoke tests.
+
+The genuine GAPS are NOT transport problems: external systems (Data Cloud kit, Marketing Cloud, Google reCAPTCHA), manual-UI-only (Web-to-Case HTML), and entitlement/feature/context blocks (Document AI for Health license; Referral Management runtime feature for the running user; guest-only execution context; HLS Modernization analytics template not provisioned). **Separately, the CSR `Status`/`StatusReason` picklist adds (steps 18/19) are achievable but out-of-band** — the `StandardValueSet` MDAPI deploy that adds them (rule 3c) is `multipart/form-data`, which `dispatch` can't send, so a pure-MCP agent must fall back to the Salesforce CLI or the Setup UI (dispatch-first, CLI-fallback — Transport rule 0). See each Act's notes.
+
+## Transport & deploy discipline (applies to EVERY Act — read before your first write)
+
+These rules are cross-cutting.
+
+**Rule 0 — dispatch-first, CLI-fallback, manual last.** The project-codey MCP is the primary transport for EVERY step: first search the catalog (`discover` / `discover` → `describe` → `dispatch`) for a served Connect API or `/headless` operation that performs the step, then dispatch it and gate on an independent read-back. Only when NO served operation exists (a routes gap — search returns nothing / `dispatch` 404s), the dispatch errors, or the read-back shows the change did not stick, fall back to a **Metadata API deploy via the Salesforce CLI** — but only if you have shell access with the CLI resolvable and an authenticated target-org alias; build the minimal metadata source, deploy, and gate on the same read-back. Surface a step as a manual / out-of-band action (citing its Salesforce Help link) only as the LAST resort, when neither the platform nor the CLI can complete it. Never hand the admin a manual step you could have dispatched or deployed; never claim a step done without a read-back. The concrete CLI commands live in the skill's execution-policy notes; the steps that stay manual even WITH CLI access (external systems, managed-content clones, Setup/Experience-Builder-UI-only designers) are called out per Act.
+
+1. **Everything goes through the project-codey MCP.** `discover` (search — try multiple angles / search by controller class / `list_apis` by team before declaring "no API") → `describe` (ALWAYS before any PATCH/POST — you need the full input schema) → `dispatch` (hits the connected org). `implemented` = a real core Connect API; `proposed` = an Aura controller behind the Headless360 dispatcher (`/headless/invoke/...`). Both are first-class.
+
+2. **Prefer the `/headless/invoke/...` Aura toggles for the referral prefs** over any metadata equivalent: `enable-criteria-based-search-and-filter`, `enable-appointment-sync`, `enable-captcha-verification`, and the `owner-id-setup` read+`save-owner` chain each return 200; gate on an independent read-back.
+
+3. **`/services/data/v67.0/headless/metadata` is the xmlRep master transport — but it is backed by a STATIC MetadataCrud allowlist (Core-side `setup-ui-crud-api`), NOT every Metadata-API type.** Body is `{type, fullName, xmlRep}` where `xmlRep` is a **Metadata-API XML string** for the component. **Verb split: POST = create, PUT = update/merge (component-level).** It reaches the types the allowlist covers — verified live for Settings singletons (`type:IndustriesSettings`, GET + PUT) and `type:OmniProcess` (step 35; the schema validator walks required fields one at a time, e.g. `omniProcessType` then `uniqueName`, so probe the 400-chain to complete the body). **A type the allowlist does NOT cover returns `400 UNSUPPORTED_OPERATION "MetadataCrud does not support CREATE/READ on type: <T>"` — this is a hard Core gate, not a body problem.** `PathAssistant` (step 7), `BusinessProcess` (step 13 — even embedded in a parent `CustomObject`; see rule 3a), and `NamedCredential` (step 24) are all UNSUPPORTED for both CREATE and READ (live-verified) — deploy them via the MDAPI CLI fallback (Transport rule 0; same `sf project deploy start --metadata-dir` mechanics as rule 3c), and gate on a Tooling read-back. Use the version-prefixed path; the un-prefixed `/headless/metadata` (Aura-dispatcher) form returns `"No controller mapping"` and is NOT wired.
+
+   3a. **A Case `BusinessProcess` is NOT reachable through `/headless/metadata` at all — deploy it via the MDAPI CLI fallback.** Neither the top-level `type:BusinessProcess` nor embedding it as a `businessProcesses` child of a parent `type:CustomObject` (`fullName:"Case"`) works: Core resolves the child to its own type and returns `400 UNSUPPORTED_OPERATION "MetadataCrud does not support CREATE on type: BusinessProcess"` (live-verified). The Tooling-REST `POST .../tooling/sobjects/BusinessProcess` path also fails (the complexvalue deserializer rejects scalar `Metadata` sub-fields). **The working transport is an MDAPI deploy** (rule 3c mechanics): build a minimal `objects/Case.object` (or a `businessProcesses`-scoped `CustomObject` component) with the `<businessProcesses>` element and deploy via the Salesforce CLI, then gate on a Tooling read-back. **The `<values>` inside the `businessProcesses` MUST be a subset of the target org's LIVE `Case.Status` picklist values — these vary per org, so discover them live (describe / `FieldDefinition`) before building the body; do NOT copy values from this SKILL or the SOR.** A value the org doesn't have fails deploy with `FIELD_INTEGRITY_EXCEPTION "Picklist value: <X> not found"`.
+
+   3b. **The Case record type itself is created via the Tooling `RecordType` sObject** (after its BusinessProcess exists, rule 3a): `POST /services/data/v67.0/tooling/sobjects/RecordType` with `{FullName:'Case.<Name>', Metadata:{label, active, businessProcess:'<BP name>'}}` → 201. A Case RecordType REQUIRES `businessProcess` (400 "businessProcess required" without it) — unlike an **Account** RecordType, which needs none. RecordTypes are `deletable:false` via Tooling — deactivate (`active:false`), never DELETE. Gate on a Tooling `RecordType` read-back (confirm `BusinessProcessId` points to the BP).
+
+   3c. **Standard picklist values on standard entities cannot be added via ANY REST transport — and the parent-CustomObject `valueSet` PUT returns a FALSE-POSITIVE `success:true` that is a SILENT NO-OP.** For CSR `Status`/`StatusReason`, all three transports fail: (a) Tooling `CustomField/ClinicalServiceRequest.Status` PATCH → 404 (standard fields are not `00N…`-addressable); (b) `type:CustomField` inline `valueSet` → `success:false FIELD_INTEGRITY_EXCEPTION "cannot define valueSet on a standard field. Use StandardValueSet instead"`; (c) the rule-3a parent pattern `PUT type=CustomObject` embedding `<fields><fullName>Status</fullName><valueSet>…` returns `success:true` **but the value is NOT added** (describe read-back shows original values unchanged). **Always verify a picklist write with a `describe` read-back — a false-positive success is more dangerous than an honest rejection.** The backing `StandardValueSet` DeveloperNames are **`CServiceRequestStatus`** (CSR `Status`) and **`CServiceRequestStatReason`** (CSR `StatusReason`); direct Tooling `StandardValueSet` PATCH fails (`FIELD_INTEGRITY "Full name must be specified"` / `MALFORMED_ID` / `Unable to load specified entity`; sentinel Id `000000000000000AAA`). **The working transport is an MDAPI `StandardValueSet` deploy:** `POST /services/data/v67.0/metadata/deployRequest` (`multipart/form-data`: JSON `deployOptions` + a zip of `package.xml` + `standardValueSets/<Name>.standardValueSet`). Because that endpoint is `multipart/form-data`, **`dispatch` (JSON body only) cannot send it** — drive the deploy via the Salesforce CLI (concrete `deployRequest` command in the execution-policy notes), a direct multipart HTTP POST to `/metadata/deployRequest`, the Metadata API SOAP endpoint, or the Setup UI picklist editor. Two load-bearing deploy rules: **(1) the deploy REPLACES the full value list, it does NOT merge** — **retrieve the existing `StandardValueSet:CServiceRequestStatus` FIRST** (via the same CLI) to capture the authoritative existing `fullName`s (the shipped FHIR values), then deploy the union (existing + new) or you drop the shipped values; **(2) the stored API `fullName`s use underscores** — `Waiting_for_Response`, `Manual_Review_Needed`, `Closed_No_Appointment` (labels have spaces/hyphens) — so the decision table (steps 16/17) must key on the underscore API values, not the display labels. `add-csr-status-picklist-values` / `add-csr-status-reason-picklist-values` are required content, achievable but out-of-band relative to the JSON-only `dispatch` surface.
+
+4. **Flows, Apex, OmniScripts, and Experience sites are all headlessly creatable via `dispatch` — no multipart MDAPI zip needed:**
+   - **Flows (screen, autolaunched, orchestrator) create via the Tooling `Flow` sObject** — `POST /services/data/v67.0/tooling/sobjects/Flow` with a JSON `Metadata` complexvalue (processType `Flow` / `AutoLaunchedFlow` / `Orchestrator`). Screen/canvas elements REQUIRE `locationX`/`locationY` (else 400 "Required field is missing: locationX"). (See Act 2 — for the packaged referral flows, clone rather than build from scratch.)
+   - **Flow activation is a Tooling `FlowDefinition` PATCH** — `PATCH /services/data/v67.0/tooling/sobjects/FlowDefinition/{id} {Metadata:{activeVersionNumber:N}}` → 204; read-back shows `ActiveVersionId` populated.
+   - **Apex classes create via the Tooling `ApexClass` sObject** — `POST /services/data/v67.0/tooling/sobjects/ApexClass {Body:"<full compilable source>"}` → 201. NEW classes POST directly; *updates* to an existing class need a `MetadataContainer` + `ContainerAsyncRequest`.
+   - **OmniScripts create+activate via the rule-3 metadata master transport** — `POST type:OmniScript` to create, then `PUT` with `isActive=true` to activate; read-back the `OmniProcess` via the **Data API** (`IsActive=true`; Tooling gives a misleading `INVALID_TYPE`). The create yields a *structural shell* — a functional OmniScript still needs its full element tree / `propertySetConfig` (a designer export). See Act 6 (clone the packaged OmniScript rather than build a shell).
+   - **Experience Cloud sites cold-create via `POST /services/data/v67.0/connect/communities`** `{name, templateName, urlPathPrefix}` → **202** `{jobId}` (async `SiteTaskCreate`); poll `BackgroundOperation` by that `jobId` until `Status:Complete`, then confirm the `Network` row exists. Requires Digital Experiences already enabled. Publishing the site Live + guest/branding config are follow-on steps.
+
+   The one hard multipart limit is the CSR `Status`/`StatusReason` picklist adds (steps 18/19 — rule 3c); every other step is reachable through `dispatch`.
+
+   4a. **PRECONDITION — the Business Rules Engine FAMILY must be provisioned on the org, and it CANNOT be self-enabled headlessly.** Steps 16/17 create cleanly *only* when the BRE family is on. Without it, both calls hard-fail with a feature gate: `GET /connect/ruleengine/usage-types` → **403 `FUNCTIONALITY_NOT_ENABLED [BusinessRuleEngineFamily]`** and `POST /connect/business-rules/expression-set` → **403 `FUNCTIONALITY_NOT_ENABLED [InteractionCalculationProcedures]`** (the decision table additionally needs the Decision Table permission). The candidate enable route `PATCH /headless/invoke/platform/bredecision-table-access/handle-pref-enable` does NOT work headlessly (500 `CONTROLLER_ERROR` — the pref's `orgAccess` expression rejects the write). So on an org without the BRE family, **steps 16/17 are a hard GAP** (`feature_not_enabled: BusinessRuleEngineFamily / InteractionCalculationProcedures`): surface it, have the family enabled through the provisioning/licensing path (not a Setup toggle), then re-run.
+
+   Once provisioned: `POST /connect/business-rules/expression-set` requires `usageType`, which MUST be a value from `GET /connect/ruleengine/usage-types` — **`Bre`** (label "Default") is the general-purpose type; free-text guesses ("Decisioning") 400 "Value does not match expected type". `POST /connect/business-rules/decision-table/definitions` needs BOTH `dataSpaceName` AND a `parameters[]` array (absent `parameters` → 500 NPE); `parameters[].dataType` ∈ `{Boolean,Currency,Date,DateTime,Number,Percent,String}` (**not** "Text"); `usage` ∈ `{Input,Output,RowCriteria}`; **Output fields must NOT carry a `sequence`** ("You can't specify the sequence number for output fields"); needs the Decision Table permission. The "update Clinical Service Request status" table has FOUR ordered columns — **THREE Inputs (`WorkType`, `CSRStatusReason`, `InsuranceStatus`; `usage=Input`, each with an ordered `sequence` 1..3) mapping to ONE Output (`CSRStatus`; `usage=Output`, OMITS `sequence`)**. CSR Status is the OUTPUT the table sets, not an input. Row/data loads follow via `postDecisionTableFile`/`postDecisionTableRows`. **Use `type: LowVolume`, `sourceType: SingleSobject`, `sourceObject: ClinicalServiceRequest`, `dataSpaceName: 'default'`.** This succeeds with no data-space-registration step — `ClinicalServiceRequest` need only be **queryable** (`SELECT Id,Status,StatusReason FROM ClinicalServiceRequest` returns 200, even at 0 rows). Do NOT switch to `type: RealTime` to work around a failure: `RealTime` is Data Cloud-backed and returns `INVALID_API_INPUT "To set Type to RealTime, make sure that dataSourceType is set to ContextDefinition."` — a different source model this DT does not need. If a `LowVolume`/`SingleSobject` create returns `INVALID_CROSS_REFERENCE_KEY`, treat it as a **body/reference** problem (confirm `dataSpaceName='default'` resolves and that `sourceObject` + every `parameters[].fieldName` exist on the object), not an org-provisioning blocker.
+
+5. **A live probe overrides the corpus `status` flag — and when one transport 500s, look for a second before declaring a gap; but a second transport is not guaranteed to exist.** Example: `describe` reports the Aura `save-path-assistant` route as `implemented`, but a live call returns **500 `CONTROLLER_ERROR "appInfo is null"`** (the dispatcher can't populate the UI-service application context, and no body param injects it) — a dead end. The `/headless/metadata` master transport does NOT rescue it either: `PathAssistant` is **not on the Core MetadataCrud allowlist** — both `POST type:PathAssistant` and the READ return `400 UNSUPPORTED_OPERATION "MetadataCrud does not support CREATE/READ on type: PathAssistant"` (live-verified). So `configure-referral-management-path` is reached via the **Salesforce-CLI MDAPI deploy** fallback (rule 0): build a minimal `pathAssistants/<Name>.path` component and `sf project deploy start`, then read-back via Tooling `PathAssistant`.
+
+6. **Re-read to verify — never trust the write's own echo.** Toggles echo the written value; gate on the INDEPENDENT read-back (the `verify-*` step), which confirms the preference actually persisted. Where a route is irreversible or org-scoped, only fire after explicit confirmation and a read that shows it is genuinely off.
+
+7. **Person Accounts enablement is a readiness-gated 3-write chain — prefer the PROPOSED Aura wizard route over the implemented Connect endpoint.** `GET /headless/invoke/platform/person-account-settings` returns four gates (`termsConditionsAccepted`, `accountRecordTypeCreated`, `profilePermsSet`, `orgWideSharingSet`) + `allStepsComplete`. When profile-perms and OWD-sharing already pass, drive: (1) `PATCH .../person-account-settings/accept-terms-and-conditions`; (2) create an Account `RecordType` via Tooling (`{FullName:"Account.<Name>", Metadata:{label, active:true}}` — an **Account** RT needs NO businessProcess, unlike a Case RT, rule 3b); (3) re-read until `allStepsComplete:true`; (4) `PATCH .../person-account-settings/enable-person-accounts` → `personAccountsEnabled:true`; (5) verify with `SELECT Id, IsPersonAccount FROM Account LIMIT 1` (the `IsPersonAccount` field now exists). **The implemented Connect endpoint `POST /connect/accounts/person-accounts-enablement/enable` has a serialization defect (`JSON_PARSER_ERROR: connectProp is null`)** — use the proposed Aura wizard route, which serializes cleanly. Enable is IRREVERSIBLE — fire only on explicit authorization.
+
+---
+
+## Act 0 of 6 — Prerequisites
+
+> **Act 0 is the prerequisite gate. It has exactly two prerequisites (see Prerequisites §A). Validate both before any Act 1–6 write; if either is unmet, STOP and redirect.**
+>
+> 1. **Health Cloud Initial Setup complete** — verify by delegating **READ-only** to the [[health-cloud-initial-setup]] SOR (run only its read/verify steps, never a write). **If Health Cloud is not set up, STOP the referral management setup and direct the user to complete Health Cloud initial setup first.**
+> 2. **Person Accounts enabled & configured** — may already be covered by (1). If PA is off, redirect to initial setup, or — only on explicit authorization of the IRREVERSIBLE enablement — fire the `enable-person-accounts` chain (Transport rule 7). Never proceed with PA off.
+>
+> Beyond the two gates, Act 0 runs a few **read-only state reads** (current RM settings, OmniStudio metadata runtime, CSR picklist baseline) that seed later Acts. These do not gate the flow.
+
+Run these in order. Nothing in Acts 1–6 fires until both prerequisites are confirmed.
+
+| # | Step id | Purpose | Controller / API | Route |
+|---|---|---|---|---|
+| 1 | `verify-health-cloud-license` | **prerequisite 1** — HC initial setup complete | Delegate **READ-only** to the [[health-cloud-initial-setup]] SOR (reads only, no writes); STOP + redirect if HC is not set up. The RM-side license confirmation is the Health Cloud license check. | GET `/headless/invoke/platform/health-cloud-admin-feature-setup/has-health-cloud-licence` (proposed) + the initial-setup SOR's read steps |
+| 2 | `read-referral-management-settings` | read (seeds resumability) | Reads the Referral Management settings | GET `/headless/invoke/platform/referral-management-settings` (proposed) |
+| 3 | `enable-person-accounts` | **prerequisite 2** — PA enabled & configured (write only if off + authorized) | Verify first; if off and authorized: readiness-gated chain accept-terms → Account `RecordType` (Tooling) → `enable-person-accounts` (Transport rule 7) | GET `/headless/invoke/platform/person-account-settings`; PATCH `.../person-account-settings/enable-person-accounts` (proposed) |
+| 4 | `check-omnistudio-runtime` | read (seeds Act 6) | Reads the OmniStudio preferences — including `standardOmniStudioRuntime` (metadata-enabled half of the two-setting toggle) | GET `/headless/invoke/platform/omni-studio-settings/get-omni-studio-prefs` (proposed) |
+| 5 | `discover-clinical-service-request-picklists` | discovery (seeds Act 2) | Tooling: `FieldDefinition`/`EntityParticle` for `ClinicalServiceRequest` Status/StatusReason | GET `/services/data/v67.0/tooling/query/` |
+
+**Act 0 — prerequisite notes (findings):**
+
+- **Prerequisite 1 — Health Cloud Initial Setup complete (`verify-health-cloud-license`).** The delegated read-only [[health-cloud-initial-setup]] verification is the HALT gate (see §A.1). The RM-side spot-check returns a scalar boolean (`true` when provisioned); treat any error/`false` as "not provisioned."
+- **`read-referral-management-settings`** — the settings read returns `{isReferralManagementAppEnabled, isCaptchaVerificationEnabled}`. Not a gate — it is the resumability read for BOTH toggles: Act 1 step 5a (the app master switch) is skipped when `isReferralManagementAppEnabled` already reads `true`, and the Act 6 captcha toggle when `isCaptchaVerificationEnabled` does.
+- **Prerequisite 2 — Person Accounts enabled & configured (`enable-person-accounts`).** May already be confirmed by the prerequisite-1 delegation — if so, don't re-check. If off, drive the readiness-gated chain (Transport rule 7) only on explicit authorization of the irreversible enable, else redirect to [[health-cloud-initial-setup]]; never proceed with PA off. Trust the live readiness read over any stored note about PA state.
+- **`check-omnistudio-runtime`** — read that seeds Act 6 (the Create Referral OmniScript), not a gate for the rest of the flow. Reads only `standardOmniStudioRuntime` (the metadata-enabled half of the two-setting toggle — see §A.1); if false, have the admin flip both settings before Act 6.
+- **`discover-clinical-service-request-picklists`** feeds Act 2. It reads the current `ClinicalServiceRequest` Status + StatusReason picklist values so the Act-2 picklist steps know the baseline. Read-only; ClinicalServiceRequest is a standard Health Cloud entity.
+
+## Act 1 of 6 — Turn on Referral Management (the Clinical Service Request core)
+
+> Act 1 opens by **turning on the Referral Management app master switch** (step 5a, `enableReferralManagementApp`) and reading it back (step 5b) — every referral runtime endpoint (`create-referral-runtime`, the guest form) is gated on it, and nothing else in the flow flips it. Then it runs in the order the Salesforce setup docs prescribe: **first configure the Clinical Service Request record page for referral coordinators** (step 6 — a **Lightning record page / FlexiPage** with four named components + its related lists), **then configure the referral Path** (step 7 — the Aura save route 500s AND the `/headless/metadata` master transport rejects `PathAssistant` as an unsupported type, so it deploys via the Salesforce-CLI MDAPI fallback), **then set up Actionable Segmentation** so coordinators work from follow-up lists of referral providers/patients (step 8).
+
+| # | Step id | Purpose | Controller / API | Route |
+|---|---|---|---|---|
+| 5a | `enable-referral-management-app` | write | **Turn on the Referral Management app** (`enableReferralManagementApp` org pref). Body `{value:true}`; the controller writes the pref only on a Health Cloud org and returns a bare boolean (`false` = nothing written). Skip if step 2 already reads `isReferralManagementAppEnabled:true`. Fallback if the route does not resolve: `/headless/metadata` PUT `{type:"IndustriesSettings", fullName:"Industries", xmlRep:"<IndustriesSettings><enableReferralManagementApp>true</enableReferralManagementApp></IndustriesSettings>"}` (partial `xmlRep` merges; `fullName:"IndustriesSettings"` 400s). | PATCH `/headless/invoke/platform/referral-management-settings/handle-referral-management-app-toggle` |
+| 5b | `verify-referral-management-app-enabled` | verify | Re-read the settings and require `isReferralManagementAppEnabled:true` before any referral runtime call. | GET `/headless/invoke/platform/referral-management-settings` |
+| 6 | `assign-clinical-service-request-page-layout` | write | **Configure the CSR record page for referral coordinators** ([`hc_admin_referral_management_clinical_service_request_layout`](https://help.salesforce.com/s/articleView?id=ind.hc_admin_referral_management_clinical_service_request_layout.htm&type=5)). Primary artifact is a **Lightning record page (FlexiPage)** for `ClinicalServiceRequest`: in App Builder add custom **tabs** + the four supported components (**Action Launcher** directly on the page, **Assessment**, **Healthcare Appointment Scheduler**, **IndustriesHCCarePlanManager Flexcard**), then **Save and activate** as the org default. Secondary: in Object Manager add four **related lists** to the classic layout. | FlexiPage create POST `/headless/metadata`; industries-component binds via a **whole-page read-modify-write `/headless/metadata` PUT** (fall back to MDAPI zip deploy only if a read-back shows the bind dropped); classic `Layout` via Tooling `Layout` |
+| 7 | `configure-referral-management-path` | write | **Configure the referral Path** (RM guided setup links generic Path docs: [`path_overview`](https://help.salesforce.com/s/articleView?id=sales.path_overview.htm&type=5)). `PathAssistant` metadata type; BOTH the Aura `save-path-assistant` route (500 `appInfo is null`) and `/headless/metadata` (400 `UNSUPPORTED_OPERATION` — `PathAssistant` not on the MetadataCrud allowlist, live-verified) fail, so deploy via the Salesforce-CLI MDAPI fallback (Transport rule 0/5) | `sf project deploy start` (MDAPI `pathAssistants/<Name>.path`); read-back via Tooling `PathAssistant` |
+| 8 | `configure-referral-actionable-lists` | write | **Set up Actionable Segmentation for Referral Management** ([`actionable_segmentation_setup_lists`](https://help.salesforce.com/s/articleView?id=ind.actionable_segmentation_setup_lists.htm&type=5)). **First verify/assign the `ActionableSegmentationForHealthCloud` permission set to the running user** (Data-API `PermissionSetAssignment`; it ships with the Health Cloud Platform license, so read-back first and only assign if missing) — the running identity can't author a definition without it. **Then verify/enable the Data Pipelines org preference** (`appType=DataManager` — see [[SonicGettingStarted]]) — Data Processing Engine will not run without it — **then turn ON the Actionable Segmentation master feature toggle** (`save-pref` `{pref:"listPref", enabled:true}`; requires Data Pipelines + DPE already on) — **then** create an **actionable list definition** (Setup → **Actionable Segmentation Settings** → **New Data Processing Engine Definition**) so coordinators get follow-up lists of referral providers/patients; assign the remaining enabling permission set(s). | Perm-set verify/assign via Data-API `PermissionSetAssignment` (`ActionableSegmentationForHealthCloud`); Data Pipelines pref: PATCH `/headless/invoke/platform/sonic-getting-started/handle-sonic-pref` (proposed); Actionable Segmentation toggle: PATCH `/headless/invoke/platform/actionable-segmentation-settings/save-pref` + read-back GET `/headless/invoke/platform/actionable-segmentation-settings` (proposed); DPE definition authored in Actionable Segmentation Settings / the DPE designer (Setup-UI, GAP for `dispatch`) |
+
+**Act 1 — notes (ordering & findings):**
+
+- **`assign-clinical-service-request-page-layout`** — The CSR coordinator page is a *Lightning record page (FlexiPage)*, NOT a classic page Layout. It is the surface where coordinators schedule appointments, complete assessments, add care plans, enroll patients in care programs, and launch actions. In Lightning App Builder, build (or edit — open a CSR record → **Edit Page**) the `ClinicalServiceRequest` record page, add custom **tabs**, and place the **four supported components**:
+  - **Action Launcher** — launches actions from an **Action Launcher deployment that includes the Clinical Service Request object**. **Add it directly to the page, NOT onto a tab.**
+  - **Assessment** — complete intake/eligibility assessments (e.g., on a custom "Assessments" tab).
+  - **Healthcare Appointment Scheduler** — schedule appointments (e.g., on a custom "Appointments" tab).
+  - **IndustriesHCCarePlanManager Flexcard** — view and add care plans.
+
+  Then **Save and activate** the record page as the CSR org default. **If the org already ships a `ClinicalServiceRequest` Lightning record page from the healthcloud package, configure/activate it rather than authoring a duplicate.**
+  - **Secondary — related lists (classic layout).** In **Object Manager**, add the referral-relevant related lists to the CSR page layout: **Assessments**, **Care Plan Details**, **Care Program Enrollees**, and **Service Appointments**. If a related list isn't available, its backing feature isn't enabled yet — enable the feature in the org first.
+  - **Transport:** create the FlexiPage via `POST /services/data/v67.0/headless/metadata {type:"FlexiPage", fullName:"…", xmlRep:"…"}`, then activate it as the default record page via the CustomObject `actionOverrides` PUT (View/Large/Flexipage). **Component binds for the industries/OmniStudio components (the Flexcard, Healthcare Appointment Scheduler): FIRST attempt a whole-page read-modify-write PUT** — GET the full FlexiPage, add the component nodes to the retrieved record, and PUT the ENTIRE record back to `/headless/metadata`. A live verification showed this binds standard industries components (`healthcloud:patientCard` / `industries_common:timeline`); the earlier "silently dropped" reports were an artifact of *partial-page* PUTs. These specific components were not individually re-verified, so **fall back to an MDAPI zip deploy** (`POST /metadata/deployRequest`) only if a read-back shows the component did not persist. Enable each component's backing feature FIRST (access gate). **CRITICAL: any transport can return success while silently failing to persist the bind — never report this step complete on the write response alone; always re-fetch the FlexiPage and confirm the component node is present.**
+  - The classic Tooling `Layout` POST (`FullName: ClinicalServiceRequest-<Name> Layout`, `layoutSections` `TwoColumnsTopToBottom` → 201; `/headless/metadata` 400s "Invalid fullName" for `Layout`, so Tooling REST is the transport) is the transport for that **secondary related-lists** artifact, not the primary page.
+- **`configure-referral-management-path`** — BOTH available live transports fail, so this step deploys via the **Salesforce-CLI MDAPI fallback** (Transport rule 0/5). (a) The Aura `save-path-assistant` route is a dead end (500 `CONTROLLER_ERROR "appInfo is null"` — the dispatcher can't populate the UI-service application context). (b) The `/headless/metadata` master transport does NOT rescue it: `PathAssistant` is **not on the Core MetadataCrud allowlist** — `POST type:PathAssistant` (and the READ) return `400 UNSUPPORTED_OPERATION "MetadataCrud does not support CREATE/READ on type: PathAssistant"` (live-verified). **The working transport:** build a minimal MDAPI source tree — `pathAssistants/ClinicalServiceRequest.Referral_Management_Path.path` (with `active`, `entityName=ClinicalServiceRequest`, `fieldName=Status`, a `<recordTypeName>` (REQUIRED — see below), and one `pathAssistantStep` per CSR Status value) + a `package.xml` naming the `PathAssistant` member — and `sf project deploy start --metadata-dir <dir>`, then read-back Tooling `SELECT Id,MasterLabel FROM PathAssistant`. **The `.path` source MUST include a `<recordTypeName>` element** — without it the deploy fails `FIELD_INTEGRITY_EXCEPTION "Required field is missing: recordTypeName"`. For a CSR with no custom record type, use the sentinel `<recordTypeName>__MASTER__</recordTypeName>`. `pathAssistantStep`s must reference picklist values that ACTUALLY EXIST on the field — on an org where the referral Status values (steps 18/19) are not yet added, build the path on the shipped FHIR values (e.g. `Draft`/`Active`/`Completed`) or a subset, then re-run to add referral-value steps once 18/19 land. The name "Referral Management Path" is illustrative — pick any clear name, and if a referral Path already exists on `ClinicalServiceRequest.Status`, reuse/update it (re-deploy the same `fullName` — MDAPI deploy upserts) rather than creating a second.
+- **`configure-referral-actionable-lists`** — Actionable Segmentation lets referral coordinators work from **actionable lists**: curated follow-up lists of providers/patients (e.g. referrals awaiting a response, or facilities that haven't confirmed capacity) drawn from a dataset. An **actionable list definition** wraps a **Data Processing Engine** definition, so the flow is **verify/assign the `ActionableSegmentationForHealthCloud` perm set → enable Data Pipelines (+ DPE) → turn ON the Actionable Segmentation master feature toggle → create the definition → assign remaining perms**.
+  - **STEP 1 — verify/assign the `ActionableSegmentationForHealthCloud` permission set to the running user FIRST (precondition).** The running identity cannot author (or launch) an actionable list / DPE definition without the **Actionable Segmentation for Health Cloud** permission set (API name **`ActionableSegmentationForHealthCloud`**). On a Health Cloud org this perm set **ships with the Health Cloud Platform license**, so it is normally already granted by the [[health-cloud-initial-setup]] license gate — but do NOT assume it: **read it back first** (`SELECT Id FROM PermissionSetAssignment WHERE Assignee.Id = '<running user>' AND PermissionSet.Name = 'ActionableSegmentationForHealthCloud'`) and **assign it only if missing** via Data-API `PermissionSetAssignment` create (`DUPLICATE_VALUE` = already assigned = success — same mechanics as step 20). If the perm set itself doesn't exist on the org, that's a license gap → surface it and HALT this step.
+  - **STEP 2 — verify/enable the Data Pipelines org preference (precondition).** Actionable list definitions run on the **Data Processing Engine**, which is gated by the **Data Pipelines** org preference. Enable it with body `{value:true, appType:"DataManager"}` (`appType=DataManager`) — PATCH `/headless/invoke/platform/sonic-getting-started/handle-sonic-pref`. This route is AURA-IS-CANONICAL (no Connect/Tooling/Metadata equivalent — the atomic batch + post-enable hook can't be reconstructed from a generic pref-write) and requires View Setup + the Data Pipelines consumer permission. See the [[SonicGettingStarted]] node for the full pref contract. The corpus exposes no independent GET read-back for this pref (the page's `init` read is an orphan action, not a dispatch route), so confirm enablement by gating on the Actionable Segmentation toggle in STEP 3 succeeding (the DPE definition create in STEP 4 is the final gate) rather than a `verify-*` echo. **If Data Pipelines is off, creating the definition will fail — enable it before proceeding.**
+  - **STEP 3 — turn ON the Actionable Segmentation master feature toggle (the org preference).** Enabling Data Pipelines is necessary but NOT sufficient — Actionable Segmentation has its own master org preference on the **Actionable Segmentation Settings** setup page (`/lightning/setup/ActionableSegmentationSettings/home`) that must be turned ON before the feature (and its list definitions) is usable. Set it via `save-pref` with body `{pref:"listPref", enabled:true}` (`listPref` is the master Actionable Segmentation feature toggle; the sibling `adminConfigAccess` pref grants admin-config edit perm and can be enabled the same way if the admin needs it) — PATCH `/headless/invoke/platform/actionable-segmentation-settings/save-pref`. **ORDERING IS LOAD-BEARING: the toggle raises an org-pref-enablement error unless BOTH Data Pipelines AND the Data Processing Engine are already enabled** — which is exactly why this step follows STEP 2. Read-back via GET `/headless/invoke/platform/actionable-segmentation-settings`, which returns the `{listPref, adminConfigAccess}` pref map — gate on `listPref:true`, not the write echo. **Note:** the same setup page also bundles a CRM Analytics (Wave) app install that backs actionable lists (`install-wave-application`); if list datasets fail to materialize, verify the Wave app installed (`get-actionable-list-folder-status`).
+  - **STEP 4 — create the actionable list definition.** From Setup → **Actionable Segmentation Settings** → **New Data Processing Engine Definition**, name it (alphanumeric, begins with a letter), select the **primary object** (e.g. `ClinicalServiceRequest` / `Account`), **Launch Data Processing Engine Definition**, add the data-source / join / filter nodes (the primary object's data-source node with `Id`+`Name` is auto-created and non-deletable), then **save + activate + run** the DPE to materialize the dataset. List creators then build actionable lists from that dataset, set priority / agent guidance / sort order, and assign each list to an agent or queue.
+  - **Permissions / licenses:** requires **Industry Sales Excellence** + **Query for Datapipelines User** licenses. To create definitions the running user needs the **Actionable Segmentation for Health Cloud** perm set (`ActionableSegmentationForHealthCloud` — verified/assigned in STEP 1) **+ Data Pipelines Base User** perm set **+ View Setup and Configuration**. On Health Cloud the `ActionableSegmentationForHealthCloud` perm set ships with the **Health Cloud Platform license** (so you do NOT assign a separate *generic* Actionable Segmentation perm set — the [[health-cloud-initial-setup]] license gate normally already grants it; STEP 1 still reads it back and assigns only if missing) — but **Data Pipelines Base User** still must be assigned separately.
+  - **Transport:** the permission-set assignments (STEP 1) and the Actionable Segmentation master toggle + read-back (STEP 3, the `save-pref` write + the settings read-back) are live-dispatchable via `dispatch` (Data-API `PermissionSetAssignment` create; `DUPLICATE_VALUE` = already assigned = success — same mechanics as step 20). The **DPE definition authoring is a Setup-UI / DPE-designer task** — the join/filter node graph has no `dispatch` surface; the definition persists as a `BatchCalcJobDefinition`, but the node authoring is designer-only, so surface it as a UI/metadata step (do NOT fabricate a call). Optionally tune the **Actionable List `List Status` picklist** (Object Manager → **Actionable List** → Fields & Relationships → **List Status**) to your workflow's status values (draft / ready / in progress / completed) and set a default.
+
+## Act 2 of 6 — Internal referral creation & routing
+
+> Act 2 opens with **Configure the Create Referral Flow** (step 9 — clone/save/activate the packaged flow), then **Include Referral Action in Provider Search** (steps 10–12 — enable Criteria-Based Search & Filter, then configure Provider Search so the **Create Referral** search action created in step 9 surfaces in provider search results), then covers the other packaged Flows + orchestration activation, the Case BusinessProcess (MDAPI deploy — `/headless/metadata` rejects the type) + Case record type, the expression set + decision table (Business Rules Engine Connect), and the Action Plans permission set. Two things are out-of-band relative to the JSON `dispatch` surface: the two CSR standard-field picklist-value adds (StandardValueSet, rule 3c) and the Case BusinessProcess (rule 3a). `create-case-business-process` is its own step (a prerequisite of the record type).
+
+| # | Step id | Purpose | Controller / API | Route |
+|---|---|---|---|---|
+| 9 | `create-referral-screen-flow` | write (clone packaged) | **Configure the Create Referral Flow** ([`hc_admin_referral_management_flow`](https://help.salesforce.com/s/articleView?id=ind.hc_admin_referral_management_flow.htm&type=5)). Flow Builder automates referral creation — the flow creates the **Clinical Service Request**, CSR details, and document links, and creates/updates the related patient **Account**. From Setup → **Flows** → click **Create Referral**; review its elements, and to customize **Save As New Flow** (label + API name + description), drag/configure elements, then **Save and activate** (Health Cloud allows only ONE active Create Referral version; if not customizing, the packaged flow is already active). Then add it as a **quick action** (action type **Flow**) on the **patient Account** record page and, optionally, the **Clinical Service Request** detail page. Needs **Manage Flow**; prerequisite data = provider records + referral-reason code set bundles. | discover: GET `/services/data/v67.0/query/` (**Data API, NOT `/tooling/query/`** — `FlowDefinitionView` is a Data-API object; `/tooling/query/` 400s `INVALID_TYPE "sObject type 'FlowDefinitionView' is not supported"`) — `FlowDefinitionView` WHERE `ApiName='CreateReferral' AND NamespacePrefix='healthcloud'`) → clone via "Save As New Flow" (UI-only; managed flow is opaque to the Metadata/Tooling API, no headless clone) → activate the UNMANAGED clone via `FlowDefinition` PATCH |
+| 10 | `enable-criteria-based-search-and-filter` | write | Enables Criteria-Based Search & Filter (body `{enable:true}`) | PATCH `/headless/invoke/platform/criteria-based-search-and-filter/set-criteria-based-search-and-filter-pref` (proposed) |
+| 11 | `verify-criteria-based-search-and-filter` | verify | Reads the Criteria-Based Search & Filter preference | GET `/headless/invoke/platform/criteria-based-search-and-filter/get-criteria-based-search-and-filter-pref` (proposed) |
+| 12 | `include-referral-action-in-provider-search` | write (CBS&F designer / Setup-UI) | **Include Referral Action in Provider Search** ([`hc_admin_provider_search_criteria_based`](https://help.salesforce.com/s/articleView?id=ind.hc_admin_provider_search_criteria_based.htm&type=5)). Configure Provider Search with Criteria-Based Search & Filter so coordinators can initiate the Create Referral flow (step 9) directly from provider search results. After CBS&F is on (steps 10/11) **and Data Pipelines is on** (Act 1 step 8): (1) create a **search criteria configuration**; (2) create a **searchable object configuration** — recommended **`CareProviderSearchableField`** (a custom searchable object also needs a custom DPE definition); (3) **set up search actions**, choosing the prebuilt **Create Referral** action ("creates referral requests using data from selected search results"); (4) add the **Criteria-Based Search and Filter** component to the coordinators' Lightning page (e.g. account record page + care-coordinator app home page), and — for the portal (Act 6) — to the Experience Cloud site. **Perms:** Criteria-Based Search and Filter perm set **AND** Health Cloud Provider Relationship Management **or** Health Cloud Provider Search perm set (card view also needs OmniStudio Admin). | CBS&F designer / Setup-UI (search criteria + searchable object + search-action authoring; `discover` for a backing surface before declaring GAP); enablement via steps 10/11; component placement via App Builder / Experience Builder |
+| 13 | `create-case-business-process` | write | Case `BusinessProcess` — prerequisite of the Case RT. `/headless/metadata` rejects it (`UNSUPPORTED_OPERATION` for both `type:BusinessProcess` and the parent-`CustomObject` embed, live-verified), so deploy via the Salesforce-CLI MDAPI fallback (Transport rule 3a) | `sf project deploy start` (MDAPI `objects/Case.object` with a `<businessProcesses>` element); read-back via Tooling `BusinessProcess` |
+| 14 | `create-case-record-type` | write | Tooling `RecordType` — `{FullName:'Case.<Name>', Metadata:{label, active, businessProcess}}` (Case RT REQUIRES `businessProcess`; `deletable:false` → deactivate only; Transport rule 3b) | POST `/services/data/v67.0/tooling/sobjects/RecordType` |
+| 15 | `create-case-from-csr-flow` | write (clone packaged) | **Configure Case Creation from a Clinical Service Request** ([`hc_admin_referral_management_case_creation_flow`](https://help.salesforce.com/s/articleView?id=ind.hc_admin_referral_management_case_creation_flow.htm&type=5)). **clone → save → activate:** discover the PACKAGED `healthcloud__CreateCaseUpdateCSR` flow ("Create Case and Update Clinical Service Request"), then CLONE it ("Save As New Flow"), and save + activate the clone; add "Referral" to CSR Source Channel + Case Origin picklists. Do NOT hand-build a new flow from scratch (if not customizing, the packaged flow is already active) | discover: GET `/services/data/v67.0/query/` (**Data API, NOT `/tooling/query/`** — see step 9; `FlowDefinitionView` is a Data-API object) — `FlowDefinitionView` WHERE `ApiName='CreateCaseUpdateCSR' AND NamespacePrefix='healthcloud'`) → clone ("Save As New Flow", UI-only) → activate the unmanaged clone via `FlowDefinition` PATCH |
+| 16 | `configure-patient-referral-expression-set` | write | **Configure the Business Rules Engine flow to update CSR status** ([`hc_admin_referral_management_configure_use_bre_flow`](https://help.salesforce.com/s/articleView?id=ind.hc_admin_referral_management_configure_use_bre_flow.htm&type=5)). Create the expression set via the Business Rules Engine Connect API — `usageType` MUST be `Bre` (from `/connect/ruleengine/usage-types`; Transport rule 4a) | POST `/services/data/v67.0/connect/business-rules/expression-set` |
+| 17 | `load-patient-referral-decision-table` | write | (same doc as step 16: [`hc_admin_referral_management_configure_use_bre_flow`](https://help.salesforce.com/s/articleView?id=ind.hc_admin_referral_management_configure_use_bre_flow.htm&type=5)) Create the decision table via the Business Rules Engine Connect API — needs `dataSpaceName` + `parameters[]` + **`sourceType: "SingleSobject"`** (case-sensitive enum `SingleSobject` / `MultipleSobjects` / `CsvUpload`; omitting it 400s "Specify a valid value for sourceType parameter", and guesses like `SObject` / `Entity` / `StandardObject` fail to parse) + `sourceObject` + `setupName` (Transport rule 4a) | POST `/services/data/v67.0/connect/business-rules/decision-table/definitions` |
+| 18 | `add-csr-status-picklist-values` | write | required content — the exact CSR **Status** values below FEED the decision-table CSV (step 17). Transport is a `StandardValueSet` MDAPI deploy of **`CServiceRequestStatus`** (multipart, replaces full list — retrieve first); the JSON-only `dispatch` surface can't send it (rule 3c), so drive via the Salesforce CLI (execution-policy notes) or the Setup UI | `StandardValueSet` MDAPI deploy (Salesforce CLI) / Setup UI |
+| 19 | `add-csr-status-reason-picklist-values` | write | CSR **StatusReason** is a **multipicklist** that ships with **zero** values; the exact values below also feed the decision table. Transport = `StandardValueSet` MDAPI deploy of **`CServiceRequestStatReason`**, same mechanics as 18 | `StandardValueSet` MDAPI deploy (Salesforce CLI) / Setup UI |
+| 20 | `assign-action-plans-permission-set` | write | Data API: create `PermissionSetAssignment` ("Action Plans" perm set → admin) | POST `/services/data/v67.0/sobjects/PermissionSetAssignment` |
+| 21 | `activate-referral-flow-orchestration` | write (clone/activate packaged) | **Set up the processing-stage Flow Orchestrator** ([`hc_admin_referral_management_configure_csr_flow_orchestration`](https://help.salesforce.com/s/articleView?id=ind.hc_admin_referral_management_configure_csr_flow_orchestration.htm&type=5)). **clone → save → activate:** to customize routing, CLONE the PACKAGED `healthcloud__AutoCsrReview` orchestrator ("Referral Management: Automate Clinical Service Request Review"; ships INACTIVE) via "Save As New Flow", then save + activate the clone; if unchanged, activate the packaged version in place via Flow Builder UI (the managed FlowDefinition is not exposed to Tooling, so in-place activation is UI-only; the PATCH transport targets an unmanaged clone). Do NOT invent a `referral-routing` orchestration from scratch | discover `FlowDefinitionView` → clone ("Save As New Flow") → PATCH `/services/data/v67.0/tooling/sobjects/FlowDefinition/{id}` (`{Metadata:{activeVersionNumber:N}}`) |
+
+**Act 2 — notes (ordering & findings):**
+
+- **`enable-criteria-based-search-and-filter` (10) + `verify-criteria-based-search-and-filter` (11)** — the enablement toggle for step 12 ("Include Referral Action in Provider Search"). PATCH body `{enable:true}` → 200 `{status:SUCCESS, isPrefEnabled:true}`; verify via step 11. This powers Provider Search's Criteria-Based Search & Filter, which hosts the **Create Referral** search action. Reversible. Per the doc, Provider Search also needs **Data Pipelines** ON — that toggle is Act 1 step 8 (`configure-referral-actionable-lists`, the Data Pipelines preference route); confirm it's on before configuring step 12.
+- **`include-referral-action-in-provider-search` (12)** — this is the step **immediately after Configure the Create Referral Flow**, and it depends on that flow existing (step 9) because the **Create Referral** search action launches it. Follow [`hc_admin_provider_search_criteria_based`](https://help.salesforce.com/s/articleView?id=ind.hc_admin_provider_search_criteria_based.htm&type=5) precisely:
+  1. **Enable Criteria-Based Search and Filter** — done by steps 10/11; the doc pairs it with **Data Pipelines** (Act 1 step 8). Don't re-toggle if already on.
+  2. **Create a search criteria configuration** (Configure the Search Criteria for a Searchable Object) — defines the custom search criteria, result filters, and result display.
+  3. **(Card view)** — if results display as cards, the recommended container is the **`HealthCloudPSProviderCardContainer`** OmniStudio FlexCard; selecting/configuring a FlexCard needs the **OmniStudio Admin** perm set. (The shipped FlexCard doesn't localize age-group/operating-hours values — clone a custom FlexCard to work around that.)
+  4. **Choose search-result actions** — the prebuilt actions are **Copy Records**, **Create Report**, and **Create Referral**. Select **Create Referral** ("creates referral requests using data from selected search results") — this is the action that puts referral creation into Provider Search. **Note:** on Experience Cloud sites only **Copy Records** is available to authenticated/guest users; **Create Report and Create Referral are NOT available on Experience Cloud sites**, so the portal (Act 6) guest form uses the Create Referral OmniScript (step 36), not this search action.
+  5. **Create a searchable object configuration** (Configure a Searchable Object) — recommended searchable object is **`CareProviderSearchableField`**; a *custom* searchable object additionally requires a custom **Data Processing Engine** definition.
+  6. **Set up search actions** (Set Up Search Actions in Criteria-Based Search and Filter) — wire the Create Referral action selected in (4) to the search configuration.
+  7. **Add the Criteria-Based Search and Filter component to a page** — for internal users, place it on a standard/custom Lightning page (e.g. the **account record page** and the **home page of the apps care coordinators use**). For guest/authenticated portal users, add it to an **Experience Cloud site** (Act 6).
+  - **Perms:** the running user needs the **Criteria-Based Search and Filter** perm set **AND** the **Health Cloud Provider Relationship Management** *or* **Health Cloud Provider Search** perm set. Available only in Lightning Experience on Enterprise/Unlimited with Health Cloud (or Life Sciences Cloud).
+  - **Transport:** the enablement is live-dispatchable (steps 10/11). The search criteria configuration, searchable object configuration, and search-action authoring are **CBS&F designer / Setup-UI** tasks; before declaring a GAP, `discover`/`discover` for a backing metadata or Connect surface (Transport rule 1). Component placement is App Builder / Experience Builder. Do NOT fabricate a call for the designer authoring — surface it as a UI step.
+- **`create-case-business-process` + `create-case-record-type`** — The Case `BusinessProcess` is NOT reachable via ANY JSON REST transport. (a) The Tooling-REST `BusinessProcess` sObject rejects it (the complexvalue deserializer rejects scalar `Metadata` sub-fields). (b) The `/headless/metadata` master transport rejects it too — both a top-level `type:BusinessProcess` and embedding it as a `businessProcesses` child of a parent `type:CustomObject` (`fullName:"Case"`) return `400 UNSUPPORTED_OPERATION "MetadataCrud does not support CREATE on type: BusinessProcess"` (Core resolves the child to its own type; live-verified). **The working transport is a Salesforce-CLI MDAPI deploy** (Transport rule 3a): build `objects/Case.object` (or a `businessProcesses`-scoped `CustomObject` component) carrying `<businessProcesses><fullName>Referral_Business_Process</fullName><isActive>true</isActive>…</businessProcesses>` plus a `package.xml`, `sf project deploy start --metadata-dir <dir>`, then read-back via Tooling `BusinessProcess`. Then the Case RT via Tooling `RecordType` `{FullName:'Case.Referral_Case', Metadata:{label, active:true, businessProcess:'Referral_Business_Process'}}` → 201 (a Case RT REQUIRES `businessProcess`, unlike an Account RT — rule 3b). RecordTypes are `deletable:false` → deactivate, never DELETE. The developer names (`Referral_Business_Process`, `Referral_Case`) are illustrative — any clear names work, and reuse an existing referral Case RT if the org already has one. Note: the corpus `CaseProcess` SOR names a server-side sObject that does not exist (404/`INVALID_TYPE`); the correct type is the generic `BusinessProcess`, deployed via MDAPI as above.
+- **`create-referral-screen-flow` (9), `create-case-from-csr-flow` (15), `activate-referral-flow-orchestration` (21)** — **CLONE THE PACKAGED FLOW, THEN SAVE + ACTIVATE; DO NOT HAND-BUILD A NEW ONE FROM SCRATCH.** The procedure is: open the packaged flow → click **"Save As New Flow"** (clone with a new label + API name; the clone inherits all packaged elements) → configure as needed → **Save and activate** the clone → add it as a quick action. Cloning is required because **managed-package flows can't be edited in place**. Only ONE active version of the Create Referral flow is allowed, so activate the single configured clone. **If no customization is needed, the packaged flow ships already active and can be used as-is (skip the clone).** All three flows ship in the `healthcloud` managed package on a Health Cloud-licensed org. Do NOT hand-build namespace-less copies from scratch — those are non-canonical duplicates that shadow the shipped assets.
+  - **Step 9 → packaged `healthcloud__CreateReferral`** (ProcessType Flow, `IsActive=true`) — **Configure the Create Referral Flow** ([`hc_admin_referral_management_flow`](https://help.salesforce.com/s/articleView?id=ind.hc_admin_referral_management_flow.htm&type=5)). This is the **first step of Act 2**. The flow creates the Clinical Service Request, CSR details, and document links, and creates or updates the related patient Account; when launched from a page that carries patient or provider information it prepopulates with that information. **Prerequisite user permission: Manage Flow** (to open/edit/create a flow in Flow Builder). **Prerequisite data:** provider records and code set bundles for referral-reason codes (optionally the patient's member plans, conditions, and diagnoses, if that data already exists for the patient). **Follow the doc's procedure exactly:** (1) From Setup, enter *Flows* in the Quick Find box, select **Flows**, then click **Create Referral** — the basic create-referral flow's elements appear in the builder; (2) review the flow's elements and attributes — update them only if you want to customize further (if so, do steps 3–7; otherwise skip to step 8); (3) click **Save As New Flow**; (4) enter a label, API name, and description for the clone, then click **Save**; (5) drag any additional elements you want onto the canvas; (6) select each flow element and configure its screen properties to suit your business requirements; (7) **Save and activate** the flow — Health Cloud supports only **ONE active version** of the Create Referral flow; (8) from the **patient Account** record page, add a **quick action** that triggers the Create Referral flow, and optionally add the same quick action to the **Clinical Service Request** detail page. Create the quick action as a new action with **action type Flow** from the object's **Buttons, Links, and Actions** page, then add it to the **Salesforce Mobile and Lightning Experience Actions** section of that object's page layout; if you use **Action Launcher**, include the quick action in an **Action Launcher Deployment** record instead. (If you use the **Crisis Support Center Management** app, you can also add the Create Referral action to the **Bed Search** component.) *Discover (headless equivalent of step 1)*: `SELECT ApiName, Label, IsActive FROM FlowDefinitionView WHERE ApiName = 'CreateReferral' AND NamespacePrefix = 'healthcloud'` **via the Data API `GET /services/data/v67.0/query/` — NOT `/tooling/query/`** (`FlowDefinitionView` is a Data-API object; the Tooling query endpoint 400s `INVALID_TYPE "sObject type 'FlowDefinitionView' is not supported"`). `FlowDefinitionView.ApiName` is UN-namespaced with a separate `NamespacePrefix` column, so `'healthcloud__CreateReferral'` returns 0 rows; the column is `ApiName` NOT `DeveloperName`; no OR/disjunctions. *Clone (steps 3–4)*: "Save As New Flow" is a Flow Builder UI action — NO headless equivalent (the managed flow is opaque to the subscriber Metadata/Tooling API). *Activate the UNMANAGED clone (step 7)*: `FlowDefinition` PATCH `{Metadata:{activeVersionNumber:N}}` → 204.
+  - **Step 15 → packaged `healthcloud__CreateCaseUpdateCSR`** ("Create Case and Update Clinical Service Request", `AutoLaunchedFlow`, `IsActive=true`). Clone via "Save As New Flow" to customize, then save + activate. ALSO add the value **"Referral"** to the CSR **Source Channel** picklist and the **Case Origin** picklist so the flow's branching resolves.
+  - **Step 21 → packaged `healthcloud__AutoCsrReview`** ("Referral Management: Automate Clinical Service Request Review", Orchestrator). This ships **INACTIVE**. To customize the routing, clone via "Save As New Flow" then save + activate the clone (`FlowDefinition` PATCH `{Metadata:{activeVersionNumber:N}}`); if the packaged orchestrator is fine unchanged, activate it in place via Flow Builder UI (managed FlowDefinition is not exposed to Tooling; the PATCH transport works only on an unmanaged clone). Do NOT invent a `referral-routing` orchestration from scratch.
+  - **If any packaged flow is missing** (zero `FlowDefinitionView` rows), that is a license/package gap — HALT and surface it; do NOT author a substitute.
+- **`configure-patient-referral-expression-set` + `load-patient-referral-decision-table`** — the "update Clinical Service Request status" decision table has FOUR ordered columns — **THREE Inputs (`WorkType`, `CSRStatusReason`, `InsuranceStatus`; each with an ordered `sequence` 1..3)** mapping to **ONE Output (`CSRStatus`; OMITS `sequence`)**. CSR Status is the OUTPUT the table sets, NOT an input. Key the `CSRStatusReason` input rows and the `CSRStatus` output rows on the underscore API `fullName`s from steps 18/19 (not the display labels). **Predictive/urgency scoring is NOT this decision table** — it is a separate Data Cloud **Scoring Framework template** ("Referral Management Scoring") that writes back to CSR `Referral Score` (see step 25); do not conflate the two.
+  - **Transport:** `usageType` MUST be a value from `GET /connect/ruleengine/usage-types` — **`Bre`** (label "Default") is the general-purpose type; free-text guesses ("Decisioning") 400 "Value does not match expected type". Decision table needs BOTH `dataSpaceName` AND `parameters[]` (absent `parameters` → 500 NPE); `parameters[].dataType` ∈ `{Boolean,Currency,Date,DateTime,Number,Percent,String}` (NOT "Text"); `usage` ∈ `{Input,Output,RowCriteria}`; **Output fields must NOT carry a `sequence`**; requires the Decision Table permission; `type: LowVolume`, `sourceType: SingleSobject`, `sourceObject: ClinicalServiceRequest`, `dataSpaceName: 'default'`. Rows/data load follow via `postDecisionTableFile`/`postDecisionTableRows`; teardown via `deleteExpressionSet` / decision-table DELETE. (Transport rule 4a.)
+- **`add-csr-status-picklist-values` + `add-csr-status-reason-picklist-values`** — required content, not merely gaps. The values below **FEED the decision-table rows** (step 17 — the `CSRStatusReason` values key the Input rows and the `CSRStatus` values fill the Output column). A setup that skips them leaves the routing decision table unmatchable.
+  - **CSR `Status` (`type=picklist`) — target values:** `New`, `Processing`, `Waiting for Response`, `Manual Review Needed`, `Rejected`, `Accepted`, `Scheduled`, `Completed`, `Closed-No Appointment`. The field ships with 7 FHIR values (`Draft`, `Active`, `On-Hold`, `Revoked`, `Completed`, `Entered-in-Error`, `Unknown`); add the referral values on top. **Stored API `fullName`s use underscores:** `New`, `Processing`, `Waiting_for_Response`, `Manual_Review_Needed`, `Rejected`, `Accepted`, `Scheduled`, `Closed_No_Appointment` (labels have spaces/hyphens).
+  - **CSR `StatusReason` (`type=multipicklist`, ships with ZERO values) — target values:** `Missing Information`, `Manual Required`, `Complex Work Type`, `Inactive Insurance`, `No Rule Match`, `Ready for Prior Authorization` — API `fullName`s `Missing_Information`, `Manual_Required`, `Complex_Work_Type`, `Inactive_Insurance`, `No_Rule_Match`, `Ready_for_Prior_Authorization`.
+  - **Transport:** a **`StandardValueSet` MDAPI deploy** — see Transport rule 3c for the full mechanics (SVS DeveloperNames `CServiceRequestStatus` / `CServiceRequestStatReason`; multipart-only so `dispatch` can't send it; retrieve-first-then-deploy-union; underscore `fullName`s; the silent-no-op traps). **ALWAYS verify a picklist write with a `describe` read-back.** `discover-clinical-service-request-picklists` (step 5) gives the baseline.
+- **`assign-action-plans-permission-set`** — assigning the "Action Plans" permission set is only a PREREQUISITE. The full deliverable is **configuring + publishing the Referral Management Action Plan Template** (~18 tasks, including the **EBV + Prior Auth tasks** that invoke the account-team callback Apex — see `create-ebv-prior-auth-apex-classes`). Do NOT treat "perm set assigned" as "Action Plan configured." Transport for the prerequisite: Data API `PermissionSetAssignment` create (the "Action Plans" permission set → running admin). `DUPLICATE_VALUE` on the POST = already assigned = success. Reversible via DELETE.
+
+## Act 3 of 6 — Eligibility / Prior Auth / Predictive Scoring
+
+> Act 3 EBV setup is a **Care Benefit Verification Settings** record (Apex handler + endpoint URI + Named Credential) with the **account-team-supplied** `EBVCallbackService` + `PACallbackHandler` Apex deployed as **guest-accessible Apex REST callback receivers** at `/services/apexrest/ebv/callback`; EBV and Prior Auth are triggered as **Action Plan tasks** (Infinitus payer API). It is NOT an Experience site. The MuleSoft FHIR NamedCredential (step 24) must be named `GFCCredentials`. Only the Data Cloud scoring data kit is a genuine external GAP.
+
+| # | Step id | Purpose | Controller / API | Route |
+|---|---|---|---|---|
+| 22 | `create-ebv-prior-auth-apex-classes` | write | **Set up Eligibility and Benefits Verification & Prior Authorization** ([`hc_admin_referral_management_ebv_prior_auth_flow`](https://help.salesforce.com/s/articleView?id=ind.hc_admin_referral_management_ebv_prior_auth_flow.htm&type=5)). deploy the **account-team-supplied** `EBVCallbackService` + `PACallbackHandler` Apex as **guest-accessible Apex REST callback receivers** (`/services/apexrest/ebv/callback`) — do NOT author a fabricated `ReferralEbvPriorAuthService`. Transport: Tooling `ApexClass` POST for the supplied source | POST `/services/data/v67.0/tooling/sobjects/ApexClass` |
+| 23 | `provision-ebv-callback-experience-site` | write | (same doc as step 22: [`hc_admin_referral_management_ebv_prior_auth_flow`](https://help.salesforce.com/s/articleView?id=ind.hc_admin_referral_management_ebv_prior_auth_flow.htm&type=5)) EBV has **no Experience site**. The EBV artifact is a **Care Benefit Verification Settings** record (Apex handler + endpoint URI + Named Credential) + guest-accessible Apex REST — configure Care Benefit Verification Settings, NOT `POST /connect/communities` | Care Benefit Verification Settings (see note) |
+| 24 | `create-mulesoft-fhir-named-credential` | write | name MUST be exactly **`GFCCredentials`** (load-bearing — the packaged Generic FHIR Client "MuleSoft Direct" app binds this literal name), **legacy named credential, PASSWORD auth** (not Anonymous). `/headless/metadata` rejects `NamedCredential` (`UNSUPPORTED_OPERATION`, live-verified), so deploy via the Salesforce-CLI MDAPI fallback (Transport rule 0); placeholder endpoint, real host+password secrets external | `sf project deploy start` (MDAPI `namedCredentials/GFCCredentials.namedCredential`) — proven live; read-back via Tooling `NamedCredential` |
+| 25 | `install-datacloud-referral-scoring-data-kit` | write | **Set up predictive scoring for referrals** ([`hc_admin_referral_management_predictive_scoring_setup`](https://help.salesforce.com/s/articleView?id=ind.hc_admin_referral_management_predictive_scoring_setup.htm&type=5)). *(GAP — external Data Cloud data kit; no cold-install route)* | — |
+
+**Act 3 — notes (ordering & findings):**
+
+- **`create-ebv-prior-auth-apex-classes`** — the EBV/Prior-Auth Apex is `EBVCallbackService` + `PACallbackHandler`, which are **account-team-supplied** (Infinitus integration), NOT hand-authored. They are deployed as **guest-accessible Apex REST callback receivers** at `/services/apexrest/ebv/callback` (so the payer's async EBV/PA response can post back), and EBV + Prior Auth are invoked as **Action Plan tasks** (see step 20's Action Plan Template). They ship from the account team, not the healthcloud package. Obtain the two classes, deploy via Tooling `ApexClass` POST `{Body:"<supplied source>"}` (→ 201; class *updates* need a `MetadataContainer` + `ContainerAsyncRequest`), then expose them as a guest Apex REST resource and grant the guest user access. If the supplied classes are unavailable → HALT and surface the dependency; do NOT author a substitute.
+- **`provision-ebv-callback-experience-site`** — EBV has NO Experience Cloud site. The EBV callback is a **guest-accessible Apex REST endpoint** (`/services/apexrest/ebv/callback`, backed by `EBVCallbackService` from step 22), not a community/site. The EBV configuration is a **Care Benefit Verification Settings** record that ties together the Apex callback handler, the callback **endpoint URI**, and the **Named Credential** (step 24, `GFCCredentials`). **Configure the Care Benefit Verification Settings record**; do NOT `POST /connect/communities` here (that cold-create transport is valid, but it's used for the guest portal in step 31).
+- **`create-mulesoft-fhir-named-credential`** — the Named Credential MUST be named exactly `GFCCredentials` and use PASSWORD authentication. The name is **load-bearing** — the packaged Generic FHIR Client "MuleSoft Direct" app looks up this exact developer name; a differently-named credential is invisible to it. It is a **legacy named credential** with username/password auth to the MuleSoft FHIR endpoint, NOT Anonymous/NoAuthentication. Transport: `/headless/metadata` rejects `NamedCredential` — `POST type:NamedCredential` returns `400 UNSUPPORTED_OPERATION "MetadataCrud does not support CREATE on type: NamedCredential"` (live-verified). **The working transport is a Salesforce-CLI MDAPI deploy** (Transport rule 0), proven live: build `namedCredentials/GFCCredentials.namedCredential` (`<protocol>Password</protocol>`, endpoint, principal) + `package.xml`, `sf project deploy start --metadata-dir <dir>` (verified live — the deploy creates the credential where the `/headless/metadata` POST cannot), then read-back via Tooling `NamedCredential`. A **placeholder endpoint** is OK — the real MuleSoft FHIR host + password secrets remain an external step, but the platform credential artifact is created.
+- **`install-datacloud-referral-scoring-data-kit`** — GAP (external_dependency): installing a Data Cloud data kit requires the Data Cloud provisioning surface + a packaged kit artifact; not a Setup metadata/Connect write reachable via `dispatch`. No cold-install route.
+
+## Act 4 of 6 — Outreach + Appointment Sync
+
+> Act 4 covers outbound-engagement component placement (step 26) and appointment sync. **Step 26 places the Outbound Engagement component (`runtime_ime_distribution:distributionComponentWrapper`) on the Home page and sets its `outboundEngagementTemplates` property — via MDAPI FlexiPage deploy, not `dispatch`.** Referral outreach is NOT Marketing Cloud (SFMC): the **Referral Outreach Patient & Provider flows** are CORE App-template flows deployed UNMANAGED once a campaign is created from the Referral Management template — in-platform, deployable via the Metadata API (Salesforce CLI), and activatable via the step-27 activation contract (the email-only flow activates headlessly; the SMS-bearing flow additionally needs an out-of-band SMS sender code).
+
+| # | Step id | Purpose | Controller / API | Route |
+|---|---|---|---|---|
+| 26 | `place-outbound-engagement-home-component` | write | **Configure patient & provider outreach** ([`hc_admin_referral_management_configure_patient_provider_outreach_template`](https://help.salesforce.com/s/articleView?id=ind.hc_admin_referral_management_configure_patient_provider_outreach_template.htm&type=5)). Place the **Outbound Engagement** component (`runtime_ime_distribution:distributionComponentWrapper`) on the target Home page and set its **`outboundEngagementTemplates`** property to the referral templates. Transport: FIRST attempt a **whole-page read-modify-write `/headless/metadata` PUT** (GET the full Home FlexiPage, add the `runtime_ime_distribution:distributionComponentWrapper` region + templates, PUT the whole record back). A live check bound this class of standard industries component via whole-page PUT (patientCard/timeline); this specific component was not individually re-verified, so **fall back to an MDAPI FlexiPage deploy** (Salesforce CLI — see the execution-policy notes) only if a read-back shows the component dropped | MDAPI `FlexiPage` deploy — `componentName: runtime_ime_distribution:distributionComponentWrapper`, region `top` |
+| 27 | `configure-marketing-cloud-outreach` | write | (same doc as step 26: [`hc_admin_referral_management_configure_patient_provider_outreach_template`](https://help.salesforce.com/s/articleView?id=ind.hc_admin_referral_management_configure_patient_provider_outreach_template.htm&type=5)) The **Referral Outreach Patient & Provider flows** are CORE App-template flows deployed UNMANAGED by the ReferralManagement App template once a campaign is created from the Referral Management template — NOT managed packaged flows (no clone needed) and NOT SFMC. Both ship `InvalidDraft`. Activation contract (retrieve/deploy as MDAPI `.flow`, atomic per deploy → one flow per package): (1) bind Communication Subscription + channel-type Id on each `sendEmailMessage` AND `sendSmsMessage` action, (2) set a valid email `senderId` (the authed User Id works, send-as-user), (3) publish campaign content via `POST /connect/cms/contents/publish`, (4) map required content-schema fields (`patientName`/`providerName`/`visitType`), (5) SMS-bearing flow additionally needs an out-of-band SMS sender code (registered `Text` MessagingChannel), (6) set `status` Active / PATCH `FlowDefinition`. Steps 1–3,6 headless; 4 metadata; 5 out-of-band | retrieve → bind subscription + senderId + publish + map schema → activate `ReferralOutreach{Patient,Provider}` (`FlowDefinition`) |
+| 28 | `enable-appointment-sync` | write | Toggles patient appointment-scheduling settings (body `{value:true}`) | PATCH `/headless/invoke/platform/patient-appointment-scheduling-settings/handle-patient-appointment-scheduling-toggle` (proposed) |
+| 29 | `verify-appointment-sync` | verify | Reads the patient appointment-scheduling preference | GET `/headless/invoke/platform/patient-appointment-scheduling-settings` (proposed) |
+
+**Act 4 — notes (ordering & findings):**
+
+- **`place-outbound-engagement-home-component`** (the first step of Act 4) — the "Outbound Engagement" component an admin drags in Lightning App Builder is **`runtime_ime_distribution:distributionComponentWrapper`**. **Do NOT confuse it with `runtime_ime_distribution:outboundHomePage`** (masterLabel "Outbound Engagement Home") — that is a *different* component with no design properties; the wrapper is the one that carries the template property.
+  - **Template selection = the `outboundEngagementTemplates` design property**, a **multi-value list of `OutboundEngagementTmplView` DeveloperNames** (NOT 18-char record Ids, NOT external Ids). For Referral Management the two values are **`AppointmentManagement_HomePage`** and **`ReferralManagement_HomePage`**.
+  - **Transport: FIRST attempt a whole-page read-modify-write `/headless/metadata` PUT** — GET the full `FlexiPage:<name>`, add the component region + templates to the retrieved record, and PUT the ENTIRE record back via project-codey `execute_api` (JSON body: `type:"FlexiPage", fullName, xmlRep`). A live verification bound standard industries components this way (Patient Card / Timeline); the earlier "silently drops" reports were an artifact of *partial-page* PUTs. This specific component was not individually re-verified, so **fall back to an MDAPI `FlexiPage` deploy via the Salesforce CLI** (concrete command in the execution-policy notes) only if the read-back shows the component did not persist. Always **gate on a read-back** (retrieve `FlexiPage:<name>` again → confirm `<componentName>` + both `<valueListItems>` persisted) — any transport can report success while silently failing to persist, so the read-back is the only proof.
+  - **HomePage FlexiPage shape:** `template` = `home:desktopTemplate`, regions `top`/`bottomLeft`/`bottomRight`/`sidebar`; place the wrapper in region `top`. Example item instance:
+    ```xml
+    <componentInstance>
+      <componentInstanceProperties>
+        <name>outboundEngagementTemplates</name>
+        <valueList>
+          <valueListItems><value>AppointmentManagement_HomePage</value></valueListItems>
+          <valueListItems><value>ReferralManagement_HomePage</value></valueListItems>
+        </valueList>
+      </componentInstanceProperties>
+      <componentName>runtime_ime_distribution:distributionComponentWrapper</componentName>
+      <identifier>runtime_ime_distribution_distributionComponentWrapper</identifier>
+    </componentInstance>
+    ```
+  - **Target page:** any Home page opened in App Builder (e.g. `Marketing_CRM_Classic_Home`; the standard Sales-app home is `Home_Page_Default`). **Two things MDAPI can't do:** (1) assign the FlexiPage as a *standard* app's Home (e.g. `standard__Marketing` exposes only `<defaultLandingTab>`, no FlexiPage element — UI-only "Activation → Assign to Apps"); (2) the component-access gate — placement requires **Distribution component access** (granted when Industries outbound engagement is enabled for the org); enable the backing Outbound Engagement feature first.
+  - **Prereqs (upstream, not this step):** Marketing Cloud Engagement enablement lives on the UMA setup page (`UmaMarketingCloudEngagement`); the template-driven engagement *creation* runtime is the `postOutboundEngagement` Connect API (`otbdEngmtTmplViewExternalId`), a separate, `dispatch`-callable action — NOT component placement.
+- **`configure-marketing-cloud-outreach`** — referral outreach is NOT Marketing Cloud (SFMC). The two outreach flows — **Referral Outreach Patient** and **Referral Outreach Provider** — are **CORE App-template flows** (`ReferralOutreachPatient` / `ReferralOutreachProvider`, shipped in the platform's Referral Management app template), deployed **UNMANAGED** (subscriber-owned) by a `FlowDefinitionUpsert` node in the "Referral Management Emails and SMS" App template (name `ReferralManagement`), which also `ManagedContentUpsert`-creates their email/SMS content. They **materialize once an admin creates a campaign from the Referral Management template**. Both are `AutoLaunchedFlow`, record-triggered (`IndivRelatedRecord`) on `ClinicalServiceRequest`, and drive email/SMS via IME distribution `sendEmailMessage`/`sendSmsMessage` actions. Because they are unmanaged, they surface in Tooling and ARE retrievable/deployable via the `sf` CLI — **no clone needed** (unlike the managed clone-first path for CreateReferral/CreateCaseUpdateCSR).
+  - **PREREQ entitlements:** IME Content Distribution / Industries Outbound Engagement + Communication Subscription (consent) framework + at least one Data Cloud MarketSegment — the same gate as `place-outbound-engagement-home-component`.
+  - **TRANSPORT:** retrieve/edit/deploy the flows as **MDAPI `.flow` files** (retrieve the flows via the Salesforce CLI into `unpackaged/flows/<ApiName>.flow`; edit XML; deploy the metadata directory back — concrete commands in the execution-policy notes). **NOT** `.flow-meta.xml` (that is the source-format filename; MDAPI uses `.flow`). An MDAPI deploy is **atomic per deploy** — if one flow fails validation the whole deploy rolls back, so **deploy each flow in its OWN package** to activate the good one independently of a blocked sibling. **Label/API-name are cross-wired in the shipped template**: file `ReferralOutreachPatient_<hash>.flow` carries `<masterLabel>Referral Outreach Provider</masterLabel>` and vice-versa — match on `masterLabel`, not the filename.
+  - **ACTIVATION CONTRACT** — both flows ship `<status>InvalidDraft</status>`:
+    1. **Bind Communication Subscription** — each `sendEmailMessage` AND `sendSmsMessage` action carries two empty inputs, `communicationSubscriptionId` + `commSubscriptionChannelTypeId`; inject a `CommSubscription` Id + a `CommSubscriptionChannelType` Id as `<value><stringValue>ID</stringValue></value>`. Discover with `SELECT Id, Name FROM CommSubscription` / `SELECT Id, Name FROM CommSubscriptionChannelType`. This binding clears the shipped InvalidDraft cause.
+    2. **Set the email `senderId` (From address)** — each `sendEmailMessage` action needs a `senderId` input pointing at a valid, **active** email From address, else the deploy fails with `Select a valid From address.` **The authed running-User Id works directly** (`senderId = <UserId>`, send-as-user). A `SenderEmailAddress` record is the alternative, but it requires an **active** `EmailDomainKey` (DKIM CNAME published in DNS) — an unverified domain stays `Status=Inactive` and is rejected, and `EmailDomainKey.IsActive` is read-only. So use the User Id unless the org has a DKIM-verified sending domain.
+    3. **Publish content** — the send actions reference ManagedContent (`contentId` MC-keys); Draft content fails the deploy with `We can't send unpublished content.` Use `POST /connect/cms/contents/publish` with `{contentIds:[...], contentSpaceOrFolderId:"<contentSpaceId>"}`. Publish **every** `contentId` referenced by **both** flows (the two reference different content sets).
+    4. **Map content-schema fields** — the published content schema requires merge fields `patientName`, `providerName`, and `visitType`; an unmapped one fails the deploy with `Enter a value for the Content Schema.<field> input parameter.` The template ships only a single `contentSchemaParameter` (→ `GetPatientName.Name`); add a `<transformValueActions>` `Map` block for each required field on **every** `contentSchemaParameter` block whose published schema demands it (e.g. `providerName` → `elementReference` `GetRequesterName.Name`).
+    5. **SMS sender code (OUT-OF-BAND — blocks the SMS-bearing flow)** — a flow containing `sendSmsMessage` actions additionally fails activation with `Select a valid sender code.` The `sendSmsMessage` action (E360 `SendSmsAction`) takes a `senderId` input; at activation the validator requires that `senderId` point at a **`MessagingChannel` record whose `ChannelProviderStatus == ACTIVE` AND `MessageType == TEXT`** (a carrier-registered 10DLC number / short code, assigned to the business unit). There is **no headless API** to provision such a channel. The registration path is the **E360 SMS Connect surface** (`/connect/e360sms/{brands,codes,campaigns,compliance/management}`, node `e360-sms-messaging`), which sits behind an E360 SMS license **and Data Cloud / CDP tenant provisioning**. On an org without the E360 SMS tenant the SMS flow cannot be activated at all. **The email-only flow ("Referral Outreach Provider") activates fully via 1–4; the email+SMS flow ("Referral Outreach Patient") stays `InvalidDraft` until a `Text`+`ACTIVE` `MessagingChannel` (sender code) exists.**
+    6. **Activate** — once its applicable prerequisites are satisfied, set `<status>Active</status>` in the flow XML and redeploy (Metadata API activates on deploy) OR PATCH `FlowDefinition {Metadata:{activeVersionNumber:N}}` once the flow is a valid Draft.
+  - **NET:** steps 1, 2, 3, 6 are fully headless (`sf` CLI / Connect API). Step 4 is metadata-doable but content-schema-dependent. Step 5 (SMS sender code) is out-of-band org provisioning. Do NOT wire SFMC connection secrets, and do NOT create throwaway `SenderEmailAddress`/`EmailDomainKey` records for an unverifiable domain — use the authed User as sender.
+- **`enable-appointment-sync`** — the referral↔appointment status sync is the packaged "Synchronize Appointment and CSR Statuses" flow (activate it) + the Healthcare Appointment Scheduler component on the CSR Lightning record page (one of the four FlexiPage components from step 6). **Intelligent Appointment Management (IAM) is a SEPARATE product** — this Aura toggle turns on IAM's appointment-scheduling settings, a prerequisite/adjacent capability, NOT the referral status-sync mechanism itself. Do NOT treat flipping this one toggle as "referral appointment sync is done": also **activate the packaged "Synchronize Appointment and CSR Statuses" flow** and **place the Healthcare Appointment Scheduler component** on the CSR record page. Transport for the toggle: PATCH body `{value:true}` → 200 (empty success body); verify via step 29. Reversible. (The un-prefixed `/headless/metadata IndustriesSettings` equivalent 404s — see Transport rule 3.) The GET read-back returns a BARE BOOLEAN SCALAR (`true` when enabled), not a pref map — gate on `body == true`.
+
+## Act 5 of 6 — External document intake (Create Referrals from Inbound Documents / Document AI for Health)
+
+> Act 5 is **Create Referrals from Inbound Documents** ([`hc_admin_referral_management_process_received_document`](https://help.salesforce.com/s/articleView?id=ind.hc_admin_referral_management_process_received_document.htm&type=5)): transform documents received by **email and fax** into Clinical Service Requests using **Intelligent Document Automation** + the **Process Received Document** invocable action — NOT "Einstein Document Reader" and NOT an external fax provider. The documented setup runs on the **Public Health Settings** guided setup in a **strict order**: (1) enable the **Disease Surveillance** org preference — which is what *surfaces* the "Set Up Document AI for Health" guided setup — then (2) complete the Document AI for Health guided setup, then (3) turn on **Batch Document AI for Health**, then (4) build the intake automation (queues + record-triggered flows + the Process Received Document invocable), then (5) grant field access. The two org-preference toggles (Disease Surveillance, Batch Document AI) ARE live-dispatchable via the MCP; the guided-setup / IDP extraction-definition authoring, the flow/queue wiring, and the **Agentforce for Health Cloud add-on** license are the gaps.
+
+| # | Step id | Purpose | Controller / API | Route |
+|---|---|---|---|---|
+| 30 | `prepare-external-referral-fax-intake` | write (multi-part) | **Create Referrals from Inbound Documents** — enable the Disease Surveillance org pref (surfaces the Document AI for Health guided setup), set up Document AI for Health, turn on Batch Document AI for Health, then wire the **Process Received Document** intake automation. See the 5-part procedure in the notes. | Public Health Settings set-preference + Batch Intelligent Doc Extract pref + Document AI guided setup + record-triggered flows/queues (mixed live + GAP) |
+
+**Act 5 — notes (ordering & findings):**
+
+- **`prepare-external-referral-fax-intake`** — per **Create Referrals from Inbound Documents** ([`hc_admin_referral_management_process_received_document`](https://help.salesforce.com/s/articleView?id=ind.hc_admin_referral_management_process_received_document.htm&type=5)), referral fax/email intake runs on **Intelligent Document Automation** + the **Process Received Document** invocable action — do NOT wire an external fax service. **The corpus einstein `document-reader/toggle-einstein-doc-reader-pref` (and `einstein-doccapture/toggle-document-reader-pref`) route is a *different* feature ("Einstein Doc Reader") — it is NOT the documented enable path for referral document intake; do not use it here.** Follow the documented setup in order:
+
+  - **PART 1 — enable the Disease Surveillance org preference FIRST (it surfaces the Document AI for Health guided setup).** Per **Set Up Document AI for Health** ([`hc_admin_disease_surveillance_set_up_pdf_ingestion_idp`](https://help.salesforce.com/s/articleView?id=ind.hc_admin_disease_surveillance_set_up_pdf_ingestion_idp.htm&type=5)), Document AI for Health is configured from the **Public Health Settings** page guided setup, and per **Enable Disease Surveillance** that guided setup only appears once the **Disease Surveillance** preference is turned on (Setup → **Public Health Settings** → turn on **Disease Surveillance**). This preference is **live-dispatchable**: PATCH `/headless/invoke/platform/public-health-settings/set-preference` body `{orgPref:"diseaseSurveillancePref", value:true}` (returns the boolean set; Customize Application gate; enabling publishes Product Feature Telemetry). **Gate on an INDEPENDENT read-back — never the write echo:** GET `/headless/invoke/platform/public-health-settings/get-preference?orgPref=diseaseSurveillancePref` → `true`. Reversible, **but note disabling `diseaseSurveillancePref` while `diseaseCaseClassificationPref` is on disables BOTH atomically**. The four allowlisted Public Health prefs (`diseaseSurveillancePref`, `diseaseCaseClassificationPref`, `healthCloudGenAIPref`, `deDupeForDSPref`) live on the [[PublicHealthSettings]] node.
+  - **PART 2 — Set Up Document AI for Health (guided setup on Public Health Settings).** In Setup → **Public Health Settings**, follow the guided setup to Set Up Document AI for Health (automates PDF/fax data extraction and maps it to Health Cloud objects). **License:** requires the **Agentforce for Health Cloud add-on** (Enterprise/Unlimited + Health Cloud). **Perm sets (per the doc):** **Health Cloud Foundation** + **Disease Surveillance** + **Data Cloud Architect** + **Document AI for Health** + **Context Service Admin**.
+    - **FIRST — verify/assign the `Document AI for Health` permission set to the running user (precondition for the guided setup).** API name **`AgentforceDiseaseSurveillanceIDP`** (namespace `force`). Without it the running identity can't author or run the Document AI extraction setup. **Read it back first** — `SELECT Id FROM PermissionSetAssignment WHERE Assignee.Id = '<running user>' AND PermissionSet.Name = 'AgentforceDiseaseSurveillanceIDP'` (the `Name` is un-namespaced with a separate `PermissionSet.NamespacePrefix = 'force'` column — same convention as `FlowDefinitionView.ApiName`; do NOT query `force__AgentforceDiseaseSurveillanceIDP`) — and **assign it only if missing** via Data-API `PermissionSetAssignment` create (`POST /services/data/v67.0/sobjects/PermissionSetAssignment` `{PermissionSetId, AssigneeId}`; `DUPLICATE_VALUE` = already assigned = success — same mechanics as step 20). If the perm set itself doesn't exist on the org, that's the **Agentforce for Health Cloud add-on** license gap (below) → surface it and HALT this part. The sibling perm sets in the doc list (Disease Surveillance, Data Cloud Architect, Context Service Admin, Health Cloud Foundation) follow the same read-back-then-assign pattern.
+    - The guided-setup / IDP extraction-definition authoring (document types, extraction models, field mappings) is a Setup-UI / IDP-designer task — see the [[IntelligentDocExtract]] companion node (document-extraction-definition templates + flows) — with no single `dispatch` write, so surface it as a UI step; do NOT fabricate a call. **GAP (`entitlement_missing`) when the add-on license is absent** — the guided setup cannot complete without it; surface, license Agentforce for Health Cloud, then re-run.
+  - **PART 3 — turn on Batch Document AI for Health.** Per **Set Up Document AI for Health for Referral Management**, once Document AI for Health is set up, turn on batch processing (Setup → **Batch Document AI for Health**). **Live-dispatchable:** PATCH `/headless/invoke/industries/industries-healthcare/batch-intelligent-doc-extract-setup-page/set-preference` `{orgPref:<batch pref>, value:true}` (Customize Application gate). **Discover the exact `orgPref` key via** GET `.../batch-intelligent-doc-extract-setup-page/get-preference` (do NOT hardcode it), set the batch source content folder via PATCH `.../batch-intelligent-doc-extract-setup-page/save-folder-selection {contentFolderId}`, and gate on the GET read-back.
+  - **PART 4 — build the intake automation (Process Received Document).** Per the main article, the **Process Received Document** invocable action uses text extracted from received documents to populate patient details and the requested procedure/diagnostic service. Build the workflow: (a) create a **queue for newly received documents** and another **queue for documents that have had their data extracted**; (b) a **record-triggered flow** that moves newly received documents to the received-documents queue; (c) a second **record-triggered flow** that moves extracted documents to the processed-documents queue — **when a `ReceivedDocument.OcrStatus` change triggers this flow, include a Run Asynchronously path** (per the doc, this guards against errors in the background Process Received Document run). Record-triggered flows are Tooling `Flow`-creatable (Transport rule 4), but the queue routing + invocable wiring is flow-designer work — surface as a UI/metadata step (see the doc's "Sample of Automated Document Queues"); do NOT fabricate a call.
+  - **PART 5 — grant field access.** Per the main article, make sure users who manage referrals have access to the **`IsAccepted`** field on the **Clinical Service Request** object (FLS via permission set / profile).
+  - **Net:** Parts 1 and 3 (the Disease Surveillance pref + the Batch Document AI toggle) are live-dispatchable and MUST each be gated on their read-back; Part 2's guided Document AI setup is license-gated (Agentforce for Health Cloud add-on) + Setup-UI; Part 4's flows/queues/invocable wiring is flow-designer; Part 5 is FLS. Do NOT wire an external fax provider, and do NOT use the einstein doc-reader toggle.
+
+## Act 6 of 6 — Public referral portal (Experience Cloud + reCAPTCHA + Web-to-Case + OmniScript + guest owner)
+
+> **This act follows the documented "Provide a Secure Referral Form to Guest Users" flow, whose canonical UI entry point is the Referral Management Settings page's guided setup.** The docs prescribe FIVE ordered phases (see the notes): **A** get the org ready (Person Accounts + OmniStudio, permission assignments, the **Guest Referral permission set**, enable Digital Experiences, register the site domain, add Google as a Trusted URL, and on the RM Settings page turn on **Require reCAPTCHA Verification** + **Assign Owner**); **B** build the site on the **Build Your Own (Aura)** template (public access → guest-profile record types/object perms → Security & Privacy CSP → trusted sites → activate); **C** set up reCAPTCHA (Google sign-up → turn on Web-to-Case → the Web-to-Case HTML Generator registers the key pair); **D** customize the **Create Referral OmniScript** (New Version → set `captchaSiteKey` + `captchaKeyPairName` → activate); **E** finish the site (assign the guest perm set + sharing rules + guest file uploads → add reCAPTCHA head markup → add the OmniScript component → publish). The live-dispatchable writes are the **Require reCAPTCHA Verification** toggle (step 32; see the HC silent-no-op caveat), the **guest referral record owner** (steps 38–39), and the **site cold-create** (step 31). The Google reCAPTCHA key, Web-to-Case HTML, Experience-Builder site config, sharing rules, head markup, and OmniScript authoring are external/manual GAPS. Analytics enablement (step 37) is PARTIAL (Phase 1 base CRM Analytics; Phase 2 requires a provisioned template) and orthogonal to these docs. Run per the `portal_scope` decision.
+
+| # | Step id | Purpose | Controller / API | Route |
+|---|---|---|---|---|
+| 31 | `provision-referral-experience-cloud-site` | write | `POST /connect/communities` with the **Aura** Build-Your-Own template — its exact `templateName` is **`"Build Your Own"`** (the Aura variant carries NO suffix; only the LWR variant is `"Build Your Own (LWR)"`). Aura ships the OmniScript component the guest form needs — NOT "Customer Service"/LWR. `{name, templateName, urlPathPrefix}` → 202 + async `SiteTaskCreate` | POST `/services/data/v67.0/connect/communities` |
+| 32 | `enable-captcha-verification` | write | Toggles Require reCAPTCHA Verification (body `{value:true}`) | PATCH `/headless/invoke/platform/referral-management-settings/handle-captcha-verification-toggle` (proposed) |
+| 33 | `verify-captcha-verification` | verify | Reads the Referral Management settings → `isCaptchaVerificationEnabled` | GET `/headless/invoke/platform/referral-management-settings` (proposed) |
+| 34 | `register-recaptcha-site-key` | write | *(GAP — Google reCAPTCHA v2 sign-up; **Domain = your guest site URL**; capture Site Key + Secret Key)* | — |
+| 35 | `generate-web-to-case-html` | write | *(GAP — manual UI: turn on Web-to-Case, then Web-to-Case HTML Generator registers the reCAPTCHA key pair → `captchaKeyPairName`)* | — |
+| 36 | `activate-create-referral-omniscript` | write (clone packaged) | CLONE the packaged `HealthCloudReferral/CreateReferral` OmniScript, set **`captchaSiteKey` + `captchaKeyPairName`**, then activate. Do NOT create an empty shell with a colliding `uniqueName`. **PRECONDITION: confirm the packaged script is present via `GET /connect/omni-designer/os/get-scripts` (type `HealthCloudReferral`, subType `CreateReferral`) — it usually ships file-based, so an empty `OmniProcess` table does NOT mean it is missing; content-blocked only if `get-scripts` lacks it too (see step note).** Stays manual: Core's clone resource is designer-internal (not served) and the captcha-property write is unverified. | `get-scripts` discovery + OmniStudio designer clone/activate |
+| 37 | `enable-referral-management-analytics` | write | Phase 1 enable CRM Analytics; Phase 2 the analytics app auto-install (`templateApiName`, `appName`, `params`) | PATCH `.../insights-setup-getting-started/enable`; PATCH `.../health-cloud-admin-feature-setup/send-auto-install-request` (proposed) |
+| 38 | `read-guest-referral-record-owner-candidates` | read | Reads the Salesforce-licensed users eligible to own guest referrals | GET `/headless/invoke/industries/industries-healthcare/owner-id-setup/get-salesforce-licensed-users` (proposed) |
+| 39 | `set-guest-referral-record-owner` | write | Saves the guest referral record owner (body `{ownerId}`) | PATCH `/headless/invoke/industries/industries-healthcare/owner-id-setup/save-owner` (proposed) |
+
+**Act 6 — notes (documented procedure, ordering & findings):**
+
+**The documented flow ("Provide a Secure Referral Form to Guest Users") runs in FIVE ordered phases (A→E below), and the canonical UI entry point is the Referral Management Settings page's guided setup** (Setup → **Referral Management Settings** → *"follow the guided setup steps to set up your Experience Cloud site, set up reCAPTCHA, and install and configure the Create Referral OmniScript"*). The executable table steps are called out by number inside each phase.
+
+- **PHASE A — Get your org ready** ([`hc_admin_referral_management_guest_users_org_ready`](https://help.salesforce.com/s/articleView?id=ind.hc_admin_referral_management_guest_users_org_ready.htm&type=5)). (1) Confirm **Person Accounts** on (Act 0 prereq) and **OmniStudio** present — for HC this is the **standard/metadata** mode (**OmniStudio Metadata ON + Managed Package Runtime OFF**; Prereqs §A / Act 0 `check-omnistudio-runtime`), even though the doc phrases it as "install the OmniStudio managed package." (2) Assign user permissions: **Customize Application** (web-form editors), **OmniStudio Admin** (OmniScript editors), **Create and Set Up Experiences** + **View Setup and Configuration** (site builders). (3) Create the **Guest Referral permission set** — Label "Guest Referral Permission Set", **License = OmniStudio**; enable the system permission *"Enables admin/developer to create new OS/DR/VIP instances"*; grant **Read** (object + all fields) on **Omni Processes** AND **Omni Process Compilations**. (4) Enable **Digital Experiences** (Setup → Digital Experiences → Settings → Enable Digital Experiences — itself dispatchable via the `CommunitiesSettings` metadata write; the `Network` sObject becoming queryable is the on/off probe), select **"Hide badges from guest users in Experience Builder sites"**, then under **Sites** register your Salesforce Site domain and select **"Allow using standard external profiles for self-registration, user creation, and login."** (5) Add **Google as a Trusted URL** (Setup → Trusted URLs → New: API Name `Google`, URL `https://www.google.com`, select **all** CSP Directives) — this is the ORG-level Trusted URL, distinct from the site-level Trusted Sites in Phase B. (6) On the **Referral Management Settings** page turn on **Require reCAPTCHA Verification** (step 32) and click **Assign Owner** (steps 38–39). (7) Then use that page's **guided setup** to drive Phases B–E.
+- **`enable-captcha-verification` (step 32) → `verify-captcha-verification` (step 33)** — this is the **"Require reCAPTCHA Verification"** control on the **Referral Management Settings** page (its "Experience Cloud Settings" surface). Aura route PATCH `.../referral-management-settings/handle-captcha-verification-toggle {value:true}` → 200; verify GET `.../referral-management-settings` → `isCaptchaVerificationEnabled:true`. It enables **server-side captcha enforcement** — the reason `postGuestReferral` then requires a `captchaToken` (runtime step 41 / C1). **HC caveat:** the backing pref is the industries captcha-verification preference (`IndustriesSettings.enableIndustriesCaptchaVerification`); the `ReferralManagementSettings` node's recipe flags that the Aura toggle **can silently no-op behind a Health-Cloud gate** — so if the step-33 read-back doesn't flip, fall back to the Metadata master transport (Transport rule 3): PUT `/services/data/v67.0/headless/metadata {type:"IndustriesSettings", fullName:"IndustriesSettings", xmlRep:"<IndustriesSettings><enableIndustriesCaptchaVerification>true</enableIndustriesCaptchaVerification></IndustriesSettings>"}` (partial-body merge), then re-verify via `readMetadata`. This toggle is ONE piece, not the whole reCAPTCHA wiring — Phases C + E complete it. Reversible.
+- **`read-guest-referral-record-owner-candidates` → `set-guest-referral-record-owner`** — the GET returns `List<UserInfo>{id, name, email, profileName, selected}` (Salesforce-licensed users eligible to own guest-created referrals; the User Id field is named `id`, NOT `userId`); the PATCH body is `{ownerId:<id>}` (the chosen element's `id`) → void 200. the save operation throws `'OwnerId is invalid'` if `ownerId` is blank/invalid, so pick a real `id` from the read (the currently-set owner shows `selected:true`). This sets the guest referral record owner value, for which there is no Metadata/Connect/Tooling equivalent — the Aura `save-owner` route is canonical.
+- **PHASE B — Build the guest referral site** ([`hc_admin_referral_management_guest_users_site_build`](https://help.salesforce.com/s/articleView?id=ind.hc_admin_referral_management_guest_users_site_build.htm&type=5)) → **`provision-referral-experience-cloud-site` (step 31)** plus its Experience-Builder config. Use the AURA Build-Your-Own template, NOT `"Customer Service"` — only the Aura template hosts the OmniScript (OmniStudio) Lightning component the guest Create Referral form is embedded into; an LWR/Customer-Service site cannot render it and the form will not appear. **UI label vs API:** Experience Builder labels it *"Build Your Own (Aura)"*, but the Connect API `templateName` is the un-suffixed **`"Build Your Own"`** (`"Build Your Own (Aura)"` 400s `INVALID_INPUT "The specified template does not exist."`; only the LWR variant carries a suffix, `"Build Your Own (LWR)"`). **Do NOT hardcode the string blind — enumerate `GET /services/data/v67.0/connect/communities/templates` first and match the Aura BYO entry**, since the exact label is org/version-sensitive. Cold-create: `POST /connect/communities {name, templateName:"Build Your Own", urlPathPrefix:"referrals"}` → **202** `{jobId}` (async); poll `BackgroundOperation` by the jobId → `Status:Complete, Type:SiteTaskCreate`; the `Network` row then exists (`Status:UnderConstruction`). Requires Digital Experiences enabled (Phase A; independently confirmable — the `Network` sObject is queryable). Transport rule 4. **Then finish the site in Experience Builder (UI, no headless route — surface as manual):** (a) **General Settings → enable Public Access** (creates the Guest Referral Site guest user profile + guest user); (b) on the **guest user profile**, Record Type Settings → Accounts → add **Person Account** and set it as **Default Record Type**, and Standard Object Permissions → **Accounts: Read + Create**, **Code Sets: Read**; (c) **Security & Privacy** → Clickjack Protection = **"Allow framing by the same origin only"**, Security Level = **"Relaxed CSP: Permit Access to Inline Scripts and Allowed Hosts"**; (d) add **Trusted Sites** `Google` = `https://www.google.com` and `gstatic` = `https://www.gstatic.com` (both Active) — these two site-level Trusted Sites let the reCAPTCHA widget load, distinct from the org Trusted URL (Phase A) and from the Google reCAPTCHA *registered domain* (Phase C); (e) **Activate** the site (Administration workspace → Activate). Copy the site URL — Phase C needs it for reCAPTCHA sign-up. Publishing Live is a Phase E follow-on.
+- **PHASE C — Set up reCAPTCHA** ([`hc_admin_referral_management_guest_users_recaptcha`](https://help.salesforce.com/s/articleView?id=ind.hc_admin_referral_management_guest_users_recaptcha.htm&type=5)) → **`register-recaptcha-site-key` (step 34)** + **`generate-web-to-case-html` (step 35)**; both external/manual GAPS. **(1) Sign up for reCAPTCHA (Google console):** the reCAPTCHA type MUST be **reCAPTCHA v2, "I'm not a robot" Checkbox (Challenge)** — NOT v3 (score-based) and NOT the invisible/Enterprise variants (the guest OmniScript widget expects the v2 checkbox challenge). **For Domain, enter the URL of your guest referral Experience Cloud site** (the site from Phase B) — *NOT* `google.com`/`gstatic.com`. (Those two are added elsewhere: as site-level **Trusted Sites** in Phase B step (d) and Google as an org-level **Trusted URL** in Phase A step (5); a prior version of this skill wrongly listed them as the Google reCAPTCHA domains.) Register → receive a public/private key pair; copy the **Site Key** (→ OmniScript `captchaSiteKey`, Phase D) and **Secret Key** into a text file — both are needed by the Web-to-Case HTML Generator. **(2) Turn on Web-to-Case** (Setup → Web-to-Case → enable) — a precondition for the generator. **(3) Generate a Web Form with reCAPTCHA Verification** (Setup → **Web-to-Case HTML Generator**): keep **"Include reCAPTCHA in HTML"** selected; next to **reCAPTCHA API Key Pair** click the lookup → **New**, enter a **nickname** + the Google Site/Secret keys, and **Save** — this **registers the key pair on the Salesforce platform, and that nickname IS the `captchaKeyPairName`** used in the OmniScript (Phase D). Click **Generate**, copy the HTML, click Finished. Manual/UI-only — surface both key values + the nickname to the admin.
+- **PHASE D — Customize the Create Referral OmniScript** ([`hc_admin_referral_management_guest_users_omniscript_configure`](https://help.salesforce.com/s/articleView?id=ind.hc_admin_referral_management_guest_users_omniscript_configure.htm&type=5)) → **`activate-create-referral-omniscript` (step 36)**. Requires the **OmniStudio Admin** permission set and **standard OmniStudio** (OmniStudio Settings → **OmniStudio Metadata ON, Managed Package Runtime OFF**; Act 0 `check-omnistudio-runtime` / `standardOmniStudioRuntime` ON). The Create Referral OmniScript ships as the **`HealthCloudReferral` / `CreateReferral`** OmniScript (`Type=HealthCloudReferral`, `SubType=CreateReferral`, language Multi-Language, name "Create Referral"). **PRECONDITION — find the packaged script before cloning.** It typically ships **file-based** (`isFileBasedScript:true`, `isActive:false`, from the `healthcloud_referral_flows` content), so it is NOT an `OmniProcess` row until cloned — `SELECT COUNT() FROM OmniProcess` can read 0 on an org that has it. FIRST call `GET /services/data/v67.0/connect/omni-designer/os/get-scripts` and look for type `HealthCloudReferral` / subType `CreateReferral`; also accept an existing `OmniProcess` row with that Type/SubType. Only if NEITHER has it is this step content-blocked (a missing-content precondition, NOT a transport failure) — deploy the healthcloud OmniStudio content so `CreateReferral` materializes, THEN proceed. **Why this stays manual:** Core does implement a whole-process clone (`POST /connect/omni-designer/clone-omni-process {id, type:"OS"}` → an inactive DB-backed copy; activation is then `IsActive=true` with any other active version deactivated first), but that resource is designer-internal (not served by the catalog) and writing the captcha properties into the cloned element over sObject REST is unverified — do not fabricate that chain; use the designer. Per the doc: App Launcher → **OmniStudio** app → **OmniScripts** → search **HealthCloudReferral/CreateReferral** → open → **New Version** (this is the "clone"; click **Edit** after New Version only if you want a different type/subtype/name). In the new version, on the **InitializeValues** set-values element set **`captchaSiteKey`** = the Google reCAPTCHA **Site Key** (Phase C) and **`captchaKeyPairName`** = the **nickname** of the Web-to-Case reCAPTCHA API key pair (Phase C); review/customize the **ReferralForm** step; then **Activate Version**. Do NOT `POST type:OmniScript` an empty shell with the same Type/SubType/Language — it collides with the packaged script and produces a non-functional duplicate. The captcha fields are load-bearing for the guest form (step 41 / C1: the guest endpoint requires a `captchaToken`).
+- **PHASE E — Customize your Experience Cloud site** ([`hc_admin_referral_management_guest_users_site`](https://help.salesforce.com/s/articleView?id=ind.hc_admin_referral_management_guest_users_site.htm&type=5)) — three UI sub-steps, all manual (no headless route): **(1) Configure Guest User Access** ([`..._config`](https://help.salesforce.com/s/articleView?id=ind.hc_admin_referral_management_guest_users_config.htm&type=5)): assign the **Guest Referral permission set** (Phase A) to the site's **guest user** (site General Settings → guest user profile → View Users → the guest user → Permission Set Assignments → Edit → move it to Enabled); create **sharing rules** (Setup → Sharing Settings) granting the guest user **Read Only** access to active **Code Sets** (Criteria: `Active` equals `True`) AND active **Omni Processes** (Criteria: `Active` equals `True`) — without the Omni Processes rule the guest can't render the OmniScript; and enable **Salesforce Files → General Settings → "Allow site guest users to upload files"** (for the referral document upload). **(2) Add reCAPTCHA verification markup** ([`hc_admin_recaptcha_markup`](https://help.salesforce.com/s/articleView?id=ind.hc_admin_recaptcha_markup.htm&type=5)): Experience Builder → Settings → **Advanced settings → Edit Head Markup** → paste the Google `grecaptcha` script (loads `https://www.google.com/recaptcha/api.js` and wires the `grecaptchaRender`/`grecaptchaReset` events that render + reset the widget) → Save + **publish**. **(3) Add the Create Referral OmniScript to the site** ([`..._site_omniscript`](https://help.salesforce.com/s/articleView?id=ind.hc_admin_referral_management_guest_users_site_omniscript.htm&type=5)): in Experience Builder drag the **OmniScript** component onto the canvas and set **OmniScript Type = `HealthCloudReferral`**, **SubType = `CreateReferral`** (or your custom version's type/subtype) → **Publish**. Only after publish does the guest form show the "I'm not a robot" checkbox and accept submissions.
+- **PHI-safety gates around Publish (both manual — no served route):** the guest site is **public and unauthenticated**, so publishing it on an over-broad guest access scope silently exposes **PHI** to the open internet — treat that as a breach, not a config nit. Two checkpoints bracket the Publish sub-step above:
+  - **`review-guest-referral-security-exposure` (BEFORE Publish)** — an admin MUST review the guest user profile's object permissions AND the guest sharing rules created in Phase E step (1), and confirm they expose **ONLY** the referral-intake surface the Create Referral OmniScript needs (and its minimum required lookups): **never** Person Account, Clinical Service Request, Case, or any other **PHI**-bearing records. Remove every object/field the form does not require from guest access. Do **NOT** publish until this review passes.
+  - **`verify-guest-site-published-and-scoped` (AFTER Publish)** — the post-publish read-back for this phase (Phase E has no served verify route). Load the public site URL **logged out** and confirm end-to-end that (1) the site is **Live** and reachable, (2) only the Create Referral OmniScript form is browsable as guest — no Person Account / Clinical Service Request / Case data is reachable — and (3) reCAPTCHA is enforced on submit. Complete this check **before** `create-guest-referral-runtime` (step 41) is exercised.
+- **`enable-referral-management-analytics`** — **PARTIAL (two-phase).** Referral analytics is a **category inside the Health Cloud "Enhanced Analytics for Healthcare" CRM Analytics app**, not a standalone toggle.
+  - **Phase 1 — enable base CRM Analytics (reversible):** PATCH `/headless/invoke/platform/insights-setup-getting-started/enable` (the CRM Analytics enable operation, `implemented`, no body) → 200; read back GET `.../insights-setup-getting-started` → `isAnalyticsFullyEnabled:true` (7 enablement steps). Reverse via the sibling `.../disable`. Requires CRM Analytics (Insights) enabled.
+  - **Phase 2 — auto-install the HC analytics app with the referral category on:** PATCH `/headless/invoke/platform/health-cloud-admin-feature-setup/send-auto-install-request` → the analytics app auto-install operation (`templateApiName`, `appName`, `params`) with `templateApiName = "sfdc_internal__HLSModernizationApp"` (label "Enhanced Analytics for Healthcare") and `params:{isReferral_Selected:"true"}` (sibling categories: `isUtilizationManagement_Selected`/`isCareManagement_Selected`/`isHomeHealth_Selected`/`isRiskScore_Selected`). Referral analytics builds the `CSR_Referral_tp` / `CSR_Referral_History_tp` datasets (CSR = Clinical Service Request → clinical referrals). The `templateApiName`, the `isReferral_Selected`/sibling param keys, and the dataset names are org/version-sensitive — re-confirm against the provisioned org's `/wave/templates` before relying on the exact strings.
+  - **Prerequisites:** assign the **HealthCare Analytics Admin** + **CRM Analytics Plus Admin** permission sets, then Phase 1, then Phase 2. There is **no** HC AdminSetup config JSON for this (unlike WarrantyAnalytics).
+  - **Why PARTIAL:** Phase 2 requires the `sfdc_internal__HLSModernizationApp` CRMA template package provisioned in the org; if absent, it returns 200 `{status:"NOT_FOUND", message:"No App Exist."}` (`/wave/templates?type=app` empty) — not a transport gap. Attempt Phase 2 on a provisioned org, then gate on the app/datasets appearing.
+  - **Disambiguation (the naming trap):** the corpus node `ReferralManagementAnalyticsSetup` (Aura `runtime_industries_referral_management:referralMarketingAnalyticsSetup`, template `Referral_Analytics`) is **B2C Referral MARKETING analytics — a different feature.** Clinical Referral Management analytics is the HC "Enhanced Analytics for Healthcare" category above, NOT that B2C marketing surface.
+
+## Runtime validation (end-to-end proof the setup works)
+
+Once Act 1 (and the internal-creation surfaces) are in place, these native Connect APIs prove the pipeline end-to-end. They are `implemented` (real Connect endpoints). Each sits behind a runtime gate (below), so treat them as diagnostics of the org's runtime readiness, not proof-of-success steps.
+
+| # | Step id | Purpose | Controller / API | Route |
+|---|---|---|---|---|
+| 40 | `create-referral-runtime` | validate | Connect `postReferralManagement` (`ReferralManagementInputRepresentation`) | POST `/services/data/v67.0/connect/health/referral-management/referrals` (implemented) |
+| 41 | `create-guest-referral-runtime` | validate | Connect `postGuestReferral` (guest intake) | `POST /connect/health/referral-management/guest-referrals` — guest-only + UiTier-excluded (HTTP 404 for external callers; authenticated POST → "This API can only be called by Guest"), so **no served/dispatchable route** — GAP; exercise only via the published guest form |
+
+- **`create-referral-runtime`** validates the internal path: with the app enabled (Act 1 steps 5a/5b) and Person Accounts present, POST a referral and confirm a `ClinicalServiceRequest` is created. The runtime is gated at the **user** level even with the org-level Referral Management app ON: an unentitled user gets 403 `FUNCTIONALITY_NOT_ENABLED`. The gate is a user-level permission-set assignment (Referral Management runtime access), not another org toggle — a residual GAP (`feature_not_enabled_for_user`) the admin closes by granting the running user the runtime permission set.
+- **`create-guest-referral-runtime`** validates the public path: it uses the guest referral record owner set in step 39. **TWO gates, and the guest-context gate fires FIRST.** An authenticated POST to `postGuestReferral` returns `UNKNOWN_EXCEPTION "This API can only be called by Guest."` — the caller-identity (guest-context) check is a hard first gate, rejecting the request before any `captchaToken` validation. The `captchaToken` requirement is the SECOND gate: `postGuestReferral`'s input representation requires a **mandatory `captchaToken`** field (a Google reCAPTCHA response token, `ReCaptcha` type, ~2-minute TTL) produced only when a real user solves the reCAPTCHA widget on the published guest form. **Net: this endpoint is NOT smoke-testable from any authenticated/programmatic session** — (1) the session is not a Guest user, and (2) no valid `captchaToken` can be synthesized. Verify it ONLY by submitting through the published guest referral form as an actual guest (a human solves the reCAPTCHA → a live token is minted and posted; requires the Experience site published Live — see Act 6). The captcha gate is the whole point of `enable-captcha-verification` (step 32) + the site-key/OmniScript captcha fields (steps 34/36).
+- Treat both as smoke tests of the completed setup, not setup steps proper. Neither succeeding is required for "done" — but each failure is a real, reportable signal (a missing user entitlement, and an unpublished guest site) rather than a corpus error.
+
+## Definition of done (the whole skill)
+
+An unqualified Referral Management setup is **complete only when every non-gapped step across Acts 0–6 has reached its verified end state** (gate on each `verify-*` read-back) AND every gapped step has been surfaced to the admin with its manual remediation. The live-dispatchable core is: Criteria-Based Search & Filter ON (Act 2), appointment sync ON (Act 4), captcha verification ON + guest referral record owner set (Act 6), with `create-referral-runtime`/`create-guest-referral-runtime` optionally exercised as smoke tests. If Person Accounts is off, the setup is BLOCKED (redirect to [[health-cloud-initial-setup]]), not partially done.
+
+**Final-summary format — the manual steps MUST each carry their Help link(s).** When you write the closing summary and list the manual / out-of-band steps (the `gaps_surfaced` list), render each as: **step name — one-line remediation — [Help doc](url)** for **every** URL in that step's `help_urls` list (steps with several docs, like `prepare-external-referral-fax-intake` and `act6-phase-e-customize-site`, render one link per doc). A manual step missing any of its Salesforce Help links is an incomplete summary; go back to the Manual-step documentation contract table (top of this skill) and add them. Do not present the manual steps as a bare bullet list of "do X by hand" with no links.
+
+**Org-specific values (picklist values, permission-set / user / data-space IDs, template API names) MUST be discovered live per-org** — never hardcode IDs or picklist sets, and always gate each write on its read-back.
+
+## Resumability
+
+Every step is skippable and revisitable. Before acting on any step, re-read the corresponding `read-`/`verify-`/`check-`/`discover-` step to detect existing org state and avoid duplicating work — the agent should determine where to begin from org state, not assume a fresh org. Skip a write when its read shows the target state is already correct (`read-referral-management-settings` resolves the Act-6 captcha toggle state).
+
+## Underlying setup-page nodes (companion references — do not duplicate their step definitions)
+
+This workflow sequences operations already defined on these setup-page nodes and sibling skills; call them by controller method / route rather than re-deriving:
+
+- `ReferralManagementSettings` — the Referral Management app + captcha verification toggles.
+- `CriteriaBasedSearchAndFilter` — Provider Search Criteria-Based Search & Filter preference.
+- `OwnerIdSetup` — guest referral record owner (the guest-referral owner save operation).
+- `PatientAppointmentSchedulingSettings` — appointment sync toggle.
+- `OmniStudioSettings` — Standard OmniStudio runtime pref.
+- `ClinicalServiceRequest` — the standard Health Cloud referral entity (Status/StatusReason picklists, page layout, path).
+- `PersonAccountSettings` (via [[health-cloud-initial-setup]]) — the irreversible Person Accounts prerequisite this skill delegates.
+- `SonicGettingStarted` — the Data Pipelines org-preference toggle (`appType=DataManager`) that gates the Data Processing Engine behind Actionable Segmentation (step 8).
+- `PublicHealthSettings` — the Public Health Settings page backing Act 5's Disease Surveillance org-preference toggle (set-preference / get-preference; allowlisted prefs `diseaseSurveillancePref`, `diseaseCaseClassificationPref`, `healthCloudGenAIPref`, `deDupeForDSPref`); enabling Disease Surveillance surfaces the Document AI for Health guided setup.
+- `IntelligentDocExtract` — the Document AI for Health / Intelligent Document Automation config surface (document-extraction-definition templates + flows) behind Act 5; batch enablement via `batch-intelligent-doc-extract-setup-page` (`set-preference`, `get-preference`, `save-folder-selection`).
+
+Additional capabilities referenced inline: the Health Cloud license gate, the OmniStudio runtime preference read, the Tooling API (Layout, picklist/RecordType discovery), and the native `ReferralManagement` Connect API (runtime create).
+
+<!-- skill-validate: ignore-start -->
+<!-- codey:operations start -->
+## Operations Reference
+
+Operations this skill uses — routing and dependency reference.
+
+| Operation | Purpose | Status | Call | Depends on |
+|-----------|---------|--------|------|------------|
+| `verify-health-cloud-license` | read | — | `GET /headless/invoke/platform/health-cloud-admin-feature-setup/has-health-cloud-licence` | — |
+| `read-referral-management-settings` | read | — | `GET /headless/invoke/platform/referral-management-settings` | — |
+| `enable-person-accounts` | write | — | `PATCH /headless/invoke/platform/person-account-settings/enable-person-accounts` | — |
+| `check-omnistudio-runtime` | read | — | `GET /headless/invoke/platform/omni-studio-settings/get-omni-studio-prefs` | — |
+| `discover-clinical-service-request-picklists` | discovery | — | `GET /services/data/v67.0/tooling/query/` | — |
+| `enable-referral-management-app` | write | — | `PATCH /headless/invoke/platform/referral-management-settings/handle-referral-management-app-toggle` | — |
+| `verify-referral-management-app-enabled` | verify | — | `GET /headless/invoke/platform/referral-management-settings` | `enable-referral-management-app` |
+| `assign-clinical-service-request-page-layout` | write | — | — | — |
+| `configure-referral-management-path` | write | — | — | `discover-clinical-service-request-picklists` |
+| `configure-referral-actionable-lists` | write | — | — | — |
+| `create-referral-screen-flow` | write | — | — | — |
+| `enable-criteria-based-search-and-filter` | write | — | `PATCH /headless/invoke/platform/criteria-based-search-and-filter/set-criteria-based-search-and-filter-pref` | — |
+| `verify-criteria-based-search-and-filter` | verify | — | `GET /headless/invoke/platform/criteria-based-search-and-filter/get-criteria-based-search-and-filter-pref` | `enable-criteria-based-search-and-filter` |
+| `include-referral-action-in-provider-search` | write | — | — | `create-referral-screen-flow`, `enable-criteria-based-search-and-filter`, `configure-referral-actionable-lists` |
+| `create-case-business-process` | write | — | — | — |
+| `create-case-record-type` | write | — | `POST /services/data/v67.0/tooling/sobjects/RecordType` | `create-case-business-process` |
+| `create-case-from-csr-flow` | write | — | — | — |
+| `configure-patient-referral-expression-set` | write | — | `POST /connect/business-rules/expression-set` | — |
+| `load-patient-referral-decision-table` | write | — | `POST /connect/business-rules/decision-table/definitions` | `configure-patient-referral-expression-set`, `add-csr-status-picklist-values`, `add-csr-status-reason-picklist-values` |
+| `add-csr-status-picklist-values` | write | — | — | — |
+| `add-csr-status-reason-picklist-values` | write | — | — | — |
+| `assign-action-plans-permission-set` | write | — | `POST /sobjects/PermissionSetAssignment` | — |
+| `activate-referral-flow-orchestration` | write | — | — | — |
+| `create-ebv-prior-auth-apex-classes` | write | — | `POST /services/data/v67.0/tooling/sobjects/ApexClass` | — |
+| `provision-ebv-callback-experience-site` | write | — | — | `create-ebv-prior-auth-apex-classes`, `create-mulesoft-fhir-named-credential` |
+| `create-mulesoft-fhir-named-credential` | write | — | — | — |
+| `install-datacloud-referral-scoring-data-kit` | write | — | — | — |
+| `place-outbound-engagement-home-component` | write | — | — | — |
+| `configure-marketing-cloud-outreach` | write | — | — | — |
+| `enable-appointment-sync` | write | — | `PATCH /headless/invoke/platform/patient-appointment-scheduling-settings/handle-patient-appointment-scheduling-toggle` | — |
+| `verify-appointment-sync` | verify | — | `GET /headless/invoke/platform/patient-appointment-scheduling-settings/get-patient-appointment-scheduling-org-pref` | `enable-appointment-sync` |
+| `enable-disease-surveillance-pref` | write | — | `PATCH /headless/invoke/platform/public-health-settings/set-preference` | — |
+| `verify-disease-surveillance-pref` | verify | — | `GET /headless/invoke/platform/public-health-settings/get-preferences` | `enable-disease-surveillance-pref` |
+| `enable-intelligent-doc-extract-pref` | write | — | `PATCH /headless/invoke/platform/intelligent-doc-extract/set-preference` | — |
+| `verify-intelligent-doc-extract-pref` | verify | — | `GET /headless/invoke/platform/intelligent-doc-extract/get-preference` | `enable-intelligent-doc-extract-pref` |
+| `prepare-external-referral-fax-intake` | write | — | — | `verify-disease-surveillance-pref`, `verify-intelligent-doc-extract-pref` |
+| `provision-referral-experience-cloud-site` | write | — | `POST /services/data/v67.0/connect/communities` | `act6-phase-a-get-org-ready` |
+| `enable-captcha-verification` | write | — | `PATCH /headless/invoke/platform/referral-management-settings/handle-captcha-verification-toggle` | — |
+| `verify-captcha-verification` | verify | — | `GET /headless/invoke/platform/referral-management-settings` | `enable-captcha-verification` |
+| `register-recaptcha-site-key` | write | — | — | — |
+| `generate-web-to-case-html` | write | — | — | `register-recaptcha-site-key` |
+| `activate-create-referral-omniscript` | write | — | — | `register-recaptcha-site-key`, `generate-web-to-case-html`, `check-omnistudio-runtime` |
+| `enable-referral-management-analytics` | write | — | `PATCH /headless/invoke/platform/insights-setup-getting-started/enable` | — |
+| `read-guest-referral-record-owner-candidates` | read | — | `GET /headless/invoke/industries/industries-healthcare/owner-id-setup/get-salesforce-licensed-users` | — |
+| `set-guest-referral-record-owner` | write | — | `PATCH /headless/invoke/industries/industries-healthcare/owner-id-setup/save-owner` | `read-guest-referral-record-owner-candidates` |
+| `create-referral-runtime` | validate | — | `POST /services/data/v67.0/connect/health/referral-management/referrals` | `verify-referral-management-app-enabled` |
+| `create-guest-referral-runtime` | validate | — | — | `enable-captcha-verification`, `register-recaptcha-site-key`, `activate-create-referral-omniscript`, `set-guest-referral-record-owner` |
+| `act6-phase-a-get-org-ready` | write | — | — | — |
+| `act6-phase-e-customize-site` | write | — | — | `provision-referral-experience-cloud-site`, `activate-create-referral-omniscript`, `verify-captcha-verification`, `set-guest-referral-record-owner` |
+| `verify-person-accounts-enabled` | verify | — | `GET /headless/invoke/platform/person-account-settings/check-person-account-readiness` | `enable-person-accounts` |
+| `verify-configure-referral-management-path` | verify | — | `GET /services/data/v67.0/tooling/query/` | `configure-referral-management-path` |
+| `verify-create-case-business-process` | verify | — | `GET /services/data/v67.0/tooling/query/` | `create-case-business-process` |
+| `verify-create-case-record-type` | verify | — | `GET /services/data/v67.0/tooling/query/` | `create-case-record-type` |
+| `verify-configure-patient-referral-expression-set` | verify | — | `GET /connect/business-rules/expression-set/{expressionSetId}` | `configure-patient-referral-expression-set` |
+| `verify-load-patient-referral-decision-table` | verify | — | `GET /connect/business-rules/decision-table/definitions/{decisionTableId}` | `load-patient-referral-decision-table` |
+| `verify-assign-action-plans-permission-set` | verify | — | `GET /services/data/v67.0/query/` | `assign-action-plans-permission-set` |
+| `verify-ebv-prior-auth-apex-classes` | verify | — | `GET /services/data/v67.0/tooling/query/` | `create-ebv-prior-auth-apex-classes` |
+| `verify-mulesoft-fhir-named-credential-created` | verify | — | `GET /services/data/v67.0/tooling/query/` | `create-mulesoft-fhir-named-credential` |
+| `verify-referral-experience-cloud-site-provisioned` | verify | — | `GET /services/data/v67.0/connect/communities` | `provision-referral-experience-cloud-site` |
+| `verify-referral-management-analytics-enabled` | verify | — | `GET /headless/invoke/platform/insights-setup-getting-started` | `enable-referral-management-analytics` |
+| `verify-guest-referral-record-owner-saved` | verify | — | — | `set-guest-referral-record-owner` |
+| `review-guest-referral-security-exposure` | validate | — | — | `provision-referral-experience-cloud-site`, `set-guest-referral-record-owner` |
+| `verify-guest-site-published-and-scoped` | verify | — | — | `act6-phase-e-customize-site`, `review-guest-referral-security-exposure` |
+<!-- codey:operations end -->
+<!-- skill-validate: ignore-end -->