@controllerai/cli 0.2.20 → 0.2.22

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

@@ -0,0 +1,112 @@
+---
+name: controllerai-flow-control
+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 -->
+
+# Flow control
+
+## Use this when
+
+- 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.
+
+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`.
+
+## How it works
+
+| 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 |
+
+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 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.
+
+## Rules
+
+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.
+
+## Recipes
+
+### Guard one action
+
+- `expr_context` — `nodeId`, `methods`, `prop`, `workflowId`
+- `expr_validate` — `nodeId`, `js`, `mode`, `prop`, `workflowId`
+- `node_only_when_set` — `nodeId`, `clear`, `groups`, `js`, `workflowId`
+
+`expr_validate` takes `mode: "onlyWhen"` and no `prop`. `node_only_when_set` takes `js` for one expression or `groups` as the parsed arrays, for example `groups: [["flow.email.isNotEmpty()", "flow.units < 5"], ["flow.override === true"]]`; pass `clear: true` only when removing the guard is the user's intent.
+
+### If/Else and Router
+
+- `branch_list` — `nodeId`, `workflowId`
+- `branch_update` — `nodeId`, `conditionJson`, `js`, `name`, `branchId`, `workflowId`
+- `branch_add` — `nodeId`, `allowDuplicate`, `conditionJson`, `js`, `name`, `workflowId`
+- `branch_update` — `nodeId`, `conditionJson`, `js`, `name`, `branchId`, `workflowId`
+- `branch_connect` — `nodeId`, `flow`, `branchId`, `to`, `workflowId`
+- `branch_reorder` — `nodeId`, `order`, `workflowId`
+
+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.
+
+`branch_update` and `branch_add` take `js` or `conditionJson` as the parsed arrays (`conditionJson: [["flow.email.isNotEmpty()", "flow.units < 5"], ["flow.override === true"]]`) with `branchId` for the route; `branch_connect` takes `branchId`, `to` and `flow`; `branch_reorder` takes `order` as the array of condition IDs.
+
+### Loop over a list
+
+- `node_get` — `nodeId`, `workflowId`
+- `flow_for_each_scaffold` — `continueOnError`, `flow`, `from`, `itemField`, `itemName`, `itemType`, `listField`, `listJs`, `maxItems`, `name`, `sourceOutput`, `workflowId`
+- `node_prop_set` — `nodeId`, `js`, `label`, `prop`, `rawExpressionJson`, `value`, `workflowId`, `valueJson`
+
+`sourceOutput` 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 pass `listField` with the dot path below `.data`; reserve `listJs` for an exact advanced expression whose shape you took from the context; the two are mutually exclusive. `itemField` (an array of `id:type[:display]` strings) is only for creating a new `custom.*` item type; stored records use `dataRecord.custom.*`. Set `maxItems` on purpose when the requirement differs from 500, decide `continueOnError` 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`.
+
+`flow_for_each_scaffold` takes `listField` or `listJs` inline; the server reads no local file. Later changes go through `node_prop_set` on the loop node: `prop: "maxItems"` with a number, or `prop: "continueOnIterationError"` with `value: true`.
+
+### Call another flow
+
+- `node_subflow_set` — `nodeId`, `flow`, `workflowId`
+- `node_prop_list` — `nodeId`, `workflowId`
+
+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
+
+- `node_add` — `after`, `connection`, `enableProp`, `flow`, `key`, `name`, `node`, `output`, `props`, `workflowId`
+- `node_prop_set` — `nodeId`, `js`, `label`, `prop`, `rawExpressionJson`, `value`, `workflowId`, `valueJson`
+- `flow_output_add` — `flowId`, `description`, `display`, `name`, `type`, `workflowId`
+- `node_add` — `after`, `connection`, `enableProp`, `flow`, `key`, `name`, `node`, `output`, `props`, `workflowId`
+- `node_continue_on_error_set` — `nodeId`, `enabled`, `workflowId`
+- `node_connect` — `flow`, `from`, `output`, `to`, `workflowId`
+
+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.
+
+`node_add` takes `node: "registry_flow"`, `key: "registry_flow-merge"` (or `"registry_flow-return-response"`), `name` and `after`; `node_prop_set` sets `prop: "mode"`, `value: "chooseActivePath"` and `prop: "pathDataType"`; `node_continue_on_error_set` takes `enabled: true`; `node_connect` takes `output: "error"` for the error path.
+
+## Verify
+
+- `branch_list` — `nodeId`, `workflowId`
+- `workflow_validate` — `workflowId`
+- `run_flow` — `flowId`, `confirmLive`, `inputs`, `target`, `waitSeconds`, `workflowId`
+- `execution_tree` — `workflowExecutionId`, `cursor`, `flowId`, `limit`, `status`, `workflowId`
+
+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-mcp/controllerai-flow-control/references/patterns.md

