@controllerai/cli 0.2.14 → 0.2.16

package/skills/controllerai-data/SKILL.md

@@ -5,7 +5,7 @@ description: Define Controller AI custom data types and safely read, write, impo
 
 # Controller AI data
 
-In MCP hosts, send each exact literal `cai ...` command through the single `exec` tool; never translate it into another grammar.
+The `cai ...` examples are canonical grammar. Use the transport selected in `controllerai-start` and its MCP tool map; never mix transports in one task.
 
 Controller AI has two separate concerns:
 
@@ -52,7 +52,9 @@ cai schema create custom.customer \
 
 Creating the schema creates/synchronizes its collection. `cai data collection create` is only an alias for schema creation.
 
-`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 CLI 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).
+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
 
@@ -93,13 +95,15 @@ 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
 
-Record deletion is CLI/REST-only; no workflow data node exposes it. Delete one known record or an explicit set of IDs:
+Record deletion is available only through the control surface; no workflow data node exposes it. Delete one known record or an explicit set of IDs:
 
 ```bash
 cai data delete <recordId> --type custom.customer --env dev --json
@@ -112,18 +116,22 @@ Delete every record in a collection only with explicit user intent; `--all` also
 cai data delete-many --type custom.customer --all --yes --env dev --json
 ```
 
-The default rail is development. Use `--env live` only for an intentional production deletion, then query that same rail to verify the result.
+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 --json
-cai data import --type custom.customer --file customers.csv --mode commit --json
+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
 ```
 
-The commit appends. Verify result counts and query the imported rows.
+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:
 
@@ -133,6 +141,8 @@ 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

package/skills/controllerai-data/references/data-rails.md

@@ -10,6 +10,8 @@
 
 Use `cai data copy-to-live --type <custom.type>` only for an intentional data promotion.
 
+MCP: `data_copy_to_live` requires the explicit acknowledgement `env: live`.
+
 ## Safe schema update
 
 1. `cai schema get <type> --json`
@@ -25,9 +27,9 @@ Field IDs are contracts. Prefer keeping an ID stable and changing only its displ
 ## Destructive operations
 
 - `data delete` soft-deletes one record.
-- `data delete-many --all --yes` is broad, REST-backed, and DEVELOPMENT-ONLY — `--env live` is refused (`DEV_ONLY_ROUTE`). The only live write paths are single-record `data create/update/delete --env live` and `copy-to-live`.
+- `data delete-many --all --yes` is broad and REST-backed on either rail. With `--env live`, the deletion immediately changes what the published workflow reads.
 - `schema delete` removes access to the whole collection and breaks its type references.
-- CSV `--mode commit` appends rows.
+- CSV `--mode commit` appends rows on the selected rail; a live commit is immediately visible to the published workflow. `--mode dryRun` writes nothing on either rail.
 - `copy-to-live` changes production data.
 
 Resolve exact workflow, environment, type, and record targets before these actions. Do not use a broad deletion to repair a schema mistake.

package/skills/controllerai-expressions/SKILL.md

@@ -5,7 +5,7 @@ description: Author, validate, persist, and debug Controller AI expressions for
 
 # Controller AI expressions
 
-In MCP hosts, send each exact literal `cai ...` command through the single `exec` tool; never translate it into another grammar.
+The `cai ...` examples are canonical grammar. Use the transport selected in `controllerai-start` and its MCP tool map; never mix transports in one task.
 
 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.
 
@@ -24,7 +24,7 @@ An empty input is not "nothing" — it evaluates to the type's empty form: empty
 - **A filter comparing against an empty value still filters — and matches NO records.** This is deliberate (fail-closed; matching everything by accident would be worse). If "empty should mean skip this filter", opt that constraint into ignore-empty mode explicitly (`ignoreEmptyConstraints`, see [references/dsl-and-recipes.md](references/dsl-and-recipes.md)).
 - **An optional TEXT input left empty arrives as `""`**, so an `equals` constraint against it matches nothing — the classic symptom is "search finds zero results only when the optional filter is blank", which then cascades (e.g. a create-if-missing step makes duplicates).
 
