@controllerai/cli 0.2.14 → 0.2.16

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,25 +1,53 @@
 ---
 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
 
-In MCP hosts, send each exact literal `cai ...` command through the single `exec` tool; never translate it into another grammar.
+## Transports
 
-Use the installed `cai` CLI as the supported platform interface. Do not call Controller AI REST or MCP routes directly.
+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. 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`.
+For a new terminal assistant, `cai agent setup` detects Claude Code, Codex, and
+Cursor, ensures login, and installs the best available plugin or MCP-and-skills
+fallback; use `cai agent setup --status --json` for a read-only machine plan.
+Use `cai doctor` to compare installed version stamps and see the exact update
+command, and `cai docs [path]` (or `cai docs --list`) to read platform docs in
+the terminal.
+
+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, run `cai upgrade` before continuing — it prints the explicit CLI install command and updates detected skills, and 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
 
@@ -38,14 +66,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.

package/skills/controllerai-start/references/mcp-tool-map.md

@@ -0,0 +1,170 @@
+<!-- Generated by cli/scripts/generate-mcp-tool-map.mjs; do not edit by hand. -->
+
+# CLI to typed MCP tool map
+
+This registry-derived map covers 162 CLI commands and 149 typed MCP tools. CLI examples remain the canonical grammar; typed MCP calls use the tool and camelCase parameters shown here. Global `--json` and `--api-url` flags are host-controlled and omitted.
+
+| `cai` command | MCP tool | Parameter mapping | Notes |
+| --- | --- | --- | --- |
+| `cai agent add-action` | `agent_tool_action_add` | `<agentId>` → `agentId`; `--action` → `action`; `--connection` → `connectionId`; `--description` → `description`; `--integration` → `integration`; `--require-confirmation` → `requireConfirmation` | — |
+| `cai agent add-file` | `agent_knowledge_file_add`<br>`agent_workspace_file_add` | `agent_knowledge_file_add`: `<agentId>` → `agentId`; `--file` → `content` (inline content); `--name` → `name`; `--type` → `type`<br>`agent_workspace_file_add`: `<agentId>` → `agentId`; `--file` → `content` (inline content); `--name` → `name`; `--space` → `space`; `--type` → `type` | split across typed tools |
+| `cai agent add-workflow` | `agent_tool_workflow_add` | `<agentId>` → `agentId`; `--description` → `description`; `--flow` → `flow`; `--require-confirmation` → `requireConfirmation`; `--workflow-id` → `workflowId` | — |
+| `cai agent conversation approve` | `agent_conversation_approve` | `<conversationId>` → `conversationId`; `--request` → `requestId` | — |
+| `cai agent conversation create` | `agent_conversation_create` | `<agentId>` → `agentId`; `--model` → `model`; `--title` → `title`; `--draft` → `rail=draft`; `--live` → `rail=live` | — |
+| `cai agent conversation deny` | `agent_conversation_deny` | `<conversationId>` → `conversationId`; `--message` → `message`; `--request` → `requestId` | — |
+| `cai agent conversation history` | `agent_conversation_history` | `<conversationId>` → `conversationId`; `--last` → `last` | — |
+| `cai agent conversation list` | `agent_conversation_list` | `<agentId>` → `agentId`; `--mode` → `mode` | — |
+| `cai agent conversation send` | `agent_conversation_send` | `<conversationId>` → `conversationId`; `--message` → `message`; `--timeout` → `waitSeconds` | `waitSeconds` default 60, max 120 |
+| `cai agent conversation status` | `agent_conversation_status` | `<conversationId>` → `conversationId` | — |
+| `cai agent create` | `agent_create` | `--disabled` → `disabled`; `--instructions` / `--instructions-file` → `instructions` (inline content); `--name` → `name` | — |
+| `cai agent delete` | `agent_delete` | `<agentId>` → `agentId` | — |
+| `cai agent files` | `agent_file_list` | `<agentId>` → `agentId`; `--cursor` → `cursor`; `--environment` → `environment`; `--folder-prefix` → `folderPrefix`; `--limit` → `limit`; `--live` → `live`; `--search` → `search`; `--space` → `space` | — |
+| `cai agent get` | `agent_get` | `<agentId>` → `agentId` | — |
+| `cai agent list` | `agent_list` | `--ownership` → `ownership`; `--search` → `search` | — |
+| `cai agent present` | `agent_present` | `<agentId>` → `agentId`; `note` (MCP-only) → `note` | hosted: Returns a hosted agent summary and app link for the MCP host to present. |
+| `cai agent publish` | `agent_publish` | `<agentId>` → `agentId`; `--name` → `name` | — |
+| `cai agent publish-preflight` | `agent_publish_preflight` | `<agentId>` → `agentId` | — |
+| `cai agent remove-tool` | `agent_tool_remove` | `<agentId>` → `agentId`; `--tool` → `toolId` | — |
+| `cai agent test` | `agent_test` | `<agentId>` → `agentId`; `--message` → `message`; `--model` → `model`; `--timeout` → `waitSeconds`; `--title` → `title`; `--draft` → `rail=draft`; `--live` → `rail=live` | `waitSeconds` default 60, max 120 |
+| `cai agent tools` | `agent_tool_list` | `<agentId>` → `agentId` | — |
+| `cai agent update` | `agent_set_enabled`<br>`agent_update` | `agent_set_enabled`: `<agentId>` → `agentId`; `--enabled` / `--disabled` → `enabled`<br>`agent_update`: `<agentId>` → `agentId`; `--instructions` / `--instructions-file` → `instructions` (inline content); `--name` → `name` | split across typed tools |
+| `cai agent update-tool` | `agent_tool_update` | `<agentId>` → `agentId`; `--connection` → `connectionId`; `--description` → `description`; `--require-confirmation` / `--no-confirmation` → `requireConfirmation`; `--tool` → `toolId` | — |
+| `cai agent versions` | `agent_version_list` | `<agentId>` → `agentId` | — |
+| `cai agent visibility` | `agent_visibility_set` | `<agentId>` → `agentId`; `--value` → `value` | — |
+| `cai approval resume` | `approval_resume` | `<id>` → `approvalId`; `waitSeconds` (MCP-only) → `waitSeconds` | `waitSeconds` default 60, max 120 |
+| `cai auth key` | — | — | dropped: Mints a long-lived local credential and is not an MCP account operation. |
+| `cai auth login` | — | — | dropped: Starts a local device-code login even though the MCP request is already OAuth-authorized. |
+| `cai auth logout` | — | — | dropped: Deletes local CLI credentials; it is not integration connection revocation. |
+| `cai auth password` | — | — | dropped: Accepts a development email/password credential on the local machine. |
+| `cai auth status` | `account_status` | — | hosted: The host reports the authenticated grant and combines it with server health facts. |
+| `cai auth token` | — | — | dropped: Writes a bearer token into local CLI configuration. |
+| `cai branch add` | `branch_add` | `<nodeId>` → `nodeId`; `--allow-duplicate` → `allowDuplicate`; `--condition-json` → `conditionJson`; `--js` / `--js-file` → `js` (inline content); `--name` → `name`; `--workflow` → `workflowId` | — |
+| `cai branch connect` | `branch_connect` | `<nodeId>` → `nodeId`; `--flow` → `flow`; `--route` → `branchId`; `--to` → `to`; `--workflow` → `workflowId` | — |
+| `cai branch delete` | `branch_delete` | `<nodeId>` → `nodeId`; `--route` → `branchId`; `--workflow` → `workflowId` | — |
+| `cai branch list` | `branch_list` | `<nodeId>` → `nodeId`; `--workflow` → `workflowId` | — |
+| `cai branch reorder` | `branch_reorder` | `<nodeId>` → `nodeId`; `--order` → `order`; `--workflow` → `workflowId` | — |
+| `cai branch update` | `branch_update` | `<nodeId>` → `nodeId`; `--condition-json` → `conditionJson`; `--js` / `--js-file` → `js` (inline content); `--name` → `name`; `--route` → `branchId`; `--workflow` → `workflowId` | — |
+| `cai config reset` | — | — | dropped: Clears a local workflow pin; typed MCP calls are stateless. |
+| `cai connect` | — | — | dropped: Installs local skills, opens a browser, and verifies a local project. |
+| `cai connection connect` | `connection_connect_url` | `<nodeSlug>` → `nodeSlug` | — |
+| `cai connection delete` | `connection_delete` | `<connectionId>` → `connectionId` | — |
+| `cai connection list` | `connection_list` | `--integration` → `integration` | — |
+| `cai connection request` | — | — | dropped: Posts a connect card into build chat; connection_connect_url supplies the hosted outcome. |
+| `cai connection update` | `connection_update` | `<connectionId>` → `connectionId`; `--name` → `displayName`; `--default` / `--no-default` → `isDefault` | — |
+| `cai data collection create` | `schema_type_create` | `<dataType>` → `name`; `--display` → `display`; `--field` → `field`; `--from-json` → `fromJson` (inline content); `--workflow` → `workflowId` | merged: The CLI command is sugar over schema create; no separate collection-create route exists. |
+| `cai data collections` | `data_collection_list` | `--env` → `env`; `--workflow` → `workflowId` | — |
+| `cai data copy-to-live` | `data_copy_to_live` | `--type` → `type`; `--workflow` → `workflowId`; `env` (MCP-only) → `env` | `env` required |
+| `cai data create` | `data_record_create` | `--env` → `env`; `--fields` → `fields`; `--type` → `type`; `--workflow` → `workflowId` | `env` required |
+| `cai data delete` | `data_record_delete` | `<recordId>` → `recordId`; `--env` → `env`; `--type` → `type`; `--workflow` → `workflowId` | `env` required |
+| `cai data delete-many` | `data_record_delete_many` | `--all` → `all`; `--env` → `env`; `--records` → `recordIds`; `--type` → `type`; `--workflow` → `workflowId` | `env` required |
+| `cai data fields` | `data_field_list` | `--type` → `type`; `--workflow` → `workflowId` | — |
+| `cai data get` | `data_record_get` | `<recordId>` → `recordId`; `--env` → `env`; `--type` → `type`; `--workflow` → `workflowId` | — |
+| `cai data import` | `data_record_import_commit`<br>`data_record_import_validate` | `data_record_import_commit`: `--env` → `env`; `--file` → `content` (inline content); `--type` → `type`; `--workflow` → `workflowId`<br>`data_record_import_validate`: `--env` → `env`; `--file` → `content` (inline content); `--type` → `type`; `--workflow` → `workflowId` | split across typed tools; `env` required |
+| `cai data query` | `data_record_query` | `--env` → `env`; `--limit` → `limit`; `--offset` → `offset`; `--query` → `query`; `--type` → `type`; `--workflow` → `workflowId` | — |
+| `cai data update` | `data_record_update` | `<recordId>` → `recordId`; `--env` → `env`; `--fields` → `fields`; `--type` → `type`; `--workflow` → `workflowId` | `env` required |
+| `cai deps` | `dependency_map` | `--workflow` → `workflowId` | — |
+| `cai doctor` | `account_status` | — | hosted: Local runtime checks do not apply; useful account and version facts are in account_status. |
+| `cai events` | `event_list` | `--cursor` → `cursor`; `--limit` → `limit`; `--since` → `since`; `--type` → `type`; `--for-workflow` / `--workflow` → `workflowId` | — |
+| `cai exec flow` | `execution_flow_get` | `<flowExecutionId>` → `flowExecutionId`; `--workflow` → `workflowId` | — |
+| `cai exec get` | `execution_get` | `<workflowExecutionId>` → `workflowExecutionId`; `--workflow` → `workflowId` | — |
+| `cai exec list` | `execution_list` | `--limit` → `limit`; `--workflow` → `workflowId` | — |
+| `cai exec node` | `execution_node_get` | `<nodeExecutionId>` → `nodeExecutionId`; `--full` → `full`; `--workflow` → `workflowId` | — |
+| `cai exec tree` | `execution_tree` | `<workflowExecutionId>` → `workflowExecutionId`; `--cursor` → `cursor`; `--flow` → `flowId`; `--limit` → `limit`; `--status` → `status`; `--workflow` → `workflowId` | — |
+| `cai expr context` | `expr_context` | `<nodeId>` → `nodeId`; `--methods` → `methods`; `--prop` → `prop`; `--workflow` → `workflowId` | — |
+| `cai expr decompile` | `expr_decompile` | `<nodeId>` → `nodeId`; `--prop` → `prop`; `--workflow` → `workflowId` | — |
+| `cai expr ops` | `expr_operation_list` | `--type` → `type`; `--workflow` → `workflowId` | — |
+| `cai expr set` | `node_prop_set` | `<nodeId>` → `nodeId`; `--js` / `--js-file` → `js` (inline content); `label` (MCP-only) → `label`; `--prop` → `prop`; `rawExpressionJson` (MCP-only) → `rawExpressionJson`; `value` (MCP-only) → `value`; `--workflow` → `workflowId`; `valueJson` (MCP-only) → `valueJson` | merged: node_prop_set exposes the same expression write alongside literal and raw-expression forms. |
+| `cai expr validate` | `expr_validate` | `<nodeId>` → `nodeId`; `--js` / `--js-file` → `js` (inline content); `--mode` → `mode`; `--prop` → `prop`; `--workflow` → `workflowId` | — |
+| `cai file share` | `file_share` | `--name` → `name`; `content` (MCP-only) → `content`; `encoding` (MCP-only) → `encoding`; `mimeType` (MCP-only) → `mimeType` | hosted: Stores inline bytes as a private artifact and returns its browser-openable link. |
+| `cai flow create` | `flow_create` | `--name` → `name`; `--workflow` → `workflowId` | — |
+| `cai flow delete` | `flow_delete` | `<flowId>` → `flowId`; `--workflow` → `workflowId` | — |
+| `cai flow duplicate` | `flow_duplicate` | `<flowId>` → `flowId`; `--workflow` → `workflowId` | — |
+| `cai flow for-each` | `flow_for_each_scaffold` | `--continue-on-error` → `continueOnError`; `--flow` → `flow`; `--from` → `from`; `--item-field` → `itemField`; `--item-name` → `itemName`; `--item-type` → `itemType`; `--list-field` → `listField`; `--list-js` / `--js-file` → `listJs` (inline content); `--max-items` → `maxItems`; `--name` → `name`; `--source-output` → `sourceOutput`; `--workflow` → `workflowId` | — |
+| `cai flow get` | `flow_get` | `<flowId>` → `flowId`; `--workflow` → `workflowId` | — |
+| `cai flow input add` | `flow_input_add` | `<flowId>` → `flowId`; `--description` → `description`; `--display` → `display`; `--list` → `list`; `--optional` → `optional`; `--type` → `type`; `--workflow` → `workflowId` | — |
+| `cai flow input delete` | `flow_input_delete` | `<flowId>` → `flowId`; `--input` → `input`; `--workflow` → `workflowId` | — |
+| `cai flow input update` | `flow_input_update` | `<flowId>` → `flowId`; `--default-value` → `defaultValue`; `--description` → `description`; `--display` → `display`; `--input` → `input`; `--name` → `name`; `--optional` / `--required` → `optional`; `--type` → `type`; `--workflow` → `workflowId` | — |
+| `cai flow layout` | `flow_layout` | `<flowId>` → `flowId`; `--workflow` → `workflowId` | — |
+| `cai flow list` | `flow_list` | `--workflow` → `workflowId` | — |
+| `cai flow output add` | `flow_output_add` | `<flowId>` → `flowId`; `--description` → `description`; `--display` → `display`; `--name` → `name`; `--type` → `type`; `--workflow` → `workflowId` | — |
+| `cai flow output delete` | `flow_output_delete` | `<flowId>` → `flowId`; `--output` → `output`; `--workflow` → `workflowId` | — |
+| `cai flow output update` | `flow_output_update` | `<flowId>` → `flowId`; `--description` → `description`; `--display` → `display`; `--name` → `name`; `--output` → `output`; `--type` → `type`; `--workflow` → `workflowId` | — |
+| `cai flow outputs` | `flow_output_list` | `<flowId>` → `flowId`; `--workflow` → `workflowId` | — |
+| `cai flow rename` | `flow_rename` | `<flowId>` → `flowId`; `--name` → `name`; `--workflow` → `workflowId` | — |
+| `cai flow reorder` | `flow_reorder` | `--order` → `order`; `--workflow` → `workflowId` | — |
+| `cai integration action` | `integration_action_get` | `--integration` → `integration`; `--key` → `key` | — |
+| `cai integration actions` | `integration_action_list` | `<query>` → `query`; `--integration` → `integration`; `--limit` → `limit` | — |
+| `cai integration search` | `integration_search` | `<query>` → `query`; `--limit` → `limit`; `--actions` → `kind=actions`; `--events` → `kind=events`; `` → `kind=all` | — |
+| `cai label list` | `label_list` | — | — |
+| `cai label set` | `label_set` | `--agent` → `agentId`; `--labels` / `--label` / `--none` → `labels`; `--workflow` → `workflowId` | — |
+| `cai node add` | `node_add` | `--after` → `after`; `--connection` → `connection`; `--enable-prop` → `enableProp`; `--flow` → `flow`; `--key` → `key`; `--name` → `name`; `--node` → `node`; `--output` → `output`; `--props` → `props`; `--workflow` → `workflowId` | — |
+| `cai node connect` | `node_connect` | `--flow` → `flow`; `--from` → `from`; `--output` → `output`; `--to` → `to`; `--workflow` → `workflowId` | — |
+| `cai node continue-on-error` | `node_continue_on_error_set` | `<nodeId>` → `nodeId`; `--enable` / `--disable` → `enabled`; `--workflow` → `workflowId` | — |
+| `cai node declare-output` | `node_output_type_declare` | `<nodeId>` → `nodeId`; `--sample-file` → `sample` (inline content); `--workflow` → `workflowId` | — |
+| `cai node delete` | `node_delete` | `<nodeId>` → `nodeId`; `--workflow` → `workflowId` | — |
+| `cai node disable-prop` | `node_optional_prop_set` | `<nodeId>` → `nodeId`; `--prop` → `prop`; `--workflow` → `workflowId`; `enabled` (MCP-only) → `enabled` | merged: The explicit enabled boolean replaces the separate disabling command. |
+| `cai node disconnect` | `node_disconnect` | `--edge` → `edge`; `--workflow` → `workflowId` | — |
+| `cai node duplicate` | `node_duplicate` | `<nodeId>` → `nodeId`; `--workflow` → `workflowId` | — |
+| `cai node enable-prop` | `node_optional_prop_set` | `<nodeId>` → `nodeId`; `--prop` → `prop`; `--workflow` → `workflowId`; `enabled` (MCP-only) → `enabled` | merged: The explicit enabled boolean replaces the separate enabling command. |
+| `cai node get` | `node_get` | `<nodeId>` → `nodeId`; `--workflow` → `workflowId` | — |
+| `cai node only-when` | `node_only_when_set` | `<nodeId>` → `nodeId`; `--clear` → `clear`; `--js` / `--js-file` → `js` (inline content); `--workflow` → `workflowId` | — |
+| `cai node optional-props` | `node_optional_prop_list` | `<nodeId>` → `nodeId`; `--workflow` → `workflowId` | — |
+| `cai node options` | `node_prop_options` | `<nodeId>` → `nodeId`; `--for` → `for`; `--page` → `page`; `--prev-context` → `prevContext`; `--prop` → `prop`; `--query` → `query`; `--workflow` → `workflowId` | — |
+| `cai node props` | `node_prop_list` | `<nodeId>` → `nodeId`; `--workflow` → `workflowId` | — |
+| `cai node reload` | `node_prop_reload` | `<nodeId>` → `nodeId`; `--workflow` → `workflowId` | — |
+| `cai node rename` | `node_rename` | `<nodeId>` → `nodeId`; `--name` → `name`; `--workflow` → `workflowId` | — |
+| `cai node set` | `node_prop_set` | `<nodeId>` → `nodeId`; `--js` / `--js-file` → `js` (inline content); `--label` → `label`; `--prop` → `prop`; `--raw-expression-json` → `rawExpressionJson` (inline content); `--value` → `value`; `--workflow` → `workflowId`; `--value` → `valueJson` | — |
+| `cai node set-connection` | `node_connection_set` | `<nodeId>` → `nodeId`; `--connection` → `connection`; `--workflow` → `workflowId` | — |
+| `cai node set-flow` | `node_subflow_set` | `<nodeId>` → `nodeId`; `--flow` → `flow`; `--workflow` → `workflowId` | — |
+| `cai node status` | `node_status` | `<nodeId>` → `nodeId`; `--workflow` → `workflowId` | — |
+| `cai run discover` | `run_discover` | `--connection` → `connection`; `--enable` → `enable`; `--key` → `key`; `--node` → `node`; `--props` → `props`; `--workflow` → `workflowId` | — |
+| `cai run flow` | `run_flow` | `<flowId>` → `flowId`; `--confirm-live` → `confirmLive`; `--inputs` → `inputs`; `--target` → `target`; `--timeout` → `waitSeconds`; `--workflow` → `workflowId` | `waitSeconds` default 60, max 120 |
+| `cai run inputs` | `run_inputs` | `<nodeIdOrFlowId>` → `nodeIdOrFlowId`; `--flow` → `flow`; `--workflow` → `workflowId` | — |
+| `cai run node` | `run_node` | `<nodeId>` → `nodeId`; `--inputs` → `inputs`; `--timeout` → `waitSeconds`; `--workflow` → `workflowId` | `waitSeconds` default 60, max 120 |
+| `cai run workflow` | — | — | dropped: Excluded dead stub whose handler always throws NOT_IMPLEMENTED. |
+| `cai schema create` | `schema_type_create` | `<name>` → `name`; `--display` → `display`; `--field` → `field`; `--from-json` → `fromJson` (inline content); `--workflow` → `workflowId` | — |
+| `cai schema delete` | `schema_type_delete` | `<name>` → `name`; `--workflow` → `workflowId` | — |
+| `cai schema get` | `schema_type_get` | `<name>` → `name`; `--workflow` → `workflowId` | — |
+| `cai schema list` | `schema_type_list` | `--all` → `all`; `--workflow` → `workflowId` | — |
+| `cai schema resolve` | `schema_type_resolve` | `<typeId>` → `typeId`; `--workflow` → `workflowId` | — |
+| `cai schema update` | `schema_type_update` | `<name>` → `name`; `--display` → `display`; `--field` → `field`; `--from-json` → `fromJson` (inline content); `--workflow` → `workflowId` | — |
+| `cai signup` | — | — | dropped: The OAuth-authorized caller already has a provisioned account; root signup is local bootstrap. |
+| `cai signup email` | `account_claim_start` | `<address>` → `email` | hosted: Uses the OAuth grant durable email-claim adapter instead of local CLI credential replacement. |
+| `cai signup verify` | `account_claim_verify` | `<code>` → `code` | hosted: Uses the OAuth grant durable email verification adapter. |
+| `cai skills install` | — | — | dropped: Writes guidance into a caller local project, which the hosted server cannot access. |
+| `cai skills status` | `guide_get`<br>`guide_list` | `guide_get`: `name` (MCP-only) → `name`<br>`guide_list`: — | hosted: guide_list and guide_get serve the bundled server guidance without inspecting a local project. |
+| `cai skills update` | — | — | dropped: Updates guidance files in a caller local project. |
+| `cai trigger audit` | `trigger_audit` | `--workflow` → `workflowId` | — |
+| `cai trigger create` | `trigger_create` | `--connection` → `connection`; `--dynamic-props-id` → `dynamicPropsId`; `--event` → `event`; `--flow` → `flow`; `--node` → `node`; `--props` → `props`; `--source-basis` → `sourceBasis`; `--workflow` → `workflowId` | — |
+| `cai trigger delete` | `trigger_delete` | `<triggerId>` → `triggerId`; `--workflow` → `workflowId` | — |
+| `cai trigger event` | `trigger_event_get` | `<eventId>` → `eventId`; `--workflow` → `workflowId` | — |
+| `cai trigger events` | `trigger_event_list` | `--limit` → `limit`; `--trigger` → `triggerId`; `--workflow` → `workflowId` | — |
+| `cai trigger get` | `trigger_get` | `<triggerId>` → `triggerId`; `--workflow` → `workflowId` | — |
+| `cai trigger list` | `trigger_list` | `--workflow` → `workflowId` | — |
+| `cai trigger options` | `trigger_prop_options` | `--configured` → `configured`; `--connection` → `connection`; `--dynamic-props-id` → `dynamicPropsId`; `--event` → `event`; `--node` → `node`; `--page` → `page`; `--prev-context` → `prevContext`; `--prop` → `prop`; `--query` → `query`; `--workflow` → `workflowId` | — |
+| `cai trigger props` | `trigger_component_props` | `--configured` → `configured`; `--connection` → `connection`; `--dynamic-props-id` → `dynamicPropsId`; `--event` → `event`; `--node` → `node`; `--workflow` → `workflowId` | — |
+| `cai trigger rename` | `trigger_rename` | `<triggerId>` → `triggerId`; `--name` → `name`; `--workflow` → `workflowId` | — |
+| `cai trigger replay` | `trigger_replay` | `--confirm-live` → `confirmLive`; `--event` → `eventId`; `--payload` → `payload`; `--target` → `target`; `--trigger` → `triggerId`; `--workflow` → `workflowId` | — |
+| `cai trigger search` | `trigger_search` | `<query>` → `query`; `--events-per-node` → `eventsPerNode`; `--limit` → `limit`; `--node` → `node`; `--workflow` → `workflowId` | — |
+| `cai trigger select-event` | `trigger_event_select` | `--event` → `eventId`; `--node` → `triggerNodeId`; `--workflow` → `workflowId` | — |
+| `cai trigger set-enabled` | `trigger_set_enabled` | `<triggerId>` → `triggerId`; `--enable` / `--disable` → `enabled`; `--workflow` → `workflowId` | merged: The explicit enabled boolean combines the mutually exclusive enable and disable flags. |
+| `cai trigger test-events` | `trigger_test_events_set` | `<triggerId>` → `triggerId`; `--acknowledge-dual-run` → `acknowledgeDualRun`; `--allow` / `--disallow` → `allowed`; `--workflow` → `workflowId` | — |
+| `cai use` | — | — | dropped: Persists a local workflow pin; every typed workflow call carries an explicit id. |
+| `cai workflow create` | `workflow_create` | `--name` → `name` | — |
+| `cai workflow delete` | `workflow_delete` | `<workflowId>` / `--workflow` → `workflowId` | — |
+| `cai workflow document` | `workflow_document_get` | `--state` → `stateId`; `--workflow` → `workflowId` | — |
+| `cai workflow duplicate` | `workflow_duplicate` | `<workflowId>` / `--workflow` → `workflowId` | — |
+| `cai workflow get` | `workflow_get` | `<workflowId>` / `--workflow` → `workflowId` | — |
+| `cai workflow history` | `workflow_history` | `--group` → `group`; `--version` → `version`; `--workflow` → `workflowId` | — |
+| `cai workflow list` | `workflow_list` | `--limit` → `limit` | — |
+| `cai workflow outline` | `workflow_outline` | `<workflowId>` / `--workflow` → `workflowId` | — |
+| `cai workflow publish` | `workflow_publish` | `--acknowledge-dual-dispatch` → `acknowledgeDualDispatch`; `--acknowledge-validation-errors` → `acknowledgeValidationErrors`; `--name` → `name`; `--workflow` → `workflowId` | — |
+| `cai workflow releases` | `workflow_release_list` | `<workflowId>` / `--workflow` → `workflowId` | — |
+| `cai workflow rename` | `workflow_rename` | `--name` → `name`; `<workflowId>` / `--workflow` → `workflowId` | — |
+| `cai workflow restore` | `workflow_state_restore` | `--state` → `stateId`; `--version` → `version`; `--workflow` → `workflowId` | — |
+| `cai workflow save` | `workflow_state_save` | `--name` → `name`; `--workflow` → `workflowId` | — |
+| `cai workflow set-description` | `workflow_description_set` | `--description` → `description`; `<workflowId>` / `--workflow` → `workflowId` | — |
+| `cai workflow state` | `workflow_state_get` | `--flow` → `flowId`; `--state` → `stateId`; `--workflow` → `workflowId` | — |
+| `cai workflow status` | `workflow_status` | `--workflow` → `workflowId` | — |
+| `cai workflow validate` | `workflow_validate` | `--workflow` → `workflowId` | — |
+| `cai workflow versions` | `workflow_version_list` | `<workflowId>` / `--workflow` → `workflowId` | — |

package/skills/controllerai-triggers/SKILL.md

@@ -5,7 +5,7 @@ description: Discover, configure, create, sample, enable, test, and debug Contro
 
 # Controller AI triggers
 
-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 trigger targets exactly one flow. Its source may capture events before publish, but ordinary event execution uses the live workflow. Creating the source is therefore separate from mapping, development testing, publishing, and live replay.
 
@@ -35,6 +35,8 @@ cai connection list --node <nodeSlug> --json
 cai connection connect <nodeSlug>
 ```
 