@@ -0,0 +1,82 @@
+<!-- generated from .claude/skills by cli/scripts/render-skills.mjs; edit the source -->
+# Flow-control patterns
+
+## Guard a side effect
+
+`only-when` means "skip this action, nothing else":
+
+```text
+Read record -> Send notification [only when status changed]
+```
+
+Test true and false; the false run shows `only_when_false` on that node and downstream stays eligible.
+
+## Exclusive decision
+
+If/Else when exactly one outcome must occur:
+
+```text
+Score -> If/Else
+           high priority -> Escalate
+           normal        -> Queue
+           Else          -> Record unknown
+```
+
+Most specific condition first; Else is the fallback and never gets a complement condition.
+
+## Independent fan-out
+
+Router when every applicable action should run:
+
+```text
+New order -> Router
+              international -> Customs review
+              high value    -> Fraud review
+              gift          -> Gift note
+```
+
+One order may take all three routes. If that is not acceptable, use If/Else.
+
+## Grouped conditions
+
+Outer rows are OR, entries within a row are AND, and each string compiles on its own:
+
+- `node_only_when_set` — `nodeId`, `clear`, `groups`, `js`, `workflowId`
+- `branch_update` — `nodeId`, `conditionJson`, `js`, `name`, `branchId`, `workflowId`
+
+## Per-item subflow
+
+- `node_get` — `nodeId`, `workflowId`
+- `flow_for_each_scaffold` — `continueOnError`, `flow`, `from`, `itemField`, `itemName`, `itemType`, `listField`, `listJs`, `maxItems`, `name`, `sourceOutput`, `workflowId`
+
+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 (`continueOnError`) 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
+
+- `node_add` — `after`, `connection`, `enableProp`, `flow`, `key`, `name`, `node`, `output`, `props`, `workflowId`
+- `node_prop_set` — `nodeId`, `js`, `label`, `prop`, `rawExpressionJson`, `value`, `workflowId`, `valueJson`
+- `node_prop_list` — `nodeId`, `workflowId`
+- `node_prop_set` — `nodeId`, `js`, `label`, `prop`, `rawExpressionJson`, `value`, `workflowId`, `valueJson`
+- `node_connect` — `flow`, `from`, `output`, `to`, `workflowId`
+- `node_add` — `after`, `connection`, `enableProp`, `flow`, `key`, `name`, `node`, `output`, `props`, `workflowId`
+
+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
+
+- `flow_output_add` — `flowId`, `description`, `display`, `name`, `type`, `workflowId`
+- `node_add` — `after`, `connection`, `enableProp`, `flow`, `key`, `name`, `node`, `output`, `props`, `workflowId`
+- `node_prop_list` — `nodeId`, `workflowId`
+- `expr_context` — `nodeId`, `methods`, `prop`, `workflowId`
+- `node_prop_set` — `nodeId`, `js`, `label`, `prop`, `rawExpressionJson`, `value`, `workflowId`, `valueJson`
+
+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 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`.
+
+- `node_continue_on_error_set` — `nodeId`, `enabled`, `workflowId`
+- `node_connect` — `flow`, `from`, `output`, `to`, `workflowId`
+
+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-mcp/controllerai-integration-actions/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: controllerai-integration-actions
+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 -->
+
+# Integration actions
+
+## Use this when
+
+- 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.
+
+Building the agent itself belongs to `controllerai-agents`; a workflow node for the same app belongs to `controllerai-node-config`.
+
+## How it works
+
+**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 (`connection_connect_url`), 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.
+
+**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.
+
+**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.
+
+**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.
+
+**Slack approvals.** Approval requests can also go to Slack through `slackRoute`. 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
+
+- `integration_search` — `query`, `limit`, `kind`
+- `integration_action_list` — `query`, `integration`, `limit`
+- `integration_action_get` — `integration`, `key`
+
+`integration_search` ranks integrations (`kind` narrows to actions or events); `integration_action_list` ranks actions across one or all integrations; `integration_action_get` 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
+
+- `connection_list` — `integration`
+
+Skip this step when the catalog says the native action needs no connection.
+
+Use the active connection whose `integration` matches exactly. If none exists, `connection_connect_url` (it takes the `nodeSlug`) returns a `url`: show it as a markdown link, ask the user to finish, then `connection_list` with `integration` and use the new ID.
+
+### Attach
+
+- `agent_tool_action_add` — `agentId`, `action`, `connectionId`, `description`, `integration`, `requireConfirmation`, `slackRoute`
+- `agent_tool_list` — `agentId`
+
+`agent_tool_action_add` takes `requireConfirmation`, optional and `false` by default; pass `connectionId` exactly when the action needs a connection.
+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
+
+- `agent_tool_update` — `agentId`, `connectionId`, `description`, `requireConfirmation`, `toolId`, `slackRoute`
+
+`agent_tool_update` takes `toolId` and at least one of `connectionId`, `description` or `requireConfirmation: true|false`; an omitted field keeps its value, so a connection-only update never changes the approval policy.
+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
+
+- `agent_test` — `agentId`, `message`, `model`, `waitSeconds`, `title`, `rail`
+- `agent_conversation_history` — `conversationId`, `last`
+- `agent_conversation_approve` — `conversationId`, `requestId`
+- `agent_conversation_deny` — `conversationId`, `message`, `requestId`
+
+`agent_test` takes `rail: "draft"` and `waitSeconds`; approve and deny take the `requestId` from the pending request.
+`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.

