@celigo/api-specs 0.2.67 → 0.2.69

package/dist/api.yml

@@ -2708,6 +2708,15 @@ components:
       description: |-
         Conditional routing within a builder-mode API. Unlike flows, APIs only
         support `first_matching_branch` routing.
+
+        A router comes in two shapes, told apart by whether `routeRecordsTo` and
+        `routeRecordsUsing` are set: a **branching router** sets both and has two or
+        more branches, each taking the requests its `inputFilter` (or the router's
+        `script`) matches — the node you see in the API builder; a **pass-through
+        router** sets neither and has exactly one branch that every request goes
+        straight through — not drawn, it holds the steps before the first branching
+        router and merges branches back into shared steps (branches rejoin only by
+        pointing `nextRouterId` at the same router).
       properties:
         id:
           type: string
@@ -2727,10 +2736,15 @@ components:
             - first_matching_branch
           x-enumDescriptions:
             first_matching_branch: Routes the request to the first branch whose criteria match.
-          description: Routing strategy. APIs only support `first_matching_branch`.
-          default: first_matching_branch
+          description: |-
+            Routing strategy; APIs only support `first_matching_branch`. Set together with
+            `routeRecordsUsing` on a branching router; leave both unset on a one-branch
+            pass-through router.
           examples:
             - first_matching_branch
+          x-celigo-ai-guidance:
+            - Set this and `routeRecordsUsing` together on every router that decides between branches; setting only one of the two is rejected with 422 `invalid_flow_router_config`.
+            - Leave both unset on a one-branch pass-through router (the steps before the first branching router, or a merge point). Setting them there still runs, but the builder shows a router node with one branch and no rules. A router with neither field and more than one branch is rejected with 422 `invalid_flow_router_branch`.
         routeRecordsUsing:
           type: string
           enum:
@@ -2739,10 +2753,13 @@ components:
           x-enumDescriptions:
             input_filters: Evaluate routing criteria using declarative filter expressions.
             script: Evaluate routing criteria using a custom JavaScript function.
-          description: Method used to evaluate routing criteria.
-          default: input_filters
+          description: |-
+            How a branching router decides which branch a request matches. Set together with
+            `routeRecordsTo`; leave both unset on a one-branch pass-through router.
           examples:
             - input_filters
+          x-celigo-ai-guidance:
+            - Set this and `routeRecordsTo` together on every router that decides between branches, and leave both unset on a one-branch pass-through router; the rejections for a half-set pair or a multi-branch pass-through are listed on `routeRecordsTo`.
         script:
           type: object
           description: |

package/dist/filedefinition.yml

@@ -982,6 +982,8 @@ components:
             - 3c7a8f2e-1234-5678-9abc-def012345678
         rules:
           type: array
+          x-celigo-agent:
+            - file_definition_rules
           description: |
             Ordered array of recursive parsing/generation `Rule` nodes that
             describe the file's structure — segments, elements, loops, and

package/dist/flow.yml

@@ -4356,14 +4356,11 @@ components:
         name:
           type: string
           description: |
-            Unique name for this branch within the router.
-
-            Used for:
-            - Identification in logs and monitoring
-            - Reference in custom routing scripts
-            - Display in the UI
-
-            Should be descriptive of the branch's purpose or criteria.
+            Label for the branch, unique within the router. On a branching router it is shown on
+            the Flow Builder canvas, appears in logs, and is the value a routing script returns to
+            pick the branch — make it describe the branch's purpose. The single branch of a
+            pass-through router has no visible label; the server stores an empty string when the
+            name is omitted.
           examples:
             - enterprise_customers
             - high_priority
@@ -4385,7 +4382,7 @@ components:
           description: |
             Filter criteria that determines which records match this branch.
 
-            Only used when the router's routeRecordsUsing="inputFilter".
+            Only used when the router's `routeRecordsUsing` is `input_filters`.
             Records matching these criteria will be routed to this branch.
           properties:
             version:
@@ -4468,15 +4465,19 @@ components:
             the server when omitted; a client-supplied value is kept as-is.
           examples:
             - El8lWTezixy
-      required:
-        - name
     Router:
       type: object
       description: |
