@salesforce/afv-skills 1.64.0 → 1.65.0

package/skills/field-service-work-plan-configure/SKILL.md

@@ -0,0 +1,253 @@
+---
+name: field-service-work-plan-configure
+description: "Use this skill when users want to configure org-level Salesforce Field Service Work Plans settings and template-to-record custom field mappings. Trigger when users mention work, plan, settings, work plan settings."
+metadata:
+  version: "1.0"
+  accessCheck: "(FieldServiceAccessCheck.ORG_HAS_WORK_PLANS_GENERAL) || (FieldServiceAccessCheck.ORG_PERMISSION_FIELD_SERVICE) || (FieldServiceSettingAccessCheck.ORG_PERMISSION_WORK_PLANS_DURATION) || (OldAccessCheck.USER_HAS_CUSTOMIZE_APPLICATION_OR_SYS_ADMIN)"
+---
+
+# Managing Work Plan Settings
+
+## When to Use This Skill
+
+Configure org-level Salesforce Field Service Work Plans settings and
+template-to-record custom field mappings. Covers the auto-generation,
+manual-status-update, and hide-not-applicable toggles, the work-order
+duration source, and custom field mappings from Work Plan Template / Work
+Step Template / Work Plan Template Entry to the generated Work Plan and
+Work Step records. Use for Field Service Work Plans configuration and
+field mapping — NOT for unrelated "work", "plan", or "settings" requests
+outside Field Service Work Plans.
+
+## Critical Constraints
+
+**Preconditions:**
+
+- Field Service feature must be enabled at the org level (FieldServiceAccessCheck.ORG_PERMISSION_FIELD_SERVICE). When off, getWorkPlansSettingsConfiguration short-circuits at the fieldServicePerm check and returns only fieldServicePerm + hasCustomizeApplicationPerm. (check: `FieldServiceAccessCheck.ORG_PERMISSION_FIELD_SERVICE`)
+- Work Plans General feature must be on at org level (FieldServiceAccessCheck.ORG_HAS_WORK_PLANS_GENERAL). hasAccess() AND-combines this with the Customize Application/Sys Admin perm; without it saveWorkPlansSettings throws NoAccessException. (check: `FieldServiceAccessCheck.ORG_HAS_WORK_PLANS_GENERAL`)
+- Customize Application permission OR System Administrator (OldAccessCheck.USER_HAS_CUSTOMIZE_APPLICATION_OR_SYS_ADMIN). Required by hasAccess(); save throws NoAccessException otherwise. (check: `OldAccessCheck.USER_HAS_CUSTOMIZE_APPLICATION_OR_SYS_ADMIN`)
+- workOrderDurationSource write additionally requires FieldServiceSettingAccessCheck.ORG_PERMISSION_WORK_PLANS_DURATION; without it the duration write is silently skipped (other toggles still persist). (check: `FieldServiceSettingAccessCheck.ORG_PERMISSION_WORK_PLANS_DURATION`)
+
+**Operational rules:**
+
+- WHAT WORK PLANS ARE
+Field Service Work Plans give front-line and back-office workers an
+ordered checklist of "work steps" on a Work Order (WO) or Work Order Line
+Item (WOLI), so jobs are completed consistently. The feature has a
+reusable "library" plus generated instances:
+  - Work Step Template (WST): a reusable task (may carry a quick action or
+    a Field Service mobile flow).
+  - Work Plan Template (WPT): a reusable ordered list of steps.
+  - Work Plan Template Entry (WPTE): a WST placed into a WPT.
+  - Work Plan Selection Rule (WPSR): logic that picks which WPT(s) apply to
+    a WO/WOLI (by work type, asset, location, service contract, etc.).
+    NOTE: selection rules support STANDARD fields only.
+  - Work Plan (WP) / Work Step (WS): the point-in-time instances generated
+    onto the WO/WOLI from the templates (WP↔WS is master-detail).
+On WO/WOLI create, the WPSR is evaluated → the matching WPT + its WSTs are
+copied into a WP + WS set on the record.
+- SCOPE OF THIS SKILL
+This skill is the ORG-LEVEL Work Plans SETTINGS page (Setup → Work Plans).
+It owns: the three org toggles (auto-generation, manual work-step status
+update, hide-not-applicable), the work-order duration source, and the
+CUSTOM FIELD MAPPINGS. It does NOT create the library records or generate
+plans — see "broader feature" below.
+- CUSTOM FIELD MAPPING
+Standard fields are auto-mapped from templates to the generated records and
+CANNOT be changed (WPT→WP: Name, Description, Execution Order; WST/WPTE→WS:
+Action Definition, Action Type, Description, Execution Order, Name, Work
+Plan Execution Order). Custom field mapping lets an admin (Customize
+Application) carry CUSTOM template fields onto the generated WP/WS records —
+e.g. a procedures-doc URL, a compliance picklist, or a "mandatory" flag on a
+step. Three fixed mapping types: WorkPlanTemplate→WorkPlan,
+WorkStepTemplate→WorkStep, WorkPlanTemplateEntry→WorkStep.
+Workflow:
+  1. getObjectMappingConfiguration_3 — the authoritative field-discovery +
+     read step. Returns the SUPPORTED source custom fields (allSourceFields[],
+     already filtered — no External Lookup / Encrypted Text / Rollup) with
+     their allowed, type-compatible targetFields[], plus the current
+     mappings. Do NOT use a raw FieldDefinition/describe query to pick
+     fields — it returns more than the mapper supports.
+  2. saveWorkPlansSettings_2 with hasMappedFieldDataChanged=true and the
+     mappedFieldData composite (see that step's notes for the exact
+     {sourceEntity, targetEntity, mappedFields} shape; all five hasXChanged
+     flags must be present even on a mappings-only save). Only map a source
+     field to a target drawn from that source field's targetFields[]. Two
+     mappings that share a target object (WST→WS and WPTE→WS both target
+     WorkStep) must use DISTINCT target fields.
+  3. Re-read via getObjectMappingConfiguration_3 to confirm persistence
+     (save returns a bare true). Mappings persist as FieldServiceSettings
+     metadata (Tooling API), not org prefs.
+- BROADER FEATURE (outside this settings page)
+Building the library and generating plans is done elsewhere and is
+supported by standard/public APIs — this skill can guide a user there:
+  - Create/manage WorkPlanTemplate, WorkStepTemplate, WorkPlanTemplateEntry,
+    WorkPlanSelectionRule, WorkPlan, WorkStep as standard sObjects (REST/
+    SOQL/Tooling); the record-level Generate / Add / Delete Work Plans and
+    Add Work Steps actions live on the WO/WOLI (see the sibling controllers
+    generate-work-plans, add-work-plans, delete-work-plans,
+    add-work-steps-to-work-plan, update-work-plan-template-entry — separate
+    from this settings page).
+  - Typical setup order: (1) Enable Work Plans + add the WO/WOLI related
+    lists and the Generate/Add/Delete actions (Object Manager); (2) assign
+    user permissions (CRUD + View All on WPT/WST/WPSR; Read/Update on WP/WS;
+    Run Flows for mobile-flow steps); (3) build WSTs, WPTs, WPTEs, and
+    selection rules; (4) map custom fields (this page); (5) generate plans.
+- PUBLIC DOCS
+  - Intro: https://help.salesforce.com/s/articleView?id=service.fs_work_plans_intro.htm&type=5
+  - Enable: https://help.salesforce.com/s/articleView?id=service.fs_work_plans_enable.htm&type=5
+  - Customize settings: https://help.salesforce.com/s/articleView?id=service.fs_work_plans_customize_settings.htm&type=5
+  - Assign permissions: https://help.salesforce.com/s/articleView?id=service.fs_work_plans_assign_user_perms.htm&type=5
+  - Map custom fields: https://help.salesforce.com/s/articleView?id=service.fs_work_plans_map_custom_fields.htm&type=5
+  - Selection rules: https://help.salesforce.com/s/articleView?id=service.fs_work_plans_create_selection_rules.htm&type=5
+  - Generate plans: https://help.salesforce.com/s/articleView?id=service.fs_work_plans_generate_work_plans.htm&type=5
+
+## Operations Reference
+
+Operations grouped by purpose. Use these as the building blocks for the workflows above.
+
+### Summary
+
+| Operation | Purpose | Status | Call | Depends on |
+|-----------|---------|--------|------|------------|
+| `getWorkPlansSettingsConfiguration_1` | read | implemented | `GET /headless/invoke/service/fieldservice/work-plans-settings/get-work-plans-settings-configuration` | — |
+| `saveWorkPlansSettings_2` | write | implemented | `PATCH /headless/invoke/service/fieldservice/work-plans-settings/save-work-plans-settings` | `getWorkPlansSettingsConfiguration_1` |
+| `getObjectMappingConfiguration_3` | read | implemented | `GET /headless/invoke/service/fieldservice/field-service-object-mapping/get-object-mapping-configuration` | `getWorkPlansSettingsConfiguration_1` |
+
+### Read operations
+
+#### `getWorkPlansSettingsConfiguration_1`
+
+Returns WorkPlansSettingsConfiguration: toggle values, workOrderDurationSource picklist with conditional workOrderDurationSourceOptions, and gating booleans the agent uses to decide which controls are mutable. AURA-IS-CANONICAL — no public Connect/Tooling/Metadata equivalent.
+
+**Call:** `GET /headless/invoke/service/fieldservice/work-plans-settings/get-work-plans-settings-configuration`   — status: `implemented`
+
+**Output:** WorkPlansSettingsConfiguration object. Toggle values:
+isWorkPlansAutoGenerationEnabled, isWorkStepManualStatusUpdateEnabled,
+isWorkStepsHideNotApplicableEnabled, workOrderDurationSource (string,
+nullable). Gating booleans: fieldServicePerm, fieldServiceOrgPref,
+hasWorkPlansDurationPerm, hasCustomizeApplicationPerm. When the duration
+perm is granted, workOrderDurationSourceOptions is also returned (the
+picklist for the duration source). mappingTypes is a fixed 3-element
+array: WorkPlans_WorkPlanTemplate_WorkPlan,
+WorkPlans_WorkStepTemplate_WorkStep,
+WorkPlans_WorkPlanTemplateEntry_WorkStep — used by the save step's
+optional mappedFieldData composite upsert. When Field Service is off
+(fieldServicePerm=false), the response short-circuits and returns only
+fieldServicePerm + hasCustomizeApplicationPerm.
+
+#### `getObjectMappingConfiguration_3`
+
+THE field-discovery + read step for custom field mapping — use this
+(not a raw FieldDefinition/describe query) to learn which fields can be
+mapped. Returns an array; each element (one per requested mappingType)
+has: type (the mappingType), sourceApiName + sourceLabel (source object,
+e.g. WorkPlanTemplate), targetApiName + targetLabel (target object, e.g.
+WorkPlan), allSourceFields[] and mappedFields.
+- allSourceFields[]: the ONLY custom source fields that may be mapped.
+  The controller already filters out unsupported source types (External
+  Lookup, Encrypted Text, Rollup Summary). Each entry has value (source
+  field API name) + targetFields[]: the allowed targets for THAT source
+  field — restricted to data-type-compatible custom fields on the target
+  object, plus a "None" ({value:""}) option. Only pair a source field
+  with a target from its own targetFields[] list.
+- mappedFields: the currently-configured {sourceFieldApiName:
+  targetFieldApiName} map for this mappingType.
+Empty allSourceFields / mappedFields means no custom fields are defined
+or none are mapped yet. This is the READ half of the workflow; the WRITE
+half is saveWorkPlansSettings with mappedFieldData. Backed by the
+embedded customFieldMapperSetupWrapper UI subcomponent on the Work Plan
+Settings page.
+
+**Call:** `GET /headless/invoke/service/fieldservice/field-service-object-mapping/get-object-mapping-configuration`   — status: `implemented`
+
+**Inputs:**
+
+- `mappingTypes` *(`List`)* — List of mappingType enum values to fetch. The three valid values
+(from getWorkPlansSettingsConfiguration's mappingTypes[]):
+WorkPlans_WorkPlanTemplate_WorkPlan (WorkPlanTemplate→WorkPlan),
+WorkPlans_WorkStepTemplate_WorkStep (WorkStepTemplate→WorkStep),
+WorkPlans_WorkPlanTemplateEntry_WorkStep (WorkPlanTemplateEntry→WorkStep).
+
+**Depends on:** `getWorkPlansSettingsConfiguration_1`
+
+### Write operations
+
+#### `saveWorkPlansSettings_2`
+
+Persist Work Plans toggles. workPlansSettings map MUST include all five
+pairs (hasIsWorkPlansAutoGenerationEnabledChanged,
+hasIsWorkStepManualStatusUpdateEnabledChanged,
+hasIsWorkStepsHideNotApplicableEnabledChanged,
+hasWorkOrderDurationSourceChanged, hasMappedFieldDataChanged) + their
+matching new values; a missing hasXChanged key raises 500
+CONTROLLER_ERROR. Duration-source writes require the WORK_PLANS_DURATION
+org perm — without it the write is silently skipped while save still
+returns true. Optional mappedFieldData drives a composite upsert against
+one of the fixed mappingTypes returned by the GET step. Throws
+NoAccessException without Customize Application + Work Plans General.
+Returns bare true — verify persistence by re-reading via
+getWorkPlansSettingsConfiguration. AURA-IS-CANONICAL — controller value-add
+(gate + batch + mappedFieldData).
+
+**Call:** `PATCH /headless/invoke/service/fieldservice/work-plans-settings/save-work-plans-settings`   — status: `implemented`
+
+**Inputs:**
+
+- `workPlansSettings` *(`LinkedHashMap`)*
+
+**Depends on:** `getWorkPlansSettingsConfiguration_1`
+
+**Rollback:** getWorkPlansSettingsConfiguration_1
+
+**Notes:** payload_contract: workPlansSettings map keys (all five hasXChanged flags are REQUIRED to
+avoid a 500 NPE; matching value fields are read only when the
+corresponding hasXChanged is true):
+  hasIsWorkPlansAutoGenerationEnabledChanged + isWorkPlansAutoGenerationEnabled (boolean)
+  hasIsWorkStepManualStatusUpdateEnabledChanged + isWorkStepManualStatusUpdateEnabled (boolean)
+  hasIsWorkStepsHideNotApplicableEnabledChanged + isWorkStepsHideNotApplicableEnabled (boolean)
+  hasWorkOrderDurationSourceChanged + workOrderDurationSource (string or null)
+  hasMappedFieldDataChanged + mappedFieldData (composite upsert object or null); error_contracts: {'empty_or_partial_payload': "Missing workPlansSettings input OR missing any hasXChanged key →\n500 CONTROLLER_ERROR (the controller unboxes booleans without null\nchecks). Send all five hasXChanged keys explicitly, even the ones\nyou don't intend to change (set those to false).", 'missing_access': 'NoAccessException when Customize Application or Sys Admin perm is\nabsent, or when Work Plans General feature is off at the org level.', 'duration_perm_silently_skipped': 'When the Work Plans Duration org permission is not granted, a\nworkOrderDurationSource write is dropped silently; save still\nreturns true. Confirm hasWorkPlansDurationPerm=true from the read\nstep before setting hasWorkOrderDurationSourceChanged=true.', 'error_message_shapes': 'Two distinct 500 CONTROLLER_ERROR message shapes distinguish payload\ndefects — inspect the error body to pick the fix:\n  - Outer-null (body={} or workPlansSettings unset): the error\n    reports that "workPlansSettings" is null → wrap the input in the\n    workPlansSettings key.\n  - Inner-null (workPlansSettings present but a hasXChanged key\n    missing): the error names the missing flag directly\n    (e.g. hasMappedFieldDataChanged) → default the named flag to\n    false. On some orgs the message instead reports a null value for\n    the workPlansSettings map lookup without naming the flag.', 'mapping_type_enum_mismatch': 'When hasMappedFieldDataChanged=true AND mappedFieldData contains a key\nthat isn\'t one of the three mappingTypes enum values, save fails with\n500 CONTROLLER_ERROR "No enum constant MappingType.<attempted-key>" —\ncomposite keys are validated pre-mutation against the mapping-type\nenum. Fix: cross-check mappedFieldData keys against mappingTypes[]\nreturned by getWorkPlansSettingsConfiguration_1 before sending.', 'mapping_data_type_mismatch': 'Catch-all 500 CONTROLLER_ERROR "We can\'t map these fields. Verify that\nthe data type details of the source and target fields match." raised\nwhen the Tooling upsert of FieldServiceSettings rejects the mapping.\nIt is NOT limited to data-type mismatches — verified against a live\norg, it also fires when:\n  - source/target field data types are incompatible;\n  - sourceEntity or targetEntity is omitted from a mappedFieldData\n    entry (the controller builds a null ObjectMapping);\n  - two mappings that share a target entity point at the SAME target\n    field (e.g. WorkStepTemplate→WorkStep and\n    WorkPlanTemplateEntry→WorkStep both mapping to\n    WorkStep.Custom_text_field__c) — each target field on a shared\n    target object can be the destination of only one source mapping.\nThe write is atomic: on this error NOTHING persists (state unchanged).\nFix: build mappings ONLY from getObjectMappingConfiguration_3 — pick a\nsource field from allSourceFields[] and a target from that field\'s own\ntargetFields[] list (both are already filtered to supported +\ntype-compatible fields); always include sourceEntity + targetEntity;\nand give each target field on a shared target object a distinct source\nmapping. Safest pattern: read the current valid config and modify it.'}; flag_gate_semantics: Flag-gate is STRICT. When hasXChanged=false the paired value is
+silently ignored — sending a new value alongside flag=false never
+writes and never errors. Consequence: all-hasXChanged=false is a
+safe no-op payload (idempotent contract). Corollary: to guarantee a
+write happens, set hasXChanged=true and populate the paired value.; loose_schema_tolerance: Unknown keys in the workPlansSettings map are silently dropped — the
+server returns 200 true with no error and does not persist the typo.
+Callers get no server-side signal on misspelled flag names. Validate
+against payload_contract keys client-side before send.; mapping_types_enum: ['WorkPlans_WorkPlanTemplate_WorkPlan', 'WorkPlans_WorkStepTemplate_WorkStep', 'WorkPlans_WorkPlanTemplateEntry_WorkStep']; mapped_field_data: Optional composite upsert of custom field mappings. Set
+hasMappedFieldDataChanged=true and populate mappedFieldData; leave both
+unset/false on a toggles-only save. mappedFieldData is a MAP keyed by
+mappingType enum name; the VALUE under each key is an object with THREE
+fields (NOT a bare {source:target} map):
+  {
+    "<mappingType>": {
+      "sourceEntity": "<source object API name>",   # e.g. WorkPlanTemplate
+      "targetEntity": "<target object API name>",   # e.g. WorkPlan
+      "mappedFields": { "<sourceFieldApiName>": "<targetFieldApiName>" }
+    }
+  }
+sourceEntity/targetEntity come from sourceApiName/targetApiName in the
+getObjectMappingConfiguration_3 read; each sourceField + targetField pair
+in mappedFields MUST come from that read's allSourceFields[] (the source)
+and that source field's targetFields[] (the allowed, type-compatible
+target). Omitting sourceEntity or targetEntity makes the controller build
+a null ObjectMapping and the Tooling upsert fails with
+dataTypeMismatchError. Persistence is a Tooling API upsert of the
+FieldServiceSettings metadata record (ObjectMappingItem[]) — mappings
+survive as org metadata, not an org pref. Verified example against a
+live org (200 true, idempotent re-apply):
+  "mappedFieldData": {
+    "WorkPlans_WorkPlanTemplate_WorkPlan": {
+      "sourceEntity": "WorkPlanTemplate", "targetEntity": "WorkPlan",
+      "mappedFields": {"Custom_text_field__c": "Custom_text_field__c"}},
+    "WorkPlans_WorkStepTemplate_WorkStep": {
+      "sourceEntity": "WorkStepTemplate", "targetEntity": "WorkStep",
+      "mappedFields": {"Custom_text_field__c": "Custom_text_field__c"}},
+    "WorkPlans_WorkPlanTemplateEntry_WorkStep": {
+      "sourceEntity": "WorkPlanTemplateEntry", "targetEntity": "WorkStep",
+      "mappedFields": {"Custom_text_field__c": "Custom_text_field_2__c"}}
+  }; idempotency: Save is idempotent for toggles — re-issuing the same payload is a safe
+no-op. All-hasXChanged=false is also a safe no-op (flag-gate strict).
+To roll back a toggle change: (1) capture the GET response before save;
+(2) re-PATCH with hasXChanged=true for each changed pair and the prior
+value.