-When a run unexpectedly returns zero results, check the resolved configs for empty comparison values first (`cai exec ports`).
+When a run unexpectedly returns zero results, check the resolved configs for empty comparison values first (`cai exec node <nodeExecutionId> --full`).
 
 ## Required write loop
 
@@ -61,9 +61,11 @@ When compilation reports an unknown field, copy a typeable display-derived acces
 Get the current operation catalog when needed:
 
 ```bash
-cai expr ops --type <text|number|date|list|boolean|file|custom> --json
+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 use loops, assignments, `new`, regular expressions, optional chaining, arbitrary library methods, or object construction unless the current compiler catalog explicitly 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.
@@ -78,14 +80,20 @@ For a node prop, prefer:
 cai expr set <nodeId> --prop <propName> --js '<expression>' --json
 ```
 
-For multiline expressions or shell-sensitive templates, 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`.
+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:
@@ -110,13 +118,17 @@ 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
 ```
 
-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 ports <nodeExecutionId> --json` to compare inputs, resolved configs, and outputs.
+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
 

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

@@ -27,6 +27,8 @@ cai expr validate <httpNodeId> --prop <jsonBodyProp> --js-file body-expression.j
 cai expr set <httpNodeId> --prop <jsonBodyProp> --js-file body-expression.js --json
 ```
 
+MCP: pass the file contents inline as `js`; the set call uses `node_prop_set`.
+
 ## Same-type fallback
 
 ```js
@@ -115,6 +117,8 @@ Confirm the exact binding and field path in context.
 5. `cai expr decompile ...`
 6. `cai run node ... --json` for isolated destination configuration
 7. `cai run flow <flowId> ... --json` when the expression consumes a wired upstream input
-8. `cai exec ports <nodeExecutionId> --json`
+8. `cai exec node <nodeExecutionId> --full --json`
+
+MCP: step 4 uses `node_prop_set`; pass expression source and run inputs inline, and set `waitSeconds` on `run_node` or `run_flow` from 0 through 120.
 
 If compilation succeeds but runtime is null or partially empty, inspect `runScope`, the actual input value, and `resolvedConfigs`; do not keep rewriting syntax blindly. A node-only run cannot prove an `inputs.<name>` binding because it does not execute upstream nodes.

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

@@ -5,7 +5,7 @@ description: Design and configure Controller AI execution paths using only-when
 
 # Controller AI flow control
 
-In MCP hosts, send each exact literal `cai ...` command through the single `exec` tool; never translate it into another grammar.
+The `cai ...` examples are canonical grammar. Use the transport selected in `controllerai-start` and its MCP tool map; never mix transports in one task.
 
 Choose the primitive from the intended execution semantics before adding nodes.
 
@@ -73,7 +73,7 @@ For If/Else, order is behavior:
 cai branch reorder <ifElseNodeId> --order <conditionId1,conditionId2> --json
 ```
 
-List every condition branch exactly once and omit Else; the CLI keeps Else last. Router routes cannot be reordered because every match runs.
+List every condition branch exactly once and omit Else; the operation keeps Else last. Router routes cannot be reordered because every match runs.
 
 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.
 
@@ -97,9 +97,12 @@ Use repeatable `--item-field <id:type[:display]>` only when creating a new `cust
 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 CLI derives the not-yet-created loop input binding deterministically.
+- 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.
-- The runtime cap defaults to 500 items and accepts 1 through 10000. Set `--max-items` explicitly when the product requirement differs. The CLI creates the core scaffold 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.
+
+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:
 
@@ -108,6 +111,8 @@ 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.
@@ -127,6 +132,8 @@ 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.
 
 When paths converge, inspect the concrete graph and execution behavior. Do not assume wiring two paths to one action creates a barrier or waits for both. If the requirement is a true join, discover a join-capable component and verify it with representative branch timing.

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

@@ -40,6 +40,8 @@ One order may take all three routes. If that is not acceptable, use If/Else.
 
 Use `cai flow for-each` to create the item flow, typed item input, loop node, and list wiring atomically. First run `cai node get <sourceNodeId> --json`, choose the intended `outputs[]` entry, and pass its exact opaque `id` as `--source-output`; never pass its label or assume the first output. Omit list-selection flags when the whole selected output payload is a list; use `--list-field <nested.path>` for a list below `.data`; reserve `--list-js` for an exact advanced expression or `--js-file <path|->` for that expression in a UTF-8 file/stdin. The three selection forms are mutually exclusive.
 
+MCP: call `flow_for_each_scaffold` and pass expression source inline as `listJs`.
+
 The runtime limit defaults to 500 items and supports 1 through 10000. Use `--max-items` when the intended bound differs, then verify the returned read-back. Put meaningful work inside the generated body flow and declare body outputs before consuming aggregate results.
 
 Decide explicitly whether one child-flow failure should stop the sequential loop. Use `--continue-on-error` only when partial completion is acceptable and downstream logic handles failed iteration records. It does not recover a list or mapping expression that fails before an iteration starts.
@@ -52,6 +54,8 @@ Continue-on-error is for steps whose failure must not block the main path — no
 cai node continue-on-error <nodeId> --enable --json
 ```
 
