@salesforce/afv-skills 1.63.0 → 1.65.0

package/skills/industries-fundraising-source-code-gen-configure/SKILL.md

@@ -0,0 +1,299 @@
+---
+name: industries-fundraising-source-code-gen-configure
+description: "Use this skill when users want to setup page for Fundraising Source Code Generation — configures the outreach source-code formula and the three UTM (medium / source / campaign) mappings Fundraising uses to derive attribution codes for donor outreach records. Trigger when users mention fundraising, source, code, gen, fundraising source code gen."
+metadata:
+  version: "1.0"
+---
+
+# Managing Fundraising Source Code Gen
+
+## When to Use This Skill
+
+Setup page for Fundraising Source Code Generation — configures the outreach
+source-code formula and the three UTM (medium / source / campaign) mappings
+Fundraising uses to derive attribution codes for donor outreach records.
+Persistence layer is the Tooling Metadata sObject `FundraisingConfig`
+(singleton row keyed on `DeveloperName=FundraisingConfig`), the same row the
+sibling `FundraisingSettings` recipe writes NextGenCmtPrcs* fields on.
+OPERATIONAL PREREQUISITE: the parent Fundraising feature must be enabled by
+the `FundraisingSettings` recipe first — that step both flips the parent
+org preference and inserts the default FundraisingConfig row. Any read on
+this recipe before Fundraising is enabled returns an empty/absent
+representation. When to pick this recipe: an admin wants to change how
+Fundraising builds a donor's outreach source code (customize the formula) or
+how it maps campaign / source / medium onto attribution fields. Not for
+donor-record or gift-transaction workflows (those live on the
+industries.fundraising / industries.fundraisingops Connect APIs).
+
+## Workflow
+
+Entity model: this recipe reads/writes exactly one row of the Tooling
+Metadata sObject `FundraisingConfig` (DeveloperName=FundraisingConfig).
+Row carries the two disjoint concept groups:
+  * OWNED BY THIS RECIPE (mutable via save-settings): the seven
+    recipe-owned fields — OutreachSourceCodeGenFmla, UtmMediumSrcObj,
+    UtmMediumSrcObjField, UtmSourceSrcObj, UtmSourceSrcObjField,
+    UtmCampaignSrcObj, UtmCampaignSrcObjField.
+  * OWNED BY THE SIBLING FundraisingSettings RECIPE (untouched by any
+    step in this SOR): IsNextGenCmtPrcsParallel, NextGenCmtPrcsMaxThreads,
+    NextGenCmtPrcsBatchSize, DonorExternalIdField.
+
+save-settings JSON keys (case-sensitive): formulaExpression + the six
+utm* keys. `formulaExpression` is the input key; the persisted column
+is `OutreachSourceCodeGenFmla` on FundraisingConfig. Sending any other
+key returns CONTROLLER_ERROR.
+
+save-settings merge semantics — recipe-owned scope is REPLACE-ALL:
+every recipe-owned key not present in the payload is nulled on the
+row. Only the sibling-owned scope (NextGenCmtPrcs* / DonorExternalIdField)
+is preserved across saves. Consequence: a "partial edit" that ships
+only one changed key clears the other six. To edit a single field,
+first read the current 7-field state (via Tooling SOQL) and resend all
+non-nulled values alongside the change.
+
+check-syntax runs a recipe-specific DSL grammar validator — NOT
+general Salesforce formula grammar. Empty string returns
+`ERROR ... input '<EOF>'`; bare identifiers (`Name`) return
+`ERROR ... input 'Name'`. Simple valid inputs: a double-quoted
+string literal (`"HELLO"`) or a comparison/logical expression over
+literals (`"A" == "B"`). `+` string concatenation is NOT accepted.
+
+`sourceCodeGenerationEnabled` gates ONLY the save-settings grammar
+validator, NOT whether a formula persists. Empirical behavior (probed
+against a live org):
+  * enabled=true  → save-settings runs the DSL grammar validator on
+    `formulaExpression`. Empty string AND grammar-invalid inputs
+    (bare identifiers, malformed expressions) return 500
+    CONTROLLER_ERROR; only grammar-valid formulas persist.
+  * enabled=false → save-settings BYPASSES the grammar validator.
+    ANY string value (empty, valid, or grammar-invalid) persists
+    verbatim to `OutreachSourceCodeGenFmla`. The gate is NOT
+    "reject non-empty when disabled"; it is "skip validation when
+    disabled." check-syntax remains callable and returns grammar
+    diagnostics regardless of the toggle.
+
+Clearing the formula: `formulaExpression:""` is REJECTED by the
+grammar validator while `sourceCodeGenerationEnabled=true`. To null
+the formula, first call set-source-code-generation-enabled(false),
+then save-settings with `formulaExpression:""`. Re-enable after if
+needed. (This works precisely because disabling bypasses grammar
+validation, letting the empty string through to persistence.)
+
+Workflow ordering:
+
+### Phase 1: Enable the parent Fundraising feature via the sibling
+
+Enable the parent Fundraising feature via the sibling
+     FundraisingSettings recipe (writes the default FundraisingConfig
+     row + flips the IndustriesFundraising org preference). Skipping
+     this yields empty reads on FundraisingConfig.
+
+### Phase 2: get-source-code-generation-enabled — read the child feature-gate
+
+get-source-code-generation-enabled — read the child feature-gate
+     org preference. Note: this toggle gates grammar VALIDATION on
+     save-settings, not persistence. When false, any formula string
+     (including grammar-invalid ones) will persist without validation
+     — callers who want the grammar-safety net must set this true
+     before writing.
+
+### Phase 3: set-source-code-generation-enabled(isEnabled=true) — enable the
+
+set-source-code-generation-enabled(isEnabled=true) — enable the
+     child feature so save-settings will run the grammar validator.
+     Verify via verify-set-source-code-generation-enabled.
+
+### Phase 4: get-utm-settings + get-outreach-source-code-formula — read
+
+get-utm-settings + get-outreach-source-code-formula — read
+     current state via Tooling SOQL on FundraisingConfig. Capture ALL
+     seven recipe-owned values before mutating.
+
+### Phase 5: check-syntax(formulaExpression) — validate a candidate formula
+
+check-syntax(formulaExpression) — validate a candidate formula
+     string. Iterate until diagnostics array is empty.
+
+### Phase 6: save-settings(oscSettings=<json>) — persist state. Payload MUST
+
+save-settings(oscSettings=<json>) — persist state. Payload MUST
+     carry every recipe-owned field the caller wants to keep, not
+     just the changed one.
+
+### Phase 7: verify-save-settings — Tooling SOQL read-back to confirm
+
+verify-save-settings — Tooling SOQL read-back to confirm.
+
+Rollback: to revert, call save-settings with the JSON originally
+returned by get-utm-settings before your edit — all seven keys
+together. To clear all recipe-owned state, save a payload with all
+seven keys set to empty string (or omit them; both null the row's
+recipe-owned columns). Sibling-owned NextGenCmtPrcs* /
+DonorExternalIdField values survive either shape.
+
+## Critical Constraints
+
+**Preconditions:**
+
+- Nonprofit Cloud Fundraising must be provisioned in the org. Without
+it, the Fundraising Admin permission check fails and every operation
+in this skill is blocked. (check: `IndustriesFundraising`)
+
+## Verification Checklist
+
+After every write operation, confirm the effect by re-reading state:
+
+- After `set-source-code-generation-enabled`: call `verify-set-source-code-generation-enabled` (`GET /headless/invoke/platform/fundraising-source-code-gen`)
+- After `save-settings`: call `verify-save-settings` (`GET /services/data/v67.0/tooling/query`)
+
+## Operations Reference
+
+Operations grouped by purpose. Use these as the building blocks for the workflows above.
+
+### Summary
+
+| Operation | Purpose | Status | Call | Depends on |
+|-----------|---------|--------|------|------------|
+| `get-source-code-generation-enabled` | read | implemented | `GET /headless/invoke/platform/fundraising-source-code-gen` | — |
+| `set-source-code-generation-enabled` | write | proposed | `PATCH /headless/invoke/platform/fundraising-source-code-gen/set-source-code-generation-enabled` | — |
+| `verify-set-source-code-generation-enabled` | verify | — | `GET /headless/invoke/platform/fundraising-source-code-gen` | `set-source-code-generation-enabled` |
+| `save-settings` | write | implemented | `PATCH /headless/invoke/platform/fundraising-source-code-gen/save-settings` | — |
+| `get-utm-settings` | read | proposed | `GET /services/data/v67.0/tooling/query` | — |
+| `get-outreach-source-code-formula` | read | implemented | `GET /services/data/v67.0/tooling/query` | — |
+| `check-syntax` | read | proposed | `GET /headless/invoke/platform/fundraising-source-code-gen/check-syntax` | — |
+| `verify-save-settings` | verify | proposed | `GET /services/data/v67.0/tooling/query` | `save-settings` |
+
+### Read operations
+
+#### `get-source-code-generation-enabled`
+
+Read the child `sourceCodeGenerationEnabled` org preference (Fundraising
+Source Code Generation feature toggle). Returns a bare boolean. This
+toggle gates the save-settings grammar VALIDATOR, not persistence —
+when false, save-settings persists any formula string (including
+grammar-invalid ones) without validation; when true, save-settings
+rejects grammar-invalid formulas with 500 CONTROLLER_ERROR. Parent
+IndustriesFundraising feature must be enabled first (via the sibling
+FundraisingSettings recipe).
+
+**Call:** `GET /headless/invoke/platform/fundraising-source-code-gen`   — status: `implemented`
+
+**Output:** Boolean. True when the org-level source-code-generation preference is enabled, false otherwise.
+
+#### `get-utm-settings`
+
+Read the seven recipe-owned fields (formula + UTM mappings) from the
+FundraisingConfig singleton via Tooling SOQL. Returns a typed
+QueryResult with one record (`totalSize:0` when the parent Fundraising
+feature has not been enabled yet). Preferred over the controller's
+JSON-string wrapper — typed columns, filter-able, discoverable schema.
+
+**Call:** `GET /services/data/v67.0/tooling/query`   — status: `proposed`
+
+**Inputs:**
+
+- `q` *(`string`)*
+
+**Output:** String. JSON-serialized UTM-style outreach source-code settings (source/medium/campaign field mappings plus behavior toggles); same shape save-settings consumes.
+
+#### `get-outreach-source-code-formula`
+
+Read the current `OutreachSourceCodeGenFmla` from the FundraisingConfig
+singleton via Tooling SOQL. Returns a typed one-record QueryResult
+(empty when the parent Fundraising feature is not enabled). Preferred
+over the controller's raw-string wrapper — typed column, discoverable
+schema.
+
+**Call:** `GET /services/data/v67.0/tooling/query`   — status: `implemented`
+
+**Inputs:**
+
+- `q` *(`string`)*
+
+**Output:** String. The formula expression currently configured for the org (Fundraising source-code-formula DSL), or empty when none is set.
+
+#### `check-syntax`
+
+Validate a candidate outreach-source-code formula against the
+recipe-specific DSL grammar. Returns an array of parser diagnostics
+(empty array = valid). NOT general Salesforce formula grammar —
+bare identifiers (`Name`) return `ERROR ... input 'Name'`; empty
+string returns `ERROR ... input '<EOF>'`. Valid inputs include
+double-quoted string literals (`"HELLO"`) and comparison/logical
+expressions over them (`"A" == "B"`); `+` string concatenation is
+NOT accepted. No public grammar-validator API exists; this is canonical.
+
+**Call:** `GET /headless/invoke/platform/fundraising-source-code-gen/check-syntax`   — status: `proposed`
+
+**Inputs:**
+
+- `formulaExpression` *(`String`)*
+
+**Output:** Array of strings. Each entry is a parser diagnostic message from the Fundraising formula grammar; an empty array indicates the formula expression parses cleanly.
+
+### Write operations
+
+#### `set-source-code-generation-enabled`
+
+Toggle the child `sourceCodeGenerationEnabled` org preference. This
+toggle gates the save-settings grammar validator: when true, the
+validator runs and rejects grammar-invalid formulas (500
+CONTROLLER_ERROR); when false, the validator is BYPASSED and any
+formula string (valid, empty, or grammar-invalid) persists verbatim.
+Set to true for admin workflows that want the grammar-safety net;
+set to false to persist an empty formula (see agent_guidance
+"Clearing the formula"). Idempotent — writing the current value is
+a no-op returning success.
+
+**Call:** `PATCH /headless/invoke/platform/fundraising-source-code-gen/set-source-code-generation-enabled`   — status: `proposed`
+
+**Inputs:**
+
+- `isEnabled` *(`boolean`)* — Whether enabled is enabled.
+
+**Output:** SaveResult. Carries success (boolean — true when the org-pref write succeeded), id (record id of the affected entity, may be empty for org-pref writes), errors (hard errors that caused failure when success is false), warnings (non-fatal warnings, may be present even when success is true), and infos (informational messages, non-blocking).
+
+#### `save-settings`
+
+Persist the recipe-owned fields on the FundraisingConfig singleton.
+JSON key is `formulaExpression` + the six utm* keys. Server enforces
+two controls the raw Tooling write does not: (1) formula-grammar
+validation gated on `sourceCodeGenerationEnabled`; (2) sibling-scope
+preservation — the sibling-owned NextGenCmtPrcs* / DonorExternalIdField
+values on the same row are untouched. Recipe-owned scope is
+REPLACE-ALL: any of the seven keys omitted from the payload is nulled.
+To change one field, first read all seven via Tooling SOQL and
+resend the unchanged values.
+
+**Call:** `PATCH /headless/invoke/platform/fundraising-source-code-gen/save-settings`   — status: `implemented`
+
+**Inputs:**
+
+- `oscSettings` *(`String`)* — Value for the osc settings field.
+
+### Verify operations
+
+#### `verify-set-source-code-generation-enabled`
+
+Confirm the child `sourceCodeGenerationEnabled` toggle persisted by
+reading the boolean back. Bind result to the value passed to
+set-source-code-generation-enabled.
+
+**Call:** `GET /headless/invoke/platform/fundraising-source-code-gen`
+
+**Depends on:** `set-source-code-generation-enabled`
+
+#### `verify-save-settings`
+
+Confirm save-settings persisted by reading the FundraisingConfig
+singleton back via Tooling SOQL. Verifies BOTH that the recipe-owned
+fields updated AND that the sibling-owned NextGenCmtPrcs* /
+DonorExternalIdField values were preserved by the server-side merge.
+
+**Call:** `GET /services/data/v67.0/tooling/query`   — status: `proposed`
+
+**Inputs:**
+
+- `q` *(`string`)*
+
+**Depends on:** `save-settings`

