@controllerai/cli 0.2.18 → 0.2.20

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

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

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

@@ -1,125 +1,24 @@
 ---
 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 and attach ready integration actions directly to Controller AI agents, configure connections and dynamic properties, and verify external app operations. Use when one existing action satisfies an agent capability.
 ---
 
-# Controller AI integration actions
+# Ready actions as agent tools
 
-The `cai ...` examples are canonical grammar. Use the transport selected in `controllerai-start` and its MCP tool map; never mix transports in one task.
+A ready integration action is one existing operation: search a service, read an object, create a record or send a message. Attach it directly to an agent when that operation is the capability. Use a workflow tool when you also need deterministic validation, multiple ordered steps, transformation, persistence or a reusable typed contract.
 
-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.
+## Discover and configure
 
-## Rules that break tasks when skipped
+Search by the intended operation, inspect the matching integration, then read its exact action key and properties. Prefer capability evidence over a similar integration name. Native actions and external provider actions can have different authorization requirements.
 
-- 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.
+Select an existing matching connection and verify its identity. If a new connection is needed, return the connection URL and let the user complete provider authorization. Never request provider credentials in chat. An “active” stored connection still needs a representative action test to prove current authorization.
 
-## Choose direct action or workflow
+Attach the action with its exact integration/action/connection and a description that tells the agent when to use it. Inspect configurable inputs and reload dependent options after selector changes. Choose the tool's runtime confirmation setting for the requested experience.
 
-Use a direct action for one existing operation such as sending one message, creating one record, or adding one row.
+## Verify the attached capability
 
-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.
+Read the saved tool list and test in a draft conversation. Inspect the chosen action, arguments, terminal result and intended external effect. A direct action does not create a workflow execution. For a failed or uncertain mutation, inspect external state before repeating it.
 
-## Discover exact identities
+Connection rebinding, detachment or revocation can affect Live independently of publishing the agent. If the user requested release, publish the updated agent configuration after testing and verify a Live conversation. Do not publish merely because the draft is ready.
 
-```bash
-cai integration search "<app or capability>" --json
-cai integration actions "<operation>" --integration <integrationSlug> --json
-cai integration action --integration <integrationSlug> --key <actionKey> --json
-```
-
-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.
-
-## Select a connection
-
-```bash
-cai connection list --integration <integrationSlug> --json
-```
-
-Use an active connection whose `integration` exactly matches the integration slug. If none exists:
-
-```bash
-cai connection connect <integrationSlug>
-```
-
-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.
-
-## 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.
-
-```bash
-cai agent add-action <agentId> \
-  --integration <integrationSlug> \
-  --action <actionKey> \
-  --connection <connectionId> \
-  --description "Use when ..." \
-  --require-confirmation \
-  --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.
-
-Read the saved grant back:
-
-```bash
-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.
-
-To rebind the live authorization grant or change a versioned policy:
-
-```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
-```
-
-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.
-
-## Verify through the hosted agent
-
-Use a representative draft conversation:
-
-```bash
-cai agent test <agentId> --draft --message "<request>" --json
-cai agent conversation history <conversationId> --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.
-
-## Publishing and sharing semantics
-
-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.
-
-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
-```
-
-- 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.
+Discovery, attachment, update and removal commands: [reference](references/command-reference.md).

package/skills/controllerai-integration-actions/references/command-reference.md

@@ -0,0 +1,118 @@
+# Controller AI integration actions
+
+
+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.
+
+
+- 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.
+
+## Choose direct action or workflow
+
+Use a direct action for one existing operation such as sending one message, creating one record, or adding one row.
+
+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.
+
+## Discover exact identities
+
+```bash
+cai integration search "<app or capability>" --json
+cai integration actions "<operation>" --integration <integrationSlug> --json
+cai integration action --integration <integrationSlug> --key <actionKey> --json
+```
+
+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.
+
+## Select a connection
+
+```bash
+cai connection list --integration <integrationSlug> --json
+```
+
+Use an active connection whose `integration` exactly matches the integration slug. If none exists:
+
+```bash
+cai connection connect <integrationSlug>
+```
+
+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.
+
+## 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.
+
+```bash
+cai agent add-action <agentId> \
+  --integration <integrationSlug> \
+  --action <actionKey> \
+  --connection <connectionId> \
+  --description "Use when ..." \
+  --require-confirmation \
+  --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.
+
+Read the saved grant back:
+
+```bash
+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.
+
+To rebind the live authorization grant or change a versioned policy:
+
+```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
+```
+
+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.
+
+## Verify through the hosted agent
+
+Use a representative draft conversation:
+
+```bash
+cai agent test <agentId> --draft --message "<request>" --json
+cai agent conversation history <conversationId> --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.
+
+## Publishing and sharing semantics
+
+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.
+
+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
+```
+
+- 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.

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