package/skills/field-service-work-rule-designer-configure/SKILL.md

@@ -1,10 +1,8 @@
 ---
 name: field-service-work-rule-designer-configure
-description: "Designs the work rules for a Salesforce Field Service scheduling policy — the hard filters that determine which resources and time slots are eligible for an appointment. Step 2 of the three-part scheduling policy design flow; receives the policy block from sfs-scheduling-policy-designer and delegates to sfs-service-objective-designer when complete. Use this skill when a user wants to design or configure the work rules (hard eligibility filters) for a Field Service scheduling policy."
-user-invocable: false
+description: "Designs the work rules for a Salesforce Field Service scheduling policy — the hard filters that determine which resources and time slots are eligible for an appointment. Step 2 of the three-part scheduling policy design flow. Receives the policy block from sfs-scheduling-policy-designer and delegates to sfs-service-objective-designer when complete."
 metadata:
   version: "1.0"
-  domains: ["Field Service"]
 ---
 
 # Salesforce Field Service – Work Rule Designer
@@ -42,139 +40,119 @@ Each row: **name — engine (DB/Apex) — what it does.** "DB w/ ESO" means the
 | **TimeSlot Designated Work** | Apex | Reserves a time slot/shift for a specific work type — only that type schedules in that window. All-or-nothing rule (no relevance groups). |
 | **Service Crew Resources Availability** | Apex | Ensures a crew-type resource is only assigned when the crew meets the parent record's minimum crew size. |
 
