@controllerai/cli 0.2.20 → 0.2.22

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

@@ -1,6 +1,7 @@
+<!-- generated from .claude/skills by cli/scripts/render-skills.mjs; edit the source -->
 # Expression DSL and recipes
 
-The live compiler and `cai expr context`/`cai expr ops` are authoritative. These examples show structure, not names to copy blindly.
+The live compiler, `cai expr context` and `cai expr ops` are authoritative. These examples show structure; take every binding, field and operation name from the context.
 
 ## Text template
 
@@ -8,36 +9,25 @@ The live compiler and `cai expr context`/`cai expr ops` are authoritative. These
 `Hello ${flow.firstName.trim()}, order ${inputs.order.id} is ready`
 ```
 
-Use the exact bindings and fields returned for the destination node.
-
 ## Text prefix
 
-When `.startsWith()` is unavailable, test a prefix with:
+When `.startsWith()` is not advertised, test a prefix with a guarded split:
 
 ```js
 flow.subject.isNotEmpty() ? flow.subject.split("urgent")[0] === "" : false
 ```
 
-The typed conditional keeps empty text from matching. Replace the binding and prefix literal with exact values from context. Do not split on whitespace unless the requirement is first-word equality. Test punctuation immediately after the prefix, such as `urgent-alpha`, plus a near miss.
+The guard keeps empty text from matching. Prefix matching is not first-word matching: do not split on whitespace unless first-word equality is the requirement, and test a value with punctuation right after the prefix (`urgent-alpha`) plus a near miss.
 
 ## HTTP JSON body
 
-An HTTP node's JSON/body prop is stored as JSON text. The expression language does not support object literals or `JSON.stringify`. Build the document as a template and insert complete JSON tokens:
+A JSON body prop is JSON text. The language has no constructed object literals and no `JSON.stringify`, so build the document as a template of complete JSON tokens:
 
 ```js
 `{"message":${flow.name.jsonEncode()},"payload":${flow.user.stringify()}}`
 ```
 
-- Use `.jsonEncode()` for text or boolean values. It returns a JSON-safe token, including the quotes around text, so do not add another pair of quotes around `${...}`.
-- Use `.stringify()` for a custom object or list.
-- Keep JSON punctuation outside the interpolation and validate against the destination's exact prop before writing.
-
-```bash
-cai expr validate <httpNodeId> --prop <jsonBodyProp> --js-file body-expression.js --json
-cai expr set <httpNodeId> --prop <jsonBodyProp> --js-file body-expression.js --json
-```
-
-MCP: pass the file contents inline as `js`; the set call uses `node_prop_set`.
+`.jsonEncode()` returns a JSON-safe token: quoted for text, bare `true`/`false` for a boolean, so never add a second pair of quotes. `.stringify()` serializes a custom object or list. Keep the JSON punctuation outside the interpolations and validate against the exact body prop before writing.
 
 ## Same-type fallback
 
@@ -47,7 +37,7 @@ flow.label ?? "unknown"
 flow.enabled ?? false
 ```
 
-Fallbacks must be same-type literals. `0` and `false` remain real values.
+`0` and `false` are values; a fallback never replaces them.
 
 ## Boolean condition
 
@@ -56,7 +46,7 @@ flow.email.isNotEmpty()
 inputs.score >= 80
 ```
 
-Validate conditions with `--mode onlyWhen` and without a prop name.
+Validate a condition with `--mode onlyWhen` and no prop name.
 
 ## Dates
 
@@ -65,23 +55,23 @@ inputs.createdAt.toDate() > now.plusDays(-7)
 inputs.createdAt.toDate().format("YYYY-MM-DD")
 ```
 
-Convert text to a date before date math. Use negative amounts to move backward.
+Convert text to a date before date math; a negative amount moves backward. Use Moment format tokens, never JavaScript `Date` constructors or getters.
 
 ## Workflow records
 
-Filter immediately after `workflowData` so the engine can push supported predicates into storage:
+Filter immediately after `workflowData` so supported predicates are pushed into storage, then sort by an advertised field:
 
 ```js
 workflowData("custom.lead")
   .filter(row => row.status === "active")
-  .sortBy("created_at", "desc")
+  .sortBy("createdAt", "desc")
 ```
 
-The collection must exist on the current dev/live rail. A schema declaration alone does not guarantee active records.
+The collection must exist on the current rail; a schema declaration alone does not put rows in it. Record identity fields are `id`, `createdAt`, `updatedAt`.
 
 ## Optional filter inputs
 