+MCP: call `node_continue_on_error_set` with `enabled: true` or `enabled: false`.
+
 Wiring the Error output is OPTIONAL — add it when a failure needs explicit handling, not as a precondition:
 
 ```bash

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

@@ -5,9 +5,9 @@ description: Discover, connect, attach, update, and verify ready integration act
 
 # Controller AI integration actions
 
-In MCP hosts, send each exact literal `cai ...` command through the single `exec` tool; never translate it into another grammar.
+The `cai ...` examples are canonical grammar. Use the transport selected in `controllerai-start` and its MCP tool map; never mix transports in one task.
 
-Ready integration actions give a hosted agent one app operation without first building a workflow. Use only the `cai` commands below; do not call Controller AI REST or MCP routes directly.
+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.
 
 ## Choose direct action or workflow
 
@@ -19,10 +19,11 @@ Use a workflow tool instead when the capability needs multiple operations, trans
 
 ```bash
 cai integration search "<app or capability>" --json
-cai integration actions <integrationSlug> --search "<operation>" --json
+cai integration actions "<operation>" --integration <integrationSlug> --json
+cai integration action --integration <integrationSlug> --key <actionKey> --json
 ```
 
-Preserve the returned integration `slug` and action `key` exactly. Never derive either from a display label. Continue with `--after <nextCursor>` when pagination reports more results.
+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
 
@@ -30,25 +31,28 @@ Preserve the returned integration `slug` and action `key` exactly. Never derive
 cai connection list --integration <integrationSlug> --json
 ```
 
-Use an active connection whose `nodeSlug` exactly matches the integration. If none exists:
+Use an active connection whose `integration` exactly matches the integration slug. If none exists:
 
 ```bash
 cai connection connect <integrationSlug>
 ```
 
-The browser handoff keeps provider credentials out of the agent context. Re-list connections after the user finishes, then attach the action.
+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.
 
-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 `cai connection connect <slug>`. A raw endpoint mentioned by the user is background context, not an instruction to hand-roll the call.
+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
 
-The product default is to run without per-call approval. Do not accept that default mechanically. Inspect the action name, description, pricing, and intended use, then decide:
+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.
 
-- Require confirmation for deletion, purchases or spend, external communications, permission changes, irreversible writes, or an ambiguous destination.
+- 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.
 
-Tell the user which policy was selected and why when it has a meaningful consequence.
-
 ```bash
 cai agent add-action <agentId> \
   --integration <integrationSlug> \
@@ -59,7 +63,7 @@ cai agent add-action <agentId> \
   --json
 ```
 
-Omit `--require-confirmation` only after making the decision; the CLI still sends an explicit `false`. Do not attach the same action twice.
+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:
 
@@ -77,6 +81,8 @@ 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
@@ -88,6 +94,8 @@ 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.

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

@@ -5,7 +5,7 @@ description: Discover, initialize, configure, connect, and verify Controller AI
 
 # Controller AI node configuration
 
-In MCP hosts, send each exact literal `cai ...` command through the single `exec` tool; never translate it into another grammar.
+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 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.
 