@@ -1,192 +1,32 @@
 ---
 name: controllerai-node-config
-description: Discover, initialize, configure, connect, and verify Controller AI workflow nodes. Use when adding an action, selecting an integration component, binding an account, setting node props, enabling optional or dynamic props, choosing provider-backed options, wiring nodes, or fixing a node that is not ready to run.
+description: Discover and configure Controller AI workflow action nodes, dynamic properties, connections, optional fields, output types and graph wiring. Use when assembling or repairing a concrete step in a flow.
 ---
 
-# Controller AI node configuration
+# Workflow nodes
 
-The `cai ...` examples are canonical grammar. Use the transport selected in `controllerai-start` and its MCP tool map; never mix transports in one task.
+A node is a step in a flow: a ready integration action, native data/file/AI action, or a control-flow construct. Its component defines properties, required authorization and output shape. The saved node is an instance configured for this workflow.
 
-A node is ready only after its component, connection, dependency-ordered props, wiring, and output type are valid. Treat configuration as a state machine, not a bag of property writes.
+## Discover by capability
 
-## Deterministic sequence
+Use `integration_search` and `integration_action_list` to search for the intended action, then inspect the exact integration slug and action key. Integration display names are not component identities. For native storage use `registry_data`; for generated files inspect native file actions; for web research inspect available search actions and connections.
 
-### 1. Find an exact component
+`integration_action_get` describes static properties. Some actions add dependent properties after a type, object, sheet or other selector is chosen. Saved connection status indicates an available binding; a successful representative provider request is the evidence it still works.
 
-```bash
-cai integration actions "<capability>" --json
-cai integration action --integration <nodeSlug> --key <nodeKey> --json
-```
+## Configure in dependency order
 
-Use the returned `nodeSlug` and full `key`. Do not infer a component key from its display name. If discovery is broad, narrow it with:
+1. Add the action to the intended flow using its returned exact key. Name the node after its purpose or produced value.
+2. Bind a required connection. Use `connection_connect_url` only when the user needs to connect an account; never request provider credentials in chat.
+3. Set selectors first, reload properties with `node_prop_list`, then read the resulting schema.
+4. Enable optional fields before setting them. Omission and an enabled empty value can have different effects, especially for updates.
+5. Set literal properties with `value`; use `js` for computed values. Read `expr_context` for expected types and available inputs.
+6. Wire the source output channel to the destination. Use returned output/port IDs; “main” and “error” are distinct channels.
+7. Inspect `node_status` and `node_get`, test the step or complete flow, then verify the saved output type and downstream mapping.
 
-```bash
-cai integration search "<integration>" --actions --json
-cai integration actions "<action>" --integration <nodeSlug> --json
-```
+Use the supported initial configuration batch when creating a node: `node_add` accepts its name, connection, upstream wiring, optional fields and a `props` map together. Direct values are literals; an advanced entry such as `"name": {"valueJs": "flow.name"}` compiles a typed expression. Put selectors such as `dataType` first so dependent fields exist. Inspect the returned `propsReadback` and readiness, then fix only rejected or missing fields. This avoids one call per property when repeating a proven CRUD pattern. Use flow scaffolds for loops and return mappings where they fit.
 
-Inspect static prop metadata before creating the node. `required`, `remoteOptions`, and `reloadProps` determine configuration order.
+A static output contract should remain stable after a run. A dynamic action may learn its output shape from a representative test; re-read its output/context before authoring downstream fields. Do not overwrite a known contract with an unrelated inferred schema just to remove a warning.
 
-### 2. Resolve the account
+Use `controllerai-flow-control` for branches/loops and `controllerai-ai-nodes` for AI output configuration. Layout once after a group of structural changes.
 
