@salesforce/afv-skills 1.48.0 → 1.50.0

package/skills/field-service-data-capture-form-deployer-configure/references/field-types.md

@@ -0,0 +1,297 @@
+# Field types reference
+
+Mapping of intermediate-JSON `fieldType` to the runtime component used in the deployed Flow. The `Flow strategy` column is the `fieldType` value in the Flow `Metadata` JSON (see [flow-metadata-json.md](flow-metadata-json.md)). **All names here have been verified against a live Field Service org by retrieving real flows and deploying probe flows** (May 2026).
+
+> **Picking a type:** classify from the actual control on the form, not from the field's label or name. A text line labeled "Signature" is `ShortText`. A textarea labeled "Photo of damage" is `LongText`. Only emit `Signature`, `UploadFile`, `UploadImage`, `FileView`, `Address`, `Matrix`, or `Repeater` when the source shows the corresponding widget (sign-here pad, file/camera picker, compound address, row-shared grid, user-added rows table) — or when the user explicitly describes that widget in prose. See the "control evidence" table in `extraction-prompt.md`.
+
+## Verified types
+
+| `fieldType`     | `extensionName`                                | Flow strategy            |
+|-----------------|------------------------------------------------|--------------------------|
+| `ShortText`     | `runtime_service_fieldservice:dcTextInput`     | `ComponentInstance`      |
+| `LongText`      | `runtime_service_fieldservice:dcLongText`      | `ComponentInstance`      |
+| `Name`          | `runtime_service_fieldservice:dcName`          | `ComponentInstance`      |
+| `Email`         | `runtime_service_fieldservice:dcEmail`         | `ComponentInstance`      |
+| `Phone`         | `runtime_service_fieldservice:dcPhone`         | `ComponentInstance`      |
+| `Numeric`       | `runtime_service_fieldservice:dcNumeric`       | `ComponentInstance`      |
+| `Counter`       | `runtime_service_fieldservice:dcCounter`       | `ComponentInstance` (supports `min`, `max`, `value` numeric params) |
+| `Date`          | `runtime_service_fieldservice:dcDate`          | `ComponentInstance`      |
+| `DateTime`      | `runtime_service_fieldservice:dcDateTime`      | `ComponentInstance`      |
+| `Checkbox`      | `runtime_service_fieldservice:dcCheckbox`      | `ComponentInstance`      |
+| `Toggle`        | `runtime_service_fieldservice:dcToggle`        | `ComponentInstance`      |
+| `Picklist`      | `runtime_service_fieldservice:dcPicklist`      | `ComponentChoice`        |
+| `Radio`         | `runtime_service_fieldservice:dcRbGroup`       | `ComponentChoice` (verified May 2026 via retrieved Inventory_Transfer flow) |
+| `CheckboxGroup` | `runtime_service_fieldservice:dcCbGroup`       | `ComponentMultiChoice`   |
+| `Signature`     | `runtime_service_fieldservice:dcSignature`     | `ComponentInstance` (auto-wires `parentRecordId` and `recordId` to the standard input variables) |
+| `UploadFile`    | `runtime_service_fieldservice:dcUpFile`        | `ComponentInstance` (auto-wires `recordId` → `parentRecordId`) |
+| `UploadImage`   | `runtime_service_fieldservice:dcUpImage`       | `ComponentInstance` (auto-wires `recordId` → `parentRecordId`) |
+| `Images`        | `runtime_service_fieldservice:dcImages`        | `ComponentInstance` (gallery viewer, auto-wires `recordId` → `parentRecordId`) |
+| `Address`       | `runtime_service_fieldservice:dcAddress`       | `ComponentInstance` (compound street/city/state/zip widget) |
+| `Matrix`        | `runtime_service_fieldservice:dcMatrix`        | `ComponentMultiChoice` (column choices via `<choiceReferences>`; row labels via `questions` JSON-array input parameter) |
+| `Lookup`        | `runtime_service_fieldservice:dcLookup`        | `ComponentInstance` (requires `lookupObject`; optional `lookupSearchFields`, `lookupMulti`) |
+| `FileView`      | `runtime_service_fieldservice:dcFileView`      | `ComponentInstance` (requires `fileName` — static asset filename without extension) |
+| `DisplayText`   | (native — no extension)                        | native `DisplayText`     |
+| `Repeater`      | (native — no extension; nested `<fields>`)     | native `Repeater` (verified May 2026; supports any `ComponentInstance` child) |
+
+## Falls back to a placeholder
+
+| `fieldType`  | Falls back to                               | Why |
+|--------------|---------------------------------------------|-----|
+| `Lookup` *with no `lookupObject`* | `dcTextInput` w/ `[Lookup — set objectApiName in Flow Builder]` prefix | `dcLookup` deploys but won't render without an `objectApiName`. Supply `lookupObject` in the spec or the admin must wire it up in Flow Builder. |
+| `FileView` *with no `fileName`* | `dcTextInput` w/ `[FileView — set fileName in Flow Builder]` prefix | `dcFileView` needs a static asset `fileName`. |
+
+## Required Flow boilerplate
+
+A Data Capture Flow won't deploy without these keys in `Metadata`:
+
+1. **`environments`** must include `Offline`:
+   ```json
+   "environments": ["Offline"]
+   ```
+2. **Three input variables** (Text, Available for Input):
+   ```json
+   "variables": [
+     { "name": "parentObjectType", "dataType": "String", "isCollection": false, "isInput": true, "isOutput": false },
+     { "name": "parentRecordId",   "dataType": "String", "isCollection": false, "isInput": true, "isOutput": false },
+     { "name": "recordId",         "dataType": "String", "isCollection": false, "isInput": true, "isOutput": false }
+   ]
+   ```
+3. **`processType`** must be `DataCaptureFlow`.
+
+## Choice/MultiChoice fields
+
+For `Picklist`, `Radio` (`dcRbGroup`), and `CheckboxGroup`, options are NOT inline parameters. They are top-level `choices` entries referenced from the field via a `choiceReferences` array:
+
+```json
+"choices": [
+  { "name": "Good", "choiceText": "Good", "dataType": "String", "value": { "stringValue": "Good" } }
+]
+```
+```json
+{
+  "name": "overallCondition",
+  "choiceReferences": ["Good", "Fair", "Poor"],
+  "extensionName": "runtime_service_fieldservice:dcPicklist",
+  "fieldText": "Overall Condition",
+  "fieldType": "ComponentChoice",
+  "inputsOnNextNavToAssocScrn": "UseStoredValues",
+  "isRequired": true,
+  "storeOutputAutomatically": true
+}
+```
+
+Dedupe choices across the whole flow — two fields with `["Good","Fair","Poor"]` share the same three `choices` entries.
+
+## Repeater fields
+
+`Repeater` is a native Flow field type — not a component. The JSON shape (children are a nested `fields` array):
+
+```json
+{
+  "name": "Part",
+  "fieldType": "Repeater",
+  "fields": [
+    { "name": "Quantity",    "extensionName": "runtime_service_fieldservice:dcCounter",   "fieldType": "ComponentInstance" },
+    { "name": "Part_Number", "extensionName": "runtime_service_fieldservice:dcTextInput", "fieldType": "ComponentInstance" }
+  ],
+  "isRequired": false,
+  "styleProperties": { "verticalAlignment": { "stringValue": "top" }, "width": { "stringValue": "12" } }
+}
+```
+
+In the spec, supply children as `repeaterFields`:
+
+```json
+{
+  "fieldName": "Part",
+  "fieldLabel": "Parts",
+  "fieldType": "Repeater",
+  "isRequired": false,
+  "repeaterFields": [
+    { "fieldName": "Quantity", "fieldLabel": "Quantity", "fieldType": "Counter", "isRequired": true, "min": 1, "value": 1 },
+    { "fieldName": "Part_Number", "fieldLabel": "Part Number", "fieldType": "ShortText", "isRequired": true },
+    { "fieldName": "Part_Description", "fieldLabel": "Part Description", "fieldType": "ShortText", "isRequired": true }
+  ]
+}
+```
+
+The runtime exposes the captured rows as the collection `<RepeaterName>.AddedItems`, with each row's child accessible as `<loopVar>.<ChildName>.value` inside a Loop element. See `flow-metadata-json.md` for the loop/createRecord pattern.
+
+## Counter min/max/value
+
+`dcCounter` accepts these optional numeric input parameters: `min`, `max`, `value` (initial value). In the spec:
+
+```json
+{
+  "fieldName": "Quantity",
+  "fieldLabel": "Quantity",
+  "fieldType": "Counter",
+  "isRequired": true,
+  "min": 1,
+  "max": 999,
+  "value": 1
+}
+```
+
+## Specialized component spec keys
+
+### Signature / UploadFile / UploadImage / Images
+
+Auto-wired — no extra spec keys needed. Inject:
+- `Signature` → `parentRecordId` and `recordId` input parameters, both as `{ "elementReference": ... }` to the flow's standard input variables of the same name.
+- `UploadFile` / `UploadImage` / `Images` → `recordId` input parameter as `{ "elementReference": "parentRecordId" }` (the runtime attaches the captured file/image to the parent record passed in via `parentRecordId`).
+
+These standard input variables are present on every flow:
+
+```json
+"variables": [
+  { "name": "parentObjectType", "dataType": "String", "isCollection": false, "isInput": true, "isOutput": false },
+  { "name": "parentRecordId",   "dataType": "String", "isCollection": false, "isInput": true, "isOutput": false },
+  { "name": "recordId",         "dataType": "String", "isCollection": false, "isInput": true, "isOutput": false }
+]
+```
+
+So `Signature` / `UploadFile` / `UploadImage` / `Images` deploy and run end-to-end as long as the flow is launched from a standard Field Service entry point (Mobile App, Work Order, Asset, etc.) that supplies `parentRecordId`.
+
+### Address
+
+No extra spec keys. Renders as `dcAddress` ComponentInstance with the field label.
+
+### Matrix
+
+```json
+{
+  "fieldName": "PreTripChecklist",
+  "fieldLabel": "Pre-trip checklist",
+  "fieldType": "Matrix",
+  "isRequired": true,
+  "options":   ["OK", "NOK", "N/A"],
+  "matrixRows": ["Tires", "Lights", "Brakes", "Fluids"]
+}
+```
+
+- `options` become column choices (`<choiceReferences>`), exactly like Picklist.
+- `matrixRows` become per-row prompts, JSON-encoded into the `questions` input parameter as a string array.
+
+### Lookup
+
+```json
+{
+  "fieldName": "AssetLookup",
+  "fieldLabel": "Asset",
+  "fieldType": "Lookup",
+  "isRequired": true,
+  "lookupObject": "Asset",
+  "lookupSearchFields": "Name, SerialNumber",
+  "lookupMulti": false
+}
+```
+
+- `lookupObject` (required) — the object API name to look up against.
+- `lookupSearchFields` — comma-separated field API names searched by typeahead.
+- `lookupMulti` (or `isMultiSelection`) — `true` to allow selecting multiple records.
+
+If `lookupObject` is missing, the field renders as a labeled ShortText placeholder so the flow still deploys.
+
+### FileView
+
+```json
+{
+  "fieldName": "ManualPreview",
+  "fieldLabel": "Manual",
+  "fieldType": "FileView",
+  "fileName": "service_manual_v3"
+}
+```
+
+`fileName` is the static-asset filename (without extension). If missing, falls back to a labeled ShortText placeholder.
+
+## Visibility rules
+
+A field can be conditionally shown based on a previously-captured field. The spec shape:
+
+```json
+{
+  "fieldName": "Work_Order_Number",
+  "fieldLabel": "Work Order Number",
+  "fieldType": "ShortText",
+  "isRequired": true,
+  "visibility": {
+    "field": "To",
+    "operator": "EqualTo",
+    "value": "Work Order"
+  }
+}
+```
+
+Look up the matching choice api name (e.g. `Work_Order`) and emit a `visibilityRule` on the field:
+
+```json
+"visibilityRule": {
+  "conditionLogic": "and",
+  "conditions": [
+    { "leftValueReference": "Work_Order", "operator": "EqualTo", "rightValue": { "booleanValue": true } }
+  ]
+}
+```
+
+> Note: Field Service's runtime evaluates visibility against the choice's *boolean selection state*, not the parent field's string value. The `leftValueReference` is therefore the **choice api name**, not the field name. If `visibility.value` doesn't match any known choice, warn and skip the rule.
+
+## Field name rules
+
+- `fieldName` must match `^[A-Za-z][A-Za-z0-9_]*$`, ≤ 80 chars, unique per flow.
+- Choice api names are derived from the option's display text (sanitized).
+- Screen api names are derived as `Screen_<PascalCaseScreenKey>`.
+
+## Sections
+
+A Section is a visual grouping inside a screen, rendered as a Salesforce Flow `RegionContainer` (one full-width Region column) with a header bar showing the section label. Use sections **only when the source explicitly shows them** (visible group headers in an image/PDF, or the user describing named sub-sections in prose). A flat field list is the right default.
+
+To declare sections, mix section-header items into a screen's field list. A section header is an item with a `section` key and **no** `fieldName`:
+
+```json
+{
+  "screens": {
+    "AssetInspection": [
+      { "section": "Asset Details" },
+      { "fieldName": "AssetName",    "fieldLabel": "Asset Name",    "fieldType": "ShortText" },
+      { "fieldName": "Manufacturer", "fieldLabel": "Manufacturer",  "fieldType": "Picklist",  "options": ["Demag","Konecranes"] },
+
+      { "section": "Inspection" },
+      { "fieldName": "Condition",    "fieldLabel": "Condition",     "fieldType": "Picklist",  "options": ["Pass","Fail"] },
+      { "fieldName": "Notes",        "fieldLabel": "Notes",         "fieldType": "LongText"   }
+    ]
+  }
+}
+```
+
+Rules:
+- A `section` item starts a new section. All subsequent fields belong to it until the next `section` item or the end of the screen.
+- Fields appearing **before** the first `section` item are bucketed into an implicit section labeled `"General"`.
+- Specs with no `section` items deploy as a flat field list — fully backward-compatible.
+- Sections are **single-column, full-width** by default. Multi-column layouts are not generated; if a source shows two columns, file each field separately and let it stack.
+- Section api names are auto-derived from the label (`Sec_<sanitized>`, deduped within the screen).
+
+The emitted JSON matches the verified `SectionWithHeader` pattern from `salesforce-data-capture/examples/Data_Capture_All_Components.flow-meta.xml`:
+
+```json
+{
+  "name": "Sec_Asset_Details",
+  "fieldText": "Asset Details",
+  "fieldType": "RegionContainer",
+  "fields": [
+    {
+      "name": "Sec_Asset_Details_Col1",
+      "fieldType": "Region",
+      "fields": [ /* AssetName, Manufacturer, etc. */ ],
+      "inputParameters": [
+        { "name": "width", "value": { "stringValue": "12" } }
+      ],
+      "isRequired": false
+    }
+  ],
+  "isRequired": false,
+  "regionContainerType": "SectionWithHeader",
+  "styleProperties": {}
+}
+```

