@salesforce/afv-skills 1.49.0 → 1.51.0

package/skills/field-service-data-capture-form-designer-configure/references/extraction-from-image.md

@@ -0,0 +1,244 @@
+# Extraction rules — visual sources (PDF / image)
+
+These are the rules to follow when given a `.pdf`, `.png`, `.jpg`, or `.jpeg` and asked to produce the intermediate JSON spec for a Data Capture Flow.
+
+The spec schema is the input contract of the build skill — see [field-types.md](../../fs-data-capture-form-deployer/reference/field-types.md) and [post-screen-automation.md](../../fs-data-capture-form-deployer/reference/post-screen-automation.md). This file covers extraction *behavior*; that file covers what the converter accepts.
+
+## Output schema
+
+```json
+{
+  "formTitle": "string",
+  "formType": "string",
+  "screens": {
+    "PascalCaseScreenName1": [ /* fields */ ],
+    "PascalCaseScreenName2": [ /* fields */ ]
+  },
+  "postScreen": { /* optional — see post-screen-automation.md */ }
+}
+```
+
+Each field has these properties (only `fieldName`, `fieldLabel`, and `fieldType` are required):
+
+| Property | Type | Notes |
+|----------|------|-------|
+| `fieldName` | string | camelCase or PascalCase, English, unique across the form, valid Salesforce API name. |
+| `fieldLabel` | string | Exact label from the source. Preserve original language, units, special characters. Strip required indicators (`*`, `(required)`). |
+| `fieldType` | string | One of the supported types in `field-types.md`. Case-sensitive. |
+| `isRequired` | boolean | true if the source had `*`, "required", "mandatory", "Pflichtfeld", "obligatoire", etc. |
+| `defaultValue` | string \| null | null for input fields; for `DisplayText`, the static body text. |
+| `options` | array \| null | Required for `Radio`, `Picklist`, `CheckboxGroup`, `Matrix` (column choices). null otherwise. |
+| `repeaterFields` | array | Required for `Repeater`. List of nested field objects with the same shape. |
+| `matrixRows` | array | Required for `Matrix`. List of row labels. |
+| `min` / `max` / `value` | number | Optional for `Counter` — initial/min/max for the +/- counter. |
+| `visibility` | object | Optional. `{ "field": "<fieldName>", "operator": "EqualTo", "value": "<choice display>" }` — show this field only when the referenced choice is selected. |
+| `lookupObject` | string | Required for `Lookup`. Salesforce object API name (e.g. `"Asset"`, `"WorkOrder"`). |
+| `lookupSearchFields` | string | Optional for `Lookup`. Comma-separated field API names searched by typeahead (e.g. `"Name, SerialNumber"`). |
+| `lookupMulti` | boolean | Optional for `Lookup`. true to allow selecting multiple records. |
+| `fileName` | string | Required for `FileView`. Static-asset filename without extension. |
+
+## Output requirements
+
+1. Output **only** the JSON object.
+2. No markdown, no code fences, no explanation before or after.
+3. Use `null` for null, `true`/`false` for booleans, double-quoted strings.
+4. Stop immediately after the closing `}`.
+
+## Field-type classification — control evidence over labels
+
+Pick a field type from what the *control* does, not from what the *label* says. A field labeled "Signature" that's just a text line is `ShortText`, not `Signature`. A field labeled "Photo of damage" that's a description box is `LongText`, not `UploadImage`. The label is a hint; the rendered UI control is the answer.
+
+Use the **most specific** type the visual evidence supports. Default to `ShortText` when in doubt.
+
+| Type | Control evidence required (PDF/image) |
+|---|---|
+| `Name` | A text input whose label is an unambiguous person role: Inspector, Operator, Technician, Employee, Customer Name, Reported By. Plain "Name" alone is fine. **A dropdown control with a person-role label (e.g. "--Select Inspector--", "Choose Operator ▼") is still `Name`, not `Picklist`** — the data captured is a person, and the runtime treatment of person fields is what matters. |
+| `Email` | Text input with `@` placeholder, label "Email", or input attribute hints. |
+| `Phone` | Text input with phone formatting, label "Phone", "Tel", "Mobile". |
+| `Numeric` | Numeric input, often with units (°C, mm, kg, bar, %). |
+| `Counter` | A `+` / `-` stepper widget *or* explicit "Quantity" with stepper UI. Default `min: 1, value: 1`. |
+| `Date` | A date picker (calendar icon, `MM/DD/YYYY` placeholder). |
+| `DateTime` | A date+time picker. |
+| `Checkbox` | A single standalone checkbox with one label. |
+| `CheckboxGroup` | Multiple checkboxes under one heading or "select all that apply". |
+| `Radio` | Radio buttons / "(circle one)" / mutually exclusive options visible on the form. |
+| `Picklist` | A combo box / dropdown indicator (▼ ▾ ⌄, "Select…"). For person-name dropdowns, prefer `Name`. Supply 3–5 sample options. |
+| `Toggle` | An on/off switch UI element (rounded slider). |
+| `UploadFile` | A file-picker control: "Choose file", paperclip icon, drag-drop zone, attachment slot. **Not** a label that mentions a file. |
+| `UploadImage` | An image-upload control: camera icon, "Add photo" button, image drop zone. **Not** a label like "Photo" on a text line. |
+| `FileView` | A read-only image preview / pre-attached image. |
+| `Signature` | A signature pad (a labeled empty box sized for handwriting, with "Sign here" / "Signature" inside the box, often with an X-line). **Not** a one-line text field labeled "Signature". |
+| `Matrix` | A grid where each row asks the same question with shared answer columns (e.g. row=item, columns=OK/NOK/N/A). ONE field with `matrixRows` + `options`. |
+| `Repeater` | A table with input columns where the user adds N rows (e.g. Part Number / Quantity / Description). ONE field with `repeaterFields`. |
+| `Address` | A compound address widget with separate sub-inputs (street + city + state + zip + country). |
+| `LongText` | A multi-line text box (textarea, ≥3 lines tall, "Notes" / "Comments" / "Remarks"). |
+| `ShortText` | A single-line text input. **This is the default** when no other evidence applies. |
+| `DisplayText` | Static instructional text with no input control. Set `defaultValue` to the body. |
+| `Lookup` | A typeahead/record-search input bound to a Salesforce object (search-as-you-type that resolves to a record). Requires `lookupObject` (the Salesforce object API name) supplied via the spec. |
+
+**Multi-part fields** (e.g. "D0: ___ Ref.-Dim.: ___") → extract each part as its own field with its own classification.
+
+### Repeater extraction rules
+
+A `Repeater` is for tables where each row is a **user-added item** with **input columns** (the user types/picks per cell). Distinct from `Matrix`, which is a fixed set of rows that share **selection columns** (OK / NOK / N/A — pick one).
+
+| Pattern | Type |
+|---|---|
+| Table: `Parameter \| Old Value \| New Value` (user types in each cell) | `Repeater` |
+| Table: `Component \| OK \| NOK \| N/A \| Repair` (user picks one per row) | `Matrix` |
+
+When emitting a `Repeater`, populate `repeaterFields` with one nested field per **input column**, classified using the same evidence rules above. Skip any selection-only "OK/NOK" columns — those mean it's a `Matrix`.
+
+**Merge side-by-side / stacked repeaters with the same columns.** If the source visually splits one logical table into two blocks (top half / bottom half, left / right) because of page-space constraints, but both blocks have the same column structure — emit **one** Repeater. Two Repeater fields with identical `repeaterFields` is almost always a mistake.
+
+**Dedupe columns with the same label.** If a table has the same column label appearing twice and the data captured is the same kind of thing, include the column **once** in `repeaterFields`.
+
+**Skip symbol-only columns.** Single-character or symbol headers (`Δ`, `Σ`, `→`, blank) are typically separators or change indicators, not data inputs.
+
+### Anti-patterns (do NOT do these)
+
+- ❌ Label contains "signature" → automatically `Signature`. The control might be a single-line text field where the inspector types their name. Only emit `Signature` if you can see a sign-here pad.
+- ❌ Label contains "photo" / "image" / "picture" → automatically `UploadImage`. The control might be a description text box. Only emit `UploadImage` when you see a camera/upload widget.
+- ❌ Label contains "attach" / "file" / "document" → automatically `UploadFile`. Same rule — needs an actual file picker.
+- ❌ Label contains "address" → automatically `Address`. A single text line for address is `ShortText` or `LongText`. Only emit `Address` for a compound widget with separate sub-inputs.
+- ❌ Any table → `Repeater`. A table where each row is a fixed inspection point (with shared OK/NOK columns) is `Matrix`, not `Repeater`.
+- ❌ Any list of options → `Picklist`. If the source explicitly shows radio buttons or "circle one", use `Radio`.
+
+When the evidence is ambiguous, **fall back to the simplest type** (`ShortText`, `LongText`, `Numeric`) and call it out in the confirmation step so the user can correct it before deploy.
+
+## Conditional fields
+
+If a field on the form is preceded by something like "If Work Order, also fill: WO#" or only makes sense given a previous answer, attach a `visibility` block:
+
+```json
+{
+  "fieldName": "WorkOrderNumber",
+  "fieldLabel": "WO#",
+  "fieldType": "ShortText",
+  "isRequired": true,
+  "visibility": { "field": "To", "operator": "EqualTo", "value": "Work Order" }
+}
+```
+
+The `value` must match one of the parent field's `options` exactly (display text, not the api-sanitized name).
+
+## Naming rules
+
+- `fieldName`: camelCase or PascalCase, English even if the label is in another language. No spaces, no special characters (underscore allowed). Unique within the form. ≤ 80 chars.
+- Screen keys: `PascalCase` describing the section (`HeaderInformation`, `OperatingParameters`, `VisualInspection`). Never `Screen1`, `Screen2`.
+- `formTitle`: human-readable, original language allowed. The Flow's API name is derived from this by the deploy step.
+- `formType`: short descriptor (e.g. `Inspection Report`, `Service Log`, `Inventory Transfer`).
+
+## Label rules
+
+- **Preserve** original language, umlauts/accents, units, bilingual text exactly as shown (`"Kennwort: / Job name:"`).
+- **Strip** leading `*`, `(required)`, `(mandatory)`, `Pflichtfeld` from the label and set `isRequired: true` instead.
+- **Do not** translate or rephrase.
+
+## Screen grouping
+
+- 8–12 fields per screen, max.
+- A form with a single section and a repeater can be a single screen — don't fabricate sections.
+- Group by logical sections in the source (header info, measurements, inspection, attachments, signatures…).
+- Use the source's section breaks where they exist.
+- Use descriptive PascalCase screen names — never `Screen1`.
+
+## Sections within a screen
+
+A Section is a *visual grouping inside one screen* — distinct from splitting fields across multiple screens. Emit a section **only when the source visibly shows a labeled group header** (a banner/heading like "Asset Details", "Inspection Notes", a colored separator with a title, or a visibly bordered group).
+
+When you emit a section, insert a `{ "section": "Header Label" }` item into the screen's field list before the fields belonging to that group:
+
+```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"] }
+    ]
+  }
+}
+```
+
+**When NOT to use sections:**
+- The source has no visible group headers — emit a flat field list.
+- The source uses one heading per screen (these are *screen names*, not within-screen sections).
+- You'd be inventing groupings the source doesn't show.
+
+**One-section screens are usually wrong.** A single section spanning the whole screen is just a screen with a redundant header bar. Either emit no sections, or emit ≥ 2 sections per screen.
+
+## Post-screen automation — determine the desired outcome
+
+A data capture form is rarely just a form. The captured data almost always needs to **do** something in Salesforce: create a record, update a record, look something up. That "do something" is the desired outcome.
+
+You **must** determine the desired outcome before finalizing the spec. A form that captures perfect data but never writes anything to Salesforce is a broken flow.
+
+### Outcome-elicitation rules
+
+For every form, ask yourself:
+
+1. **What Salesforce object should be created or updated when the user finishes the form?** (e.g. ProductTransfer, WorkOrderLineItem, Case, Asset, ServiceAppointment.)
+2. **Are any rows in a Repeater supposed to become individual records?** If yes, you need a `loop` over `<Repeater>.AddedItems` and a `recordCreate` per iteration.
+3. **Does any captured value need to be resolved to a record Id before writing?** If yes, you need a `recordLookup`.
+4. **Is the user picking a branch that determines which lookup or write to do?** If yes, you need a `decision`.
+5. **Is there a parent record passed in via `parentRecordId` / `parentObjectType` that should be referenced or updated?** This is the standard Field Service entry-point pattern.
+
+### How to decide whether to emit `postScreen`
+
+| Signal | Action |
+|---|---|
+| The form's name or purpose strongly implies a single object — Inventory Transfer, Work Order Completion, Asset Inspection, Damage Report, Time Entry | **Emit `postScreen`** with your best-guess object/field mapping AND list every `valueRef` / `field` in the confirmation step so the user can correct names. |
+| The form has a Repeater whose rows obviously become rows in Salesforce (parts, line items, time entries, photos with metadata) | **Emit `postScreen`** with a loop + recordCreate. State the assumption explicitly. |
+| You're refining an existing flow the user pointed you at | **Mirror the existing flow's `postScreen`** (same object, same field shape). |
+| You truly cannot infer what the data should do | Surface a question to the user in the confirmation step ("What should happen when this form is submitted?") and emit no `postScreen` until they answer. |
+
+### Common outcome patterns
+
+- **Inventory Transfer** (form has a parts repeater) → loop over `Part.AddedItems` → create one `ProductTransfer` per row, mapping `Product2Id`, `QuantitySent`, `QuantityReceived`, `DestinationLocationId`.
+- **Inspection / Checklist** → create one `WorkOrderLineItem` or `Asset__History` record summarizing the inspection.
+- **Time Entry** → create a `ResourceAbsence` or custom time-entry record tied to `parentRecordId`.
+- **Damage Report** → update the parent Work Order and/or create child Case records.
+
+### Validation for `postScreen`
+
+When you emit a `postScreen` block, every reference must point at a real thing:
+
+- Every `valueRef` is either: a `<fieldName>.value` from a screen field, a `<RepeaterName>.<ChildName>.value` inside a loop, a non-input variable you declared, or a global like `$User.Id`.
+- Every `field` in `inputAssignments` and `outputAssignments` is the API name of a field on the named `object`. If you don't know the exact API name, use your best guess and list it in the confirmation step.
+- Every `next` connector targets the name of an element you actually defined.
+- The decision's branch `when.field` is a screen field, and `when.value` exactly matches one of that field's `options`.
+
+## Validation checklist
+
+Before returning, verify:
+
+- [ ] Every screen key is PascalCase.
+- [ ] Every `fieldName` is a valid API name, unique across the form (including inside repeaters).
+- [ ] Every `fieldType` is one of the supported types in [field-types.md](../../fs-data-capture-form-deployer/reference/field-types.md) (case-sensitive).
+- [ ] `Radio`, `Picklist`, `CheckboxGroup` have non-empty `options`.
+- [ ] `Matrix` has both `options` (columns) and `matrixRows`.
+- [ ] `Repeater` has `repeaterFields` (each child has its own valid `fieldType`).
+- [ ] Any `visibility.value` exactly matches one of the referenced field's `options`.
+- [ ] No required indicators (`*`, "(required)") left in any label.
+- [ ] No translations of original labels.
+- [ ] No fabricated fields the source doesn't have.
+- [ ] **Outcome is determined.** Either a `postScreen` block is emitted, or the confirmation step will explicitly ask the user what to do with the data.
+- [ ] If `postScreen` is emitted: every `valueRef` resolves, every `field` belongs to the named `object` (or is flagged for user review), every `next` connector targets a defined element, and decision branch `value`s match a parent field's `options`.
+- [ ] **Specialized types are evidence-backed.** For every `Signature`, `UploadFile`, `UploadImage`, `Images`, `FileView`, `Address`, `Matrix`, `Lookup`, and `Repeater` in the output, name the visual evidence (camera-icon button, sign-here pad, +/- stepper, table with row-add button, typeahead picker). If you can only point to the field's *label*, downgrade the type per the table above. (These deploy as **real functional components** — `dcSignature`, `dcUpImage`, `dcMatrix`, etc. — so emitting them when the source only shows a text line is the most common extraction bug.)
+- [ ] **Lookup has `lookupObject`.** Every `Lookup` field has a `lookupObject` (Salesforce object API name). If the source doesn't make it explicit, pick a best-guess and flag it in the confirmation step.
+- [ ] **FileView has `fileName`.** Every `FileView` field has a `fileName` (static asset filename, no extension). If unknown, surface a question.
+- [ ] **Repeaters are not duplicated.** No two `Repeater` fields have identical `repeaterFields` (merge side-by-side or stacked tables that share columns). No `repeaterFields` entries for symbol-only headers (`Δ`, `Σ`).
+- [ ] **Sections only where the source shows them.** Every `{ "section": "..." }` item corresponds to a visible group header in the source. No invented sections, and no screens with exactly one section.
+
+---
+
+## Source design docs
+
+This rule sheet is informed by two upstream design docs. Don't paste the full prompts from those docs into the user-facing flow — they're internal source-of-truth references.
+
+- **Form-To-Flow AI HLD** ([doc](https://docs.google.com/document/d/1XlDRQE1gVrux8Iyz5LDupN9xV7i1IKpczLbsvMq5Tc4)) — the Flow Builder team's architecture for PDF-to-DC-Flow generation.
+- **Field Service POC HLD** ([doc](https://docs.google.com/document/d/10TO6CC983AcclXY7Ixp3I3hY5R7TagUMWP9VRqXOFoc)) — Field Service team's Apex+Agentforce POC. Source for the intermediate JSON contract and the extraction prompt rules.

package/skills/field-service-data-capture-form-designer-configure/references/extraction-from-prompt.md

@@ -0,0 +1,222 @@
+# Extraction rules — natural-language sources
+
+These are the rules to follow when given a prose description of a form (no PDF or image) and asked to produce the intermediate JSON spec for a Data Capture Flow.
+
+The spec schema is the input contract of the build skill — see [field-types.md](../../fs-data-capture-form-deployer/reference/field-types.md) and [post-screen-automation.md](../../fs-data-capture-form-deployer/reference/post-screen-automation.md). This file covers extraction *behavior*; that file covers what the converter accepts.
+
+## Output schema
+
+```json
+{
+  "formTitle": "string",
+  "formType": "string",
+  "screens": {
+    "PascalCaseScreenName1": [ /* fields */ ],
+    "PascalCaseScreenName2": [ /* fields */ ]
+  },
+  "postScreen": { /* optional — see post-screen-automation.md */ }
+}
+```
+
+Each field has these properties (only `fieldName`, `fieldLabel`, and `fieldType` are required):
+
+| Property | Type | Notes |
+|----------|------|-------|
+| `fieldName` | string | camelCase or PascalCase, English, unique across the form, valid Salesforce API name. |
+| `fieldLabel` | string | The label the user gave (or a faithful summary if they didn't give an explicit label). Strip required indicators (`*`, `(required)`). |
+| `fieldType` | string | One of the supported types in `field-types.md`. Case-sensitive. |
+| `isRequired` | boolean | true if the user said "required", "mandatory", "must enter", etc. |
+| `defaultValue` | string \| null | null for input fields; for `DisplayText`, the static body text. |
+| `options` | array \| null | Required for `Radio`, `Picklist`, `CheckboxGroup`, `Matrix` (column choices). null otherwise. |
+| `repeaterFields` | array | Required for `Repeater`. List of nested field objects with the same shape. |
+| `matrixRows` | array | Required for `Matrix`. List of row labels. |
+| `min` / `max` / `value` | number | Optional for `Counter` — initial/min/max for the +/- counter. |
+| `visibility` | object | Optional. `{ "field": "<fieldName>", "operator": "EqualTo", "value": "<choice display>" }` — show this field only when the referenced choice is selected. |
+| `lookupObject` | string | Required for `Lookup`. Salesforce object API name (e.g. `"Asset"`, `"WorkOrder"`). |
+| `lookupSearchFields` | string | Optional for `Lookup`. Comma-separated field API names searched by typeahead (e.g. `"Name, SerialNumber"`). |
+| `lookupMulti` | boolean | Optional for `Lookup`. true to allow selecting multiple records. |
+| `fileName` | string | Required for `FileView`. Static-asset filename without extension. |
+
+## Output requirements
+
+1. Output **only** the JSON object.
+2. No markdown, no code fences, no explanation before or after.
+3. Use `null` for null, `true`/`false` for booleans, double-quoted strings.
+4. Stop immediately after the closing `}`.
+
+## Field-type classification — explicit vocabulary required
+
+For prose input (no visual reference), only choose specialized types (`Signature`, `UploadFile`, `UploadImage`, `FileView`, `Matrix`, `Address`, `Repeater`) when the user **explicitly** describes that control. The user saying "captures the inspector's signature" with no other context isn't enough — that could be a typed name or a real signature pad. Default to the simpler text/number/date type unless the user uses control vocabulary.
+
+Use the **most specific** type the prose evidence supports. Default to `ShortText` when in doubt.
+
+| Type | Prose evidence required |
+|---|---|
+| `Name` | User says the field captures a person's name (inspector, operator, technician, customer, employee). |
+| `Email` | User says "email". |
+| `Phone` | User says "phone", "phone number", "mobile", "contact number". |
+| `Numeric` | User says "number", "count", or gives a numeric measurement (pressure, temperature, weight). |
+| `Counter` | User says "counter", "stepper", "+/- quantity", "quantity field". |
+| `Date` | User says "date". |
+| `DateTime` | User says "date and time", "timestamp". |
+| `Checkbox` | User says "checkbox" (singular). |
+| `CheckboxGroup` | User says "select multiple", "all that apply", "checkbox group". |
+| `Radio` | User says "radio", "single choice", "pick one", "select one". |
+| `Picklist` | User says "dropdown", "picklist", "select from a list". For person-name dropdowns, prefer `Name`. |
+| `Toggle` | User says "toggle" or "on/off switch". |
+| `UploadFile` | User says "upload a file" / "attach a document" / explicitly describes a file picker. |
+| `UploadImage` | User says "upload an image" / "add a photo" / "camera capture" / explicitly describes an image picker. |
+| `FileView` | User explicitly asks for a read-only image viewer. |
+| `Signature` | User says "signature pad" / "captures a signature" / explicitly describes a sign-here widget. |
+| `Matrix` | User explicitly describes a same-question-per-row table (rows share OK/NOK columns). |
+| `Repeater` | User says "add multiple rows" / "list of parts" / "repeat for each item" / "repeater". |
+| `Address` | User explicitly says "compound address" or lists street/city/state/zip as a single block. |
+| `LongText` | User says "notes", "comments", "long text", "description", "remarks". |
+| `ShortText` | User just lists a label with no other vocabulary. **This is the default.** |
+| `DisplayText` | User explicitly says "show static text" / "instructions". |
+| `Lookup` | User says "lookup", "select a record", "pick an existing X". Requires `lookupObject` (the Salesforce object API name). |
+
+### Anti-patterns (do NOT do these)
+
+- ❌ User mentions "signature" → automatically `Signature`. They might mean a typed name. Only emit `Signature` when they say "signature pad", "sign-here widget", or similar control vocabulary.
+- ❌ User mentions "photo" / "image" → automatically `UploadImage`. They might mean a description field. Only emit `UploadImage` when they say "upload an image", "add a photo", "camera capture".
+- ❌ User mentions "address" → automatically `Address`. Single text line is fine for most addresses. Only emit `Address` for an explicit compound widget.
+- ❌ User says "table" → automatically `Repeater` or `Matrix`. Ask for clarification: rows-the-user-adds (Repeater) vs. fixed-rows-with-shared-columns (Matrix).
+- ❌ Inventing fields the user didn't mention. If the user says "asset id, condition rating, photos, and remarks", emit four fields. Don't add an "Inspector" or "Date Inspected" field just because forms usually have those.
+
+When the evidence is ambiguous, **fall back to the simplest type** (`ShortText`, `LongText`, `Numeric`) and call it out in the confirmation step so the user can correct it before deploy.
+
+## Conditional fields
+
+If the user describes a field that depends on a previous answer ("if they pick Work Order, then ask for the WO number"), attach a `visibility` block:
+
+```json
+{
+  "fieldName": "WorkOrderNumber",
+  "fieldLabel": "WO Number",
+  "fieldType": "ShortText",
+  "isRequired": true,
+  "visibility": { "field": "To", "operator": "EqualTo", "value": "Work Order" }
+}
+```
+
+The `value` must match one of the parent field's `options` exactly (display text, not the api-sanitized name).
+
+## Naming rules
+
+- `fieldName`: camelCase or PascalCase, English. No spaces, no special characters (underscore allowed). Unique within the form. ≤ 80 chars.
+- Screen keys: `PascalCase` describing the section (`HeaderInformation`, `OperatingParameters`, `VisualInspection`). Never `Screen1`, `Screen2`.
+- `formTitle`: human-readable. The Flow's API name is derived from this by the deploy step.
+- `formType`: short descriptor (e.g. `Inspection Report`, `Service Log`, `Inventory Transfer`).
+
+## Label rules
+
+- Use the user's words verbatim where possible. If the user gave a label, keep it. If they only described the field ("the inspector's name"), summarize concisely as the label ("Inspector Name").
+- **Strip** any `*`, `(required)`, `(mandatory)` from the label and set `isRequired: true` instead.
+
+## Screen grouping
+
+- 8–12 fields per screen, max.
+- A small form (≤ 8 fields) can be a single screen — don't fabricate sections.
+- If the user described multiple sections ("first ask for header info, then measurements, then the parts list"), respect their grouping.
+- If the user just listed fields with no sections, group them into one screen unless there are more than 12 fields. Then split logically.
+- Use descriptive PascalCase screen names — never `Screen1`.
+
+## Sections within a screen
+
+A Section is a *visual grouping inside one screen* — distinct from splitting fields across multiple screens. **Default to a flat field list.** Emit sections only when the user explicitly describes named sub-groups within a single screen ("on the inspection screen, group fields under 'Asset Details' and 'Inspection Notes'"). Don't infer sections from a list of field topics — a list of fields is just a list of fields.
+
+When you emit a section, insert a `{ "section": "Header Label" }` item into the screen's field list before the fields belonging to that group:
+
+```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"] }
+    ]
+  }
+}
+```
+
+**When NOT to use sections:**
+- The user didn't explicitly name within-screen sub-groups.
+- The user described separate steps (those become separate *screens*, not sections).
+- You'd be inventing groupings the user didn't describe.
+
+**Single-column only.** Sections render as full-width single-column groups. Don't try to express multi-column layouts.
+
+**One-section screens are usually wrong.** A single section spanning the whole screen is just a screen with a redundant header bar. Either emit no sections, or emit ≥ 2 sections per screen.
+
+## Post-screen automation — determine the desired outcome
+
+A data capture form is rarely just a form. The captured data almost always needs to **do** something in Salesforce: create a record, update a record, look something up.
+
+You **must** determine the desired outcome before finalizing the spec. A form that captures perfect data but never writes anything to Salesforce is a broken flow.
+
+### Outcome-elicitation rules
+
+For every form, ask yourself:
+
+1. **What Salesforce object should be created or updated when the user finishes?** (e.g. ProductTransfer, WorkOrderLineItem, Case, Asset, ServiceAppointment.)
+2. **Are any rows in a Repeater supposed to become individual records?** If yes, you need a `loop` over `<Repeater>.AddedItems` and a `recordCreate` per iteration.
+3. **Does any captured value need to be resolved to a record Id before writing?** If yes, you need a `recordLookup`.
+4. **Is the user picking a branch that determines which lookup or write to do?** If yes, you need a `decision`.
+5. **Is there a parent record passed in via `parentRecordId` / `parentObjectType`?** This is the standard Field Service entry-point pattern.
+
+### How to decide whether to emit `postScreen`
+
+| Signal | Action |
+|---|---|
+| The user explicitly says what to create/update ("create a ProductTransfer for each part") | **Emit `postScreen`** with the named object and field mappings. |
+| The user gives a form name or purpose that strongly implies a single object — Inventory Transfer, Work Order Completion, Asset Inspection, Damage Report, Time Entry | **Emit `postScreen`** with your best-guess object/field mapping AND list every `valueRef` / `field` in the confirmation step so the user can correct names. |
+| The user describes a Repeater whose rows obviously become rows in Salesforce | **Emit `postScreen`** with a loop + recordCreate. State the assumption explicitly. |
+| You truly cannot infer what the data should do, AND the user gave no hint | Surface a question in the confirmation step ("What should happen when this form is submitted?") with concrete options. Don't deploy a screens-only flow without flagging that the data goes nowhere. |
+
+### Common outcome patterns
+
+- **Inventory Transfer** (form has a parts repeater) → loop over `Part.AddedItems` → create one `ProductTransfer` per row, mapping `Product2Id`, `QuantitySent`, `QuantityReceived`, `DestinationLocationId`.
+- **Inspection / Checklist** → create one `WorkOrderLineItem` or `Asset__History` record summarizing the inspection.
+- **Time Entry** → create a `ResourceAbsence` or custom time-entry record tied to `parentRecordId`.
+- **Damage Report** → update the parent Work Order and/or create child Case records.
+
+### Validation for `postScreen`
+
+When you emit a `postScreen` block, every reference must point at a real thing:
+
+- Every `valueRef` is either: a `<fieldName>.value` from a screen field, a `<RepeaterName>.<ChildName>.value` inside a loop, a non-input variable you declared, or a global like `$User.Id`.
+- Every `field` in `inputAssignments` and `outputAssignments` is the API name of a field on the named `object`. If you don't know the exact API name, use your best guess and list it in the confirmation step.
+- Every `next` connector targets the name of an element you actually defined.
+- The decision's branch `when.field` is a screen field, and `when.value` exactly matches one of that field's `options`.
+
+## Validation checklist
+
+Before returning, verify:
+
+- [ ] Every screen key is PascalCase.
+- [ ] Every `fieldName` is a valid API name, unique across the form (including inside repeaters).
+- [ ] Every `fieldType` is one of the supported types in [field-types.md](../../fs-data-capture-form-deployer/reference/field-types.md) (case-sensitive).
+- [ ] `Radio`, `Picklist`, `CheckboxGroup` have non-empty `options` (use 3–5 plausible options if the user didn't list specific ones, and surface that you guessed).
+- [ ] `Matrix` has both `options` (columns) and `matrixRows`.
+- [ ] `Repeater` has `repeaterFields` (each child has its own valid `fieldType`).
+- [ ] Any `visibility.value` exactly matches one of the referenced field's `options`.
+- [ ] **No fabricated fields the user didn't mention.** This is the most common prose-extraction bug — don't pad the form with "usual" fields.
+- [ ] **Outcome is determined.** Either a `postScreen` block is emitted, or the confirmation step will explicitly ask the user what to do with the data.
+- [ ] If `postScreen` is emitted: every `valueRef` resolves, every `field` belongs to the named `object` (or is flagged for user review), every `next` connector targets a defined element.
+- [ ] **Specialized types are evidence-backed.** For every `Signature`, `UploadFile`, `UploadImage`, `Images`, `Matrix`, `Address`, `Lookup`, `FileView`, and `Repeater` in the output, name the prose evidence ("user said 'add multiple parts'"). If the user only used the *label* not the *control vocabulary*, downgrade the type per the table above. (These are real components that deploy as functional widgets — emitting them when the user only meant a text field is the most common bug.)
+- [ ] **Lookup has `lookupObject`.** Every `Lookup` field has a `lookupObject` (Salesforce object API name). If the user didn't say which object, surface a question in the confirmation step or pick a best-guess and flag it.
+- [ ] **FileView has `fileName`.** Every `FileView` field has a `fileName` (static asset filename, no extension). If unknown, surface a question.
+- [ ] **Sections only where the user described them.** Every `{ "section": "..." }` item corresponds to a named sub-group the user actually mentioned. No invented sections, and no screens with exactly one section.
+
+---
+
+## Source design docs
+
+This rule sheet is informed by two upstream design docs. Don't paste the full prompts from those docs into the user-facing flow — they're internal source-of-truth references.
+
+- **Form-To-Flow AI HLD** ([doc](https://docs.google.com/document/d/1XlDRQE1gVrux8Iyz5LDupN9xV7i1IKpczLbsvMq5Tc4)) — the Flow Builder team's architecture for prose/PDF-to-DC-Flow generation.
+- **Field Service POC HLD** ([doc](https://docs.google.com/document/d/10TO6CC983AcclXY7Ixp3I3hY5R7TagUMWP9VRqXOFoc)) — Field Service team's Apex+Agentforce POC. Source for the intermediate JSON contract and the extraction prompt rules.

package/skills/field-service-data-capture-form-editor-configure/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: field-service-data-capture-form-editor-configure
+description: "Patch an existing Data Capture Flow that's already deployed in a connected Salesforce org. Retrieves the live Flow Metadata JSON via the Tooling API, applies the user's requested change, and PATCHes it back. Use when the user names an existing flow and asks to add/remove/rename a field, change visibility, fix a bug, add visual polish, or swap a placeholder for a real component ('add a Notes field to Inventory_Transfer', 'fix the visibility rule on Work_Order_Number', 'make the parts repeater optional', 'replace the Signature placeholder with the real dcSignature component'). Do NOT use this skill to build a brand-new flow — that's fs-data-capture-form-designer followed by fs-data-capture-form-deployer."
+user-invocable: false
+metadata:
+  version: "1.0"
+  domains: ["Field Service"]
+---
+
+# Edit a Data Capture Form (in an org)
+
+This skill patches a flow that already exists in a connected org. The source of truth is the deployed flow's `Metadata` JSON, retrieved live from the Tooling `Flow` sObject — there is no spec file, no `.flow-meta.xml`, no zip, no SFDX project. The skill retrieves the JSON, edits it in memory, and PATCHes it back.
+
+> **Runtime contract:** every org interaction in this skill is a REST call
+> dispatched through the Codey runtime (`execute_api` locally / the hosted
+> Headless 360 MCP in shared surfaces). This skill has **no dependency on the
+> execution environment** — no `sf` CLI, no local Python, no temp files, no
+> scratch SFDX project. Auth probes, the flow retrieve, and the redeploy are
+> single REST calls; the JSON patch is authored by the agent inline. Do not
+> shell out.
+
+## When this skill fires
+
+- The user names an existing flow (`Inventory_Transfer`, `Asset_Inspection`, etc.) and asks for a change.
+- The user pastes a Flow Builder URL and asks for a change.
+- The user describes a deploy error or runtime bug in a deployed flow.
+
+If the user is starting from scratch (prose, PDF, image), route to a `design-*` skill instead.
+
+## Workflow
+
+### 1. Verify org auth
+
+Confirm the connected org is reachable with a cheap auth probe — dispatch `SELECT Id FROM Organization LIMIT 1` (`GET /services/data/vXX.0/query`):
+
+- 2xx with `totalSize=1` → the session token is live; continue.
+- 401/403 → the org needs re-authentication. Surface that to the user and **stop**. (The Codey runtime resolves and refreshes the connected org — this skill does not manage org aliases.)
+
+### 2. Retrieve the live flow's Metadata JSON
+
+The Tooling `Flow` sObject exposes the flow definition as a JSON `Metadata` field — the same shape the deployer assembles and POSTs. Retrieving is a two-call round-trip, no CLI and no file:
+
+1. **Resolve the latest version id from the API name.** Dispatch `GET /services/data/vXX.0/tooling/query` with:
+
+   ```sql
+   SELECT Id, ActiveVersionId, LatestVersionId FROM FlowDefinition WHERE DeveloperName = '<FlowApiName>'
+   ```
+
+   Edit the **latest** version (`LatestVersionId`) so the patch builds on the newest draft, not a stale active version. If `LatestVersionId` is null, fall back to `ActiveVersionId`.
+
+2. **Read the Metadata blob.** Dispatch `GET /services/data/vXX.0/tooling/sobjects/Flow/<versionId>` and take the `Metadata` object from the response. This JSON is the flow — screens, choices, decisions, variables, and the post-screen chain. See [../fs-data-capture-form-deployer/reference/flow-metadata-json.md](../fs-data-capture-form-deployer/reference/flow-metadata-json.md) for the shape.
+
+If the FlowDefinition query returns zero rows, the API name is wrong or the user is pointed at the wrong org. Confirm with the user before retrying. List the candidate flows in the org if useful — dispatch `GET /services/data/vXX.0/tooling/query` with `SELECT DeveloperName FROM FlowDefinition ORDER BY DeveloperName`.
+
+### 3. Read the retrieved Metadata JSON and the rule sheet
+
+Before patching, **read** the retrieved `Metadata` JSON to understand the current structure, then read [fs-data-capture-reference/SKILL.md](../fs-data-capture-reference/SKILL.md) for the platform's hard constraints. The constraints are identical whether the flow is expressed as XML or JSON — a repeated XML element is a JSON array, so "grouping" becomes "the array" (see the JSON↔XML mapping rule in [../fs-data-capture-form-deployer/reference/flow-metadata-json.md](../fs-data-capture-form-deployer/reference/flow-metadata-json.md)). Pay particular attention to:
+
+- **Element arrays**: `screens`, `choices`, `decisions`, `recordLookups`, `recordCreates`, `recordUpdates`, `loops`, `assignments`, `variables` are each a single JSON array. Add a new element by appending to the right array — never introduce a duplicate top-level key.
+- **CUD ordering**: no record-lookup or screen after any CUD (recordCreate/recordUpdate/recordDelete) in the connector chain. No decision between sequential CUDs.
+- **`.AllItems` vs `.AddedItems` Repeater accessor** — use what the deployed flow uses, don't change it.
+- **Visibility rules**: in a `visibilityRule.conditions` entry, `leftValueReference` is the *choice* api-name, not the parent field's name.
+- **Required-field behind visibility-rule** anti-pattern (see `fs-data-capture-reference` SKILL.md).
+- **`isLlmTargetable`**: carried as a `{ "stringValue": "true" }`-style wrapper, not a raw JSON boolean — match whatever the retrieved flow uses.
+
+The prohibited-patterns table at the bottom of [fs-data-capture-reference/SKILL.md](../fs-data-capture-reference/SKILL.md) is the fastest reference for "what would break this patch".
+
+### 4. Plan the patch and confirm with the user
+
+Before editing, tell the user:
+
+1. **What you're going to change** — specific element, specific lines (cite `path:line` references), and what the result will look like.
+2. **Whether the change requires schema reordering** — e.g. adding a new `<recordLookups>` element when none exist requires placing it in the right group. Call this out.
+3. **Activation status risk** — patches deploy as a new draft version of the flow. The active version (if any) keeps running until the user activates the new draft in Flow Builder. Tell the user this.
+4. **Anything you noticed that's worth flagging** — pre-existing issues, deprecated patterns, validation rules that look broken. Don't auto-fix unrelated issues; surface them.
+
+Use `AskUserQuestion` to gate the edit. Options:
+- **Apply and deploy** — proceed.
+- **Show me the change first** — present the before/after of just the edited JSON subtree (the specific field, screen, or rule you're touching) inline in the chat, then ask again. No file is written; the patch lives in memory until the user approves the PATCH.
+- **Cancel** — stop without deploying.
+
+Do not proceed to step 5 without explicit approval.
+
+### 5. Apply the patch
+
+Edit the in-memory `Metadata` JSON object retrieved in step 2. Some specific guidelines:
+
+- **Append to the right array.** If you're adding a screen, append to the `screens` array; a choice, to `choices`; a variable, to `variables`. Never create a second top-level key of the same name.
+- **Booleans and numbers stay JSON scalars.** `"isRequired": true`, `"locationX": 0` — not strings. Typed value wrappers keep their key (`{ "stringValue": "X" }`, `{ "booleanValue": true }`, `{ "elementReference": "Foo" }`).
+- **Preserve `locationX` / `locationY`** for existing elements. For new elements set both to `0` — Flow Builder re-layouts on open.
+- **If the change touches a Repeater, preserve the existing `.AllItems` / `.AddedItems` accessor in any loops** — switching accessors will break runtime behavior.
+- **If you add a new field, copy the shape from a sibling field** in the same flow (label inputParameter, `inputsOnNextNavToAssocScrn`, `storeOutputAutomatically`, `styleProperties`, `isRequired`). Don't compose from memory — the rules at [fs-data-capture-reference/SKILL.md](../fs-data-capture-reference/SKILL.md) show what's required per component, but the deployed flow already has working examples.
+- **If the change requires a new `choices` entry**, dedupe — check whether a choice with the same `value` already exists in the `choices` array.
+- **Never emit a `required` inputParameter** on a screen component — some `dc*` components (`dcName`, `dcSignature`) reject it. Carry requiredness via the field's `isRequired` key only.
+
+### 6. Redeploy via a Tooling PATCH
+
+Push the edited flow back as a new draft version with a single Tooling API call — dispatch `PATCH /services/data/vXX.0/tooling/sobjects/Flow/<versionId>` with body:
+
+```json
+{ "Metadata": { "...the full edited Metadata object..." } }
+```
+
+- Send the **complete** `Metadata` object, not a partial patch — Tooling replaces the whole blob.
+- A 204 (No Content) is success. On a 400, the response body's `message` carries the Flow validation error — diagnose against step 7's table.
+- This creates a new **draft** version of the flow. Existing active versions keep running until the user activates the new draft in Flow Builder. (To activate on save instead, set `Metadata.status: "Active"` — default is to leave it Draft.)
+
+### 7. Report back
+
+On success:
+- State plainly what changed (e.g. "Added `Notes` ShortText field to `Header_Information` screen").
+- Print the Flow Builder URL so the user can review and activate. Look up the FlowDefinition Id with a Tooling API query — dispatch `GET /services/data/vXX.0/tooling/query` with `SELECT Id, ActiveVersionId FROM FlowDefinition WHERE DeveloperName = '<FlowApiName>'` → `<instanceUrl>/builder_platform_interaction/flowBuilder.app?flowId=<id>`
+- Remind the user the active version hasn't changed yet — they need to activate the new draft in Flow Builder.
+
+On failure (the `PATCH` returned a 400 — read the error from the response body's `message`):
+- Cross-reference the prohibited-patterns table at [fs-data-capture-reference/SKILL.md](../fs-data-capture-reference/SKILL.md). Common diagnoses for edits: element-array grouping violation, CUD ordering, `Element X doesn't exist` (typo'd reference), `extension not found` (wrong component name), `'Range' is not a valid value` (slider not supported), `We can't find this input attribute: 'required'` (drop the `required` inputParameter — use `isRequired`).
+- If the error is about an element you didn't touch, the retrieved flow might have been in a broken state already. Re-read the current version's Metadata and compare against the active version (`GET /tooling/sobjects/Flow/<ActiveVersionId>`).
+- Don't loop more than twice without showing the user.
+
+## Out of scope
+
+- Building a new flow — `fs-data-capture-form-designer` + `fs-data-capture-form-deployer`.
+- Bulk migrations across many flows.
+- Replacing a flow with a wholly different structure (delete + rebuild is cleaner).
+- Editing flows that aren't `processType=DataCaptureFlow` — this skill assumes the FSL Mobile runtime.
+
+## Related skills
+
+- **`fs-data-capture-reference`** (library) — read this *before* every edit. Source of truth for valid flow patterns, prohibited patterns + exact deploy errors, visual polish HTML, supporting CustomObject/PermissionSet/CustomTab deploy.
+- **`fs-data-capture-form-deployer`** — creates flows via the same Tooling `Flow` JSON round-trip this skill uses to patch them. Its [reference/flow-metadata-json.md](../fs-data-capture-form-deployer/reference/flow-metadata-json.md) is the authoritative `Metadata` shape for both skills.
+
+## Files in this skill
+
+This skill has **no executable scripts**. The auth probe, the flow retrieve (`GET /tooling/sobjects/Flow/{id}`), and the redeploy (`PATCH /tooling/sobjects/Flow/{id}`) are all single REST calls dispatched through the Codey runtime. The JSON patch is authored by the agent inline against [../fs-data-capture-form-deployer/reference/flow-metadata-json.md](../fs-data-capture-form-deployer/reference/flow-metadata-json.md).