package/skills/industries-google-maps-api-key-settings-configure/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: industries-google-maps-api-key-settings-configure
+description: "Use this skill when users want to read, set, or clear the org-wide Google Maps API key consumed by Consumer Goods Cloud / Retail Execution map and visit-routing surfaces. Trigger when users mention google, maps, api, key, settings, google maps api key settings."
+metadata:
+  version: "1.0"
+---
+
+# Managing Google Maps Api Key Settings
+
+## When to Use This Skill
+
+Read, set, or clear the org-wide Google Maps API key consumed by Consumer Goods Cloud / Retail Execution map and visit-routing surfaces. The key is a single org-level credential string (no per-user / per-record variants). All three operations route to Connect resource IGoogleMapsApiKeyResource at /connect/industries/retail/google-map-api-key (GET / PUT / DELETE) and require the caller's user to have Retail Execution or Direct Store Delivery enabled.
+
+## Critical Constraints
+
+**Preconditions:**
+
+- Caller's user must have Retail Execution OR Direct Store Delivery enabled (the Connect resource's userDynamicChecks gate UserHasRetailExecutionOrDirectStoreDeliveryEnable). The Aura wrapper's gate Run Retail Execution permission is a strict subset. (check: `UserHasRetailExecutionOrDirectStoreDeliveryEnable`)
+- Customize Application (or equivalent admin permission) is required to mutate org-wide credentials, consistent with other org-level credential settings.
+
+**Destructive operations — require explicit user confirmation:**
+
+- **`deleteGoogleMapsApiKey_3`** — Clear the org-wide Google Maps API key. After this returns, getGoogleMapsApiKey responds with apiKey null/empty until a new value is saved.
+  - Rollback: No automatic rollback.
+
+## Verification Checklist
+
+After every write operation, confirm the effect by re-reading state:
+
+- After `saveGoogleMapsApiKey_2`: call `verify-saveGoogleMapsApiKey_2` (`/services/data/v67.0/connect/industries/retail/google-map-api-key`)
+
+## Operations Reference
+
+Operations grouped by purpose. Use these as the building blocks for the workflows above.
+
+### Summary
+
+| Operation | Purpose | Status | Call | Depends on |
+|-----------|---------|--------|------|------------|
+| `getGoogleMapsApiKey_1` | read | implemented | `/services/data/v67.0/connect/industries/retail/google-map-api-key` | — |
+| `saveGoogleMapsApiKey_2` | write | implemented | `/services/data/v67.0/connect/industries/retail/google-map-api-key` | `getGoogleMapsApiKey_1` |
+| `deleteGoogleMapsApiKey_3` | delete | implemented | `/services/data/v67.0/connect/industries/retail/google-map-api-key` | `getGoogleMapsApiKey_1` |
+| `verify-saveGoogleMapsApiKey_2` | verify | — | `/services/data/v67.0/connect/industries/retail/google-map-api-key` | `saveGoogleMapsApiKey_2` |
+
+### Read operations
+
+#### `getGoogleMapsApiKey_1`
+
+Read the org-wide Google Maps API key. Returns a GoogleMapsApiKeyRepresentation with one field, apiKey (String); apiKey is null/empty when no key has been saved yet.
+
+**Call:** `/services/data/v67.0/connect/industries/retail/google-map-api-key`   — status: `implemented`
+
+**Output:** GoogleMapsApiKeyRepresentation — single field apiKey (String). Null/empty when no key has been configured for the org.
+
+### Write operations
+
+#### `saveGoogleMapsApiKey_2`
+
+Persist the org-wide Google Maps API key. Body GoogleMapsApiKeyInputRepresentation has one non-empty apiKey String; idempotent overwrite. Response echoes the persisted apiKey.
+
+**Call:** `/services/data/v67.0/connect/industries/retail/google-map-api-key`   — status: `implemented`
+
+**Inputs:**
+
+- `apiKey` *(`String`)*
+
+**Depends on:** `getGoogleMapsApiKey_1`
+
+### Verify operations
+
+#### `verify-saveGoogleMapsApiKey_2`
+
+Read back via getGoogleMapsApiKey to confirm saveGoogleMapsApiKey persisted: response apiKey should equal the value just submitted.
+
+**Call:** `/services/data/v67.0/connect/industries/retail/google-map-api-key`
+
+**Depends on:** `saveGoogleMapsApiKey_2`
+
+### Destructive operations
+
+#### `deleteGoogleMapsApiKey_3`
+
+Clear the org-wide Google Maps API key. After this returns, getGoogleMapsApiKey responds with apiKey null/empty until a new value is saved.
+
+**Call:** `/services/data/v67.0/connect/industries/retail/google-map-api-key`   — status: `implemented`
+
+**Depends on:** `getGoogleMapsApiKey_1`