package/skills-mcp/controllerai-node-config/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: controllerai-node-config
+description: Discover, add, connect, configure, wire, and verify Controller AI workflow nodes. Use when adding an action, choosing a component, binding an account, setting props (static, optional, option-backed or dynamic), wiring nodes, resolving an output type, or fixing a node that is not ready.
+---
+<!-- generated from .claude/skills by cli/scripts/render-skills.mjs; edit the source -->
+
+# Node configuration
+
+## Use this when
+
+- A flow needs an action from an app or a native service, and the node has to be found, added, bound to an account, configured and wired.
+- A node reports missing connection, missing or disabled required props, pending selectors, or an unresolved output type.
+
+Computed values and conditions belong to `controllerai-expressions`; Router, If/Else, loops and subflows to `controllerai-flow-control`; Ask AI provider, model and typed output to `controllerai-ai-nodes`; tests and execution evidence to `controllerai-runs`.
+
+## How it works
+
+A **node** is a configured instance of a **component**: an integration action, a native data, file or AI action, or a control node. The component defines the props, whether an account is required, and the output shape. A node becomes usable in stages: component, connection, props in dependency order, then wiring and a concrete output type for whatever reads it downstream; each stage has its own readiness signal, so configure it as a sequence, not as one batch of property writes.
+
+**Connections** are the authorized accounts of an integration. A saved active connection proves a binding exists, not that the provider still accepts it; a representative request proves that. Changing a node's connection invalidates every connection-scoped option: re-fetch and re-verify them.
+
+**Props** come in kinds: static values; optional props that exist in the catalog and appear once enabled; option-backed props whose values come from static lists or a provider lookup; reload selectors (`reloadProps: true`) that change the schema of later props; and expression-capable props that take a dynamic value. Options are resolved in prop order: an earlier single-choice selector gates later lookups. `optionsAvailability` reports `available`, `blocked_upstream` with `blockedBy`, or `dynamic_upstream`; when the field is absent, availability is unknown, not available.
+
+**Readiness** (the node status read) reports distinct blockers: `missingConnection`, `missingRequiredProps`, `disabledRequiredProps` (the selector that activates them is named in `blockedBy` and `next`), `pendingReloadProps`, an unset subflow target or an invalid static option, and `dynamicSelectorNotes` (non-blocking: dependents still reflect the last concrete selection). `readyForExpressions` means the connection and the required and reload props are complete; `readyForRun` means it can execute; `readyForDownstreamExpressions` additionally means the output type is concrete. Readiness does not check wiring. `outputTypeStatus` is `concrete`, `unresolved` or `none` (a sink or control node has no output); an unresolved integration output is learned from a representative run, a supported output selector or a declared sample, and adoption changes only that node, so two instances of a generic component can learn different shapes. `next` is diagnostic guidance phrased as a CLI step: apply it through the current surface and its policy rather than executing it blindly.
+
+## Rules
+
+1. **Use the exact component the discovery returned** (`nodeSlug` and full `key`); never infer a key from a display name, and never swap in a similar integration or a raw HTTP request (`registry_http-http-request`) because a connection is missing. A user's mention of an endpoint is context, not a request to hand-roll the call.
+2. **Add a node without a connection when no account exists.** `missingConnection: true` is a valid handoff state; get the user's authorization and bind the exact new connection ID afterwards. Never ask for a provider credential in chat.
+3. **Configure in dependency order and read back after every write.** Set reload selectors before their dependents, re-read props after each selector or connection change, and treat a write as done only after readback plus `node status`.
+4. **Write only props that exist.** Materialized props and catalog optionals are writable; a name absent from both is an error. Setting a catalog optional enables it automatically; do not enable first. If that write then fails, the prop stays enabled: disable it and re-read.
+5. **Repair in place.** Keep the node ID, wiring, conditions and references, because downstream bindings and subflow mappings point at that ID. Replace a node only when the requested component itself changes; then reconnect and revalidate every dependent.
+6. **Keep value and label together for option-backed props.** Labels are how providers that do not index opaque IDs are searched and how values are verified. Outside `dynamic_upstream`, a value that is not in the advertised options fails closed.
+7. **Wire before writing an expression that reads upstream data**, and use branch connections for Router and If/Else outputs.
+8. **Never fabricate an output schema.** Resolve the type with a representative run, a supported output selector, or a documented provider sample declared as unverified; preserve a static contract instead of overwriting it with an inferred one.
+9. **Update Data writes every enabled field that resolves to a value.** A field that resolves to nothing is left out, but an enabled field that resolves to null or empty text overwrites the stored value, so disable fields you enabled by accident and inspect the resolved values before running.
+
+## Recipes
+
+### Find the component
+
+- `integration_action_list` — `query`, `integration`, `limit`
+- `integration_action_get` — `integration`, `key`
+
+Narrow a broad result with `integration_search`, then `integration_action_list`. Read `required`, `remoteOptions` and `reloadProps` before adding: they decide the configuration order.
+
+### Resolve the account
+
+- `connection_list` — `integration`
+
+One active connection: use its ID. Several: follow the user's stated preference, otherwise ask which account. None: add the node without a connection and hand off.
+
+Call `connection_connect_url` with the `nodeSlug`, show the returned `url` as a markdown link, ask the user to finish, then `connection_list` for that integration and bind the new ID. A URL is a handoff, not a completed authorization.
+
+- `node_connection_set` — `nodeId`, `connection`, `workflowId`
+- `node_status` — `nodeId`, `workflowId`
+
+### Add the node
+
+- `node_add` — `after`, `connection`, `enableProp`, `flow`, `key`, `name`, `node`, `output`, `props`, `workflowId`
+
+Name the node after its purpose or the value it produces. `after` wires the upstream node's main output (`output: "error"` for its error path) at creation, which later expressions need; initial `props` may carry only inspected static values, and `enableProp` lists optionals confirmed by the metadata. Never pass a remote option, a reload selector with its dependents, or a prop that has not materialized at creation. Capture the returned `nodeId`, then inspect `propsReadback` and `readiness` in the result and fix only rejected or missing fields.
+
+### Follow readiness
+
+- `node_status` — `nodeId`, `workflowId`
+- `node_prop_list` — `nodeId`, `workflowId`
+
+Clear blockers in this order: connection; required reload selectors; newly revealed required props; static and option-backed props; wiring an expression needs; expressions; output type. Use `next` as the guide for the next step. After a concrete selector or connection change, re-read props: fields appear, disappear or reset. `node_prop_reload` re-resolves dependents without re-setting a selector; when a materialized selector is unset it returns `reconcileSkipped: "unset_selector"` and preserves the dependents.
+
+### Set a prop
+
+- `node_prop_set` — `nodeId`, `js`, `label`, `prop`, `rawExpressionJson`, `value`, `workflowId`, `valueJson`
+- `node_optional_prop_list` — `nodeId`, `workflowId`
+- `node_prop_options` — `nodeId`, `for`, `page`, `prevContext`, `prop`, `query`, `workflowId`
+- `node_prop_set` — `nodeId`, `js`, `label`, `prop`, `rawExpressionJson`, `value`, `workflowId`, `valueJson`
+- `node_optional_prop_set` — `nodeId`, `prop`, `workflowId`, `enabled`
+
+`node_prop_set` takes exactly one of `value`, `valueJson` (JSON text kept verbatim), `js` or `rawExpressionJson`; for an option-backed prop pass `label` as an array of the returned labels aligned with the values (a one-element array for a single selection). `node_prop_options` continues a page with `prevContext` (parsed JSON) and previews under uncommitted earlier values with `for` as an array of `"<prop>=<value>"` strings. `node_optional_prop_set` with `enabled: false` disables; `true` enables. When options are `blocked_upstream`, the error names the selector to set first. For `dynamic_upstream`, no list exists: set a known exact ID with its label, or an expression in `js`.
+
+For a component whose dependent props exist only after a concrete selection, materialize a template first: set one concrete value, re-read props and configure the revealed dependents, then switch the selector to an expression. The dependents persist from that last concrete selection; starting dynamic leaves them absent. For dynamic values, load `controllerai-expressions`.
+
+### Wire
+
+- `node_connect` — `flow`, `from`, `output`, `to`, `workflowId`
+
+`output: "error"` is only for the automatic error path. Router and If/Else outputs use branch connections from `controllerai-flow-control`.
+
+### Resolve the output type
+
+- `run_node` — `nodeId`, `inputs`, `waitSeconds`, `workflowId`
+- `node_output_type_declare` — `nodeId`, `sample`, `workflowId`
+
+`run_node` takes parsed `inputs` and `waitSeconds` (default 60, maximum 120). `node_output_type_declare` takes the parsed provider response in `sample`; the server cannot read a file path.
+
+Prefer the representative run: the completed execution is checked for ownership and terminal state, then its output shape is adopted for that node. Inspect `outputTypeAdoption` in the run result: `no_observed_output` on a data-producing action means the run returned nothing reusable, so rerun it with inputs that return data only when a downstream binding needs the type and the additional real action is authorized; on a sink or control node it is the expected result. `error` means stop and surface it. Declare a documented sample (an object or a non-empty array of items) when the action is unavailable, unsafe or declined; it stays unverified until the first real run. A node test with a wired input is an isolated check; upstream expressions are verified only by running the containing flow. Adoption is node-local: a discovery run on a scratch node never types the node in the flow. Read `controllerai-runs` for discovery.
+
+## Verify
+
+`node status` shows no blockers for the requested readiness level, every written prop reads back with the intended value and label, the wiring matches the flow, and the output type is concrete before downstream fields are bound. Expression context (`expr_context`) lists the upstream binding you expect.
+
+## Report
+
+The component and connection used, which props were set and which remain for the user (a missing authorization above all), and whether the output type was verified by a run or only declared.
+
+Read [references/prop-and-readiness.md](references/prop-and-readiness.md) when a prop is dynamic, option-backed, expression-capable, or unexpectedly absent, or when a status field needs its exact meaning.

