@controllerai/cli 0.2.17 → 0.2.20

package/skills/controllerai-expressions/references/command-reference.md

@@ -0,0 +1,166 @@
+# Controller AI expressions
+
+
+Controller AI uses a restricted JavaScript-like authoring language that is compiled into the workflow engine's expression AST. It is not general JavaScript. Discover the real scope and compile before every write.
+
+
+- Wire first; refresh context after structural changes. See Required write loop.
+- `--value` is static; dynamic values use `--js`. See Typed values and templates.
+- Copy current bindings, not labels or stale names. See Read the destination's exact scope.
+- Never use raw ASTs, general JavaScript, or private APIs. See Use only advertised syntax.
+- Keep ternaries in the destination type. See Typed values and templates.
+- Prove resolution in a containing-flow run. See Verify runtime resolution.
+
+Data types are the TypeScript types of workflows: every expression is typed, and an expression can only be written against a known type. Integration types describe what integration actions output (resolved by a successful dev run); `custom.*` types describe shapes for data-store records and AI-node structured outputs. Two wrappers matter: `dataRecord.custom.x` means "an actual stored record of that shape" — the fields plus record identity (`id`, `createdAt`) — while bare `custom.x` is just data in that shape; `list.` prefixes a list of any type. When an expression cannot be authored, the cause is usually a missing type — resolve the upstream node's output type first, don't guess field paths.
+
+`.every()` accepts the same multi-condition predicates as `.filter()` and compiles to `:all match`. A removed schema field makes `.every()` false but is dropped by `.filter()`. Comparator semantics govern missing, null, and unparseable values; guards must require presence explicitly.
+
+## How empty values evaluate
+
+An empty input evaluates to its typed empty form: `""` for TEXT, null/undefined for objects. Both cases below fail silently:
+
+- **A filter compared with empty matches no records.** To skip an omitted constraint, opt into `ignoreEmptyConstraints`; see [dsl-and-recipes.md](dsl-and-recipes.md).
+- **An omitted optional TEXT input arrives as `""`.** Equality then matches nothing and can make a create-if-missing step duplicate data.
+
+When a run unexpectedly returns zero results, check the resolved configs for empty comparison values first (`cai exec node <nodeExecutionId> --full`).
+
+## Required write loop
+
+### 1. Wire first
+
+An upstream output is available only after it is connected to the target node. If context lists it under `unwiredUpstreamOutputs`, connect it, then fetch context again.
+
+```bash
+cai node connect --flow <flowId> --from <sourceNodeId> --to <targetNodeId> --json
+```
+
+Use `cai branch connect` for Router or If/Else outputs.
+
+### 2. Read the destination's exact scope
+
+```bash
+cai expr context <nodeId> --prop <propName> --json
+```
+
+Copy binding and field names exactly. Important sources include:
+
+- `flow.<name>`: flow input
+- `inputs.<name>`: wired node input; the payload is usually already unwrapped
+- `item`: injected current item, only where context exposes it
+- `workflowData("custom.type")`: records from an active workflow collection
+- `now`, `isLiveVersion`: constants shown by context
+
+Do not derive a binding from a display label. Context flags duplicate display names and supplies the de-duplicated JS name, input ID, and source node.
+
+When compilation reports an unknown field, copy a typeable display-derived accessor it advertises; field IDs appear second for disambiguation.
+
+### 3. Use only advertised syntax
+
+Get the current operation catalog when needed:
+
+```bash
+cai expr ops --workflow <workflowId> --type <text|number|date|list|boolean|file|custom> --json
+```
+
+The catalog is workflow-scoped because it is read from expression context. On CLI, an existing `cai use` or `CAI_WORKFLOW` selection can replace the explicit flag; MCP `expr_operation_list` always requires `workflowId`.
+
+Keep the program to optional `const` declarations followed by one final expression. Do not submit raw AST JSON or probe private APIs. Do not use loops, assignments, `new`, regular expressions, optional chaining, arbitrary library methods, or object construction unless the compiler catalog supports them.
+
+Date values are ISO-8601 strings on the wire (`"2026-06-05"` or `"2026-06-05T12:30:00Z"`). A `date`-typed flow input or field is used directly with date operations; only `text` values need `.toDate()` first. For epoch text, pass the unit literal explicitly: `flow.timestamp.toDate("epoch_seconds")` or `flow.timestamp.toDate("epoch_millis")`. The ops table renders that argument generically; never guess the unit from digit count.
+
+#### Typed values and templates
+
+`--value` stores a literal, so `flow.name`, `{inputs.Name}`, `{{name}}`, and `${name}` stay static. `--js` and `--js-file` compile typed expressions. `${...}` interpolates only inside a backtick template expression, which returns text. Keep non-text values as direct typed expressions.
+
+Ternaries preserve compatible scalar branch types: number and boolean branches stay number and boolean. A different inferred destination type means the write is incomplete. Report the compiler error; do not quote or coerce branches to text.
+
+Read [dsl-and-recipes.md](dsl-and-recipes.md) for canonical patterns.
+
+### 4. Compile, write, and read back
+
+For a node prop, prefer:
+
+```bash
+cai expr set <nodeId> --prop <propName> --js '<expression>' --json
+```
+
+MCP: use `node_prop_set` with `js`; it merges `cai expr set` with `cai node set`.
+
+For multiline expressions or shell-sensitive templates on CLI, put the exact source in a UTF-8 file and use `--js-file <path>`. Use `--js-file -` to read stdin. It is mutually exclusive with inline `--js` and is available on `expr validate/set`, `node set/only-when`, and `branch add/update`.
+
+```bash
+cai expr set <nodeId> --prop <propName> --js-file expression.js --json
+```
+
+MCP: pass the file contents inline as `js`; the hosted process does not read the local path or stdin.
+
+This fetches target metadata, auto-enables a catalog-only optional target when needed, compiles before writing the value, persists to the correct channel, and verifies read-back. If validation or the value write then fails, the prop stays enabled; repair with `cai node disable-prop <nodeId> --prop <propName>`.
+
+MCP: repair with `node_optional_prop_set` and `enabled: false`.
+
+Array channels are not interchangeable. On a value-channel `SHORT_TEXT_ARRAY`, a scalar expression replaces the whole array with one dynamic element; it does not append. List-typed expressions on value-channel array props are rejected. Use `cai node set <nodeId> --prop <propName> --value '["a","b"]'` for a static list, or use a list-typed expression only where prop metadata exposes whole-array expression mode.
+
+For a side-effect-free check:
+
+```bash
+cai expr validate <nodeId> --prop <propName> --js '<expression>' --json
+```
+
+For conditions:
+
+```bash
+cai expr validate <nodeId> --mode onlyWhen --js '<boolean expression>' --json
+cai node only-when <nodeId> --js '<boolean expression>' --json
+```
+
+Node `only-when` takes one restricted boolean through `--js` or `--js-file`, or grouped conditions through `--groups-json '[["a","b"],["c"]]'` (inner arrays are AND, outer rows are OR). Root scalar `&&` or `||` inside one expression is unsupported; use `--groups-json` for compound guards. Branch add/update accepts `string[][]`: outer rows are OR, inner entries are AND, and each entry compiles separately.
+
+```bash
+cai branch update <nodeId> --route <routeId> --condition-json '[["flow.email.isNotEmpty()","flow.units < 5"],["flow.override === true"]]' --json
+```
+
+Use grouping only when branch semantics fit. For a compound node-only guard, use `--groups-json`; do not weaken the rule or probe private APIs. To make missing numeric input fail `< 5`, use `(flow.unitsLeft ?? 5) < 5`.
+
+Router and If/Else conditions are written with `cai branch add` or `cai branch update` after the same context/validation discipline.
+
+### 5. Verify runtime resolution
+
+```bash
+cai expr decompile <nodeId> --prop <propName> --json
+cai run node <nodeId> --inputs <values.json> --json
+```
+
+MCP: `run_node` takes the parsed `inputs` object and `waitSeconds` (default 60, max 120).
+
+Use `run node` to isolate the destination's own configuration. It never executes wired upstream nodes. If the expression consumes `inputs.<name>`, also run its containing flow:
+
+```bash
+cai run flow <flowId> --inputs <values.json> --json
+```
+
+MCP: `run_flow` takes the parsed `inputs` object and `waitSeconds` (default 60, max 120).
+
+Inspect `runScope` and `resolvedConfigs` in the run result. A null or missing dynamic config is an expression failure, not success; a partially empty value is equally suspect. Only the full flow run proves an upstream-derived value. Use `cai exec node <nodeExecutionId> --full --json` to inspect the final status, resolved configs, and untruncated output.
+
+## Hard rules
+
+- Never guess a binding, field, method, or target type.
+- Never author against an unwired output.
+- Never add `.data` automatically. Use the exact path shown by context.
+- Re-read context after rewiring, renaming inputs, changing schemas, changing dynamic selectors, or resolving an output type.
+- Preserve `0` and `false`; they are values, not missing data.
+- Optional filters need an explicit behavior decision. Do not silently change fail-closed filtering to match-all.
+- A compiler success proves syntax and types, not correct source selection. Verify the source node/input IDs when names are ambiguous and inspect runtime values.
+
+## Before you finish
+
+```bash
+cai expr context <nodeId> --prop <propName> --json
+cai expr validate <nodeId> --prop <propName> --js '<expression>' --json
+cai expr decompile <nodeId> --prop <propName> --json
+cai run flow <flowId> --inputs <values.json> --json
+```
+
+- Context must show current source IDs and bindings.
+- Validation and decompile must agree on source and type.
+- The flow run must show the intended value in `runScope` and `resolvedConfigs`.