package/skills/industries-grantmaking-intelligence-settings-open/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: industries-grantmaking-intelligence-settings-open
+description: "Use this skill when users want to setup landing page for Grantmaking Intelligence — an Aura wrapper (setup_industries_npc:grantmakingDataCloudSetupWrapper) that composes two child components with no controller of its own, and no first-party API on this node today. Trigger when users mention grantmaking, intelligence, settings, grantmaking intelligence settings."
+metadata:
+  version: "1.0"
+---
+
+# Querying Grantmaking Intelligence Settings
+
+## When to Use This Skill
+
+Setup landing page for Grantmaking Intelligence — an Aura wrapper
+(setup_industries_npc:grantmakingDataCloudSetupWrapper) that composes two
+child components with no controller of its own, and no first-party API
+on this node today. Agent-driven configuration is not available from
+this skill.
+
+What renders here:
+  (1) an Intelligent App Hub panel (wave:intelligentAppHub) that
+      lists CRM Analytics apps and lets an admin pin/schedule them;
+      its backing controller lives with the insights/wave team, not
+      NPC Cartwheel.
+  (2) an Admin Setup Assistant container
+      (industries_common:adminSetupAssistantContainer) — the same
+      generic wizard shell used by CaseMgmtIntelligenceSettings.
+      That shell is generic; it reads a per-page setup-config JSON
+      registration owned by the industries-common team. No such
+      registration currently exists for GrantmakingIntelligenceSettings
+      (tried both the node-id and DataCloud-variant file names),
+      so the container renders empty on this page today.
+
+When an admin asks to configure Grantmaking Intelligence, the
+productive action from a chat/agent context is to navigate them to
+/lightning/setup/GrantmakingIntelligenceSettings/home and let them
+interact with the embedded UI (schedule an app in the Intelligent App
+Hub, or wait for the Admin Setup Assistant registration to arrive).
+Do not fabricate step calls — no wire endpoint on this node returns
+success today.
+
+Access: six gates enforced at the setup-tree level — see preconditions.
+
+## Critical Constraints
+
+**Preconditions:**
+
+- Caller must be an org admin — the setup-manifest access clause
+requires an admin user. (check: `Org Admin`)
+- Org must have Budget object access provisioned — setup-manifest
+requires Budget.orgHasBudgetAccess. (check: `Budget org access`)
+- Caller must have user-level Budget access — setup-manifest
+requires Budget.userHasBudgetUserAccess. (check: `Budget user access`)
+- Org must have Funding Award access provisioned — setup-manifest
+requires IndustriesFundingAward.orgHasFundingAwardAccess. (check: `Funding Award access`)
+- Org must have Data Cloud (CDP) or Genie enabled — setup-manifest
+requires Data Cloud or Genie enabled. (check: `CDP or Genie enabled`)
+- The Nonprofit Data Cloud setup feature gate must be enabled on
+the org. Orgs without the gate rolled out do not see this setup
+page. (check: `Nonprofit Data Cloud setup feature gate`)