package/skills-mcp/controllerai-node-config/references/prop-and-readiness.md

@@ -0,0 +1,49 @@
+<!-- generated from .claude/skills by cli/scripts/render-skills.mjs; edit the source -->
+# Prop and readiness reference
+
+## What `node_status` reports
+
+- `missingConnection`: an authenticated component has no account bound.
+- `missingRequiredProps`: materialized required props without a value.
+- `disabledRequiredProps`: names of required props currently disabled by an activating selector. `blockedBy` and `next` name that selector.
+- `pendingReloadProps`: selectors that must be set before dependent props are trustworthy.
+- `dynamicSelectorNotes`: reload selectors holding dynamic values whose dependents were not re-resolved. Non-blocking; read them even when the node is ready.
+- `outputTypeStatus`: `concrete`, `unresolved` or `none`. Connection-port wrappers never count as a concrete process output.
+- `readyForExpressions`: connection and required/reload props complete. The source still has to be wired before its binding appears in expression context.
+- `readyForRun`: runnable; the run may be what discovers the output type.
+- `readyForDownstreamExpressions`: runnable and the process output type is concrete enough for downstream field bindings. Require this, not `readyForRun`, before binding downstream fields.
+- `next`: diagnostic guidance for the next step, phrased as a CLI command; apply it through the current surface and its policy.
+
+## Prop channels
+
+`node_prop_set` picks the channel from live metadata: `value` (or `valueJson` for JSON text kept verbatim) is a literal; `js` is an expression, read back as `valueJs` for text, JSON text and custom data, or `expressionValueJs` for a non-text prop in expression mode; `rawExpressionJson` round-trips a compiled tree. Pass exactly one of the four.
+
+Never force a channel through internal fields. The expression setters compile before writing (a raw tree is validated by the backend), and every setter verifies the actual channel in the readback.
+
+## Option-backed props
+
+Static options are declared in the component metadata. Remote options need the current connection and the earlier prop values. When dependency metadata is present, each option-bearing prop reports:
+
+- `available`: no earlier selector blocks the lookup (a connection or provider failure can still stop it).
+- `blocked_upstream` with `blockedBy`: an earlier single-choice selector is unset. Follow the error's exact command first.
+- `dynamic_upstream`: an earlier single-choice selector holds an expression, so no concrete option list exists. Write a known exact ID with its display label, or an expression. This is the only case that skips membership validation; it still needs prop metadata and verified readback.
+
+Older backends and responses without a dependency catalog omit these fields; absence means unknown.
+
+Pass the value and the label from the same live option. Many providers search labels rather than opaque IDs, so a copied ID without its label may be impossible to re-verify. Multi-select takes an ordered array of values and an aligned array of labels; the readback shows `{value, label}` records.
+
+`node_prop_options` takes `query`, an opaque `prevContext` from the previous page, and `for` as an array of `"<prop>=<value>"` overrides for a read-only preview under uncommitted earlier values; `node_prop_set` takes the chosen `value` (or an array of values) and `label` as an array of the matching labels.
+
+## Reload selectors
+
+A prop with `reloadProps: true` changes the schema of later props. Set it, then immediately re-read props and status. Provider, model family, spreadsheet, database and action selectors commonly behave this way; never batch their dependents against stale metadata.
+
+A prop reload re-resolves current values without re-setting a selector. If a materialized reload selector is unset, it returns `reconcileSkipped: "unset_selector"` and preserves the materialized dependents instead of reconciling them.
+
+For a component whose dependent schema exists only after a concrete selection: set one concrete value, re-read and configure the revealed dependents, then switch the selector to an expression. The dependents persist from the last concrete selection; starting dynamic leaves them absent, and neither the dynamic write nor a reload materializes them.
+
+## Output type
+
+Resolve an unresolved output by setting the component's supported output or data-type selector, by running the configured node with representative inputs, or by declaring a documented provider sample as unverified. A discovery run (`controllerai-runs`) probes a component that is not in the graph on a scratch node: it deletes that node afterwards, keeps the scratch flow for reuse, and never types a node in the real flow.
+
+A completed run passes its exact node-execution ID back for ownership, workflow, node, component-snapshot and terminal-state checks, then the persisted output shape is adopted for that non-static node only. Read `outputTypeAdoption` (or `outputTypeAdoptions`) in the run result: `no_observed_output` means the run produced no reusable output, which is expected for a sink or control node and, for a data-producing action, a reason to rerun with representative data only when a downstream binding needs the type; `error` means stop and surface it. After adoption, re-read `node status` and the expression context. An example response alone never establishes a type.