package/skills/controllerai-expressions/references/dsl-and-recipes.md

@@ -90,7 +90,7 @@ workflowData("custom.lead").filter(
 )
 ```
 
-Test both the supplied and omitted cases. Empty text may behave as a real value rather than a missing value; do not assume the opt-in drops it.
+Test both supplied and omitted cases. With this option, null, omitted values, empty text and empty lists are skipped; zero and false remain real constraints. Optional OR filters preserve input order and duplicates, and return all rows when every branch is skipped. Use `.take(count)` and `.skip(offset)` for pagination.
 
 ## Loop item
 

package/skills/controllerai-flow-control/SKILL.md

@@ -1,178 +1,39 @@
 ---
 name: controllerai-flow-control
-description: Design and configure Controller AI execution paths using only-when rules, Router routes, If/Else branches, for-each loops, and subflows. Use when work must branch, fan out, skip, iterate over a list, call another flow, converge paths, or handle errors without changing the user's intended semantics.
+description: Build Controller AI execution paths with conditions, routers, if/else branches, loops, joins and subflow calls. Use when a flow must validate, branch, iterate or reuse another flow.
 ---
 
-# Controller AI flow control
+# Routing, loops and reusable flows
 
-The `cai ...` examples are canonical grammar. Use the transport selected in `controllerai-start` and its MCP tool map; never mix transports in one task.
+Control-flow nodes decide which steps execute and how data moves between paths. Use conditions to validate requests, a router for named alternatives, a loop for each item in a list, and subflows for reusable behavior.
 
-Choose by intended runtime semantics.
+## Choose the construct
 
-## Rules that break tasks when skipped
+- **Only when:** skip one node unless a condition holds.
+- **If/Else:** two paths, such as record found versus not found.
+- **Router:** several named routes, such as search modes or operation types.
+- **For each / Run Flow on List:** execute a body flow for each typed item and collect iteration results.
+- **Subflow:** call a reusable typed flow and map its inputs/outputs.
+- **Join paths:** deliberately reconcile active paths before a shared continuation.
 
-- Guard the exact action with node `only-when`; see Conditions.
-- Use If/Else for one path and Router for all matches; see Pick the correct primitive.
-- Keep downstream wiring after node-only skip; see Conditions.
-- Never invent a missing condition or Router order; see If/Else and Router.
-- Build standard loops only with `flow for-each`; see Loops.
-- Converge paths through Join Paths; see Subflows and convergence.
-- Fail missing comparisons closed; keep money paths blocking. See Conditions, Loops, and the error pattern.
-- Never acknowledge validation errors without explicit approval; see `controllerai-workflows` Lifecycle rules.
+Choose whether multiple matching routes should run or one alternative should win. Make invalid/missing-input paths return a clear result without performing the write. A skipped node is expected only if its condition and port explain why.
 
-## Pick the correct primitive
+## Build branches
 
-| Intent | Primitive | Semantics |
-| --- | --- | --- |
-| Skip one action when a condition is false | Node `only-when` | No alternate path |
-| Choose exactly one path | If/Else | First matching branch runs; Else is last |
-| Run every matching path | Router | Conditions are independent; multiple routes may run |
-| Apply work to every list item | `flow for-each` | Atomic loop scaffold with typed item flow |
-| Reuse a typed unit of work once | Run flow/subflow node | Explicit input and output contract |
-| Continue after an action error | Error output or continue-on-error | Error behavior is explicit and testable |
+Inspect the router's current expression context, define a route condition, and connect the route output to its path. Conditions can use the flow's inputs and wired upstream data. Use the supported structured OR-of-AND condition groups for compound logic; do not assume ordinary JavaScript syntax is valid in every condition surface.
 
-Do not substitute one primitive merely because its component is easier to find.
+A condition accepting a record requires a fetched record, not a fabricated object. Test both branches, including false/zero values and a missing record. Declare and populate the flow output on each intended return path.
 
-## Conditions
+## Build loops
 
-Before writing any condition:
+Use the available for-each scaffolding operation to create the loop, body flow, typed item input and mappings together. It reduces the mistakes involved in assembling loop injection manually. Supply the list expression and exact source output when wiring an upstream list.
 
-```bash
-cai expr context <controlNodeId> --json
-cai expr validate <controlNodeId> --mode onlyWhen --js '<boolean expression>' --json
-```
+The body receives one item; it does not receive the whole original list implicitly. Custom-shaped items and real data-record items have different types. Loop output represents iteration results, so inspect its actual fields before mapping a final list.
 
-For one guarded action:
+For an uploaded CSV, a conversational agent can read rows and call a per-row flow. Use a native loop when the workflow already receives a typed list and deterministic iteration is desired.
 
-```bash
-cai node only-when <nodeId> --js '<boolean expression>' --json
-```
+## Verify paths
 
-Use `--clear` only when the user's intent is to remove the guard.
+Run one representative case per route and inspect node status, selected output ports, skipped reasons and final outputs. For writes, verify the same-environment record effects. A successful outer loop does not prove every iteration succeeded; surface row failures in the result.
 
-Guard the action that must skip. Do not substitute If/Else for a node-only skip. Its `only_when_false` does not block ordinary output; downstream remains eligible. Keep wiring. Guard downstream separately or branch if it must also skip.
-
-Node `only-when` takes one restricted boolean through `--js` or `--js-file`, or grouped conditions through `--groups-json '[["a","b"],["c"]]'` (inner arrays are AND, outer rows are OR). Root scalar `&&` or `||` inside one expression is unsupported; use `--groups-json` for compound guards. Grouped `string[][]` conditions exist only on branch add/update, with outer rows OR and inner entries AND. Use them only when branch semantics fit. If an exact compound node-only guard is required, report it as unsupported; do not weaken the rule or probe private APIs. For a missing number that must fail `< 5`, use a same-type boundary such as `(flow.unitsLeft ?? 5) < 5`.
-
-Choose the primitive by the runtime signal that callers and tests need. A false node `only-when` records `skipReason: "only_when_false"`; a node on an untaken If/Else branch or unmatched Router route records `skipReason: "upstream_skipped"`.
-
-## If/Else and Router
-
-Discover and initialize the appropriate control component using `controllerai-node-config`, then inspect its exact branch IDs:
-
-```bash
-cai branch list <controlNodeId> --json
-```
-
-A fresh If/Else already contains one blank `If` branch and an Else branch. The blank condition is a publish/runtime blocker: copy that default branch ID from `branch list` and update it before adding another condition branch. Do not leave the default blank and create a replacement beside it.
-
-Never invent a missing condition from node names, current values, or one observed run. If no authoritative platform surface supplies the business rule, leave the branch blank, report the blocker, and ask the user.
-
-```bash
-cai branch update <ifElseNodeId> \
-  --route <defaultIfBranchId> \
-  --name "<meaning>" \
-  --js '<boolean expression>' \
-  --json
-```
-
-Add another condition only when the decision needs another non-Else case. Router routes are independent, so update an existing blank route or add each intended route explicitly:
-
-```bash
-cai branch add <controlNodeId> --name "<meaning>" --js '<boolean expression>' --json
-cai branch update <controlNodeId> --route <routeOrBranchId> --js '<boolean expression>' --json
-cai branch connect <controlNodeId> --route <routeOrBranchId> --to <targetNodeId> --flow <flowId> --json
-```
-
-For If/Else, order is behavior:
-
-```bash
-cai branch reorder <ifElseNodeId> --order <conditionId1,conditionId2> --json
-```
-
-List every condition branch exactly once and omit Else; the operation keeps Else last. Router routes cannot be reordered because every match runs. Do not simulate order by deleting a route or serializing its downstream nodes. Leave the fan-out unchanged unless the user explicitly authorizes a redesign.
-
-After edits, run `cai branch list` again. Treat its warnings about missing conditions or unwired paths as blockers: an unwired selected path can end with an apparently green execution.
-
-## Loops
-
-Never assemble the standard per-item subflow pattern by hand:
-
-```bash
-cai node get <listProducingNodeId> --json
-cai flow for-each \
-  --flow <parentFlowId> \
-  --from <listProducingNodeId> \
-  --source-output <exactOutputId> \
-  --name "<item flow name>" \
-  --item-type <text|number|date|boolean|custom.type> \
-  --json
-```
-
-Use repeatable `--item-field <id:type[:display]>` only when creating a new `custom.*` item type.
-
-Copy `--source-output` from the selected node's exact `outputs[].id`. It is an opaque ID, not `displayName`, and there is no first-output default. This matters for Router, If/Else, and error outputs as well as ordinary action nodes.
-
-- If the source's whole output is the list, omit both `--list-field` and `--list-js`.
-- If the list is nested in the source payload, use `--list-field` with the dot-delimited path below `.data`; the operation derives the not-yet-created loop input binding deterministically.
-- Use `--list-js` only for an advanced exact expression. For multiline or shell-sensitive source, use `--js-file <path|->` instead. Both are mutually exclusive with `--list-field` and with each other; copy the wrapper/binding shape from expression context rather than guessing it.
-
-MCP: pass expression source inline as `listJs` to `flow_for_each_scaffold`; the server cannot read a local `--js-file` path.
-
-- The runtime cap defaults to 500 items and accepts 1 through 10000. Set `--max-items` explicitly when the product requirement differs. The scaffold operation creates the core graph first, then materializes and verifies this optional prop. The cap is all-or-nothing at runtime: a list larger than the cap throws and NOTHING iterates — there is no partial truncation.
-
-Changing an existing loop: update its loop-node props directly:
-
-```bash
-cai node set <loopNodeId> --prop maxItems --value <n> --json
-cai node set <loopNodeId> --prop continueOnIterationError --value true --json
-```
-
-MCP: use `node_prop_set` for both writes.
-
-This is not `cai node continue-on-error`, which configures the node-level Error output — a different feature.
-
-Read every returned warning. A list/item type mismatch means the scaffold is not verified even though it was created. Follow the returned `nextSteps` in order.
-
-Inside loop mappings, `item` exists only where context exposes it. Inside the body flow, use its `flow.<itemInput>` binding. Downstream loop results are iteration records whose declared child outputs are under `.outputs`.
-
-Loops run sequentially. `--continue-on-error` applies to a failed child iteration; a list expression or mapping/config expression that fails before the child starts still aborts the loop. Test empty, one-item, several-item, over-limit, and intended iteration-error behavior.
-
-Never enable continue-on-error on a money path; charges, purchases, transfers, refunds, and other spend must fail fast.
-
-## Subflows and convergence
-
-Define the called flow's inputs and outputs first. Then initialize a Run flow component and bind it:
-
-```bash
-cai node set-flow <runFlowNodeId> --flow <calledFlowId> --json
-cai node props <runFlowNodeId> --json
-```
-
-MCP: `cai node set-flow` maps to `node_subflow_set`.
-
-Setting the target flow creates mapping props from the target's current inputs. If those inputs later change, run `set-flow` again and reconfigure mappings.
-
-For one action after whichever exclusive branch runs, use `registry_flow-merge` (Join Paths) in `chooseActivePath` mode, then place the shared action after it. Never wire several branches directly to an ordinary node or duplicate the shared action. Follow the exact recipe in [references/patterns.md](references/patterns.md) and test each branch once.
-
-Return semantics: a flow that should return data needs `registry_flow-return-response`; without it callers see empty success. Declare outputs first, initialize that exact component after the producer, then bind its generated prop with `cai expr set`. Do not guess component keys. See [references/patterns.md](references/patterns.md). Multiple completed Return nodes merge, with later values overwriting earlier ones; design for one Return per path unless merging is intended.
-
-Deleting a flow removes its graph, contract, triggers, and caller links. Validate and restore if mistaken. Turning `continueOnError` off also deletes its Error output and edges; validate and restore likewise.
-
-Read [references/patterns.md](references/patterns.md) for concise canonical patterns.
-
-## Before you finish
-
-```bash
-cai branch list <controlNodeId> --json
-cai workflow validate --json
-cai run flow <flowId> --inputs <values.json> --json
-cai exec tree <workflowExecutionId> --json
-```
-
-- Every branch has the intended condition and a wired target.
-- If/Else ordering matches priority and Else remains last.
-- Router fan-out is intentional when more than one condition can be true.
-- Loop item type and list expression compile against actual source data.
-- Expected true, false/Else, empty-list, one-item, several-item, over-limit, and error paths are tested.
-- The execution tree shows intended `only_when_false` or `upstream_skipped` reasons and no unexplained missing nodes.
+Examples and commands: [command reference](references/command-reference.md). Control-flow details: [patterns](references/patterns.md).

package/skills/controllerai-flow-control/references/command-reference.md

@@ -0,0 +1,171 @@
+# Controller AI flow control
+
+
+Choose by intended runtime semantics.
+
+
+- Guard the exact action with node `only-when`; see Conditions.
+- Use If/Else for one path and Router for all matches; see Pick the correct primitive.
+- Keep downstream wiring after node-only skip; see Conditions.
+- Never invent a missing condition or Router order; see If/Else and Router.
+- Build standard loops only with `flow for-each`; see Loops.
+- Converge paths through Join Paths; see Subflows and convergence.
+- Fail missing comparisons closed; keep money paths blocking. See Conditions, Loops, and the error pattern.
+- Never acknowledge validation errors without explicit approval; see `controllerai-workflows` Lifecycle rules.
+
+## Pick the correct primitive
+
+| Intent | Primitive | Semantics |
+| --- | --- | --- |
+| Skip one action when a condition is false | Node `only-when` | No alternate path |
+| Choose exactly one path | If/Else | First matching branch runs; Else is last |
+| Run every matching path | Router | Conditions are independent; multiple routes may run |
+| Apply work to every list item | `flow for-each` | Atomic loop scaffold with typed item flow |
+| Reuse a typed unit of work once | Run flow/subflow node | Explicit input and output contract |
+| Continue after an action error | Error output or continue-on-error | Error behavior is explicit and testable |
+
+Do not substitute one primitive merely because its component is easier to find.
+
+## Conditions
+
+Before writing any condition:
+
+```bash
+cai expr context <controlNodeId> --json
+cai expr validate <controlNodeId> --mode onlyWhen --js '<boolean expression>' --json
+```
+
+For one guarded action:
+
+```bash
+cai node only-when <nodeId> --js '<boolean expression>' --json
+```
+
+Use `--clear` only when the user's intent is to remove the guard.
+
+Guard the action that must skip. Do not substitute If/Else for a node-only skip. Its `only_when_false` does not block ordinary output; downstream remains eligible. Keep wiring. Guard downstream separately or branch if it must also skip.
+
+Node `only-when` takes one restricted boolean through `--js` or `--js-file`, or grouped conditions through `--groups-json '[["a","b"],["c"]]'` (inner arrays are AND, outer rows are OR). Root scalar `&&` or `||` inside one expression is unsupported; use `--groups-json` for compound guards. Grouped `string[][]` conditions exist only on branch add/update, with outer rows OR and inner entries AND. Use them only when branch semantics fit. If an exact compound node-only guard is required, report it as unsupported; do not weaken the rule or probe private APIs. For a missing number that must fail `< 5`, use a same-type boundary such as `(flow.unitsLeft ?? 5) < 5`.
+
+Choose the primitive by the runtime signal that callers and tests need. A false node `only-when` records `skipReason: "only_when_false"`; a node on an untaken If/Else branch or unmatched Router route records `skipReason: "upstream_skipped"`.
+
+## If/Else and Router
+
+Discover and initialize the appropriate control component using `controllerai-node-config`, then inspect its exact branch IDs:
+
+```bash
+cai branch list <controlNodeId> --json
+```
+
+A fresh If/Else already contains one blank `If` branch and an Else branch. The blank condition is a publish/runtime blocker: copy that default branch ID from `branch list` and update it before adding another condition branch. Do not leave the default blank and create a replacement beside it.
+
+Never invent a missing condition from node names, current values, or one observed run. If no authoritative platform surface supplies the business rule, leave the branch blank, report the blocker, and ask the user.
+
+```bash
+cai branch update <ifElseNodeId> \
+  --route <defaultIfBranchId> \
+  --name "<meaning>" \
+  --js '<boolean expression>' \
+  --json
+```
+
+Add another condition only when the decision needs another non-Else case. Router routes are independent, so update an existing blank route or add each intended route explicitly:
+
+```bash
+cai branch add <controlNodeId> --name "<meaning>" --js '<boolean expression>' --json
+cai branch update <controlNodeId> --route <routeOrBranchId> --js '<boolean expression>' --json
+cai branch connect <controlNodeId> --route <routeOrBranchId> --to <targetNodeId> --flow <flowId> --json
+```
+
+For If/Else, order is behavior:
+
+```bash
+cai branch reorder <ifElseNodeId> --order <conditionId1,conditionId2> --json
+```
+
+List every condition branch exactly once and omit Else; the operation keeps Else last. Router routes cannot be reordered because every match runs. Do not simulate order by deleting a route or serializing its downstream nodes. Leave the fan-out unchanged unless the user explicitly authorizes a redesign.
+
+After edits, run `cai branch list` again. Treat its warnings about missing conditions or unwired paths as blockers: an unwired selected path can end with an apparently green execution.
+
+## Loops
+
+Never assemble the standard per-item subflow pattern by hand:
+
+```bash
+cai node get <listProducingNodeId> --json
+cai flow for-each \
+  --flow <parentFlowId> \
+  --from <listProducingNodeId> \
+  --source-output <exactOutputId> \
+  --name "<item flow name>" \
+  --item-type <text|number|date|boolean|custom.type> \
+  --json
+```
+
+Use repeatable `--item-field <id:type[:display]>` only when creating a new `custom.*` item type.
+
+Copy `--source-output` from the selected node's exact `outputs[].id`. It is an opaque ID, not `displayName`, and there is no first-output default. This matters for Router, If/Else, and error outputs as well as ordinary action nodes.
+
+- If the source's whole output is the list, omit both `--list-field` and `--list-js`.
+- If the list is nested in the source payload, use `--list-field` with the dot-delimited path below `.data`; the operation derives the not-yet-created loop input binding deterministically.
+- Use `--list-js` only for an advanced exact expression. For multiline or shell-sensitive source, use `--js-file <path|->` instead. Both are mutually exclusive with `--list-field` and with each other; copy the wrapper/binding shape from expression context rather than guessing it.
+
+MCP: pass expression source inline as `listJs` to `flow_for_each_scaffold`; the server cannot read a local `--js-file` path.
+
+- The runtime cap defaults to 500 items and accepts 1 through 10000. Set `--max-items` explicitly when the product requirement differs. The scaffold operation creates the core graph first, then materializes and verifies this optional prop. The cap is all-or-nothing at runtime: a list larger than the cap throws and NOTHING iterates — there is no partial truncation.
+
+Changing an existing loop: update its loop-node props directly:
+
+```bash
+cai node set <loopNodeId> --prop maxItems --value <n> --json
+cai node set <loopNodeId> --prop continueOnIterationError --value true --json
+```
+
+MCP: use `node_prop_set` for both writes.
+
+This is not `cai node continue-on-error`, which configures the node-level Error output — a different feature.
+
+Read every returned warning. A list/item type mismatch means the scaffold is not verified even though it was created. Follow the returned `nextSteps` in order.
+
+Inside loop mappings, `item` exists only where context exposes it. Inside the body flow, use its `flow.<itemInput>` binding. Downstream loop results are iteration records whose declared child outputs are under `.outputs`.
+
+Loops run sequentially. `--continue-on-error` applies to a failed child iteration; a list expression or mapping/config expression that fails before the child starts still aborts the loop. Test empty, one-item, several-item, over-limit, and intended iteration-error behavior.
+
+Never enable continue-on-error on a money path; charges, purchases, transfers, refunds, and other spend must fail fast.
+
+## Subflows and convergence
+
+Define the called flow's inputs and outputs first. Then initialize a Run flow component and bind it:
+
+```bash
+cai node set-flow <runFlowNodeId> --flow <calledFlowId> --json
+cai node props <runFlowNodeId> --json
+```
+
+MCP: `cai node set-flow` maps to `node_subflow_set`.
+
+Setting the target flow creates mapping props from the target's current inputs. If those inputs later change, run `set-flow` again and reconfigure mappings.
+
+For one action after whichever exclusive branch runs, use `registry_flow-merge` (Join Paths) in `chooseActivePath` mode, then place the shared action after it. Never wire several branches directly to an ordinary node or duplicate the shared action. Follow the exact recipe in [patterns.md](patterns.md) and test each branch once.
+
+Return semantics: a flow that should return data needs `registry_flow-return-response`; without it callers see empty success. Declare outputs first, initialize that exact component after the producer, then bind its generated prop with `cai expr set`. Do not guess component keys. See [patterns.md](patterns.md). Multiple completed Return nodes merge, with later values overwriting earlier ones; design for one Return per path unless merging is intended.
+
+Deleting a flow removes its graph, contract, triggers, and caller links. Validate and restore if mistaken. Turning `continueOnError` off also deletes its Error output and edges; validate and restore likewise.
+
+Read [patterns.md](patterns.md) for concise canonical patterns.
+
+## Before you finish
+
+```bash
+cai branch list <controlNodeId> --json
+cai workflow validate --json
+cai run flow <flowId> --inputs <values.json> --json
+cai exec tree <workflowExecutionId> --json
+```
+
+- Every branch has the intended condition and a wired target.
+- If/Else ordering matches priority and Else remains last.
+- Router fan-out is intentional when more than one condition can be true.
+- Loop item type and list expression compile against actual source data.
+- Expected true, false/Else, empty-list, one-item, several-item, over-limit, and error paths are tested.
+- The execution tree shows intended `only_when_false` or `upstream_skipped` reasons and no unexplained missing nodes.