-### Requirements mapping
-
-Don't start from the rule list — start from **what the business needs**, then map each requirement to the rule(s) that satisfy it. Walk the user through this mapping:
-
-| If the requirement is… | Use this work rule |
-|---|---|
-| Resources need specific skills / proficiency levels | **Match Skills**; **Extended Match** |
-| Non-skill matching factors (e.g., serviceable postal codes) | **Match Boolean**; **Match Skills**; **Extended Match** |
-| Breaks during the day / specific or multiple breaks | **Service Resource Availability** (+ work rule entries for multiple breaks, ESO) |
-| Can work go into overtime? Can resources travel outside working hours? | **Service Resource Availability** |
-| Max number / duration of appointments per resource per day | **Count Rule** |
-| A specific resource **must** be assigned | **Required Resources** |
-| A specific resource **must not** be assigned | **Excluded Resources** |
-| Customer has specific service-call time windows | **Service Appointment Visiting Hours** |
-| Ensure crew-type resources get scheduled | **Service Crew Resources Availability** |
-| Appointments have arrival windows / required arrival times | **Match Time Rule** |
-| Cap travel distance from home / control travel cost across large territories | **Maximum Travel from Home** — ask whether the cap is by **distance** or by **travel time** (see note below) |
-| Assign specific work types to a resource for part/all of a day | **TimeSlot Designated Work** |
-| Restrict work to the resource's **primary and secondary** service territory memberships | **Working Territories** |
+### Interview order — MANDATORY
 