-Filters are fail-closed by default: a missing right-hand value matches no records. Use optional matching only when the user's requirement explicitly allows an omitted constraint:
+An empty right-hand value is a real comparison: equality matches only empty fields, a negation or containment matches every row. Skip an omitted constraint only when the requirement allows it:
 
 ```js
 workflowData("custom.lead").filter(
@@ -90,45 +80,57 @@ workflowData("custom.lead").filter(
 )
 ```
 
-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.
+With the option on, null, empty text and an empty list skip the constraint; `0`, `false`, whitespace and dates remain real constraints. Test the supplied and the omitted case.
+
+## List membership
+
+For a list field such as tags, membership is a single element: `row.tags.includes(flow.tag)`. `filter`, `some`, `find` and `every` share the same predicate grammar; `map` projects fields rather than building objects.
+
+## Primitive lists
+
+A predicate compares a field of the item, so `flow.weights.filter(w => w >= flow.threshold)` is rejected, and `w.value` on a number compiles as a missing field whose constraint is dropped, matching every item. Aggregate a primitive list with the advertised list operations (`.sum()`, `.count()`, `.max()`), and classify or count its items with a per-item loop whose body returns a flag:
+
+```js
+inputs.runFlowOnList.filter(row => row.status === "completed").map(row => row.outputs).map(row => row.heavyFlag).sum()
+```
+
+`.map()` picks one field per call, so nested picks are chained; the `status` filter keeps failed iterations out of the total.
 
 ## Loop item
 
-Where context exposes `item`, primitive lists use the item directly:
+Where the context exposes `item`, a primitive list uses it directly:
 
 ```js
 item
 ```
 
-Object lists use an advertised field:
+An object list uses an advertised field:
 
 ```js
 item.email
 ```
 
-Inside the child flow, the item arrives through a flow input and is referenced as `flow.<name>`, not `item`.
+Inside the child flow the item arrives as a flow input and is `flow.<name>`, never `item`. A root routing node can read flow inputs directly; no producer node is needed to expose them.
 
 ## Loop output
 
-Run-on-list output is a list of iteration records. Child flow outputs live under `outputs`:
+Run-on-list output is a list of iteration records; child outputs sit under `outputs`:
 
 ```js
 inputs.enrichEach[0].outputs.score
 ```
 
-Confirm the exact binding and field path in context.
+Confirm the binding and the path in the context.
 
-## Troubleshooting sequence
+## Troubleshooting order
 
-1. `cai expr context <node> --prop <prop> --json`
-2. Confirm the intended source is wired and its `sourceNodeId` is correct.
-3. `cai expr validate ...`
-4. `cai expr set ...`
-5. `cai expr decompile ...`
-6. `cai run node ... --json` for isolated destination configuration
-7. `cai run flow <flowId> ... --json` when the expression consumes a wired upstream input
+1. `cai expr context <nodeId> --prop <propName> --json`
+2. Confirm the intended source is wired and its `sourceNodeId` is right.
+3. `cai expr validate <nodeId> --prop <propName> --js '<expression>' --json`
+4. `cai expr set <nodeId> --prop <propName> --js '<expression>' --json`
+5. `cai expr decompile <nodeId> --prop <propName> --json`
+6. `cai run node <nodeId> --inputs <values.json> --json` for the destination alone
+7. `cai run flow <flowId> --inputs <values.json> --json` when the expression consumes a wired input
 8. `cai exec node <nodeExecutionId> --full --json`
 
-MCP: step 4 uses `node_prop_set`; pass expression source and run inputs inline, and set `waitSeconds` on `run_node` or `run_flow` from 0 through 120.
-
-If compilation succeeds but runtime is null or partially empty, inspect `runScope`, the actual input value, and `resolvedConfigs`; do not keep rewriting syntax blindly. A node-only run cannot prove an `inputs.<name>` binding because it does not execute upstream nodes.
+If compilation succeeds but the runtime value is empty or partial, inspect `runScope`, the actual input value and `resolvedConfigs` before touching the syntax again. A node-only run cannot prove an `inputs.<name>` binding because it does not execute upstream nodes.

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

@@ -1,39 +1,122 @@
 ---
 name: controllerai-flow-control
-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.
+description: Design and configure Controller AI execution paths with only-when guards, If/Else branches, Router routes, for-each loops, subflows, Join Paths and error handling. Use when work must skip, branch, fan out, iterate over a list, call another flow, converge, return a value, or continue after a failure without changing the user's intended semantics.
 ---
+<!-- generated from .claude/skills by cli/scripts/render-skills.mjs; edit the source -->
 
-# Routing, loops and reusable flows
+# Flow control
 
-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.
+## Use this when
 