+MCP: call `connection_connect_url`; it returns the URL immediately and has no `open` or `wait` parameter.
+
 ## Resolve trigger props
 
 ```bash
@@ -45,9 +47,9 @@ cai trigger props \
   --json
 ```
 
-Use the returned shape-correct `propsExample` as a starting point. Hidden props remain unset. `readyForCreate` must be true before using it in `trigger create`; the CLI intentionally omits unresolved required option props rather than emitting a plausible placeholder.
+Use the returned shape-correct `propsExample` as a starting point. Hidden props remain unset. `readyForCreate` must be true before using it in `trigger create`; the response intentionally omits unresolved required option props rather than emitting a plausible placeholder.
 
-For each name in `unresolvedOptionProps`, run the complete option command printed by the CLI, or equivalently:
+For each name in `unresolvedOptionProps`, run the complete canonical option command returned by the transport, or equivalently:
 
 ```bash
 cai trigger options \
@@ -75,7 +77,7 @@ cai trigger props \
   --json
 ```
 
-Keep the same node, event, connection, and configured values on every reload, but always pass the LATEST `dynamicPropsId` the backend returned — a reload can mint a new ID, and reusing a stale one resolves against a stale schema. The CLI prints this complete command; do not shorten it to only `--configured`.
+Keep the same node, event, connection, and configured values on every reload, but always pass the LATEST `dynamicPropsId` the backend returned — a reload can mint a new ID, and reusing a stale one resolves against a stale schema. The response provides the complete canonical command; do not shorten it to only `--configured`.
 
 Timer values are objects:
 
