@controllerai/cli 0.2.17 → 0.2.20

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).