@controllerai/cli 0.2.18 → 0.2.21

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

@@ -1,167 +1,110 @@
 ---
 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: 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 -->
 
-# Controller AI flow control
+# Flow control
 
-The `cai ...` examples are canonical grammar. Use the transport selected in `controllerai-start` and its MCP tool map; never mix transports in one task.
+## Use this when
 
-Choose by intended runtime semantics.
+- 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.
 
-## Rules that break tasks when skipped
+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`.
 
-- 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.
+## How it works
 
-## Pick the correct primitive
-
-| Intent | Primitive | Semantics |
+| Intent | Primitive | Runtime 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 |
+| 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 |
 
-Do not substitute one primitive merely because its component is easier to find.
+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.
 
-## Conditions
+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.
 
-Before writing any condition:
+## Rules
 
-```bash
-cai expr context <controlNodeId> --json
-cai expr validate <controlNodeId> --mode onlyWhen --js '<boolean expression>' --json
-```
+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.
 
-For one guarded action:
+## Recipes
+
+### Guard one action
 
 ```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
 ```
 
-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`.
+Use `--clear` only when removing the guard is the user's intent.
 
-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:
+### If/Else and Router
 
 ```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 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 <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 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
 ```
 
-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.
+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.
 
-## Loops
-
-Never assemble the standard per-item subflow pattern by hand:
+### 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> \
-  --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 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
 ```
 
-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.
+`--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`.
 
-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.
+For multiline or shell-sensitive list source, pass `--js-file <path|->` instead of `--list-js`.
 
-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:
+### Call another flow
 
 ```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.
+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.
 
-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.
+### Converge, return, handle errors
 
-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.
+```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
+```
 
-Read [references/patterns.md](references/patterns.md) for concise canonical patterns.
+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.
 
-## Before you finish
+## Verify
 
 ```bash
 cai branch list <controlNodeId> --json
@@ -170,9 +113,10 @@ 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.
+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,125 +1,97 @@
 ---
 name: controllerai-integration-actions
-description: Discover, connect, attach, update, and verify ready integration actions used directly by Controller AI agents. 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.
+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 -->
 
-# Controller AI integration actions
+# Integration actions
 
-The `cai ...` examples are canonical grammar. Use the transport selected in `controllerai-start` and its MCP tool map; never mix transports in one task.
+## Use this when
 
-Ready integration actions give a hosted agent one app operation without first building a workflow. Use the canonical operations below through the selected transport; do not call Controller AI REST routes directly.
+- 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.
 
-## Rules that break tasks when skipped
+Building the agent itself belongs to `controllerai-agents`; a workflow node for the same app belongs to `controllerai-node-config`.
 
-- Attach one existing app operation directly; never wrap it in a one-node workflow. See Choose direct action or workflow.
-- Capture the exact integration, action, connection, and tool IDs. See Discover exact identities.
-- Decide confirmation before attachment, especially for writes or spend. See Decide approval before attaching.
-- Verify persisted direct-action events, not a workflow execution ID. See Verify through the hosted agent.
+## How it works
 
-## Choose direct action or workflow
+**A ready action is one operation.** The catalog exposes provider integration actions that an agent can call directly, without a workflow; native registry actions appear in the same discovery but are not attachable as direct actions, and every direct attachment needs a connection, so native and provider operations carry different authorization requirements. 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.
 
-Use a direct action for one existing operation such as sending one message, creating one record, or adding one row.
+**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. The action binds to a connection whose `integration` matches that slug exactly.
 
-Use a workflow tool instead when the capability needs multiple operations, transformations, branches, loops, durable state, triggers, a custom typed contract, or reuse outside the agent. Do not build a one-node workflow when the same ready action already fits.
+**Runtime.** The agent runtime configures the action's dynamic arguments when it invokes the action; nothing is preconfigured at attachment beyond identity, 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.
 
-## Discover exact identities
+**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.
 
-```bash
-cai integration search "<app or capability>" --json
-cai integration actions "<operation>" --integration <integrationSlug> --json
-cai integration action --integration <integrationSlug> --key <actionKey> --json
-```
+**Live bindings.** Publishing snapshots the action identity, description and approval policy into the agent version. The 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 also 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; direct actions run through the owner's connected account and the organization's shared usage pool whoever calls them.
 
-Preserve each returned `nodeSlug` and `key` pair exactly, then inspect that action's static props before using it. Never derive either identifier from a display label. Narrow the query or raise `--limit` when more matches exist.
+## Rules
 
-## Select a connection
+1. **Capture and reuse the exact identities**: integration slug, action key, connection ID, tool ID. Narrow the query or raise the result limit when more matches exist; never derive an identifier from a label.
+2. **A missing connection is a handoff, not a substitution.** Keep the selected integration and action, give the user the authorization route, and stop the attachment there; never swap in `registry_http-http-request` or request provider credentials in chat. 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.** 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 runs the action** before organization sharing: the owner's connection and the organization's usage pool, regardless of caller.
 
-```bash
-cai connection list --integration <integrationSlug> --json
-```
+## Recipes
 
-Use an active connection whose `integration` exactly matches the integration slug. If none exists:
+### Discover
 
 ```bash