-Always include exactly one **Service Resource Availability** rule — the only mandatory rule this skill emits. Never emit Earliest Start Permitted or Due Date — provisioned automatically.
+Walk through the 16 work rule types **in the exact order of the table in *The 16 work rule types* above** — top to bottom, one rule at a time. **Do NOT split the interview into a separate "which rules apply" pass and a later "configure them" pass, and do NOT reorder the rules.** For each rule, in order:
 
-**Arrival Window Match Time rules (opt-in default pair).** If the user wants appointments to honor customer **arrival windows**, ask them to confirm, and if they agree, emit **two** Match Time rules with these exact default settings — do not ask the user to fill these in, they are the standard arrival-window configuration:
+1. **Decide whether it applies.** Service Resource Availability is always in (no question). For every other rule, either the user's stated business needs already make it obviously needed, or ask the short **Applies when / ask** question in that rule's entry below. Interpret the user's needs against the *What it does* column — e.g. "resources need the right skills" → Match Skills; "cap travel from home" → Maximum Travel from Home.
+2. **If it applies and it has configuration, ask that rule's config question(s) right now** — before moving on to the next rule. Never defer configuration to the end. If the rule is selection-only (no config), just confirm it and continue.
 
-| Setting | Rule A | Rule B |
-|---|---|---|
-| Name | `Arrival Window Start` | `Arrival Window End` |
-| Service Schedule Time Property | `SchedStartTime` | `SchedStartTime` |
-| Service Time Operator | `Later than or Equal to` | `Before or Equal to` |
-| Service Time Property | `ArrivalWindowStartTime` | `ArrivalWindowEndTime` |
-| Pass Empty Values | `true` | `true` |
+Then continue to the next rule in the table. Ask one question at a time. Only after you have walked all 16 rules is the rule list final.
 
