@celigo/api-specs 0.2.6 → 0.2.8

package/dist/ai-agent.yml

@@ -4681,36 +4681,39 @@ components:
     OneToMany:
       type: boolean
       description: |
-        Controls whether the resource treats child records within parent records as the primary data units.
-
-        **Important: this is not for specifying where records are in an api response**
-
-        If you need to tell an export where to find the array of records in the HTTP response
-        body (e.g. "the records are at data.items"), use `http.response.resourcePath` instead.
-        `oneToMany` serves a completely different purpose — it operates on records that have
-        already been extracted from the response.
-
-        **What oneToMany actually does**
-
-        When set to true, this field fundamentally changes how record data is processed:
-        - The system will "unwrap" nested child records from their parent containers
-        - Each child record becomes a separate output record for downstream processing
-        - The pathToMany field must be set to indicate where these child records are located
-        - Parent record fields can still be accessed via a special "parent" context
-
-        This is typically used on **lookup exports** (isLookup: true) or **imports** where
-        the incoming records contain nested arrays that need to be fanned out.
-
-        Common scenarios for enabling this option:
-        - Processing order line items individually from an order export
-        - Handling invoice line items from an invoice export
-        - Processing individual transaction lines from journal entries
-        - Extracting address records from customer exports
-
-        This setting applies for the duration of the current flow step only and does not affect
-        how data is stored or structured in other flow steps.
-
-        If false (default), the resource processes each top-level record as a single unit.
+        When true, the step runs once per child record instead of once per incoming record.
+        `pathToMany` names the array field that holds the children inside an object record; when
+        the incoming record is itself an array (grouped or row-based data), leave `pathToMany` blank
+        and each element becomes a record. The fan-out is scoped to this step: afterwards the children
+        are re-joined into the record's original shape — the object with its array, or the array of rows —
+        carrying any response-mapping enrichment, and that re-joined record is what the next step
+        receives. Not for locating records in an export's HTTP response; use
+        `http.response.resourcePath` for that.
+      x-celigo-ai-guidance:
+        - |-
+          Two modes, decided by the SHAPE of the record entering the step. Object record with a child
+          array under a field → set ``pathToMany`` to that field. Array record (a ``groupByFields``
+          export, a CSV/file group, a script that returns an array) → leave ``pathToMany`` blank; each
+          element becomes one record. Live-verified 2026-09-10 on flows, Tools, and APIs.
+        - |-
+          Blank ``pathToMany`` on an OBJECT record fails every record with code ``oneToMany_error``:
+          "Failed to extract child records from oneToMany import data. Record at index 0 was not an
+          array, and no PathToMany was provided". Builder previews return only the code, with no
+          message. The fix is never "turn oneToMany off" by default — first determine whether the
+          record arriving at the step is an object (set a path) or an array (blank is correct; a
+          preview error on an array-fed step is the preview panel re-applying one-to-many to the
+          already-fanned-out record — verify with a test run or a real run).
+        - |-
+          Child record shape differs by mode. Path mode: each child is the array element plus
+          ``_PARENT`` (the parent record minus the array). Blank/row mode: each child is the element
+          itself, with no ``_PARENT``. In both modes templates on the step reference the child as
+          ``{{record.<field>}}``; a response mapping on a one-to-many lookup merges into each child and
+          the downstream step receives the re-joined parent (path mode) or the re-joined array (row
+          mode) with every element enriched.
+        - |-
+          One-to-many never batches by itself: ``batch_of_records`` appears as the HTTP body template
+          root only when ``http.batchSize`` is greater than 1 (children are batched after fan-out).
+          With the default batch size the template root is ``record``.
       default: false
       examples:
         - true
@@ -4718,27 +4721,25 @@ components:
     PathToMany:
       type: string
       description: |