@@ -107,7 +109,7 @@ cai trigger create \
   --json
 ```
 
-Capture all returned IDs. `triggerId` is the canvas ID used for get/rename/toggle/delete. `backendTriggerId` is numeric and used for captured events and replay. They are not interchangeable.
+Capture all returned IDs. `triggerId` is the canvas ID used for get/rename/set-enabled/delete. `backendTriggerId` is numeric and used for captured events and replay. They are not interchangeable.
 
 Read a single trigger back with `cai trigger get <triggerId> --json` — the full record: node, event, connection, props, lifecycle. Read-back is always `get`; the CLI has no `describe` read command anywhere (`cai workflow set-description` is a setter).
 
@@ -115,7 +117,9 @@ Follow returned `nextSteps` in order. Trigger payload does not automatically pop
 
 ## Remove or disable an automatic start
 
-`cai trigger delete <triggerId>` removes the automatic start from the development canvas; use it when the start should no longer exist. `cai trigger toggle <triggerId>` disables it reversibly by flipping its enabled state; read `cai trigger list --json` before and after because toggle is not a setter.
+`cai trigger delete <triggerId>` removes the automatic start from the development canvas; use it when the start should no longer exist. `cai trigger set-enabled <triggerId> --enable|--disable` changes the enabled state reversibly and idempotently; pass exactly one state flag.
+
+MCP: call `trigger_set_enabled` with `enabled: true` or `enabled: false`.
 
 Both are development edits. Publish after either so production follows; until then, the previous live trigger can still start the published workflow.
 
@@ -139,13 +143,15 @@ Armed test events let real events reach the DEV version while you set the trigge
 cai trigger test-events --id <triggerId> --disallow
 ```
 