-Emit each as a Match Time work rule whose `params` carry those four values (keys `serviceScheduleTimeProperty`, `serviceTimeOperator`, `serviceTimeProperty`, `passEmptyValues`). These are separate from the mandatory Earliest Start Permitted / Due Date rules (never emitted).
+**Do NOT ask a relevance-group / subset question on every rule.** Most rules apply policy-wide, and asking "all or a subset?" after each one is noise. Instead:
 
-**Interpreting and emitting break times (clock time vs. shift-start offset):** A Service Resource Availability rule expresses breaks in one of two shapes, and **this skill decides the shape and emits the values the data-layer skill needs** — the data-layer skill never receives a clock time it has to convert. Choose the shape as follows:
-
-- **One fixed daily break at an absolute clock time** (e.g. "30 minutes at 12:00 every day") → emit it as an **absolute** break: `{ "mode": "absolute", "startClock": "12:00", "durationMinutes": 30 }`. No offset math, no working-day start needed.
-- **One or more breaks defined as an offset from the start of the working day** (e.g. "a 30-minute lunch starting 3 hours into the shift") → emit each as an **offset** break, in **minutes from the start of the working day**: `{ "mode": "offset", "earliestStartOffsetMinutes": 180, "latestEndOffsetMinutes": 240, "durationMinutes": 30 }`. All three of `earliestStartOffsetMinutes`, `latestEndOffsetMinutes`, and `durationMinutes` are **mandatory** for an offset break. **When the user states the break in offset terms already** (e.g. "3 hours after the start of day"), that offset *is* `earliestStartOffsetMinutes` (180) — **do not ask for the working-day start; you don't need it.**
-- **Breaks given as clock times but there is more than one** (e.g. "15 minutes at 10:00 and 30 minutes at 12:00") → you must use the **offset** shape, which means **converting each clock time into an offset from the start of the working day**. You cannot do that without knowing when the day starts, so **ask the user for the shift / working-day start**, then compute `earliestStartOffsetMinutes = (break start clock − day start)` in minutes for each break. Never assume the day starts at midnight (that would turn "10:00" into a wrong 600-minute offset). *(Only ask for the day start in this clock-time case — never when the break is already expressed as an offset.)*
+- **React to scoping the user volunteers.** If while answering a rule's question the user signals the rule is only for a specific scenario, workforce, or work type — e.g. "only for part-time techs," "just for installation jobs," "tighter cap in France" — *then* pursue it: confirm the basis (Service Territory Member for a resource subset, Service Appointment for a work subset), get the Boolean field name, and record `relevanceGroup: { basis, booleanField }` on that rule. (First check the rule supports that basis under ES&O — see *Relevance Groups*.)
+- **Otherwise sweep for it once, at the end.** After all 16 rules are walked, ask a single closing question: *"Are there any constraints here that should apply only to a certain part of your workforce or to certain types of work — rather than to everyone/everything? For example, different break or travel limits for part-time vs. full-time techs, or stricter handling for a specific work type or region."* Only if the user says yes do you scope the affected rules (per the *Relevance Groups* section). If no, leave every `relevanceGroup` null.
 
-**Always emit `latestEndOffsetMinutes` for every offset break — ask for it directly, do not fabricate a window.** The earliest start comes from what the user stated (an offset, or a converted clock time) — **do not invent ± tolerance windows around it** (no "±1 hour" / "±2 hour" options). If the user only gave a break start (or a duration with no stated finish-by), **ask them plainly for the latest the break may end**, phrased in the *same terms they used*: if they gave an offset ("starts 3 hours after start of day"), ask "what is the latest it may end, as time after the start of the day?" and convert (e.g. "4 hours after start" → 240); if they gave a clock time, ask for a clock time and convert with the day start. If the user says the break is fixed/pinned with no flex, set `latestEndOffsetMinutes = earliestStartOffsetMinutes + durationMinutes`. Never emit an offset break missing any of the three fields, and never guess the latest-end. If a break requirement is too involved to convert reliably, ask clarifying questions or recommend the manual approach rather than guessing.
+Always include exactly one **Service Resource Availability** rule — the only mandatory rule this skill emits. Never emit Earliest Start Permitted or Due Date — provisioned automatically.
 
