@controllerai/cli 0.2.13 → 0.2.15

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

@@ -5,7 +5,9 @@ description: Discover, connect, attach, update, and verify ready integration act
 
 # Controller AI integration actions
 
-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.
+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 the canonical operations below through the selected transport; do not call Controller AI REST routes directly.
 
 ## Choose direct action or workflow
 
@@ -17,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
 
@@ -28,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.
+
+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 `cai connection connect <slug>`. A raw endpoint mentioned by the user is background context, not an instruction to hand-roll the call.
+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> \
@@ -57,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:
 
@@ -75,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
@@ -86,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,6 +5,8 @@ description: Discover, initialize, configure, connect, and verify Controller AI
 
 # Controller AI node configuration
 
+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.
 
 ## Deterministic sequence
@@ -12,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.
@@ -33,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
@@ -54,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.
@@ -89,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
@@ -97,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
@@ -112,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:
 
@@ -144,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,6 +5,8 @@ description: Run and debug Controller AI nodes on development and flows on devel
 
 # Controller AI runs
 
+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.
 
 ## Consequential actions: mitigate with the user, don't refuse
@@ -21,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
@@ -31,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
@@ -40,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
 {
@@ -63,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:
 
@@ -73,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
 
@@ -82,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
 
@@ -104,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.

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

@@ -11,26 +11,30 @@ cai flow get <flowId> --json
 
 Node runs use development. Flow runs default to development; `cai run flow <flowId> --target live --confirm-live` runs the published version. Trigger replay also defaults to development and uses the same flags for live. Every rail can call real providers and create external effects.
 
+MCP: `run_flow` takes `waitSeconds` and may return before the execution is terminal.
+
 ## 2. Find the first divergence
 
 ```bash
-cai exec tree <workflowExecutionId> --json
+cai exec tree <workflowExecutionId> --limit 50 --json
 ```
 
-Classify each node as completed, failed, skipped intentionally, skipped unexpectedly, or absent. The first divergence is usually the cause; later failures are often consequences.
+Follow `nextCursor` with `--cursor`, and use repeatable `--status` or `--flow <flowId>` when the
+run is large. Classify each node as completed, failed, skipped intentionally, skipped unexpectedly,
+or absent. The first divergence is usually the cause; later failures are often consequences.
 
 ## 3. Inspect the node boundary
 
 ```bash
-cai exec ports <nodeExecutionId> --json
+cai exec node <nodeExecutionId> --full --json
 ```
 
 Check:
 
-1. Inputs: did the expected upstream value arrive?
-2. Configs: did each expression resolve, and to the correct type/value?
-3. Outputs: did the component return the promised shape?
-4. Status/error: did the provider or engine reject the call?
+1. Resolved configs: did each expression resolve, and to the correct type/value?
+2. Output: did the component return the promised shape and value?
+3. Status/error: did the provider or engine reject the call?
+4. Upstream execution rows and wiring: did every expected producer run and connect to this node?
 
 ## 4. Fix by category
 

package/skills/controllerai-start/SKILL.md

@@ -1,23 +1,46 @@
 ---
 name: controllerai-start
-description: Connect, orient, and route work across Controller AI agents and no-code automations. Use when starting a Controller AI coding-agent session, after `cai connect`, or when deciding whether an outcome should be a ready integration action, a workflow, an agent, or a combination.
+description: Connect, orient, and route work across Controller AI agents and no-code automations. Use when starting a Controller AI coding-agent or MCP session, after `cai connect`, or when deciding whether an outcome should be a ready integration action, a workflow, an agent, or a combination.
 ---
 
 # Start with Controller AI
 
-Use the installed `cai` CLI as the supported platform interface. Do not call Controller AI REST or MCP routes directly.
+## Transports
+
+The `cai ...` examples are canonical grammar. Use either the CLI or the typed MCP tools for a task; never mix transports within one task.
+
+MCP tool names are domain-first snake_case derived from CLI command paths (`cai flow input add` -> `flow_input_add`). Read [references/mcp-tool-map.md](references/mcp-tool-map.md) for every command and reviewed exception. MCP has no workflow pin: pass `workflowId` on every workflow-scoped tool. Long-running MCP tools take `waitSeconds` (default 60, maximum 120) instead of CLI wait or timeout flags.
+
+Local CLI setup commands do not exist on MCP. Use `account_status` for `auth status` and `doctor`, `account_claim_start`/`account_claim_verify` for email claiming, and `guide_list`/`guide_get` for bundled skills. `cai connect`, root `cai signup`, `cai auth login` and other local auth mutations, `cai skills install`, `cai skills update`, `cai use`, `cai config reset`, and `cai connection request` remain local-only; `cai agent present` and `cai file share` stay available to the in-app builder while hosted MCP uses their equivalents below.
+
+- **Connect:** Call `connection_connect_url`, show its `url` as a markdown link, ask the user to finish connecting, then confirm with `connection_list` using its `integration`.
+- **Finished agent:** Call `agent_present` and relay the returned agent card, including its link.
+- **File for the user:** Call `file_share` and relay its returned link; Claude Code users may also just read it from the terminal.
+
+## Your account on MCP
+
+Call `account_status` first. During OAuth, the user explicitly chose **My Controller account** or **Separate agent account**; do not infer that choice from browser state. In your first reply, say which account `account_status` reports they are using. If it is an unclaimed agent account, offer to claim it with their email at any time. Never ask for passwords—the claim uses the 6-digit code sent to their email. After a successful claim, tell them they can open the app URL from `account_status`, choose **Forgot password** with that email, set a password, and sign in to the same workspace.
 
 ## Confirm the setup
 
-Run:
+On the CLI, run:
 
 ```bash
 cai doctor
 ```
 
-If authentication is missing and the human already has an account, run `cai connect`. If no account exists, run `cai signup` to create a provisional workspace and start building immediately. Unverified signup has a small usage cap ($1 by default — `cai signup` prints the exact amount), and workflow and agent publishing stay locked until email verification. When ready to publish or when the cap bites, run `cai signup email <address>`, ask the human account owner for the 6-digit code delivered to their inbox (never guess it), then run `cai signup verify <code>`. If agent signup is disabled, ask the human to register at https://app.getcontroller.ai/register, then run `cai connect`.
+MCP: use `account_status`; local diagnosis, login, and `cai connect` do not exist.
+
+On the CLI, if authentication is missing and the human already has an account, run `cai connect`. If no account exists, run `cai signup` to create a provisional workspace and start building immediately. An unclaimed signup has the same functional access as a free account, including workflow and agent publishing; its workspace is not automatically deleted, and it has a $1 monthly usage cap (`cai signup` prints the exact amount). Email claiming is optional: run `cai signup email <address>`, ask the human account owner for the 6-digit code delivered to their inbox (never guess it), then run `cai signup verify <code>` to raise the monthly cap to $5 and enable durable account recovery. If agent signup is disabled, ask the human to register at https://app.getcontroller.ai/register, then run `cai connect`.
+
+MCP: the OAuth caller is already provisioned; use `account_claim_start` and `account_claim_verify` for optional email claiming.
+
+On the CLI, if `cai doctor` reports missing, stale, or damaged managed skills, run `cai skills update`, then run `cai doctor` again. When the `CLI version` row says a newer cai is available, upgrade before continuing (`npm install -g @controllerai/cli@latest`, then `cai skills update`) — new versions carry fixes the rest of these skills assume. Skill updates are setup maintenance, not a step to repeat during every build.
+
+MCP: use `guide_list` and `guide_get`; skill installation, updates, and CLI upgrades are not hosted-session steps. Never ask the user to paste a password, provider token, or Controller AI credential into chat.
 
-If `cai doctor` reports missing, stale, or damaged managed skills, run `cai skills update`, then run `cai doctor` again. When the `CLI version` row says a newer cai is available, upgrade before continuing (`npm install -g @controllerai/cli@latest`, then `cai skills update`) — new versions carry fixes the rest of these skills assume. Skill updates are setup maintenance, not a step to repeat during every build. Never ask the user to paste a password, provider token, or Controller AI credential into chat.
+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.
 
 ## Route the outcome
 
@@ -36,14 +59,14 @@ If the user's outcome does not reveal whether they want an agent or an automatio
 
 ## Platform docs
 
-The platform reference lives at https://docs.getcontroller.ai. Fetch https://docs.getcontroller.ai/llms.txt for the machine-readable index of every page; append `.md` to any page path for raw markdown (for example https://docs.getcontroller.ai/start/safety.md), or fetch /llms-full.txt for the whole corpus at once. Skills remain the procedural authority — consult the docs for what they do not carry: the execution and cost models, type-system and version-rail contracts, the full CLI and expression-operation references, and the workflow API. When a docs page and a skill disagree, prefer the skill and its live CLI queries (`cai expr ops`, `cai node find`).
+The platform reference lives at https://docs.getcontroller.ai. Fetch https://docs.getcontroller.ai/llms.txt for the machine-readable index of every page; append `.md` to any page path for raw markdown (for example https://docs.getcontroller.ai/start/safety.md), or fetch /llms-full.txt for the whole corpus at once. Skills remain the procedural authority — consult the docs for what they do not carry: the execution and cost models, type-system and version-rail contracts, the full CLI and expression-operation references, and the workflow API. When a docs page and a skill disagree, prefer the skill and its live platform queries (`cai expr ops`, `cai integration actions`).
 
 ## Keep rails explicit
 
 - Agent Test mode uses the owner's mutable draft, current workflow development heads, current draft knowledge, and live runtime files overlaid by development/test runtime files. Live mode uses the latest published agent version, each workflow's latest live release, frozen published knowledge, and live runtime files only.
 - Agent draft edits require another agent publish to reach Live. Publishing restamps existing live conversations; shared users always receive the latest published version and never the draft.
 - Workflow publishes and direct-action connection/authorization grants are live bindings: a rebind can redirect Live, while revocation or detachment can block Live without another agent publish.
-- Local coding-agent subscriptions cover builder reasoning, not Controller AI hosted-agent runtime usage.
+- Coding-agent subscriptions cover builder reasoning, not Controller AI hosted-agent runtime usage.
 - Provider actions can send messages, mutate or delete records, and incur provider charges. Decide the per-action confirmation policy before attaching one.
 - Never publish, share with the organization, replay a live trigger, or perform a consequential external test without clear user intent.
 - When a platform limitation blocks the outcome, STOP and report the partial result with the blocking error; never keep probing until the clock expires.