-        Configuration for conditional routing that directs records to different processing branches.
-
-        Routers evaluate each record against defined criteria and route them to appropriate branches
-        for specialized processing. This enables complex business logic and conditional workflows.
+        Directs records into branches. A router comes in two shapes, told apart by whether
+        `routeRecordsTo` and `routeRecordsUsing` are set: a **branching router** sets both and has two
+        or more branches, each taking the records its `inputFilter` (or the router's `script`)
+        matches — the router node you see in Flow Builder; a **pass-through router** sets neither and
+        has exactly one branch that every record goes straight through — not drawn in Flow Builder,
+        it is the joint that holds the steps before the first branching router and that merges
+        branches back into shared steps (branches rejoin only by pointing `nextRouterId` at the same
+        router). A flow with no branching needs no routers — its steps go in top-level
+        `pageProcessors` — unless it is abstract (`isAbstract`), where top-level `pageProcessors` are
+        rejected and the chain sits in one pass-through router.
       properties:
         id:
           type: string
@@ -4499,28 +4500,35 @@ components:
             - Order Status Router
         routeRecordsTo:
           type: string
-          description: Strategy for routing records to branches.
+          description: |-
+            How many branches a record may continue down. Set together with `routeRecordsUsing` on a
+            branching router; leave both unset on a one-branch pass-through router.
           enum:
             - first_matching_branch
             - all_matching_branches
           x-enumDescriptions:
             first_matching_branch: Routes each record to only the first branch whose criteria match.
             all_matching_branches: Routes each record to every branch whose criteria match, creating copies.
-          default: first_matching_branch
           examples:
             - first_matching_branch
+          x-celigo-ai-guidance:
+            - Set this and `routeRecordsUsing` together on every router that decides between branches; setting only one of the two is rejected with 422 `invalid_flow_router_config`.
+            - Leave both unset on a one-branch pass-through router (the steps before the first branching router, or a merge point). Setting them there still runs, but Flow Builder shows a router node with one branch and no rules. A router with neither field and more than one branch is rejected with 422 `invalid_flow_router_branch`.
         routeRecordsUsing:
           type: string
-          description: Method used to evaluate routing criteria.
+          description: |-
+            How a branching router decides which branch a record matches. Set together with
+            `routeRecordsTo`; leave both unset on a one-branch pass-through router.
           enum:
             - input_filters
             - script
           x-enumDescriptions:
             input_filters: Evaluate routing criteria using declarative filter expressions.
             script: Evaluate routing criteria using a custom JavaScript function.
-          default: input_filters
           examples:
             - input_filters
+          x-celigo-ai-guidance:
+            - Set this and `routeRecordsTo` together on every router that decides between branches, and leave both unset on a one-branch pass-through router; the rejections for a half-set pair or a multi-branch pass-through are listed on `routeRecordsTo`.
         script:
           type: object
           description: |
@@ -5271,8 +5279,19 @@ components:
         routers:
           type: array
           description: |-
-            Routing configurations that direct records to conditional branches. Mutually exclusive with
-            top-level `pageProcessors` — use one or the other, not both.
+            Routers that direct records into branches. Mutually exclusive with top-level
+            `pageProcessors` — a flow with no branching uses `pageProcessors` and no routers at all,
+            except an abstract flow (`isAbstract`), which rejects top-level `pageProcessors` and so
+            holds even a linear chain in a pass-through router. A router comes in two shapes: a
+            **branching router** sets both `routeRecordsTo` and `routeRecordsUsing` and has two or
+            more branches (the router node you see in Flow Builder); a **pass-through router** sets
+            neither, has exactly one branch, and is not drawn — it is the invisible joint that holds
+            the steps before the first branching router (they cannot sit in top-level
+            `pageProcessors` once routers exist) and that merges branches back into shared steps.
+          x-celigo-ai-guidance:
+            - No branching on a non-abstract flow → leave `routers` out and put the steps in top-level `pageProcessors`. No branching on an abstract flow → one pass-through router holding the chain (top-level `pageProcessors` are rejected with 422 `abstract_flow_invalid_fields`).
+            - Steps before the first branching router go in a one-branch pass-through router at `routers[0]` with neither `routeRecordsTo` nor `routeRecordsUsing` set, chained to the branching router with `branches[0].nextRouterId`. Branches that rejoin point `nextRouterId` at one shared pass-through router.
+            - A one-branch router with BOTH routing fields set still runs, but Flow Builder draws it as a router node with a single branch and no rules — the pass-through shape (neither field) is the one that stays hidden.
           items:
             $ref: '#/components/schemas/Router'
         _exportId:
@@ -5385,8 +5404,9 @@ components:
             Marks this as an abstract (multi-instance) flow — a reusable template that cannot be
             executed directly. Instance flows reference it via `_abstractFlowId` and provide `overrides`.
 
-            Constraints: top-level `pageProcessors` are not allowed (use `routers`), cannot reference
-            another abstract flow, cannot be a "run next" target, and cannot be unset while instances exist.
+            Constraints: top-level `pageProcessors` are not allowed (use `routers` — a linear chain
+            sits in one pass-through router with neither routing field set), cannot reference another
+            abstract flow, cannot be a "run next" target, and cannot be unset while instances exist.
           examples:
             - true
             - false

package/dist/tool.yml

@@ -5785,6 +5785,15 @@ components:
         Unlike flows, tools only support "first_matching_branch" routing strategy.
         Branches can chain to other routers or use the special "outputRouter"
         terminal sink to exit the tool and return results.
+
+        A router comes in two shapes, told apart by whether `routeRecordsTo` and
+        `routeRecordsUsing` are set: a **branching router** sets both and has two or
+        more branches, each taking the inputs its `inputFilter` (or the router's
+        `script`) matches — the node you see in the Tool builder; a **pass-through
+        router** sets neither and has exactly one branch that every input goes
+        straight through — not drawn, it holds the steps before the first branching
+        router and merges branches back into shared steps (branches rejoin only by
+        pointing `nextRouterId` at the same router).
       x-celigo-ai-guidance:
         - |-
           Set `routeRecordsTo` and `routeRecordsUsing` together or omit both — a router with
@@ -5820,8 +5829,13 @@ components:
           description: |
             Routing strategy. Tools only support "first_matching_branch",
             which routes to the first branch whose criteria match the input.
+            Set together with `routeRecordsUsing` on a branching router; leave
+            both unset on a one-branch pass-through router.
           examples:
             - first_matching_branch
+          x-celigo-ai-guidance:
+            - Set this and `routeRecordsUsing` together on every router that decides between branches; setting only one of the two is rejected with 422 `invalid_flow_router_config`.
+            - Leave both unset on a one-branch pass-through router (the steps before the first branching router, or a merge point). Setting them there still runs, but the builder shows a router node with one branch and no rules. A router with neither field and more than one branch is rejected with 422 `invalid_flow_router_branch`.
         routeRecordsUsing:
           type: string
           enum:
@@ -5831,12 +5845,12 @@ components:
             input_filters: Evaluate routing criteria using declarative filter expressions.
             script: Evaluate routing criteria using a custom JavaScript function.
           description: |
-            Method used to evaluate routing criteria.
-
-            - **input_filters**: Use declarative filter expressions on each branch
-            - **script**: Use a custom JavaScript function to determine the branch
+            How a branching router decides which branch an input matches. Set together
+            with `routeRecordsTo`; leave both unset on a one-branch pass-through router.
           examples:
             - input_filters
+          x-celigo-ai-guidance:
+            - Set this and `routeRecordsTo` together on every router that decides between branches, and leave both unset on a one-branch pass-through router; the rejections for a half-set pair or a multi-branch pass-through are listed on `routeRecordsTo`.
         script:
           type: object
           description: |

package/package.json

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

package/schemas.json

@@ -1,8 +1,8 @@
 {
 	"provenance": {
 		"repo": "celigo/integrator-api-specs",
-		"iasCommit": "f9e33ad",
-		"generatedAt": "2026-10-01"
+		"iasCommit": "5a9800c",
+		"generatedAt": "2026-10-02"
 	},
 	"roots": {
 		"aiagent": 133,