+MCP: call `trigger_test_events_set` with `allowed: false`, or `allowed: true` to arm it.
+
 The armed state is sticky: nothing disarms it for you, and dev dispatch and live dispatch are independent gates. A trigger that is armed while the workflow is also live runs ONE real event TWICE — both executions real, both billed. The starkest case is a schedule trigger: armed + enabled + published, the cron fires BOTH dev and live at every interval, forever, with no external event involved — until someone edits and republishes.
 
 Keeping a trigger armed alongside live on purpose (side-by-side comparison on real events) is legitimate but uncommon; it is a user decision, never a default.
 
 ## Verify development, then publish
 
-Use `cai run flow` for direct development verification, then replay one captured event through the development trigger path:
+Use `cai run flow` for direct development verification, then replay one captured event through the development trigger path. MCP `run_flow` calls take `waitSeconds`.
 
 ```bash
 cai trigger replay --trigger <backendTriggerId> --event <eventId> --target dev --json

package/skills/controllerai-triggers/references/lifecycle.md

@@ -23,12 +23,12 @@ Skipping capture/sample selection commonly leaves downstream output untyped. Ski
 
 | ID | Used by |
 | --- | --- |
-| Canvas `triggerId` | `trigger get`, `rename`, `toggle`, `delete` |
+| Canvas `triggerId` | `trigger get`, `rename`, `set-enabled`, `delete` |
 | Numeric `backendTriggerId` | `trigger events`, `replay` |
 | `triggerNodeId` | `trigger select-event` |
 | Captured `eventId` | `trigger event`, `select-event`, `replay --event` |
 
-Always copy these from CLI output.
+Always copy these from the transport output.
 
 Development replay is the normal pre-publish check:
 
@@ -40,7 +40,9 @@ Use `--target live --confirm-live` only for an intentional post-publish live ver
 
 ## Enable/disable
 
-`cai trigger toggle <triggerId>` flips state; it is not a setter. Read `cai trigger list --json` before and after. Do not toggle blindly.
+`cai trigger set-enabled <triggerId> --enable|--disable` sets the requested state idempotently. Pass exactly one state flag.
+
+MCP: call `trigger_set_enabled` with `enabled: true` or `enabled: false`.
 
 ## Debugging a missing run
 

package/skills/controllerai-workflows/SKILL.md

@@ -1,13 +1,11 @@
 ---
 name: controllerai-workflows
-description: Build, inspect, edit, test, recover, and publish Controller AI workflows through the cai CLI. Use when a user asks to create or change an automation, workflow, flow, or workflow release, or when another Controller AI skill needs the shared lifecycle and safety rules.
+description: Build, inspect, edit, test, recover, and publish Controller AI workflows through the cai CLI or typed MCP tools. Use when a user asks to create or change an automation, workflow, flow, or workflow release, or when another Controller AI skill needs the shared lifecycle and safety rules.
 ---
 
 # Controller AI workflows
 
-In MCP hosts, send each exact literal `cai ...` command through the single `exec` tool; never translate it into another grammar.
-
-Use `cai` as the control surface. Never call Controller AI REST or MCP routes directly; when the CLI lacks a capability, say so and name the UI path instead of bypassing it.
+The `cai ...` examples are canonical grammar. Follow the transport rules and MCP map in `controllerai-start`; never mix transports within one task. Do not call private REST endpoints or invoke MCP routes outside the typed tools. When the selected transport lacks a capability, say so and name the UI path instead of bypassing it.
 
 ## Establish context
 
@@ -18,17 +16,19 @@ cai use <workflowId>
 cai workflow status --json
 ```
 
