@salesforce/afv-skills 1.55.0 → 1.57.0

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

@@ -0,0 +1,278 @@
+# Component Mapping Reference
+
+Mapping from legacy Field Service Mobile (`FieldServiceMobile` process type) flow
+components to Data Capture Flow (`DataCaptureFlow` process type) equivalents.
+
+> **Source of truth.** The authoritative supported/unsupported decisions live in
+> [`fsm-dc-capability-catalog.md`](./fsm-dc-capability-catalog.md) and its
+> executable twin `scripts/fsm_dc_catalog.py`. This file is a human-readable
+> companion; where the two ever disagree, the catalog wins.
+
+## Keyed on the real FSM vocabulary — not Lightning names
+
+FSM Flow screen fields use the standard Flow `FlowScreenFieldType` enum:
+`InputField`, `DropdownBox`, `RadioButtons`, `MultiSelectCheckboxes`,
+`DisplayText`, `LargeTextArea`, `PasswordField`, `ComponentInstance`, …
+
+A `lightning:*` / `forceContent:*` / `c:*` name is **not** a field type — it only
+ever appears as the `<extensionName>` *inside* a `ComponentInstance` field. So
+classification is always **`fieldType` first, `extensionName` second**. An earlier
+version of this skill keyed its decisions off `lightning:input` /
+`lightning:fileUpload` names; that was wrong and produced the two errors corrected
+in the catalog (signature, file-upload). See W-23364461.
+
+## Class 1 — Direct mappings (clean FSM → DC path)
+
+Keyed by the FSM `<fieldType>`; `InputField` is further resolved by its
+`<dataType>`, and `ComponentInstance` by its `<extensionName>`.
+
+| FSM `<fieldType>` | Discriminator | Data Capture | DC extension |
+|---|---|---|---|
+| `InputField` | dataType `String` | ShortText | `dcTextInput` |
+| `InputField` | dataType `TextArea`/`LongTextArea` | LongText | `dcLongText` |
+| `InputField` | dataType `Email` | Email | `dcEmail` |
+| `InputField` | dataType `Phone` | Phone | `dcPhone` |
+| `InputField` | dataType `Number`/`Double`/`Currency` | Numeric | `dcNumeric` |
+| `InputField` | dataType `Date` | Date | `dcDate` |
+| `InputField` | dataType `DateTime` | DateTime | `dcDateTime` |
+| `InputField` | dataType `Boolean` | Checkbox | `dcCheckbox` — *(see discrepancy in catalog)* |
+| `InputField` | dataType `Picklist` | Picklist | `dcPicklist` |
+| `InputField` | dataType `MultiselectPicklist` | CheckboxGroup | `dcCbGroup` |
+| `LargeTextArea` | — | LongText | `dcLongText` |
+| `DropdownBox` | — | Picklist | `dcPicklist` |
+| `RadioButtons` | — | Radio | `dcRbGroup` |
+| `RadioButtonGroup` | — | Radio | `dcRbGroup` |
+| `MultiSelectCheckboxes` | — | CheckboxGroup | `dcCbGroup` |
+| `MultiSelectPicklist` | — | CheckboxGroup | `dcCbGroup` *(or `dcPicklist` multi-mode)* |
+| `DisplayText` | — | DisplayText | *(pass-through; review formulas)* |
+| `ComponentInstance` | ext `forceContent:fileUpload` | UploadFile | `dcUpFile` |
+| `ComponentInstance` | ext `forceContent:imageUpload` | UploadImage | `dcUpImage` |
+| `ComponentInstance` | ext already `runtime_service_fieldservice:dc*` | *(pass-through, cleaned)* | — |
+
+`DisplayText` is the only field type valid in **both** flow types.
+`forceContent:fileUpload` is the **only** screen extension core allows inside an
+FSM flow (per `FieldServiceMobileFlowValidator`).
+
+## Class 2 — No DC equivalent (flag, never silently drop)
+
+These FSM field types have nothing on the DC side and cannot auto-migrate. The
+analyzer flags each in its Data Capture Gap Report.
+
+| FSM `<fieldType>` | Reason | Recommended approach |
+|---|---|---|
+| `PasswordField` | No DC password component | Capture as `dcTextInput` only if non-secret, else drop |
+| `DisplayRichText` | No DC rich-text display | Downgrade to `DisplayText`; rich formatting lost |
+| `PlainButtons` | **Capability gap** — DC has no action buttons | Remove or redesign; no migration path |
+| `ComponentInstance` w/ any custom ext (`c:*`, or `lightning:*` other than the whitelisted `forceContent:fileUpload`) | DC has no custom-component extension point | Rebuild with a native `dc*` component or flag as unmigratable |
+
+Multi-select choice types (`MultiSelectPicklist`, `MultiSelectCheckboxes`) and
+`RadioButtonGroup` are **not** gaps — they map to DC via `ComponentMultiChoice` /
+`ComponentChoice` (see Class 1). DC has no *single* component covering both single-
+and multi-select, but `dcPicklist` covers both modes and `dcCbGroup` covers multi.
+
+## Class 3 — DC-only components (no FSM source produces them)
+
+These exist only in Data Capture; **nothing in a source FSM flow migrates into
+them**, so the converter never emits them from a migration.
+
+| DC component | Notes |
+|---|---|
+| `dcSignature` | Signature capture — **FSM has no signature component** (see correction below) |
+| `dcEmail` / `dcPhone` / `dcName` | Dedicated inputs (FSM approximates via `InputField`) |
+| `dcAddress` | Address input (optional GPS) |
+| `dcLookup` | Record lookup |
+| `dcMatrix` | Matrix / grid input |
+| `dcCounter` | Numeric stepper |
+| `dcCheckbox` | Single checkbox — distinct from Boolean/Toggle (see discrepancy in catalog) |
+| `dcFileView` | Read-only file/image viewer (requires `fileName`) |
+| `dcUpImage` | Image upload (dedicated component) |
+| `Region` / `RegionContainer` / `Repeater` / `ObjectProvided` | Layout/structural — FSM disallows |
+
+> **`dcImages` does not exist.** Image upload is `dcUpImage`; the read-only
+> file/image viewer is `dcFileView`.
+
+### Correction: Signature is DC-only (WI-3 reversal)
+
+An earlier decision (WI-3 / W-23364096) recorded that file-upload **and
+signature** were supported FSM → DC migration targets. Core disproves the
+signature half: `FieldServiceMobileFlowValidator` whitelists exactly one screen
+extension — `forceContent:fileUpload` — and there is **no** native FSM signature
+component anywhere in the FSM path. `dcSignature` is DataCaptureFlow-only. There
+is no FSM signature source to migrate *from*, so the skill emits no `dcSignature`
+and the downstream signature-emission task (WI-7 / W-23364093) is reverted. The
+file-upload half of WI-3 stands, but keyed on `forceContent:fileUpload → dcUpFile`,
+never `lightning:fileUpload`.
+
+## Automation element mapping
+
+| Legacy element | Data Capture | Notes |
+|---|---|---|
+| Record Lookup | `<recordLookups>` | Direct map; verify offline behavior |
+| Record Create | `<recordCreates>` | Must follow the last screen (CUD-at-end) |
+| Record Update | `<recordUpdates>` | Must follow the last screen (CUD-at-end) |
+| Record Delete | `<recordDeletes>` | Must follow the last screen (CUD-at-end) |
+| Decision | `<decisions>` | Direct map; review cross-screen routing |
+| Loop | `<loops>` | Direct map |
+| Assignment | `<assignments>` | Direct map |
+| Action Call (Apex) | **BLOCKER** | DC forbids `<actionCalls>`/Apex; only `AGX_FLOW` actions. Convert to record lookups |
+| Subflow Call | **BLOCKER** | DC can only call other DC flows and subflows cannot contain CUD; inline or convert |
+| Formula | `<assignments>` or Decision | Limited DisplayText formula support at DC runtime; pre-calculate |
+| Fault path | **Not supported** | Fault connectors stripped; `$Flow.FaultMessage` blocked |
+
+These are the capability-level gaps returned by
+`fsm_dc_catalog.capability_gaps()` and surfaced per-flow by `analyze_flow.py`.
+
+## Visibility rules
+
+| Legacy pattern | Data Capture | Migration notes |
+|---|---|---|
+| Simple field visibility | `<visibilityRule>` | Direct map; same XML structure |
+| Complex formula visibility | `<visibilityRule>` | Review formula; DC runtime support is limited |
+| Cross-screen visibility | Not directly supported | Redesign with decision-based routing |
+
+## Choice set patterns
+
+### Legacy: picklist with static choices
+
+```xml
+<choices>
+    <name>choice_Yes</name>
+    <choiceText>Yes</choiceText>
+    <dataType>String</dataType>
+    <value><stringValue>Yes</stringValue></value>
+</choices>
+```
+
+### Data Capture equivalent
+
+In spec JSON:
+```json
+{
+  "fieldType": "Picklist",
+  "choices": ["Yes", "No", "Maybe"]
+}
+```
+
+Converter auto-generates `<choices>` blocks with deduplication.
+
+### Legacy: dynamic choice set (record-backed)
+
+```xml
+<dynamicChoiceSets>
+    <name>AssetChoices</name>
+    <object>Asset</object>
+    <displayField>Name</displayField>
+    <valueField>Id</valueField>
+</dynamicChoiceSets>
+```
+
+Data Capture supports `dynamicChoiceSets` with the same structure. Converter
+preserves these but flags for offline-priming verification.
+
+## Input parameter mapping
+
+| Legacy parameter | DC parameter | Notes |
+|---|---|---|
+| `label` | `label` | Direct map for ComponentInstance fields |
+| `required` | Field-level `<isRequired>` | Moved from parameter to field attribute |
+| `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 |
+| `min` / `max` (Counter) | `min` / `max` | Direct map for `dcCounter` |
+| `minDate` / `maxDate` | `minDate` / `maxDate` | Direct map for `dcDate` / `dcDateTime` |
+
+## Common migration pitfalls
+
+### 1. Apex dependency
+
+**Legacy:** Flow calls Apex to compute pricing, validate inventory, etc.
+**Migration:** DC flows are offline-first and cannot call Apex at runtime.
+**Fix:** Convert Apex logic to record lookups, or gate the flow behind an online detector and degrade gracefully.
+
+### 2. AutoLaunched subflows
+
+**Legacy:** Flow calls an AutoLaunched subflow for reusable logic.
+**Migration:** DC can only call other DC flows (`processType=DataCaptureFlow`), and subflows cannot contain CUD.
+**Fix:** Inline the subflow logic or convert the subflow to DC format.
+
+### 3. Cross-screen formula references
+
+**Legacy:** Screen 3's DisplayText references fields from Screen 1 via formula.
+**Migration:** DC has limited formula support in DisplayText.
+**Fix:** Use `<assignments>` between screens to pre-calculate values into variables.
+
+### 4. Custom components (`ComponentInstance`)
+
+**Legacy:** Custom LWC (`c:*`) or non-whitelisted `lightning:*` component embedded in a `ComponentInstance` field.
+**Migration:** No custom component extension points in DC.
+**Fix:** Rebuild with native DC components or flag as incompatible.
+
+### 5. Action buttons (`PlainButtons`)
+
+**Legacy:** `PlainButtons` field drives in-screen navigation or actions.
+**Migration:** DC has no user-facing action buttons (only `AGX_FLOW`).
+**Fix:** Redesign the interaction; there is no direct migration path.
+
+## Validation checklist
+
+After migration, verify:
+
+- [ ] All screens render
+- [ ] All field types display correctly
+- [ ] Required validation fires
+- [ ] Conditional visibility works
+- [ ] Choices populate (picklists, radios, checkboxes)
+- [ ] Lookups search the correct object
+- [ ] File-upload components accept input
+- [ ] Record creates/updates succeed
+- [ ] Loops iterate correctly
+- [ ] Decisions route to correct next steps
+- [ ] Offline behavior: drafts queue when airplane mode on
+- [ ] Form appears in FSL Mobile "Forms" tab
+
+## Conversion confidence levels
+
+### GREEN (high confidence, automated)
+
+- Simple data-entry forms
+- Standard `InputField` types (text, number, date, boolean)
+- Static picklists (`DropdownBox`) and radio groups (`RadioButtons`)
+- File upload via `forceContent:fileUpload`
+- Single record create at end
+- No Apex, no custom components
+
+### YELLOW (medium confidence, requires review)
+
+- Visibility rules with formulas
+- Decision-based routing
+- Dynamic choice sets (requires offline-priming verification)
+- Record updates with conditional logic
+- `MultiSelectPicklist` / `RadioButtonGroup` rebuilt as `dcCbGroup` / `dcRbGroup`
+
+### RED (low confidence, manual redesign)
+
+- Custom `ComponentInstance` components (`c:*`, non-whitelisted `lightning:*`)
+- `PlainButtons` action buttons
+- Apex callouts
+- AutoLaunched subflows
+- Complex nested decisions
+- Cross-screen formula dependencies in DisplayText
+- `DisplayRichText`
+
+## Testing strategy
+
+1. **Desktop first:** Open migrated flow via `<instanceUrl>/flow/<FlowApiName>_v2`, complete the form end-to-end
+2. **Offline priming:** Verify Briefcase includes all objects/fields the flow touches
+3. **Mobile render:** Attach to a test record, open on FSL Mobile device
+4. **Offline mode:** Airplane mode + complete form + verify draft queues
+5. **Data integrity:** Compare output records from legacy vs. migrated flow
+6. **Edge cases:** Test all branches, visibility conditions, validation rules
+
+## Rollback procedure
+
+If migrated flow has issues:
+
+1. Keep legacy flow active (don't deactivate)
+2. Remove `DynamicDataCapture` attachment for migrated flow
+3. Iterate on spec, rebuild, redeploy as `_v3`, `_v4`, etc.
+4. Once validated, deactivate legacy flow and clean up test versions

package/skills/field-service-data-capture-migrate/references/converter-builder-contract.md

@@ -0,0 +1,183 @@
+# Converter → Builder integration contract
+
+This is the authoritative contract between the two scripts that form the
+migration pipeline:
+
+```text
+legacy Digital Forms XML
+   └─▶ scripts/convert_to_dc_spec.py   (producer)
+          └─▶ spec JSON
+                 └─▶ scripts/vendor/build_flow.py   (consumer)
+                        └─▶ .flow-meta.xml (DataCaptureFlow)
+```
+
+Before `collapse_gating_decisions`, the converter runs `normalize_inverted_gates`,
+which rewrites inverted-shape gates (default branch shows the gated field) into
+equivalent positive gates by negating the rule condition and swapping connectors.
+Collapse then handles them unchanged (field or section). Inverted gates whose
+condition uses a non-invertible operator or custom logic are left flagged (see the
+capability catalog).
+
+`build_flow.py` (`parse_spec`) is the source of truth for the JSON shape.
+`convert_to_dc_spec.py` MUST emit exactly this shape.
+
+> **History:** an earlier converter emitted `screens` as a *list* of
+> `{title, fields:[{name, label, fieldType, required, choices}]}`, while the
+> builder consumes `screens` as a *dict* of `{ScreenName: [{fieldName,
+> fieldLabel, isRequired, options, visibility}]}`. Piping one into the other
+> raised `ValueError: spec must have a non-empty 'screens' object` and produced
+> no output. This doc + the smoke test exist to prevent that regression.
+
+## Top-level spec object
+
+| Key | Type | Required | Notes |
+|-----|------|----------|-------|
+| `formTitle` | string | yes | Flow label / interview label. |
+| `formType` | string | no | Free text; converter sets `"DataCaptureFlow"`. |
+| `screens` | **object (dict)** | yes | Keyed by screen name → list of field objects. Must be non-empty. |
+| `decisions` | list | no | Pre-CUD screen-routing decisions. Each: `{name, label, defaultConnector, defaultLabel, rules:[{name, label, conditionLogic, conditions:[{leftValueReference, operator, rightValue}], connectsTo}]}`. Emitted by the converter (WI-6a) **only when the decision passes the deployability gate** — every target resolves to an element 6a actually builds (another surviving decision) AND the decision is reachable from a screen connector. Decisions that fail either bar are routed to `_decisionFlags`, never emitted, so no `<decisions>` element ever carries a dangling `<targetReference>`. |
+| `_screenConnectors` | object | no | `{screen_key: target_api_name}` — a source screen's outgoing connector, **filtered to targets that are emitted decisions**. Connectors whose target is not an emitted decision are dropped so the screen falls through sequentially rather than dangling. Full connector-graph wiring to renamed `Screen_` api-names and to assignments/lookups is deferred to WI-6b/6c. |
+| `_decisionFlags` | list | no | `{name, reason}` for **decisions** the routing gate did not emit. Two reason families: (1) **Decision→CUD** — routes directly to a CUD element (forbidden by the CUD-at-end rule); (2) **target not yet wired** — routes to screens/assignments/lookups 6a does not build, or is unreachable — deferred to WI-6b/6c. Decision-routing only; structural ceilings live in `_ceilingFlags`. Migration annotation only. |
+| `_ceilingFlags` | list | no | `{name, reason}` for **structural** DC deploy-time ceilings the converter cannot translate (WI-7), in document order: (1) any element reachable only after a CUD node (CUD-at-end rule); (2) any element carrying a `<faultConnector>`; (3) any `<loops>`. Kept SEPARATE from `_decisionFlags` because the same element name can legitimately appear in both surfaces (a decision that is both unwired and post-CUD), so a single name-keyed list would collide. Migration annotation only. |
+| `_cudAnalysis` | object | no | WI-8 ordinal CUD-placement analysis. `{consolidated:[{node,op,from,to}], manualRestructure:[{node,op,position,reason,blockers}], hasMidFlowCud:bool}`. Present only when the flow has ≥1 CUD element. `consolidated` lists safe record-creates the converter moved to `postScreen`; `manualRestructure` lists CUD needing hand-restructuring (unsafe, or safe update/delete with no `postScreen` emission path). Migration annotation only. |
+| `_collapsedDecisions` | list | no | `{decision, field?, section?, fields?, clearedRequired?}` for gates the converter collapsed into visibility. Field-level collapses (WI-6b) populate `field`; section-level collapses (WI-6c) populate `section` and `fields` (the list of field api-names the section contained) and `clearedRequired` (field names whose required flag was unset because they became conditionally visible). Migration annotation only. |
+| `_incompleteMigration` | list | no | Unsupported elements from the source flow that have no Data Capture equivalent. Each: `{type, name, reason}` where `type ∈ {apex, subflow, faultPath, customComponent, unknownField}`. Present **only when** the source flow has ≥1 unsupported element; the key is omitted entirely (not emitted as an empty list) for clean flows. Ordering: flow-level (`apex`, `subflow`, `faultPath`) in document order, then field-level (`customComponent`, `unknownField`) in screen/field document order — deterministic. See "Incomplete Migration Marker" section below. |
+| `postScreen` | object | no | End-of-flow automation (decisions/lookups/loop/creates). As of WI-8, `_automationNote` fires only when mid-flow CUD is detected and its body is ordering-based (points at `_cudAnalysis`); the former count-based note is removed. Safe record-creates are emitted into `postScreen.recordCreates`. |
+| `_migrationSummary` | list of strings | no | Human-readable rollup, one line per migration action: section/field collapses, cleared-required fields (WI-6c), and WI-7 ceiling flags (post-CUD / fault / loop). The human-facing mirror of the machine keys `_collapsedDecisions` and `_ceilingFlags`. Only present when at least one action occurred. Migration annotation only. |
+
+Any key beginning with `_` (e.g. `_automationNote`, `_migrationNote`, `_incompleteMigration`, `_screenConnectors`, `_decisionFlags`) is a
+migration annotation. As of WI-8, `_automationNote` fires only when mid-flow CUD is detected and its body is ordering-based (points at `_cudAnalysis`); the former count-based note is removed. Safe record-creates are emitted into `postScreen.recordCreates`. The builder ignores unknown keys, so annotations pass
+through harmlessly.
+
+## `screens` — dict, not list
+
+- **Key**: the screen name/label as a string (e.g. `"Asset Details"`). It does
+  not need to be pre-sanitized — the builder derives the display label via
+  `humanize_screen_key` and produces the screen api-name by running the key
+  through `coerce_api_name` with a `Screen_` prefix (so `"Asset Details"` →
+  api-name `Screen_Asset_Details`, label "Asset Details"). Keys must be unique
+  within the `screens` dict.
+- **Value**: a **non-empty** list of field objects or **section-sentinel dicts**. The builder raises if any
+  screen maps to an empty list, so the converter drops screens that yield no
+  convertible fields rather than emit an empty one. Section-sentinels (WI-6c) are expressed as `{"section": label, "visibility"?: {...}, "fields": [...]}` for self-contained / nestable sections, or `{"section": label}` (no `fields` key) for legacy inline openers.
+
+## Field object
+
+| Key | Type | Required | Emitted by converter | Notes |
+|-----|------|----------|----------------------|-------|
+| `fieldName` | string | yes | yes | Source field api-name. Builder re-sanitizes and uniquifies it. |
+| `fieldLabel` | string | yes | yes | Display label. |
+| `fieldType` | string | yes | yes | One of the builder's `TYPE_MAP` keys (see below). Unknown types fall back to `ShortText` with a `[Unknown type: X]` label prefix. |
+| `isRequired` | bool | yes | yes | Coerced with `bool()` by the builder. |
+| `options` | list[string] | for choice types | when choices present | Choice display values for `Picklist` / `Radio` / `CheckboxGroup` / `Matrix`. |
+| `visibility` | object | no | yes (6b/6c) | `{ field, operator, value }`; `field` must reference a choice field, `value` one of its options. Field-level visibility collapse delivered in WI-6b. A `visibility` key on a **section sentinel** (WI-6c) gates the entire section (builder emits a `<visibilityRule>` on the `RegionContainer` field). Note: legacy FSM has no component-level visibility — all conditionality arrives via the top-level `decisions` list (decision routing delivered in WI-6a). |
+| `defaultValue` | string/number/bool | no | not yet | Pre-fill / DisplayText body. |
+| `_migrationNote` | string | no | yes (when needed) | Migration annotation; ignored by builder. |
+
+Repeater/Matrix/Counter/Lookup/FileView carry extra keys (`repeaterFields`,
+`matrixRows`, `min`/`max`/`value`, `lookupObject`, `fileName`) — see
+`build-data-capture-form/reference/field-types.md`. The converter does not emit
+these yet.
+
+### Sections & nesting
+
+Sections (WI-6c) are expressed as **section-sentinel dicts** within a screen's field list. Two forms exist:
+
+- **Self-contained / nestable**: `{"section": label, "visibility"?: {...}, "fields": [...]}` — the `fields` array contains the section's child fields (and may itself contain nested section sentinels, up to `MAX_SECTION_DEPTH = 5`). The builder emits a `RegionContainer` field wrapping the children. If `visibility` is present, the builder emits a `<visibilityRule>` on the `RegionContainer`.
+- **Legacy inline opener**: `{"section": label}` (no `fields` key) — the legacy converter emitted this form; it opens a section that extends to the next section sentinel or end-of-screen. Not nested. The current converter (WI-6c) emits only the self-contained form.
+
+**Cascade rule**: each section carries only its own `visibility` conditions. The Data Capture runtime auto-hides children when a parent section is hidden, so the converter does not need to propagate parent conditions downward into child field visibility rules.
+
+## Decision conditions
+
+Each decision in the top-level `decisions` list contains `rules`, and each rule contains `conditions`. Condition structure:
+
+| Key | Type | Notes |
+|-----|------|-------|
+| `leftValueReference` | string | Field api-name or merge-field reference. |
+| `operator` | string | Flow operator (e.g. `EqualTo`, `NotEqualTo`, `IsNull`, `GreaterThan`). Defaults to `EqualTo` if omitted. |
+| `rightValue` | object | Typed single-key dict: one of `{booleanValue: bool}`, `{numberValue: float}`, `{stringValue: string}`, or `{elementReference: string}`. May be omitted for null-check operators. |
+
+The `conditionLogic` field (string) is copied verbatim from the source Flow decision, including custom logic strings like `3 and (1 OR 2) and 4`. Defaults to `"and"` if omitted.
+
+## Field-type vocabulary
+
+`fieldType` values MUST be keys in `build_flow.py`'s `TYPE_MAP`. As of this
+writing:
+
+```text
+ShortText, LongText, Name, Email, Phone, Numeric, Counter, Date, DateTime,
+Checkbox, Toggle, Picklist, Radio, CheckboxGroup, DisplayText, Repeater,
+Signature, UploadFile, UploadImage, Address, Matrix, Images, Lookup, FileView
+```
+
+The converter maps legacy `extensionName`s to a subset of these (see
+`reference/component-mapping.md`). Any legacy component with no mapping is
+emitted as `ShortText` with a `_migrationNote`.
+
+## Renamed keys (legacy converter → current contract)
+
+If you are updating older code or docs, these are the renames that closed the
+contract gap:
+
+| Old converter key | Current contract key |
+|-------------------|----------------------|
+| `screens` (list) | `screens` (dict, keyed by screen name) |
+| screen `title` | (dropped — label derived from the dict key) |
+| screen `fields` | (dropped — the dict value *is* the field list) |
+| `name` | `fieldName` |
+| `label` | `fieldLabel` |
+| `required` | `isRequired` |
+| `choices` | `options` |
+
+## Incomplete Migration Marker
+
+When the converter encounters source flow elements that have no Data Capture equivalent, it emits `_incompleteMigration`: a top-level list of `{type, name, reason}` dictionaries. This key is present **only when** the source flow has ≥1 unsupported element; it is omitted entirely (not emitted as an empty list) for clean flows.
+
+### Type vocabulary
+
+`type` is a closed set with exactly five values:
+
+| Type | Meaning | Example |
+|------|---------|---------|
+| `apex` | Apex action call or invocable action | EmailAlert, Apex class invocation |
+| `subflow` | Subflow invocation | DataCaptureFlow can call other DC subflows, but this flags manual review |
+| `faultPath` | Fault connector (error path) | DC has no fault paths; error handling is stripped |
+| `customComponent` | Custom Lightning component in a field slot | Non-runtime_service_fieldservice component |
+| `unknownField` | Field with no recognized type mapping | Unrecognized extensionName or fieldType |
+
+### Ordering
+
+The list is deterministic:
+1. **Flow-level** (`apex`, `subflow`, `faultPath`) in source-document order (from `detect_unsupported_elements`)
+2. **Field-level** (`customComponent`, `unknownField`) in screen/field document order (collected during the screen loop)
+
+### Builder behavior
+
+`build_flow.py` reads `_incompleteMigration` via `parse_spec` into `FormSpec.incomplete_migration` (a list). When present and non-empty, `build_xml` renders ONE `<!-- INCOMPLETE MIGRATION ... -->` comment block between the `<?xml version="1.0"?>` declaration and the `<Flow>` opening tag. Each entry is formatted as:
+
+```text
+  - [type] name: reason
+```
+
+If the key is absent, no comment is emitted. (In practice the converter omits the key rather than emitting an empty list, but the builder tolerates an empty list too.)
+
+### Coexistence with other annotations
+
+`_incompleteMigration` coexists with `_subflowNote`, `_automationNote`, and per-field `_migrationNote`. These annotations were **not consolidated** — each serves a distinct purpose:
+- `_incompleteMigration`: top-level spec key listing all unsupported elements → XML comment block
+- `_subflowNote` / `_automationNote`: converter stdout warnings about CUD/subflow review needs
+- `_migrationNote`: per-field note embedded in the spec field dict (not promoted to `_incompleteMigration` unless the field is also unsupported)
+
+A subflow is intentionally surfaced by **both** mechanisms: it is flagged in `_incompleteMigration` (type `subflow`) **and** may still trigger a `_subflowNote` stdout warning. The two are independent and were deliberately left un-deduplicated (consolidation is out of scope for WI-7).
+
+### Unsupported field placeholder behavior
+
+Unsupported field slots (those with `meta['unsupported'] = True`) are emitted as **read-only `DisplayText` placeholders** with the `fieldLabel` set to `[UNSUPPORTED: <fieldName> — <reason>]` (em-dash U+2014 separator). They are NOT emitted as silent `ShortText` inputs (the WI-7 silent-downgrade behavior was removed). The placeholder ensures the unsupported field is visible in the built XML and flagged for manual attention.
+
+## Verifying the contract
+
+Run `scripts/convert_to_dc_spec.py` against `assets/sample-legacy-flow.flow-meta.xml`, then
+`scripts/vendor/build_flow.py` against the resulting spec, and confirm the output XML has a
+non-empty `screens` section. If it fails, the converter output and builder input have drifted —
+reconcile against `build_flow.parse_spec`, which remains the source of truth.

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

@@ -0,0 +1,130 @@
+# DC platform rules reference
+
+These rules govern any valid DataCaptureFlow. The transformer enforces them automatically. This section is the authoritative reference for debugging deploy errors or validating migrated flows manually.
+
+## Required flow headers
+
+```xml
+<processType>DataCaptureFlow</processType>
+<areMetricsLoggedToDataCloud>false</areMetricsLoggedToDataCloud>
+<environments>Offline</environments>
+<!-- NO <apiVersion> tag — causes: "You can't specify the field API Version" -->
+```
+
+## Required input variables (platform launch contract)
+
+SFS Mobile passes these on launch — every DataCaptureFlow must declare them:
+```xml
+<variables><name>recordId</name><dataType>String</dataType><isInput>true</isInput>...</variables>
+<variables><name>parentRecordId</name><dataType>String</dataType><isInput>true</isInput>...</variables>
+<variables><name>parentObjectType</name><dataType>String</dataType><isInput>true</isInput>...</variables>
+```
+
+## Flow structure rules
+
+| Rule | Detail |
+|---|---|
+| First element after `<start>` | **Must be a `<screens>` element** — connecting `<start>` directly to recordLookups or decisions causes mobile offline rendering failure |
+| DML placement | Create, Update, Delete MUST be at the END of the flow |
+| Screens after DML | NOT allowed |
+| Decision between sequential CUD nodes | A Decision CAN route to which CUD chain starts; once a CUD chain begins, no Decision may appear between sequential CUD nodes |
+| Subflows (CUD) | Subflows CANNOT contain Create, Update, or Delete operations |
+| Subflows (type) | Can only call another DataCaptureFlow — calling an AutoLaunched subflow is blocked |
+| `<actionCalls>` | Not allowed in DataCaptureFlow |
+| Fault connectors | Not supported — must be stripped |
+| XML element grouping | All elements of the same type must appear in a contiguous block — mixing them causes "Element X is duplicated" deploy error |
+
+## Visibility rule accessor suffixes
+
+```xml
+<leftValueReference>componentName.SUFFIX</leftValueReference>
+```
+
+| Component type | Suffix |
+|---|---|
+| Input components (`dcTextInput`, `dcNumeric`, `dcCheckbox`, `dcDate`, etc.) | `.value` |
+| Choice components (`dcPicklist`, `dcRbGroup`, `dcCbGroup`) | `.selectedChoiceValues` |
+| Toggle (`dcToggle`) | `.isActive` |
+| Name component (`dcName`) | `.firstName` / `.lastName` |
+| Lookup single select (`dcLookup`) | `.recordId` |
+| Lookup multi-select (`dcLookup` with `isMultiSelection=true`) | `.recordIds` |
+
+## Decision IsNull canonical pattern
+
+`IsNull` uses a `booleanValue` on the right — NOT a null literal:
+```xml
+<conditions>
+    <leftValueReference>v_ParentId</leftValueReference>
+    <operator>IsNull</operator>
+    <rightValue><booleanValue>false</booleanValue></rightValue>
+    <!-- false = "is not null"; true = "is null" -->
+</conditions>
+```
+
+## Calculation timing (critical)
+
+Calculated values **cannot display on the same screen that collects the inputs** — calculations run only after the user taps Next.
+
+Required pattern:
+```text
+Screen N (collect inputs) → Assignment / recordLookups / decisions → Screen N+1 (display results)
+```
+
+Screen N's connector must point to the calculation element, NOT directly to Screen N+1.
+
+## DisplayText formula limitations
+
+`DisplayText` has severely limited formula support at mobile runtime. Complex formulas deploy and preview in Flow Builder but **fail at runtime** with `Error while resolving default value reference`.
+
+| Pattern | Works in DC DisplayText? |
+|---|---|
+| Simple variable reference: `{!var_RiskScore}` | Yes |
+| Component ref: `{!MyPicklist.selectedChoiceValues}` | Yes |
+| Global vars: `{!$Flow.CurrentDate}`, `{!$User.FirstName}` | Yes |
+| `IF(Toggle.isActive, "YES", "NO")` | No — fails at mobile runtime |
+| `TEXT(CASE(...))`, `ADDMONTHS(...)`, nested date math | No — fails at mobile runtime |
+| Mixing multiple component refs + formulas in one `fieldText` | No — fails at mobile runtime |
+
+**Pattern**: pre-calculate in an `<assignments>` element → store in a variable → reference that variable in DisplayText.
+
+## `isRequired=true` behind a `visibilityRule`
+
+**Never** mark a field `isRequired=true` if it is behind a `visibilityRule`. The required check fires even while the field is hidden — the mobile worker cannot proceed.
+
+Set `isRequired=false` and add a `validationRule` instead:
+```text
+IF(TriggerField.isActive, AND(NOT(ISBLANK(value)), value >= 0), TRUE)
+```
+
+## Lookup component specifics
+
+| Property | Behaviour |
+|---|---|
+| Display label in results | Driven by the object's **Primary Compact Layout** — first field in that layout. To change: Setup → Compact Layouts → reorder → assign as Primary. No `displayField` inputParameter exists. |
+| Multi-select | Set `isMultiSelection=true`; output is `{!Lookup.recordIds}` (collection) |
+| Scoping filter | Use `recordIdCollection` (not `recordIds`) — only effective when `isMultiSelection=true`; silently ignored in single-select |
+| Attribute names | `isDisabled` and `isReadonly` (lowercase `o`) — `disabled`/`readOnly` cause deploy errors |
+
+## Repeater specifics
+
+- Output collection: **`.AllItems` only** (confirmed API v66) — `AddedItems`, `PrepopulatedItems`, `RemovedItems` all cause deploy errors
+- Loop body references: use `Loop_Name.fieldName.value` (the loop variable's name), NOT `Repeater_Name.fieldName.value`
+- Prepopulate: bind an existing SObject collection via the `collection` inputParameter
+- Inside nested fields: reference source rows via `SourceCollection[$EachItem].FieldApiName` — `$EachItem` only resolves inside Repeater-nested fields; downstream loops still iterate `Repeater_Name.AllItems` normally
+- The Repeater itself must NOT have `storeOutputAutomatically` — causes deploy error; only nested fields inside the Repeater get it
+
+## Global variable allowlist
+
+Only these global variables are supported in DataCaptureFlow (all others blocked):
+
+- `$Api`, `$Label`, `$Organization`, `$Profile`, `$System`, `$User`, `$UserRole`
+- `$Flow.CurrentDate`, `$Flow.CurrentDateTime`, `$Flow.InterviewStartTime`, `$Flow.InterviewGuid`
+
+Input default binding behavior:
+
+| Default binding | Component | Works? |
+|---|---|---|
+| `$User.Username` | `dcTextInput` | Yes |
+| `$User.Name` | `dcTextInput` | No — type mismatch, use `$User.Username` |
+| `$Flow.InterviewStartTime` | `dcDateTime` | Yes |
+| `$Flow.CurrentDate` | `dcDate` | Yes |