-## Choose the construct
+- A flow must skip an action, choose one path, run every matching path, repeat work per item, call another flow, converge exclusive paths, return a value, or continue after a failure.
+- A run shows an unexpected skip, a branch that never fires, an empty return, or a loop that stops early.
 
-- **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.
+Conditions are written with the expression discipline in `controllerai-expressions`; components are found and configured with `controllerai-node-config`; runs are read with `controllerai-runs`.
 
-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.
+## How it works
 
-## Build branches
+| Intent | Primitive | Runtime semantics |
+| --- | --- | --- |
+| Skip one action when a condition is false | node `only-when` | No alternate path; the node records `only_when_false`, downstream stays eligible |
+| Choose exactly one path | If/Else | The first matching branch runs; Else is the mandatory last fallback |
+| Run every matching path | Router | Conditions are independent; every matching route runs, possibly several |
+| Do work for every list item | `flow for-each` loop | A typed body flow runs once per item, sequentially, under an item cap |
+| Reuse a typed unit of work once | Run flow (subflow) | Explicit input and output mapping to another flow's contract |
+| Continue after a failed action | continue-on-error / Error output | The error is captured, downstream sees null for that node, the run ends `completed_with_error` |
+| One action after whichever exclusive path ran | Join Paths (`registry_flow-merge`) | `chooseActivePath` passes the single active input's value on; `passThrough` returns one field per connected input (blocked ones null) and suits fan-out that can overlap |
+| Give a flow its return value | Return response (`registry_flow-return-response`) | Maps producer values into the declared outputs; without it an otherwise successful flow returns empty outputs |
 
-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.
+Skip reasons are the evidence: a false guard records `only_when_false`; a node on an untaken branch or an unmatched route records `upstream_skipped`. Choose the primitive by the semantics the caller and the tests need, never because a component was 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.
+A fresh If/Else ships with one blank `If` branch and an Else; the blank condition is a validation blocker until it is set. Router routes cannot be reordered because every match runs. Loops run sequentially with a cap that defaults to 500 items (1 to 10000); a list over the cap fails before any iteration, never truncates. `continueOnIterationError` on a loop node continues past a failed child iteration and cannot help when the list or mapping expression fails before any child starts; node-level continue-on-error on the loop node lets the parent flow continue past that failed loop with a null output, but repairs nothing and resumes no iteration. With `chooseActivePath`, zero active inputs stop the flow at the join unless `continueIfNoActivePath` is enabled, which passes null on. Setting a subflow's target synthesizes mapping props from the target's current inputs; when those inputs change, set the target again and remap. Deleting a flow removes its graph, contract, triggers and caller links; turning continue-on-error off deletes the node's Error output and its edges.
 
-## Build loops
+## Rules
 
-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.
+1. **Guard the action that must skip with `only-when`; do not replace a node skip with If/Else.** A false guard does not stop downstream execution (the skipped node just yields no value), so guard downstream separately or branch when it must skip too.
+2. **Never invent a missing condition** from names, sample values or one observed run. Leave the branch blank, report the blocker and ask; a missing business rule is not yours to guess.
+3. **Update the blank default If branch before adding another branch.** Adding beside it leaves a blocker and a duplicate.
+4. **Order is behavior only for If/Else.** Put the most specific condition first, never write a complement condition for Else, and never simulate Router order by deleting routes or chaining descendants; leave a fan-out unchanged unless the user authorizes a redesign.
+5. **Build per-item work with `flow for-each`**, never by hand-assembling the injection and mapping pattern. Put the real work in the generated body flow and declare its outputs before consuming aggregate results. Continue past failed iterations only when partial completion is acceptable and the downstream logic handles failed iteration records.
+6. **Compound guards are supported**: a node guard takes one boolean expression or grouped conditions (inner list AND, outer list OR); a root `&&` or `||` inside one expression is not. Never weaken a rule to fit the grammar, and never probe a private API.
+7. **Fail missing comparisons closed** with a same-type boundary (`(flow.unitsLeft ?? 5) < 5`), and keep money paths blocking: charges, purchases, transfers and refunds never continue on error, and never enable continue-on-error just to make a run green.
+8. **Converge exclusive paths through Join Paths**; never wire several branches straight into an ordinary node and never duplicate the shared action.
+9. **A flow that returns data needs a Return response node** bound to declared outputs. Every Return writes every declared output, unbound ones as null, and a later Return (in execution order) overwrites an earlier one, so a partial Return can erase a value; design one Return per path unless merging is intended.
+10. **Read the branch list after every edit.** Warnings about missing conditions or unwired paths are blockers even when a run looks green.
 
-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.
+## Recipes
 
-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.
+### Guard one action
 