@@ -14,15 +14,15 @@ A node is ready only after its component, connection, dependency-ordered props,
 ### 1. Find an exact component
 
 ```bash
-cai node find "<capability>" --json
-cai node component --node <nodeSlug> --key <nodeKey> --json
+cai integration actions "<capability>" --json
+cai integration action --integration <nodeSlug> --key <nodeKey> --json
 ```
 
-Use the returned `nodeSlug` and full `nodeKey`. Do not infer a component key from its display name. If discovery is broad, narrow it with:
+Use the returned `nodeSlug` and full `key`. Do not infer a component key from its display name. If discovery is broad, narrow it with:
 
 ```bash
-cai node search "<integration>" --actions --json
-cai node components "<action>" --node <nodeSlug> --json
+cai integration search "<integration>" --actions --json
+cai integration actions "<action>" --integration <nodeSlug> --json
 ```
 
 Inspect static prop metadata before creating the node. `required`, `remoteOptions`, and `reloadProps` determine configuration order.
@@ -35,12 +35,19 @@ If the component requires auth:
 cai connection list --node <nodeSlug> --json
 ```
 
-- One active connection: use its exact `connectionId`.
+- 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. Get the link with `cai connection connect <nodeSlug> --no-open` and share it with the user right away — do not start with `--wait`, which blocks until they finish and delays sharing the link. After they confirm, run `cai connection list --integration <nodeSlug> --json` and bind the new ID with `cai node set-connection <nodeId> --connection <connectionId>`.
+- 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
@@ -56,6 +63,8 @@ cai node init \
   --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.
@@ -91,6 +100,8 @@ Static value:
 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
@@ -99,8 +110,12 @@ 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
@@ -114,7 +129,7 @@ cai node set <nodeId> \
 
 `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: the CLI uses it to search providers that do not index opaque IDs, then verifies that the returned value still matches before writing. For a multi-select, pass a JSON array of returned values and one `--label` argument per value, in the same order. The CLI supplies the persisted label shape, chooses the correct expression storage channel, and verifies read-back.
+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:
 
@@ -146,14 +161,20 @@ 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.

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

@@ -13,7 +13,7 @@ The JSON response reports:
 - `readyForExpressions`: connection and required/reload props are complete. The source still must be wired before its binding appears in expression context.
 - `readyForRun`: connection and required/reload props are complete; running may be the step that discovers a concrete output type.
 - `readyForDownstreamExpressions`: the node is runnable and its actual process output type is concrete enough for downstream field bindings.
-- `next`: the CLI's exact next diagnostic command.
+- `next`: the canonical next diagnostic command.
 
 Follow `next`, then read status again. Do not treat `readyForRun` as proof that downstream fields are typed; require `readyForDownstreamExpressions` for that.
 
@@ -26,6 +26,8 @@ cai node set-connection <nodeId> --connection <connectionId> --json
 cai node status <nodeId> --json
 ```
 
+MCP: replace `cai connection connect` with `connection_connect_url { nodeSlug }`; the other calls map directly.
+
 ## Prop channels
 
 Use `cai node set`; it selects the persisted shape from live metadata.
@@ -36,6 +38,8 @@ Use `cai node set`; it selects the persisted shape from live metadata.
 | Dynamic text, JSON text, or custom data | `--js` | `valueJs` |
 | Dynamic non-text prop with expression mode | `--js` | `expressionValueJs` |
 
+MCP: both `cai node set` and `cai expr set` use `node_prop_set`; pass exactly one of `value`, `js`, or `rawExpressionJson`.
+
 Do not force a channel with internal fields. `cai node set` and `cai expr set` compile first and verify the actual channel after writing.
 
 ## Option-backed props
@@ -55,7 +59,7 @@ cai node options <nodeId> --prop <name> --query "<specific search>" --json
 cai node set <nodeId> --prop <name> --value '<option.value>' --label '<option.label>' --json
 ```
 
-Pass the value and label from the same live option. Remote providers often search labels rather than opaque values, so omitting `--label` can make a valid copied ID impossible to re-verify. For multi-select, pass a JSON array of returned values plus one `--label` argument per value in matching order. The CLI constructs the required array of `{value,label}` records for read-back/UI compatibility.
+Pass the value and label from the same live option. Remote providers often search labels rather than opaque values, so omitting `--label` can make a valid copied ID impossible to re-verify. For multi-select, pass a JSON array of returned values plus one `--label` argument per value in matching order. The write constructs the required array of `{value,label}` records for read-back/UI compatibility.
 
 Continue a provider page with the opaque context printed by the previous call:
 