-If the component requires auth:
-
-```bash
-cai connection list --node <nodeSlug> --json
-```
-
-- One active connection: use its exact `id` as the `connectionId`.
-- Several: use an explicit user preference; otherwise ask which account.
-- None: add the real component without `--connection`; `missingConnection: true` is a valid handoff state. On CLI, get the link with `cai connection connect <nodeSlug> --no-open` and share it right away; do not block on `--wait` before sharing.
-
-  MCP: call `connection_connect_url` with `nodeSlug`, show its `url` as a markdown link, ask the user to finish, then confirm with `connection_list` using its `integration`.
-
-  After they confirm, run `cai connection list --integration <nodeSlug> --json` and bind the new ID with `cai node set-connection <nodeId> --connection <connectionId>`.
-
-Never substitute a connection from a similar slug.
-
-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. A raw endpoint mentioned by the user is background context, not an instruction to hand-roll the call.
-
-### 3. Initialize once
-
-```bash
-cai node init \
-  --flow <flowId> \
-  --node <nodeSlug> \
-  --key <nodeKey> \
-  --name "<data this node produces>" \
-  --connection <connectionId> \
-  --after <upstreamNodeId> \
-  --json
-```
-
-MCP: use `node_add`; `cai node init` is the CLI alias of `cai node add`.
-
-Omit flags that do not apply. `--after` creates the ordinary main/error wire at creation. Use it when later props need upstream data. Initialization also accepts `--props`, but use it only for static, non-option values already present in the inspected component metadata. Never inline a `remoteOptions` value, a reload selector and its dependents, or a prop that has not materialized yet; initialize first and set those sequentially. Use `--enable-prop <name...>` only for optional props confirmed by component metadata.
-
-Capture the returned `nodeId`; do not rediscover it by name. Inspect the complete create result before projecting fields. A missing projection is not proof that creation failed, so read the captured ID or exact flow inventory before any retry.
-
-When repairing an existing node, keep its node ID and configure it in place. Do not delete and recreate it merely to clear bad props, select a component, or refresh generated props; deletion discards wiring, conditions, and identity-based references. Replace it only when the requested component itself must change. Then capture the replacement ID, reconnect every dependent, and revalidate them.
-
-### 4. Follow readiness, not guesses
-
-```bash
-cai node status <nodeId> --json
-cai node props <nodeId> --json
-```
-
-For option-backed props, `node props` and write readback may report `optionsAvailability`: `available`, `blocked_upstream` with `blockedBy`, or `dynamic_upstream`. It is positional: earlier single `DROPDOWN` selectors gate later options. Older backends, and responses without a dependency catalog, may omit it; treat absence as unknown, not available.
-
-Work through blockers in this order:
-
-1. Missing connection
-2. Required selector props with `reloadProps`
-3. Newly revealed required props
-4. Static and remote-option props
-5. Wiring required for expressions
-6. Expressions
-7. Unresolved output type
-
-Follow `next`. When a disabled required prop has an activating selector, its blocker names that selector; when it is the next blocker, `next` gives the exact `cai node set` command. `dynamicSelectorNotes` is non-blocking: a node may read ready while its dynamic selector's dependents still reflect the last concrete resolution.
-
-After every concrete reload-selector or connection change, re-run `node props`; dynamic props can appear, disappear, or reset. Use `cai node reload <nodeId> --json` to re-resolve without re-setting a selector. If an explicit reload finds an unset materialized reload selector, it returns `reconcileSkipped: "unset_selector"` plus a note and preserves materialized dependent props instead of reconciling them.
-
-### 5. Set props safely
-
-Static value:
-
-```bash
-cai node set <nodeId> --prop <exactName> --value '<literal-or-json>' --json
-```
-
-MCP: use `node_prop_set` with `value`; it also handles expression writes through `js`.
-
-Optional prop:
-
-```bash
-cai node optional-props <nodeId> --json
-cai node set <nodeId> --prop <exactName> --value '<literal-or-json>' --json
-# or: cai expr set <nodeId> --prop <exactName> --js '<expression>' --json
-```
-
-MCP: `cai expr set` is the `js` form of `node_prop_set`.
-
-`node set` and `expr set` auto-enable a catalog-only optional prop, refresh its metadata, then write. Do not run a separate enable step first. If validation or the later write fails, the prop stays enabled; repair with `cai node disable-prop <nodeId> --prop <exactName>` and re-read props. This is also the repair for the Update-data wipe footgun: that action writes every enabled field, so disable any accidentally enabled field before running it.
-
-MCP: use `node_optional_prop_set` with `enabled: false` to disable or `enabled: true` to enable.
-
-Remote or dynamic option:
-
-```bash
-cai node options <nodeId> --prop <exactName> --query "<specific label>" --json
-cai node set <nodeId> \
-  --prop <exactName> \
-  --value '<returned value>' \
-  --label '<returned label>' \
-  --json
-```
-
-`node options` also supports `--prev-context '<context JSON>'` from the preceding page and repeatable `--for '<earlierProp>=<value>'` overrides for read-only hypothetical resolution; JSON literals are accepted and bare text stays a string. If options are `blocked_upstream`, both `node options` and `node set` name the blocking prop and print the exact `cai node set` command to run first.
-
-For an ordinary remote option, preserve both fields from the same returned option. The label is not cosmetic: it is used to search providers that do not index opaque IDs, then the returned value is verified before writing. For a multi-select, pass a JSON array of returned values and one `--label` argument per value, in the same order. The write supplies the persisted label shape, chooses the correct expression storage channel, and verifies read-back.
-
-When an earlier selector makes the prop `dynamic_upstream`, no option list exists. Use a known exact ID or an expression:
-
-```bash
-cai node set <nodeId> --prop <exactName> --value '<exact-id>' --label '<display label>' --json
-cai node set <nodeId> --prop <exactName> --js '<expression>' --json
-```
-
-`--value` stores the literal without provider-option validation and prints a note; on a label-bearing selector, `--label` controls its display label. This is the sole raw `--value` exception when the CLI has an advertised option set: outside `dynamic_upstream`, a missing prop row, a failed or empty advertised remote-options lookup, or a value absent from advertised options fails closed. The exception still requires prop metadata and verified read-back. Do not bypass failures with a raw API call.
-
-For components whose dependent props exist only after a concrete selector value, use a template first: set one concrete value, re-read `node props`, configure or record the revealed dependents, then switch the selector to `--js`. Those materialized props persist as the last concrete schema. Starting dynamic leaves them absent; neither that write nor `node reload` materializes them until one concrete selection is made.
-
-For dynamic values, load `controllerai-expressions` and prefer `cai expr set`.
-
-### 6. Wire and verify
-
-Ordinary outputs:
-
-```bash
-cai node connect --flow <flowId> --from <sourceNodeId> --to <targetNodeId> --output main --json
-```
-
-Use `--output error` only for the automatic error path. Router and If/Else outputs require `cai branch connect` from the flow-control skill.
-
-Finish with:
-
-```bash
-cai node status <nodeId> --json
-cai run node <nodeId> --inputs <values.json> --json
-```
-
-MCP: `run_node` takes the parsed `inputs` object and `waitSeconds` (default 60, max 120).
-
-If the node has a wired input or consumes `inputs.<name>`, the node test is only an isolated configuration check. Run `cai run flow <flowId> --inputs <values.json> --json` before declaring its upstream expressions verified.
-
-MCP: `run_flow` takes the parsed `inputs` object and `waitSeconds` (default 60, max 120).
-
-If a dynamic provider action cannot be run but its response is documented, declare an unverified output contract:
-
-```bash
-cai node declare-output <nodeId> --sample-file provider-response.json --json
-```
-
-MCP: call `node_output_type_declare` with the parsed provider response in `sample`; the server cannot read `provider-response.json`.
-
-The sample must be a JSON object or a non-empty JSON array of provider items. Re-read status and expression context afterward; the first real completed run verifies the declaration.
-
-Read [references/prop-and-readiness.md](references/prop-and-readiness.md) when a prop is dynamic, option-backed, expression-capable, or unexpectedly absent.
-
-## Hard rules
-
-- Configure props in returned order; later props may depend on earlier values.
-- Never write a prop absent from `node props`.
-- Let `node set` or `expr set` auto-enable catalog-only optional props; disable the prop explicitly after a failed write.
-- Wire before authoring an expression that consumes upstream data.
-- Changing a connection invalidates connection-scoped options; re-read props and options.
-- A successful write is not completion. Require read-back plus `node status`.
-- If output type remains unresolved, perform a realistic development test and inspect the resulting execution. Declare only a documented provider sample; never fabricate an output schema.
+Detailed property-setting examples: [command reference](references/command-reference.md). Readiness and dynamic-property behavior: [prop reference](references/prop-and-readiness.md).