-## Verify paths
+```bash
+cai expr context <nodeId> --json
+cai expr validate <nodeId> --mode onlyWhen --js '<boolean expression>' --json
+cai node only-when <nodeId> --js '<boolean expression>' --json
+cai node only-when <nodeId> --groups-json '[["flow.email.isNotEmpty()","flow.units < 5"],["flow.override === true"]]' --json
+```
 
-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.
+Use `--clear` only when removing the guard is the user's intent.
 
-Examples and commands: [command reference](references/command-reference.md). Control-flow details: [patterns](references/patterns.md).
+### If/Else and Router
+
+```bash
+cai branch list <controlNodeId> --json
+cai branch update <controlNodeId> --route <defaultIfBranchId> --name "<meaning>" --js '<boolean expression>' --json
+cai branch add <controlNodeId> --name "<meaning>" --js '<boolean expression>' --json
+cai branch update <controlNodeId> --route <routeId> --condition-json '[["flow.email.isNotEmpty()","flow.units < 5"],["flow.override === true"]]' --json
+cai branch connect <controlNodeId> --route <routeId> --to <targetNodeId> --flow <flowId> --json
+cai branch reorder <ifElseNodeId> --order <conditionId1,conditionId2> --json
+```
+
+Find the control component with `controllerai-node-config`, then read the branch IDs. Grouped conditions are OR of AND rows, each string compiled separately. Add an If branch only for another non-Else case; add a Router route for each intended independent match. Reorder lists every condition branch exactly once and omits Else, which stays last. Wire every returned route ID explicitly.
+
+### Loop over a list
+
+```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> --max-items <n> --json
+cai node set <loopNodeId> --prop maxItems --value <n> --json
+cai node set <loopNodeId> --prop continueOnIterationError --value true --json
+```
+
+`--source-output` is the exact `outputs[].id` of the selected node, never a display name, and there is no first-output default (branch and error outputs included). When the whole output is the list, omit the list selectors; for a nested list use `--list-field` with the dot path below `.data`; reserve `--list-js` for an exact advanced expression whose shape you took from the context; the selection forms are mutually exclusive. `--item-field <id:type[:display]>` (repeatable) is only for creating a new `custom.*` item type; stored records use `dataRecord.custom.*`. Set the cap on purpose when the requirement differs from 500, decide `--continue-on-error` explicitly, then read the returned warnings and follow `nextSteps` in order; a list/item type mismatch means created but unverified. In mappings, `item` exists only where the context exposes it; inside the body flow the item is `flow.<itemInput>`; aggregate results are iteration records with child outputs under `outputs`.
+
+For multiline or shell-sensitive list source, pass `--js-file <path|->` instead of `--list-js`.
+
+### Call another flow
+
+```bash
+cai node set-flow <runFlowNodeId> --flow <calledFlowId> --json
+cai node props <runFlowNodeId> --json
+```
+
+Define the called flow's inputs and outputs first, add the Run flow component, set the target, then bind the generated mapping props with expressions.
+
+### Converge, return, handle errors
+
+```bash
+cai node add --flow <flowId> --node registry_flow --key registry_flow-merge --name "Join paths" --json
+cai node set <joinNodeId> --prop mode --value chooseActivePath --json
+cai flow output add <bodyFlowId> --display "<output label>" --name <output_key> --type <type> --json
+cai node add --flow <bodyFlowId> --node registry_flow --key registry_flow-return-response --name "Return <value>" --after <producerNodeId> --json
+cai node continue-on-error <nodeId> --enable --json
+cai node connect --flow <flowId> --from <nodeId> --to <handlerNodeId> --output error --json
+```
+
+Join Paths: connect every type-compatible branch tail to it (all connected input types are checked, inactive paths included, which is why `pathDataType` is asked for once `chooseActivePath` reveals it), set `pathDataType` from the returned options, and place the shared action after it (`--after <joinNodeId>`, or connect the existing action). Return: declare the output first so its generated prop exists, add the exact component after the producer, then bind the prop through the expression setter. Error output wiring is optional; add it only when a failure needs explicit handling.
+
+## Verify
+
+```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 its intended condition and a wired target; If/Else order matches priority with Else last; Router fan-out is intentional where more than one condition can be true; the loop's item type and list expression compile against real data; the paths the task implies ran: true, false or Else, empty list, one item, several, over the cap, and the intended error path; the execution tree explains every `only_when_false` and `upstream_skipped` and shows no unexplained missing node; a loop's outer success is not proof for every item, so inspect iteration records and surface individual failures.
+
+## Report
+
+Which primitive carries each decision and why, the tested paths with their outcomes, any rule you could not set because the business rule was missing, and any error-continuation you enabled and where.
+
+Read [references/patterns.md](references/patterns.md) for the canonical shapes: guard, exclusive decision, fan-out, grouped conditions, per-item subflow, convergence, return, error path.

package/skills/controllerai-flow-control/references/patterns.md

@@ -1,18 +1,19 @@
+<!-- generated from .claude/skills by cli/scripts/render-skills.mjs; edit the source -->
 # Flow-control patterns
 
 ## Guard a side effect
 
-Use `only-when` when false should mean "skip this action" and nothing else:
+`only-when` means "skip this action, nothing else":
 
 ```text
 Read record -> Send notification [only when status changed]
 ```
 
-Test both true and false. A false run should show an intentional skip reason.
+Test true and false; the false run shows `only_when_false` on that node and downstream stays eligible.
 
 ## Exclusive decision
 
-Use If/Else when only one outcome must occur:
+If/Else when exactly one outcome must occur:
 
 ```text
 Score -> If/Else
