@salesforce/afv-skills 1.63.0 → 1.65.0

package/skills/fsc-stage-management-transitions-configure/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: fsc-stage-management-transitions-configure
+parent: "digital-origination-stage-management-setup"
+purpose: "Build the stage transition map and transition rules that run the Digital Lending Stage Management flow, then activate the transitions."
+description: "Set up the stage transitions for Digital Lending: within the stage definition, define the allowed transitions between application form product stages (Intake to Submitted, In Review to Underwriter Approved, and so on), add a transition rule to each with a step definition of Step Type AutoTask whose FlowDefinitionName is the Digital Lending Stage Management flow (RunAsUser is optional and omitted), and activate the transitions. This is the step that makes the stage field enforce the allowed moves and fire the CDS flow after each change. Created via direct StageTransition / StgFulfillmentStepDefGrp / StgFulfillmentStepDef sObject REST, and never invents the customer's transition map."
+metadata:
+  version: "1.0"
+---
+
+# Digital Origination Stage Management — stage transitions
+
+Define the allowed moves between stages and wire each to the CDS Flow. This is the step that makes the
+`Stage` field enforce valid transitions and that triggers the `Digital Lending Stage Management` Flow
+after each change so CDS re-computes access. This sibling operates inside the stage definition created by
+`stage-definition` and depends on the Flow created by `apex-and-flow`.
+
+Source: Salesforce Help "Set Up Stage Transitions for Digital Lending".
+
+## Prerequisites this sibling depends on
+
+- The `StageDefinition` (`1DL…`) from the `stage-definition` sibling, on `ApplicationFormProduct` / `Stage`.
+- The active `Digital Lending Stage Management` autolaunched Flow from the `apex-and-flow` sibling — the
+  transition rule step definitions bind to it by exact name.
+- The three decision matrices active (the Flow's Apex reads them at runtime).
+
+## Inputs
+
+- Target-org alias and acting admin.
+- The transition map — which stage may move to which. The article's personal-loan example:
+
+  | From stage | Allowed transitions to |
+  |---|---|
+  | Intake | Submitted, Auto Rejected |
+  | Submitted | In Review, Need More Info, Auto Approved, Auto Rejected |
+  | In Review | Need More Info, UW Approved, UW Rejected |
+  | UW Approved | Customer Approved, Customer Rejected |
+  | Auto Approve | Customer Approved, Customer Rejected, Contract Generation |
+  | Customer Approved | Contract Generation |
+  | Contract Generation | Signature Complete |
+
+  Use the admin's transition map — the example is illustrative, not a default. The **one exception is the
+  entry transition `Intake → Submitted`**: because `Intake` is the entry stage every application starts in
+  (see `stage-definition`) and activation requires at least one transition, always define
+  `Intake → Submitted` as the baseline first transition, then layer the admin's remaining moves on top of
+  it. Do not activate the stage definition until this entry transition exists.
+
+## Reusable operations — proven headless sObject path
+
+**The transitions and rules are created directly via sObject REST POST — no builder UI, dispatcher
+envelope, or Connect API is needed.** (org-verified on fsc-dop8, v63.0). All four Stage Management
+records accept plain `POST /services/data/vXX.0/sobjects/<Entity>`:
+
+- **`StageTransition`** — `StageDefinitionId` (REQ), `FromStageValueId` (REQ), `ToStageValueId` (REQ),
+  `Description`. The `From`/`To` ids are `StageValue` ids (`1DE…`) created by the `stage-definition`
+  sibling. A transition is what blocks invalid moves — an undefined move (e.g. Submitted → Intake) is
+  simply prevented.
+- **`StgFulfillmentStepDefGrp`** — one group per transition: `StageDefinitionId` (REQ),
+  `ContextReferenceId` (REQ, = the `StageTransition` id — this is what binds the rule to the transition),
+  `StgFulfillmentStepDefGrpName`.
+- **`StgFulfillmentStepDef`** — the rule that runs the Flow: `StgFulfillmentStepDefGrpId` (REQ),
+  `StgFulfillmentStepDefName` (REQ), `StgFulfillmentStepDefApiName` (REQ), `StepType`,
+  `FlowDefinitionName`.
+
+**Field-value contract (three org-verified findings — do not repeat the earlier mistakes):**
+
+- **`StepType = "AutoTask"`** — NOT "AutoLaunched Flow". "AutoLaunched Flow" is the *UI label*; the
+  sObject picklist value for a Flow-backed step is `AutoTask` (full picklist:
+  AutoTask/Callout/ManualTask/Milestone/Pause/StagedAssetize).
+- **`FlowDefinitionName` is the Flow's *API name*** — `Digital_Lending_Stage_Management` (underscored),
+  not the display name `Digital Lending Stage Management`.
+- **`RunAsUser` is OPTIONAL — omit it.** Every string value ("Admin", "AdminUser", "RunAsAdmin",
+  "Admin User") returns `400 INVALID_INPUT "Specify a valid value for Run As User"`. Omitting the field
+  creates the record cleanly. The UI's "Run As User = Admin User" is a UI-only convenience, not required
+  for the sObject write.
+- There is **no `SequenceNumber` column** on `StgFulfillmentStepDef` ("No such column").
+
+The Stage Management Builder
+(`builder_industries_stagemgmt/stageManagementBuilder.app?stateDefId=<1DL id>`, wizard SOR
+`builders/fsc-rolex/ui-industries-stage-mgmt-components`) remains available as a **UI fallback** if a
+future org rejects the direct sObject writes, but the direct path above is proven and preferred.
+
+## Workflow
+
+### Step 1 — Create transitions
+
+For each allowed move in the admin's transition map, POST a `StageTransition` with the source/target
+`StageValue` ids (`FromStageValueId`/`ToStageValueId`), the `StageDefinitionId`, and a `Description`.
+Only create the moves in the map — an undefined move is what blocks an invalid transition.
+
+### Step 2 — Add transition rules (group + step per transition)
+
+For each transition that should recompute CDS access, create the two-record rule:
+
+1. POST a **`StgFulfillmentStepDefGrp`** with `ContextReferenceId` = the `StageTransition` id, the
+   `StageDefinitionId`, and a group name.
+2. POST a **`StgFulfillmentStepDef`** into that group: `StgFulfillmentStepDefGrpId` = the group id,
+   `StepType = "AutoTask"`, `FlowDefinitionName = "Digital_Lending_Stage_Management"` (the Flow's API
+   name from `apex-and-flow`), plus `StgFulfillmentStepDefName` + `StgFulfillmentStepDefApiName`.
+   **Do not set `RunAsUser`** (it 400s on every value).
+
+### Step 3 — Activate the stage definition (do this LAST, after ≥1 transition exists)
+
+Now that at least one transition exists, activate the `StageDefinition`. **This is the ONLY point
+activation succeeds (org-verified):** `IsActive=true` set at create time is rejected, and set before any
+`StageTransition` exists it throws `FIELD_INTEGRITY_EXCEPTION`. Activate via the
+`IndustriesStageDefinitions` setup op that toggles publish state (the Aura/SOAP path pins
+`UsageType=STAGE_MANAGEMENT`); a raw `PATCH /sobjects/StageDefinition/<1DL id> {"IsActive": true}` also
+works once ≥1 transition is present. This is why `stage-definition` deliberately leaves the definition
+inactive and hands activation to this sibling.
+
+### Step 4 — Confirm active
+
+Re-read the definition and count: every intended transition has a group (matched by
+`ContextReferenceId`) and a step bound to `Digital_Lending_Stage_Management`. Confirm the stage
+definition/version reads `IsActive=true` on a fresh query.
+
+## Idempotency and rollback
+
+- Reuse existing transitions and rules that match the admin's map; do not duplicate a transition or a rule.
+- On a mismatch (an extra or missing transition, or a rule pointing at a different Flow), present the diff
+  and stop.
+- Rollback removes only transitions/rules created by this run and only after confirming no active
+  application depends on the transition path.
+
+## Output contract
+
+Return the created transitions (source → targets with their `StageTransition` ids), each transition's
+`StgFulfillmentStepDefGrp` id, and each `StgFulfillmentStepDef` with its name, `StepType` (`AutoTask`),
+and bound `FlowDefinitionName` (`Digital_Lending_Stage_Management`), plus a fresh read confirming the
+stage definition/version is active and the group/step counts match the transition count.
+
+## Definition of done
+
+The transition map matches the admin's specification, every intended transition has a
+`StgFulfillmentStepDefGrp` (bound by `ContextReferenceId`) and a `StgFulfillmentStepDef` whose
+`StepType=AutoTask` step runs the `Digital_Lending_Stage_Management` Flow, and the transitions read back
+on a fresh query with matching counts. Invalid moves are provably blocked (not defined). If the direct
+sObject path is rejected and the builder-UI fallback is left incomplete, this sibling is partial; a
+partial run is never reported as complete.

package/skills/health-cloud-appt-booking-config-configure/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: health-cloud-appt-booking-config-configure
+description: "Use this skill when users want to manage the Appointment Booking Config record (ApptBookingConfig), the parent setup record that tells Health Cloud Patient Appointment Scheduling how to reach a scheduling system. Trigger when users mention appt, booking, config, appt booking config."
+metadata:
+  version: "1.0"
+---
+
+# Managing Appt Booking Config
+
+## When to Use This Skill
+
+Manage the Appointment Booking Config record (ApptBookingConfig), the parent setup record that tells Health Cloud Patient Appointment Scheduling how to reach a scheduling system. Use standard sObject REST (/services/data/v67.0/sobjects/ApptBookingConfig) for describe, query, get, create, update and delete. The Intelligent Appointment Management skill relies on an active config with ApptBookingUrlConfig children for slot search and booking; this skill covers the config record itself. Only one record may have IsActive=true. To create, send DeveloperName (unique) and MasterLabel; everything else is optional. Without other values a new record is created with IsActive=false, IsSingleSourceSystem=false, CanCreateDuplicateRecord=true and Language=en_US, so send IsActive=true to make it the active config. Optional fields seen on a working configuration: NamedCredentialId and ApexClassId (to reach an external scheduling system), AssignedProviderRole, AttendanceThresholdPct, ServiceApptRecordTypeName, BestTimeSlotsDefinition and GetSlotStatusTimeout. Create the config first, then its ApptBookingUrlConfig children (see the ApptBookingUrlConfig skill). To remove, delete the children first, then the config. Requires Patient Appointment Scheduling to be on and the Health Cloud license.
+
+## Workflow
+
+Call describe first and build payloads from the createable fields. Before activating, query ApptBookingConfig for IsActive=true: creating or activating a second one fails with "There's already an active appointment scheduling configuration record. Deactivate it to use this one." To switch configs, set the old record IsActive to false first. GetSlotStatusTimeout, if set, must be 0 to 60,000 (milliseconds); other values fail with "Enter a Get Slot Status Timeout value from 0 through 60,000." DeveloperName must be unique. Lookups are named NamedCredentialId and ApexClassId in the REST payload and are optional. After creating the config, create its ApptBookingUrlConfig children. Delete the URL-config children before the parent: deleting a config that still has children fails with a dependency error.
+
+## Critical Constraints
+
+**Preconditions:**
+
+- The user needs create, read, update and delete access to ApptBookingConfig (Customize Application permission is required to create, edit or delete). (check: `<udd:crud:ApptBookingConfig>`)
+- Patient Appointment Scheduling must be turned on in the org, and the org must hold the Health Cloud license. (check: `Patient Appointment Scheduling enabled`)
+- Only one ApptBookingConfig can be active at a time. Query for an existing active record before activating a new one.
+- To reach an external scheduling system, a Named Credential for that system must exist first; an Apex class implementing the booking interface is optional.
+
+## Operations Reference
+
+Operations grouped by purpose. Use these as the building blocks for the workflows above.
+
+### Summary
+
+| Operation | Purpose | Status | Call | Depends on |
+|-----------|---------|--------|------|------------|
+| `describe` | read | — | `GET /services/data/v67.0/sobjects/ApptBookingConfig/describe` | — |
+| `list` | read | — | `GET /services/data/v67.0/query` | — |
+| `get-by-id` | read | — | `GET /services/data/v67.0/sobjects/ApptBookingConfig/{Id}` | `list` |
+| `create` | write | — | `POST /services/data/v67.0/sobjects/ApptBookingConfig` | `describe` |
+| `update` | write | — | `PATCH /services/data/v67.0/sobjects/ApptBookingConfig/{Id}` | `get-by-id` |
+| `delete` | write | — | `DELETE /services/data/v67.0/sobjects/ApptBookingConfig/{Id}` | `get-by-id` |
+
+### Dependency graph
+
+```mermaid
+graph TD
+  describe["describe (read)"]
+  list["list (read)"]
+  get_by_id["get-by-id (read)"]
+  create["create (write)"]
+  update["update (write)"]
+  delete["delete (write)"]
+  list --> get_by_id
+  describe --> create
+  get_by_id --> update
+  get_by_id --> delete
+```
+
+### Read operations
+
+#### `describe`
+
+Retrieve the ApptBookingConfig sObject describe — fields, picklist values, FLS, createable/updateable flags.
+
+**Call:** `GET /services/data/v67.0/sobjects/ApptBookingConfig/describe`
+
+**Output:** DescribeSObjectResult for ApptBookingConfig — use this to build the field list for list / create / update payloads.
+
+#### `list`
+
+List ApptBookingConfig records. Pair this with /describe first to pick field names.
+
+**Call:** `GET /services/data/v67.0/query`
+
+**Inputs:**
+
+- `where` *(`String`)* — Optional SOQL WHERE clause to filter Appt Booking Config records.
+- `limit` *(`int`)* — Optional SOQL LIMIT value.
+- `q` *(`string`)*
+
+**Output:** Query response with records[] of ApptBookingConfig — Id plus any SELECTed fields.
+
+#### `get-by-id`
+
+Retrieve a specific ApptBookingConfig record by Id.
+
+**Call:** `GET /services/data/v67.0/sobjects/ApptBookingConfig/{Id}`
+
+**Inputs:**
+
+- `Id` *(`ID`)* — Id of the ApptBookingConfig record to fetch.
+
+**Depends on:** `list`
+
+**Output:** Single ApptBookingConfig record with all readable fields per user FLS.
+
+### Write operations
+
+#### `create`
+
+Create an ApptBookingConfig record. Required: DeveloperName and MasterLabel. A new record defaults to IsActive=false, IsSingleSourceSystem=false, CanCreateDuplicateRecord=true; send IsActive=true to activate it. Only one config can be active; activating a second fails and the old one must be deactivated first. GetSlotStatusTimeout, if set, must be 0 to 60,000. Add NamedCredentialId (and optionally ApexClassId) only when integrating an external scheduling system.
+
+**Call:** `POST /services/data/v67.0/sobjects/ApptBookingConfig`
+
+**Inputs:**
+
+- `body` *(`object`)* — Field/value map for the new ApptBookingConfig. Populate from /describe's createableFields list.
+
+**Depends on:** `describe`
+
+**Rollback:** Call delete with the returned Id to undo the create.
+
+#### `update`
+
+Update an existing ApptBookingConfig record. Merge-patch semantics.
+
+**Call:** `PATCH /services/data/v67.0/sobjects/ApptBookingConfig/{Id}`
+
+**Inputs:**
+
+- `Id` *(`ID`)* — Id of the ApptBookingConfig to update.
+- `body` *(`object`)* — Partial field/value map — only include fields you want to change.
+
+**Depends on:** `get-by-id`
+
+#### `delete`
+
+Delete an ApptBookingConfig record. Delete all of its ApptBookingUrlConfig children first; the parent cannot be deleted while children exist. Deleting the active config leaves no active scheduling configuration until a new one is created.
+
+**Call:** `DELETE /services/data/v67.0/sobjects/ApptBookingConfig/{Id}`
+
+**Inputs:**
+
+- `Id` *(`ID`)* — Id of the ApptBookingConfig to delete.
+
+**Depends on:** `get-by-id`

package/skills/health-cloud-appt-booking-url-config-configure/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: health-cloud-appt-booking-url-config-configure
+description: "Use this skill when users want to manage Appointment Booking URL Config records (ApptBookingUrlConfig, use this exact object name), the child records of an Appointment Booking Config that tell Health Cloud Patient Appointment Scheduling which endpoint to call for each scheduling operation. Trigger when users mention appt, booking, url, config, appt booking url config."
+metadata:
+  version: "1.0"
+---
+
+# Managing Appt Booking Url Config
+
+## When to Use This Skill
+
+Manage Appointment Booking URL Config records (ApptBookingUrlConfig, use this exact object name), the child records of an Appointment Booking Config that tell Health Cloud Patient Appointment Scheduling which endpoint to call for each scheduling operation. Use standard sObject REST (/services/data/v67.0/sobjects/ApptBookingUrlConfig). Required to create: DeveloperName, MasterLabel, ApptBookingConfigId (the parent Id) and EndpointName, which must be one of FIND_SLOTS, GET_SLOT_STATUS, CREATE_APPOINTMENT, CANCEL_APPOINTMENT, GET_APPOINTMENT or CREATE_PATIENT. UrlPath (up to 80 characters, the path appended to the base URL) and AdditionalHeaders are optional and used for an external scheduling system. The platform accepts more than one row for the same EndpointName under a config, so create one row per endpoint and check existing rows first. Create the parent ApptBookingConfig first (see the ApptBookingConfig skill). Requires Patient Appointment Scheduling to be on and the Health Cloud license.
+
+## Workflow
+
+Call describe first, then query existing ApptBookingUrlConfig rows for the parent so you do not create a second row for an endpoint that already has one. EndpointName is a restricted picklist: any other value fails with a bad-value error. ApptBookingConfigId and EndpointName are required. UrlPath longer than 80 characters is rejected. Delete the URL-config rows before deleting their parent ApptBookingConfig.
+
+## Critical Constraints
+
+**Preconditions:**
+
+- The user needs create, read, update and delete access to ApptBookingUrlConfig (Customize Application permission is required to create, edit or delete). (check: `<udd:crud:ApptBookingUrlConfig>`)
+- Patient Appointment Scheduling must be turned on in the org, and the org must hold the Health Cloud license. (check: `Patient Appointment Scheduling enabled`)
+- The parent ApptBookingConfig record must already exist; its Id is required as ApptBookingConfigId.
+
+## Operations Reference
+
+Operations grouped by purpose. Use these as the building blocks for the workflows above.
+
+### Summary
+
+| Operation | Purpose | Status | Call | Depends on |
+|-----------|---------|--------|------|------------|
+| `describe` | read | — | `GET /services/data/v67.0/sobjects/ApptBookingUrlConfig/describe` | — |
+| `list` | read | — | `GET /services/data/v67.0/query` | — |
+| `get-by-id` | read | — | `GET /services/data/v67.0/sobjects/ApptBookingUrlConfig/{Id}` | `list` |
+| `create` | write | — | `POST /services/data/v67.0/sobjects/ApptBookingUrlConfig` | `describe` |
+| `update` | write | — | `PATCH /services/data/v67.0/sobjects/ApptBookingUrlConfig/{Id}` | `get-by-id` |
+| `delete` | write | — | `DELETE /services/data/v67.0/sobjects/ApptBookingUrlConfig/{Id}` | `get-by-id` |
+
+### Dependency graph
+
+```mermaid
+graph TD
+  describe["describe (read)"]
+  list["list (read)"]
+  get_by_id["get-by-id (read)"]
+  create["create (write)"]
+  update["update (write)"]
+  delete["delete (write)"]
+  list --> get_by_id
+  describe --> create
+  get_by_id --> update
+  get_by_id --> delete
+```
+
+### Read operations
+
+#### `describe`
+
+Retrieve the ApptBookingUrlConfig sObject describe — fields, picklist values, FLS, createable/updateable flags.
+
+**Call:** `GET /services/data/v67.0/sobjects/ApptBookingUrlConfig/describe`
+
+**Output:** DescribeSObjectResult — `fields[]` (each with name, type, createable, updateable, nillable, picklistValues), `recordTypeInfos[]`, `childRelationships[]`, `keyPrefix: 0mI`, `feedEnabled`, `searchable`, plus FLS flags. Drives field selection for list / create / update.
+
+#### `list`
+
+List via SOQL. SELECT only FLS-readable fields — others silently omit the row from results. Run /describe first for the field set.
+
+**Call:** `GET /services/data/v67.0/query`
+
+**Inputs:**
+
+- `where` *(`String`)* — Optional SOQL WHERE clause to filter Appt Booking Url Config records.
+- `limit` *(`int`)* — Optional SOQL LIMIT value.
+- `q` *(`string`)*
+
+**Output:** Query response with records[] of ApptBookingUrlConfig — Id plus any SELECTed fields.
+
+#### `get-by-id`
+
+Retrieve a specific ApptBookingUrlConfig record by Id.
+
+**Call:** `GET /services/data/v67.0/sobjects/ApptBookingUrlConfig/{Id}`
+
+**Inputs:**
+
+- `Id` *(`ID`)* — Id of the ApptBookingUrlConfig record to fetch.
+
+**Depends on:** `list`
+
+**Output:** Single ApptBookingUrlConfig record with all readable fields per user FLS.
+
+### Write operations
+
+#### `create`
+
+Create an ApptBookingUrlConfig record for one endpoint of a config. Required: DeveloperName, MasterLabel, ApptBookingConfigId and EndpointName (FIND_SLOTS, GET_SLOT_STATUS, CREATE_APPOINTMENT, CANCEL_APPOINTMENT, GET_APPOINTMENT or CREATE_PATIENT). UrlPath (up to 80 characters) and AdditionalHeaders are optional. Check for an existing row for the endpoint first, because duplicates are accepted.
+
+**Call:** `POST /services/data/v67.0/sobjects/ApptBookingUrlConfig`
+
+**Inputs:**
+
+- `body` *(`object`)* — Field/value map for the new ApptBookingUrlConfig. Populate from /describe's createableFields list.
+
+**Depends on:** `describe`
+
+**Rollback:** Call delete with the returned Id to undo the create.
+
+#### `update`
+
+Update an existing ApptBookingUrlConfig record. Merge-patch semantics.
+
+**Call:** `PATCH /services/data/v67.0/sobjects/ApptBookingUrlConfig/{Id}`
+
+**Inputs:**
+
+- `Id` *(`ID`)* — Id of the ApptBookingUrlConfig to update.
+- `body` *(`object`)* — Partial field/value map — only include fields you want to change.
+
+**Depends on:** `get-by-id`
+
+#### `delete`
+
+Delete an ApptBookingUrlConfig record. Deleting a FIND_SLOTS row removes the slot-search endpoint for its config; delete all rows before deleting the parent ApptBookingConfig.
+
+**Call:** `DELETE /services/data/v67.0/sobjects/ApptBookingUrlConfig/{Id}`
+
+**Inputs:**
+
+- `Id` *(`ID`)* — Id of the ApptBookingUrlConfig to delete.
+
+**Depends on:** `get-by-id`

package/skills/health-cloud-care-provider-affl-role-config-configure/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: health-cloud-care-provider-affl-role-config-configure
+description: "Use this skill when users want to manage the Care Provider Affiliation Role Config (CareProviderAfflRoleConfig) with standard sObject REST (/services/data/v67.0/sobjects/CareProviderAfflRoleConfig). Trigger when users mention care, provider, affl, role, config, care provider affl role config."
+metadata:
+  version: "1.0"
+---
+
+# Managing Care Provider Affl Role Config
+
+## When to Use This Skill
+
+Manage the Care Provider Affiliation Role Config (CareProviderAfflRoleConfig) with standard sObject REST (/services/data/v67.0/sobjects/CareProviderAfflRoleConfig). It sets ProviderRole, the role value Health Cloud uses for hospital-affiliation links created through the Provider API; the Provider Search More Details view shows a hospital affiliation only when the link's role matches it. Required to create: MasterLabel and DeveloperName (unique). ProviderRole (text, up to 255 characters) and AffiliationType are optional on create, but set both: AffiliationType is a restricted picklist with the single value HospitalAffiliation. A value of AffiliationType can be used by only one record, so a second HospitalAffiliation record fails with a duplicate-value error on create and on update; records with AffiliationType left blank are not limited. To change the role, update the existing HospitalAffiliation record rather than creating another. Set the role before creating providers, because existing affiliations may not be updated when the role changes. It is independent of CareProviderSearchConfig.
+
+## Workflow
+
+Query for an existing record with AffiliationType HospitalAffiliation first. If one exists, PATCH its ProviderRole; creating or updating a second record to HospitalAffiliation fails with DUPLICATE_VALUE. The only allowed AffiliationType value is HospitalAffiliation; any other value is rejected as a bad restricted-picklist value. ProviderRole longer than 255 characters is rejected. Set the role before provider data is created through the Provider API. This record does not choose which roles are searchable; it defines the single role value used for hospital affiliations.
+
+## Critical Constraints
+
+**Preconditions:**
+
+- Provider Search must be enabled in the org and the user must have Provider Search access. (check: `Provider Search enabled`)
+- At most one record can have AffiliationType HospitalAffiliation; update the existing record instead of creating another.
+
+## Operations Reference
+
+Operations grouped by purpose. Use these as the building blocks for the workflows above.
+
+### Summary
+
+| Operation | Purpose | Status | Call | Depends on |
+|-----------|---------|--------|------|------------|
+| `describe` | read | — | `GET /services/data/v67.0/sobjects/CareProviderAfflRoleConfig/describe` | — |
+| `list` | read | — | `GET /services/data/v67.0/query` | `describe` |
+| `get-by-id` | read | — | `GET /services/data/v67.0/sobjects/CareProviderAfflRoleConfig/{Id}` | `list` |
+| `create` | write | — | `POST /services/data/v67.0/sobjects/CareProviderAfflRoleConfig` | `describe` |
+| `update` | write | — | `PATCH /services/data/v67.0/sobjects/CareProviderAfflRoleConfig/{Id}` | `get-by-id` |
+| `delete` | write | — | `DELETE /services/data/v67.0/sobjects/CareProviderAfflRoleConfig/{Id}` | `get-by-id` |
+
+### Dependency graph
+
+```mermaid
+graph TD
+  describe["describe (read)"]
+  list["list (read)"]
+  get_by_id["get-by-id (read)"]
+  create["create (write)"]
+  update["update (write)"]
+  delete["delete (write)"]
+  describe --> list
+  list --> get_by_id
+  describe --> create
+  get_by_id --> update
+  get_by_id --> delete
+```
+
+### Read operations
+
+#### `describe`
+
+Retrieve the CareProviderAfflRoleConfig sObject describe — fields, picklist values, FLS, createable/updateable flags.
+
+**Call:** `GET /services/data/v67.0/sobjects/CareProviderAfflRoleConfig/describe`
+
+**Output:** DescribeSObjectResult for CareProviderAfflRoleConfig — use this to build the field list for list / create / update payloads.
+
+#### `list`
+
+List CareProviderAfflRoleConfig records. Pair this with /describe first to pick field names.
+
+**Call:** `GET /services/data/v67.0/query`
+
+**Inputs:**
+
+- `where` *(`String`)* — Optional SOQL WHERE clause to filter Care Provider Affl Role Config records.
+- `limit` *(`int`)* — Optional SOQL LIMIT value.
+- `q` *(`string`)*
+
+**Depends on:** `describe`
+
+**Output:** Query response with records[] of CareProviderAfflRoleConfig — Id plus any SELECTed fields.
+
+#### `get-by-id`
+
+Retrieve a specific CareProviderAfflRoleConfig record by Id.
+
+**Call:** `GET /services/data/v67.0/sobjects/CareProviderAfflRoleConfig/{Id}`
+
+**Inputs:**
+
+- `Id` *(`ID`)* — Id of the CareProviderAfflRoleConfig record to fetch.
+
+**Depends on:** `list`
+
+**Output:** Single CareProviderAfflRoleConfig record with all readable fields per user FLS.
+
+### Write operations
+
+#### `create`
+
+Create the Care Provider Affiliation Role Config record. Required: MasterLabel and DeveloperName. Also send ProviderRole and AffiliationType=HospitalAffiliation (both optional on create, but the HospitalAffiliation record is the one that sets the role). Only one record can hold AffiliationType HospitalAffiliation; if one already exists, update it instead.
+
+**Call:** `POST /services/data/v67.0/sobjects/CareProviderAfflRoleConfig`
+
+**Inputs:**
+
+- `body` *(`object`)* — Field/value map for the new CareProviderAfflRoleConfig. Populate from /describe's createableFields list.
+
+**Depends on:** `describe`
+
+**Rollback:** Call delete with the returned Id to undo the create.
+
+#### `update`
+
+Update an existing CareProviderAfflRoleConfig record. Merge-patch semantics — only include fields you want to change. The mutable config columns are ProviderRole and AffiliationType; standard Setup audit fields are system-managed.
+
+**Call:** `PATCH /services/data/v67.0/sobjects/CareProviderAfflRoleConfig/{Id}`
+
+**Inputs:**
+
+- `Id` *(`ID`)* — Id of the CareProviderAfflRoleConfig to update.
+- `body` *(`object`)* — Partial field/value map — only include fields you want to change.
+
+**Depends on:** `get-by-id`
+
+#### `delete`
+
+Delete a CareProviderAfflRoleConfig record.
+
+**Call:** `DELETE /services/data/v67.0/sobjects/CareProviderAfflRoleConfig/{Id}`
+
+**Inputs:**
+
+- `Id` *(`ID`)* — Id of the CareProviderAfflRoleConfig to delete.
+
+**Depends on:** `get-by-id`