+MCP: use `account_status`, then call `workflow_list` and `workflow_status` with explicit `workflowId`; there is no `cai use` or stored pin.
+
 If no workflow exists, create it with its final name:
 
 ```bash
 cai workflow create --name "<clear outcome-oriented name>" --json
 ```
 
-Read `selected`, `effectiveWorkflowId`, and `pinSource` from the result; creation does not guarantee that the new workflow won the effective pin. If `selected` is false, rerun without `--workflow` when `pinSource` is `flag`; otherwise run `cai use <id>` for a stored pin or clear an inherited `CAI_WORKFLOW` pin in the parent environment, then re-check context. Use `cai config reset` to clear stale stored pins; it cannot clear an environment pin. `cai doctor` verifies that the effective workflow pin and its development head are readable. Do not create and then rename: `workflow create --name` submits the name directly.
+On the CLI, read `selected`, `effectiveWorkflowId`, and `pinSource` from the result; creation does not guarantee that the new workflow won the effective pin. If `selected` is false, rerun without `--workflow` when `pinSource` is `flag`; otherwise run `cai use <id>` for a stored pin or clear an inherited `CAI_WORKFLOW` pin in the parent environment, then re-check context. Use `cai config reset` to clear stale stored pins; it cannot clear an environment pin. `cai doctor` verifies that the effective workflow pin and its development head are readable. On MCP, capture the created `workflowId` and pass it explicitly thereafter. Do not create and then rename: `workflow create --name` submits the name directly.
 
 A new workflow already ships with one empty flow. Rename that flow and build in it — do not add a second flow for the first piece of work; only add flows for genuinely separate canvases. A stray empty "Flow 1" left behind is clutter the user has to clean up.
 