@@ -21,11 +22,11 @@ Score -> If/Else
            Else          -> Record unknown
 ```
 
-Put the most specific/highest-priority conditions first. Never write a complement condition for Else.
+Most specific condition first; Else is the fallback and never gets a complement condition.
 
 ## Independent fan-out
 
-Use Router when every applicable action should run:
+Router when every applicable action should run:
 
 ```text
 New order -> Router
@@ -36,95 +37,57 @@ New order -> Router
 
 One order may take all three routes. If that is not acceptable, use If/Else.
 
-## Grouped branch condition
+## Grouped conditions
 
-Only Router and If/Else branch commands accept grouped conditions. The outer rows are OR and the expressions within one row are AND:
+Outer rows are OR, entries within a row are AND, and each string compiles on its own:
 
 ```bash
-cai branch update <controlNodeId> \
-  --route <routeId> \
-  --condition-json '[["flow.email.isNotEmpty()","flow.units < 5"],["flow.override === true"]]' \
-  --json
+cai node only-when <nodeId> --groups-json '[["flow.email.isNotEmpty()","flow.units < 5"],["flow.override === true"]]' --json
+cai branch update <controlNodeId> --route <routeId> --condition-json '[["flow.email.isNotEmpty()","flow.units < 5"],["flow.override === true"]]' --json
 ```
 
-Each string must compile independently. Node `only-when` has no `--condition-json`; if exact compound node-only semantics are required, report the limitation instead of using a private API or weakening the guard.
-
 ## Per-item subflow
 
-Use `cai flow for-each` to create the item flow, typed item input, loop node, and list wiring atomically. First run `cai node get <sourceNodeId> --json`, choose the intended `outputs[]` entry, and pass its exact opaque `id` as `--source-output`; never pass its label or assume the first output. Omit list-selection flags when the whole selected output payload is a list; use `--list-field <nested.path>` for a list below `.data`; reserve `--list-js` for an exact advanced expression or `--js-file <path|->` for that expression in a UTF-8 file/stdin. The three selection forms are mutually exclusive.
-
-MCP: call `flow_for_each_scaffold` and pass expression source inline as `listJs`.
-
-The runtime limit defaults to 500 items and supports 1 through 10000. Use `--max-items` when the intended bound differs, then verify the returned read-back. Put meaningful work inside the generated body flow and declare body outputs before consuming aggregate results.
+```bash
+cai node get <sourceNodeId> --json
+cai flow for-each --flow <parentFlowId> --from <sourceNodeId> --source-output <exactOutputId> --name "<item flow name>" --item-type <type> --json
+```
 
-Decide explicitly whether one child-flow failure should stop the sequential loop. Use `--continue-on-error` only when partial completion is acceptable and downstream logic handles failed iteration records. It does not recover a list or mapping expression that fails before an iteration starts.
+The scaffold creates the item flow, its typed item input, the loop node and the list wiring in one operation, then materializes the optional cap; a failure setting the cap does not roll the scaffold back. The body receives one item, not the whole list; a custom-shaped item and a stored record (`dataRecord.custom.*`) are different types. Continue past a failed iteration (`--continue-on-error`) only when partial completion is acceptable and the downstream logic handles failed iteration records (null outputs with a status and an error); it cannot rescue a list or mapping expression that fails before the child starts.
 
 ## Converge exclusive paths
 