@@ -103,4 +107,6 @@ An unresolved output blocks trustworthy downstream field expressions. Resolve it
 
 After the run, read `cai node status` and `cai expr context` again. Do not infer fields from an example response alone if the platform did not adopt a concrete type.
 
-`cai run node` and `cai run flow` pass the exact completed node-execution ID back to the backend. The backend verifies ownership, workflow, node, component snapshot, and terminal status, then derives the persisted output shape; callers never supply the type name. Adoption updates only that non-static node, so separate instances of generic components such as HTTP can learn different schemas. Inspect `outputTypeAdoption`/`outputTypeAdoptions` in the run result. If it reports `no_observed_output`, use a representative input that returns data and rerun. If it reports `error`, stop and surface that error rather than inventing a schema.
+Completed node and flow runs pass the exact node-execution ID back for ownership, workflow, node, component-snapshot, and terminal-status checks before deriving the persisted output shape; callers never supply the type name. Adoption updates only that non-static node, so separate instances of generic components such as HTTP can learn different schemas. Inspect `outputTypeAdoption`/`outputTypeAdoptions` in the run result. If it reports `no_observed_output`, use a representative input that returns data and rerun. If it reports `error`, stop and surface that error rather than inventing a schema.
+
+MCP: `run_node` and `run_flow` take `inputs` inline and `waitSeconds` from 0 through 120.

package/skills/controllerai-runs/SKILL.md

@@ -5,7 +5,7 @@ description: Run and debug Controller AI nodes on development and flows on devel
 
 # Controller AI runs
 
-In MCP hosts, send each exact literal `cai ...` command through the single `exec` tool; never translate it into another grammar.
+The `cai ...` examples are canonical grammar. Use the transport selected in `controllerai-start` and its MCP tool map; never mix transports in one task.
 
 Think "real run", not "simulation". `run node` always uses development; `run flow` defaults to development and can target the published live version. Both rails execute real integration actions (messages send, records change, provider usage is spent); development isolation covers the data store only. Running is a required part of building — one successful run is how a dynamic node's output type gets resolved for the next step — so mitigate risk before running.
 
@@ -23,6 +23,8 @@ If the user declines running the action, accept it. Then keep the build honest:
 cai node declare-output <nodeId> --sample-file shape.json
 ```
 
+MCP: call `node_output_type_declare` with parsed JSON in `sample`; the server cannot read `shape.json`.
+
 — where `shape.json` is a representative response object from the provider's API reference. The contract is marked `declared (unverified)`; the first real completed run verifies and upgrades it automatically. State clearly that it is unverified until then, and make the first live run the explicit verification step. Never silently skip the question and never present an unrun action as verified.
 
 ## First live run is part of development
@@ -33,6 +35,8 @@ After publishing, run the published version directly under supervision:
 cai run flow <flowId> --inputs values.json --target live --confirm-live --json
 ```
 
+MCP: pass parsed values in `inputs` and set `waitSeconds` on `run_flow`.
+
 This command fires external actions and spends usage. For risky sends, build the safe-audience harness: branch on the `isLiveVersion` data source with If/Else — the false branch targets the developer (own email/channel), the true branch targets the real audience. Use this direct live run for explicit verification; do not wait for a real trigger event.
 
 ## Prepare exact run inputs