package/skills/field-service-data-capture-form-deployer-configure/references/flow-metadata-json.md

@@ -0,0 +1,243 @@
+# Flow Metadata JSON — Data Capture Flow
+
+A Data Capture Flow is a Salesforce Flow with `processType=DataCaptureFlow`. It is created and updated through the **Tooling API `Flow` sObject**, whose `Metadata` field is a JSON object — the same shape you get back from `GET /services/data/vXX.0/tooling/sobjects/Flow/{id}`. There is **no `.flow-meta.xml`, no zip, and no SFDX project** — the agent assembles this JSON inline and POSTs it.
+
+The shape below is the JSON transliteration of the Metadata blob retrieved from real flows in a live Field Service org (`Data_Capture_Asset_Inspection`, `Inventory_Transfer`) and verified against that org's `Flow` describe.
+
+## The deploy call
+
+```http
+POST /services/data/vXX.0/tooling/sobjects/Flow
+{
+  "FullName": "<FlowApiName>",
+  "Metadata": { ...the object below... }
+}
+```
+
+- `FullName` is the Flow API name (matches `^[A-Z][A-Za-z0-9_]*$`). `FullName` is set-on-create only.
+- A 201 with `success: true` returns the new Flow version id.
+- To **activate on create**, set `Metadata.status: "Active"`. Default `"Draft"` so the user reviews in Flow Builder first — activation is via `Flow.Metadata.status`, not a separate `FlowDefinition` write (`FlowDefinition.ActiveVersionId` is not directly writable).
+- To **update** an existing version, `PATCH /services/data/vXX.0/tooling/sobjects/Flow/{id}` with `{"Metadata": {...full metadata...}}` (the editor skill's redeploy path).
+
+## JSON ↔ XML mapping rule
+
+The Metadata JSON is a mechanical transliteration of the Flow XML:
+
+- Each XML element becomes a JSON key. `<label>X</label>` → `"label": "X"`.
+- **Repeated** elements become a JSON **array**: multiple `<screens>` → `"screens": [ {...}, {...} ]`; multiple `<choiceReferences>` → `"choiceReferences": ["A","B"]`.
+- Typed value wrappers keep their wrapper key: `<value><stringValue>X</stringValue></value>` → `"value": {"stringValue": "X"}`; `<booleanValue>true</booleanValue>` → `{"booleanValue": true}`; `<numberValue>1.0</numberValue>` → `{"numberValue": 1.0}`; `<elementReference>Foo</elementReference>` → `{"elementReference": "Foo"}`.
+- Booleans and numbers are real JSON scalars, not strings.
+
+## Minimum-deployable shape
+
+```json
+{
+  "processType": "DataCaptureFlow",
+  "environments": ["Offline"],
+  "areMetricsLoggedToDataCloud": false,
+  "label": "HVAC Compressor Inspection",
+  "interviewLabel": "HVAC Compressor Inspection {!$Flow.CurrentDateTime}",
+  "description": "Generated from spec: HVAC Compressor Inspection",
+  "status": "Draft",
+
+  "processMetadataValues": [
+    { "name": "BuilderType", "value": { "stringValue": "LightningFlowBuilder" } },
+    { "name": "CanvasMode",  "value": { "stringValue": "AUTO_LAYOUT_CANVAS" } }
+  ],
+
+  "choices": [
+    { "name": "Good", "choiceText": "Good", "dataType": "String", "value": { "stringValue": "Good" } }
+  ],
+
+  "start": { "locationX": 0, "locationY": 0, "connector": { "targetReference": "Screen_HeaderInformation" } },
+
+  "screens": [
+    {
+      "name": "Screen_HeaderInformation",
+      "label": "Header Information",
+      "locationX": 0, "locationY": 0,
+      "allowBack": true, "allowFinish": true, "allowPause": true,
+      "showFooter": true, "showHeader": true,
+      "connector": { "targetReference": "Screen_OperatingParameters" },
+      "fields": [
+
+        {
+          "name": "jobName",
+          "extensionName": "runtime_service_fieldservice:dcTextInput",
+          "fieldType": "ComponentInstance",
+          "inputParameters": [
+            { "name": "label",    "value": { "stringValue": "Job Name" } }
+          ],
+          "inputsOnNextNavToAssocScrn": "UseStoredValues",
+          "isRequired": true,
+          "storeOutputAutomatically": true,
+          "styleProperties": {
+            "verticalAlignment": { "stringValue": "top" },
+            "width": { "stringValue": "12" }
+          }
+        },
+
+        {
+          "name": "Quantity",
+          "extensionName": "runtime_service_fieldservice:dcCounter",
+          "fieldType": "ComponentInstance",
+          "inputParameters": [
+            { "name": "label", "value": { "stringValue": "Quantity" } },
+            { "name": "min",   "value": { "numberValue": 1.0 } },
+            { "name": "value", "value": { "numberValue": 1.0 } }
+          ]
+        },
+
+        {
+          "name": "To",
+          "choiceReferences": ["Truck", "Work_Order"],
+          "extensionName": "runtime_service_fieldservice:dcRbGroup",
+          "fieldText": "To",
+          "fieldType": "ComponentChoice"
+        },
+
+        {
+          "name": "issuesIdentified",
+          "choiceReferences": ["Corrosion", "Wear", "Leakage"],
+          "extensionName": "runtime_service_fieldservice:dcCbGroup",
+          "fieldText": "Issues Identified",
+          "fieldType": "ComponentMultiChoice"
+        },
+
+        {
+          "name": "Work_Order_Number",
+          "extensionName": "runtime_service_fieldservice:dcTextInput",
+          "fieldType": "ComponentInstance",
+          "inputParameters": [
+            { "name": "label",    "value": { "stringValue": "Work Order Number" } }
+          ],
+          "isRequired": true,
+          "visibilityRule": {
+            "conditionLogic": "and",
+            "conditions": [
+              { "leftValueReference": "Work_Order", "operator": "EqualTo", "rightValue": { "booleanValue": true } }
+            ]
+          }
+        },
+
+        {
+          "name": "Part",
+          "fieldType": "Repeater",
+          "fields": [
+            { "name": "Quantity",    "extensionName": "runtime_service_fieldservice:dcCounter",   "fieldType": "ComponentInstance" },
+            { "name": "Part_Number", "extensionName": "runtime_service_fieldservice:dcTextInput", "fieldType": "ComponentInstance" }
+          ],
+          "isRequired": false,
+          "styleProperties": { "verticalAlignment": { "stringValue": "top" }, "width": { "stringValue": "12" } }
+        },
+
+        {
+          "name": "safetyInstructions",
+          "fieldText": "<p>All personnel must wear PPE.</p>",
+          "fieldType": "DisplayText"
+        }
+      ]
+    }
+  ],
+
+  "decisions": [
+    {
+      "name": "Transfer_Location_Decision",
+      "label": "Transfer Location Decision",
+      "locationX": 0, "locationY": 0,
+      "defaultConnectorLabel": "Error",
+      "rules": [
+        {
+          "name": "Truck_Decision",
+          "conditionLogic": "and",
+          "conditions": [
+            { "leftValueReference": "To.selectedChoiceValues", "operator": "EqualTo", "rightValue": { "elementReference": "Truck" } }
+          ],
+          "connector": { "targetReference": "Get_Truck" },
+          "label": "Truck"
+        }
+      ]
+    }
+  ],
+
+  "recordLookups": [
+    {
+      "name": "Get_Truck",
+      "label": "Get Truck",
+      "locationX": 0, "locationY": 0,
+      "assignNullValuesIfNoRecordsFound": false,
+      "connector": { "targetReference": "Part_Transfers" },
+      "filterLogic": "and",
+      "filters": [
+        { "field": "Service_Resource__c", "operator": "EqualTo", "value": { "elementReference": "$User.Id" } }
+      ],
+      "object": "Location",
+      "outputAssignments": [
+        { "assignToReference": "Transfer_Destination", "field": "Id" }
+      ]
+    }
+  ],
+
+  "loops": [
+    {
+      "name": "Part_Transfers",
+      "label": "Part Transfers",
+      "locationX": 0, "locationY": 0,
+      "collectionReference": "Part.AddedItems",
+      "iterationOrder": "Asc",
+      "nextValueConnector": { "targetReference": "Transfer_Part" }
+    }
+  ],
+
+  "recordCreates": [
+    {
+      "name": "Transfer_Part",
+      "label": "Transfer Part",
+      "locationX": 0, "locationY": 0,
+      "connector": { "targetReference": "Part_Transfers" },
+      "inputAssignments": [
+        { "field": "Product2Id", "value": { "elementReference": "Part_Transfers.Part_Number.value" } }
+      ],
+      "object": "ProductTransfer",
+      "storeOutputAutomatically": true
+    }
+  ],
+
+  "variables": [
+    { "name": "parentObjectType",   "dataType": "String", "isCollection": false, "isInput": true,  "isOutput": false },
+    { "name": "parentRecordId",     "dataType": "String", "isCollection": false, "isInput": true,  "isOutput": false },
+    { "name": "recordId",           "dataType": "String", "isCollection": false, "isInput": true,  "isOutput": false },
+    { "name": "Transfer_Destination","dataType": "String", "isCollection": false, "isInput": false, "isOutput": false }
+  ]
+}
+```
+
+## Field-rendering strategies
+
+| Strategy | Triggered by | Key JSON differences |
+|----------|--------------|----------------------|
+| `ComponentInstance` | most types: TextInput, Email, Phone, Numeric, Counter, Date, DateTime, Checkbox, Toggle, LongText | `"fieldType": "ComponentInstance"`, label via `inputParameters` |
+| `ComponentChoice` | Picklist, Radio (`dcRbGroup`) | `"fieldType": "ComponentChoice"`, label via `fieldText`, options via `choiceReferences` array |
+| `ComponentMultiChoice` | CheckboxGroup | `"fieldType": "ComponentMultiChoice"`, label via `fieldText`, options via `choiceReferences` array |
+| native `DisplayText` | DisplayText | `"fieldType": "DisplayText"`, body via `fieldText` (HTML), no `extensionName` |
+| native `Repeater` | Repeater | `"fieldType": "Repeater"`, child fields via nested `fields` array, no `extensionName` |
+
+## Requiredness — `isRequired` only, never a `required` inputParameter
+
+Mark a mandatory field with the field-level `"isRequired": true` key **only**. Do **not** add `{ "name": "required", ... }` to `inputParameters` — `dcName`, `dcSignature`, and other Field Service components reject it, and the deploy fails with `We can't find this input attribute: 'required'`. This is the single most common deploy error; the examples above intentionally carry `isRequired` with no `required` inputParameter.
+
+## Connector pattern
+
+- `start.connector` points to screen #1.
+- Each screen — *except* the last — has a `connector` to the next screen.
+- The **last screen** connects to `postScreen` (decision/lookup/loop/create) if present, otherwise omits `connector`.
+- All screens set `"allowFinish": true`.
+
+## Things deliberately not generated
+
+- No formulas, assignments, or text templates.
+- No nested loops or decisions inside loops.
+- No subflows.
+- No `dcLookup` without an `objectApiName` (specs missing `lookupObject` fall back to a labeled TextInput placeholder).
+- No `dcFileView` without a `fileName` (specs missing `fileName` fall back to a labeled TextInput placeholder).
+- No visual polish HTML (banners, progress bars, callouts).

package/skills/field-service-data-capture-form-deployer-configure/references/post-screen-automation.md

@@ -0,0 +1,127 @@
+# Post-screen automation: decision → lookup → loop → createRecord
+
+The Inventory_Transfer flow in the demo org shows the canonical "do something with the captured data" chain. After the last screen, the flow:
+
+1. **Decides** which branch to take based on a Radio answer (Truck vs Work Order).
+2. **Looks up** a record per branch (the truck Location for the user, or the WorkOrder).
+3. **Stores** the resulting Id into a private variable (`Transfer_Destination`).
+4. **Loops** over the Repeater's `AddedItems` collection.
+5. **Creates** one Salesforce record per row, mapping the row's child-field values onto the target object.
+
+This file documents the spec shape that drives that XML.
+
+## Spec extension
+
+Add a top-level `postScreen` block:
+
+```json
+{
+  "formTitle": "Inventory Transfer",
+  "formType": "Inventory",
+  "screens": { ... },
+  "postScreen": {
+    "variables": [
+      { "name": "Transfer_Destination", "type": "String" }
+    ],
+    "decision": {
+      "name": "Transfer_Location_Decision",
+      "label": "Transfer Location Decision",
+      "defaultLabel": "Error",
+      "branches": [
+        {
+          "name": "Truck_Decision",
+          "label": "Truck",
+          "when": { "field": "To", "operator": "EqualTo", "value": "Truck" },
+          "then": "Get_Truck"
+        },
+        {
+          "name": "Work_Order_Decision",
+          "label": "Work Order",
+          "when": { "field": "To", "operator": "EqualTo", "value": "Work Order" },
+          "then": "Get_WO"
+        }
+      ]
+    },
+    "recordLookups": [
+      {
+        "name": "Get_Truck",
+        "label": "Get Truck",
+        "object": "Location",
+        "filters": [
+          { "field": "Service_Resource__c", "operator": "EqualTo", "valueRef": "$User.Id" }
+        ],
+        "outputAssignments": [
+          { "assignTo": "Transfer_Destination", "field": "Id" }
+        ],
+        "next": "Part_Transfers"
+      },
+      {
+        "name": "Get_WO",
+        "label": "Get WO",
+        "object": "WorkOrder",
+        "filters": [
+          { "field": "Id", "operator": "EqualTo", "valueRef": "Work_Order_Number.value" }
+        ],
+        "outputAssignments": [
+          { "assignTo": "Transfer_Destination", "field": "LocationId" }
+        ],
+        "next": "Part_Transfers"
+      }
+    ],
+    "loop": {
+      "name": "Part_Transfers",
+      "label": "Part Transfers",
+      "collection": "Part.AddedItems",
+      "next": "Transfer_Part"
+    },
+    "recordCreates": [
+      {
+        "name": "Transfer_Part",
+        "label": "Transfer Part",
+        "object": "ProductTransfer",
+        "next": "Part_Transfers",
+        "inputAssignments": [
+          { "field": "DestinationLocationId", "valueRef": "Transfer_Destination" },
+          { "field": "IsReceived", "boolean": true },
+          { "field": "OwnerId", "valueRef": "$User.Id" },
+          { "field": "Product2Id", "valueRef": "Part_Transfers.Part_Number.value" },
+          { "field": "QuantityReceived", "valueRef": "Part_Transfers.Quantity.value" },
+          { "field": "QuantitySent", "valueRef": "Part_Transfers.Quantity.value" },
+          { "field": "ReceivedById", "valueRef": "$User.Id" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## How the converter wires it up
+
+When `postScreen` is present:
+
+- The **last screen's connector** points to the decision's `name` (or, if no decision, the first lookup, or the loop, or the first recordCreate — whichever is first in the chain).
+- The decision emits `<decisions>` with one `<rules>` per branch. Each rule's `connector` targets `then`. The `defaultConnectorLabel` becomes the catch-all branch label (no connector means the flow ends on the default path).
+- Each `recordLookups` emits its filter list, output assignments, and a `connector` to its `next`.
+- The `loop` emits `<loops>` with `collectionReference`, `nextValueConnector` to its `next`. The "no more items" path falls through (no connector).
+- Each `recordCreates` emits its input assignments and a `connector` back to the loop (so iteration continues). The loop's "default" (after items finish) is what naturally terminates the flow.
+- All non-input variables in `postScreen.variables` are emitted alongside the three required `parentObjectType` / `parentRecordId` / `recordId` variables.
+
+## Spec → XML reference card
+
+| Spec key | Emits |
+|---|---|
+| `valueRef` | `<elementReference>...</elementReference>` |
+| `value` (string) | `<stringValue>...</stringValue>` |
+| `boolean` | `<booleanValue>true|false</booleanValue>` |
+| `number` | `<numberValue>...</numberValue>` |
+
+Filter / decision-condition operators that have been seen in real flows: `EqualTo`, `NotEqualTo`, `GreaterThan`, `LessThan`, `IsNull`, `Contains`. The converter passes them through as-is — Salesforce will reject anything invalid.
+
+## Limitations
+
+- Only one decision, one loop, and one chain of lookups+creates per spec. Real flows can have many; that's not in scope here.
+- No `assignments` element (the Inventory_Transfer flow uses `recordLookups` outputAssignments instead, which we replicate).
+- No formula resources or text templates.
+- No nested loops, no decisions inside loops.
+
+If you need any of the above, deploy what the skill produces and finish wiring in Flow Builder.