-Initialize Join Paths and select its active-path mode:
-
 ```bash
-cai node init \
-  --flow <flowId> \
-  --node registry_flow \
-  --key registry_flow-merge \
-  --name "Join paths" \
-  --json
+cai node add --flow <flowId> --node registry_flow --key registry_flow-merge --name "Join paths" --json
 cai node set <joinNodeId> --prop mode --value chooseActivePath --json
 cai node props <joinNodeId> --json
-# If returned props require it:
 cai node set <joinNodeId> --prop pathDataType --value <returnedTypeValue> --json
 cai node connect --flow <flowId> --from <firstBranchTailNodeId> --to <joinNodeId> --json
 cai node connect --flow <flowId> --from <secondBranchTailNodeId> --to <joinNodeId> --json
-cai node init \
-  --flow <flowId> \
-  --node <sharedNodeSlug> \
-  --key <sharedNodeKey> \
-  --name "<shared action>" \
-  --after <joinNodeId> \
-  --json
+cai node add --flow <flowId> --node <sharedNodeSlug> --key <sharedNodeKey> --name "<shared action>" --after <joinNodeId> --json
 ```
 
-Set `pathDataType` only when returned props require it, using an exact returned option. Repeat the branch-tail connection for every type-compatible exclusive path. If the shared action already exists, connect it after Join Paths instead of initializing a replacement. Do not connect several branches directly to an ordinary node or duplicate the action. `chooseActivePath` requires at most one active input, so do not use it after a Router whose routes can overlap. Run one test per branch and stop after all pass.
+Set `pathDataType` from the returned options once `chooseActivePath` reveals it. Repeat the tail connection for every type-compatible exclusive path; if the shared action already exists, connect it after Join Paths instead of adding a replacement. `chooseActivePath` allows at most one active input and stops the flow when none is active unless `continueIfNoActivePath` is enabled (then it passes null); after a Router whose routes can overlap use `passThrough`, which returns one field per connected input with the blocked ones null. Run one test per branch and stop after all pass.
 
 ## Return a flow value
 
-Declare the output before the Return response node so its generated prop exists:
-
 ```bash
-cai flow output add <bodyFlowId> \
-  --display "<output label>" \
-  --name <output_key> \
-  --type <type> \
-  --json
-cai node init \
-  --flow <bodyFlowId> \
-  --node registry_flow \
-  --key registry_flow-return-response \
-  --name "Return <value>" \
-  --after <producerNodeId> \
-  --json
+cai flow output add <bodyFlowId> --display "<output label>" --name <output_key> --type <type> --json
+cai node add --flow <bodyFlowId> --node registry_flow --key registry_flow-return-response --name "Return <value>" --after <producerNodeId> --json
 cai node props <returnNodeId> --json
 cai expr context <returnNodeId> --prop <generatedOutputProp> --json
 cai expr set <returnNodeId> --prop <generatedOutputProp> --js '<producer binding>' --json
 ```
 
-Do not guess `registry_flow-return` or `registry_flow-response`. Run the body flow and verify its top-level output contains the promised value.
+Declare the output before adding the Return node so its generated prop exists. Do not guess `registry_flow-return` or `registry_flow-response`. Run the body flow and check the promised top-level output. Populate the outputs on every intended return path, including the "nothing found" path, which should return a clear result without performing writes.
 
 ## Error path
 
-Continue-on-error is for steps whose failure must not block the main path — notifications, logging, optional enrichment. Enabling it captures the node's error, downstream nodes still execute (receiving null for the failed node's output), and the run ends `completed_with_error`:
+Continue-on-error suits steps whose failure must not block the main path: notifications, logging, optional enrichment. The node's error is captured, downstream nodes run with null for its output, and the run ends `completed_with_error`.
 
 ```bash
 cai node continue-on-error <nodeId> --enable --json
-```
-
-MCP: call `node_continue_on_error_set` with `enabled: true` or `enabled: false`.
-
-Wiring the Error output is OPTIONAL — add it when a failure needs explicit handling, not as a precondition:
-
-```bash
 cai node connect --flow <flowId> --from <nodeId> --to <handlerNodeId> --output error --json
 ```
 
-Never enable continue-on-error on critical-path steps (validate → charge → confirm must fail fast), and never merely to make the parent execution green. Read back the setting after changing it.
+Wiring the Error output is optional. Never enable continue-on-error on a critical path (validate, charge, confirm must fail fast) and never to make a parent run green. Read the setting back after changing it.

package/skills/controllerai-integration-actions/SKILL.md

@@ -1,24 +1,102 @@
 ---
 name: controllerai-integration-actions
-description: Discover and attach ready integration actions directly to Controller AI agents, configure connections and dynamic properties, and verify external app operations. Use when one existing action satisfies an agent capability.
+description: Discover, connect, attach, update and verify ready integration actions that a Controller AI agent calls directly. Use when an agent needs one existing app operation without a workflow, when choosing between a direct action and a workflow tool, or when changing an action's connection or per-run approval policy.
 ---
+<!-- generated from .claude/skills by cli/scripts/render-skills.mjs; edit the source -->
 