-Use IDs returned by the CLI. Never invent workflow, flow, node, prop, event, field, route, or connection identifiers.
+Use IDs returned by the selected transport. Never invent workflow, flow, node, prop, event, field, route, or connection identifiers.
 
 To orient inside a workflow, prefer one call over many:
 
@@ -36,6 +36,10 @@ To orient inside a workflow, prefer one call over many:
 cai workflow outline --json
 ```
 
+`cai workflow state --json` is the bounded state projection; add `--flow <flowId>` for that
+flow's node and edge identities. Use `cai workflow document --json` only when the complete opaque
+workflow JSON is actually needed.
+
 It returns the whole map compactly — every flow with typed inputs/outputs, its nodes with upstream `deps` (the graph shape), triggers with source/enabled/armed state, and data types with per-rail record counts. Drill into a specific flow with `cai flow get <flowId>` only when you need props and expressions.
 
 ## Build protocol
@@ -67,7 +71,7 @@ Load the narrow skill when the task reaches that surface:
 
 - All graph edits target development. Live remains unchanged until `cai workflow publish`.
 - Email verification is not a publishing prerequisite. An unclaimed agent-created account may publish; email claiming only raises its monthly usage cap and enables account recovery.
-- Prefer `--json` for decisions and IDs; human tables are for presentation. If human output looks odd, re-run the same read with `--json` before acting.
+- On the CLI, prefer `--json` for decisions and IDs; human tables are for presentation. MCP tools return typed JSON. If human output looks odd, re-run the same read with `--json` before acting.
 - A workflow contains flows; a flow is one canvas. Do not confuse their IDs.
 - For flow inputs, pass a human `--display` label and use the compiler-current binding from the latest `cai flow get` (`jsBinding`) or `cai workflow outline` (`binding`). An input rename can change it: re-read bindings after every rename and never cache their spellings across renames. `legacyBinding` is diagnostic-only; never use it in expressions.
 - Name nodes after the data they produce. Downstream input bindings are seeded from that name when wired.
@@ -75,10 +79,10 @@ Load the narrow skill when the task reaches that surface:
 - **Edit the graph with a plan-aware safety net.** Each save is a version state. `cai workflow history` has no age cutoff on Free, Max, or custom plans and a 90-day window on Pro/Starter; expand a group with `cai workflow history --group <groupId>` to get its state IDs. Restore with `cai workflow restore --state <stateId>` within 7 days on Free, 90 days on Pro/Starter, or without an age limit on Max/custom. Duplicate, delete, and refactor with that window in mind. Restore rolls back the DEFINITION (graph and schemas) only — record data is unversioned and stays as it is. External side effects (sent messages, provider calls) are equally outside the undo.
 - **Validate after structural edits, don't ask permission before them.** After deleting a flow, deleting a type, or a large refactor — and before every publish — run `cai workflow validate` and fix what it lists. It is deep: required props, connections, wiring, expressions, output types, subflows, branches, trigger issues, grouped per red node. Publish refuses when validation reports errors; `--acknowledge-validation-errors` may only be used after the user explicitly approved publishing with the listed issues. Deleting a flow deletes its nodes, edges, inputs/outputs, and attached triggers, and breaks callers in other flows — exactly like deleting a function breaks its call sites; validate shows every break.
 - On a conflict, re-read current state and reapply intent. Do not replay stale IDs or whole documents.
-- Never delete a workflow without the user's explicit intent; the CLI requires `--yes` but that is not a substitute for authorization. `cai workflow delete` tears down deployed triggers and soft-deletes the workflow row. Historical workflow/version data remains stored, but there is currently no CLI restore command for the deleted row.
+- Never delete a workflow without the user's explicit intent; the CLI requires `--yes` but that is not a substitute for authorization. MCP: `workflow_delete` has no `yes` parameter, but still requires the same explicit intent. `cai workflow delete` tears down deployed triggers and soft-deletes the workflow row. Historical workflow/version data remains stored, but there is currently no restore command for the deleted row.
 - **Know the dependency graph before deleting or refactoring shared resources.** `cai deps` shows which agents attach this workflow as a tool (LIVE or draft), which workflows call it, and which connections it uses; `cai deps --account` maps the whole account. Deleting a workflow with agent dependents is refused server-side, and `--force` is a deprecated, inert compatibility flag. For a draft attachment, run `cai agent remove-tool <agentId> --tool <toolId>`. If it is also LIVE, publish that detached draft with `cai agent publish <agentId>`; if it is LIVE-only, publish the already-detached current draft or delete the agent. Publishing or deleting a dependent agent is its own live/destructive decision — get the user's explicit approval for that step first. Then retry the workflow delete.
-- **Check the account feed when recent activity matters.** `cai events` lists what happened in the account, newest first: connections created, workflow edits/publishes/runs, agents created/published, members added. Filter with `--type` (comma-separated), `--since 30m|2h|7d|<ISO>`, `--for-workflow <id>`; page with `--cursor`. Typical uses: `cai events --type connection.created --since 10m` to see whether the user finished connecting, `cai events --since 24h` to catch up at session start, `cai events --for-workflow <id> --type workflow.run` for recent run activity. The feed cannot show connection deletions, settings changes, member removals, or any label/folder/share activity — absence there proves nothing. When the user asks you to reconstruct a past change the platform does not record (e.g. which workflow a label was removed from), say it is not recorded and change nothing; names or current state that merely suggest an answer are not evidence, and acting on a guess is worse than reporting the limitation.
-- **Share the platform, not just text.** At the right moments, hand the user the real product page — command outputs include `appUrl` when the app origin is known: after `workflow publish` (the live builder view), after development `run flow`/`run node` (the run page; live flow runs omit it), after `agent publish`/`test` (agent and conversation pages), and `connection connect` prints the connect link (share the link first with `--no-open`; add `--wait` only after the link is already in front of the user). When the user asks for a link at any other time, don't guess URLs: `cai workflow get`, `cai workflow status`, and `cai agent get` include `appUrl`. When you cannot perform something (settings, product-only surfaces), give the link instead of apologizing.
+- **Check the account feed when recent activity matters.** `cai events` lists what happened in the account, newest first: connections created, workflow edits/publishes/runs, agents created/published, members added. Filter with `--type` (comma-separated), `--since 30m|2h|7d|<ISO>`, `--for-workflow <id>`; page with `--cursor`. Typical uses: `cai events --type connection.created --since 10m` to see whether the user finished connecting, `cai events --since 24h` to catch up at session start, `cai events --for-workflow <id> --type workflow.run` for recent run activity. The feed cannot show connection deletions, settings changes, member removals, or label activity — absence there proves nothing. When the user asks you to reconstruct a past change the platform does not record (e.g. which workflow a label was removed from), say it is not recorded and change nothing; names or current state that merely suggest an answer are not evidence, and acting on a guess is worse than reporting the limitation.
+- **Share the platform, not just text.** At the right moments, hand the user the real product page — command outputs include `appUrl` when the app origin is known: after `workflow publish` (the live builder view), after development `run flow`/`run node` (the run page; live flow runs omit it), and after `agent publish`/`test` (agent and conversation pages). On the CLI, `connection connect` prints the link; share it with `--no-open` before optionally adding `--wait`. MCP: `connection_connect_url` returns the link immediately and has no `open` or `wait` parameter. When the user asks for a link at any other time, don't guess URLs: `cai workflow get`, `cai workflow status`, and `cai agent get` include `appUrl`. When you cannot perform something (settings, product-only surfaces), give the link instead of apologizing.
 - Never silently weaken the request to make a test pass. Report an unsupported capability or ask about a real product decision.
 
 ## Completion gate
@@ -92,6 +96,8 @@ cai flow get <flowId> --json
 cai run flow <flowId> --inputs <values.json> --json
 ```
 
