@salesforce/afv-skills 1.65.0 → 1.65.1

package/skills/industries-health-engagement-settings-configure/SKILL.md

@@ -1,218 +0,0 @@
----
-name: industries-health-engagement-settings-configure
-description: "Use this skill when users want to read and toggle two Health Cloud org preferences — Outbound Health Engagement (proactive patient outreach, `IndustriesSettings.OrgPreferences.outboundHealthEngagement`) and Empower Health Engagement (patient self-service, `IndustriesSettings.OrgPreferences.empowerHealthEngagement. Trigger when users mention health, engagement, settings, health engagement settings."
-metadata:
-  version: "1.0"
----
-
-# Querying Health Engagement Settings
-
-## When to Use This Skill
-
-Read and toggle two Health Cloud org preferences — Outbound Health Engagement (proactive patient outreach, `IndustriesSettings.OrgPreferences.outboundHealthEngagement`) and Empower Health Engagement (patient self-service, `IndustriesSettings.OrgPreferences.empowerHealthEngagement`). All routes are AURA-IS-CANONICAL: the health-engagement setup endpoint enforces a per-call `Health Cloud outbound enabled/EmpowerHealthEngagement` AccessCheck before write (throws `AuraHandledException` with a localized NoAccessMessage on denial), self-heals a stale-true preference when access is later revoked, and emits PFT telemetry on toggle. Substituting Metadata API `IndustriesSettings.enable*HealthEngagement` deploy is contract-lossy. Pre-call sequence: check user edit permission → read org access check for each feature → read current pref → toggle. `getOrgType` exposes the Health Engagement configuration variant used for UI routing.
-
-## Workflow
-
-Two independent org preferences on one Setup page: Outbound Health Engagement
-(proactive outreach) and Empower Health Engagement (patient self-service).
-Each preference has its own read/access-check/toggle triple; the two triples
-do not compose — pick the one the customer named.
-
-Per-preference workflow (Outbound shown; Empower is symmetric):
-
-### Phase 1: Gate the page
-
-checkUserHasEditPermission_1 requires Customize Application or
-System Admin. Same gate for both preferences.
-
-### Phase 2: Check org access
-
-getOutboundHealthEngagementOrgAccessCheck_4 is the org
-licence/feature gate. Side effect — a false response auto-resets the preference
-to false server-side.
-
-### Phase 3: Read current value
-
-getOutboundHealthEngagementPref_2 returns the current
-preference value.
-
-### Phase 4: Write the toggle
-
-toggleOutboundHealthEngagementPref_6 PATCHes the
-preference. The request body carries a required boolean under `value` (a missing
-boolean surfaces as a deserialization error before the AccessCheck runs). Success
-returns an empty response body; on AccessCheck denial the step throws
-AuraHandledException carrying a localized NoAccessMessage label.
-
-### Phase 5: Verify the write
-
-verify-toggleOutboundHealthEngagementPref_6 reads back the
-value (the toggle returns void, so a post-write GET is the only confirmation of
-the new state).
-
-Access denial contract: when the per-preference AccessCheck is off, the toggle
-step throws AuraHandledException carrying a localized NoAccessMessage label.
-Agents must not retry — remediation is org licensing, not caller-side.
-
-Metadata API is not a viable substitute: an IndustriesSettings deploy is
-scratch-org gated and drops the per-call AccessCheck + PFT emit; every step
-here is AURA-IS-CANONICAL.
-
-## Critical Constraints
-
-**Preconditions:**
-
-- Health Cloud must be licensed and provisioned for the org. The `HealthEngagementSettings` Setup page is only reachable when the HealthCloud feature is enabled (the controller's per-method AccessCheck flags `Outbound Health Engagement feature` / `orgHasEmpowerHealthEngagement` will otherwise return false and the toggles will be hidden / non-functional). (check: `Outbound Health Engagement feature / Health Engagement enabled`)
-- The running user must hold Customize Application or System Administrator permission. Every controller method is access-guarded by `Customize Application permission`; unprivileged users see read-only toggles and a 403-equivalent on write. (check: `Customize Application permission`)
-
-## Verification Checklist
-
-After every write operation, confirm the effect by re-reading state:
-
-- After `toggleOutboundHealthEngagementPref_6`: call `verify-toggleOutboundHealthEngagementPref_6` (`GET /headless/invoke/industries/industries-healthcare/health-engagement-setup/get-outbound-health-engagement-pref`)
-- After `toggleEmpowerHealthEngagementPref_7`: call `verify-toggleEmpowerHealthEngagementPref_7` (`GET /headless/invoke/industries/industries-healthcare/health-engagement-setup/get-empower-health-engagement-pref`)
-
-## Operations Reference
-
-Operations grouped by purpose. Use these as the building blocks for the workflows above.
-
-### Summary
-
-| Operation | Purpose | Status | Call | Depends on |
-|-----------|---------|--------|------|------------|
-| `checkUserHasEditPermission_1` | read | implemented | `GET /headless/invoke/industries/industries-healthcare/health-engagement-setup/check-user-has-edit-permission` | — |
-| `getOrgType_8` | read | implemented | `GET /headless/invoke/industries/industries-healthcare/health-engagement-setup/get-org-type` | — |
-| `getOutboundHealthEngagementOrgAccessCheck_4` | read | implemented | `GET /headless/invoke/industries/industries-healthcare/health-engagement-setup/get-outbound-health-engagement-org-access-check` | — |
-| `getEmpowerHealthEngagementOrgAccessCheck_5` | read | implemented | `GET /headless/invoke/industries/industries-healthcare/health-engagement-setup/get-empower-health-engagement-org-access-check` | — |
-| `getOutboundHealthEngagementPref_2` | read | implemented | `GET /headless/invoke/industries/industries-healthcare/health-engagement-setup/get-outbound-health-engagement-pref` | `getOutboundHealthEngagementOrgAccessCheck_4` |
-| `getEmpowerHealthEngagementPref_3` | read | implemented | `GET /headless/invoke/industries/industries-healthcare/health-engagement-setup/get-empower-health-engagement-pref` | `getEmpowerHealthEngagementOrgAccessCheck_5` |
-| `toggleOutboundHealthEngagementPref_6` | read | implemented | `PATCH /headless/invoke/industries/industries-healthcare/health-engagement-setup/toggle-outbound-health-engagement-pref` | `checkUserHasEditPermission_1`, `getOutboundHealthEngagementOrgAccessCheck_4`, `getOutboundHealthEngagementPref_2` |
-| `toggleEmpowerHealthEngagementPref_7` | read | implemented | `PATCH /headless/invoke/industries/industries-healthcare/health-engagement-setup/toggle-empower-health-engagement-pref` | `checkUserHasEditPermission_1`, `getEmpowerHealthEngagementOrgAccessCheck_5`, `getEmpowerHealthEngagementPref_3` |
-| `verify-toggleOutboundHealthEngagementPref_6` | verify | — | `GET /headless/invoke/industries/industries-healthcare/health-engagement-setup/get-outbound-health-engagement-pref` | `toggleOutboundHealthEngagementPref_6` |
-| `verify-toggleEmpowerHealthEngagementPref_7` | verify | — | `GET /headless/invoke/industries/industries-healthcare/health-engagement-setup/get-empower-health-engagement-pref` | `toggleEmpowerHealthEngagementPref_7` |
-
-### Dependency graph
-
-```mermaid
-graph TD
-  checkUserHasEditPermission_1["checkUserHasEditPermission_1 (read)"]
-  getOrgType_8["getOrgType_8 (read)"]
-  getOutboundHealthEngagementOrgAccessCheck_4["getOutboundHealthEngagementOrgAccessCheck_4 (read)"]
-  getEmpowerHealthEngagementOrgAccessCheck_5["getEmpowerHealthEngagementOrgAccessCheck_5 (read)"]
-  getOutboundHealthEngagementPref_2["getOutboundHealthEngagementPref_2 (read)"]
-  getEmpowerHealthEngagementPref_3["getEmpowerHealthEngagementPref_3 (read)"]
-  toggleOutboundHealthEngagementPref_6["toggleOutboundHealthEngagementPref_6 (read)"]
-  toggleEmpowerHealthEngagementPref_7["toggleEmpowerHealthEngagementPref_7 (read)"]
-  verify_toggleOutboundHealthEngagementPref_6["verify-toggleOutboundHealthEngagementPref_6 (verify)"]
-  verify_toggleEmpowerHealthEngagementPref_7["verify-toggleEmpowerHealthEngagementPref_7 (verify)"]
-  getOutboundHealthEngagementOrgAccessCheck_4 --> getOutboundHealthEngagementPref_2
-  getEmpowerHealthEngagementOrgAccessCheck_5 --> getEmpowerHealthEngagementPref_3
-  checkUserHasEditPermission_1 --> toggleOutboundHealthEngagementPref_6
-  getOutboundHealthEngagementOrgAccessCheck_4 --> toggleOutboundHealthEngagementPref_6
-  getOutboundHealthEngagementPref_2 --> toggleOutboundHealthEngagementPref_6
-  checkUserHasEditPermission_1 --> toggleEmpowerHealthEngagementPref_7
-  getEmpowerHealthEngagementOrgAccessCheck_5 --> toggleEmpowerHealthEngagementPref_7
-  getEmpowerHealthEngagementPref_3 --> toggleEmpowerHealthEngagementPref_7
-  toggleOutboundHealthEngagementPref_6 --> verify_toggleOutboundHealthEngagementPref_6
-  toggleEmpowerHealthEngagementPref_7 --> verify_toggleEmpowerHealthEngagementPref_7
-```
-
-### Read operations
-
-#### `checkUserHasEditPermission_1`
-
-Returns whether the running user holds Customize Application or System Administrator. Gates whether toggle controls are editable on the Setup page. AURA-IS-CANONICAL — no public API exposes this single-perm probe; Tooling `UserPermissionAccess` requires a follow-up join and doesn't replicate the controller's Customize Application permission semantics.
-
-**Call:** `GET /headless/invoke/industries/industries-healthcare/health-engagement-setup/check-user-has-edit-permission`   — status: `implemented`
-
-**Output:** boolean — true when the running user holds Customize Application or System Administrator permission.
-
-#### `getOrgType_8`
-
-Returns a string identifying this org's Health Engagement configuration variant; the Setup UI uses it to choose between alternative configuration files. AURA-IS-CANONICAL — no Connect / Tooling / sObject / Metadata surface exposes this Setup-page-specific org-flavor read.
-
-**Call:** `GET /headless/invoke/industries/industries-healthcare/health-engagement-setup/get-org-type`   — status: `implemented`
-
-**Output:** string — Health Engagement configuration-variant identifier; the Setup UI keys alternative config files off this value.
-
-#### `getOutboundHealthEngagementOrgAccessCheck_4`
-
-Returns whether the org has Outbound Health Engagement feature AccessCheck enabled. SIDE EFFECT: when access is denied AND `IndustriesSettings.OrgPreferences.outboundHealthEngagement` is currently true, force-resets the pref to false (controller line 105). AURA-IS-CANONICAL — the self-heal is server-enforced; no Metadata/Tooling read replicates it.
-
-**Call:** `GET /headless/invoke/industries/industries-healthcare/health-engagement-setup/get-outbound-health-engagement-org-access-check`   — status: `implemented`
-
-**Output:** boolean — true when the org has `Outbound Health Engagement feature` access. False also indicates the side-effect auto-reset of the outboundHealthEngagement pref to false has fired this call.
-
-#### `getEmpowerHealthEngagementOrgAccessCheck_5`
-
-Returns whether the org has Health Engagement enabled AccessCheck enabled. SIDE EFFECT: when access is denied AND `IndustriesSettings.OrgPreferences.empowerHealthEngagement` is currently true, force-resets the pref to false (controller line 119). AURA-IS-CANONICAL — the self-heal is server-enforced; no Metadata/Tooling read replicates it.
-
-**Call:** `GET /headless/invoke/industries/industries-healthcare/health-engagement-setup/get-empower-health-engagement-org-access-check`   — status: `implemented`
-
-**Output:** boolean — true when the org has `Health Engagement enabled` access. False also indicates the side-effect auto-reset of the empowerHealthEngagement pref to false has fired this call.
-
-#### `getOutboundHealthEngagementPref_2`
-
-Returns the current boolean state of `IndustriesSettings.OrgPreferences.outboundHealthEngagement`. AURA-IS-CANONICAL — Metadata API retrieve of `IndustriesSettings` operates at XML-deploy/retrieve granularity over the whole Settings type, not a single-pref read; no sObject column exposes this org pref directly.
-
-**Call:** `GET /headless/invoke/industries/industries-healthcare/health-engagement-setup/get-outbound-health-engagement-pref`   — status: `implemented`
-
-**Depends on:** `getOutboundHealthEngagementOrgAccessCheck_4`
-
-**Output:** boolean — current value of `IndustriesSettings.OrgPreferences.outboundHealthEngagement`.
-
-#### `getEmpowerHealthEngagementPref_3`
-
-Returns the current boolean state of `IndustriesSettings.OrgPreferences.empowerHealthEngagement`. AURA-IS-CANONICAL — Metadata API retrieve of `IndustriesSettings` operates at XML-deploy/retrieve granularity over the whole Settings type, not a single-pref read; no sObject column exposes this org pref directly.
-
-**Call:** `GET /headless/invoke/industries/industries-healthcare/health-engagement-setup/get-empower-health-engagement-pref`   — status: `implemented`
-
-**Depends on:** `getEmpowerHealthEngagementOrgAccessCheck_5`
-
-**Output:** boolean — current value of `IndustriesSettings.OrgPreferences.empowerHealthEngagement`.
-
-#### `toggleOutboundHealthEngagementPref_6`
-
-Sets `IndustriesSettings.OrgPreferences.outboundHealthEngagement` to the request body `value` (controller line 135). Throws `AuraHandledException` with the localized `OutboundHealthEngagementNoAccessMessage` label when Outbound Health Engagement feature AccessCheck is denied; emits a PFT `proactiveEngagement.enabled` / `.disabled` telemetry event on success. AURA-IS-CANONICAL — Metadata API `IndustriesSettings.enableOutboundHealthEngagement` deploy drops the per-call AccessCheck enforcement, the localized error contract, and the PFT emit, and is not supported in scratch org definitions.
-
-**Call:** `PATCH /headless/invoke/industries/industries-healthcare/health-engagement-setup/toggle-outbound-health-engagement-pref`   — status: `implemented`
-
-**Inputs:**
-
-- `value` *(`boolean`)*
-
-**Depends on:** `checkUserHasEditPermission_1`, `getOutboundHealthEngagementOrgAccessCheck_4`, `getOutboundHealthEngagementPref_2`
-
-#### `toggleEmpowerHealthEngagementPref_7`
-
-Sets `IndustriesSettings.OrgPreferences.empowerHealthEngagement` to the request body `value` (controller line 150). Throws `AuraHandledException` with the localized `EmpowerHealthEngagementNoAccessMessage` label when Health Engagement enabled AccessCheck is denied; emits a PFT telemetry event on success. AURA-IS-CANONICAL — Metadata API `IndustriesSettings.enableEmpowerHealthEngagement` deploy drops the per-call AccessCheck enforcement, the localized error contract, and the PFT emit, and is not supported in scratch org definitions.
-
-**Call:** `PATCH /headless/invoke/industries/industries-healthcare/health-engagement-setup/toggle-empower-health-engagement-pref`   — status: `implemented`
-
-**Inputs:**
-
-- `value` *(`boolean`)*
-
-**Depends on:** `checkUserHasEditPermission_1`, `getEmpowerHealthEngagementOrgAccessCheck_5`, `getEmpowerHealthEngagementPref_3`
-
-### Verify operations
-
-#### `verify-toggleOutboundHealthEngagementPref_6`
-
-Read back via `getOutboundHealthEngagementPref` to confirm the toggle wrote the requested value to `IndustriesSettings.OrgPreferences.outboundHealthEngagement`. The toggle returns `void`, so a verifying read is the only post-write confirmation.
-
-**Call:** `GET /headless/invoke/industries/industries-healthcare/health-engagement-setup/get-outbound-health-engagement-pref`
-
-**Depends on:** `toggleOutboundHealthEngagementPref_6`
-
-**Output:** boolean — should match the value passed to the preceding toggle call.
-
-#### `verify-toggleEmpowerHealthEngagementPref_7`
-
-Read back via `getEmpowerHealthEngagementPref` to confirm the toggle wrote the requested value to `IndustriesSettings.OrgPreferences.empowerHealthEngagement`. The toggle returns `void`, so a verifying read is the only post-write confirmation.
-
-**Call:** `GET /headless/invoke/industries/industries-healthcare/health-engagement-setup/get-empower-health-engagement-pref`
-
-**Depends on:** `toggleEmpowerHealthEngagementPref_7`
-
-**Output:** boolean — should match the value passed to the preceding toggle call.

package/skills/industries-home-health-agentforce-setup-configure/SKILL.md

@@ -1,131 +0,0 @@
----
-name: industries-home-health-agentforce-setup-configure
-description: "Enable Agentforce/Einstein GenAI platform toggles and build the Home Health agent (with its subagent), optionally grounded on a Data Cloud data library, plus the Voice Call layout and care-coordinator entity-access permission set. Triggers on \"set up Agentforce for Home Health\", \"build the Home Health agent\", \"enable Einstein GenAI for Home Health\", or as a delegation target from `home-health-guided-setup` Phase 13."
-metadata:
-  relatedSkills:
-  - agentforce-generate
-  version: "1.0"
-  cliTools:
-  - tool:
-    - "jq"
-    semver: ">=1.6"
-  - tool:
-    - "sf"
-    semver: ">=2.0.0"
----
-
-# Home Health — Agentforce Setup
-
-Child skill extracted from `home-health-guided-setup` Phase 13 (`[enablement toggles + layout + perms automate; agent build + subagent + data library are headlessly automatable on a Data-Cloud-provisioned org; only Voice steps are blocked by org provisioning and a narrow prompt-action publish-500]`) · gated by `HealthCloud.orgHasHomeHealthAgentWithoutGenAI` — only run this phase once real Agentforce/Einstein agents are in scope for the customer.
-
-**CANONICAL EXECUTION SEQUENCE for this phase (follow in this order):**
-
-1. **Enable the settings first.** Run **Step 0** (the four `Einstein Generative AI` platform toggles) — it turns on the Agentforce platform itself and is the prerequisite for everything downstream; check `EinsteinGptSettings.enableEinsteinGptPlatform` state from Phase 0 first (if already on from an earlier phase, Step 0 is idempotent). Then run **Step 1** (`EnableAgentPref`, the HC-specific `healthCloudGenAIPref`). These are the enablement toggles — do them before any agent authoring.
-2. **Create the default agent.** Step 0's toggles #3/#4 (`AgentPlatformSettings.enableAgentPlatform` + `EinsteinCopilotSettings.enableEinsteinGptCopilot`) activate the built-in **Agentforce (Default) Agent** — the org's `Copilot_for_Salesforce` `BotDefinition` (`Type=InternalCopilot`) flips its `BotVersion.Status` to `Active`. Confirm it is Active (`SELECT Status FROM BotVersion WHERE BotDefinitionId=<the InternalCopilot BotDefinition Id>` → `Active`) before building the HH agent.
-3. **Create the Home Health agent with its subagent.** Run **Step 4** — build the HH agent + its `PatientHomeHealthcareMgmt` subagent end-to-end and automatically. It depends ONLY on Step 0's toggles, NOT on steps 1–3 (SCV/contact-center, which are org-provisioning-gated) and NOT on Data Cloud (that gates only step 5's library grounding). Do not defer Step 4 to manual just because the SCV/Bot-legal-terms paths are blocked; those are separate dependency chains.
-4. **Check Data Cloud enablement.** Data Cloud is required ONLY if the customer wants to set up a data library (Step 5) to ground the agent — it is NOT needed for anything above. Probe provisioning via the data-library prerequisites check / the Data-Cloud-enabled check (see Step 5).
-   - **If Data Cloud is NOT enabled →** do NOT block or fail silently on the whole phase. **Prompt the user** that Data Cloud must be enabled/provisioned in order to set up the data library, then **continue to the next phase (or any other pending steps in this phase — e.g. steps 6/7)** without the library. An empty `rag_feature_config_id` is the correct end state on a non-Data-Cloud org; the agent built in step 3 is already fully active without it.
-   - **If Data Cloud IS enabled →** proceed to **Step 5** and **ask the user, in interaction mode, how to set up the data library** — which library grounds which agent (create a new library vs attach an existing one, its name/source). Do not fabricate the library or its grounding target.
-
-**Group 13 scorecard:** `EnableAgentPref` ✅ automate (headless preference-set action) · `CreateContactCenter` ❌ NOT-here — SCV OrgProvisioning gate (statusCode 216), EXTERNAL-TD/customer AWS · `AssignContactCenter` ⚠️ mechanism confirmed (`User.CallCenterId` PATCH) but blocked in SCV context by step 2, `[data — ask users]` · `AssignHomeHealthTopic` ✅ automate END-TO-END, run INDEPENDENTLY right after Step 0 (no `[ask]` gate) — a fresh agent + its `PatientHomeHealthcareMgmt` subagent built, published, and set **Active** via the `sf agent` CLI (preferred) or `POST /nextgen-authoring/bundles` (note: NO `/connect` prefix); the sole residual is a narrow `generatePromptResponse://` prompt-action publish-500 (a filed platform defect, `-306402626`) → that action falls through to Agent Builder. Proven on an org with no Data Cloud, no `industries_hls_einstein` package, and Bot-legal-terms unaccepted. · `DataCloudLibraryAssignAgent` ✅ automate — a grounding library can be created (`POST /einstein/data-libraries` 201) and grounded on the agent (`assignLibrary` 200) on a Data-Cloud-provisioned org; a 501/500 on an unprovisioned org is a Data-Cloud **provisioning** gap, not an API gap; `[ask]` which library grounds which agent · `VoiceCallPageLayout` ✅ automate (classic Layout Tooling PATCH) · `SetupAgentEntityAccess` ⚠️ mechanism confirmed (PermissionSet+ObjectPermissions Data API) but VoiceCall excluded from perms picklist, `[data — ask permset/entities]`.
-
-Group 13 (`AgentforceSetup`), 7 steps:
-
-**Step 0 — Agentforce platform enablement (three required platform toggles; Bot Settings is NOT one of them) `[automate — MDAPI Settings deploy; end-to-end]`.** Before any agent authoring (steps 4–5) can happen, the org's Agentforce platform must be turned on. In the Setup UI this is a chain of toggles under **Einstein Generative AI** that must be flipped **in dependency order** — and the later ones only become available *after* the earlier ones are on. The three **required** ones (#1, #3, #4 below) are headless via a single/sequenced **Metadata API `Settings` deploy** (a Metadata API deploy of `settings/*.settings-meta.xml` (the `/headless/metadata` path)), NOT the discovery-feature API (there is **no** `agentforce`/`einstein-*` discovery feature — every candidate name returns `NOT_FOUND`) and NOT a Tooling PATCH. ⚠️ **`BotSettings.enableBots` (listed below as "opt" for context) is NOT a prerequisite for building the Employee (`InternalCopilot`) agent this skill produces — the agent publishes + activates with `enableBots=false`. Do NOT include it in the required enablement set, and do NOT block Step 0 or Step 4 if it can't be turned on.** Deploy the three required toggles in this order (each `Succeeded`, each re-retrieved to confirm persistence):
-
-   | # | Setup UI toggle | Settings type · field → value | Notes |
-   |---|---|---|---|
-   | 1 | Einstein Generative AI Platform | `EinsteinGptSettings.enableEinsteinGptPlatform = true` | master switch — **must be first** (the one hard-proven ordering dependency) |
-   | opt | Agents/Bots runtime | `BotSettings.enableBots = true` | ⚠️ **NOT A PREREQUISITE — skip it for the default (Employee/`InternalCopilot`) agent.** Only needed if you deliberately build the optional *service/messaging* variant (`EinsteinServiceAgent`, patient-facing Messaging/voice, bound to the Messaging channel). Deploying it can fail `Error: Bot — "Legal Terms acceptance and/or necessary feature dependencies required to enable Bot Settings"` — a MANUAL one-time Einstein Bots legal-terms acceptance in Setup (`/lightning/setup/EinsteinBots/home`) with no API/MDAPI/discovery lever. Agent publish + activate succeed to a `Type=InternalCopilot` `BotDefinition` with `enableBots=false`. Never gate the build on this toggle. |
-   | 3 | Agentforce Studio → **Agentforce Agent** | `AgentPlatformSettings.enableAgentPlatform = true` | the Studio agent toggle — flip it **before** Agent availability (matches the UI order the admin walks) |
-   | 4 | Agentforce → **Agent availability** | `EinsteinCopilotSettings.enableEinsteinGptCopilot = true` | the "turn on Agent availability" toggle — comes last |
-
-   > **Ordering note (honest provenance):** only #1 (`enableEinsteinGptPlatform`) has been confirmed to hard-require coming first — the remaining toggles all deploy successfully as independent MDAPI writes, so a strict server-side dependency between #3 and #4 has **not** been established. The #3-before-#4 order above follows the **Setup UI flow** (Agentforce Studio agent, then Agent availability), which is the order to prefer. If a future run finds one toggle rejects because another isn't on yet, that's the real dependency signal — reorder to satisfy it and update this table.
-
-   - ⚠️ **`EinsteinAgentSettings` is a decoy — do NOT touch it.** `EinsteinAgentSettings` (fields `einsteinAgentRecommendations`/`summarizationCopilot`/…) is the **legacy Service-Cloud "Einstein Agent" recommendations** feature, unrelated to Agentforce. Its `enableEinsteinAgent`-style guesses fail deploy (`Element enableEinsteinAgent invalid at this location`). The four real types are exactly `EinsteinGptSettings`, `BotSettings`, `EinsteinCopilotSettings`, `AgentPlatformSettings`.
-   - ⚠️ **Don't guess type names — enumerate them.** `Agentforce`, `AgentforceStudio`, `GenAiSettings`, `GenAiAgent`, `CopilotSettings` are all **invalid** and are *silently dropped* on retrieve (no error, just missing files — the failure mode that wastes a cycle). Discover the org's real Settings subtypes first: `sf org list metadata --metadata-type Settings --json | jq -r '.result[].fullName'` (surfaces `Bot`, `EinsteinGpt`, `EinsteinCopilot`, `AgentPlatform`, etc.).
-   - ⚠️ **mdapi-dir vs source-format filename.** A source-format deploy uses `settings/EinsteinGpt.settings-meta.xml`; a raw `--metadata-dir` mdapi deploy needs the file named `settings/EinsteinGpt.settings` (dropping `-meta.xml`) or it fails "associated settings metadata is missing from the settings folder." Prefer the source-format Metadata API deploy of the `settings/` folder (proven).
-   - **Verify by OBJECT ACCESSIBILITY, not a settings read** (the reliable signal — same philosophy as the FSL package-presence gate). Before enablement, `GET /sobjects/<obj>/describe` for `BotDefinition`, `GenAiPlannerDefinition`, `GenAiPluginDefinition`, `GenAiFunctionDefinition` all return `NOT_FOUND`. The Agentforce **platform** toggles (#1, then #3 + #4) bring them online — `BotDefinition` + `GenAiPlannerDefinition` first, then `GenAiPluginDefinition` + `GenAiFunctionDefinition`. **`enableBots` (the "opt" row) is NOT what makes these describable/createable** — the full `BotDefinition` (`Type=InternalCopilot`) + `GenAiPlannerDefinition` + `GenAiPluginDefinition` set can be created and activated with `enableBots=false`. (`GenAiPlugin` — the runtime-instance object — stays `NOT_FOUND`; the metadata-authored variant is `GenAiPluginDefinition`, so that's expected, not a failure.)
-   - **The "Agentforce (Default) Agent" toggle in Agentforce Studio is NOT a settings flag — it's the activation state of the built-in default agent.** Enabling the Studio-agent + Agent-availability toggles (#3/#4) is what turns it on; the org's built-in `Copilot_for_Salesforce` agent (`BotDefinition` `Type=InternalCopilot`) has its `BotVersion.Status` flip to `Active`. Verify with `SELECT Status FROM BotVersion WHERE BotDefinitionId=<the InternalCopilot BotDefinition Id>` → `Active`. Don't hunt for a `Settings` field behind it — there isn't one (`EinsteinCopilotSettings` carries exactly one field).
-   - **Relationship to step 1 below and the `setPrefs` note:** step 1 (`EnableAgentPref`) is the HC-specific `healthCloudGenAIPref`; toggles #3/#4 here (`AgentPlatformSettings.enableAgentPlatform` + `EinsteinCopilotSettings.enableEinsteinGptCopilot`) are the same two platform prefs the standing-changes note documents via the agent-preferences set action (`ORG_PREFERENCE_AGENT_PLATFORM_ENABLED` + `ORG_PREFERENCE_EINSTEIN_GPTCOPILOT_ENABLED`) — the **MDAPI `Settings` deploy here is the reliable cross-org path** (works even when the Aura controller/UI toggle isn't wired), and it additionally covers `enableEinsteinGptPlatform` (plus `enableBots` *if* you're building the optional messaging variant — otherwise skip it). Prefer this deploy chain; fall back to the preferences-set action only if a deploy channel isn't available.
-   - ⚠️ **Enablement ≠ entitlement.** These toggles turn the feature *on*; actual agent *execution* (LLM calls at runtime) still depends on the org carrying the **Agentforce / Einstein GenAI license entitlement**. If it's absent the objects exist but runtime invocation fails — surface that to the admin rather than claiming end-to-end readiness. Standing ON (the platform toggles you deployed persist — #1/#3/#4, plus `enableBots` only if you enabled the optional messaging variant; disclose, don't clean up).
-
-1. `EnableAgentPref` `[automate — headless]` — org link: `/lightning/setup/PackageToCoreSettings/home`; help doc: https://sfdc.co/HomeHealthAgentforce. Reclassified from `[manual]`. Controller `PackageToCoreSetupController` via `/headless/invoke`: read `getPreference` `params_schema:[{"name":"orgPref","type":"String"}]` body `{"orgPref":"healthCloudGenAIPref"}`; write `setPreference` (adds `{"name":"value","type":"boolean"}`) body `{"orgPref":"healthCloudGenAIPref","value":true}` → 200. Read back to confirm the flip persisted. GOTCHA: `isPackageEnabled` is `false` when the legacy HealthCloud managed package isn't installed, so the Setup UI may not even render this toggle — but the **API write persists regardless of UI-visibility gating**. ⚠️ Standing change — leave ON.
-2. `CreateContactCenter` `[NOT automatable here — blocked by SCV OrgProvisioning gate]` — org link: `/lightning/setup/ServiceCloudVoice/home`; help doc: https://sfdc.co/HomeHealthServiceCloudVoice. Even when the `ServiceCloudVoicePsl` license is active with free seats, a real SCV contact center can't necessarily be created: the SCV-enabled-toggle action over `/headless/invoke` can return 200 with embedded `OrgProvisioning:{statusCode:216,"Failed Org Status Check Fatal Error",success:false}` and `CreateContactCenter actionable:false`; a direct contact-center-create call can 500 "Make sure … Salesforce Voice is turned on." The gate is **AWS-side org provisioning**, not license. NOTE: the bare classic `CallCenter` sObject IS Data-API createable (`POST /sobjects/CallCenter` → 201) but that's an empty shell with no telephony wiring — not the wizard's deliverable. GOTCHA: `CallCenter` is metadata-backed — Data API creates it but only Metadata API `deleteMetadata` (type `CallCenter`) can delete it (`deletable=false` on Data/SOAP). → EXTERNAL-TD / customer AWS Connect provisioning.
-3. `AssignContactCenter` `[data — ask which users; mechanism = User.CallCenterId PATCH; blocked in SCV context by step 2 gate]` — org link: `/lightning/setup/ServiceVoiceContactCenters/home`; help doc: https://sfdc.co/HomeHealthContactCenter. The classic assignment join is `User.CallCenterId` — `PATCH /sobjects/User/<id> {"CallCenterId":<CallCenter Id>}` → 204; read back to confirm, revert to null if this was just a mechanism check. The SCV-native path (`addUsersToContactCenter`) → 500 "…Salesforce Voice is turned on" against a real CallCenter Id (needs a truly SCV-provisioned center, i.e. step 2 must clear first); the native-CCaaS variant (the queue-backend user-assignment action) → 403 ACCESS_DENIED (wrong path). So the assignment MECHANISM is confirmed, but meaningful use is gated on step 2. WHICH users = ask.
-4. `AssignHomeHealthTopic` `[automate — run INDEPENDENTLY, immediately after Step 0; build the agent + its subagent end-to-end without an [ask] gate]` — org link: `/lightning/setup/EinsteinCopilot/home`; help doc: https://sfdc.co/HomeHealthAgentTopics.
-
-   🚨 **DATA CLOUD IS NOT REQUIRED TO CREATE THE AGENT. Building + publishing + activating the Home Health agent and its subagent does NOT depend on Data Cloud in any way.** Proven on an org that has **no Data Cloud provisioned at all** — the agent (`Home_Health_Agent`) built, published, and reached `BotVersion.Status:Active` with the `PatientHomeHealthcareMgmt` subagent + router bound to the active planner. **The ONLY thing Data Cloud gates is step 5 (grounding the agent on a data *library*)** — on an org without Data Cloud, `knowledge.rag_feature_config_id` simply stays empty and `AnswerQuestionsWithKnowledge` has no library to retrieve from; the agent itself is fully built and active. An empty `rag_feature_config_id` is the CORRECT end state on a non-Data-Cloud org, **not** a build failure. Do NOT defer or block Step 4 on Data Cloud (nor on SCV, the Bot-legal-terms gate, or the `industries_hls_einstein` package — none are required).
-
-   **EXECUTION RULE: once Step 0's three required platform toggles (#1, #3, #4 — NOT `enableBots`) are on, build the Home Health agent (`Home_Health_Agent`) with its subagent automatically — do NOT block on an `[ask]` for whether to build, and do NOT wait on `enableBots` (it's optional; see Step 0). Default to creating a fresh HH agent; only OPTIONALLY confirm a non-default agent name/label. This step is independent of steps 1–3 (SCV/contact-center), independent of the Bot Settings legal-terms gate, and independent of Data Cloud provisioning (that gates only step 5's library grounding).** A **shipped HH agent template exists**: the agent-templates listing action returns `HH Next Scheduler` (`industries_hls_einstein__HHNextScheduler`, full agentScript with HH topics HHSchedulerOrchestrator/ManualExecution/SOCExecution/AutoRecurringExecution). The topic-assignment mechanism (the local/agent-topics create actions) is real and callable but needs a target `agentVersionId`. GOTCHAS: legacy `createCopilotFromTemplate` → 500 "template not found" (it's the old Copilot model; the Next-Gen agent-authoring surface has no create-from-template method exposed — only `createBundleWithVersion`/`createDraftBundleVersion` taking a full bundle input). A fresh org typically has no pre-seeded HH agent to target — build a new one rather than assuming an existing HH agent exists. **Agent identity (optional confirm only — do NOT gate the build on it):** default to a fresh agent named `Home_Health_Agent`; if the customer names an existing agent to attach the HH topics to instead, use that. Do not invent a different agent identity, but do not wait on this answer to proceed with the default.
-
-   **Building an agent WITH the HH subagent from scratch — end-to-end automatable, and CONFIRMED to NOT require Data Cloud provisioning or the `industries_hls_einstein` package.** (Expected end state on an org without those two: agent `Home_Health_Agent`, BotVersion `Status:Active`, the subagent `PatientHomeHealthcareMgmt` present + active.) The earlier "Data-Cloud-provisioned org" caveat on this step applies ONLY to the separate data-library-grounding step below (step 5) — **the agent-plus-subagent build/publish/activate path itself has NO Data Cloud dependency whatsoever; never block, defer, or mark this step manual on Data Cloud status.**
-
-   ✅ **THE PUBLISH GATE IS THE AGENT *TYPE*, NOT `enableBots` (holds end-to-end with `enableBots=false`).** An Agentforce agent's root record is a `BotDefinition`, but its **`Type`** depends on the `.agent` `config.agent_type`. Build it as an **Employee agent** and it publishes + activates freely with Bots off:
-   ```text
-   config:
-       agent_label: "Home Health Agent"
-       agent_template: "EmployeeCopilot__AgentforceEmployeeAgent"
-       developer_name: "Home_Health_Agent_Emp"
-       agent_type: "AgentforceEmployeeAgent"
-   model_config:
-       model: "model://sfdc_ai__DefaultGPT54"
-   ```
-   → produces a `BotDefinition` with `Type=InternalCopilot`, which is **not** legal-terms-gated. **If you OMIT `agent_type`, or leave a `messages:` (welcome/error) block or `@MessagingSession.*` linked variables in the blueprint, it compiles to an `EinsteinServiceAgent`** (patient-facing Messaging/voice agent) — and *that* type is what (a) validation-errors `INVALID_API_INPUT "Default agent user is required for the agent type EinsteinServiceAgent"` and (b) requires `enableBots=true` + the one-time Einstein Bots legal-terms acceptance because it binds to the Messaging channel. So: for the default HH agent build, use the Employee `agent_type` above and DROP the `messages:` block and all messaging linked vars (the voice-call subagent `PatientHomeHlthcrMgmtVoiceCall` is out of scope and is never built) — then publish/activate need no Bot legal terms. Only build the `EinsteinServiceAgent` variant (and accept the legal-terms hand-off) if a patient-facing Messaging/voice channel agent is explicitly wanted.
-
-   **Recipe — create bundle → assemble afscript → patch draft → publish → activate:**
-   1. `POST /nextgen-authoring/bundles` with a flat body `{"label":"Home Health Agent","apiName":"Home_Health_Agent"}` → 201, returning `{bundleId, id:<draftVersionId>, apiName:"Home_Health_Agent_1", versionStatus:"DRAFT", ...}` (server auto-suffixes `apiName` on collision — don't pass `agentTemplate`, it 400s `JSON_PARSER_ERROR "Unrecognized field"`).
-   2. Assemble the afscript = a base Employee-agent afscript (e.g. pull one via `GET /nextgen-authoring/bundle-versions/<id>` off any existing Employee-agent bundle/draft) + the 2 subagent blocks (`topicAFScript` + each subagent's `actions:` block — the full `PatientHomeHealthcareMgmt` subagent YAML, including their `AnswerQuestionsWithKnowledge`/`IdentifyRecordByName`/`QueryRecords`/`GetRecordDetails`/`SummarizePatientHomeHlthcrDtl` actions) + a `go_to_PatientHomeHealthcareMgmt` router transition added to `agent_router.reasoning.actions` alongside the existing `go_to_ambiguous_question` anchor.
-   3. `PATCH /nextgen-authoring/bundle-versions/{draftId}` with body `{"assets":[{"resourceName":"definition.agent","resourceType":"agentDefinition","resourceContent":"<full afscript string>"}]}` → 204. Read back with a fresh GET to confirm the content persisted (it's a real overwrite, not a merge). ✅ **`resourceContent` can be the raw `.agent` DSL string verbatim** (the same file `sf agent validate` compiles) — no separate "afscript" transpile step is required for the PATCH; the server accepts the `.agent` content under `resourceType:agentDefinition`, and the read-back returns the full asset. Create (201) + PATCH (204) + read-back all succeed with **only the session access token** — no OAuth refresh, no external gateway.
-   4. `POST /nextgen-authoring/bundle-versions/{draftId}/publish` → 201 `{publishedBotId, publishedBotVersionId}`.
-   5. `POST /nextgen-authoring/bundle-versions/{draftId}/activate` → 204.
-   6. Verify independently: fresh `GET /nextgen-authoring/bundle-versions/{draftId}` → `versionStatus:"PUBLISHED"`, `targetStatus:"ACTIVE"`; fresh Data-API query `SELECT Status FROM BotVersion WHERE Id='<publishedBotVersionId>'` → `Status:"Active"`.
-
-   ⚠️ **A PUBLISH-TIME `INSUFFICIENT_ACCESS` OR `EinsteinServiceAgent` VALIDATION ERROR ALMOST ALWAYS MEANS THE BLUEPRINT COMPILED TO A *SERVICE* AGENT — FIX THE `agent_type`, DON'T CHASE `enableBots`/permsets/entitlement.** Two symptoms, one cause: (a) `publish` → `[{"errorCode":"INVALID_API_INPUT","message":"…Default agent user is required for the agent type EinsteinServiceAgent"}]`, or (b) an older run's `[{"errorCode":"INSUFFICIENT_ACCESS","message":"…User doesn't have access to agent."}]`. Both come from a blueprint that carries a `messages:` (welcome/error) block, `@MessagingSession.*`/`@MessagingEndUser.*` linked variables, or an omitted `agent_type` → the server classifies it as an `EinsteinServiceAgent` (Messaging channel), which needs `enableBots=true` + the Einstein Bots legal terms. **The fix is NOT to enable Bots — it's to rebuild the draft as an Employee agent** (add `config.agent_type: "AgentforceEmployeeAgent"` + `agent_template: "EmployeeCopilot__AgentforceEmployeeAgent"` + a `model_config`, and strip the `messages:` block / voice subagent / messaging linked vars — see the config snippet above). Re-PATCH the same draft and re-publish: it lands a `Type=InternalCopilot` `BotDefinition` and activates with `enableBots=false`. Assigning more permsets does nothing (proven: an org with `CopilotSalesforceAdmin` + `CopilotSalesforceUser` + `EinsteinGPTCopilotPsl` still failed while the blueprint was a service agent). Only if a patient-facing **Messaging/voice** agent is explicitly wanted do you actually need `enableBots=true` — see the legal-terms hand-off note below.
-
-   📋 **ONLY IF THE `EinsteinServiceAgent` (Messaging/voice) VARIANT IS EXPLICITLY REQUIRED — hand off the one-time legal-terms click, then resume automatically.** Deploying `BotSettings.enableBots=true` fails `Error: Bot — "Legal Terms acceptance and/or necessary feature dependencies required to enable Bot Settings"`, and on an org where the headless proxy is unwired there is NO API/MDAPI/Setup-Discovery lever (all three confirmed dead: controller `NOT_IMPLEMENTED`, no `einstein-bots` discovery feature, MDAPI deploy is itself the gated action). The executor must NOT auto-accept it — it's a personal "I'm authorized by my company to accept these terms" attestation — and must not drive it via a scripted browser session. Prompt text to use:
-   > *"You've asked for a patient-facing Messaging/voice agent, which runs on Einstein Bots. Turning Bots on requires a one-time legal-terms acceptance that only you can make. In Setup, open **Einstein Bots** (`/lightning/setup/EinsteinBots/home`), check **‘I'm authorized by my company to accept these terms’**, and click **‘Try Einstein’**. Tell me once done and I'll finish automatically — enabling Bots and publishing + activating the Messaging agent (already staged). (The Employee-facing Home Health agent is already built and needs none of this.)"*
-
-   After acceptance: deploy `BotSettings.enableBots=true` (now succeeds), then publish + activate the service-agent draft via the REST chain. **This is an OPTIONAL variant, not the default HH agent path** — the Employee agent is built with zero human action. **This org-side gate is a different failure from the external-gateway 404 below** — reaching a publish/validation response at all is proof the correct org-domain REST mechanism was used.
-
-   ⚠️ **ENDPOINT PATH — the resource is `/services/data/vXX.0/nextgen-authoring/bundles`, with NO `/connect` prefix.** `POST /services/data/vXX.0/connect/nextgen-authoring/bundles` → `NOT_FOUND` (this is a common false-negative that reads like "capability absent" — it's just the wrong path). The correct flat-body POST returns 201 with the auto-suffixed `apiName` (`Home_Health_Agent` → `Home_Health_Agent_1`). Do NOT treat one `NOT_FOUND` on the `/connect`-prefixed path as a dead end — that mistake once caused this whole step to be wrongly deferred to manual.
-
-   🚨 **MECHANISM CHOICE — prefer the org-domain REST recipe above; the `sf agent` CLI publish routes through an EXTERNAL gateway that 404s on orgs not registered on it (typically scratch / pre-release / internal dev orgs).** `sf agent publish authoring-bundle` bootstraps a JWT and POSTs the compiled bundle to the **external Agentforce SFAP gateway** (`api.salesforce.com/einstein/ai-agent/authoring`, with `test.api.`/`dev.api.` fallbacks). On an org not registered on that public gateway, all three hosts return **404 `AgentApiNotFound`** and **nothing is written to the org** (`BotDefinition` count stays 0) — a failure that looks like "the agent couldn't be created" but is really just the wrong endpoint. The `sf agent validate` step is safe (local compile), but for the actual org write **drive the REST recipe above** (`POST /nextgen-authoring/bundles` → `PATCH …/bundle-versions/{id}` with the `.agent` content → `publish` → `activate`), which stays on the org's own My Domain and works with the session token. Reserve the CLI publish for orgs known to be registered on the SFAP gateway. **Do not conclude "agent build failed" from a `sf agent publish` 404 without first trying the org-domain REST path.**
-
-   **CLI convenience path (only on gateway-registered orgs) — drive the same nextgen-authoring surface via the `sf agent` CLI instead of hand-rolling the REST PATCH/publish/activate.** The CLI transpiles the `.agent` DSL (the sf-skills authoring format), assembles the afscript, and calls the identical nextgen-authoring endpoints — but handles the afscript resource-envelope shape for you (a raw REST `PATCH …/bundle-versions/{id}` with the wrong `resourceType`/`content` field silently fails or `UNKNOWN_EXCEPTION`s). Steps:
-   1. `sf org login access-token --instance-url <url> --alias <alias>` (feed the org access token on stdin) → the token-only login this whole runbook uses.
-   2. Scaffold a Metadata API project with an `aiAuthoringBundles/Home_Health_Agent/` dir holding `Home_Health_Agent.agent` (the afscript — base a knowledge-grounded Employee agent off the sf-skills `agentforce-generate/assets/agents/knowledge-grounded.agent` template; add the router + the `PatientHomeHealthcareMgmt` subagent block, on the `AnswerQuestionsWithKnowledge` RAG path with the prompt action dropped per the platform-defect workaround below) and `Home_Health_Agent.bundle-meta.xml` (`<masterLabel>` + `<bundleType>Agent</bundleType>`). For an Employee agent use `agent_type: "AgentforceEmployeeAgent"` and OMIT the `access:`/messaging linked-variable blocks (gotcha (i)).
-   3. `sf agent validate authoring-bundle --api-name Home_Health_Agent` → `{success:true}`. This is the fast pre-flight — the afscript compiles here before any org write.
-   4. `sf agent publish authoring-bundle --api-name Home_Health_Agent` → **creates the BotDefinition + GenAiPlannerDefinition + both GenAiPluginDefinitions (router + the subagent) on the org.** ⚠️ **KNOWN COSMETIC ERROR:** this command's *final* metadata step can throw `MetadataTransferError: Required field is missing: bundleType` even though the bundleType is set in the meta — but by then the agent, planner, and all topic/subagent definitions are ALREADY created (verify via `SELECT Id,DeveloperName,Type FROM BotDefinition WHERE DeveloperName='Home_Health_Agent'` + `SELECT DeveloperName,MasterLabel FROM GenAiPluginDefinition`). Do NOT treat this error as a build failure; proceed to activate.
-   5. `sf agent activate --api-name Home_Health_Agent` → `{success:true, version:N}`; the latest `BotVersion` flips to `Status:Active`. This finishes what the publish-step's cosmetic error left dangling.
-   6. Verify: `SELECT Id,DeveloperName,Status,VersionNumber FROM BotVersion WHERE BotDefinitionId=<def>` → the newest version `Active`; `SELECT Plugin FROM GenAiPlannerFunctionDef WHERE PlannerId=<active planner>` → 2 rows; the 2 `GenAiPluginDefinition`s (`PluginType:Topic`) are `agent_router` + `PatientHomeHealthcareMgmt`. The subagent renders under **Topics** on the agent's **Active** version in Agent Builder.
-
-   ⚠️ **UI-MASKING GOTCHA — a leftover EMPTY nextgen-authoring draft bundle sharing the agent's `apiName` masks the real active agent's subagent in Agent Builder.** If you (or a prior probe) created a bare `POST /nextgen-authoring/bundles` draft that was never PATCHed/published, Agent Builder can resolve the agent-by-name to that empty shell (no afscript, `publishedBotId:null`) and show **zero subagents** — even though the real active BotVersion's planner has both topics bound. **Fix:** list bundles (`GET /nextgen-authoring/bundles`), find the empty duplicate (`activeBundleVersionId:null` AND `publishedBotId:null` with an empty `latestBundleVersion`), and `DELETE /services/data/vXX.0/nextgen-authoring/bundles/<id>` → 204. Then hard-refresh Agent Builder and open the **Active** version. (When the CLI publish path is used, no such empty draft is created — this gotcha is specific to a hand-rolled REST `POST /bundles` that didn't complete.)
-
-   **Portability gotchas (all fatal on publish/persist if missed):** (i) if the base afscript was authored as a *messaging* agent it carries 5 `@MessagingSession.*` / `@MessagingEndUser.*` linked variables (`EndUserId`, `RoutableId`, `ContactId`, `EndUserLanguage`, `ChannelType`) → publish 400 `INVALID_API_INPUT "The Messaging Session is not a valid entity"`; **strip those 5 linked variables** for an Employee/Copilot agent. (ii) `developer_name` collisions → publish 400 `DUPLICATE_VALUE "BotDefinition duplicates value"`; use a fresh `developer_name` (a failed publish can leave a half-BotDefinition behind, so bump the name on retry). Server auto-suffixes the bundle `apiName` (e.g. `Home_Health_Agent` → `Home_Health_Agent_1`). (iii) **If dropping the prompt action (see limitation below), don't just delete its action binding — rewrite the subagent's `reasoning.instructions` prose too.** The subagent's shipped instructions are a step-by-step script that explicitly says "call the SummarizePatientHomeHlthcrDtl action"; leaving that prose in after removing the action definitions gives the agent instructions it can't execute. Replace those steps with an instruction to answer via `AnswerQuestionsWithKnowledge` (RAG/knowledge-article grounding) instead, and note the summarization/extraction capability is pending the platform fix below.
-
-   ⚠️ **CONFIRMED PLATFORM LIMITATION — prompt-action subagents cannot be published headlessly (a filed platform defect, `-306402626`).** The HH subagent contains a `generatePromptResponse://` PROMPT action (`industries_hls_einstein__summarizePatientHomeHealthcareDetails`). Enabling Einstein for Health Cloud (step 1) **does provision that prompt template** (`TEMPLATE_NOT_FOUND` → `200 Published`), and the afscript **compiles cleanly** (`POST /nextgen-authoring/afscript/compile` v65.0 → 200), BUT **publishing any bundle version containing a `generatePromptResponse://` action returns 500 `UNKNOWN_EXCEPTION` (platform defect `-306402626`)** — this has been reproduced across independent orgs with Data Cloud + templates + full admin access, which rules out permissions/provisioning. This is a **platform-side publish-persistence bug**, filed as a gap. On an org where `industries_hls_einstein` isn't installed at all, the same action is moot regardless — the prompt templates they target don't exist to provision. **Workaround (what actually ships, and is confirmed clean on both an HLS-Einstein-installed org and a non-installed org):** publish the subagent with the PROMPT action dropped (per gotcha (iii) above) — the knowledge/RAG path (`AnswerQuestionsWithKnowledge` + `IdentifyRecordByName`/`QueryRecords`/`GetRecordDetails`) publishes + activates cleanly and carries the data-library grounding; re-add the prompt action via the Agent Builder UI once the platform bug is fixed (and, on a non-HLS-Einstein org, once that package is installed), or hand off that action manually. Everything else in the agent (the topic, router, knowledge grounding, library attach) is fully headless.
-5. `DataCloudLibraryAssignAgent` `[Data-Cloud-GATED — run ONLY if the data library is wanted; check enablement first, then branch: prompt-if-disabled / ask-in-interaction-mode-if-enabled]` — org link: `/lightning/setup/EinsteinCopilot/home`; help doc: https://sfdc.co/HomeHealthDataLibrary.
-
-   🚦 **DATA CLOUD IS REQUIRED ONLY FOR THIS STEP (setting up the data library). Nothing else in Phase 13 needs it.** Do this step ONLY after steps 0/1 (enablement), the default agent (Step 0 toggles #3/#4), and Step 4 (HH agent + its subagent) are done. **First check Data Cloud enablement**, then branch:
-
-   - **CHECK:** probe provisioning — the data-library prerequisites check (→ `true`/`false`) and the Data-Cloud-enabled check, both over `/headless/invoke`. On an UNprovisioned org four calls converge: the prerequisites check→false; `listDataLibraries()`→**501**; the Data-Cloud-enabled check→false; `getAllDataspaces()`→**500**.
-   - **IF DATA CLOUD IS NOT ENABLED →** do NOT silently skip the whole phase and do NOT block the run. **Prompt the user** that Data Cloud must be enabled/provisioned first in order to set up the data library, and that until then the HH agent runs without library grounding (empty `rag_feature_config_id`, which is the correct non-Data-Cloud end state — the agent from Step 4 is already fully active). Then **continue to the next phase, or to any other pending steps in this phase (steps 6/7)** — leave the library for a later run once Data Cloud is provisioned.
-   - **IF DATA CLOUD IS ENABLED →** proceed with the create→attach flow below, but **ask the user in interaction mode how to set up the data library** first: whether to create a new library or attach an existing one, the library name/source, and **which library grounds which agent**. Do not fabricate the library or its grounding target. Only after the user answers, run the mechanism below.
-
-   **PROVISIONING NOTE:** on a Data-Cloud-provisioned org the attach can be exercised end-to-end. **Two paths, both via `AiDataLibraryController` (FQN `AiDataLibraryController`) over `/headless/invoke`:**
-   - **(a) Direct feature-attach.** `assignLibrary` `params_schema:[{"name":"featureName","type":"String"},{"name":"aiRagFeaturePromptContentDevName","type":"String"},{"name":"groundingLibraryId","type":"String"}]`. `featureName` is an `AIGroundingFeatureConfigEnum` — for an Agentforce agent use `COPILOT` (values: SERVICE_REPLIES, EINSTEIN_BOTS, COPILOT, SERVICE_REPLIES_FOR_EMAIL, ARTICLE_RECOMMENDATIONS_FOR_CONVERSATION/_FOR_CASE, EINSTEIN_KNOWLEDGE_CREATION; COPILOT + EINSTEIN_BOTS are multi-instance). ⚠️ **GOTCHA:** passing a planner Id or empty string as `aiRagFeaturePromptContentDevName` → "Could not find AiRagFeaturePromptContent record with devName or Id". FIX: pass the devName in the form **`ARFPC_<groundingLibraryId>`** — the `NGA_DATA_LIBRARY_ID_PREFIX = "ARFPC_"` triggers the create-branch in the library-assignment service, which mints the ARFPC junction record → 200. Read back to resolve the junction to the real library.
-   - **(b) Production planner-bound path (attach-at-publish).** The way the product actually binds a library to a specific agent version: set `knowledge.rag_feature_config_id = "ARFPC_<groundingLibraryId>"` in the agent's afscript (the base afscript ships `knowledge: { rag_feature_config_id: "" }`, wired into the `AnswerQuestionsWithKnowledge` action as `"ragFeatureConfigId"` bound to the `knowledge.rag_feature_config_id` afscript variable), then publish the bundle version. At publish the platform reads that value and attaches the library to the agent's planner, stamping the planner as Parent. This publishes cleanly when the base afscript sets `rag_feature_config_id: "ARFPC_<libId>"`.
-   - **(c) CREATE a data library headlessly.** `POST /einstein/data-libraries` (**v66.0, connect=False**) body `{"masterLabel":"…","developerName":"…","description":"…","fileAdlMode":3,"groundingSource":{"sourceType":"SFDRIVE","groundingFileRefs":[]}}` → 201 returning `{libraryId, status:"IN_PROGRESS", groundingSource:{indexMode:"BASIC"}}`. ⚠️ **Two create gotchas:** (i) `groundingSource` is a polymorphic input — the discriminator key is **`sourceType`** with value **`SFDRIVE`** (NOT `groundingSourceType`, and NOT `SalesforceDrive`); omitting it → 400 `JSON_PARSER_ERROR "missing property 'sourceType'"`, wrong value → 400 "Could not resolve type id". (ii) **Do NOT pass `dataSpaceScopeId`** — supplying any non-default dataspace id (even another existing library's) → 400 `INVALID_REQUEST_STATE "Non-default dataspace is not supported. Only the default dataspace is allowed."`; **omit the field** and the server defaults it. Then attach with path (a). Expected result of the full create→attach chain: a new library gets created → `assignLibrary(COPILOT, ARFPC_<libraryId>, <libId>)` → 200 junction.
-   - ⚠️ **Indexing-stall caveat (external, no headless lever):** the data library's async indexing pipeline (stages DATA_LAKE_OBJECT → DATA_MODEL_OBJECT → SEARCH_INDEX → INDEXING → RETRIEVER; poll `GET /einstein/data-libraries/{id}/status` v66.0) starts at `status: IN_PROGRESS` on create and can stall at `SEARCH_INDEX` for well over an hour (RETRIEVER never activating) — so the *library's queryability* (and thus retrieval-time read-back of the planner binding) may not be confirmable even though the create + attach *writes* succeed (201/200). This is a backend job, not an automation gap. Ask the customer **which data library grounds which agent** before attaching.
-   - **Provisioning is org-specific, NOT a permission issue:** on a fully-provisioned reference org the data-library prerequisites check → `true` and a real library may pre-exist, so create+attach runs clean; on an org without Data Cloud provisioned, the same calls return false/501/500. Same token-only headless calls — the difference is org provisioning, so branch on the prerequisites check and fail-silently when false.
-6. `VoiceCallPageLayout` `[automate — classic Layout Tooling PATCH]` — help doc: https://sfdc.co/HomeHealthVoiceCallPage. Reclassified from `[manual]`. `VoiceCall` is `layoutable=true`; the layout is a classic `Layout` (NOT FlexiPage — same pattern as Group 9 quick actions). Query `Layout WHERE TableEnumOrId='VoiceCall'` to find it (typically named "VoiceCall-Voice Call Layout"). `PATCH /tooling/sobjects/Layout/<id> {"Metadata":<full blob>,"FullName":"VoiceCall-Voice Call Layout"}` → 204; read back to confirm the flipped property, revert to original if this was just a mechanism check. ⚠️ GOTCHA: the PATCH body must contain ONLY `Metadata` + `FullName` — any other top-level field (even mirroring a real column) → 400 `FIELD_INTEGRITY_EXCEPTION`.
-7. `SetupAgentEntityAccess` `[automate-the-mechanism / ask-the-permset+entities]` — org link: `/lightning/setup/PermSets/home`; help doc: https://sfdc.co/HomeHealthCareCoordinatorPermission. `PermissionSet` create + `ObjectPermissions`/`FieldPermissions` create via **Data API** (not Tooling) works for standard HH entities (create a probe permset → 201, grant `Case` + `CareRequest` object perms → 201, read back, clean up → 204 if it was just a mechanism check). ⚠️ **VoiceCall is EXCLUDED from the `ObjectPermissions/FieldPermissions.SobjectType` restricted picklist** — `POST /sobjects/ObjectPermissions {SobjectType:"VoiceCall"}` → 400 `INVALID_OR_NULL_FOR_RESTRICTED_PICKLIST` (not inferable from describe alone); VoiceCall access is controlled purely by Voice licenses/PSLs, not object CRUD. GOTCHA: dependency chains — `CareRequest` perm needs `Case` read first, `Account` needs `Contact` first (else `FIELD_INTEGRITY_EXCEPTION`). No shipped HH permset covers Voice/Agentforce entities (check `ManageHomeHealthPsl`, `ContactCenterAgentforHealthCloud`, all `HcHomeHealth*`) — a new permset must be authored. Which permset/entities/users = **ask**.
-
-## Return contract (for callers delegating to this skill)
-
-Report back a per-step ledger (Step 0, 1, 2, 3, 4, 5, 6, 7 → done / automated-done / blocked-org-provisioning / deferred-data-cloud-not-enabled / awaiting-data) and a single `phase_complete` boolean. `phase_complete: true` requires Step 0, 1, and 4 (platform enablement + the HH agent build) to be terminal — those are the only hard requirements. Steps 2/3 (SCV contact center) terminally report `blocked-org-provisioning` rather than ever converting to `done` on orgs without AWS Connect provisioning — don't hold the phase open on them. Step 5 (data library) terminally reports `deferred-data-cloud-not-enabled` on a non-Data-Cloud org (not a blocker) or `awaiting-data` once Data Cloud is enabled but the admin hasn't yet answered which library grounds which agent. Steps 6/7 are independent automatable mechanisms gated only on `[ask]` for layout content / permset+entities respectively.
-
-## Companion references
-
-- `health-cloud-revan/home-health-guided-setup` — the root orchestrator (full 16-group Home Health wizard) that delegates to this skill.

package/skills/industries-home-health-bundling-policy-create/SKILL.md

@@ -1,50 +0,0 @@
----
-name: industries-home-health-bundling-policy-create
-description: "Create a Home Health appointment bundling policy (`ApptBundlePolicy`) via direct REST create, going further than the wizard's own navigation-only button, with real business rules confirmed before writing. Triggers on \"create Home Health bundling policy\", or as a delegation target from `home-health-guided-setup-get-org-ready` (Phase 2f)."
-metadata:
-  version: "1.0"
----
-
-# Home Health — Create Bundling Policy
-
-Child skill extracted from `home-health-guided-setup` Phase 2f (`[data for real business rules — but the wizard button itself is pure navigation, not automation]`).
-
-Public doc (literal URL, confirmed via Custom Label): `https://sfdc.co/HomeHealthBundlePolicy`.
-
-**No wizard-native executor exists for this step.** Unlike `home-health-create-work-order-record-type` / `home-health-create-scheduling-policy`, the wizard step is a plain navigation button to `/lightning/o/ApptBundlePolicy/home` — none of the wizard's automated setup actions (label get/update, scheduling policy, work-order/budget record types, reschedule-flow toggle, permission validation) touch `ApptBundlePolicy`. The wizard's own button truly does nothing but open the object's list view; the admin creates the record by hand in that UI.
-
-That said, the underlying `ApptBundlePolicy` object is directly REST-creatable — `createAccess="always"`, gated only by Field Service being enabled (i.e. requires `home-health-install-fsl-package` to have run first). So this skill CAN offer to create it via `POST /sobjects/ApptBundlePolicy`, going further than the wizard's own button, as long as the real business rules are confirmed first. Real field values, with the platform's own defaults surfaced (per the show-defaults-then-create pattern):
-
-| Field | Platform default | Nature |
-|---|---|---|
-| `Name` | none — required, unique | **ask** |
-| `Priority` | none — required, unique, must be positive | **ask** |
-| `IsManualBundling` | none (never required) | ask if relevant |
-| `IsAutomaticBundling` | `false` | present as default, let admin override |
-| `LimitAmountOfBundleMembers` | `50` (valid range 2–200, server-enforced) | present as default, let admin override |
-| `LimitDurationOfBundle` | none (non-negative if set) | ask |
-| `BundleStartTimeFieldName` / `BundleEndTimeFieldName` | none — enum of `ServiceAppointment` datetime fields (e.g. `ServiceAppointment.SchedStartTime` / `SchedEndTime`) | ask, offer the enum's real options via Describe |
-| `IsTimeCalcByBundleDurationFld` | has an insert default, never required in UI | present as default |
-| `ConstantTimeValue` | none (non-negative if set) | ask, only relevant if not calculating from the duration field |
-| `FilterCriteria` | none — FK to a `RecordsetFilterCriteria` | ask if the admin wants filtered bundling |
-| `CanAllowSchleDepndInBundle` | `false` | present as default, let admin override |
-
-Present this table to the admin as: "here are Salesforce's platform defaults for the fields that have one — want to keep them, or change any? Name and Priority are required and I need your real values for those either way." Only call the create once the admin has confirmed or overridden. Never invent `Name`/`Priority` or the start/end-time field choice — those are real business decisions with no platform default.
-
-**Public-doc content note**: the article at `https://sfdc.co/HomeHealthBundlePolicy` could not be independently read for this skill (Salesforce Help returned a loading-error page on fetch, both directly and via the resolved short-link) — the field-level detail above comes from the `ApptBundlePolicy` object definition and its validation rules, not from the article's own text. Still surface the link to the admin — just don't claim the article's content was verified.
-
-## Show-defaults-then-create pattern
-
-Whenever a step has fixed platform default values AND real customer-specific fields in the same create, don't silently pick one path. Discover what the admin has already said this session, present the platform defaults for the rest explicitly, and let the admin confirm or override before the write happens — never create first and explain after. (`home-health-create-scheduling-policy` uses the same pattern.)
-
-## Return contract (for callers delegating to this skill)
-
-Report back the policy record's Id and the final field values used, or `blocked: FSL not installed` if the prerequisite isn't met.
-
-## Companion references
-
-- `health-cloud-revan/home-health-create-scheduling-policy` — Phase 2e leaf — scheduling policy.
-- `health-cloud-revan/home-health-create-work-order-record-type` — Phase 2d leaf — Work Order record type.
-- `health-cloud-revan/home-health-guided-setup-get-org-ready` — Phase 2 orchestrator (sub-steps 2a-2f).
-- `health-cloud-revan/home-health-guided-setup` — the root orchestrator (full 16-group Home Health wizard) that delegates to this skill.
-- `health-cloud-revan/home-health-install-fsl-package` — leaf — FSL managed-package install (Tooling API → Setup Discovery recipe → Salesforce Go).

package/skills/industries-home-health-entity-labels-configure/SKILL.md

@@ -1,29 +0,0 @@
----
-name: industries-home-health-entity-labels-configure
-description: "Surface entity-rename label suggestions for Home Health's renamable entities and hand off the actual rename write to the admin (no CRUD endpoint exists for it). Triggers on \"rename Home Health labels\", \"update entity labels\", or as a delegation target from `home-health-guided-setup-get-org-ready` (Phase 2c)."
-metadata:
-  version: "1.0"
----
-
-# Home Health — Update Entity Labels
-
-Child skill extracted from `home-health-guided-setup` Phase 2c (`[metadata to show, data to decide, manual to write]`).
-
-Wizard step `UpdateLabels` (`action.type: LaunchComponent`, resource `{"name": "healthcloud:renameEntities"}`). Help doc: https://sfdc.co/HomeHealthUpdateLabels.
-
-There is **no CRUD endpoint** for the actual rename write (`CustomObjectTranslation`/`GlobalValueSetTranslation`/`StandardValueSetTranslation`/`RecordTypeTranslation` are all 404 on Tooling Describe; the underlying mechanism is internal Java + PL/SQL with no external write surface). What IS automatable:
-
-1. Read current labels live: `GET /sobjects/<Entity>/describe` → `label`/`labelPlural`, for each of the 13 Home-Health-renamable entities (ServiceAppointment, WorkOrder, WorkPlan, WorkStep, WorkType, ServiceResource, ServiceTerritory, OperatingHours, ResourcePreference, WorkPlanTemplate, ResourceAbsence, ServiceResourceSkill, PartyAppointmentRequest).
-2. Show the admin a table: entity | current label (real, from Describe) | platform's suggested label (fixed reference, not invented).
-3. Ask: keep current / adopt suggested / enter a custom name, per entity or in bulk.
-4. Hand off to the UI for the actual write — this step is entirely **optional** (cosmetic only, no functional impact if skipped):
-   > "This is optional and purely cosmetic — nothing else in this setup depends on it. I can't write the rename myself (no API surface exists for this; it's owned by the Globalization team's Rename Tabs mechanism), but here's exactly what to enter: `<org-instance-url>/lightning/setup/RenameTab/home` (works in any language) or the Home Health 'Update Labels' modal (English-only, faster). Let me know when you're done, or say skip."
-
-## Return contract (for callers delegating to this skill)
-
-Report back which entities the admin chose to rename (and to what), or `skipped` if declined — this step never blocks downstream phases.
-
-## Companion references
-
-- `health-cloud-revan/home-health-guided-setup-get-org-ready` — Phase 2 orchestrator (sub-steps 2a-2f).
-- `health-cloud-revan/home-health-guided-setup` — the root orchestrator (full 16-group Home Health wizard) that delegates to this skill.

package/skills/industries-home-health-fsl-package-deploy/SKILL.md

@@ -1,71 +0,0 @@
----
-name: industries-home-health-fsl-package-deploy
-description: "Install the Field Service (FSL) managed package on a Health Cloud org — the hard prerequisite that gates Home Health's scheduling/optimization steps. Triggers on \"install Field Service package\", \"FSL package install\", \"is FSL installed\", or as a delegation target from `home-health-guided-setup-enable-org-fsl` (Phase 0 step 4 of the Home Health guided setup). Tries a direct Tooling API install first, falls back to a headless Setup Discovery recipe, and only then hands off to the admin via a resolved Salesforce Go link."
-metadata:
-  version: "1.0"
-  cliTools:
-  - tool:
-    - "sf"
-    semver: ">=2.0.0"
----
-
-# Home Health — Install Field Service Managed Package
-
-Leaf skill extracted from `home-health-guided-setup` Phase 0 step 4 (the FSL package install), so it can be delegated to from any phase/skill that needs FSL present — not just re-derived inline each time. `home-health-guided-setup-enable-org-fsl` delegates to this skill rather than inlining the detect/install/poll/fallback logic.
-
-## Guided hand-off contract (applies if every automated path below fails)
-
-Many steps in the Home Health family have no API (managed-package install being the canonical example) — these are **guided manual hand-offs**, not dead ends:
-
-1. **Guide, don't just name it.** Present: (a) what it accomplishes and why it's needed, (b) the exact org-specific link, (c) numbered click-by-click instructions, (d) the public help-doc link.
-2. **State what's blocked behind it.** Tell the caller which later steps can't complete until this lands, and which steps can keep running in parallel meanwhile.
-3. **Wait for the "done" signal**, then **verify, don't trust** — re-run the detect query. If it still fails, say exactly what you looked for and found, and keep waiting.
-4. **On verified success, resume automatically** — don't make the caller re-issue the ask.
-
-**Prerequisite polling.** After handing off manual instructions, re-check the prerequisite on each subsequent turn (treat any response during the wait as a possible "is it ready?"). When it flips to satisfied, announce it ("✅ Field Service package detected — resuming setup") and return control. Do not poll on a timer or fabricate a "still waiting" status.
-
-## Install procedure
-
-**Field Service package install — try the direct package-install API first, then the manual Salesforce Go hand-off if it can't run on this org; ALWAYS surface this proactively.** (wizard step `InstallFieldServicePackage`, `action.type: Manual` in the wizard, but a direct API install path is now proven — see below.) This is a hard gate: run its detection early and, if unmet, attempt the direct API install then ASK the admin (with the resolved Salesforce Go link) only if it can't install on this org; do not assume they know to.
-
-- **Detect first (this is what tells you whether to act):** query installed packages via **Tooling API** — `GET /services/data/vXX/tooling/query?q=SELECT SubscriberPackage.Name, SubscriberPackage.NamespacePrefix FROM InstalledSubscriberPackage`. FSL present = a package with namespace `FSL` (or name containing "Field Service"). A quick corroborating check: `SELECT COUNT() FROM FSL__Scheduling_Policy__c` — a `400 sObject type 'FSL__…' is not supported` means the package is NOT installed. (Note: `InstalledSubscriberPackage` is a **Tooling** object — a Data-API `/query` against it 400s.)
-
-- **Tier orchestration — SEQUENTIAL, never parallel; `IN_PROGRESS` is NOT failure.** FSL install is a long process (commonly 20–30 min). Run the tiers strictly in order and stop at the first one that is accepted:
-  1. Try PRIMARY. If it reports `IN_PROGRESS` (request accepted, not yet done) → **STOP: do NOT also fire SECONDARY** (avoids a double install). Keep polling PRIMARY and return `in-progress` to the caller so it can use the wait productively (see Return contract).
-  2. Only if PRIMARY **errors explicitly** (`Package Not Found`, create 400, or `Status=ERROR`) → try SECONDARY. If SECONDARY is accepted (`201` and status `IN_PROGRESS`) → same: stop, keep polling, return `in-progress`.
-  3. Only if BOTH explicitly error → TERTIARY (Salesforce Go hand-off).
-  - Status meanings: `IN_PROGRESS` = running, keep polling (even if it looks frozen); `SUCCESS`/`ENABLED` = candidate success, **confirm only via the `FSL` namespace in the detect query**; `ERROR`/`NOT_ENABLED` with the namespace still absent = that tier failed.
-  - **Overall polling ceiling ≈ 45 min** from the first accepted install. If `FSL` is still absent after that, treat the in-flight tier as failed and move to the next tier / Salesforce Go. While a tier is `IN_PROGRESS`, poll opportunistically (callers re-check at safe points, see the parent's "while FSL installs" rule) — don't block foreground on it.
-  - During the Salesforce Go manual hand-off keep polling the detect query too; the admin finishing the install flips the state to `installed` without needing a message.
-
-- **PRIMARY: install the FSL managed package directly via the Tooling API `PackageInstallRequest` — token-only, no browser, no admin interaction.** This is the same mechanism Salesforce's own managed-package install flow uses; it just needs a bearer token. Three sub-steps:
-  - **(i) Resolve the latest compatible FSL version id** from the public Salesforce Sites endpoint (no auth): `GET https://d36000000z1fneac.my.salesforce-sites.com/PublicLatestFSL` → take `response.trim().substring(0,15)` (or the full trimmed body — the API accepts the 15- or 18-char id) → the `04t…` `SubscriberPackageVersion` id. This host is the **hardcoded production endpoint** (a fixed platform endpoint, not an org setting), not an org-specific value — it always publishes the current prod-GA FSL version. (The response is a bare `04t…` id; it rotates each FSL release, which is exactly why you fetch it at runtime rather than hardcoding one.)
-  - **(ii) Confirm the org can resolve that version** before attempting the install: `GET /tooling/query?q=SELECT Id,Name,MajorVersion,MinorVersion FROM SubscriberPackageVersion WHERE Id='<04t>'`. A 200 with the record (its `Name` + version, e.g. a named seasonal release) = go; a **`Package Not Found`** error = this org's instance does not have that FSL version published/replicated (see the prod-versioning caveat below) → **skip straight to the headless recipe / manual fallback**, do not attempt the create (it will only 400).
-  - **(iii) Create the install request** (Tooling REST, **omit** the internal `PackageInstallSource` field — it's a SOAP-only enum core sets internally and is not required over REST): `POST /services/data/vXX/tooling/sobjects/PackageInstallRequest` body `{"SubscriberPackageVersionKey":"<04t>","SecurityType":"Full","NameConflictResolution":"Block"}` → `{"id":"0Hf…","success":true}`. Then **poll** `GET /tooling/sobjects/PackageInstallRequest/<id>` reading `Status` (+ `Errors`): `IN_PROGRESS` → keep polling (~20–30 s cadence; FSL takes ~4–15 min), until `SUCCESS` or `ERROR`. On `SUCCESS`, **re-run the detect query** to confirm the `FSL` namespace now appears (authoritative signal — same rule as the recipe path). On `ERROR`, surface `Errors` and fall through.
-  - ⚠️ **Prod-versioning caveat (this is the crux of why the API install "fails" on some orgs).** The `04t` from the endpoint is a **prod-GA** version id; it only resolves on instances where FSL is actually published (real **production / sandbox / test instances**). On a **scratch / pre-release** org, step (ii) returns `Package Not Found` and step (iii) 400s `INVALID_CROSS_REFERENCE_KEY "invalid cross reference id"` — **not a broken call, just an org where the version isn't available.** So the resolve-check in (ii) is the gate: if it fails, this path is unavailable on this org — fall through to the Salesforce Go manual hand-off, don't retry the create.
-
-- **SECONDARY (executed) — the headless Setup Discovery recipe.** When the direct `PackageInstallRequest` can't run on this org (step (ii) `Package Not Found`, or the create/poll errors), **attempt this recipe next — before falling back to the browser.** It installs the FSL managed package headlessly along with the other quickstart steps (org settings, perm sets, console app, profiles). It is environment-gated and does **not** always converge (it can run `IN_PROGRESS → NOT_ENABLED` without installing — see the ⚠️ warning below), which is exactly why it sits *second*, behind `PackageInstallRequest`, and why success is judged solely by the `FSL`-namespace detect query, never by a status flip. The executed order is **`PackageInstallRequest` (primary) → Setup Discovery recipe (secondary) → manual Salesforce Go (tertiary/final)**. Fire the recipe (`POST` → `201 {"success":true}`, status → `IN_PROGRESS`):
-  - `POST /services/data/vXX/connect/setup/discovery/feature/field-service-initial-cloud-setup/enable` with body `{}` — triggers the `fieldServiceQuickstart` recipe (min-version 254). Requires View Setup + Customize Application (System Administrator covers it).
-  - Poll `GET /services/data/vXX/connect/setup/discovery/feature/field-service-initial-cloud-setup/status` until `status` leaves `IN_PROGRESS`. `ENABLED` (and FSL now present via the detect query) = success; re-run the detect query to confirm the `FSL` namespace actually appears before treating it as done.
-  - ⚠️ **Do NOT trust `status` alone — the ONLY authoritative success signal is the `FSL` namespace appearing in the package-detect query.** The recipe is **environment-gated**: on orgs where the FSL `04t` package version isn't available or Field Service isn't licensed, it returns to `NOT_ENABLED` **without** installing. **A clean/empty status body is NOT proof of success** — for example, on an org without Field Service licensing, the recipe can run `IN_PROGRESS → NOT_ENABLED` and leave a *completely clean* status body (`enableBlockedReasons: []`, `dependencyStatuses: []`, `blockedByApexLock: false`) yet installed **no** package; `enableBlockedReasons`/`dependencyStatuses` sometimes surface why (e.g. `ANOTHER_FEATURE_RUNNING` if a prior run is still in flight — re-fire once it clears), but often they're empty even on a no-op.
-  - ⏱️ **Convergence takes real time — a frozen `IN_PROGRESS` is NOT itself failure.** Confirmed on a live orgfarm/pc-rnd test instance: the recipe can sit at `IN_PROGRESS` with `lastStatusUpdate` apparently frozen for **20–30 minutes** before either converging (namespace appears) or genuinely going `NOT_ENABLED`. **Do not conclude "headless path unavailable" before at least 20–30 minutes have elapsed since the fire.** Poll on a ~1–2 min cadence (don't busy-loop) and keep polling through that window — a few minutes of apparent staleness is normal, not a signal. Only once 20–30 min have passed with the `FSL` namespace still absent (whether `status` reads `IN_PROGRESS` or has flipped to `NOT_ENABLED`) should you treat it as "headless path unavailable on this org" and fall through to the manual hand-off. If other non-FSL-dependent setup work is available, keep making progress on that in parallel rather than blocking the whole session on this wait — do not loop indefinitely once the window has elapsed, and never report success on a `status` flip or an empty status body alone.
-
-- **TERTIARY / FINAL FALLBACK (executed only after BOTH API paths above have failed): the manual Salesforce Go hand-off.** If the direct `PackageInstallRequest` can't run on this org (step (ii) `Package Not Found`, or the create/poll errors) **AND** the Setup Discovery recipe also fails to converge (still no `FSL` namespace **after waiting out the full 20–30 min convergence window** per the ⏱️ note above — don't fall back early just because `status` looks stuck), **hand the admin the org-specific Salesforce Go link and wait** (say this, don't wait to be asked). Both API paths (primary + secondary) are gated on the org's instance having the FSL version published/replicated, so when neither resolves on this org, browser install is the remaining route.
-  - 🔴 **MANDATORY — resolve and render the ACTUAL clickable URL; never emit the angle-bracket placeholder and never skip the link.** So **compute it**: take the org's live instance URL (from the session / `sf org display`), replace the `.my.salesforce.com` host suffix with `.my.salesforce-setup.com`, and append `/lightning/setup/page/feature/industries-health-cloud-home-health/home?topic=SalesforceGo`. Present the finished `https://…` URL as a clickable link in the message. **Build it from the connected org — never hardcode a domain.** The transform (generic, using `<mydomain>` only as a stand-in for whatever host the connected org actually has): `https://<mydomain>.my.salesforce.com` → `https://<mydomain>.my.salesforce-setup.com/lightning/setup/page/feature/industries-health-cloud-home-health/home?topic=SalesforceGo`. Read `<mydomain>` from the live session's instance URL at runtime; do not carry any specific org's domain in this skill. (If the instance host doesn't end in `.my.salesforce.com` — e.g. a sandbox `.sandbox.my.salesforce.com` — apply the same `→ .my.salesforce-setup.com`-family substitution for that host form; the point is a real, resolved, clickable link built from the current org, not a placeholder and not a fixed domain.)
-  > "Home Health depends on the **Field Service managed package**, and it isn't installed on your org yet. I tried installing it directly through the API, but this org's instance doesn't have the current FSL package version available to install that way — so the remaining route is the browser. Please install it here (this is the Salesforce Go guided-setup page for your org, which resolves the current package version automatically):
-  > **`https://<yourdomain>.my.salesforce-setup.com/lightning/setup/page/feature/industries-health-cloud-home-health/home?topic=SalesforceGo`** ← *render the org's real resolved URL here per the MANDATORY note above, not this template*
-  > (Alternative: Setup → **Field Service Settings** → toggle Field Service on → **Get Managed Package**; or the AppExchange listing. Background doc: https://sfdc.co/HomeHealthInstallFieldService.) Let me know once it's installed and I'll verify and continue. Meanwhile I can set up everything that doesn't depend on the package."
-
-- **Do NOT fabricate an `apvId`.** The old `…/packagingSetupUI/ipLanding.app?apvId=<version-id>` pattern needs a version Id that **rotates every FSL release** — inventing one risks a stale/wrong version and violates the no-invented-setup-data rule. The Salesforce Go page above (and the Field Service Settings toggle) resolve the current version for the admin, so prefer those.
-
-- **After the admin confirms**, verify via the Tooling query above (namespace `FSL` now present) before reporting success back to the caller.
-
-## Return contract (for callers delegating to this skill)
-
-Report back one of: `installed` (namespace `FSL` confirmed present, state which path — primary/secondary/manual — got it there), `in-progress` (primary or secondary accepted the install and it has not finished; state which tier and the request id / recipe; caller should START Phase 13 (`home-health-guided-setup-agentforce-setup`) now and re-check this skill at safe points — this is NOT a failure), or `awaiting-manual` (both automated tiers failed or the ~45-min ceiling elapsed; Salesforce Go hand-off issued; caller should keep running Phase 13 / non-FSL-dependent work and re-poll this skill — detect-query polling continues during the manual install).
-
-## Companion references
-
-- `health-cloud-revan/home-health-guided-setup-agentforce-setup` — Phase 13 — Agentforce/Einstein enablement and Home Health agent build.
-- `health-cloud-revan/home-health-guided-setup-enable-org-fsl` — Phase 0 — enable Home Health, FSL package, Digital Experience, FSL settings/ESO.
-- `health-cloud-revan/home-health-guided-setup` — the root orchestrator (full 16-group Home Health wizard) that delegates to this skill.