-# Ready actions as agent tools
+# Integration actions
 
-A ready integration action is one existing operation: search a service, read an object, create a record or send a message. Attach it directly to an agent when that operation is the capability. Use a workflow tool when you also need deterministic validation, multiple ordered steps, transformation, persistence or a reusable typed contract.
+## Use this when
 
-## Discover and configure
+- An agent needs one existing app operation: send one message, create one record, add one row, look something up.
+- You must decide between attaching a ready action and building a workflow tool.
+- An attached action needs another connection, a different approval policy, or proof that it runs.
 
-Search by the intended operation, inspect the matching integration, then read its exact action key and properties. Prefer capability evidence over a similar integration name. Native actions and external provider actions can have different authorization requirements.
+Building the agent itself belongs to `controllerai-agents`; a workflow node for the same app belongs to `controllerai-node-config`.
 
-Select an existing matching connection and verify its identity. If a new connection is needed, return the connection URL and let the user complete provider authorization. Never request provider credentials in chat. An “active” stored connection still needs a representative action test to prove current authorization.
+## How it works
 
-Attach the action with its exact integration/action/connection and a description that tells the agent when to use it. Inspect configurable inputs and reload dependent options after selector changes. Choose the tool's runtime confirmation setting for the requested experience.
+**A ready action is one operation.** The catalog exposes provider integration actions and native registry actions that an agent can call directly, without a workflow; a native action is attachable when the catalog marks it `agentAttachable`. Most native actions need no connection: they run on the platform's paid rails, bill the user's usage balance per call, and describe the charge in `usagePricingDescription`. A native action that does need authorization uses the platform connection flow, not Pipedream. Use a workflow tool instead when the capability needs several operations, transformation, branching, loops, durable state, a trigger, a custom typed contract, or reuse outside the agent. Never wrap a ready action whose contract already fits in a one-node workflow, and never replace deterministic orchestration with several independent direct actions.
 
-## Verify the attached capability
+**Identity is a pair.** An action is the exact integration slug plus its action key, as returned by discovery; a display label is not an identity, and a similar integration with a familiar name is not evidence of the capability. When the catalog says the action needs a connection, it binds to one whose `integration` matches that slug exactly.
 
-Read the saved tool list and test in a draft conversation. Inspect the chosen action, arguments, terminal result and intended external effect. A direct action does not create a workflow execution. For a failed or uncertain mutation, inspect external state before repeating it.
+**Runtime.** The agent runtime configures the action's dynamic arguments when it invokes the action; nothing is preconfigured at attachment beyond identity, any required connection, description and approval policy. A direct action runs inline in the conversation and creates no workflow execution: the evidence is the persisted conversation, its action events with arguments and result, and the external effect.
 
-Connection rebinding, detachment or revocation can affect Live independently of publishing the agent. If the user requested release, publish the updated agent configuration after testing and verify a Live conversation. Do not publish merely because the draft is ready.
+**Approval policy.** An attached action runs without a human approval step unless `requireConfirmation` is `true`; the default is no approval. When confirmation is on, the runtime pauses with a pending request that the user approves or denies with the exact arguments visible.
 