-        Specifies the JSON path to child records when oneToMany mode is enabled.
-
-        This field is only used when oneToMany is set to true. It defines the exact location
-        of child records within the parent record structure using dot notation:
-
-        - Simple path: "items" for a direct child array field
-        - Nested path: "lines.lineItems" for a more deeply nested array
-        - Multi-level: "details.items.subitems" for deeply nested structures
-
-        The system uses this path to:
-        - Locate the array of child records within each parent record
-        - Extract each array element as a separate record for processing
-        - Make both the child record data and parent context available to downstream steps
-
-        Important considerations:
-        - The path must point to an array field
-        - For row-based data (i.e. where Celigo models this via an array or arrays of objects), this field is not required
-        - If the path is invalid or doesn't exist, the resource will report success but process zero records
-        - Maximum path depth: 10 levels
-
-        This field must contain a valid JSON path expression using dot notation.
+        Path to the array of child records inside an object record when `oneToMany` is true, in dot
+        notation (`items`, `lines.lineItems`). Leave blank when the incoming record is itself an array
+        (grouped or row-based data) — each element is then a child record. A path that does not resolve
+        to an array processes zero records and reports success.
+      x-celigo-ai-guidance:
+        - |-
+          Set this ONLY when the record entering the step is an object whose children sit under a field.
+          On an array record (a ``groupByFields`` export, a CSV/file group, a script returning an array)
+          any path resolves to nothing: the step processes ZERO children, builds no request, and reports
+          success with no error. Live-verified 2026-09-10 — the failure is silent, so confirm the arriving
+          record's shape (test run stage data, or the flow builder's input panel: ``rows`` means array).
+        - |-
+          Blank with an object record is the ``oneToMany_error`` failure ("Record at index 0 was not an
+          array, and no PathToMany was provided"); blank with an array record is the correct row-based
+          configuration. An empty string behaves exactly like an absent field.
+        - |-
+          Use the bare field name or dotted path (``lineItems``, ``details.items``), not a JSONPath
+          expression. Each child in path mode carries ``_PARENT`` (the parent minus the array), so
+          parent-level fields are read as ``{{record._PARENT.<field>}}``.
       examples:
         - items
         - line_items

package/dist/connection.yml

@@ -2445,7 +2445,15 @@ components:
             autoRecoverRateLimitErrors:
               type: boolean
               default: true
-              description: When true, the connection automatically backs off and retries when it encounters rate-limit errors from the target system.
+              description: |-
+                When true, rate-limit errors from the target system trigger automatic recovery: concurrency
+                drops to 1, the rate-limited requests are retried with doubling waits (1 to 1024 minutes,
+                after which the flag switches itself off), and concurrency climbs back toward
+                `targetConcurrencyLevel`. While true, `concurrencyLevel` is platform-managed and writes to
+                it are ignored — `targetConcurrencyLevel` is the lever.
+              x-celigo-ai-guidance:
+                - To change throughput while this is true, write `targetConcurrencyLevel`; a `concurrencyLevel` write returns 200 and changes nothing.
+                - Turning it on copies `concurrencyLevel` into `targetConcurrencyLevel`; turning it off copies the target back into `concurrencyLevel` and unsets the target.
             enableMicroBatchForOneToMany:
               type: boolean
               default: true
@@ -3722,16 +3730,17 @@ components:
             Higher values increase throughput but may trigger API rate limits.
             Set this based on the target API's rate limit documentation.
             Values above the account's licensed maximum (25 standard, 50 with an Environments license) are silently clamped down.
+            Platform-managed while `autoRecoverRateLimitErrors` is true — writes are ignored; set `targetConcurrencyLevel` instead.
           minimum: 1
           maximum: 50
           default: 25
         targetConcurrencyLevel:
           type: number
           description: |
-            Target concurrency level for auto-scaling. The system automatically adjusts
-            concurrency between 1 and this value based on rate limit feedback.
+            Ceiling the platform climbs back to after rate-limit recovery, in steps of 25% of this value.
+            Writing it also sets `concurrencyLevel` to the same value and stops any recovery in progress.
 
-            Only relevant when autoRecoverRateLimitErrors is enabled on the connection.
+            Honored only while `autoRecoverRateLimitErrors` is true; ignored, and unset, when it is false.
           minimum: 1
           maximum: 50
           examples:

package/dist/export.yml

@@ -796,36 +796,39 @@ components:
     OneToMany:
       type: boolean
       description: |
-        Controls whether the resource treats child records within parent records as the primary data units.
-
-        **Important: this is not for specifying where records are in an api response**
-
-        If you need to tell an export where to find the array of records in the HTTP response
-        body (e.g. "the records are at data.items"), use `http.response.resourcePath` instead.
-        `oneToMany` serves a completely different purpose — it operates on records that have
-        already been extracted from the response.
-
-        **What oneToMany actually does**
-
-        When set to true, this field fundamentally changes how record data is processed:
-        - The system will "unwrap" nested child records from their parent containers
-        - Each child record becomes a separate output record for downstream processing
-        - The pathToMany field must be set to indicate where these child records are located
-        - Parent record fields can still be accessed via a special "parent" context
-
-        This is typically used on **lookup exports** (isLookup: true) or **imports** where
-        the incoming records contain nested arrays that need to be fanned out.
-
-        Common scenarios for enabling this option:
-        - Processing order line items individually from an order export
-        - Handling invoice line items from an invoice export
-        - Processing individual transaction lines from journal entries
-        - Extracting address records from customer exports
-
-        This setting applies for the duration of the current flow step only and does not affect
-        how data is stored or structured in other flow steps.
-
-        If false (default), the resource processes each top-level record as a single unit.
+        When true, the step runs once per child record instead of once per incoming record.
+        `pathToMany` names the array field that holds the children inside an object record; when
+        the incoming record is itself an array (grouped or row-based data), leave `pathToMany` blank
+        and each element becomes a record. The fan-out is scoped to this step: afterwards the children
+        are re-joined into the record's original shape — the object with its array, or the array of rows —
+        carrying any response-mapping enrichment, and that re-joined record is what the next step
+        receives. Not for locating records in an export's HTTP response; use
+        `http.response.resourcePath` for that.
+      x-celigo-ai-guidance:
+        - |-
+          Two modes, decided by the SHAPE of the record entering the step. Object record with a child
+          array under a field → set ``pathToMany`` to that field. Array record (a ``groupByFields``
+          export, a CSV/file group, a script that returns an array) → leave ``pathToMany`` blank; each
+          element becomes one record. Live-verified 2026-09-10 on flows, Tools, and APIs.
+        - |-
+          Blank ``pathToMany`` on an OBJECT record fails every record with code ``oneToMany_error``:
+          "Failed to extract child records from oneToMany import data. Record at index 0 was not an
+          array, and no PathToMany was provided". Builder previews return only the code, with no
+          message. The fix is never "turn oneToMany off" by default — first determine whether the
+          record arriving at the step is an object (set a path) or an array (blank is correct; a
+          preview error on an array-fed step is the preview panel re-applying one-to-many to the
+          already-fanned-out record — verify with a test run or a real run).
+        - |-
+          Child record shape differs by mode. Path mode: each child is the array element plus
+          ``_PARENT`` (the parent record minus the array). Blank/row mode: each child is the element
+          itself, with no ``_PARENT``. In both modes templates on the step reference the child as
+          ``{{record.<field>}}``; a response mapping on a one-to-many lookup merges into each child and
+          the downstream step receives the re-joined parent (path mode) or the re-joined array (row
+          mode) with every element enriched.
+        - |-
+          One-to-many never batches by itself: ``batch_of_records`` appears as the HTTP body template
+          root only when ``http.batchSize`` is greater than 1 (children are batched after fan-out).
+          With the default batch size the template root is ``record``.
       default: false
       examples:
         - true
@@ -833,27 +836,25 @@ components:
     PathToMany:
       type: string
       description: |
-        Specifies the JSON path to child records when oneToMany mode is enabled.
-
-        This field is only used when oneToMany is set to true. It defines the exact location
-        of child records within the parent record structure using dot notation:
-
-        - Simple path: "items" for a direct child array field
-        - Nested path: "lines.lineItems" for a more deeply nested array
-        - Multi-level: "details.items.subitems" for deeply nested structures
-
-        The system uses this path to:
-        - Locate the array of child records within each parent record
-        - Extract each array element as a separate record for processing
-        - Make both the child record data and parent context available to downstream steps
-
-        Important considerations:
-        - The path must point to an array field
-        - For row-based data (i.e. where Celigo models this via an array or arrays of objects), this field is not required
-        - If the path is invalid or doesn't exist, the resource will report success but process zero records
-        - Maximum path depth: 10 levels
-
-        This field must contain a valid JSON path expression using dot notation.
+        Path to the array of child records inside an object record when `oneToMany` is true, in dot
+        notation (`items`, `lines.lineItems`). Leave blank when the incoming record is itself an array
+        (grouped or row-based data) — each element is then a child record. A path that does not resolve
+        to an array processes zero records and reports success.
+      x-celigo-ai-guidance:
+        - |-
+          Set this ONLY when the record entering the step is an object whose children sit under a field.
+          On an array record (a ``groupByFields`` export, a CSV/file group, a script returning an array)
+          any path resolves to nothing: the step processes ZERO children, builds no request, and reports
+          success with no error. Live-verified 2026-09-10 — the failure is silent, so confirm the arriving
+          record's shape (test run stage data, or the flow builder's input panel: ``rows`` means array).
+        - |-
+          Blank with an object record is the ``oneToMany_error`` failure ("Record at index 0 was not an
+          array, and no PathToMany was provided"); blank with an array record is the correct row-based
+          configuration. An empty string behaves exactly like an absent field.
+        - |-
+          Use the bare field name or dotted path (``lineItems``, ``details.items``), not a JSONPath
+          expression. Each child in path mode carries ``_PARENT`` (the parent minus the array), so
+          parent-level fields are read as ``{{record._PARENT.<field>}}``.
       examples:
         - items
         - line_items

package/dist/flow.yml

@@ -5333,10 +5333,18 @@ components:
             - false
         autoResolveMatchingTraceKeys:
           type: boolean
-          description: When true, new errors with trace keys matching existing open errors are auto-resolved.
+          default: true
+          description: |-
+            When true, a new error for a record whose trace key already has open errors on the same step
+            auto-resolves the older ones, a later success for that record auto-resolves its open errors,
+            and errors classified `intermittent` are retried automatically — up to four attempts, the
+            first about 30 minutes after the error.
           examples:
             - true
             - false
+          x-celigo-ai-guidance:
+            - Both behaviors hang off this one flag — off means repeated failures of a record stay open and intermittent errors get no automatic retries; never turn it off as a fix for "duplicate" errors (those come from the destination, not from trace keys).
+            - Intermittent auto-retry does not depend on the trace key — errors with a blank trace key are scheduled and retried the same way; a blank key only loses the duplicate collapse.
         isAbstract:
           type: boolean
           description: |-
@@ -6102,13 +6110,18 @@ components:
         classification:
           type: string
           description: |-
-            Category assigned by the platform (or a user) to this error — drives auto-retry and reporting.
-            Empty when unclassified.
+            Category the platform derives from the error's code, message, and source — read-only, never
+            set by users; `intermittent` errors are retried automatically while the flow's
+            `autoResolveMatchingTraceKeys` is on. Absent when nothing matched with confidence. The value
+            set is the `classification` dimension of the errors filter metadata.
           examples:
             - intermittent
+          x-celigo-ai-guidance:
+            - Read the classification off the record; never infer it from the message text — the classifier is heuristic and identical messages can classify differently.
+            - There is no setting, mapping, hook, or API that changes a classification; a wrong one is a Celigo Support matter.
         classifiedBy:
           type: string
-          description: '`auto` when the platform classified it, or a user id / email when a human did.'
+          description: '`auto` on every classified error; absent on unclassified ones.'
           examples:
             - auto
         reqAndResKey:
@@ -6140,11 +6153,14 @@ components:
           type: string
           format: date-time
           description: |-
-            When the platform is scheduled to auto-retry this error. Populated on `classification:
-            intermittent` errors (the platform retries with exponential backoff up to a cap). Absent on
-            errors that won't be auto-retried.
+            Present while the platform is auto-retrying this `intermittent` error. On a first-occurrence
+            error it is stamped about a minute after `occurredAt` and is not the first attempt time (that
+            runs roughly 30 minutes out); on the error a failed attempt opens, it is the next scheduled
+            attempt. Absent once the attempts are exhausted and on errors that are not auto-retried.
           examples:
             - '2026-01-15T09:35:00.000Z'
+          x-celigo-ai-guidance:
+            - Presence answers "is this error in auto-retry mode?"; the value is a real schedule only after at least one attempt has run.
         tags:
           type:
             - array

package/dist/import.yml

@@ -2016,14 +2016,22 @@ components:
               ### Pattern B — Batch / page wrapper around mapped records
 
               Wrap an envelope (header, version, marketplace, etc.) around
-              a serialized batch.  ``{{#each data}}`` iterates the page;
-              ``{{#each batch_of_records}}`` iterates the page-level batch
-              for ``oneToMany`` imports.
+              a serialized batch.  The template root depends ONLY on
+              ``batchSize`` (live-verified 2026-09-10): with ``batchSize`` 1
+              (the default) the root carries ``record`` (an object record —
+              or the fanned-out child on a ``oneToMany`` import) or ``rows``
+              (a grouped/array record), and ``data`` is the one-element list
+              of records in the request; with ``batchSize`` > 1 the root
+              carries ``batch_of_records`` (one ``{record: …}`` item per
+              record in the request) and ``data`` (the bare records), and
+              ``record`` / ``rows`` are ABSENT.  ``oneToMany`` does not make
+              ``batch_of_records`` appear — children are batched after
+              fan-out under the same rule.
 
               Example shape:
               ``{"values": {{#each data}} {{{jsonSerialize this}}} {{/each}} }``
 
-              Example with comma-separation:
+              Example with comma-separation (``batchSize`` > 1):
               ``[{{#each batch_of_records}}{{{jsonSerialize this.record}}}{{#unless @last}},{{/unless}}{{/each}}]``
 
               ### Pattern C — Custom envelope with per-message fields
@@ -10290,36 +10298,39 @@ components:
     OneToMany:
       type: boolean
       description: |
-        Controls whether the resource treats child records within parent records as the primary data units.
-
-        **Important: this is not for specifying where records are in an api response**
-
-        If you need to tell an export where to find the array of records in the HTTP response
-        body (e.g. "the records are at data.items"), use `http.response.resourcePath` instead.
-        `oneToMany` serves a completely different purpose — it operates on records that have
-        already been extracted from the response.
-
-        **What oneToMany actually does**
-
-        When set to true, this field fundamentally changes how record data is processed:
-        - The system will "unwrap" nested child records from their parent containers
-        - Each child record becomes a separate output record for downstream processing
-        - The pathToMany field must be set to indicate where these child records are located
-        - Parent record fields can still be accessed via a special "parent" context
-
-        This is typically used on **lookup exports** (isLookup: true) or **imports** where
-        the incoming records contain nested arrays that need to be fanned out.
-
-        Common scenarios for enabling this option:
-        - Processing order line items individually from an order export
-        - Handling invoice line items from an invoice export
-        - Processing individual transaction lines from journal entries
-        - Extracting address records from customer exports
-
-        This setting applies for the duration of the current flow step only and does not affect
-        how data is stored or structured in other flow steps.
-
-        If false (default), the resource processes each top-level record as a single unit.
+        When true, the step runs once per child record instead of once per incoming record.
+        `pathToMany` names the array field that holds the children inside an object record; when
+        the incoming record is itself an array (grouped or row-based data), leave `pathToMany` blank
+        and each element becomes a record. The fan-out is scoped to this step: afterwards the children
+        are re-joined into the record's original shape — the object with its array, or the array of rows —
+        carrying any response-mapping enrichment, and that re-joined record is what the next step
+        receives. Not for locating records in an export's HTTP response; use
+        `http.response.resourcePath` for that.
+      x-celigo-ai-guidance:
+        - |-
+          Two modes, decided by the SHAPE of the record entering the step. Object record with a child
+          array under a field → set ``pathToMany`` to that field. Array record (a ``groupByFields``
+          export, a CSV/file group, a script that returns an array) → leave ``pathToMany`` blank; each
+          element becomes one record. Live-verified 2026-09-10 on flows, Tools, and APIs.
+        - |-
+          Blank ``pathToMany`` on an OBJECT record fails every record with code ``oneToMany_error``:
+          "Failed to extract child records from oneToMany import data. Record at index 0 was not an
+          array, and no PathToMany was provided". Builder previews return only the code, with no
+          message. The fix is never "turn oneToMany off" by default — first determine whether the
+          record arriving at the step is an object (set a path) or an array (blank is correct; a
+          preview error on an array-fed step is the preview panel re-applying one-to-many to the
+          already-fanned-out record — verify with a test run or a real run).
+        - |-
+          Child record shape differs by mode. Path mode: each child is the array element plus
+          ``_PARENT`` (the parent record minus the array). Blank/row mode: each child is the element
+          itself, with no ``_PARENT``. In both modes templates on the step reference the child as
+          ``{{record.<field>}}``; a response mapping on a one-to-many lookup merges into each child and
+          the downstream step receives the re-joined parent (path mode) or the re-joined array (row
+          mode) with every element enriched.
+        - |-
+          One-to-many never batches by itself: ``batch_of_records`` appears as the HTTP body template
+          root only when ``http.batchSize`` is greater than 1 (children are batched after fan-out).
+          With the default batch size the template root is ``record``.
       default: false
       examples:
         - true
@@ -10327,27 +10338,25 @@ components:
     PathToMany:
       type: string
       description: |
-        Specifies the JSON path to child records when oneToMany mode is enabled.
-
-        This field is only used when oneToMany is set to true. It defines the exact location
-        of child records within the parent record structure using dot notation:
-
-        - Simple path: "items" for a direct child array field
-        - Nested path: "lines.lineItems" for a more deeply nested array
-        - Multi-level: "details.items.subitems" for deeply nested structures
-
-        The system uses this path to:
-        - Locate the array of child records within each parent record
-        - Extract each array element as a separate record for processing
-        - Make both the child record data and parent context available to downstream steps
-
-        Important considerations:
-        - The path must point to an array field
-        - For row-based data (i.e. where Celigo models this via an array or arrays of objects), this field is not required
-        - If the path is invalid or doesn't exist, the resource will report success but process zero records
-        - Maximum path depth: 10 levels
-
-        This field must contain a valid JSON path expression using dot notation.
+        Path to the array of child records inside an object record when `oneToMany` is true, in dot
+        notation (`items`, `lines.lineItems`). Leave blank when the incoming record is itself an array
+        (grouped or row-based data) — each element is then a child record. A path that does not resolve
+        to an array processes zero records and reports success.
+      x-celigo-ai-guidance:
+        - |-
+          Set this ONLY when the record entering the step is an object whose children sit under a field.
+          On an array record (a ``groupByFields`` export, a CSV/file group, a script returning an array)
+          any path resolves to nothing: the step processes ZERO children, builds no request, and reports
+          success with no error. Live-verified 2026-09-10 — the failure is silent, so confirm the arriving
+          record's shape (test run stage data, or the flow builder's input panel: ``rows`` means array).
+        - |-
+          Blank with an object record is the ``oneToMany_error`` failure ("Record at index 0 was not an
+          array, and no PathToMany was provided"); blank with an array record is the correct row-based
+          configuration. An empty string behaves exactly like an absent field.
+        - |-
+          Use the bare field name or dotted path (``lineItems``, ``details.items``), not a JSONPath
+          expression. Each child in path mode carries ``_PARENT`` (the parent minus the array), so
+          parent-level fields are read as ``{{record._PARENT.<field>}}``.
       examples:
         - items
         - line_items

package/dist/tool.yml

@@ -4883,7 +4883,15 @@ components:
             autoRecoverRateLimitErrors:
               type: boolean
               default: true
-              description: When true, the connection automatically backs off and retries when it encounters rate-limit errors from the target system.
+              description: |-
+                When true, rate-limit errors from the target system trigger automatic recovery: concurrency
+                drops to 1, the rate-limited requests are retried with doubling waits (1 to 1024 minutes,
+                after which the flag switches itself off), and concurrency climbs back toward
+                `targetConcurrencyLevel`. While true, `concurrencyLevel` is platform-managed and writes to
+                it are ignored — `targetConcurrencyLevel` is the lever.
+              x-celigo-ai-guidance:
+                - To change throughput while this is true, write `targetConcurrencyLevel`; a `concurrencyLevel` write returns 200 and changes nothing.
+                - Turning it on copies `concurrencyLevel` into `targetConcurrencyLevel`; turning it off copies the target back into `concurrencyLevel` and unsets the target.
             enableMicroBatchForOneToMany:
               type: boolean
               default: true
@@ -6160,16 +6168,17 @@ components:
             Higher values increase throughput but may trigger API rate limits.
             Set this based on the target API's rate limit documentation.
             Values above the account's licensed maximum (25 standard, 50 with an Environments license) are silently clamped down.
+            Platform-managed while `autoRecoverRateLimitErrors` is true — writes are ignored; set `targetConcurrencyLevel` instead.
           minimum: 1
           maximum: 50
           default: 25
         targetConcurrencyLevel:
           type: number
           description: |
-            Target concurrency level for auto-scaling. The system automatically adjusts
-            concurrency between 1 and this value based on rate limit feedback.
+            Ceiling the platform climbs back to after rate-limit recovery, in steps of 25% of this value.
+            Writing it also sets `concurrencyLevel` to the same value and stops any recovery in progress.
 
-            Only relevant when autoRecoverRateLimitErrors is enabled on the connection.
+            Honored only while `autoRecoverRateLimitErrors` is true; ignored, and unset, when it is false.
           minimum: 1
           maximum: 50
           examples:
@@ -10618,14 +10627,22 @@ components:
               ### Pattern B — Batch / page wrapper around mapped records
 
               Wrap an envelope (header, version, marketplace, etc.) around
-              a serialized batch.  ``{{#each data}}`` iterates the page;
-              ``{{#each batch_of_records}}`` iterates the page-level batch
-              for ``oneToMany`` imports.
+              a serialized batch.  The template root depends ONLY on
+              ``batchSize`` (live-verified 2026-09-10): with ``batchSize`` 1
+              (the default) the root carries ``record`` (an object record —
+              or the fanned-out child on a ``oneToMany`` import) or ``rows``
+              (a grouped/array record), and ``data`` is the one-element list
+              of records in the request; with ``batchSize`` > 1 the root
+              carries ``batch_of_records`` (one ``{record: …}`` item per
+              record in the request) and ``data`` (the bare records), and
+              ``record`` / ``rows`` are ABSENT.  ``oneToMany`` does not make
+              ``batch_of_records`` appear — children are batched after
+              fan-out under the same rule.
 
               Example shape:
               ``{"values": {{#each data}} {{{jsonSerialize this}}} {{/each}} }``
 
-              Example with comma-separation:
+              Example with comma-separation (``batchSize`` > 1):
               ``[{{#each batch_of_records}}{{{jsonSerialize this.record}}}{{#unless @last}},{{/unless}}{{/each}}]``
 
               ### Pattern C — Custom envelope with per-message fields
@@ -18623,36 +18640,39 @@ components:
     OneToMany:
       type: boolean
       description: |
-        Controls whether the resource treats child records within parent records as the primary data units.
-
-        **Important: this is not for specifying where records are in an api response**
-
-        If you need to tell an export where to find the array of records in the HTTP response
-        body (e.g. "the records are at data.items"), use `http.response.resourcePath` instead.
-        `oneToMany` serves a completely different purpose — it operates on records that have
-        already been extracted from the response.
-
-        **What oneToMany actually does**
-
-        When set to true, this field fundamentally changes how record data is processed:
-        - The system will "unwrap" nested child records from their parent containers
-        - Each child record becomes a separate output record for downstream processing
-        - The pathToMany field must be set to indicate where these child records are located
-        - Parent record fields can still be accessed via a special "parent" context
-
-        This is typically used on **lookup exports** (isLookup: true) or **imports** where
-        the incoming records contain nested arrays that need to be fanned out.
-
-        Common scenarios for enabling this option:
-        - Processing order line items individually from an order export
-        - Handling invoice line items from an invoice export
-        - Processing individual transaction lines from journal entries
-        - Extracting address records from customer exports
-
-        This setting applies for the duration of the current flow step only and does not affect
-        how data is stored or structured in other flow steps.
-
-        If false (default), the resource processes each top-level record as a single unit.
+        When true, the step runs once per child record instead of once per incoming record.
+        `pathToMany` names the array field that holds the children inside an object record; when
+        the incoming record is itself an array (grouped or row-based data), leave `pathToMany` blank
+        and each element becomes a record. The fan-out is scoped to this step: afterwards the children
+        are re-joined into the record's original shape — the object with its array, or the array of rows —
+        carrying any response-mapping enrichment, and that re-joined record is what the next step
+        receives. Not for locating records in an export's HTTP response; use
+        `http.response.resourcePath` for that.
+      x-celigo-ai-guidance:
+        - |-
+          Two modes, decided by the SHAPE of the record entering the step. Object record with a child
+          array under a field → set ``pathToMany`` to that field. Array record (a ``groupByFields``
+          export, a CSV/file group, a script that returns an array) → leave ``pathToMany`` blank; each
+          element becomes one record. Live-verified 2026-09-10 on flows, Tools, and APIs.
+        - |-
+          Blank ``pathToMany`` on an OBJECT record fails every record with code ``oneToMany_error``:
+          "Failed to extract child records from oneToMany import data. Record at index 0 was not an
+          array, and no PathToMany was provided". Builder previews return only the code, with no
+          message. The fix is never "turn oneToMany off" by default — first determine whether the
+          record arriving at the step is an object (set a path) or an array (blank is correct; a
+          preview error on an array-fed step is the preview panel re-applying one-to-many to the
+          already-fanned-out record — verify with a test run or a real run).
+        - |-
+          Child record shape differs by mode. Path mode: each child is the array element plus
+          ``_PARENT`` (the parent record minus the array). Blank/row mode: each child is the element
+          itself, with no ``_PARENT``. In both modes templates on the step reference the child as
+          ``{{record.<field>}}``; a response mapping on a one-to-many lookup merges into each child and
+          the downstream step receives the re-joined parent (path mode) or the re-joined array (row
+          mode) with every element enriched.
+        - |-
+          One-to-many never batches by itself: ``batch_of_records`` appears as the HTTP body template
+          root only when ``http.batchSize`` is greater than 1 (children are batched after fan-out).
+          With the default batch size the template root is ``record``.
       default: false
       examples:
         - true
@@ -18660,27 +18680,25 @@ components:
     PathToMany:
       type: string
       description: |
-        Specifies the JSON path to child records when oneToMany mode is enabled.
-
-        This field is only used when oneToMany is set to true. It defines the exact location
-        of child records within the parent record structure using dot notation:
-
-        - Simple path: "items" for a direct child array field
-        - Nested path: "lines.lineItems" for a more deeply nested array
-        - Multi-level: "details.items.subitems" for deeply nested structures
-
-        The system uses this path to:
-        - Locate the array of child records within each parent record
-        - Extract each array element as a separate record for processing
-        - Make both the child record data and parent context available to downstream steps
-
-        Important considerations:
-        - The path must point to an array field
-        - For row-based data (i.e. where Celigo models this via an array or arrays of objects), this field is not required
-        - If the path is invalid or doesn't exist, the resource will report success but process zero records
-        - Maximum path depth: 10 levels
-
-        This field must contain a valid JSON path expression using dot notation.
+        Path to the array of child records inside an object record when `oneToMany` is true, in dot
+        notation (`items`, `lines.lineItems`). Leave blank when the incoming record is itself an array
+        (grouped or row-based data) — each element is then a child record. A path that does not resolve
+        to an array processes zero records and reports success.
+      x-celigo-ai-guidance:
+        - |-
+          Set this ONLY when the record entering the step is an object whose children sit under a field.
+          On an array record (a ``groupByFields`` export, a CSV/file group, a script returning an array)
+          any path resolves to nothing: the step processes ZERO children, builds no request, and reports
+          success with no error. Live-verified 2026-09-10 — the failure is silent, so confirm the arriving
+          record's shape (test run stage data, or the flow builder's input panel: ``rows`` means array).
+        - |-
+          Blank with an object record is the ``oneToMany_error`` failure ("Record at index 0 was not an
+          array, and no PathToMany was provided"); blank with an array record is the correct row-based
+          configuration. An empty string behaves exactly like an absent field.
+        - |-
+          Use the bare field name or dotted path (``lineItems``, ``details.items``), not a JSONPath
+          expression. Each child in path mode carries ``_PARENT`` (the parent minus the array), so
+          parent-level fields are read as ``{{record._PARENT.<field>}}``.
       examples:
         - items
         - line_items

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celigo/api-specs",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "private": false,
   "description": "Public OpenAPI bundles (dist/) and the celigo-cli lint schema pack (schemas.json).",
   "files": [

package/schemas.json

@@ -1,7 +1,7 @@
 {
 	"provenance": {
 		"repo": "celigo/integrator-api-specs",
-		"iasCommit": "96fa282",
+		"iasCommit": "3f92987",
 		"generatedAt": "2026-09-10"
 	},
 	"roots": {