@celigo/api-specs 0.2.29 → 0.2.30

package/dist/export.yml

@@ -904,10 +904,15 @@ components:
           iterate ``{{#each rows}}``); hook code sees the array as the
           record element and must not assume object shape.
         - |-
-          Transform 2.0 cannot reshape a grouped record at the array root —
-          ``mode: "modify"`` passes the array through untouched and
-          ``mode: "create"`` yields an empty object. Reshape grouped data in
-          a preSavePage hook (or downstream postResponseMap) instead.
+          A grouped record is ONE record: Mapper 2.0 and Transform 2.0 root
+          JSONPath at the array (``$[0].<field>`` / ``$[*].<field>``;
+          ``$.<field>`` resolves nothing), and a Transform 2.0 in ``mode:
+          "create"`` reshapes it in place — header fields from ``$[0]``, a
+          lines array from a ``buildArrayHelper`` over ``$[*]`` (``mode:
+          "modify"`` has no object to overlay and passes the array through
+          untouched). Changing how many records the page carries — each
+          row becoming its own record for every downstream step — is the
+          ``preSavePage`` hook's job alone.
       items:
         type: string
       examples:
@@ -12810,9 +12815,11 @@ components:
             This field supports THREE DISTINCT PATTERNS that are easily distinguished:
 
             **1. json Path Syntax**
-            - MUST start with '$.' prefix
+            - MUST start with '$' — the record root. An object record is addressed as
+              '$.field'; a grouped (array) record as '$[0].field' / '$[*].field'
             - Used for precisely targeting data in structured JSON objects
-            - Examples: '$.customer.firstName', '$.items[0].price', '$.addresses[*].street'
+            - Examples: '$.customer.firstName', '$.items[0].price', '$.addresses[*].street',
+              '$[*].Tax' (every row of a grouped record)
             - Wildcards like [*] extract multiple values/objects
 
             ```json
@@ -12823,7 +12830,8 @@ components:
             - Contains '{{' and '}}' pattern
             - Evaluated by the AFE 2.0 handlebars template engine
             - Can include logic, formatting, and computation
-            - Access input record fields with {{record.fieldName}} notation
+            - Access input record fields with {{record.fieldName}} notation; a grouped
+              (array) record binds as `rows` instead — {{rows.0.fieldName}} / {{#each rows}}
             - Examples: "{{record.firstName}} {{record.lastName}}", "{{#if record.isActive}}Active{{else}}Inactive{{/if}}"
             - Valid on `object`, `objectarray`, and primitive-array dataTypes as
               well as scalars — the rendered template output must parse into the
@@ -12834,7 +12842,7 @@ components:
             ```
 
             **3. Hard-Coded Value (literal string)**
-            - Does NOT start with '$.'
+            - Does NOT start with '$'
             - Does NOT contain handlebars '{{' syntax
             - System treats it as a literal string value
             - VERY COMMON for setting static/constant values
@@ -12856,10 +12864,38 @@ components:
             - The system maintains this context even in deeply nested mappings
             - For object mappings without child mappings, extract should return a complete object
             - When both extract and mappings are defined for objects, extract is applied first
+            - The root is the record as it arrives: an object record roots at `$.field`; a
+              grouped record (an array of rows — grouped exports, file key columns, NetSuite
+              grouped saved searches) roots at the array, so its rows are addressed as
+              `$[0].field` (one row) or `$[*].field` (every row). A root that contradicts the
+              record's shape resolves to nothing without an error.
 
             For most simple field-to-field mappings, prefer JSON path syntax for its clarity and performance.
             For hard-coded values, simply use the literal string as the extract value.
           x-celigo-ai-guidance:
+            - |-
+              ## GROUPED (ARRAY) RECORDS
+              Decide the JSONPath root from the record's shape before writing
+              any extract. When the record is an array of rows, `$.field`,
+              `$.properties.field` and `$.rows[*].field` all resolve to
+              nothing — the processor still reports success and the request
+              body ships as `{}`. Address rows as `$[0].field` (that row's
+              value, typed) or `$[*].field` (every row: joined with commas
+              into a `string` destination; rejected with
+              `incompatible_destination_conversion` into a `number`
+              destination). Column labels with spaces work as
+              `$[*][Order Number]`, `$[*].[Order Number]`, or
+              `$[*]['Order Number']`. For one destination element per row
+              the two array kinds take different helper forms: a primitive
+              array (`stringarray` / `numberarray`) uses `buildArrayHelper:
+              [{"extract": "$[*].field"}]`; an `objectarray` uses
+              `buildArrayHelper: [{"extract": "$[*]", "mappings": [...]}]`
+              with the children addressing the row relatively (`$.field`,
+              `{{rows.field}}`). An `extract` placed directly on the
+              array-typed field yields nothing. Handlebars
+              extracts bind the array record as `rows` (`{{rows.0.field}}`),
+              an object record as `record`. The reverse holds too: `$[*]` on
+              an object record iterates the object's values, not rows.
             - |-
               ## SIZE LIMIT
               The platform's import save validator caps this field at **1024
@@ -13117,7 +13153,11 @@ components:
               (`$.items[*]`), `"$"` (the record root), or omission — a
               constructed entry (child `mappings` with the extract omitted or
               `"$"`; the two spellings are equivalent) contributes exactly one
-              element, and entries append in order. Indexed or comma-joined
+              element, and entries append in order. On a grouped (array)
+              record the record itself is the array to iterate: `"$[*]"`
+              yields one `objectarray` element per row (children address the
+              row as `$.field`), and `"$[*].field"` yields one primitive-array
+              value per row. Indexed or comma-joined
               entry extracts (`"$[0]"`, `"$[0],$[0]"`) are not valid: the
               processor renders the entire destination array as null with no
               validation error. To emit a fixed number of static elements, add
@@ -13138,7 +13178,9 @@ components:
 
             **For Simple Arrays (stringarray, numberarray, booleanarray)**
             - Only the 'extract' field is used to pull values
-            - JSON path with wildcards (e.g., $.items[*].name) returns multiple values
+            - JSON path with wildcards (e.g., $.items[*].name) returns multiple values;
+              on a grouped (array) record the record itself is the array, so the
+              path roots at it ($[*].name — one value per row)
             - Each result is converted to the appropriate primitive type
             ```json
             {
@@ -13240,11 +13282,13 @@ components:
             - When both extract and mappings are provided, the system creates special composite objects
               that maintain hierarchical context during processing
             - This enables accessing both the current array element AND its parent context
-            - An ITERATING entry's extract MUST use JSON path syntax starting with '$.'
-              (e.g. '$.items[*]'). A CONSTRUCTED entry (child mappings building one element)
-              instead omits extract or sets it to exactly "$" — never rewrite "$" into a
-              '$.'-prefixed, indexed, or comma-joined form ('$[0]', '$[0],$[0]'): those render
-              the entire destination array as null without raising a validation error
+            - An ITERATING entry's extract MUST be a JSON path that iterates an array:
+              '$.items[*]' when the array is a field of an object record, or '$[*]'
+              (objectarray) / '$[*].field' (primitive arrays) when the record itself is a
+              grouped array of rows. A CONSTRUCTED entry (child mappings building one
+              element) instead omits extract or sets it to exactly "$" — never rewrite "$"
+              into an indexed or comma-joined form ('$[0]', '$[0],$[0]'): those render the
+              entire destination array as null without raising a validation error
             - Each array helper entry acts independently, potentially adding multiple elements
 
             The buildArrayHelper is the most complex part of the mappings system - always analyze the
@@ -13658,9 +13702,11 @@ components:
               This field supports THREE DISTINCT PATTERNS that are easily distinguished:
 
               **1. json Path Syntax**
-              - MUST start with '$.' prefix
+              - MUST start with '$' — the record root. An object record is addressed as
+                '$.field'; a grouped (array) record as '$[0].field' / '$[*].field'
               - Used for precisely targeting data in structured JSON objects
-              - Examples: '$.customer.firstName', '$.items[0].price', '$.addresses[*].street'
+              - Examples: '$.customer.firstName', '$.items[0].price', '$.addresses[*].street',
+                '$[*].Tax' (every row of a grouped record)
               - Wildcards like [*] extract multiple values/objects
 
               ```json
@@ -13671,7 +13717,8 @@ components:
               - Contains '{{' and '}}' pattern
               - Evaluated by the AFE 2.0 handlebars template engine
               - Can include logic, formatting, and computation
-              - Access input record fields with {{record.fieldName}} notation
+              - Access input record fields with {{record.fieldName}} notation; a grouped
+                (array) record binds as `rows` instead — {{rows.0.fieldName}} / {{#each rows}}
               - Examples: "{{record.firstName}} {{record.lastName}}", "{{#if record.isActive}}Active{{else}}Inactive{{/if}}"
               - Valid on `object`, `objectarray`, and primitive-array dataTypes as
                 well as scalars — the rendered template output must parse into the
@@ -13682,7 +13729,7 @@ components:
               ```
 
               **3. Hard-Coded Value (literal string)**
-              - Does NOT start with '$.'
+              - Does NOT start with '$'
               - Does NOT contain handlebars '{{' syntax
               - System treats it as a literal string value
               - VERY COMMON for setting static/constant values
@@ -13704,10 +13751,38 @@ components:
               - The system maintains this context even in deeply nested mappings
               - For object mappings without child mappings, extract should return a complete object
               - When both extract and mappings are defined for objects, extract is applied first
+              - The root is the record as it arrives: an object record roots at `$.field`; a
+                grouped record (an array of rows — grouped exports, file key columns, NetSuite
+                grouped saved searches) roots at the array, so its rows are addressed as
+                `$[0].field` (one row) or `$[*].field` (every row). A root that contradicts the
+                record's shape resolves to nothing without an error.
 
               For most simple field-to-field mappings, prefer JSON path syntax for its clarity and performance.
               For hard-coded values, simply use the literal string as the extract value.
             x-celigo-ai-guidance:
+              - |-
+                ## GROUPED (ARRAY) RECORDS
+                Decide the JSONPath root from the record's shape before writing
+                any extract. When the record is an array of rows, `$.field`,
+                `$.properties.field` and `$.rows[*].field` all resolve to
+                nothing — the processor still reports success and the request
+                body ships as `{}`. Address rows as `$[0].field` (that row's
+                value, typed) or `$[*].field` (every row: joined with commas
+                into a `string` destination; rejected with
+                `incompatible_destination_conversion` into a `number`
+                destination). Column labels with spaces work as
+                `$[*][Order Number]`, `$[*].[Order Number]`, or
+                `$[*]['Order Number']`. For one destination element per row
+                the two array kinds take different helper forms: a primitive
+                array (`stringarray` / `numberarray`) uses `buildArrayHelper:
+                [{"extract": "$[*].field"}]`; an `objectarray` uses
+                `buildArrayHelper: [{"extract": "$[*]", "mappings": [...]}]`
+                with the children addressing the row relatively (`$.field`,
+                `{{rows.field}}`). An `extract` placed directly on the
+                array-typed field yields nothing. Handlebars
+                extracts bind the array record as `rows` (`{{rows.0.field}}`),
+                an object record as `record`. The reverse holds too: `$[*]` on
+                an object record iterates the object's values, not rows.
               - |-
                 ## SIZE LIMIT
                 The platform's import save validator caps this field at **1024
@@ -13965,7 +14040,11 @@ components:
                 (`$.items[*]`), `"$"` (the record root), or omission — a
                 constructed entry (child `mappings` with the extract omitted or
                 `"$"`; the two spellings are equivalent) contributes exactly one
-                element, and entries append in order. Indexed or comma-joined
+                element, and entries append in order. On a grouped (array)
+                record the record itself is the array to iterate: `"$[*]"`
+                yields one `objectarray` element per row (children address the
+                row as `$.field`), and `"$[*].field"` yields one primitive-array
+                value per row. Indexed or comma-joined
                 entry extracts (`"$[0]"`, `"$[0],$[0]"`) are not valid: the
                 processor renders the entire destination array as null with no
                 validation error. To emit a fixed number of static elements, add
@@ -13986,7 +14065,9 @@ components:
 
               **For Simple Arrays (stringarray, numberarray, booleanarray)**
               - Only the 'extract' field is used to pull values
-              - JSON path with wildcards (e.g., $.items[*].name) returns multiple values
+              - JSON path with wildcards (e.g., $.items[*].name) returns multiple values;
+                on a grouped (array) record the record itself is the array, so the
+                path roots at it ($[*].name — one value per row)
               - Each result is converted to the appropriate primitive type
               ```json
               {
@@ -14088,11 +14169,13 @@ components:
               - When both extract and mappings are provided, the system creates special composite objects
                 that maintain hierarchical context during processing
               - This enables accessing both the current array element AND its parent context
-              - An ITERATING entry's extract MUST use JSON path syntax starting with '$.'
-                (e.g. '$.items[*]'). A CONSTRUCTED entry (child mappings building one element)
-                instead omits extract or sets it to exactly "$" — never rewrite "$" into a
-                '$.'-prefixed, indexed, or comma-joined form ('$[0]', '$[0],$[0]'): those render
-                the entire destination array as null without raising a validation error
+              - An ITERATING entry's extract MUST be a JSON path that iterates an array:
+                '$.items[*]' when the array is a field of an object record, or '$[*]'
+                (objectarray) / '$[*].field' (primitive arrays) when the record itself is a
+                grouped array of rows. A CONSTRUCTED entry (child mappings building one
+                element) instead omits extract or sets it to exactly "$" — never rewrite "$"
+                into an indexed or comma-joined form ('$[0]', '$[0],$[0]'): those render the
+                entire destination array as null without raising a validation error
               - Each array helper entry acts independently, potentially adding multiple elements
 
               The buildArrayHelper is the most complex part of the mappings system - always analyze the
@@ -14818,6 +14901,16 @@ components:
                   x-enumDescriptions:
                     create: Builds entirely new output records from inputs, ignoring unmapped fields.
                     modify: Makes targeted edits to existing records, preserving unmapped fields.
+                  x-celigo-ai-guidance:
+                    - |-
+                      On a grouped record (the export groups rows, so the record is an
+                      array) only `create` can author output — build it from the rows with
+                      `$[0].field`, `$[*].field`, or a `buildArrayHelper` over `$[*]`.
+                      `modify` has no object to overlay onto an array: the record passes
+                      through untouched and the processor reports success. Either mode
+                      reshapes the inside of one record; neither changes how many records
+                      the page carries (that is the export's `preSavePage` hook) or whether
+                      the export groups at all (that is its grouping setting).
                   examples:
                     - create
                     - modify

package/dist/import.yml

@@ -11232,9 +11232,11 @@ components:
             This field supports THREE DISTINCT PATTERNS that are easily distinguished:
 
             **1. json Path Syntax**
-            - MUST start with '$.' prefix
+            - MUST start with '$' — the record root. An object record is addressed as
+              '$.field'; a grouped (array) record as '$[0].field' / '$[*].field'
             - Used for precisely targeting data in structured JSON objects
-            - Examples: '$.customer.firstName', '$.items[0].price', '$.addresses[*].street'
+            - Examples: '$.customer.firstName', '$.items[0].price', '$.addresses[*].street',
+              '$[*].Tax' (every row of a grouped record)
             - Wildcards like [*] extract multiple values/objects
 
             ```json
@@ -11245,7 +11247,8 @@ components:
             - Contains '{{' and '}}' pattern
             - Evaluated by the AFE 2.0 handlebars template engine
             - Can include logic, formatting, and computation
-            - Access input record fields with {{record.fieldName}} notation
+            - Access input record fields with {{record.fieldName}} notation; a grouped
+              (array) record binds as `rows` instead — {{rows.0.fieldName}} / {{#each rows}}
             - Examples: "{{record.firstName}} {{record.lastName}}", "{{#if record.isActive}}Active{{else}}Inactive{{/if}}"
             - Valid on `object`, `objectarray`, and primitive-array dataTypes as
               well as scalars — the rendered template output must parse into the
@@ -11256,7 +11259,7 @@ components:
             ```
 
             **3. Hard-Coded Value (literal string)**
-            - Does NOT start with '$.'
+            - Does NOT start with '$'
             - Does NOT contain handlebars '{{' syntax
             - System treats it as a literal string value
             - VERY COMMON for setting static/constant values
@@ -11278,10 +11281,38 @@ components:
             - The system maintains this context even in deeply nested mappings
             - For object mappings without child mappings, extract should return a complete object
             - When both extract and mappings are defined for objects, extract is applied first
+            - The root is the record as it arrives: an object record roots at `$.field`; a
+              grouped record (an array of rows — grouped exports, file key columns, NetSuite
+              grouped saved searches) roots at the array, so its rows are addressed as
+              `$[0].field` (one row) or `$[*].field` (every row). A root that contradicts the
+              record's shape resolves to nothing without an error.
 
             For most simple field-to-field mappings, prefer JSON path syntax for its clarity and performance.
             For hard-coded values, simply use the literal string as the extract value.
           x-celigo-ai-guidance:
+            - |-
+              ## GROUPED (ARRAY) RECORDS
+              Decide the JSONPath root from the record's shape before writing
+              any extract. When the record is an array of rows, `$.field`,
+              `$.properties.field` and `$.rows[*].field` all resolve to
+              nothing — the processor still reports success and the request
+              body ships as `{}`. Address rows as `$[0].field` (that row's
+              value, typed) or `$[*].field` (every row: joined with commas
+              into a `string` destination; rejected with
+              `incompatible_destination_conversion` into a `number`
+              destination). Column labels with spaces work as
+              `$[*][Order Number]`, `$[*].[Order Number]`, or
+              `$[*]['Order Number']`. For one destination element per row
+              the two array kinds take different helper forms: a primitive
+              array (`stringarray` / `numberarray`) uses `buildArrayHelper:
+              [{"extract": "$[*].field"}]`; an `objectarray` uses
+              `buildArrayHelper: [{"extract": "$[*]", "mappings": [...]}]`
+              with the children addressing the row relatively (`$.field`,
+              `{{rows.field}}`). An `extract` placed directly on the
+              array-typed field yields nothing. Handlebars
+              extracts bind the array record as `rows` (`{{rows.0.field}}`),
+              an object record as `record`. The reverse holds too: `$[*]` on
+              an object record iterates the object's values, not rows.
             - |-
               ## SIZE LIMIT
               The platform's import save validator caps this field at **1024
@@ -11539,7 +11570,11 @@ components:
               (`$.items[*]`), `"$"` (the record root), or omission — a
               constructed entry (child `mappings` with the extract omitted or
               `"$"`; the two spellings are equivalent) contributes exactly one
-              element, and entries append in order. Indexed or comma-joined
+              element, and entries append in order. On a grouped (array)
+              record the record itself is the array to iterate: `"$[*]"`
+              yields one `objectarray` element per row (children address the
+              row as `$.field`), and `"$[*].field"` yields one primitive-array
+              value per row. Indexed or comma-joined
               entry extracts (`"$[0]"`, `"$[0],$[0]"`) are not valid: the
               processor renders the entire destination array as null with no
               validation error. To emit a fixed number of static elements, add
@@ -11560,7 +11595,9 @@ components:
 
             **For Simple Arrays (stringarray, numberarray, booleanarray)**
             - Only the 'extract' field is used to pull values
-            - JSON path with wildcards (e.g., $.items[*].name) returns multiple values
+            - JSON path with wildcards (e.g., $.items[*].name) returns multiple values;
+              on a grouped (array) record the record itself is the array, so the
+              path roots at it ($[*].name — one value per row)
             - Each result is converted to the appropriate primitive type
             ```json
             {
@@ -11662,11 +11699,13 @@ components:
             - When both extract and mappings are provided, the system creates special composite objects
               that maintain hierarchical context during processing
             - This enables accessing both the current array element AND its parent context
-            - An ITERATING entry's extract MUST use JSON path syntax starting with '$.'
-              (e.g. '$.items[*]'). A CONSTRUCTED entry (child mappings building one element)
-              instead omits extract or sets it to exactly "$" — never rewrite "$" into a
-              '$.'-prefixed, indexed, or comma-joined form ('$[0]', '$[0],$[0]'): those render
-              the entire destination array as null without raising a validation error
+            - An ITERATING entry's extract MUST be a JSON path that iterates an array:
+              '$.items[*]' when the array is a field of an object record, or '$[*]'
+              (objectarray) / '$[*].field' (primitive arrays) when the record itself is a
+              grouped array of rows. A CONSTRUCTED entry (child mappings building one
+              element) instead omits extract or sets it to exactly "$" — never rewrite "$"
+              into an indexed or comma-joined form ('$[0]', '$[0],$[0]'): those render the
+              entire destination array as null without raising a validation error
             - Each array helper entry acts independently, potentially adding multiple elements
 
             The buildArrayHelper is the most complex part of the mappings system - always analyze the
@@ -12080,9 +12119,11 @@ components:
               This field supports THREE DISTINCT PATTERNS that are easily distinguished:
 
               **1. json Path Syntax**
-              - MUST start with '$.' prefix
+              - MUST start with '$' — the record root. An object record is addressed as
+                '$.field'; a grouped (array) record as '$[0].field' / '$[*].field'
               - Used for precisely targeting data in structured JSON objects
-              - Examples: '$.customer.firstName', '$.items[0].price', '$.addresses[*].street'
+              - Examples: '$.customer.firstName', '$.items[0].price', '$.addresses[*].street',
+                '$[*].Tax' (every row of a grouped record)
               - Wildcards like [*] extract multiple values/objects
 
               ```json
@@ -12093,7 +12134,8 @@ components:
               - Contains '{{' and '}}' pattern
               - Evaluated by the AFE 2.0 handlebars template engine
               - Can include logic, formatting, and computation
-              - Access input record fields with {{record.fieldName}} notation
+              - Access input record fields with {{record.fieldName}} notation; a grouped
+                (array) record binds as `rows` instead — {{rows.0.fieldName}} / {{#each rows}}
               - Examples: "{{record.firstName}} {{record.lastName}}", "{{#if record.isActive}}Active{{else}}Inactive{{/if}}"
               - Valid on `object`, `objectarray`, and primitive-array dataTypes as
                 well as scalars — the rendered template output must parse into the
@@ -12104,7 +12146,7 @@ components:
               ```
 
               **3. Hard-Coded Value (literal string)**
-              - Does NOT start with '$.'
+              - Does NOT start with '$'
               - Does NOT contain handlebars '{{' syntax
               - System treats it as a literal string value
               - VERY COMMON for setting static/constant values
@@ -12126,10 +12168,38 @@ components:
               - The system maintains this context even in deeply nested mappings
               - For object mappings without child mappings, extract should return a complete object
               - When both extract and mappings are defined for objects, extract is applied first
+              - The root is the record as it arrives: an object record roots at `$.field`; a
+                grouped record (an array of rows — grouped exports, file key columns, NetSuite
+                grouped saved searches) roots at the array, so its rows are addressed as
+                `$[0].field` (one row) or `$[*].field` (every row). A root that contradicts the
+                record's shape resolves to nothing without an error.
 
               For most simple field-to-field mappings, prefer JSON path syntax for its clarity and performance.
               For hard-coded values, simply use the literal string as the extract value.
             x-celigo-ai-guidance:
+              - |-
+                ## GROUPED (ARRAY) RECORDS
+                Decide the JSONPath root from the record's shape before writing
+                any extract. When the record is an array of rows, `$.field`,
+                `$.properties.field` and `$.rows[*].field` all resolve to
+                nothing — the processor still reports success and the request
+                body ships as `{}`. Address rows as `$[0].field` (that row's
+                value, typed) or `$[*].field` (every row: joined with commas
+                into a `string` destination; rejected with
+                `incompatible_destination_conversion` into a `number`
+                destination). Column labels with spaces work as
+                `$[*][Order Number]`, `$[*].[Order Number]`, or
+                `$[*]['Order Number']`. For one destination element per row
+                the two array kinds take different helper forms: a primitive
+                array (`stringarray` / `numberarray`) uses `buildArrayHelper:
+                [{"extract": "$[*].field"}]`; an `objectarray` uses
+                `buildArrayHelper: [{"extract": "$[*]", "mappings": [...]}]`
+                with the children addressing the row relatively (`$.field`,
+                `{{rows.field}}`). An `extract` placed directly on the
+                array-typed field yields nothing. Handlebars
+                extracts bind the array record as `rows` (`{{rows.0.field}}`),
+                an object record as `record`. The reverse holds too: `$[*]` on
+                an object record iterates the object's values, not rows.
               - |-
                 ## SIZE LIMIT
                 The platform's import save validator caps this field at **1024
@@ -12387,7 +12457,11 @@ components:
                 (`$.items[*]`), `"$"` (the record root), or omission — a
                 constructed entry (child `mappings` with the extract omitted or
                 `"$"`; the two spellings are equivalent) contributes exactly one
-                element, and entries append in order. Indexed or comma-joined
+                element, and entries append in order. On a grouped (array)
+                record the record itself is the array to iterate: `"$[*]"`
+                yields one `objectarray` element per row (children address the
+                row as `$.field`), and `"$[*].field"` yields one primitive-array
+                value per row. Indexed or comma-joined
                 entry extracts (`"$[0]"`, `"$[0],$[0]"`) are not valid: the
                 processor renders the entire destination array as null with no
                 validation error. To emit a fixed number of static elements, add
@@ -12408,7 +12482,9 @@ components:
 
               **For Simple Arrays (stringarray, numberarray, booleanarray)**
               - Only the 'extract' field is used to pull values
-              - JSON path with wildcards (e.g., $.items[*].name) returns multiple values
+              - JSON path with wildcards (e.g., $.items[*].name) returns multiple values;
+                on a grouped (array) record the record itself is the array, so the
+                path roots at it ($[*].name — one value per row)
               - Each result is converted to the appropriate primitive type
               ```json
               {
@@ -12510,11 +12586,13 @@ components:
               - When both extract and mappings are provided, the system creates special composite objects
                 that maintain hierarchical context during processing
               - This enables accessing both the current array element AND its parent context
-              - An ITERATING entry's extract MUST use JSON path syntax starting with '$.'
-                (e.g. '$.items[*]'). A CONSTRUCTED entry (child mappings building one element)
-                instead omits extract or sets it to exactly "$" — never rewrite "$" into a
-                '$.'-prefixed, indexed, or comma-joined form ('$[0]', '$[0],$[0]'): those render
-                the entire destination array as null without raising a validation error
+              - An ITERATING entry's extract MUST be a JSON path that iterates an array:
+                '$.items[*]' when the array is a field of an object record, or '$[*]'
+                (objectarray) / '$[*].field' (primitive arrays) when the record itself is a
+                grouped array of rows. A CONSTRUCTED entry (child mappings building one
+                element) instead omits extract or sets it to exactly "$" — never rewrite "$"
+                into an indexed or comma-joined form ('$[0]', '$[0],$[0]'): those render the
+                entire destination array as null without raising a validation error
               - Each array helper entry acts independently, potentially adding multiple elements
 
               The buildArrayHelper is the most complex part of the mappings system - always analyze the
@@ -12971,6 +13049,16 @@ components:
                   x-enumDescriptions:
                     create: Builds entirely new output records from inputs, ignoring unmapped fields.
                     modify: Makes targeted edits to existing records, preserving unmapped fields.
+                  x-celigo-ai-guidance:
+                    - |-
+                      On a grouped record (the export groups rows, so the record is an
+                      array) only `create` can author output — build it from the rows with
+                      `$[0].field`, `$[*].field`, or a `buildArrayHelper` over `$[*]`.
+                      `modify` has no object to overlay onto an array: the record passes
+                      through untouched and the processor reports success. Either mode
+                      reshapes the inside of one record; neither changes how many records
+                      the page carries (that is the export's `preSavePage` hook) or whether
+                      the export groups at all (that is its grouping setting).
                   examples:
                     - create
                     - modify