package/skills/industries-hc-score-category-settings-configure/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: industries-hc-score-category-settings-configure
+description: "Use this skill when users want to cRUD on ScoreCategory records via standard sObject REST — describe, list, get-by-id, create, update, delete. Trigger when users mention hcscore, category, settings, hcscore category settings."
+metadata:
+  version: "1.0"
+---
+
+# Managing Hc Score Category Settings
+
+## When to Use This Skill
+
+CRUD on ScoreCategory records via standard sObject REST — describe, list, get-by-id, create, update, delete. Run /describe first, then build payloads from createableFields. The hierarchical projection (parent/child tree, decorated with iconUrl/parentName/developerName via the ScoreCategoryHierarchy type) is NOT served here; use the sibling SOR ScoreCategorySettings (op `industries.industries-healthcare.score-category-setup-page.getScoreCategories`) when the agent needs the tree shape.
+
+## Workflow
+
+Standard sObject REST provides full CRUD + describe on ScoreCategory; no proprietary controller is involved. Run /describe first, then build payloads from createableFields — the shape depends on the org's permission/profile setup, so the SOR does not enumerate fields statically. Wire constraints an admin will hit: CategoryName is required and capped at 25 chars; MasterLabel caps at 40; Description caps at 255; Language is a restricted locale picklist and defaults to en_US when omitted at create; DeveloperName is settable at create despite /describe reporting createable:false, and auto-derives from CategoryName when omitted (must begin with a letter, alphanumeric + underscore only, no consecutive or trailing underscores, unique within the org). ParentCategoryId is a self-FK, so parent/child relationships are reachable via plain SOQL on this SOR when only the tree shape is needed; use the sibling SOR ScoreCategorySettings when the tree needs the decorated projection (iconUrl / parentName / developerName). Deleting a parent cascades to its children automatically.
+
+## Critical Constraints
+
+**Preconditions:**
+
+- User needs CRUD access to ScoreCategory. (check: `<udd:crud:ScoreCategory>`)
+- Org must have the Health Cloud / Holistic Patient Index feature line provisioned (the ScoreCategory entity ships with Health Cloud — orgs without Health Cloud provisioned will not see the entity).
+
+## 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/ScoreCategory/describe` | — |
+| `list` | read | — | `GET /services/data/v67.0/query` | `describe` |
+| `get-by-id` | read | — | `GET /services/data/v67.0/sobjects/ScoreCategory/{Id}` | `list` |
+| `create` | write | — | `POST /services/data/v67.0/sobjects/ScoreCategory` | `describe` |
+| `update` | write | — | `PATCH /services/data/v67.0/sobjects/ScoreCategory/{Id}` | `get-by-id` |
+| `delete` | write | — | `DELETE /services/data/v67.0/sobjects/ScoreCategory/{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 ScoreCategory sObject describe — fields, picklist values, FLS, createable/updateable flags.
+
+**Call:** `GET /services/data/v67.0/sobjects/ScoreCategory/describe`
+
+**Output:** DescribeSObjectResult for ScoreCategory — use this to build the field list for list / create / update payloads.
+
+**Notes:** developerName_describe_mismatch: /describe reports DeveloperName createable:false — but the wire actually ACCEPTS DeveloperName in the create
+payload and honors the caller-supplied value. Agents that trust describe alone will not know they can
+override the auto-derived value. POST with an explicit DeveloperName returns 201 and the record keeps
+the supplied value.; child_relationships: {'ChildScoreCategories': {'cascadeDelete': True, 'note': 'Deleting a parent ScoreCategory automatically deletes its children. A subsequent GET on a\nchild record after the parent is gone returns 404 NOT_FOUND; a subsequent DELETE on the same\nrecord returns 404 INVALID_CROSS_REFERENCE_KEY instead — the two verbs report different error\ncodes for the same gone-due-to-cascade record.'}}
+
+#### `list`
+
+List ScoreCategory records via SOQL. Pair with /describe first to pick field names. ParentCategoryId is a self-FK, so a query that selects it (and optionally the parent's Name via a relationship traversal) returns the parent/child tree shape without leaving this SOR — reach for the sibling SOR ScoreCategorySettings only when the decorated projection (iconUrl / parentName / developerName) is needed.
+
+**Call:** `GET /services/data/v67.0/query`
+
+**Inputs:**
+
+- `where` *(`String`)* — Optional SOQL WHERE clause to filter Score Category records.
+- `limit` *(`int`)* — Optional SOQL LIMIT value.
+- `q` *(`string`)*
+
+**Depends on:** `describe`
+
+**Output:** Query response with records[] of ScoreCategory — Id plus any SELECTed fields.
+
+**Notes:** soql_relationship_name: SOQL traversal from ScoreCategory back to its parent uses the relationship name "ParentCategory", NOT the
+standard "Parent" token most sObjects expose. A query like "SELECT ParentCategory.CategoryName FROM
+ScoreCategory" succeeds; "SELECT Parent.CategoryName FROM ScoreCategory" returns 400 INVALID_FIELD with
+"Didn't understand relationship 'Parent'". The relationship name is discoverable via
+GET /sobjects/ScoreCategory/describe under fields.ParentCategoryId.relationshipName. When constructing
+tree-view queries agents should traverse via ParentCategory.{field} rather than the generic Parent.{field}.; query_example: SELECT Id, CategoryName, MasterLabel, ParentCategoryId, ParentCategory.CategoryName, Description, IconUrl FROM ScoreCategory ORDER BY ParentCategoryId NULLS FIRST
+
+#### `get-by-id`
+
+Retrieve a specific ScoreCategory record by Id.
+
+**Call:** `GET /services/data/v67.0/sobjects/ScoreCategory/{Id}`
+
+**Inputs:**
+
+- `Id` *(`ID`)* — Id of the ScoreCategory record to fetch.
+
+**Depends on:** `list`
+
+**Output:** Single ScoreCategory record with all readable fields per user FLS.
+
+### Write operations
+
+#### `create`
+
+Create a ScoreCategory record. CategoryName is required (max 25 chars); MasterLabel is the admin display label (max 40). Language defaults to en_US when omitted. DeveloperName auto-derives from CategoryName — override only when a specific API name is needed (must begin with a letter, alphanumeric + underscore only, no consecutive or trailing underscores, unique within the org).
+
+**Call:** `POST /services/data/v67.0/sobjects/ScoreCategory`
+
+**Inputs:**
+
+- `body` *(`object`)* — Field/value map for the new ScoreCategory. Populate from /describe's createableFields list.
+
+**Depends on:** `describe`
+
+**Output:** Standard sObject REST create response — {"id": "<new-Id>", "success": true, "errors": []}. Use the id in downstream get-by-id / update / delete steps. On failure, HTTP status is 400 and body is an array of {"errorCode","message","fields":[...]} entries.
+
+**Rollback:** Call delete with the returned Id to undo the create.
+
+**Notes:** error_contracts: {'duplicate_developer_name': '400 DUPLICATE_VALUE (NOT DUPLICATE_DEVELOPER_NAME) when a POST supplies a DeveloperName already in use. Message is generic ("duplicate value found: <unknown> duplicates value on record with id: <unknown>") — the field name is not echoed, so callers must attribute by context.', 'bad_parent_reference': '400 INSUFFICIENT_ACCESS_ON_CROSS_REFERENCE_ENTITY when ParentCategoryId points at a nonexistent or inaccessible record. Same error covers "no such record" and "record exists but user lacks CRUD/FLS" — the caller cannot distinguish from the error alone.', 'unknown_field': '400 INVALID_FIELD when the body carries a field name not on ScoreCategory ("No such column \'<name>\' on sobject of type ScoreCategory"). Run /describe first to enumerate valid field names.', 'oversized_payload_5xx': 'MasterLabel > ~255 chars can return 500 UNKNOWN_EXCEPTION with a support ErrorId instead of a clean 400 STRING_TOO_LONG. Treat any 500 as a retryable/report-worthy server condition; enforce reasonable client-side length caps rather than probing the boundary.', 'self_parenting_foot_gun': "Wire does NOT reject self-parenting — setting ParentCategoryId to the record's own Id is accepted with 204/201, with no cycle detection. Validate client-side before writing."}
+
+#### `update`
+
+Update an existing ScoreCategory record. Merge-patch semantics.
+
+**Call:** `PATCH /services/data/v67.0/sobjects/ScoreCategory/{Id}`
+
+**Inputs:**
+
+- `Id` *(`ID`)* — Id of the ScoreCategory to update.
+- `body` *(`object`)* — Partial field/value map — only include fields you want to change.
+
+**Depends on:** `get-by-id`
+
+**Rollback:** GET the record before update to capture the prior state, then PATCH the same fields back with the captured values to undo.
+
+**Notes:** error_contracts: {'system_field_write': '400 INVALID_FIELD_FOR_INSERT_UPDATE when PATCH body includes a non-updateable/system field (CreatedDate, CreatedById, LastModifiedDate, LastModifiedById, SystemModstamp, IsDeleted, Id).', 'null_clears_optional': 'PATCH with a field set to null returns 204 and clears the value (verified on Description). Use this instead of omitting the field, which would preserve the prior value under merge semantics.', 'developer_name_mutable': 'DeveloperName can be renamed via PATCH — wire returns 204 and the record reflects the new value on read-back. The base sObject uniqueness constraint still applies (renaming to a value already in use returns 400 DUPLICATE_VALUE).'}; field_constraints_on_patch: CategoryName remains capped at 25 chars under PATCH. MasterLabel and Description are enforced more loosely than /describe reports (short overflows accepted; very large payloads may 500). Language stays restricted-picklist.
+
+#### `delete`
+
+Delete a ScoreCategory record.
+
+**Call:** `DELETE /services/data/v67.0/sobjects/ScoreCategory/{Id}`
+
+**Inputs:**
+
+- `Id` *(`ID`)* — Id of the ScoreCategory to delete.
+
+**Depends on:** `get-by-id`
+
+**Notes:** cascade_delete: Deleting a parent ScoreCategory automatically deletes all its children (ChildScoreCategories relationship carries
+cascadeDelete=true). A subsequent GET on a child record after the parent is deleted returns 404 NOT_FOUND;
+a subsequent DELETE on the same child returns 404 INVALID_CROSS_REFERENCE_KEY instead — not 204 either way,
+but the two verbs report different error codes for the same gone-due-to-cascade record. Callers who need
+to delete only the parent and re-parent children must first PATCH each child's ParentCategoryId to null
+or to another parent before deleting the original parent.; developer_name_uniqueness_release: A hard DELETE releases the DeveloperName uniqueness constraint immediately — a subsequent POST with the same
+DeveloperName the deleted record used returns 201, not the DUPLICATE_VALUE error a still-live record would
+produce. This makes delete-then-recreate a valid pattern for renaming or shape-correcting a category without
+needing an intermediate name. There is no Recycle Bin restore path for ScoreCategory (it is not a standard
+soft-delete sObject), so the release is permanent.