+MCP: pass the parsed values in `inputs` and set `waitSeconds` on `run_flow`.
+
 Then confirm:
 
 - **`cai workflow validate` reports `errors: 0`.** Every error is fixed, or explicitly reported to the user with what it breaks — never summarized away, never called cosmetic. A red canvas and a "done" claim cannot coexist.

package/skills/controllerai-workflows/references/command-map.md

@@ -1,6 +1,6 @@
 # Workflow command map
 
-Read only the sections relevant to the requested work. Use `cai <domain> --help` as the authoritative flag reference.
+Read only the sections relevant to the requested work. On the CLI, use `cai <domain> --help` for flags. On MCP, inspect the typed tool schema and [the generated map](../../controllerai-start/references/mcp-tool-map.md).
 
 ## Setup and workflow lifecycle
 
@@ -10,11 +10,13 @@ cai doctor
 cai config reset [--local|--global]
 cai auth status
 cai workflow list|create|get|rename|set-description|duplicate|delete
-cai workflow state|status|versions|releases|history|save|restore|publish
+cai workflow document|state|status|versions|releases|history|save|restore|publish
 cai use <workflowId>
 ```
 
-`workflow save` creates a named development checkpoint. `workflow publish` promotes development to live. Version history may be plan-gated. `workflow delete --yes` undeploys triggers and soft-deletes the workflow row; it refuses while any draft or LIVE agent depends on the workflow. Detach draft tools with `agent remove-tool`, publish detached drafts that are still LIVE, then retry. `--force` is deprecated and inert. Deletion is not a permanent history purge, and deleted rows currently have no CLI restore command.
+MCP: `account_status` replaces `auth status` and `doctor`; `cai connect`, `config reset`, and `use` are local-only, so pass `workflowId` explicitly.
+
+`workflow state` is a bounded projection; use `--flow <flowId>` for node and edge identities. `workflow document` returns the complete opaque JSON. `workflow save` creates a named development checkpoint. `workflow publish` promotes development to live. Version history may be plan-gated. `workflow delete --yes` undeploys triggers and soft-deletes the workflow row; it refuses while any draft or LIVE agent depends on the workflow. Detach draft tools with `agent remove-tool`, publish detached drafts that are still LIVE, then retry. `--force` is deprecated and inert. Deletion is not a permanent history purge, and deleted rows currently have no CLI restore command.
 
 ## Canvas and graph
 
@@ -22,10 +24,12 @@ cai use <workflowId>
 cai flow list|get|create|rename|duplicate|delete|reorder|layout
 cai flow input add|update|delete
 cai flow output add|update|delete
-cai node find|search|components|component
+cai integration search|actions|action
 cai node init|status|get|props|set|connect|disconnect|delete
 ```
 