-**Maximum Travel from Home — establish the cap type, not the unit.** When a requirement caps how far a resource may travel from home, **ask the user whether the cap is by distance or by travel time** — the two are configured differently and the data-layer skill needs to know which. Emit the value and the type in `params`: `{ "maxTravelFromHome": 50, "maxTravelFromHomeType": "Distance" | "Travel Time" }`. Interpret the user's phrasing to set the *type* — "50 miles"/"50 km" ⇒ `Distance`, "45 minutes" ⇒ `Travel Time` — but **do not ask for or emit a distance unit (miles vs km): it is not part of the work-rule config**; the unit is governed by the org's locale/distance settings elsewhere, so the rule stores only the number. For `Travel Time` the value is minutes. Never emit the cap value without its type.
+---
 
-### Per-rule configuration
+### The rules, in interview order
 
-Once the requirements mapping has selected which rules to build, configure the specifics for each. The **`Emit` line gives the exact `params` keys** — use these verbatim so the data-layer skill can map them. Only configure rules the user selected; skip the rest.
+Take these in the order shown — it matches the table above. For each entry: **Applies when** tells you how to decide it's needed; **Ask** lists the config questions to ask *immediately* on a yes; **Emit** gives the exact `params` keys — use them verbatim so the data-layer skill can map them.
 
 ---
 
-**Service Resource Availability** *(always present)*
-Gate: Always included — no selection needed.
+**1. Service Resource Availability** *(always present — the only mandatory rule)*
+Applies when: always. No applicability question.
 Ask:
 - "Can work run into **overtime**?" (yes/no)
 - "Can resources **travel outside working hours** to/from home?" — if yes, ask how many minutes from home (to first job) and to home (from last job); "no limit" = 120; "no" = 0 for both
-- Breaks interview (see *Interpreting and emitting break times*)
+- Breaks interview (see *Interpreting and emitting break times* below)
 
 Emit: `{ "enableOvertime": true|false, "travelFromHomeMinutes": <number>, "travelToHomeMinutes": <number>, "breaks": [ … ] }`
-Note: Travel values are minutes — 0 = no travel outside working hours, 120 = effectively unlimited. If user gives no availability detail, emit baseline (`enableOvertime: false`, travel keys and breaks omitted).
+Note: Travel values are minutes — 0 = no travel outside working hours, 120 = effectively unlimited. If the user gives no availability detail, emit baseline (`enableOvertime: false`, travel keys and breaks omitted).
 
 ---
 
-**Match Time Rule** *(arrival windows)*
-Gate: Only if selected in requirements mapping.
-Ask: "Should appointments honor customer **arrival windows**?"
-Emit: Two default rules from the Arrival Window table — no further questions.
+**2. Match Time Rule** *(arrival windows)*
+Applies when: appointments should honor customer **arrival windows** / required arrival times. Ask: "Should appointments honor customer arrival windows?"
+Emit: on a yes, emit the **two** default rules from the *Arrival Window Match Time rules* table below — do not ask the user to fill these in.
 
 ---
 
-**Match Skills**
-Gate: Only if selected in requirements mapping.
+**3. Match Skills**
+Applies when: resources need specific skills / proficiency levels.
 Ask: "Should the resource also **meet a minimum skill level** (proficiency), or is simply *having* the skill enough?"
 Emit: `{ "matchSkillLevel": true|false }`
 Note: Do not ask about skill-type AND/OR logic — this skill does not configure `skillTypeLogic`.
 
 ---
 
-**Match Fields**
-Gate: Only if selected in requirements mapping.
+**4. Match Fields**
+Applies when: one appointment field must match one resource field (1:1). (For one appointment field vs. multiple resource values, use Extended Match instead.)
 Ask: "Which Service Appointment field must match which Service Resource field, and with what operator?"
 Emit: `{ "serviceProperty": "<SA field>", "resourceProperty": "<resource field>", "booleanOperator": "=" }`
 Note: Operator is one of `=`, `>=`, `<=`, `>`, `<` (default `=`). Field names are the customer's own — pass through as given.
 
 ---
 
-**Match Boolean**
-Gate: Only if selected in requirements mapping.
+**5. Match Boolean**
+Applies when: a checkbox on the resource must be true/false — including non-skill matching factors (e.g., serviceable postal codes).
 Ask: "Which checkbox field on the resource must be true (or false)?"
 Emit: `{ "resourceProperty": "<resource field>", "value": true|false }`
 Note: Max 5 Match Boolean rules per policy.
 
 ---
 