package/skills-mcp/controllerai-runs/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: controllerai-runs
+description: Run Controller AI nodes and flows and read execution evidence: inputs, resolved configs, outputs, ports, skips, warnings and output-type adoption. Use when proving a build works, investigating a failed or green-but-wrong run, resolving a dynamic output type, or checking what an expression produced at runtime.
+---
+<!-- generated from .claude/skills by cli/scripts/render-skills.mjs; edit the source -->
+
+# Runs
+
+## Use this when
+
+- A node or flow was just built or changed and needs proof with real values.
+- A run failed, or finished green with empty, partial or wrong data.
+- A dynamic node's output type is unknown and downstream expressions cannot be written.
+
+Expression authoring belongs to `controllerai-expressions`, branch and loop structure to `controllerai-flow-control`, trigger replay to `controllerai-triggers`.
+
+## How it works
+
+**A run is real.** Node runs always execute on development; flow runs execute on development by default or, explicitly, on the published live version. Both call the real providers: messages send, records change, usage is spent. Development isolation covers the workflow data store only.
+
+**Running resolves types.** A dynamic integration node gets its output type from one completed representative run (`outputTypeAdoption`), and every downstream expression depends on that type. When the user declines to run a consequential action, the fallback is a declared output contract built from the provider's documented response; it is marked `declared (unverified)` and the first real completed run verifies it.
+
+**Three scopes.** A node run isolates the node's own configuration and does not execute wired upstream nodes; `runScope.endToEndValidationRequired` is computed from the wiring before the run and says that upstream-derived values need a containing-flow check, while `resolvedConfigs` shows what they actually were. A flow run executes the wiring and proves `inputs.<name>` expressions and the return contract. A discovery run creates a scratch node from a component that is not in the graph inside a reusable scratch flow, executes it and deletes the node (the flow stays), only to learn what it returns; it types nothing in the real flow.
+
+**Inputs are keyed by ID.** `run inputs` lists the exact input IDs a node or flow reads. A flow lists every declared input with a `used` flag: supply the used ones (an omitted used input falls back to its saved test value), and values for unused inputs are accepted and ignored. An isolated node run must receive every referenced `flowInputs[].id` or it fails before executing with `ISOLATED_FLOW_CONTEXT_REQUIRED`. Explicit `null`, `""`, `false` and `0` are supplied values; dates are plain ISO-8601 text.
+
+**The evidence.** `status` and `errorMessage`; `skipReason` (`only_when_false`, `upstream_skipped`); `runScope`; `resolvedConfigs`, where a null entry on a dynamic prop that the contract did not intend is a silent expression failure on an otherwise green run, and each entry's `resolutionWarnings` (an explicit `[]` means the resolver reported nothing; the value still has to match the contract); the output shape and values; and the adoption result, `outputTypeAdoption` on a node run or `outputTypeAdoptions` on a flow run, where `adopted` or `already_typed` lets the node status converge, `no_observed_output` means the run returned no reusable shape, and each entry's `adoptedNodeIds` must be empty or name only its own node.
+
+**Outcomes.** A run ends `completed`, `completed_with_error` (a handled error path, the expected result when testing continue-on-error), `failed` or `cancelled`; it can also stop `paused` waiting on something, or still be running when the wait ends. Polling is bounded by `waitSeconds` (default 60, maximum 120); a timeout, a pause or a failure comes back as execution evidence with its ID. A running or paused status means inspect that execution later, never dispatch the run again.
+
+## Rules
+
+1. **Mitigate, do not refuse.** Before a send, delete, charge or people-affecting run, say what will really happen and agree a safe target: the user's own address or channel, a record created for the test, a person the user names. Reuse authorization the task already gave; ask only for what it did not cover.
+2. **A declined run is declared, not skipped.** Declare the output from the provider's documented response, say it is unverified, and name the first real run as the verification step.
+3. **Smallest scope first, then the containing flow.** A node run proves configuration; only a flow run proves upstream-derived values and the return value.
+4. **Green is not proof, and red is not always failure.** Read resolved configs, outputs, ports and skips; a `completed` run with empty or null output is a failure until the values are read and explained, a null dynamic config the contract did not intend is a failure even when the status is green, and a run that matched the scenario's expected status, outputs and effects passed even when that status is `completed_with_error`. `0` and `false` are values.
+5. **Find the first divergence, not the last error.** Walk the execution tree, classify each node as completed, failed, skipped on purpose, skipped unexpectedly or absent; later failures are usually consequences.
+6. **Verify the effect where it lives.** Data writes: query the same store. Files: open the artifact. Provider actions: the provider's result, not the execution ID.
+7. **Never let a stalled run become a duplicate.** Inspect the returned execution; rerun only after it reached a terminal state and the cause is understood.
+8. **Adoption stays on the tested node.** Stop if `adoptedNodeIds` names a sibling, and re-read `node status` and downstream expression contexts after a type is adopted.
+
+## Recipes
+
+### Prepare inputs and run
+
+- `run_inputs` — `nodeIdOrFlowId`, `flow`, `workflowId`
+- `run_node` — `nodeId`, `inputs`, `waitSeconds`, `workflowId`
+- `run_flow` — `flowId`, `confirmLive`, `inputs`, `target`, `waitSeconds`, `workflowId`
+
+`run_inputs` takes `nodeIdOrFlowId` and `flow: true` for a flow (omit it for a node); `run_node` and `run_flow` take `inputs` as the parsed object keyed by input ID and `waitSeconds`.
+
+### Declare an output the user will not run yet
+
+- `node_output_type_declare` — `nodeId`, `sample`, `workflowId`
+
+`node_output_type_declare` takes the parsed sample in `sample`; the server reads no file.
+
+### Discover what a component returns
+
+- `run_discover` — `connection`, `enable`, `key`, `node`, `props`, `workflowId`
+
+`run_discover` takes `node`, `key`, `connection` (`"none"` for a component without auth), `props` and `enable`; it always deletes the scratch node and has no keep or wait parameter.
+Discovery calls the real action and spends usage. Never probe a destructive action just to learn its output: agree a safe target or declare the shape instead. Prefer testing a configured node: discovery returns `observedOutputType`, `nodeExecution`, `workflowExecutionId`, `scratchFlowId` and `nodeDeleted`, the full execution stays readable by ID, and the real node in the flow still has to be typed by its own run or a declaration.
+
+### Verify the published version
+
+- `run_flow` — `flowId`, `confirmLive`, `inputs`, `target`, `waitSeconds`, `workflowId`
+
+Pass `target: "live"` and `confirmLive: true` to `run_flow`.
+When the user authorized live verification and named a safe target, run the published flow once under supervision instead of waiting for a real trigger event. It fires real actions and spends usage. Where the design calls for it, a safe-audience harness (an If/Else on `isLiveVersion` whose false branch targets the developer and whose true branch targets the real audience) protects development runs; the live run is still a real send, and adding that harness is a design change to agree, not a test step.
+
+### Read the execution
+
+- `execution_tree` — `workflowExecutionId`, `cursor`, `flowId`, `limit`, `status`, `workflowId`
+- `execution_get` — `workflowExecutionId`, `workflowId`
+- `execution_flow_get` — `flowExecutionId`, `workflowId`
+- `execution_node_get` — `nodeExecutionId`, `full`, `workflowId`
+
+Page the tree with the returned `nextCursor` as `cursor` and narrow a large run with `status` (an array) or an exact `flowId`; `execution_node_get` with `full: true` returns the untruncated output. The tree locates the first unexpected status; the full node execution holds the resolved configuration and the untruncated output. Read [references/debugging.md](references/debugging.md) for the fault-isolation order and the symptom table.
+
+## Verify
+
+The run exercised the changed path with credible values; the first unexpected node, if any, was identified from the tree; every dynamic config resolved to the intended value and `resolutionWarnings` were read; the output shape and values match what downstream expects; skips are intentional and error paths accounted for; a flow run reached the scenario's expected status, outputs and effects after isolated fixes; the stored or external effect was checked where it lives; and any declared contract is still marked unverified in the report.
+
+## Report
+
+What ran and on which version, the execution IDs, what each run proved, what is declared but unverified, and what remains untested and why.