@@ -42,7 +46,7 @@ cai run inputs <nodeId> --json
 cai run inputs <flowId> --flow --json
 ```
 
-Use returned opaque input IDs. Flow mode lists EVERY declared input with a `used` flag: supply the used ones (an unsupplied used input falls back to its saved test value), while values keyed to unused inputs are accepted and ignored. A compact input file can be a flat map:
+Use returned opaque input IDs. Flow mode lists EVERY declared input with a `used` flag: supply the used ones (an unsupplied used input falls back to its saved test value), while values keyed to unused inputs are accepted and ignored. The input object can be a flat map; the CLI may load it from a file:
 
 ```json
 {
@@ -65,9 +69,11 @@ cai run node <nodeId> --inputs values.json --json
 cai run flow <flowId> --inputs values.json --json
 ```
 
+MCP: pass parsed values in `inputs` and set `waitSeconds` on `run_node` or `run_flow`.
+
 `run node` is deliberately isolated: it does not execute wired upstream nodes. Read its `runScope`. If `endToEndValidationRequired` is true, values derived from upstream can be empty even when the selected node is green; do not accept that run as expression proof. `run flow` is the end-to-end check that executes upstream wiring.
 
-The CLI waits for a terminal execution state. Capture `workflowExecutionId` and `nodeExecutionId` from the result.
+The CLI waits for a terminal execution state by default. MCP polling is bounded by `waitSeconds` and may return an unfinished execution ID. Capture `workflowExecutionId` and `nodeExecutionId` from the result.
 
 For every node test, inspect:
 
@@ -75,7 +81,7 @@ For every node test, inspect:
 - `skipReason`
 - `runScope`, especially `upstreamNodesExecuted` and `endToEndValidationRequired`
 - `resolvedConfigs`
-- `resolvedConfigs[].resolutionWarnings`: trust every structured entry; `[]` is authoritatively clean. Runs also surface entries on stderr, so read stderr even when the execution completed.
+- `resolvedConfigs[].resolutionWarnings`: trust every structured entry; `[]` is authoritatively clean. Also read any transport warnings; CLI runs may mirror them on stderr.
 - `outputTypeAdoption`: the server verifies the exact completed `nodeExecutionId`, derives its persisted output shape, and updates only that non-static node. `adopted` or `already_typed` lets the next `node status` converge; `no_observed_output` means the representative run returned no reusable shape. `adoptedNodeIds` must be empty or contain only the tested node; stop if it names a sibling.
 - output shape and values
 
@@ -84,14 +90,16 @@ A dynamic prop with a null/empty resolved config is a failure even when status i
 ## Debug from the execution tree
 
 ```bash
-cai exec tree <workflowExecutionId> --json
+cai exec tree <workflowExecutionId> --limit 50 --json
 cai exec get <workflowExecutionId> --json
 cai exec flow <flowExecutionId> --json
-cai exec node <nodeExecutionId> --json
-cai exec ports <nodeExecutionId> --json
+cai exec node <nodeExecutionId> --full --json
 ```
 
-Use the tree to locate the first unexpected status. Use ports to compare actual inputs, resolved configuration, and outputs at that node. Read [references/debugging.md](references/debugging.md) for the fault-isolation order.
+Page with the returned `nextCursor` via `--cursor`; narrow large runs with repeatable `--status`
+or `--flow <flowId>`. Use the tree to locate the first unexpected status. Use the full node
+execution to inspect its status, resolved configuration, and untruncated output. Read
+[references/debugging.md](references/debugging.md) for the fault-isolation order.
 
 ## Output discovery
 
@@ -106,13 +114,15 @@ cai run discover \
   --json
 ```
 
-This calls the real third-party action and spends usage. For a destructive action, do not probe merely to learn its output — first ask the user for a safe target (see "Consequential actions" above); if they decline, declare the expected shape instead. Use `--keep` only when the user wants the scratch node retained.
+MCP: `run_discover` always removes the scratch graph and exposes neither `keep` nor `waitSeconds`.
+
+This calls the real third-party action and spends usage. For a destructive action, do not probe merely to learn its output — first ask the user for a safe target (see "Consequential actions" above); if they decline, declare the expected shape instead. On CLI, use `--keep` only when the user wants the scratch node retained.
 
 After successful output discovery, re-read `cai node status` and downstream `cai expr context`; verify the adopted output type is concrete.
 
 ## Completion gate
 
-- Gate scripts on `cai workflow validate`; it exits 1 when the response has `valid: false`.
+- CLI scripts may gate on `cai workflow validate` exiting 1; MCP callers inspect `valid` and `errors`.
 - The test exercised the changed path with credible values.
 - The first unexpected node, if any, was identified rather than inferred from the final error.
 - All dynamic configs resolved to intended values.