@salesforce/afv-skills 1.58.0 → 1.60.0

package/skills/experience-ui-bundle-metadata-generate/scripts/verify-bundle-location.mjs

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+// Verifies that a UI bundle was created under force-app/main/default/uiBundles/
+// (and not at the repo root, which would be non-deployable), AND that the
+// scaffold itself is complete (package.json, src/, entry index.html present) —
+// not just a hand-authored metadata-only directory.
+//
+// The entry index.html lives at the bundle root for React (reactbasic) and at
+// src/index.html for Angular (angularbasic), so both locations are accepted.
+//
+// If a custom output directory was used (--output-dir on the scaffold command),
+// pass it as the second argument. The script then verifies the bundle exists
+// there instead of assuming the default location. Pass the framework
+// (react|angular) as the third argument so the remediation hint uses the right
+// --template flag; pass "" for the second argument to supply only a framework.
+//
+// Usage: node verify-bundle-location.mjs <BundleName> [<CustomOutputDir>] [<framework>]
+//
+// Always invoke via `node` (never as a bare executable) so this works on
+// Windows cmd/PowerShell as well as macOS/Linux/Git Bash.
+
+import fs from "node:fs";
+import path from "node:path";
+
+const args = process.argv.slice(2);
+
+if (args.length < 1 || args.length > 3) {
+  console.log("ERROR: Bundle name required");
+  console.log("Usage: node verify-bundle-location.mjs <BundleName> [<CustomOutputDir>] [<framework>]");
+  process.exit(1);
+}
+
+const BUNDLE_NAME = args[0];
+const CUSTOM_OUTPUT_DIR = args[1] ?? "";
+const FRAMEWORK = args[2] ?? "";
+
+// Pick the remediation template and the expected entry-HTML location from the
+// framework. When the framework is not supplied we stay lenient: default the
+// hint to reactbasic and accept the entry index.html at either location.
+let TEMPLATE;
+let ENTRY;
+switch (FRAMEWORK) {
+  case "angular":
+    TEMPLATE = "angularbasic";
+    ENTRY = "src/index.html";
+    break;
+  case "react":
+    TEMPLATE = "reactbasic";
+    ENTRY = "index.html";
+    break;
+  default:
+    TEMPLATE = "reactbasic";
+    ENTRY = "";
+    break;
+}
+
+function isFile(p) {
+  try {
+    return fs.statSync(p).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function isDir(p) {
+  try {
+    return fs.statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+// Checks that the scaffold actually produced a full project, not just
+// hand-written metadata files. Returns false (and prints guidance) if
+// incomplete.
+function checkScaffoldComplete(bundlePath, outputDir = "") {
+  const missing = [];
+  if (!isFile(path.join(bundlePath, "package.json"))) missing.push("package.json");
+  if (!isDir(path.join(bundlePath, "src"))) missing.push("src/");
+  // Entry HTML lives at the bundle root for React and at src/index.html for
+  // Angular. When the framework is known, require the correct location; when
+  // it is unknown, accept either.
+  if (ENTRY) {
+    if (!isFile(path.join(bundlePath, ENTRY))) missing.push(ENTRY);
+  } else if (!isFile(path.join(bundlePath, "index.html")) && !isFile(path.join(bundlePath, "src", "index.html"))) {
+    missing.push("index.html");
+  }
+
+  if (missing.length > 0) {
+    let scaffoldCmd = `sf template generate ui-bundle -n ${BUNDLE_NAME} --template ${TEMPLATE}`;
+    if (outputDir) {
+      scaffoldCmd = `${scaffoldCmd} --output-dir "${outputDir}"`;
+    }
+    console.error(`ERROR: Bundle found at ${bundlePath}, but the scaffold is incomplete. Missing:`);
+    for (const item of missing) {
+      console.error(`  - ${item}`);
+    }
+    console.error("");
+    console.error("This usually means 'sf template generate ui-bundle' was never run — metadata");
+    console.error("files alone were hand-authored instead. Run the scaffold command now:");
+    console.error(`  ${scaffoldCmd}`);
+    console.error("Metadata files are configuration ON TOP of the scaffold, not a substitute for it.");
+    return false;
+  }
+  return true;
+}
+
+if (CUSTOM_OUTPUT_DIR) {
+  const customPath = path.join(CUSTOM_OUTPUT_DIR, BUNDLE_NAME);
+  if (isDir(customPath)) {
+    if (checkScaffoldComplete(customPath, CUSTOM_OUTPUT_DIR)) {
+      console.log(`OK: Bundle found at ${customPath} (custom output-dir location, scaffold complete)`);
+      process.exit(0);
+    }
+    process.exit(1);
+  }
+  console.log(`ERROR: Bundle not found at custom output-dir location: ${customPath}`);
+  console.log("Check that --output-dir matched what was passed to the scaffold command.");
+  process.exit(1);
+}
+
+const EXPECTED_PATH = path.join("force-app", "main", "default", "uiBundles", BUNDLE_NAME);
+const WRONG_PATH = path.join("uiBundles", BUNDLE_NAME);
+
+if (isDir(EXPECTED_PATH)) {
+  if (checkScaffoldComplete(EXPECTED_PATH)) {
+    console.log(`OK: Bundle found at ${EXPECTED_PATH} (deployable location, scaffold complete)`);
+    process.exit(0);
+  }
+  process.exit(1);
+}
+
+if (isDir(WRONG_PATH)) {
+  console.log(`ERROR: Bundle found at repo root: ${WRONG_PATH}`);
+  console.log("This location is NOT deployable. The SFDX deploy command will not find it.");
+  console.log("");
+  console.log("To fix: Move the bundle to force-app/main/default/uiBundles/");
+  console.log(`  Create the directory force-app/main/default/uiBundles/ (if it doesn't exist),`);
+  console.log(`  then move ${WRONG_PATH} to ${EXPECTED_PATH}.`);
+  console.log("");
+  checkScaffoldComplete(WRONG_PATH);
+  process.exit(1);
+}
+
+console.log("ERROR: Bundle not found at either location:");
+console.log(`  - Expected: ${EXPECTED_PATH}`);
+console.log(`  - Also checked: ${WRONG_PATH}`);
+console.log("");
+console.log("If a custom --output-dir was used, re-run this script with that directory");
+console.log(`as the second argument: node verify-bundle-location.mjs ${BUNDLE_NAME} <CustomOutputDir>`);
+console.log("");
+console.log("Otherwise, the scaffold command may have failed. Check for errors above.");
+process.exit(1);

package/skills/experience-ui-bundle-mfa-configure/references/branding.md

@@ -15,9 +15,11 @@ The MFA challenge page and login page are platform-rendered. Their branding is c
 
 ## Retrieve existing branding
 
-```bash
-# Create a package.xml manifest
-cat > /tmp/branding-pkg.xml <<'EOF'
+Create a package.xml manifest at `manifest/branding-pkg.xml` in the project (a
+plain file write — avoid a shell heredoc, since `<<EOF` and `/tmp` are not
+portable to Windows cmd/PowerShell) with this content:
+
+```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <Package xmlns="http://soap.sforce.com/2006/04/metadata">
   <types>
@@ -26,11 +28,13 @@ cat > /tmp/branding-pkg.xml <<'EOF'
   </types>
   <version>62.0</version>
 </Package>
-EOF
+```
 
-# Retrieve from org
+Then retrieve from the org:
+
+```bash
 sf project retrieve start --target-org <org-alias> \
-  --manifest /tmp/branding-pkg.xml \
+  --manifest manifest/branding-pkg.xml \
   --target-metadata-dir ./branding-retrieve --unzip
 ```
 

package/skills/external-diagram-mermaid-generate/SKILL.md

@@ -2,6 +2,18 @@
 name: external-diagram-mermaid-generate
 description: "Salesforce architecture diagrams using Mermaid with ASCII fallback. Use this skill when generating text-based diagrams for Salesforce architecture, OAuth flows, ERDs, integration sequences, or Agentforce structure. TRIGGER when: user says \"diagram\", \"visualize\", \"ERD\", or asks for sequence diagrams, flowcharts, class diagrams, or architecture visualizations in Mermaid. DO NOT TRIGGER when: user asks about non-Salesforce systems."
 metadata:
+  version: "1.0"
+  domains: ["External"]
+  relatedSkills:
+    - "agentforce-generate"
+    - "automation-flow-generate"
+    - "integration-connectivity-connected-app-configure"
+    - "integration-connectivity-generate"
+    - "platform-apex-generate"
+    - "platform-custom-field-generate"
+    - "platform-custom-object-generate"
+    - "platform-data-manage"
+    - "platform-metadata-deploy"
   cliTools:
     - tool: ["curl"]
       semver: ">=7.0.0"
@@ -13,18 +25,6 @@ metadata:
       semver: ">=3.10.0"
     - tool: ["sf"]
       semver: ">=2.0.0"
-  relatedSkills:
-    - "agentforce-generate"
-    - "automation-flow-generate"
-    - "integration-connectivity-connected-app-configure"
-    - "integration-connectivity-generate"
-    - "platform-apex-generate"
-    - "platform-custom-field-generate"
-    - "platform-custom-object-generate"
-    - "platform-data-manage"
-    - "platform-metadata-deploy"
-  version: "1.0"
-  domains: ["External"]
 ---
 
 # external-diagram-mermaid-generate: Salesforce Diagram Generation

package/skills/field-service-data-capture-migrate/references/component-mapping.md

@@ -174,7 +174,7 @@ preserves these but flags for offline-priming verification.
 | Legacy parameter | DC parameter | Notes |
 |---|---|---|
 | `label` | `label` | Direct map for ComponentInstance fields |
-| `required` | Field-level `<isRequired>` | Moved from parameter to field attribute |
+| `required` | Field-level `<isRequired>` **and** a `required` inputParameter | `ComponentInstance` fields read required-ness from the inputParameter at DC runtime, not `<isRequired>` alone — transformer emits both. Exception: `dcCheckbox`/`dcToggle` don't expose a `required` input attribute; only `<isRequired>` is set for those. |
 | `placeholder` | *(not supported)* | Bake into label text |
 | `disabled` / `readOnly` | `isDisabled` / `isReadonly` | Available on some DC components |
 | `helpText` | *(not supported)* | Bake into label or use DisplayText |

package/skills/field-service-data-capture-migrate/references/fsm-dc-capability-catalog.md

@@ -24,8 +24,7 @@ A `lightning:*` / `forceContent:*` / `c:*` name only ever appears as the
 Two inputs were reconciled:
 
 1. The **assessment spreadsheet** — *FSM Flow vs Data Capture Flow component
-   assessment*
-   ([sheet](https://docs.google.com/spreadsheets/d/1KeZPHw4AN8XxqxoTh4X9ciLavp9JNcOeYDbSzmCATGg/edit)).
+   assessment*.
 2. **Salesforce core code** (core-2206, 264 release line), which is
    authoritative where the two disagree.
 

package/skills/field-service-data-capture-migrate/references/known-deploy-errors.md

@@ -34,3 +34,4 @@ These were encountered in real migration runs. All are handled automatically by
 | `Error while resolving default value reference` *(runtime — not deploy)* | Complex formula in `DisplayText` (`IF`, `CASE`, date math) | Transformer warns; pre-calculate in Assignment → reference simple variable in DisplayText |
 | `isRequired=true` blocks hidden field *(runtime — not deploy)* | Required check fires even when field is hidden behind `visibilityRule` | Transformer warns; manually clear `isRequired` and add `validationRule` |
 | `outputAssignments` in `dynamicChoiceSets` populates blank *(runtime — not deploy)* | `outputAssignments` inside choice sets deploys but does NOT populate variables at mobile runtime | Replace with post-selection `recordLookups` using `outputAssignments` |
+| `We can't find this input attribute: "required"` on `dcCheckbox` / `dcToggle` | These boolean-backed components don't expose a `required` input attribute — unlike other `ComponentInstance` types, they don't need one to enforce required-ness | Transformer skips the `required` inputParameter injection for `dcCheckbox`/`dcToggle` extensions; `<isRequired>` is still set |

package/skills/field-service-data-capture-migrate/references/transformer-rules.md

@@ -91,7 +91,7 @@ the `transform_flow.py` restructurer, which rewrites the flow XML connectors in
 - Strips fault connectors from all elements (not supported in DataCaptureFlow)
 - Removes platform event `<recordCreates>` nodes (DC can't create non-UI entities like `AsgnResourceLocUpdateEvent`) — **side effect: those events will no longer fire**
 - Removes `<outputAssignments>` from screen fields → replaced with `storeOutputAutomatically=true` + an injected `<assignments>` node to preserve variable bindings
-- Strips invalid `<inputParameters>`: `required`, `disabled`, `multiple`, `accept`, `helpText`, `placeholder` (none supported in DC; bake content into label text instead)
+- Strips invalid incoming `<inputParameters>`: `required`, `disabled`, `multiple`, `accept`, `helpText`, `placeholder` (not carried over as-is from the legacy field). `disabled`/`helpText`/`placeholder`/`multiple`/`accept` stay stripped (bake content into label text instead). `required` is different: it's re-added as a computed inputParameter (from `<isRequired>`) on most `ComponentInstance` fields, since the DC runtime reads required-ness from the inputParameter, not `<isRequired>`, for those — except `dcCheckbox`/`dcToggle`, which don't expose a `required` input attribute at all and get only `<isRequired>`
 - Replaces `minimumDate`/`maximumDate` with `minDate`/`maxDate` on date fields
 - Replaces `multiSelection` with `isMultiSelection` on Lookup fields
 - Replaces `disabled`/`readOnly` with `isDisabled`/`isReadonly` (note lowercase `o`) on Lookup fields

package/skills/field-service-data-capture-migrate/scripts/transform_flow.py

@@ -267,6 +267,17 @@ CHOICE_REQUIRED = {
 # Invalid inputParameter names on dc* components
 INVALID_PARAMS = frozenset(('required', 'disabled', 'multiple', 'accept', 'helpText', 'placeholder'))
 
+# dc* ComponentInstance extensions that do NOT expose a `required` input
+# attribute — injecting one deploys as "We can't find this input attribute:
+# 'required'". Confirmed for dcCheckbox (W-24086520); dcToggle is the other
+# boolean-backed component and excluded on the same rationale: an unchecked/
+# off boolean is itself a valid answer, so these components have no notion of
+# "required" distinct from <isRequired> already being set on the field.
+NO_REQUIRED_INPUT_PARAM_EXTENSIONS = frozenset((
+    'runtime_service_fieldservice:dcCheckbox',
+    'runtime_service_fieldservice:dcToggle',
+))
+
 # ──────────────────────────────────────────────
 # Phase 1: Screen field transformation
 # ──────────────────────────────────────────────
@@ -389,7 +400,7 @@ def _apply_component_type(field: ET.Element, new_ft: str, new_ext: str, label_st
         # don't need this — they read <isRequired> directly.)
         is_required = (findtext(field, 'isRequired') or 'false').lower() == 'true'
         has_required_param = any(findtext(p, 'name') == 'required' for p in findall(field, 'inputParameters'))
-        if not has_required_param:
+        if not has_required_param and new_ext not in NO_REQUIRED_INPUT_PARAM_EXTENSIONS:
             ip = make('inputParameters')
             ip.append(make('name', 'required'))
             v = sub(ip, 'value')

package/skills/field-service-data-capture-migrate/scripts/vendor/build_flow.py

@@ -719,7 +719,10 @@ def render_field(field: Field, spec: FormSpec, indent: str = "        ") -> str:
     parts.append(f"{indent}    <extensionName>{x(extension_name)}</extensionName>\n")
     parts.append(f"{indent}    <fieldType>ComponentInstance</fieldType>\n")
     parts.append(render_input_param("label", label, indent=inner))
-    if field.is_required:
+    # dcCheckbox/dcToggle don't expose a `required` input attribute — an
+    # unchecked/off boolean is itself a valid answer, so deploying `required`
+    # on these fails with "We can't find this input attribute: 'required'".
+    if field.is_required and field.field_type not in ("Checkbox", "Toggle"):
         parts.append(render_input_param("required", boolean_value=True, indent=inner))
     if field.field_type == "Counter":
         if field.counter_min is not None:

package/skills/field-service-setup-orchestrator-get/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: field-service-setup-orchestrator-get
 description: "Use this skill to set up Salesforce Field Service — Work Types, Skills, Service Territories, Operating Hours, Scheduling Policy, Work Rules, Service Objectives, Data Capture Forms, FSL mobile forms, Pre-Work Brief, Mobile Branding, or any FSL setup, enablement, or configuration request. Entry point that identifies what the user wants to configure and routes to the right sub-workflow: Foundation Setup, Scheduling Policy, Data Capture Forms, Pre-Work Brief, or Mobile Branding."
-user-invocable: false
 owning_team: sfs-setup-experience
 metadata:
   version: "1.0"

package/skills/insurance-brokerage-agency-billing-configure/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: insurance-brokerage-agency-billing-configure
+description: "Configure end-to-end Agency Billing on a Salesforce FSC Insurance Brokerage org via dispatch MCP calls. Use this skill when users want to set up brokerage billing, configure agency billing, enable insurance billing features, create billing rules, set up accounting periods, assign billing permission sets, or create a demo policy for the Issue-to-Invoice flow. TRIGGER when: user mentions agency billing setup, brokerage billing configuration, insurance billing enablement, billing treatments, billing rules creation, accounting period setup, insurance policy billing information, or Issue-to-Invoice testing. Also use when users say things like set up my brokerage org for billing, configure billing on my insurance org, enable billing features, create billing treatments, set up GL accounts, or assign billing permissions. DO NOT TRIGGER when: user needs general Revenue Cloud Billing without insurance context, needs CPQ/quoting configuration, or needs claims processing setup."
+metadata:
+  version: "2.0"
+  minApiVersion: "66.0"
+  accessCheck:
+  - type: "license"
+    value: "InsuranceBrokerageFoundationPsl"
+---
+
+# Insurance Brokerage Agency Billing Configuration
+
+Automates the full Agency Billing setup on a Salesforce FSC Insurance Brokerage org. Runs 7 sequential phases using `dispatch` MCP calls to verify licenses, enable features, **assign permissions early**, configure billing settings, create billing rules, set org defaults, set up accounting, and create a demo policy for Issue-to-Invoice testing. **Phase order is critical**: permissions must be assigned before billing settings configuration.
+
+## Scope
+
+- **In scope**: License verification, feature enablement (Context Service, Brokerage, Billing, Salesforce Pricing), billing settings configuration, billing rules creation (Legal Entity, Billing Treatments, Tax Engine, Payment Terms, Product Selling Models, Proration Policy), accounting setup (periods, GL accounts, GLAAR rules), permission set assignment, FLS creation via metadata endpoint, and demo policy creation.
+- **Out of scope**: Revenue Cloud CPQ/quoting, claims processing, policy administration workflows, custom Apex development, LWC UI components. Data Pipelines (Sonic) requires an org-level `SonicLicensedOrg` feature not present on standard brokerage orgs — enable it manually if needed.
+- **All phases fully automated** via `dispatch` (headless routes + Metadata CRUD + Tooling API). No manual steps, no SF CLI, no gaps.
+
+---
+
+## CRITICAL — Standard Field Names (no __c anywhere)
+
+Every field in this workflow is STANDARD. Never append `__c` to any field name. Here are the correct API names:
+
+| Object | Field (correct) | WRONG (never use) |
+|--------|----------------|-------------------|
+| BillingTreatment | Status | ~~Status__c~~ |
+| TaxEngine | TaxEngineName | ~~TaxEngineName__c~~ |
+| PaymentTerm | DaysDue | ~~DaysDue__c~~ |
+| PaymentTerm / PaymentTermItem | PeriodUnit | ~~PeriodUnit__c~~ |
+| PaymentTerm | Active | ~~Active__c~~ |
+| LegalEntity | Active | ~~Active__c~~ |
+| BillingTreatmentItem | ChargeType | ~~ChargeType__c~~ |
+| BillingTreatmentItem | BillingType | ~~BillingType__c~~ |
+| BillingTreatmentItem | Active | ~~Active__c~~ |
+| ProductSellingModel | Active | ~~Active__c~~ |
+
+---
+
+## Required Inputs
+
+Do not ask the user for any information — proceed autonomously using defaults and the pre-configured environment.
+
+- **Authenticated org**: The default target org is pre-configured in the MCP environment. Verify connectivity by calling `dispatch GET /chatter/users/me`.
+- **Target user ID**: Capture the `id` field from the `/chatter/users/me` response and use it as AssigneeId for all license and permission assignments throughout all phases.
+
+Defaults (always apply unless the user explicitly overrides in their initial prompt):
+- All 7 phases execute in sequence
+- Demo policy uses configuration from `references/demo-policy-config.md`
+- Billing rules use configuration from `references/billing-rules-config.md`
+- Permission sets from `references/permissions-config.md`
+
+---
+
+## Workflow
+
+All phases are sequential. Do not skip or reorder. **Critical cross-dependencies:**
+- Phase 2 (Permissions) MUST run before Phase 3 (Billing Settings) — many billing settings require billing admin permissions
+- Phase 2 (Permissions) MUST run before Phase 4 (Billing Rules) — BillingTreatment object access requires permissions
+- Phase 2 (Permissions) MUST run before Phase 7 (Demo Policy) — InsPolicyBillingInfo fields require permissions + propagation time
+
+Follow the execution order below exactly.
+
+### Phase 1 — Prerequisites
+
+1. **Verify org connectivity and capture target user ID** — call `dispatch GET /chatter/users/me` and confirm a 200 response. **Capture the `id` field from the response and store it as `TARGET_USER_ID` — this SAME ID must be used throughout ALL phases for license assignments, permission set assignments, and any user-specific operations.** If Chatter is disabled, fall back to querying the User object: `dispatch GET /query?q=SELECT+Id,Username,Name+FROM+User+WHERE+IsActive=true+AND+Profile.Name+LIKE+'%25System+Administrator%25'+LIMIT+1` and capture the `Id` field from the first record.
+
+   **CRITICAL:** Do not re-query for the user ID in later phases. Use the same `TARGET_USER_ID` captured here for all subsequent operations. Re-querying can return a different user if multiple admins exist.
+
+2. **Verify 19 required licenses** — read `references/prerequisites.md` for the full license list. Use `dispatch GET /query?q=<SOQL>` to query `PermissionSetLicense` records. If any are missing from the org, stop and inform the user.
+
+3. **Assign missing licenses to target user** — query `PermissionSetLicenseAssign` for the `TARGET_USER_ID` captured in step 1. Assign any missing licenses via `dispatch POST /sobjects/PermissionSetLicenseAssign` using the same `TARGET_USER_ID`.
+
+4. **Enable features** — read `references/prerequisites.md` for the feature enablement sequence and exact routes. Each feature is a read → write → verify cycle. Enable in order: Context Service, Brokerage, Billing, Salesforce Pricing.
+
+> Features MUST be enabled in dependency order. Context Service before Brokerage, Brokerage before Billing.
+
+### Phase 2 — Permissions Assignment (moved from Phase 6)
+
+5. **Assign permission sets EARLY** — read `references/permissions-config.md` for the 15 required sets. Query current assignments, assign only missing ones via `dispatch POST /sobjects/PermissionSetAssignment`. **This must run before Phase 3 (Billing Settings) because several billing settings require these permissions to modify.**
+
+6. **Create custom permission set with FLS for InsPolicyBillingInfo billing lookup fields** — **MANDATORY STEP, CANNOT BE SKIPPED UNDER ANY CIRCUMSTANCES.** The 6 billing lookup fields on InsPolicyBillingInfo require Field-Level Security to be visible: BillingTreatmentId, TaxTreatmentId, ProrationPolicyId, PaymentTermId, ProductSellingModelId, LegalEntityId. Without this FLS, Phase 7 will fail with INVALID_FIELD errors when creating InsPolicyBillingInfo records.
+
+   **CRITICAL: ALWAYS attempt to create the permission set — DO NOT skip this step based on FLS query results.** Even if FieldPermissions query shows FLS is already granted via another permission set, you MUST attempt to create the `Insurance_Billing_Field_Access` permission set. If it already exists, the API will return DUPLICATE_VALUE — treat this as success and continue.
+
+   **Step 1 — Verify FLS (for diagnostic purposes only, NOT a gate for creation):**
+   ```text
+   dispatch GET /query?q=SELECT+Field+FROM+FieldPermissions+WHERE+SobjectType='InsPolicyBillingInfo'+AND+Field+IN+('InsPolicyBillingInfo.BillingTreatmentId','InsPolicyBillingInfo.TaxTreatmentId','InsPolicyBillingInfo.ProrationPolicyId','InsPolicyBillingInfo.PaymentTermId','InsPolicyBillingInfo.ProductSellingModelId','InsPolicyBillingInfo.LegalEntityId')+AND+PermissionsRead=true+AND+PermissionsEdit=true
+   ```
+   
+   **Step 2 — UNCONDITIONALLY create the permission set (DO NOT skip regardless of Step 1 results):**
+   ```text
+   dispatch POST /services/data/v66.0/headless/metadata
+   {
+     "type": "PermissionSet",
+     "fullName": "Insurance_Billing_Field_Access",
+     "xmlRep": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><PermissionSet xmlns=\"http://soap.sforce.com/2006/04/metadata\"><fieldPermissions><field>InsPolicyBillingInfo.BillingTreatmentId</field><readable>true</readable><editable>true</editable></fieldPermissions><fieldPermissions><field>InsPolicyBillingInfo.TaxTreatmentId</field><readable>true</readable><editable>true</editable></fieldPermissions><fieldPermissions><field>InsPolicyBillingInfo.ProrationPolicyId</field><readable>true</readable><editable>true</editable></fieldPermissions><fieldPermissions><field>InsPolicyBillingInfo.PaymentTermId</field><readable>true</readable><editable>true</editable></fieldPermissions><fieldPermissions><field>InsPolicyBillingInfo.ProductSellingModelId</field><readable>true</readable><editable>true</editable></fieldPermissions><fieldPermissions><field>InsPolicyBillingInfo.LegalEntityId</field><readable>true</readable><editable>true</editable></fieldPermissions><hasActivationRequired>false</hasActivationRequired><label>Insurance Billing Field Access</label><description>Grants FLS for InsPolicyBillingInfo billing lookup fields</description></PermissionSet>"
+   }
+   ```
+   
+   **Expected outcomes:**
+   - Success (new creation): `{ results: [{ success: true, id: "0PS...", fullName: "Insurance_Billing_Field_Access" }] }` — capture the `id` field.
+   - DUPLICATE_VALUE (already exists): `{ results: [{ success: false, errors: [{ statusCode: "DUPLICATE_VALUE" }] }] }` — the permission set exists; proceed to reconciliation step below.
+
+7. **Reconcile FieldPermissions — MANDATORY, DO NOT SKIP.** A pre-existing `Insurance_Billing_Field_Access` permission set may be missing some of the 6 required entries. Resolve the permission set ID, query its FieldPermissions, and for each of the 6 required fields (`InsPolicyBillingInfo.BillingTreatmentId`, `.TaxTreatmentId`, `.ProrationPolicyId`, `.PaymentTermId`, `.ProductSellingModelId`, `.LegalEntityId`) that is missing or has read/edit false: create or PATCH the FieldPermissions record. See `references/permissions-config.md` § "Reconcile Field Permissions" for the exact API calls. Only after all 6 fields are confirmed read+edit proceed to assignment.
+
+8. **Assign the permission set to target user** — **MANDATORY STEP, DO NOT SKIP.** Query for the permission set ID (whether you just created it or it already existed), then verify assignment status and create the assignment if missing.
+   
+   **First, resolve the permission set ID:**
+   ```text
+   dispatch GET /query?q=SELECT+Id+FROM+PermissionSet+WHERE+Name='Insurance_Billing_Field_Access'+AND+IsOwnedByProfile=false
+   ```
+   
+   **Then check if already assigned:**
+   ```text
+   dispatch GET /query?q=SELECT+Id+FROM+PermissionSetAssignment+WHERE+AssigneeId='<TARGET_USER_ID>'+AND+PermissionSetId='<PS_ID>'
+   ```
+   
+   **If the assignment query returns 0 records, create the assignment:**
+   ```text
+   dispatch POST /sobjects/PermissionSetAssignment
+   {"AssigneeId": "<TARGET_USER_ID>", "PermissionSetId": "<PS_ID>"}
+   ```
+   
+   If the assignment POST returns DUPLICATE_VALUE, the user already has it assigned between your query and now (treat as success). Any other error is a failure and must be reported.
+
+### Phase 3 — Billing Settings (requires Phase 2 permissions)
+
+7. **Read current billing settings** — read `references/billing-settings.md` for the full settings map and routes. Call `dispatch GET /headless/invoke/platform/billing-settings/get-billing-general-setting-states` to read current state.
+
+8. **Write only changed settings** — compare each field against desired state and write only what differs. Enable Design Document Templates via `dispatch PATCH /headless/invoke/platform/accounting-guided-setup/setup-billing-doc-gen-and-fetch-invoice-template-data` (must run after billing is on). InsuranceBrokerage IPT/IPTD settings are now automated via `PATCH /setup/org/values/I_P_T_D_ENABLED_FOR_BROKERAGE` and `PATCH /setup/org/values/I_P_T_ENABLED_FOR_BROKERAGE`.
+
+> **If any setting returns "Access denied":** Phase 2 permissions did not propagate yet. Wait 30 seconds and retry.
+
+### Phase 4 — Billing Rules (requires Phase 2 permissions for BillingTreatment object access)
+
+9. **Query existing billing rules** — for each record type (Legal Entity, Billing Treatments, Tax Engine, Tax Treatment, Payment Term, Product Selling Models, Proration Policy), use `dispatch GET /query?q=<SOQL>` before creating. Read `references/billing-rules-config.md` for exact field values and search patterns.
+
+10. **Create only missing records** — use `dispatch POST /sobjects/<Object>` for creates and `dispatch PATCH /sobjects/<Object>/<id>` for updates. For Billing Treatments, follow the Draft→Items→Activate sequence. Track all record IDs.
+
+> Billing Treatments must be created in Draft, child Items created in Active, then parent activated. This is enforced by the platform.
+
+### Phase 5 — Org Defaults
+
+11. **Set billing defaults** — read `references/org-defaults.md`. Set the five default fields (Legal Entity, Billing Treatment, Tax Treatment, two DPE definitions) via dedicated headless routes. Use record IDs from Phase 4.
+
+### Phase 6 — Accounting
+
+12. **Create accounting periods** — read `references/accounting-setup.md`. Compute dates at runtime for the current fiscal year. Query existing periods via `dispatch GET /query?q=<SOQL>`, create only missing months via `dispatch POST /sobjects/AccountingPeriod`. Link periods to Legal Entity via `LegalEntyAccountingPeriod`.
+
+13. **Create GL accounts** — query by `AccountingCode`, create only missing accounts (11 total) via `dispatch POST /sobjects/GeneralLedgerAccount`. Link each to the Legal Entity.
+
+14. **Create GLAAR rules** — query existing rules, create parent `GeneralLedgerAcctAsgntRule` + child `GeneralLedgerJrnlEntryRule` if missing.
+
+### Phase 7 — Demo Policy
+
+15. **Demo policy** — proceed with creating a demo policy for Issue-to-Invoice testing. Skip only if the user explicitly requested to skip this phase in their initial prompt.
+
+16. **Create demo policy chain** — read `references/demo-policy-config.md`. Check for duplicate Account via `dispatch GET /query?q=<SOQL>`. If none exists, create: Account → Contact → Insurance Policy → Coverages → Surcharges → Insurance Policy Billing Information. Use record IDs from Phase 4 for billing info lookups. All creates via `dispatch POST /sobjects/<Object>`.
+
+17. **Verify FLS** — use `dispatch GET /query?q=<SOQL>` to query `FieldPermissions` for policy objects. Report any fields needing manual FLS configuration.
+
+---
+
+## Rules / Constraints
+
+| Constraint | Rationale |
+|-----------|-----------|
+| Query before create — always | Prevents duplicates; existing records may have been created manually or by a colleague |
+| Never ask the user questions or offer to run later | Proceed autonomously — execute all commands immediately. Never say "if you want me to run" or "say Run now". Just do it. Report results at the end. |
+| Capture target user ID once in Phase 1, use everywhere | Phase 1 step 1 captures `TARGET_USER_ID` — this SAME ID is used for all license assignments, permission set assignments, and user-specific operations. Do NOT re-query for user ID in later phases. |
+| Track all record IDs across phases | Later phases reference IDs from earlier phases for lookups |
+| Enable features individually and sequentially | Cross-dependencies require ordered enablement |
+| Use `dispatch` for all org operations | No sf CLI dependency — all reads/writes go through the project-codey MCP dispatch tool |
+| Compute dates at runtime | Fiscal year, accounting periods, and policy dates must reflect the current calendar year |
+| Read config from references/ files | Centralizes field values; prevents drift between instructions and actual creates |
+| NEVER use `__c` suffix on ANY object or field | Every object and every field in this workflow is STANDARD. There are ZERO custom objects or custom fields. Never write `__c` anywhere — not on object names, not on field names. `Status` not `Status__c`. `Active` not `Active__c`. `BillingType` not `BillingType__c`. Using `__c` causes immediate DML failures. |
+| Report skipped steps | When a commented-out section is skipped, tell the user which settings were not configured and why |
+
+---
+
+## Gotchas
+
+| Issue | Resolution |
+|-------|------------|
+| Chatter may be disabled on the target org | If `GET /chatter/users/me` returns 403 FUNCTIONALITY_NOT_ENABLED, fall back to `SELECT Id,Username,Name FROM User WHERE IsActive=true AND Profile.Name LIKE '%System Administrator%' LIMIT 1` to identify the target user |
+| Target user ID must be captured once in Phase 1 and used consistently across ALL phases | Capture the user ID from `/chatter/users/me` (or the User query fallback) in Phase 1 step 1 and store it as `TARGET_USER_ID`. Use this SAME ID for all license assignments (Phase 1), permission set assignments (Phase 2), and any user-specific operations. Do NOT re-query for the user ID in later phases — if multiple System Administrator users exist, re-querying can return a different user, causing "invalid user id" errors. If Phase 2 or Phase 7 returns INVALID_CROSS_REFERENCE_KEY with "invalid user id", you used the wrong ID — go back to Phase 1 and use the correct `TARGET_USER_ID` captured there. |
+| `TaxEngine` name field is `TaxEngineName`, not `Name` | Use `TaxEngineName` in queries and creates |
+| `PeriodUnit` (on PaymentTerm and PaymentTermItem) is singular, not `PeriodUnits` | Field was renamed; use singular form |
+| `ProrationPolicy` has NO `Status` field | Do not include Status in queries or creates for this object |
+| `BillingTreatment` activation validates children exist | Must create Items before activating parent |
+| `InsPolicyBillingInfo` is abbreviated, not `InsurancePolicyBillingInformation` | Use the short API name |
+| `InsPolicyTransactionDetail` is abbreviated, not `InsurancePolicyTransactionDetail` | Use the short API name |
+| `GeneralLedgerAccount.Name` is auto-generated | Do not include Name in create; use `AccountingCode` + `AccountingName` |
+| `LegalEntyAccountingPeriod.Name` is auto-generated | Do not include Name in create |
+| `InsurancePolicyCoverage` uses `CoverageName` not `Name` | `Name` is auto-generated on this object |
+| Surcharges must be on terminal nodes (coverages), not directly on the policy | Platform enforces this for tax proration to work correctly |
+| Headless invoke routes use kebab-case path segments | The route `PATCH /headless/invoke/platform/billing-settings/set-billing-setup-enabled` is the canonical form; camelCase variants 404 |
+| `INSURANCE_BILLING` requires `INSURANCE_TRANSACTION_DETAIL` on first | Enable `I_P_T_D_ENABLED_FOR_BROKERAGE` before `I_P_T_ENABLED_FOR_BROKERAGE`. The `handle-pref-enable` route is wrong for both — use `PATCH /setup/org/values/<name>` with `{"orgValue": true}` (same as `SetupApiFamilyController.updateOrgValue` in the UI). |
+| `InsuranceBrokerageSettings` context mapping via `/setup/org/values/*` | Use the same pattern as IPTD/IPT: `GET/PATCH /setup/org/values/INS_BRK_BILLING_CTX_DEF` (and `_SCHED_GRP_MAP`, `_TNX_MAPPING`) with `{"orgValue": "<value>"}`. Tooling API `SELECT Metadata FROM InsuranceBrokerageSettings` returns `INVALID_TYPE` on standard orgs. |
+| `BillingSettings` Tooling SOQL returns INVALID_TYPE | `SELECT Id,Metadata FROM BillingSettings` via Tooling API fails on many org types. `BillingSettings` is a standard platform Metadata type (Metadata API deploy/retrieve works), but the Tooling SOQL surface doesn't expose it universally. For Phase 4 org defaults, use the dedicated headless routes in `references/org-defaults.md` — they write the same underlying OrgValues without any Tooling API dependency. |
+| `BillingTreatmentItem.Percentage` is required even for Advance/Arrears | Platform requires Percentage on all BTI types, not just Milestone. Use 100 for non-milestone items |
+| `BillingTreatmentItem` has no `CurrencyIsoCode` field | Do not include CurrencyIsoCode — the field does not exist on this object |
+| `InsurancePolicyCoverage` has no `CurrencyIsoCode` field | Do not include CurrencyIsoCode — the field does not exist on this object |
+| `ProductSellingModel` OneTime cannot have `PricingTerm` or `PricingTermUnit` | Omit both fields when SellingModelType=OneTime; platform returns INVALID_INPUT if either is set |
+| `PaymentTerm` must be created without Status, then activated after child item | Creating PaymentTerm with Status=Active fails if no PaymentTermItem exists. Create without Status, add PaymentTermItem, then PATCH Status=Active+IsDefault=true |
+| `GeneralLedgerAcctAsgntRule` create fails with Status=Active if no child journal entry rule exists | Create with Status=Inactive, add GeneralLedgerJrnlEntryRule child, then PATCH Status=Active. Valid values: Active, Inactive (no Draft) |
+| `LegalEntity` has no `CurrencyIsoCode` field on orgfarm orgs | Omit from SOQL query and create body |
+| `BillingTreatment.ExcludeFromBilling` is a restricted picklist | Valid values are `"Yes"`/`"No"` only. Sending a boolean-like `"true"`/`"false"` string fails with `400 INVALID_OR_NULL_FOR_RESTRICTED_PICKLIST` |
+| `InsPolicyBillingInfo` billing lookup fields require FLS grants from Phase 2 custom permission set | `BillingTreatmentId`, `TaxTreatmentId`, `ProrationPolicyId`, `PaymentTermId`, `ProductSellingModelId`, `LegalEntityId` are hidden from describe and SOQL until Field-Level Security is granted. Phase 2 creates a custom permission set "Insurance Billing Field Access" with FieldPermissions for these 6 fields and assigns it to the target user. If the POST returns INVALID_FIELD on any of these after Phase 2 completed, the FLS grants may not have been created correctly — verify the custom permission set exists and has the 6 FieldPermissions records. Phase 7 MUST run after Phase 2 completes. |
+
+---
+
+## Output Expectations
+
+This skill produces no file artifacts. It configures an org via `dispatch` calls and produces a status report at the end of each phase and a comprehensive summary after all phases complete. Commented-out steps are reported as skipped with investigation notes.
+
+---
+
+## Reference File Index
+
+| File | When to read |
+|------|-------------|
+| `references/prerequisites.md` | Phase 1 — license list, feature enablement routes |
+| `references/permissions-config.md` | Phase 2 — 15 permission sets API names (moved early to unblock Phase 3) |
+| `references/billing-settings.md` | Phase 3 — settings field map, headless routes, and desired values |
+| `references/billing-rules-config.md` | Phase 4 — billing rules field values, search patterns, creation sequence |
+| `references/org-defaults.md` | Phase 5 — investigation status and deferred default fields |
+| `references/accounting-setup.md` | Phase 6 — GL account chart, GLAAR rule structure, period naming |
+| `references/demo-policy-config.md` | Phase 7 — demo policy record fields, lookup resolution, and FLS verification |