package/skills-mcp/controllerai-runs/references/debugging.md

@@ -0,0 +1,53 @@
+<!-- generated from .claude/skills by cli/scripts/render-skills.mjs; edit the source -->
+# Execution debugging
+
+Use this order; it avoids changing a downstream node when the defect is upstream.
+
+## 1. Confirm the version and the graph
+
+- `workflow_status` — `workflowId`
+- `flow_get` — `flowId`, `workflowId`
+
+Node runs use development. Flow runs use development unless the published version was selected explicitly. Every run can call real providers.
+
+## 2. Find the first divergence
+
+- `execution_tree` — `workflowExecutionId`, `cursor`, `flowId`, `limit`, `status`, `workflowId`
+
+Follow `nextCursor` as `cursor`; use `status` (an array) or an exact `flowId` on a large run. Classify each node as completed, completed with a handled error, failed, cancelled, paused, skipped on purpose (`only_when_false`), skipped unexpectedly (`upstream_skipped` behind a failure or a wrong branch), or absent. The first divergence is usually the cause; later failures are consequences.
+
+## 3. Inspect the node boundary
+
+- `execution_node_get` — `nodeExecutionId`, `full`, `workflowId`
+
+In order:
+
+1. Resolved configs: did each expression resolve, and to the right type and value? A null entry on a dynamic prop that the contract did not intend is the failure even when the node is green; read each entry's `resolutionWarnings`.
+2. Port: did the node select the branch or output the test expected?
+3. Output: did the component return the promised shape and values? Compare a flow's return with its declared outputs.
+4. Status and error: did the provider or the engine reject the call?
+5. Upstream rows and wiring: did every expected producer run and connect to this node?
+
+## 4. Fix by symptom
+
+| Symptom | Inspect next |
+| --- | --- |
+| Missing or wrong input | Wiring, branch connection, or the test input ID |
+| Null dynamic config | Expression binding, field path, or a missing source value |
+| Invalid option or account | Node connection, dependency-ordered props, or a stale option |
+| Provider error | Integration configuration, credentials, quota, or payload |
+| Green node, wrong output | Component choice, output contract, or prompt |
+| Unexpected skip | Guard, branch condition or order, or an upstream failure |
+| Empty record query | Store (development versus live), field key, optional-filter semantics |
+| Provider authentication failure | Connection identity and the provider's error; an active status is not a fresh credential test |
+| Return value empty | Return node bindings, skipped branches, or resolved empty values |
+
+Re-read metadata and contexts before editing. Rerun the smallest failed scope, then the full flow.
+
+## 5. Avoid false confidence
+
+- A compile pass does not prove runtime data exists.
+- A node pass does not prove downstream mapping: a node run does not execute wired upstream nodes.
+- A development pass does not prove live data or the live release state.
+- A top-level completed status does not prove every intended branch ran, and a loop's success does not prove every iteration.
+- Keep the evidence of failed runs and separate it clearly from the final verified result; broaden the test when a fix changes shared behavior.