@controllerai/cli 0.2.20 → 0.2.22

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

@@ -1,177 +0,0 @@
-# Controller AI data
-
-
-Controller AI has two separate concerns:
-
-- A `custom.*` schema defines fields and makes a collection available.
-- Development and live record stores hold separate rows. Publishing graph/configuration does not copy records.
-
-
-- Persisting data requires both a schema and a create-record node; see A type vs a stored record.
-- `schema update --field` replaces the full field list; see Define a schema deliberately.
-- Relabel a stable key instead of recreating it; see How schema changes affect stored records.
-- Query results and writes use different field keys; see Respect field-key asymmetry.
-- Read and write the requested dev or live store; see Work on the correct rail.
-- Remove only scratch schemas created for abandoned attempts; see Before you finish.
-
-## A type vs a stored record
-
-When a request says store, save, log, or record with no external destination, create the schema and configure a create-record node. A flow output alone is not persistence.
-
-`custom.customer` and `dataRecord.custom.customer` are different things, and the difference carries through everything:
-
-- `custom.customer` is the TYPE — the shape, like a TypeScript interface. A value of this type is just data in that shape.
-- `dataRecord.custom.customer` is an ACTUAL STORED RECORD of that shape — the same fields plus record identity (`id`, `createdAt`, `updatedAt`) proving it lives in the collection.
-
-In the product UI this appears as the "data record" checkbox when selecting a type for a flow input or run-subflow-on-list: unchecked means "data shaped like a customer", checked means "a real stored customer record". Users find this checkbox confusing — be ready to explain it in these terms.
-
-Consequences:
-
-- Only real records satisfy a `dataRecord.*` input. An expression that CONSTRUCTS record-shaped objects (e.g. a `.map()` that builds new objects) produces `custom.*`-shaped values with no identity — pass fetched records through instead.
-- Record metadata (`id`, `createdAt`) exists only on `dataRecord.*` values; on plain `custom.*` values those paths resolve empty.
-
-## Data nodes: update semantics
-
-- "Update multiple data records" takes an expression typed `list.dataRecord.custom.<type>` — real stored records passed through from a query or `workflowData(...)`. The batch is ONE transaction: if any resolved record is stale (deleted since fetched) or foreign to the collection, the node errors and NOTHING updates. A failed run therefore means zero changes — fix and rerun safely.
-- On the single-record "Update data" node, every ENABLED field is written. Enable only the fields you intend to change; disabled fields keep their stored values.
-
-## Define a schema deliberately
-
-Inspect existing types first:
-
-```bash
-cai schema list --json
-cai schema get custom.<name> --json
-```
-
-Create a type with stable field IDs:
-
-```bash
-cai schema create custom.customer \
-  --display "Customer" \
-  --field email:text:"Email" \
-  --field score:number:"Score" \
-  --json
-```
-
-Creating the schema creates/synchronizes its collection. `cai data collection create` is only an alias for schema creation.
-
-MCP: `cai data collection create` is merged into `schema_type_create`.
-
-`schema update --field` replaces the complete field list; it does not append — this is deliberate, so a subset CAN intentionally replace the whole schema. Read the current schema, preserve intended fields, and disclose any removals. The transport response warns about every field being dropped and echoes back the COMPLETE stored shape after the write — always read that echo and confirm it matches intent. Deleting a schema hides its collection and records and breaks dependent expressions — tell the user, and know it is recoverable (see below).
-
-## How schema changes affect stored records
-
-Schema changes never hard-delete data. There is no delete path for records in schema sync — everything is deactivation and hiding:
-
-- Delete a type → its collection goes INACTIVE on the next saved state; every record row survives. Re-add the same `custom.*` key and the same collection reactivates with all records intact.
-- Delete a field → its values stay inside each record, unaddressable. Re-add the SAME field id and the old values reappear.
-- Add a field → purely additive; existing records read the new field as null.
-- Change a field's type → values are never converted or erased; incompatible values read as null and return if the type is changed back. The schema hash changes, which blocks copy-to-live until dev and live match again.
-- Publish applies the same deactivate/reactivate logic to live. Live records are hidden, never deleted.
-- Restoring an older workflow state rolls back the DEFINITION (graph and schemas), never the data. The record store is not versioned and only moves forward: a deleted type reactivates with whatever the store holds NOW — records created, edited, or soft-deleted after the restored state stay exactly as they are. Restore is not a data snapshot.
-
-The truly destructive operations are record-level only: `data delete`, `data delete-many`, and overwriting edits. Those have no undo — treat them with explicit user intent; everything schema-shaped is safely reversible.
-
-Relabel a type without changing its stable key:
-
-```bash
-cai schema update custom.customer --display "Customers" --json
-```
-
-Changing `custom.customer` itself is a key migration, not a relabel. It creates a new type and deactivates the old collection, stranding its records under the old key. Migrate records explicitly by export/import or restore the old key.
-
-## Respect field-key asymmetry
-
-```bash
-cai data fields --type custom.customer --json
-```
-
-- `data create` and `data update` take field IDs.
-- Query/get results are keyed by field display names.
-- CSV columns are also matched by display names.
-
-Never feed a queried record directly into a write. Build a new fields object keyed by the `writeKey` mapping and omit reserved `id`, `createdAt`, and `updatedAt`.
-
-Fields may be typed `date`. Their values are strict ISO-8601 strings (`"2026-06-05"` or `"2026-06-05T12:30:00Z"`) on both write and read; anything else is rejected. Reserved `createdAt`/`updatedAt` are currently `text` — use `.toDate()` before date operations on them.
-
-## Work on the correct rail
-
-Development is the default:
-
-```bash
-cai data collections --env dev --json
-cai data query --type custom.customer --env dev --json
-cai data create --type custom.customer --fields '{"email":"a@example.com","score":5}' --env dev --json
-```
-
-MCP: every data write requires explicit `env`; reads default to `dev` when `env` is omitted.
-
-Use `--env live` only when the user intends to inspect or mutate production state. Before a live write, say that published/triggered runs read this store.
-
-`data query --query` is plain-text search over serialized records and metadata, not a field predicate. Perform exact field filtering inside workflow expressions or inspect results explicitly.
-
-## Delete records explicitly
-
-Native workflow Delete Record actions provide reusable deletion inside a flow. Discover their exact keys under registry_data. The data tools below also delete one known record or an explicit set of IDs during setup and debugging:
-
-```bash
-cai data delete <recordId> --type custom.customer --env dev --json
-cai data delete-many --type custom.customer --records <id1,id2> --env dev --json
-```
-
-Delete every record in a collection only with explicit user intent; `--all` also requires `--yes`:
-
-```bash
-cai data delete-many --type custom.customer --all --yes --env dev --json
-```
-
-MCP: `data_record_delete_many` requires explicit `env: dev|live` and exactly one of `recordIds` or `all: true`; it has no `yes` parameter.
-
-The CLI default rail is development. Targeted and `--all --yes` bulk deletions also support `--env live`; a live deletion immediately changes the data read by the published workflow, so use it only with explicit production intent and query that rail afterward.
-
-## Import and promote
-
-Validate CSV before writing:
-
-```bash
-cai data import --type custom.customer --file customers.csv --mode dryRun --env dev --json
-cai data import --type custom.customer --file customers.csv --mode commit --env dev --json
-```
-
-MCP: pass CSV text inline as `content` with explicit `env: dev|live` to `data_record_import_validate`, then use `data_record_import_commit` to write the validated content.
-
-Both CLI modes support `--env live`: dry-run remains non-writing, while a live commit appends rows immediately visible to the published workflow. Verify result counts and query the imported rows on the same rail.
-
-To seed live from development:
-
-```bash
-cai workflow publish --json
-cai data copy-to-live --type custom.customer --json
-cai data collections --env live --json
-```
-
-MCP: call `data_copy_to_live` with the explicit acknowledgement `env: live`.
-
-The live schema must exist through a publish before copying. Treat copy-to-live as a production mutation and report counts/results.
-
-## Workflow expressions
-
-`workflowData("custom.customer")` requires an active collection on the executing rail. Read `controllerai-expressions` for filtering. Test stateful behavior against development, then independently verify required live seed data.
-
-Read [data-rails.md](data-rails.md) before schema rewrites, deletion, bulk deletion, import, or copy-to-live.
-
-## Before you finish
-
-```bash
-cai schema get custom.<type> --json
-cai data collections --env <dev|live> --json
-cai data query --type custom.<type> --env <dev|live> --json
-cai workflow outline --json
-cai workflow validate --json
-```
-
-- Schema read-back must show the intended stable key, display, complete field list, and field types.
-- The same-rail query must prove the expected persisted records; node output alone is insufficient.
-- Compare schema and workflow inventory with the request. Remove only schemas created during abandoned attempts, never pre-existing user objects.
-- For a live request, verify the live collection after publish or copy and report the affected record count.

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

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

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

@@ -1,171 +0,0 @@
-# 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/references/command-reference.md

@@ -1,118 +0,0 @@
-# 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.