+MCP: `node set` and `expr set` are merged into `node_prop_set`.
+
 Declare flow outputs before adding a Return response node. Its props are derived from those outputs.
 
 `cai flow input add <flowId> --display "<human label>" --type <type>` returns the compiler-current `jsBinding`. Use the latest value from `flow get` (`jsBinding`) or `workflow outline` (`binding`), re-read it after every input rename, and never cache its spelling across renames. `legacyBinding` is diagnostic-only.
@@ -39,6 +43,8 @@ cai flow for-each
 cai node set-flow
 ```
 
+MCP: use `flow_for_each_scaffold` for `flow for-each` and `node_subflow_set` for `node set-flow`; pass file-based loop source inline as `listJs` and branch condition source as `js`.
+
 Use branch-specific connection commands for Router and If/Else outputs. Generic `node connect` supports only `main` and `error` outputs.
 
 ## Verification
@@ -48,18 +54,27 @@ cai run inputs|node|flow|discover
 cai exec list|get|flow|node|ports|tree
 ```
 
+MCP: `run_node` and `run_flow` take `waitSeconds` (default 60, maximum 120). `run_discover` never keeps its scratch graph.
+
 `run discover` executes the real integration action in a scratch flow and can incur third-party effects or usage. Do not use it casually for mutating actions.
 
 ## Product surfaces
 
 ```text
 cai connection list|connect
-cai trigger list|get|search|props|options|create|events|event|select-event|replay|toggle|rename|delete
+cai trigger list|get|search|props|options|create|events|event|select-event|replay|set-enabled|rename|delete
 cai schema list|get|resolve|create|update|delete
 cai data collections|fields|query|get|create|update|delete|delete-many|import|copy-to-live
 cai agent list|get|create|update|add-workflow|remove-tool|add-file|tools|publish-preflight|publish|versions|visibility
 cai agent conversation list|create|status|history|send|approve|deny
 ```
 
-Connections are authorized in a browser. The CLI returns and opens the Controller AI connection URL.
+Connections are authorized in a browser. The CLI returns and may open the URL; MCP returns it from `connection_connect_url`.
+
+MCP: `trigger_set_enabled` takes the same explicit enabled state as the CLI setter.
+
+MCP: every data write requires explicit `env`; pass CSV text inline as `content` to `data_record_import`, and pass `env: "live"` to `data_copy_to_live`.
+
+MCP: `agent update` splits into `agent_update` and `agent_set_enabled`; `agent add-file` splits into `agent_knowledge_file_add` and `agent_workspace_file_add` with inline `content`. `agent_conversation_send` takes `waitSeconds`.
+
 Agent visibility supports only `private` and `organization`; organization is an explicit live access change after agent publish.