@salesforce/afv-skills 1.63.0 → 1.65.0

package/skills/nonprofit-fundraising-configure/references/mcp-invocation.md

@@ -0,0 +1,678 @@
+# MCP invocation reference — nonprofit-fundraising-configure
+
+## Contents
+
+- Tool argument shape
+- MCP client registration and External Client App setup
+- Phase 0 caching rules
+- Front-loading Phase 1's live checks
+- Discovery-first approach for Fundraising-specific operations
+- Identifying the current authenticated user
+- Confirm-to-write checkpoint
+- Person Accounts enablement (Layer 0) and Fundraising's dedicated enablement confirmation
+- Status-recap table format
+- Optional enhanced features (step 12)
+- Error taxonomy
+
+## Tool argument shape (IMPORTANT)
+
+`mcp__headless-360__dispatch` and `mcp__headless-360__dispatch_readonly` both take raw HTTP:
+
+```json
+{
+  "url": "/services/data/vXX.0/...",
+  "method": "GET|POST|PATCH",
+  "body": { /* optional; required for POST/PATCH */ },
+  "queryParams": { /* required for SOQL — see note below */ }
+}
+```
+
+They do **not** take `{operation_id, arguments}` — that shape returns `INVALID_ARGUMENT: 'url'
+and 'method' are required`. Every example below uses the `{url, method, body?, queryParams?}`
+shape.
+
+**`queryParams` is camelCase, not `query_params`** — `query_params` (snake_case) is silently
+ignored (the request reaches Salesforce with no `q` at all, surfacing as a confusing
+downstream `400 MALFORMED_QUERY: "A query string has to be specified"`, or as a gateway-side
+`ROUTE_NOT_FOUND`/`404` depending on whether an inline querystring was also present). For a SOQL
+call (`GET /services/data/vXX.0/query`), an inline querystring in `url` (`?q=...`) is **actively
+rejected** — `400 INVALID_ARGUMENT: 'url' must not contain an inline query string — pass query
+parameters via the 'queryParams' argument instead` — it is not merely "an alternative" to
+`queryParams` as one might assume; `queryParams` is the only working mechanism for this server.
+Always call SOQL as `{"url": "/services/data/vXX.0/query", "method": "GET", "queryParams": {"q":
+"SELECT ..."}}`.
+
+`discover` and `describe` are the indexing/schema tools:
+
+- `mcp__headless-360__discover(query="<free text>")` — returns candidate indexed operations.
+  A miss does **not** mean the route is absent — standard Data API paths (`/query`,
+  `/sobjects/<Type>`) can be dispatched directly even when `discover` doesn't surface them.
+- `mcp__headless-360__describe(id=<operation_id>)` — returns the input/output schema for a
+  discovered operation. Always call this before a `dispatch` write.
+
+**Response envelope**: `dispatch*` returns `{ "status_code": 200, "body": <REST response> }`.
+Read `body`. A create returns `body.id` and `body.success == true`; a query returns
+`body.records[]`. Status codes: `200/201` success; `400` bad body (re-check schema via
+`describe`); `401` the MCP session needs re-auth; `403` the executing user is missing a
+permission; `404` the endpoint/sObject is not present on this org (surfaces separately as the
+licensing/prerequisite checks in `SKILL.md` Phase 1); `500` a downstream dependency issue.
+
+---
+
+## MCP client registration and External Client App setup
+
+Every org that dispatches through headless-360 needs a one-time **External Client App (ECA)**
+registered in that org, plus the **headless-360 MCP Server** activated (Setup → MCP Server
+Configuration). This is an org-admin, one-time task — not something this skill can do for
+itself, since it is the very session credential the skill's own `dispatch*` calls depend on.
+
+Required ECA configuration:
+
+- Enable OAuth. OAuth Scopes: "Perform requests at any time (refresh_token, offline_access)"
+  and "Access Salesforce hosted MCP servers (mcp_api)".
+- Flow Enablement: check "Enable Authorization Code and Credentials Flow"; leave "Require user
+  credentials in the POST body" unchecked (that sub-flow is for a different credential-embedding
+  variant, not the standard browser/PKCE flow).
+- Security: leave PKCE and JWT-based access tokens for named users on (org-enforced defaults).
+- After creation: set OAuth Policies (Permitted Users, IP Relaxation if the org enforces login
+  IP ranges), then Setup → MCP Servers → `headless-360` → Activate. ECA propagation can take up
+  to 30 minutes; MCP Server activation up to 2 minutes.
+
+If a `discover`/`describe`/`dispatch*` call returns `401`, the MCP client is not authenticated to
+the target org (session expired or the ECA/activation above is incomplete) — halt and surface the
+raw error rather than retrying blindly.
+
+---
+
+## Phase 0 caching rules
+
+`SKILL.md`'s Phase 0 (skip-if-already-known) is modeled on the identical section in
+`service-itsm-incident-mgmt-configure/SKILL.md`. What qualifies as cache-eligible this session,
+scoped to the current org (the `headless-360` session binds to one org via JWT):
+
+**Cache-eligible** — a fact from a successful tool response this session, for the current org:
+- `describe` schemas for any operation used below (`GiftDesignation`, `FundraisingConfig`,
+  Fundraising feature toggles, `PermissionSet`/`PermissionSetGroup`, the optional-features
+  operations) — stable within a session; reuse rather than re-`describe` the same operation twice.
+- A prior `dispatch_readonly` read of `personAccountsEnabled`, `fundraisingLicensed`,
+  `orgPreferenceEnabled`, permission set/group resolution and `Status`, current feature-toggle
+  values, or the optional-features org preferences — reuse rather than re-querying, **unless**
+  a `dispatch` write elsewhere in this session could have changed that specific fact (this
+  skill's own writes, or a parent orchestrator's), in which case re-read.
+
+**Never cache-eligible:**
+- A user's verbal claim ("I already enabled it," "done") — only a live tool response is
+  authoritative. This is what Layer 0's pause-gate re-check and step 13's final verification
+  exist to enforce, and Phase 0 never overrides either: both always re-read live regardless of
+  what was cached earlier in the run, because their entire purpose is verifying an out-of-band
+  action (Setup UI, or a write whose response alone isn't proof) actually took effect.
+- Anything from before a possible org-binding change. If the user hints at a different org, or
+  it's unclear which org an earlier fact came from, re-read rather than trust the cache.
+
+When in doubt, re-check — a wrong skip on a live org write is worse than one duplicated read.
+
+---
+
+## Front-loading Phase 1's live checks (SKILL.md Workflow)
+
+Each of steps 6–11 already needs a live read before deciding whether to write anything (Phase 0
+caching above). Rather than resolving that read in step order — discover, describe, query,
+maybe-write, repeat — resolve all six live checks as early as Phase 1 allows, before starting
+Phase 3's writes: perm-set/group assignment coverage (6, 8), `orgPreferenceEnabled` (7), an
+existing default `GiftDesignation` (9), `FundraisingConfig` field values (10), and the six
+feature-toggle states (11).
+
+"Batched" describes *when* these reads happen (grouped together, ahead of the writes), never *how
+many* — this is still five to seven separate live queries, one per fact family above, each needing
+its own `dispatch_readonly` (a single Tooling read of the toggle fields covers all six toggles in one
+call, but perm-set coverage, `orgPreferenceEnabled`, `GiftDesignation`, and `FundraisingConfig` are
+each a distinct object and need their own separate query). Collapsing this to one or two calls
+total and calling it "batched" is under-verification, not the fast path this describes — it risks
+concluding steps are complete when they were never actually checked.
+
+This applies even when a request says "core setup is already done, skip it": the live batch is
+still the minimum bar, not an optional extra — run every one of these reads regardless of what the
+request claims, since a claim is never a substitute for a live query. Any step the batch confirms
+is already satisfied moves straight to step 12's gate without its own discover/describe/confirm
+cycle; any step the batch shows missing or wrong still gets the full step-by-step flow to fix it,
+and every one of these facts must still be recorded in `state.json`'s per-step booleans even when
+the request says to skip past them — "already done" shortens the path to step 12, it never
+shortens what gets written to `state.json`.
+
+---
+
+## Discovery-first approach for Fundraising-specific operations
+
+The exact operation IDs backing Nonprofit Cloud Fundraising can still be org- and
+release-version-dependent, but the underlying object/field/type names are known and should be
+used to target discovery rather than guessed at blind:
+
+- `GiftDesignation` — standard sObject, `Name`/`IsActive`/`IsDefault`. Data API create/query.
+- `FundraisingConfig` — settings type governing gift/recurring-donation-failure handling
+  (`installmentExtDayCount`, `lapsedUnpaidTrxnCount`, `failedTransactionCount`,
+  `shouldCreateRcrSchdTrxn`, `shouldClosePaidRcrCmt`). This is a
+  **Metadata API construct** in the underlying platform — confirm a Data/Tooling REST route
+  exists via `describe` before attempting a `dispatch` write; if none exists, that is a real
+  capability gap, not a routing miss.
+- `enableFundraising` — the org-wide Fundraising enablement flag. It's owned by the
+  `FundraisingSettings` skill and set through its named `set-fundraising-org-preference` operation
+  (`describe` it first), unlike `FundraisingConfig` above. Because it's a one-way, irreversible, org-wide enable — unlike the six feature toggles,
+  which are independently reversible — it gets its own dedicated warning and confirmation
+  (`SKILL.md` Phase 2 step 5) before Phase 3 step 7 dispatches it, on top of the ordinary
+  confirm-to-write checkpoint. Read its state via the `FundraisingSettings`
+  skill's `get-settings-view-model` (`orgPreferenceEnabled`) early, in Phase 1 — do this before, not after, resolving permission sets
+  — since `orgPreferenceEnabled = false` also means `GiftDesignation` won't resolve as a queryable
+  sObject and `save-fundraising-settings` will refuse to write.
+- `PermissionSet` — Fundraising's name has been observed as both `force__FundraisingAccess` and
+  unprefixed `FundraisingAccess` across orgs; query for both candidates.
+- `PermissionSetGroup` — `Fundraising_Admin`/`Fundraising_User` (`DeveloperName`); check
+  `Status = 'Updated'` (not `'Updating'`) before assigning.
+
+### FundraisingConfig field defaults
+
+Fields: `installmentExtDayCount`, `lapsedUnpaidTrxnCount`, `failedTransactionCount`,
+`shouldCreateRcrSchdTrxn`, `shouldClosePaidRcrCmt`. If the user hasn't stated a preference,
+reasonable operational defaults are `installmentExtDayCount=1`, `lapsedUnpaidTrxnCount=3`,
+`failedTransactionCount=1`, `shouldCreateRcrSchdTrxn=true`, `shouldClosePaidRcrCmt=true`.
+
+`donorMatchingMethod` is deliberately **not** written: a new org defaults it to `No_Matching`, and
+setting `Duplicate_Management_Rules` would also require the inactive Person Account matching and
+duplicate rules to be activated manually in Setup. Leave it at the platform default unless the
+admin explicitly asks for it.
+
+`DonorExternalIdField` is a separate `FundraisingConfig` field (the donor-lookup External ID) and
+is reachable via a plain Data API update — no Metadata-API caveat here. Its Setup UI control shows
+disabled/greyed on many orgs; that is **not** a Fundraising-sequencing gate, it is conditional on
+the org having a field marked as an external ID on the donor object. Resolve it deterministically —
+`IsExternalId` is NOT a queryable column on `FieldDefinition` or `EntityParticle` (400
+`INVALID_FIELD` on both, regardless of org). The only correct source is a full object describe —
+`dispatch_readonly` `GET /services/data/vXX.0/sobjects/<donor object>/describe`, then scan its
+`fields[]` client-side for an entry with `externalId: true`:
+
+```text
+fields[] entries look like: { "name": "...", "externalId": true|false, "idLookup": ..., ... }
+```
+
+If a match exists, set `DonorExternalIdField` to that field's `name`; if none exists, fall back to
+the donor name field. No admin prompt is needed either way — this is fully determined by what the
+org's schema already has. The describe response is large (100K+ characters for a standard object
+like `Contact`) — that's expected for this call, not a sign something's wrong.
+
+### Fundraising feature toggles
+
+None of these toggles are written through the `IndustriesSettings` Metadata API — that surface is
+not available on every org, so this skill never uses it for a write. Of the six toggles, two route
+through separate named controllers, and the remaining four route through a generic Setup
+org-preference operation. See the last bullet below for why a seventh candidate toggle was dropped
+from this skill. Re-`describe`/re-test on any new org before assuming this generalizes.
+
+There is no `enableEnhancedCommitmentProcessor` toggle to dispatch: NextGen Commitment Processing
+(org preference `FrEnhancedCmtPrscrEnabled`) is force-enabled as a side effect of `FundraisingSettings`'
+Layer-0 `set-fundraising-org-preference` call (which
+co-enables it alongside the base Fundraising and Gift Entry Grid preferences, unconditionally, no
+branch). `FundraisingSettings.save-fundraising-settings`'s `isNextGenCmtPrcsParallel` field is a
+separate, unrelated parallel-execution tuning knob for an already-enabled feature — it does not
+enable or disable NextGen Commitment Processing, so don't dispatch it under the assumption that it
+does.
+
+- **Not `IndustriesSettings` at all — use the named controller/operation directly**:
+  `enableGiftEntryGrid` → the `FundraisingGiftEntrySettings` skill's grid-preference toggle;
+  `enableSourceCodeGeneration` → the `FundraisingSourceCodeGen` skill's `set-source-code-generation-enabled`.
+  `describe` each skill and follow it rather than restating its route or body here.
+  Never write these two as `IndustriesSettings` fields — the field names exist in the metadata
+  schema but the real write path is elsewhere.
+- **Generic Setup org-preference operation**: `enableGiftPlanning` → `GiftPlanningEnabled`;
+  `enableGiftAgreement` → `GiftAgreementEnabled`; `enablePhilResearchAgent` →
+  `PhilResearchAgentEnabled`; `enableInteractionSummaryPref` → `InteractionSummaryPref`. Write via
+  `platform.setup.setup-metadata.setOrgPreference` (`PATCH
+  /headless/invoke/platform/setup/setup-metadata/set-org-preference`, body `{"orgPreferences":
+  {"<Name>": <bool>}}`). Do **not** use this operation's read side (`isOrgPreferenceEnabled`) for
+  verification: it takes a list-valued parameter that the dispatch path cannot carry, so
+  the call fails `400 REQUEST_ERROR "Invalid request"` however it is encoded — not a usage mistake. Verify instead with the best-effort Tooling read described under "Verifying a toggle" below.
+
+  `GiftPlanningEnabled`, `GiftAgreementEnabled`, `PhilResearchAgentEnabled` — enable/disable both
+  verified. `InteractionSummaryPref` — enable works; **disabling this one field currently fails**
+  (`500`), so it's not a routing issue — don't rely on disable for this field without
+  re-verifying. Its access-check mismatch
+  (a cross-industry entitlement rather than a Fundraising-owned check) does not block
+  enable on a Fundraising-provisioned org — cross-industry access is commonly co-provisioned, so
+  don't assume the mismatch blocks this toggle.
+- **Not routed anywhere — dropped from this skill**: `enableActionPlanTaskComment` has no entry in
+  the generic operation's access map, and there is no safe alternative write path. Out of scope for
+  this skill.
+
+All six toggles ride `SKILL.md` step 5's single confirm-to-write checkpoint — never add a
+separate confirmation per toggle, including for `enablePhilResearchAgent`.
+
+**Verifying a toggle**: `IndustriesSettings` may be readable via the Tooling API, but it is not
+present on every org, so treat this read as best-effort. `dispatch_readonly` a Tooling query:
+`{"url": "/services/data/vXX.0/tooling/query", "method": "GET", "queryParams": {"q": "SELECT
+<ToolingFieldName> FROM IndustriesSettings"}}`. The Tooling field name is **not** the write-side
+preference name — the mapping is `enable<X>Pref` → `Is<X>PrefEnabled`, e.g.
+`enableInteractionSummaryPref` → `IsInteractionSummaryPrefEnabled`; fields newer than the API
+version in the URL return `400 INVALID_FIELD`, so query a recent version (`v68.0`+) before
+concluding a field is missing. If the object itself is unavailable on the org (query fails with
+`INVALID_TYPE`, `404`, or a persistent `INVALID_FIELD` at a recent version), **do not fall back to
+any metadata write or deploy** — report the toggle as "written, unverified" and tell the admin to
+confirm it in Setup. Never trust a write response alone when a read-back is available.
+
+Discovery procedure:
+
+1. `discover` with free-text queries targeting the above (e.g. `"Fundraising settings"`,
+   `"Gift Designation object"`, `"Nonprofit Cloud permission set group"`).
+2. `describe` every candidate operation before using it, to get the authoritative field list and
+   confirm it's actually dispatchable via REST (not Metadata-API-only).
+3. When `discover` returns nothing for a standard Data API shape (`PermissionSet`,
+   `PermissionSetGroup`, `RecordType`, `GiftDesignation` are core/standard sObjects), probe the
+   documented path directly with `dispatch_readonly` rather than treating the `discover` miss as
+   a hard failure.
+4. If a direct probe also 404s, or `describe` shows no REST-dispatchable route for a
+   Metadata-API-only construct (`FundraisingConfig`), that is a real
+   signal — report it as a missing prerequisite or capability gap rather than guessing at an
+   alternative path.
+
+### Enabling Fundraising (`set-fundraising-org-preference`)
+
+`enableFundraising` is not one of the six toggles above — it's the master org-wide switch, and
+unlike those six, it's irreversible rather than independently reversible. It rides its own
+named headless-360 operation, `set-fundraising-org-preference`,
+which turns on the org preference and writes the default `FundraisingConfig` row in the same
+transaction.
+
+- Dispatch: `describe` the `FundraisingSettings` skill first, same as any other write, and follow its
+  `set-fundraising-org-preference` step rather than restating its route or body here.
+- Verify via that skill's `get-settings-view-model` read → `orgPreferenceEnabled = true` (the same
+  read as Phase 1 step 4).
+- Because this write is irreversible and org-wide (unlike the reversible feature toggles), `SKILL.md` Phase 2
+  step 5 requires its own dedicated warning + `AskUserQuestion` confirmation before Phase 3 step 7
+  dispatches it — in addition to, not replacing, the plan-wide confirm-to-write checkpoint that
+  covers every other write in the plan.
+- If a live `dispatch`/`describe` attempt on this exact org shows no dispatchable route for
+  `set-fundraising-org-preference` at all, treat that as a blocking capability gap and stop — there is no
+  supported alternative write for this field, so do **not** fall back to a Metadata API write.
+- `navigate-fundraising-turn-on` remains available as an optional, human-driven alternative for an
+  admin who'd rather perform this specific irreversible action themselves through Setup.
+
+---
+
+## Identifying the current authenticated user
+
+`PermissionSetAssignment` writes must target a human user, but this MCP server exposes no
+dedicated "who am I" endpoint, and the obvious Connect API route
+(`GET /services/data/vXX.0/connect/user-profiles/me`, and `/chatter/users/me`) can be disabled on
+the org entirely (`403 FUNCTIONALITY_NOT_ENABLED`) — seen live. `GET /services/oauth2/userinfo`
+is also not proxied by this server (`ROUTE_NOT_FOUND`).
+
+Fallback heuristic when both of those fail:
+
+1. Query active users: `SELECT Id, Username, Name, UserType, IsActive, ProfileId FROM User WHERE
+   IsActive = true AND UserType = 'Standard' ORDER BY LastLoginDate DESC NULLS LAST`.
+2. `UserType = 'Standard'` alone is **not sufficient** — built-in integration/bot accounts (seen
+   live: "SalesforceIQ Integration", "Insights Integration", "Bot User", "DigitalAgent.*") also
+   carry `UserType = 'Standard'`. Exclude names matching those patterns.
+3. Cross-check the remaining candidates' `ProfileId` against `Profile.Name` — prefer one that
+   resolves to `'System Administrator'`.
+4. Prefer the most recent `LastLoginDate` among what's left.
+
+This is an inference, not a guarantee — state that explicitly when reporting which user was used
+as the assignee, so a human reviewing the run can correct it if wrong.
+
+---
+
+## Confirm-to-write checkpoint (REQUIRED)
+
+Before any `dispatch` write that assigns a permission set/group, creates the default Gift
+Designation record, enables Fundraising, or flips a feature toggle, present the full plan via
+`AskUserQuestion` and wait for explicit confirmation. This mirrors the confirm-to-write pattern in
+`service-itsm-incident-mgmt-configure` and `service-itsm-agentic-setup-uel-user-create` — the
+distinction from the pause-and-resume gate below is that these actions are ones the *agent itself*
+can perform after a "yes." Fundraising enablement rides this checkpoint too, but — because it's
+irreversible and org-wide, unlike every other write here — it also gets its own dedicated warning
+and confirmation on top of it; see the next section.
+
+## Person Accounts enablement (Layer 0) and Fundraising's dedicated enablement confirmation
+
+A real headless enablement chain exists: `discover(query="enable Person Accounts")` surfaces
+`hr-service-person-account-setup`, and `describe` on it returns a full, `implemented`-status chain
+including `accept-terms-and-conditions` and `enable-person-accounts`. This was Setup-UI-only
+historically; it no longer is. But that SOR is **HR-Service's own workflow**, not
+Fundraising's, so this skill must never delegate to it or run its step list — call exactly the four operations
+below, directly by path, and nothing else. This is an allowlist, not a skip-list: whatever other
+steps that SOR contains today, adds, or renames later, this skill is unaffected as long as these
+four paths keep working, because it never calls the SOR by id in the first place.
+
+1. `GET /headless/invoke/platform/person-account-settings/check-person-account-readiness` — returns
+   `personAccountsEnabled`, `termsConditionsAccepted`, `accountRecordTypeCreated`, `profilePermsSet`,
+   `orgWideSharingSet`, `allStepsComplete`. If `personAccountsEnabled` is already `true`, skip the
+   rest of this chain. `accountRecordTypeCreated` and the profile-visibility gate are already
+   satisfied by this skill's own Business Account record type and profile-visibility sub-checks
+   below — run those first if either gate is still false. If `profilePermsSet`/`orgWideSharingSet`
+   are false for a reason not covered by those sub-checks, fall back to the manual Setup UI gate for
+   just the unmet gate rather than blocking the whole chain on it.
+2. `PATCH /headless/invoke/platform/person-account-settings/accept-terms-and-conditions` once
+   `accountRecordTypeCreated` is true. Re-read step 1 and assert `termsConditionsAccepted = true`
+   before continuing — never trust the `PATCH` response alone.
+3. **Explicit confirmation, then the irreversible write.** `enable-person-accounts` is documented
+   IRREVERSIBLE by the operation itself ("Do NOT call without explicit user confirmation") — gate it
+   exactly like Fundraising's own dedicated enablement confirmation below: warn that it's irreversible
+   and org-wide, get an explicit `AskUserQuestion` confirmation, then `PATCH
+   /headless/invoke/platform/person-account-settings/enable-person-accounts`. On decline, stop, zero
+   further writes, `STOPPED_PERSON_ACCOUNTS_MISSING`.
+4. Re-verify via step 1's `GET` again (`personAccountsEnabled = true`) and the existing
+   `FieldDefinition` check Layer 0 already runs (`IsPersonAccount` on `Account`, `totalSize > 0`) —
+   never trust the `PATCH` response alone. Post-enable artifacts can materialize asynchronously; if
+   the re-check doesn't show it immediately, wait a couple of seconds and retry once before treating
+   it as a real failure.
+
+**Why an allowlist, not a skip-list**: as of this writing, the discovered SOR's other steps create
+an `Employee` record type, assign it to profiles, and enable `ReportsToOnPersonAccount` —
+HR-Service's data model, not Fundraising's. That's context for *why* this skill only calls the four
+paths above, not a maintained list to keep excluding — don't add "and also skip step N" here when
+the SOR changes; the four operations above are the entire contract regardless.
+
+If `discover` ever stops returning this operation, or `describe` no longer shows it as
+`implemented`, fall back to the old live pause-and-resume gate: present the exact manual Setup
+steps, ask via `AskUserQuestion` whether the admin has completed them, and re-run the readiness
+check before trusting it either way — a "yes, I did it" is a claim, not a fact.
+
+Fundraising enablement (Phase 1 step 4 / Phase 2 step 5) uses the same confirm-then-dispatch
+pattern — a single named `PATCH` operation, `set-fundraising-org-preference` (see "Enabling
+Fundraising" above), gated the same way as `enable-person-accounts` above.
+
+**Person Accounts (Phase 2 step 5)** — Layer 0 only detects; ask for confirmation as part of the
+plan, *before any write in this chain*, including the Business Account record type check/create
+below: it's reversible on its own, but a normal Fundraising request must not touch org metadata
+without consent when Person Accounts isn't enabled yet. This single confirmation also satisfies
+step 3's gate above — don't ask twice. Phase 3 step 6a performs the writes only after it. The prompt:
+*"Person Accounts isn't enabled on this org. Nonprofit Cloud Fundraising models donors as Person
+Accounts, so none of the setup below can proceed without it. I'll create a Business Account record
+type (reversible) and then enable Person Accounts (irreversible, org-wide) via the same headless
+operations Setup uses. Proceed?"* Options: *"Yes — proceed"* / *"Stop here"*. On "Yes," check/create
+the record type (see "Business Account record type" below), then run the chain above; re-check
+readiness before continuing either way.
+
+**Fundraising org preference (Phase 2 step 5)** — Warn, don't redirect: *"Enabling Fundraising
+permanently turns on all Fundraising objects and functionality for this org and cannot be
+reversed. I'll dispatch the Fundraising enablement operation — do you want to proceed?"* Options:
+*"Yes — enable it"* / *"Stop"*. On "Yes," Phase 3 step 7 dispatches
+`set-fundraising-org-preference` and re-verifies via `get-settings-view-model` →
+`orgPreferenceEnabled` before treating it as done — never trust the dispatch response alone.
+"Stop" ends the run with zero writes — no permission set/group assignment or any other step —
+in `STOPPED_ENABLEMENT_NOT_CONFIRMED`.
+
+For Person Accounts: if a re-check still fails after the confirmed write, say so plainly (propagation
+delay, or the write itself errored) and re-run the chain from step 1 rather than assuming success —
+never trust a "done" claim or a `PATCH` response alone.
+
+For Fundraising: if the re-check after dispatching `set-fundraising-org-preference` still shows
+`orgPreferenceEnabled = false`, treat it as a write issue, not a Setup-UI claim problem — check
+the `dispatch` response for errors, and retry once before reporting `STOPPED_OTHER` with the error
+as `stopReason`.
+
+### Person Accounts record-type profile visibility (a Layer 0 sub-check, distinct from enablement)
+
+Layer 0's `FieldDefinition` check only confirms Person Accounts is enabled org-wide (the
+`IsPersonAccount` field exists on `Account`) — it does **not** confirm any non-admin profile can
+actually select or default to the Person Account record type. These are two different layers:
+Person Accounts being enabled vs. a **profile** having `recordTypeVisibilities` for the record type.
+Person Accounts being enabled (`personAccountsEnabled: true`, `Account.Person Account` record type
+active) does not imply any profile has visibility for it. System Administrator can still select
+every record type (implicit access), but neither profile necessarily has Person Account as its
+default, and **Standard User** may not be able to select it until this is set. A profile retrieve
+cannot tell you which — see the verify bullet below for how to read the real state.
+
+Unlike Person Accounts enablement itself, this is **not** irreversible or Setup-UI-only, so it
+doesn't need the pause-and-resume treatment — it's an ordinary declarative Metadata API deploy,
+same class as the other Profile/PermissionSet writes this skill already performs.
+
+- **Target state, for both `Standard User` and `System Administrator`**: both
+  `Account.Business_Account` and `PersonAccount.PersonAccount` are in the profile's selected record
+  types (`visible: true`), and **Person Account is the default** (`PersonAccount.PersonAccount` gets
+  `default: true` and `personAccountDefault: true`; `Account.Business_Account` gets
+  `default: false`). Setting the default explicitly also covers System Administrator, whose
+  implicit access to every record type does not make Person Account its default.
+- **H360 first, per policy**: `discover` for this returns no dedicated SOR (best hits — "managing-
+  profiles", "UserManagementSettings" — are off-target). The closest real hit is a *step inside* an
+  unrelated workflow SOR, `hr-service-person-account-setup`'s `assign-record-types-to-profiles`
+  step: `PUT /headless/metadata` with `type: "Profile"`, `fullName` = the profile's developer name
+  (`Admin` for System Administrator, `Standard` for Standard User), and an `xmlRep` containing only
+  the `<recordTypeVisibilities>` fragments being set (one per record type) — **PUT, not POST, and a
+  minimal fragment only, never a full-Profile round-trip** (the SOR's own guidance; matches this
+  skill's existing "omit optional fields, let the platform default them" rule). Confirms the
+  mechanism (Metadata API `Profile.recordTypeVisibilities`), not a dispatchable op of its own — it's
+  HR-Service's Business Account/Employee record types, not Fundraising's. Adapt the fragments to
+  `Account.Business_Account` and `PersonAccount.PersonAccount` instead.
+- **Scope is the active human users' profiles** — reuse step 6's human-user set
+  (`IsActive=true AND UserType='Standard'`) and its `Profile.Name` classification (see
+  `references/permission-targeting.md`), which resolves to `System Administrator` (Admin) and
+  `Standard User` (Standard). Apply the target state to both. Any other profile an active human user
+  holds (custom/unclassified) is left alone and reported as manual.
+- **Fallback: Metadata API deploy.** `/headless/metadata` is not available on every org (it returns
+  `404 NOT_FOUND`, even for types that work elsewhere). When the headless `PUT` is rejected or 404s,
+  deploy the same minimal `Profile` fragment through the Metadata API (`sf project deploy start`
+  with a project holding only the two profile files; a `--dry-run` validates first). Each profile
+  file contains only:
+  ```xml
+  <Profile xmlns="http://soap.sforce.com/2006/04/metadata">
+      <recordTypeVisibilities>
+          <default>false</default>
+          <recordType>Account.Business_Account</recordType>
+          <visible>true</visible>
+      </recordTypeVisibilities>
+      <recordTypeVisibilities>
+          <default>true</default>
+          <personAccountDefault>true</personAccountDefault>
+          <recordType>PersonAccount.PersonAccount</recordType>
+          <visible>true</visible>
+      </recordTypeVisibilities>
+  </Profile>
+  ```
+  Profiles merge on deploy, so the fragment does not disturb other profile settings. Only if both
+  routes fail, tell the admin to add both record types under each profile's Record Type Settings in
+  Setup, set Person Account as the default, and report the sub-check as manual.
+- **Verify, don't assume broken**: a Metadata API retrieve of `Profile:Admin`/`Profile:Standard`
+  **alone returns no `recordTypeVisibilities`** — the entries appear only when the record types are
+  in the same retrieve. Retrieve `Profile:Admin`, `Profile:Standard`,
+  `RecordType:Account.Business_Account` and `RecordType:PersonAccount.PersonAccount` together (note
+  the `PersonAccount.` prefix for the person record type), then confirm both entries are present
+  with `visible=true` and that `PersonAccount.PersonAccount` is the default, before reporting this
+  sub-check as resolved. Reading a profile without the record types and concluding "not set" is a
+  false negative.
+
+### Business Account record type (a Layer 0 sub-check, distinct from enablement)
+
+Salesforce enforces creating a Business Account record type as a **hard precondition** for
+enabling Person Accounts at all — it's one of the wizard's own readiness gates
+(`accountRecordTypeCreated`), not an optional nice-to-have. Salesforce does not auto-provision it —
+an org may already have it (`Business_Account`, active) only because an admin created it manually.
+Today this sub-step is invisible, bundled inside the generic Layer 0 manual pause-and-resume gate above
+("Go to Setup → Person Accounts and complete the steps...") — an admin has no way to tell from
+that prompt that record-type creation is one of the things being asked of them.
+
+Unlike Person Accounts enablement itself, this specific write is **not** irreversible or
+Setup-UI-only — it's an ordinary, reversible Metadata API write, the same class of write this
+skill already automates elsewhere. That makes it safe to pull out of the manual bundle and
+automate — but only under the same upfront confirmation gate as the (now also automatable)
+T&C-acceptance and enable-Person-Accounts steps, never ahead of or outside it: see "Person
+Accounts enablement (Layer 0)" above.
+
+- **H360 first, per policy**: `discover` for "create a Business Account record type before
+  enabling Person Accounts" returns no dedicated standalone SOR (best hit, ~0.66, is the *parent*
+  workflow SOR below, not an isolated operation); a second `discover` with `resultType: "endpoint"`
+  confirms the same — no closer match. The closest real hit is again a *step inside* an unrelated
+  workflow SOR, `hr-service-person-account-setup`'s `create-business-account-record-type` step —
+  same pattern as the profile-visibility sub-check above: it's HR-Service's flow, not
+  Fundraising's, so treat it as a lead on the mechanism, not a dispatchable op of its own.
+- **That SOR's documented mechanism is wrong**: its step calls `POST /headless/metadata` with
+  `type: "RecordType"` (a `PUT` with `type: "CustomObject"` wrapping a nested `<recordTypes>` block
+  behaves the same way) — both are rejected with `400 UNSUPPORTED_OPERATION` /
+  `"MetadataCrud does not support CREATE on type: RecordType"`, a flat routing rejection, not a
+  `DUPLICATE_VALUE`. Don't trust an `implemented`-status SOR step's mechanism as proven just because
+  another skill's workflow lists it — verify it before reusing it, same as any carried-over claim.
+- **Working mechanism**: a plain sObject REST create — `POST /services/data/v69.0/sobjects/RecordType`
+  with body `{"Name": "Business Account", "DeveloperName": "Business_Account", "SobjectType":
+  "Account"}` — no Metadata API deploy, no xmlRep. This matches the `CollaborationGroupRecordTypes`
+  SOR's documented pattern for a different object exactly ("Uses the standard RecordType sObject
+  \[…\]. Required fields on create: Name, DeveloperName, SobjectType"), which is what pointed at the
+  right mechanism, and is round-tripped end to end by the companion **Household** record type create
+  below (`201`, re-queried and present).
+- **Sequencing**: no dependency on anything HR-Service-specific — this is a plain, standalone
+  sObject create, clean to run ahead of the Person Accounts manual gate.
+- **Design**: query `SELECT Id, DeveloperName, IsActive FROM RecordType WHERE SObjectType =
+  'Account' AND DeveloperName = 'Business_Account'` first; skip if an active row exists; otherwise
+  `dispatch` the sObject create above; re-query to confirm before continuing to the (now narrower)
+  manual gate for the remaining, genuinely irreversible steps.
+
+### Household record type (optional, standalone — not a Layer 0 precondition)
+
+Unlike Business Account, a Household record type on Account is **not** required by anything —
+Salesforce doesn't gate Person Accounts or any other enablement on it. It's an org-owner
+convenience some admins create alongside Business Account so household-style donors have a
+dedicated record type too, not a requirement.
+
+- **H360 first, per policy**: no dedicated SOR exists. `discover` for "create Household record
+  type on Account for Nonprofit Cloud" and "configure household account record type" both surface
+  only off-target or unrelated hits — FSC's `industries-fsc-householding-connect-api` (a
+  *different*, license-gated Household **object** for wealth-management householding, not an
+  Account record type) and the same `hr-service-person-account-setup` lead as above — no existing
+  precedent to copy, confirming this really is a gap, not a missed lookup.
+- **Mechanism**: same plain sObject create as Business Account — `POST
+  /services/data/v69.0/sobjects/RecordType` with `{"Name": "Household", "DeveloperName":
+  "Household", "SobjectType": "Account"}`. Returns `201`, `success: true`; re-query to confirm
+  present and active (`DeveloperName='Household'`, `IsActive=true`).
+- **Design**: query `SELECT Id, DeveloperName, IsActive FROM RecordType WHERE SObjectType =
+  'Account' AND DeveloperName = 'Household'` first; skip if an active row exists; otherwise
+  `dispatch` the create above; re-query to confirm. Offer this as its own optional step (not folded
+  into Layer 0, since nothing gates on it).
+
+---
+
+## Status-recap table format
+
+Both the core-setup recap immediately before step 12's combined ask, and step 14's final rollup,
+must be a compact **Item | Status** markdown table — never a run-on prose paragraph. A table lets
+the admin see at a glance exactly what's configured vs. what's still optional vs. what needs their
+own manual action, which a sentence buries. Use plain, specific status values (`Enabled`,
+`Assigned (N users)`, `Created`, `Skipped — <reason>`, `Failed — <reason>`, `Manual action required
+— see below`) rather than a generic "done"/"not done".
+
+Pre-step-12 recap (core setup, steps 6–11) — one row per item, e.g.:
+
+| Item | Status |
+|------|--------|
+| Fundraising license | Confirmed |
+| `FundraisingAccess` (org-wide) | Assigned (5 users) |
+| Fundraising org preference | Enabled |
+| Permission set groups (`Fundraising_Admin`/`Fundraising_User`) | Assigned by role |
+| Default Gift Designation | Created ("General Fund") |
+| Basic gift/recurring-donation settings | Configured |
+| Feature toggles (6/6) | Enabled |
+
+Step 14's final rollup extends the same table with whichever optional-feature rows from step 12
+were actually attempted (see "Optional enhanced features" below for what belongs in each row —
+e.g. Record Alerts shows category creation and org-preference guidance as separate rows, since only the first is verifiable), plus a closing `outcome`/`stopReason` line. Never collapse a
+partially-completed feature into a single "done" row — if Life Events' license was assigned but
+the Business Milestones related list still needs the admin's own manual Setup action, say so as
+two distinct rows, not one that implies full completion.
+
+## Optional enhanced features (step 12)
+
+Offered once, combined, via a single `AskUserQuestion` after core setup (steps 6–11) completes —
+never one prompt per feature. Refer to each feature by its product name in the prompt (e.g.
+"Timeline"), never by an underlying metadata field name. Per-feature mechanism, headless-360 only
+(no Metadata API write or CLI deploy for any of them):
+
+- **Interest Tags** — the org preference is owned by the Interest Tagging Setup skill, not the
+  Metadata API. `describe` id `InterestTaggingSettings` and follow its steps for the check, the
+  write and the verification; do not restate or improvise them here. If that skill's access check
+  or write fails (the org or user lacks the Interest Tagging feature or permission, or the type
+  is unavailable), tell the admin to turn on Interest Tagging on the Setup **Interest Tagging
+  Settings** page (`/lightning/setup/InterestTaggingSettings/home`) and never fall back to the
+  Metadata API or the CLI. Once it is on, seed categories via a plain Data API create against
+  `TagCategory`. The `InterestTag` records themselves are Setup-UI-only — there is no Data API
+  create route for them; don't attempt one.
+- **Interaction Summaries** — the `InteractionSummaryPref` org preference (already covered
+  as one of the standard toggles above — see "Fundraising feature toggles" for the write
+  path, live-tested enable/disable behavior, and the access-check caveat) plus assigning the
+  relevant permission set license.
+- **Record Alerts** — two independent parts: the category is automated, the org preferences are
+  manual guidance.
+  1. **Category creation** (Tooling API, not Metadata API or the Data API). No dedicated skill covers this create yet, so the mechanics are here: check for an existing
+     row first with `dispatch_readonly` `GET /services/data/vXX.0/tooling/query` (`XX` = the org's current API
+     version, as for every other versioned path in this skill), `queryParams`
+     `{"q": "SELECT Id, DeveloperName, MasterLabel, Description, Severity FROM
+     RecordAlertCategory"}`. If a row with the intended `DeveloperName` exists, treat it as already
+     satisfied. Otherwise `dispatch` `POST /services/data/vXX.0/tooling/sobjects/RecordAlertCategory`
+     (`describe` first, as for any write) with:
+
+     ```json
+     {
+       "FullName": "<Developer_Name_From_Label>",
+       "Metadata": {
+         "masterLabel": "<admin-provided label>",
+         "description": "<admin-provided description>",
+         "severity": "<Error|Warning|Info>"
+       }
+     }
+     ```
+
+     `FullName` is create-only and becomes `DeveloperName`; `Metadata` carries all the content.
+     `severity` is one of `Error`, `Warning`, `Info`. The key is `masterLabel`, **not** `label` —
+     `label` fails with `XML_PARSER_ERROR`. `DeveloperName`, `MasterLabel`, `Description`,
+     `Severity` and `Language` are read-only projections you can query but not write. A successful
+     create returns `201` with `{"id": "0qX...", "success": true}`; re-run the query above and
+     confirm all four fields match before reporting it done.
+
+     Every value above is a placeholder, not a default. **Never create a category
+     unless the admin has supplied its name in this run.** If the admin selects Record Alerts in the
+     combined step 12 ask, follow up with one `AskUserQuestion` that asks for the category's label
+     (free text) and description, and offers severity as a choice of exactly `Error`, `Warning` or
+     `Info`; derive `FullName` from the label. If no name is given, skip creation and report it as
+     skipped — do not substitute a made-up or example name. Covered by the `FundraisingAccess` permission set from step 6.
+  2. **Org preferences — manual guidance only**: no API route exists today for
+     the Record Alert org preferences, so never probe for one or write them. If the admin opts in at step 12, direct them to complete the steps on the Setup **Record
+     Alert Setup** page (`/lightning/setup/RecordAlertSetup/home`) themselves, and record
+     `optionalFeatures.recordAlerts.orgPrefsOutcome = "manual_guidance_given"`. Do not infer a
+     license gap from anything here; only the admin's own report from that page could establish one
+     (`license_gap`). This part never places the Record Alert Lightning component on a page.
+- **Life Events** — the `LifeEventsAccessPSL` permission set license + a permission set assignment
+  are the only automated part (same mechanism as any other permission set/license grant, no
+  separate handling). Everything else is **manual guidance only — never an automated deploy.** The Setup **Life Events** page
+  (`/lightning/setup/LifeEventsSetup/home`) is a checklist, not a wizard that performs actions:
+  adding the Business Milestones and Person Life Events related lists, adding the Life
+  Events/Business Milestones component to a record page, and creating/activating event or milestone
+  types are all manual to-dos with "Show Me How in Help" links out to documentation. Page layout
+  and Lightning-page placement have no API or automatable route, so if the admin opts in at step 12,
+  direct them to complete the steps on that page themselves and never offer to do it for them. The
+  `BusinessMilestone` object's own records remain fully Data-API-writable — only the
+  page-layout/component placement and type setup are manual.
+- **Timeline** — this is not a plain settings toggle and does not go through any metadata write.
+  It is owned by the approved `Timeline` skill: `describe` it and follow its enable step and the
+  verification it defines, plus its configuration lifecycle (create or update, activate or
+  deactivate, delete) when configs are needed. Don't restate its routes here. **Only the initial
+  enable is treated as irreversible** — give that step its own explicit warning and a separate,
+  specific confirmation in addition to the combined ask above; do not enable it on a bare "yes" to
+  the combined feature list alone. Name the feature simply "Timeline" when asking the admin to
+  confirm. The configs created afterward are ordinary CRUD and don't need the same treatment. This
+  skill never automates Lightning-page component placement; if visual placement is needed, it's
+  manual guidance like Life Events above, never an automated deploy.
+
+Report exactly which of the offered features were actually enabled (and which were skipped or hit
+a confirmed gap) in the final summary — do not assume "offered" implies "enabled."
+
+---
+
+## Error taxonomy
+
+| Status / symptom | Likely cause | Action |
+|---|---|---|
+| `401` | headless-360 MCP client not authenticated to the target org | Halt, surface raw error — session needs re-auth |
+| `local_rate_limited` on `discover` | H360 MCP server-side rate limit — distinct from the LLM gateway's own rate limiting, and not a "no match" | Not fatal: fall back to direct `dispatch_readonly` probes for standard Data API objects; retry after a short delay for Metadata-API-only constructs (`FundraisingConfig`) that have no direct-probe fallback |
+| `403` | Executing user missing a required permission | Halt, report exactly which permission is implicated |
+| `404` on a Fundraising-specific route | Org not licensed for Fundraising, or the object/field doesn't exist at this API version | Treat as a licensing/prerequisite failure, not a routing bug — do not retry with guessed alternate paths |
+| `404` on a core Data API path (`/query`, `/sobjects/<Type>`) | Wrong path or typo — these are always present | Re-check the path against `describe`/documentation before retrying |
+| `400 INVALID_TYPE` on `SELECT ... FROM GiftDesignation` | Fundraising org preference is off, so the package's sObjects (`GiftDesignation`) aren't provisioned yet — not a licensing or path problem | Check `orgPreferenceEnabled` via `get-settings-view-model`; if `false`, treat as the same capability gap as the `IndustriesSettings` enablement block, not a separate bug |
+| `400` on a `dispatch` write | Body doesn't match the schema | Re-`describe` the operation and correct the body — do not retry blindly |
+| `200` on a create, but a later verification query shows the record/flag unchanged | A downstream validation rule silently rejected the change | Report as a failure — never trust the write response alone |
+| `500` on a `dispatch` write (e.g. `PermissionSetAssignment` create) | Can be a genuine failure, **or** a false negative — seen live: a `500` on every attempt, but the record existed on read-back | Never report failure from the write response alone either — re-verify with a read-only query before concluding the write didn't take |
+| `DUPLICATE_VALUE` on a `PermissionSetAssignment`/group-assignment or default `GiftDesignation` create | This skill has no persisted resume state by design — every invocation, whether resuming the same paused session or starting fresh days later, replays Phase 1–3 from the top against live org state, and can re-attempt a write that already succeeded | Query for an existing match (`AssigneeId` + `PermissionSetId`/`PermissionSetGroupId`, or `IsDefault = true` for `GiftDesignation`) before creating; treat a match as already-satisfied, not a failure |