-Discovery, attachment, update and removal commands: [reference](references/command-reference.md).
+**Slack approvals.** Approval requests can also go to Slack with `--slack-connection <connectionId>` and `--slack-channel <channelId>`. Routes are draft tool settings published with the agent like approval settings. Test conversations use the draft; live ones use the published version. Only the connection owner and configured approvers can answer in Slack; the app's approval card still works.
+
+**Live bindings.** Publishing snapshots the action identity, description and approval policy into the agent version. When an action needs a connection, that connection and its authorization grant are live security bindings: rebinding redirects the published action immediately, and revocation, breakage or detachment stops it immediately without an agent publish. Detachment has the same immediate effect on a connectionless action, always removes the draft tool, and a later publish removes it from the published list. Confirmation is strictest-wins: tightening the grant to require confirmation blocks the published action at once until a publish carries the new policy, while relaxing it waits for the publish. Organization members use the published agent, never the draft; connected actions run through the owner's connected account and the organization's shared usage pool, while connectionless native actions use the platform's paid rails and bill that pool whoever invokes them.
+
+## Rules
+
+1. **Capture and reuse the exact identities**: integration slug, action key, connection ID when required, tool ID. Narrow the query or raise the result limit when more matches exist; never derive an identifier from a label.
+2. **A required missing connection is a handoff, not a substitution.** Keep the selected integration and action, give the user the platform authorization route, and stop the attachment there; never request provider credentials in chat. Never swap in `registry_http-http-request`: the HTTP node is never agent-attachable, so that substitution is impossible by construction. A raw endpoint the user mentions is context, not an instruction to hand-roll the call.
+3. **Decide the approval policy before attaching.** For an action that sends, posts, spends or deletes, choose `true` or explicitly tell the user it will run unattended; prefer confirmation for permission changes, irreversible writes or an ambiguous destination, and omit it for reads and low-risk reversible operations the user asked to run autonomously. Mention the confirmation choice in the report to the user.
+4. **Attach once.** Read the tool list before and after; the final list holds one intended direct attachment.
+5. **A stored active connection is not proof of authorization.** For an action that needs one, only a representative action test proves the provider still accepts it.
+6. **Verify what the request asked for, where it lives.** Discovery proves metadata; a blocked attachment proves the honest handoff and the independent work; an attachment proves the saved grant; only an authorized runtime test proves the external effect, and for that the action event, its arguments and result, and the external state are the evidence, never a reply that says it ran. Inspect the external state before repeating a failed or uncertain mutation.
+7. **Say whose account and balance run the action** before organization sharing: connected actions use the owner's account; connectionless native actions use the platform's paid rails; calls use the organization's shared usage balance regardless of caller.
+
+## Recipes
+
+### Discover
+
+```bash
+cai integration search "<app or capability>" --agent-attachable --json
+cai integration actions "<operation>" --integration <integrationSlug> --agent-attachable --json
+cai integration action --integration <integrationSlug> --key <actionKey> --json
+```
+
+`search` ranks integrations (`--actions` or `--events` narrows the kind); `actions` ranks actions across one or all integrations; `--agent-attachable` keeps results with attachable actions; `action` returns the static metadata and props of one exact action. Read `agentAttachable`, the exact props and, for native actions, whether a connection is needed and `usagePricingDescription` before choosing.
+
+### Select or request a connection
+
+```bash
+cai connection list --integration <integrationSlug> --json
+```
+
+Skip this step when the catalog says the native action needs no connection.
+
+Use the active connection whose `integration` matches exactly. If none exists, `cai connection connect <integrationSlug> --no-open` returns the authorization URL: share it right away, and after the user finishes, list again and use the new ID.
+
+### Attach
+
+```bash
+cai agent add-action <agentId> --integration <integrationSlug> --action <actionKey> --connection <connectionId> --description "Use when ..." --require-confirmation --json
+cai agent add-action <agentId> --integration <integrationSlug> --action <actionKey> --description "Use when ..." --require-confirmation --json
+cai agent tools <agentId> --json
+```
+
+`--connection` is required exactly when the catalog says the action needs one and must be omitted otherwise. `--require-confirmation` sets the policy to `true`; omitting it keeps the `false` default.
+The description tells the agent when to choose the tool. Read the saved grant back: `toolType`, integration, action key, any required connection, description and confirmation policy.
+
+### Update
+
+```bash
+cai agent update-tool <agentId> --tool <toolId> --connection <connectionId> --json
+cai agent update-tool <agentId> --tool <toolId> --require-confirmation --json
+cai agent update-tool <agentId> --tool <toolId> --no-confirmation --json
+cai agent update-tool <agentId> --tool <toolId> --description "<when to use it>" --json
+```
+
+A connection change redirects a connected published action at once. A description change waits for the agent publish. A policy change is strictest-wins: turning confirmation on blocks the published action immediately until the next publish carries it, turning it off takes effect only at that publish.
+
+### Verify in a draft conversation
+
+```bash
+cai agent test <agentId> --draft --message "<request that needs the action>" --json
+cai agent conversation history <conversationId> --json
+cai agent conversation approve <conversationId> --request <requestId> --json
+cai agent conversation deny <conversationId> --request <requestId> --message "<reason>" --json
+```
+
+`agent test` is a one-shot that opens a new conversation; when a follow-up or an approval is expected, create one draft conversation and send into it as in `controllerai-agents`. When confirmation is on, inspect the pending action and its exact arguments, then approve or deny in that same conversation and read the history for the terminal result. Direct actions do not create workflow execution IDs: never invent one.
+
+## Verify
+
+For an attachment, the tool list shows exactly one intended direct attachment with the exact identities, any required connection, description and confirmation policy; for an authorized runtime test, the draft conversation history holds the action event, its arguments and its result, and the external effect was checked separately; for discovery alone, the exact metadata was read and nothing was changed. No wrapper workflow exists unless orchestration or reuse required it.
+
+## Report
+
+Which action is attached to which agent, any connection and the confirmation choice, what the draft test proved, whose account or paid rail and usage balance the action will use, and what remains: a connection to authorize, a publish, or a live verification.