-cai connection connect <integrationSlug>
+cai integration search "<app or capability>" --json
+cai integration actions "<operation>" --integration <integrationSlug> --json
+cai integration action --integration <integrationSlug> --key <actionKey> --json
 ```
 
-MCP: call `connection_connect_url`, show its `url` as a markdown link, ask the user to finish, then confirm with `connection_list` using its `integration`; it has no `open` or `wait` parameter.
-
-The connection handoff keeps provider credentials out of the agent context. The CLI may open the URL; MCP returns it. Re-list connections after the user finishes, then attach the action.
-
-Rename or change the default with `cai connection update <id> [--name "<displayName>"] [--default|--no-default]` (MCP: `connection_update`); delete only intentionally with `cai connection delete <id> --yes` (MCP: `connection_delete`).
-Deleting a connection immediately removes authorization from bound nodes and agent tools.
-
-A missing connection is never a reason to substitute `registry_http-http-request` for a catalog component. For a workflow node, add the real component and leave it unconnected; `missingConnection: true` is a valid handoff state. For a direct action, preserve the selected integration and action and stop at the connection handoff. Give the user the returned connection URL; on CLI, `cai connection connect <slug>` obtains it. A raw endpoint mentioned by the user is background context, not an instruction to hand-roll the call.
+`search` ranks integrations (`--actions` or `--events` narrows the kind); `actions` ranks actions across one or all integrations; `action` returns the static metadata and props of one exact action. Read that metadata before choosing.
 
-## Decide approval before attaching
-
-Attached actions run without a human approval step unless `requireConfirmation` is `true`. When attaching an action that sends, posts, spends, or deletes, choose `true` or explicitly tell the user that it will run unattended. Mention the confirmation choice in the report to the user.
-
-- Prefer confirmation for permission changes, irreversible writes, or an ambiguous destination.
-- Usually omit confirmation for read-only retrieval and low-risk, reversible operations the user clearly asked the agent to perform autonomously.
+### Select or request a connection
 
 ```bash
-cai agent add-action <agentId> \
-  --integration <integrationSlug> \
-  --action <actionKey> \
-  --connection <connectionId> \
-  --description "Use when ..." \
-  --require-confirmation \
-  --json
+cai connection list --integration <integrationSlug> --json
 ```
 
-MCP: call `agent_tool_action_add`; `requireConfirmation` is optional and defaults to `false`. On CLI, `--require-confirmation` selects `true` and omission preserves the `false` default. Do not attach the same action twice.
+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.
 
-Read the saved grant back:
+### Attach
 
 ```bash
+cai agent add-action <agentId> --integration <integrationSlug> --action <actionKey> --connection <connectionId> --description "Use when ..." --require-confirmation --json
 cai agent tools <agentId> --json
 ```
 
-Verify `toolType`, integration, action key, connection, schema tier, description, and confirmation policy. The hosted runtime configures dynamic action properties when it invokes the action; the builder does not preconfigure runtime-only action arguments here.
+`--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, connection, description and confirmation policy.
 
-To rebind the live authorization grant or change a versioned 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
 ```
 
-MCP: call `agent_tool_update`; use `connectionId` and `requireConfirmation: true` or `requireConfirmation: false`.
-
-`--connection` can redirect the published action immediately because authorization is live-bound. Description and confirmation-policy edits remain draft changes until the agent is published.
+A connection change redirects the 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 through the hosted agent
-
-Use a representative draft conversation:
+### Verify in a draft conversation
 
 ```bash
-cai agent test <agentId> --draft --message "<request>" --json
+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
 ```
 
-MCP: call `agent_test` with `rail: draft` and `waitSeconds`.
-
-A direct action runs inline and does not create a workflow execution ID. Evidence is the persisted conversation, its direct-action tool/run events, the returned result, and any observed external side effect. Never invent a workflow execution ID for it.
-
-If confirmation is required, inspect the pending action and exact arguments before approving or denying its request. A successful assistant reply alone does not prove the intended action ran.
+`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.
 
-## Publishing and sharing semantics
+## Verify
 
-Publishing snapshots the action identity, description, and approval policy into the agent version. The connection and authorization grant remain live security bindings: rebinding can redirect the published action, while breakage, revocation, or detachment can stop it immediately without another agent publish. Detachment also removes the draft tool; publish afterward to remove the unavailable tool from the published list.
+For an attachment, the tool list shows exactly one intended direct attachment with the exact identities, 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.
 
-Organization members use the published agent, never its mutable draft. Direct actions run through the agent owner's connected external account. Controller AI usage draws from the organization's shared usage pool, regardless of which member calls the agent. State that credential boundary before organization sharing.
-
-## Before you finish
-
-```bash
-cai agent tools <agentId> --json
-cai agent conversation history <conversationId> --json
-```
+## Report
 
-- Tools must show one intended direct attachment with the exact returned identities, connection, description, and confirmation policy.
-- History must contain the persisted action event, exact arguments, and result; confirm any requested external effect separately.
-- No wrapper workflow should exist unless the capability actually required orchestration or reuse.
+Which action is attached to which agent, its connection and confirmation choice, what the draft test proved, whose account and usage pool the action will use, and what remains: a connection to authorize, a publish, or a live verification.