-**Maximum Travel from Home**
-Gate: Only if selected in requirements mapping.
-Ask: "Is the cap by **distance** or by **travel time**?" (see cap-type note in Requirements mapping)
-Emit: `{ "maxTravelFromHome": <number>, "maxTravelFromHomeType": "Distance"|"Travel Time" }`
-Note: Distance unit (miles vs km) is not part of the rule — governed by org locale. For Travel Time, value is minutes.
+**6. Extended Match** *(advisory only — data-layer skill will not build this)*
+Applies when: custom-criteria matching via a junction object (e.g., serviceable postal codes, product lines).
+Ask: None — no params to collect. Advise the user to set up before deploying:
+1. A junction object with exactly **two** Master-Detail relationships (to Service Resource + matched object) — packaged trigger requires exactly two or the rule fails
+2. A Service Appointment Lookup field driving the match; a reference field on the junction matched against it
+3. Once those exist, create and configure the rule manually in Setup (Field Service Settings → Scheduling → Work Rules)
+
+Capture intended objects/fields in `prerequisites` as advisory text — do not emit in `workRules[]`.
+
+---
+
+**7. Match Territory** — *(skip entirely; not part of the interview)*
+This interview never emits a standalone Match Territory rule. **Skip it silently** — do not ask a Match Territory question, and do not announce or narrate that you are skipping it. Move straight from rule 6 to rule 8 with no mention of Match Territory at all. (If a user explicitly asks for primary/relocation-only territory scoping, advise manual configuration then — but never raise it yourself. Also: don't cover a resource by both Match Territory and Working Territories.)
 
 ---
 
-**Working Territories**
-Gate: Only if selected in requirements mapping.
+**8. Working Territories**
+Applies when: work must be restricted to the resource's **primary and secondary** service territory memberships.
 Ask: None — selecting the rule is sufficient.
 Emit: `{ "workingLocationEnablePrimary": true }`
-Note: No separate Match Territory question — the interview does not emit a standalone Match Territory rule. If primary/relocation-only scoping is needed, advise manual configuration.
 
 ---
 
-**Service Crew Resources Availability**
-Gate: Only if selected in requirements mapping.
-Ask:
-- "Should the rule evaluate individual crew members' availability and skills, not just the crew record?" → `considerCrewMembership`
-- "What is the maximum number of extra resources beyond the base crew that can be pulled in?" → `maxAdditionalResources` (optional)
-
-Emit: `{ "considerCrewMembership": true|false, "maxAdditionalResources": <number> }` (omit `maxAdditionalResources` if blank)
+**9. Maximum Travel from Home**
+Applies when: capping distance/travel time between a resource's home and any assigned appointment / controlling travel cost across large territories.
+Ask: "Is the cap by **distance** or by **travel time**?" (see the cap-type note below), plus the cap value.
+Emit: `{ "maxTravelFromHome": <number>, "maxTravelFromHomeType": "Distance"|"Travel Time" }`
+Note: Distance unit (miles vs km) is not part of the rule — governed by org locale. For Travel Time, value is minutes.
 
 ---
 
-**Extended Match** *(advisory only — data-layer skill will not build this)*
-Gate: Only if selected in requirements mapping.
-Ask: None — no params to collect.
-Advise the user to set up before deploying:
-1. A junction object with exactly **two** Master-Detail relationships (to Service Resource + matched object) — packaged trigger requires exactly two or the rule fails
-2. A Service Appointment Lookup field driving the match; a reference field on the junction matched against it
-3. Once those exist, create and configure the rule manually in Setup (Field Service Settings → Scheduling → Work Rules)
+**10. Required Resources** *(selection-only)*
+Applies when: any work order ever has a resource marked **Required** that must always be assigned. Ask: "Do any work orders ever have a specific resource marked *Required* that must always be assigned to that job?"
+Emit: `{}`
+Prerequisite: Resource Preference records must exist on the work order / WOLI — the rule enforces them but does not create them.
 
-Capture intended objects/fields in `prerequisites` as advisory text — do not emit in `workRules[]`.
+---
+
+**11. Excluded Resources** *(selection-only)*
+Applies when: any work order ever has a resource marked **Excluded** that must never be assigned. Ask: "Do any work orders ever have a resource marked *Excluded* that must never be assigned?"
+Emit: `{}`
+Prerequisite: Resource Preference records must exist on the work order / WOLI — the rule enforces them but does not create them.
 
 ---
 
-**Count Rule**
-Gate: Only if selected in requirements mapping.
+**12. Count Rule**
+Applies when: capping the number/duration of appointments (or a custom value) per resource per day.
 Ask: Have the user describe the limit in plain terms, then classify into:
 - `countBy` — `"Appointments"` (count of jobs), `"Hours"` (duration cap), or `"Custom"` (sum of a custom SA field)
 - `maxValue` — the numeric cap (for Hours, convert to hours)
@@ -185,32 +163,67 @@ Note: Time Resolution is always Daily; counted object is always Service Appointm
 
 ---
 
-**Selection-only rules** *(no config fields — each rule acts as an on/off switch that tells the scheduler to enforce constraints defined elsewhere in the org; selected in requirements mapping, no further questions needed)*
-
-**Required Resources / Excluded Resources**
-Gate: Only if selected in requirements mapping.
-Emit: `{}`
-Prerequisite: Resource Preference records must exist on the work order / WOLI — the rule enforces them but does not create them.
-
-**Work Capacity** *(ESO only)*
-Gate: Only if selected in requirements mapping.
+**13. Work Capacity** *(ESO only — selection-only)*
+Applies when: Work Capacity Limit records cap how much work schedules per territory. Ask: "Do you use Work Capacity Limit records to cap how much work can be scheduled per territory?"
 Emit: `{}`
 Prerequisite: WorkCapacityLimit records must be configured per territory outside the policy.
 
-**Service Appointment Visiting Hours**
-Gate: Only if selected in requirements mapping.
+---
+
+**14. Service Appointment Visiting Hours** *(selection-only)*
+Applies when: customers have allowed visit windows that should block scheduling outside those hours. Ask: "Do customers have allowed visit windows (e.g., weekdays only, or mornings only) that should block scheduling outside those hours?"
 Emit: `{}`
-Note: Do not ask for the windows — they are per-account data on OperatingHours records, not a policy-wide value. (No relevance-group scoping.)
+Note: Do not ask for the windows — they are per-account data on OperatingHours records, not a policy-wide value. All-or-nothing rule — no relevance-group scoping.
 Prerequisite: Each account must have visiting/operating hours populated; the Work Order's Visiting Hours must resolve from the account.
 
-**TimeSlot Designated Work**
-Gate: Only if selected in requirements mapping.
+---
+
+**15. TimeSlot Designated Work** *(selection-only)*
+Applies when: certain time slots must be reserved for specific types of work. Ask: "Do you need to reserve certain time slots for specific types of work (e.g., install work only in morning slots)?"
 Emit: `{}`
-Note: Do not ask for slot→work mappings — that is data setup. Phrase the selection as "types of work," not "Work Type" (the designation is broader than the Work Type object). (No relevance-group scoping.)
+Note: Do not ask for slot→work mappings — that is data setup. Phrase the selection as "types of work," not "Work Type" (the designation is broader than the Work Type object). All-or-nothing rule — no relevance-group scoping.
 Prerequisite: Time slots must be configured to designate the intended work.
 
 ---
 
+**16. Service Crew Resources Availability**
+Applies when: crew-type resources must only be assigned when the crew meets the parent record's minimum crew size.
+Ask:
+- "Should the rule evaluate individual crew members' availability and skills, not just the crew record?" → `considerCrewMembership`
+- "What is the maximum number of extra resources beyond the base crew that can be pulled in?" → `maxAdditionalResources` (optional)
+
+Emit: `{ "considerCrewMembership": true|false, "maxAdditionalResources": <number> }` (omit `maxAdditionalResources` if blank)
+
+---
+
+### Configuration reference notes
+
+These deep-dives support the **Ask** lines above; consult them when configuring the rule that references them.
+
+**Arrival Window Match Time rules (default pair — rule 2).** When the user confirms appointments should honor customer arrival windows, emit **two** Match Time rules with these exact default settings — do not ask the user to fill these in, they are the standard arrival-window configuration:
+
+| Setting | Rule A | Rule B |
+|---|---|---|
+| Name | `Arrival Window Start` | `Arrival Window End` |
+| Service Schedule Time Property | `SchedStartTime` | `SchedStartTime` |
+| Service Time Operator | `Later than or Equal to` | `Before or Equal to` |
+| Service Time Property | `ArrivalWindowStartTime` | `ArrivalWindowEndTime` |
+| Pass Empty Values | `true` | `true` |
+
+Emit each as a Match Time work rule whose `params` carry those four values (keys `serviceScheduleTimeProperty`, `serviceTimeOperator`, `serviceTimeProperty`, `passEmptyValues`). These are separate from the mandatory Earliest Start Permitted / Due Date rules (never emitted).
+
+**Interpreting and emitting break times — clock time vs. shift-start offset (rule 1).** A Service Resource Availability rule expresses breaks in one of two shapes, and **this skill decides the shape and emits the values the data-layer skill needs** — the data-layer skill never receives a clock time it has to convert. Choose the shape as follows:
+
+- **One fixed daily break at an absolute clock time** (e.g. "30 minutes at 12:00 every day") → emit it as an **absolute** break: `{ "mode": "absolute", "startClock": "12:00", "durationMinutes": 30 }`. No offset math, no working-day start needed.
+- **One or more breaks defined as an offset from the start of the working day** (e.g. "a 30-minute lunch starting 3 hours into the shift") → emit each as an **offset** break, in **minutes from the start of the working day**: `{ "mode": "offset", "earliestStartOffsetMinutes": 180, "latestEndOffsetMinutes": 240, "durationMinutes": 30 }`. All three of `earliestStartOffsetMinutes`, `latestEndOffsetMinutes`, and `durationMinutes` are **mandatory** for an offset break. **When the user states the break in offset terms already** (e.g. "3 hours after the start of day"), that offset *is* `earliestStartOffsetMinutes` (180) — **do not ask for the working-day start; you don't need it.**
+- **Breaks given as clock times but there is more than one** (e.g. "15 minutes at 10:00 and 30 minutes at 12:00") → you must use the **offset** shape, which means **converting each clock time into an offset from the start of the working day**. You cannot do that without knowing when the day starts, so **ask the user for the shift / working-day start**, then compute `earliestStartOffsetMinutes = (break start clock − day start)` in minutes for each break. Never assume the day starts at midnight (that would turn "10:00" into a wrong 600-minute offset). *(Only ask for the day start in this clock-time case — never when the break is already expressed as an offset.)*
+
+**Always emit `latestEndOffsetMinutes` for every offset break — ask for it directly, do not fabricate a window.** The earliest start comes from what the user stated (an offset, or a converted clock time) — **do not invent ± tolerance windows around it** (no "±1 hour" / "±2 hour" options). If the user only gave a break start (or a duration with no stated finish-by), **ask them plainly for the latest the break may end**, phrased in the *same terms they used*: if they gave an offset ("starts 3 hours after start of day"), ask "what is the latest it may end, as time after the start of the day?" and convert (e.g. "4 hours after start" → 240); if they gave a clock time, ask for a clock time and convert with the day start. If the user says the break is fixed/pinned with no flex, set `latestEndOffsetMinutes = earliestStartOffsetMinutes + durationMinutes`. Never emit an offset break missing any of the three fields, and never guess the latest-end. If a break requirement is too involved to convert reliably, ask clarifying questions or recommend the manual approach rather than guessing.
+
+**Maximum Travel from Home — establish the cap type, not the unit (rule 9).** When a requirement caps how far a resource may travel from home, **ask the user whether the cap is by distance or by travel time** — the two are configured differently and the data-layer skill needs to know which. Emit the value and the type in `params`: `{ "maxTravelFromHome": 50, "maxTravelFromHomeType": "Distance" | "Travel Time" }`. Interpret the user's phrasing to set the *type* — "50 miles"/"50 km" ⇒ `Distance`, "45 minutes" ⇒ `Travel Time` — but **do not ask for or emit a distance unit (miles vs km): it is not part of the work-rule config**; the unit is governed by the org's locale/distance settings elsewhere, so the rule stores only the number. For `Travel Time` the value is minutes. Never emit the cap value without its type.
+
+---
+
 ## Relevance Groups
 
 A relevance group scopes a single work rule or service objective so it applies only to certain appointments or resources, instead of the whole policy. This lets one policy hold different logic for different work or resource types — e.g., different break/travel limits for part-time vs. full-time employees, or expedited scheduling for high-value accounts.
@@ -286,3 +299,16 @@ When the user confirms the work rules, delegate to `sfs-service-objective-design
 Do not start the service objective interview here. Transition message:
 
 > "Work rules are locked in. Next: service objectives — the scoring criteria that rank the eligible candidates. I'll walk through the trade-off questions one at a time."
+
+<!-- skill-validate: ignore-start -->
+<!-- codey:operations start -->
+## Operations Reference
+
+Operations this skill uses — routing and dependency reference.
+
+| Operation | Purpose | Status | Call | Depends on |
+|-----------|---------|--------|------|------------|
+| `emit-work-rules-block` | write | — | — | — |
+| `handoff-to-service-objective-designer` | delegate | — | → `sfs-setup-experience/sfs-service-objective-designer` | `emit-work-rules-block` |
+<!-- codey:operations end -->
+<!-- skill-validate: ignore-end -->