@controllerai/cli 0.2.18 → 0.2.20

package/skills/controllerai-agents/SKILL.md

@@ -1,214 +1,47 @@
 ---
 name: controllerai-agents
-description: Design, assemble, test, publish, and share user-facing Controller AI agents with ready integration actions, workflow tools, instructions, and knowledge files. Use when creating or editing an agent, choosing its tool architecture, attaching or updating tools, verifying draft/live conversations, or publishing and sharing an agent safely.
+description: Build Controller AI user-facing assistants with chat and uploaded files, instructions, knowledge, direct integration actions and workflow tools. Use for conversational experiences, file enrichment, tool selection, testing and publishing agents.
 ---
 
 # Controller AI agents
 
-An agent has one mutable draft and immutable published versions. Build instructions, tools, permissions, and files on the draft; verify in Test; publish last. Draft edits never update Live by themselves.
+A Controller AI agent is an assistant a person can chat with. It reasons, reads conversation attachments, uses reference knowledge, calls tools, and creates files for the user. Give it direct integration actions for individual app operations and workflow tools for reusable processing or data access.
 
-The `cai ...` examples are canonical grammar. Use the transport selected in `controllerai-start` and its MCP tool map; never mix transports in one task or call Controller AI REST routes directly.
+The agent has a mutable draft and published versions. Test uses the draft; shared users use the latest published version. Disabling an agent pauses runtime independently of publication.
 
-## Rules that break tasks when skipped
+## Design the experience
 
-- Attach one ready action directly instead of wrapping it; see Choose the capability architecture.
-- Choose confirmation before attaching a consequential tool; see Create and assemble the draft.
-- Use one conversation on an explicit rail for each verification task; see Verify the draft as an agent.
-- Resolve pending requests in that same conversation; see Verify the draft as an agent.
-- Enablement is runtime state, not publication; see Create and assemble the draft.
-- Publish authorized workflow dependencies, preflight, then publish the agent; see Publish in dependency order.
-- Draft-only means stop before publish; draft evidence never proves Live. See Publish in dependency order.
+Write instructions that state the agent's role, required information, how to choose tools, how to handle missing data, and how to present results. Put deterministic validation and database changes in workflow tools. Put stable reference material in knowledge files. Avoid telling an agent to retry all failures indiscriminately: reads, rejected validation and uncertain mutations require different responses.
 
-## 1. Choose the capability architecture
+For a workflow tool, describe when to use it, its inputs and its result. For a ready action, discover the exact integration/action and use a valid connection. Attach with `agent_tool_workflow_add` or `agent_tool_action_add`; inspect `agent_tool_list` afterward.
 
-- Use `controllerai-integration-actions` when one existing app operation completes it.
-- Use a workflow tool for multiple steps, transformations, branching, looping, durable state, triggers, a custom typed contract, or reusable business logic.
-- Put judgment, tool-selection rules, tone, and escalation in instructions; put stable sources in knowledge files.
+Confirmation policy is a tool setting, not the builder's permission to finish authorized work. Choose it for the intended user experience. A read/search tool normally runs directly; consequential unattended actions should match the user's stated scope.
 
-Do not create a one-node workflow merely to expose a ready action, or replace orchestration with several independent direct actions when ordering or data handling must be deterministic.
+## Recipe: upload a CSV, enrich investors, download the result
 
-## 2. Build and verify capabilities
+1. Build a flow `Research one investor` accepting a person's name and optional company. Return structured fields such as matched name/company, work email, public contact links, source URLs, match confidence and a per-row error/status.
+2. Test one clear match and one ambiguous/missing match. Do not invent an email or claim none exists merely because search did not find one.
+3. Create the agent and attach that flow. Instruct it to inspect the CSV columns, preserve original columns and row order, process every row, keep failures on their original rows and append the enrichment columns.
+4. The **agent** reads the uploaded file and produces the CSV. Workflows receive typed values extracted from rows. A `file` workflow value is hosted-file metadata, not a chat upload or parser.
+5. Test with a small CSV including quoted commas, a missing company, an ambiguous name and a failed lookup. Verify the exported file opens and retains every input row.
+6. Share the generated attachment through the supported file-sharing surface. A message saying “saved the file” is not proof of an accessible download.
 
-For a ready action, follow `controllerai-integration-actions`: discover exact identities, select a connection, decide confirmation, then attach.
+## Files have distinct roles
 
-For every workflow tool, load the relevant workflow skills and test the development state before attaching:
+- **Conversation attachments:** files supplied or generated during a chat, tied to that conversation.
+- **Knowledge:** reference files in the agent draft; publishing freezes the live knowledge snapshot.
+- **Shared runtime workspace:** files the agent can work with across its runtime. Shared-file writes affect the live workspace; Test sees live files overlaid by development files. They are not a substitute for uploading a file to a conversation.
 
-```bash
-cai use <workflowId>
-cai flow get <flowId> --json
-cai run flow <flowId> --inputs values.json --json
-```
+Use `agent_conversation_file_add` with inline UTF-8 content to attach CSV/text, `agent_conversation_file_list` to discover attached and generated files, `agent_conversation_file_read` for text, and `agent_conversation_file_download` to return the original file through a private download link. CLI equivalents are `cai agent conversation add-file|files|read-file|download-file`.
 
-MCP: there is no pin; pass `workflowId` to `flow_get` and `run_flow`, pass parsed `inputs`, and set `waitSeconds`.
+Use returned file metadata and paths. Runtime mounts can prefix workspace paths; rediscover the actual attachment or workspace file instead of inventing a new path.
 
-Capture the successful execution ID. Inputs become tool parameters and outputs its result. Require a nonempty output contract and verify the run returns it.
+## Verify conversations and release
 
-## 3. Create and assemble the draft
+Create a draft conversation and keep its ID for follow-up. `agent_test` creates a new conversation; use conversation send/status/history for subsequent turns. History is a compact transcript by default: use `limit` and `before: nextBeforeId` for older messages, or `last: true` for the latest reply. Request `raw: true` only for SDK diagnostics. File results are discoverable by conversation ID without reading raw events.
 
-Write short instructions for role, tool use, inputs/results, safety, response style, and errors. Require truthful failure reporting and at most one retry.
+Verify tool selection, arguments, terminal results, persisted data and downloadable outputs. Resolve a real approval request only within the user's authorized scope and in the same conversation; sending the original prompt again creates duplicate work.
 
-Read [references/instructions-and-versioning.md](references/instructions-and-versioning.md) before publishing or explaining Test versus Live behavior.
+When release is authorized: publish changed workflow dependencies, run agent preflight, publish the agent, and test a fresh Live conversation. Live workflow tools follow the latest published workflow, while Test uses its current development head. Present the returned agent link or `agent_present` result. Organization sharing is separate from publishing and should match the requested audience.
 
-```bash
-cai agent create --name "<agent name>" --instructions-file instructions.md --json
-```
-
-MCP: `agent_create` takes complete Markdown in `instructions`; it cannot read `instructions.md`.
-
-```bash
-cai agent add-action <agentId> \
-  --integration <integrationSlug> \
-  --action <actionKey> \
-  --connection <connectionId> \
-  --description "Use when ..." \
-  --json
-
-cai agent add-workflow <agentId> \
-  --workflow-id <workflowId> \
-  --flow <flowId> \
-  --description "Use when ...; accepts ...; returns ..." \
-  --json
-```
-
-MCP: use `agent_tool_action_add` or `agent_tool_workflow_add`; `requireConfirmation` is optional and defaults to `false`.
-
-```bash
-cai agent add-file <agentId> --file <path> --space <knowledge|shared> --json
-cai agent files <agentId> --space <knowledge|shared> [--live] --json
-cai agent tools <agentId> --json
-cai agent get <agentId> --json
-```
-
-MCP: use `agent_knowledge_file_add` or `agent_workspace_file_add` with inline `content`; `agent_file_list` uses `environment: dev|live`. Shared runtime files update live immediately.
-
-The default is no approval: attached actions and workflow tools run without a human approval step unless `requireConfirmation` is `true`, and omitting `--require-confirmation` has the same behavior. 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; `cai agent update-tool` can change it later.
-
-Keep the two modes straight:
-
-| Context | Test / draft conversation | Live / shared conversation |
-| --- | --- | --- |
-| Agent configuration | Current mutable draft | Latest published immutable agent version |
-| Workflow tools | Current workflow development heads | Each workflow's latest live release; never pinned |
-| Reference files | Current draft knowledge files | Knowledge frozen into the published agent version |
-| Runtime files | Current live runtime files, overlaid by development/test runtime files at the same path | Current live runtime files only |
-| Access | Owner only | Owner, plus organization members when shared; non-owners never see the draft |
-
-Version pinning for workflow tools does not exist. Live tools track the latest release. If asked to freeze one, explain this, attach with policy `latest`, and never abandon the attachment.
-
-Publishing snapshots versioned fields, moves the live pointer, and restamps every existing live conversation. It does not snapshot the runtime model. This cutover interrupts in-flight answers and expires pending approvals; time it accordingly.
-
-Runtime lifecycle changes do not require publishing:
-
-```bash
-cai agent update <agentId> --disabled --json
-cai agent update <agentId> --enabled --json
-cai agent delete <agentId> --confirm --json
-```
-
-MCP: draft edits use `agent_update`; runtime uses `agent_set_enabled`; `agent_delete` has no `confirm`. Disable pauses runtime. Soft delete revokes access and requests session termination; there is no CLI restore.
-
-## Runtime usage boundary
-
-The user's coding-agent subscription covers builder reasoning, but hosted agent tests and conversations consume Controller AI runtime usage from the organization's pool, and connected providers may add charges or side effects. Say so before starting a hosted test.
-
-## 4. Verify the draft as an agent
-
-Saving the draft updates the agent's Test environment — there is no separate deploy step. Test conversations run each workflow tool's DEVELOPMENT version.
-
-```bash
-cai agent test <agentId> --draft --message "<representative request>" --json
-cai agent conversation history <conversationId> --json
-```
-
-MCP: `agent_test` requires `rail: draft` or `rail: live` and takes `waitSeconds`.
-
-`agent test` always creates a conversation. Use it for a one-shot check. When a task may need follow-up or approval, create one conversation on the requested rail, capture its ID, and reuse it:
-
-```bash
-cai agent conversation create <agentId> --draft --title "<test case>" --json
-cai agent conversation send <conversationId> --message "<request>" --wait --json
-```
-
-Do not resend the request or create a replacement after an approval pause. A required post-publish Live check is a separate rail task and gets one fresh Live conversation.
-
-Test positive and negative tool selection, exact arguments, results, errors, and knowledge. Offer the returned `appUrl`; on MCP, call `agent_present` and relay the returned card.
-
-- For a workflow tool, correlate a side-effectful call with its terminal workflow execution ID.
-- For a direct integration action, inspect persisted conversation action events/run result and the intended external effect. Direct actions do not create workflow execution IDs.
-
-For a pending approval, inspect the exact request first:
-
-```bash
-cai agent conversation approve <conversationId> --request <requestId> --json
-cai agent conversation deny <conversationId> --request <requestId> --message "<reason>" --json
-```
-
-The server resolves the tool from the request ID. Do not approve merely to continue. Resolve every pending request before publishing; approval or denial resumes this conversation, while publishing expires it.
-
-After `cai agent remove-tool`, test one request that must no longer use the removed capability and one retained capability.
-
-## 5. Publish in dependency order
-
-For attached workflows only:
-
-```bash
-cai use <workflowId>
-cai workflow status --json
-cai workflow publish --name "<release>" --json
-```
-
-MCP: there is no `use`; pass `workflowId` to `workflow_status` and `workflow_publish`.
-
-Publish a workflow only when its verified development state must go live and the user authorized it. A workflow publish already followed by a live agent changes that tool's live behavior immediately; do not republish the agent merely to pick it up.
-
-For a draft-only request, stop after Test evidence. Do not publish a workflow or agent merely because it is ready.
-
-Then publish the agent:
-
-```bash
-cai agent publish-preflight <agentId> --json
-cai agent publish <agentId> --name "<release>" --json
-cai agent versions <agentId> --json
-cai agent test <agentId> --live --message "<representative request>" --json
-```
-
-MCP: `agent_test` requires `rail: draft` or `rail: live` and takes `waitSeconds`.
-
-`publish-preflight` is the arbiter of structural readiness. Report blockers and stop. With none and an authorized release, publish, except an error you actually watched happen; that blocks even a green preflight.
-
-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.
-
-Use one loop: edit draft, read back, verify Test, publish, verify Live. Published versions have no rollback. Recover forward from `agent versions`; restore workflow definitions with history/restore, then republish. Workflow releases, action grants, and runtime files are live-bound; see [references/instructions-and-versioning.md](references/instructions-and-versioning.md). After detaching an action, publish to remove it from the published list.
-
-Draft evidence does not prove the live agent. Test is owner-only; shared users always run the latest published agent version and never see draft instructions, tools, or knowledge.
-
-## 6. Offer Slack and organization sharing
-
-After publish, offer product setup for Slack. Agents remain private unless the user requests organization access:
-
-```bash
-cai agent visibility <agentId> --value organization --json
-```
-
-Members use the published version. Direct actions use the owner's external account and organization usage pool. Grant changes affect Live immediately; private visibility revokes access.
-
-## Before you finish
-
-```bash
-cai agent tools <agentId> --json
-cai agent conversation list <agentId> --mode dev --json
-cai data query --type custom.<type> --env dev --json
-cai agent conversation history <conversationId> --json
-cai agent publish-preflight <agentId> --json
-cai agent versions <agentId> --json
-cai agent test <agentId> --live --message "<representative request>" --json
-```
-
-Run the last three commands only for an authorized release. For Live verification, use `--mode live` and `--env live` in the same pair.
-
-- Conversation list must show the captured ID on the requested rail, without retry-created duplicates.
-- History must show the intended tool arguments, terminal result, and no unresolved permission request.
-- For stateful behavior, the same-rail data query must show the expected record; an assistant reply is not proof.
-- A release requires clean preflight, agent version read-back, and one fresh Live conversation. Draft-only work must remain unpublished.
-
-Report the agent ID/version, tools and confirmation policies, execution or direct-action evidence, rail state, connections, access, and anything unverified.
+Command sequences: [reference](references/command-reference.md). Exact version/file semantics: [instructions and versioning](references/instructions-and-versioning.md).

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

@@ -0,0 +1,205 @@
+# Controller AI agents
+
+An agent has one mutable draft and immutable published versions. Build instructions, tools, permissions, and files on the draft; verify in Test; publish last. Draft edits never update Live by themselves.
+
+
+
+- Attach one ready action directly instead of wrapping it; see Choose the capability architecture.
+- Choose confirmation before attaching a consequential tool; see Create and assemble the draft.
+- Use one conversation on an explicit rail for each verification task; see Verify the draft as an agent.
+- Resolve pending requests in that same conversation; see Verify the draft as an agent.
+- Enablement is runtime state, not publication; see Create and assemble the draft.
+- Publish authorized workflow dependencies, preflight, then publish the agent; see Publish in dependency order.
+- Draft-only means stop before publish; draft evidence never proves Live. See Publish in dependency order.
+
+## 1. Choose the capability architecture
+
+- Use `controllerai-integration-actions` when one existing app operation completes it.
+- Use a workflow tool for multiple steps, transformations, branching, looping, durable state, triggers, a custom typed contract, or reusable business logic.
+- Put judgment, tool-selection rules, tone, and escalation in instructions; put stable sources in knowledge files.
+
+Do not create a one-node workflow merely to expose a ready action, or replace orchestration with several independent direct actions when ordering or data handling must be deterministic.
+
+## 2. Build and verify capabilities
+
+For a ready action, follow `controllerai-integration-actions`: discover exact identities, select a connection, decide confirmation, then attach.
+
+For every workflow tool, load the relevant workflow skills and test the development state before attaching:
+
+```bash
+cai use <workflowId>
+cai flow get <flowId> --json
+cai run flow <flowId> --inputs values.json --json
+```
+
+MCP: there is no pin; pass `workflowId` to `flow_get` and `run_flow`, pass parsed `inputs`, and set `waitSeconds`.
+
+Capture the successful execution ID. Inputs become tool parameters and outputs its result. Require a nonempty output contract and verify the run returns it.
+
+## 3. Create and assemble the draft
+
+
+Read [instructions-and-versioning.md](instructions-and-versioning.md) before publishing or explaining Test versus Live behavior.
+
+```bash
+cai agent create --name "<agent name>" --instructions-file instructions.md --json
+```
+
+MCP: `agent_create` takes complete Markdown in `instructions`; it cannot read `instructions.md`.
+
+```bash
+cai agent add-action <agentId> \
+  --integration <integrationSlug> \
+  --action <actionKey> \
+  --connection <connectionId> \
+  --description "Use when ..." \
+  --json
+
+cai agent add-workflow <agentId> \
+  --workflow-id <workflowId> \
+  --flow <flowId> \
+  --description "Use when ...; accepts ...; returns ..." \
+  --json
+```
+
+MCP: use `agent_tool_action_add` or `agent_tool_workflow_add`; `requireConfirmation` is optional and defaults to `false`.
+
+```bash
+cai agent add-file <agentId> --file <path> --space <knowledge|shared> --json
+cai agent files <agentId> --space <knowledge|shared> [--live] --json
+cai agent tools <agentId> --json
+cai agent get <agentId> --json
+```
+
+MCP: use `agent_knowledge_file_add` or `agent_workspace_file_add` with inline `content`; `agent_file_list` uses `environment: dev|live`. Shared runtime files update live immediately.
+
+The default is no approval: attached actions and workflow tools run without a human approval step unless `requireConfirmation` is `true`, and omitting `--require-confirmation` has the same behavior. 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; `cai agent update-tool` can change it later.
+
+Keep the two modes straight:
+
+| Context | Test / draft conversation | Live / shared conversation |
+| --- | --- | --- |
+| Agent configuration | Current mutable draft | Latest published immutable agent version |
+| Workflow tools | Current workflow development heads | Each workflow's latest live release; never pinned |
+| Reference files | Current draft knowledge files | Knowledge frozen into the published agent version |
+| Runtime files | Current live runtime files, overlaid by development/test runtime files at the same path | Current live runtime files only |
+| Access | Owner only | Owner, plus organization members when shared; non-owners never see the draft |
+
+Version pinning for workflow tools does not exist. Live tools track the latest release. If asked to freeze one, explain this, attach with policy `latest`, and never abandon the attachment.
+
+Publishing snapshots versioned fields, moves the live pointer, and restamps every existing live conversation. It does not snapshot the runtime model. This cutover interrupts in-flight answers and expires pending approvals; time it accordingly.
+
+Runtime lifecycle changes do not require publishing:
+
+```bash
+cai agent update <agentId> --disabled --json
+cai agent update <agentId> --enabled --json
+cai agent delete <agentId> --confirm --json
+```
+
+MCP: draft edits use `agent_update`; runtime uses `agent_set_enabled`; `agent_delete` has no `confirm`. Disable pauses runtime. Soft delete revokes access and requests session termination; there is no CLI restore.
+
+## Runtime usage boundary
+
+
+## 4. Verify the draft as an agent
+
+Saving the draft updates the agent's Test environment — there is no separate deploy step. Test conversations run each workflow tool's DEVELOPMENT version.
+
+```bash
+cai agent test <agentId> --draft --message "<representative request>" --json
+cai agent conversation history <conversationId> --json
+```
+
+MCP: `agent_test` requires `rail: draft` or `rail: live` and takes `waitSeconds`.
+
+`agent test` always creates a conversation. Use it for a one-shot check. When a task may need follow-up or approval, create one conversation on the requested rail, capture its ID, and reuse it:
+
+```bash
+cai agent conversation create <agentId> --draft --title "<test case>" --json
+cai agent conversation send <conversationId> --message "<request>" --wait --json
+```
+
+Do not resend the request or create a replacement after an approval pause. A required post-publish Live check is a separate rail task and gets one fresh Live conversation.
+
+Test positive and negative tool selection, exact arguments, results, errors, and knowledge. Offer the returned `appUrl`; on MCP, call `agent_present` and relay the returned card.
+
+- For a workflow tool, correlate a side-effectful call with its terminal workflow execution ID.
+- For a direct integration action, inspect persisted conversation action events/run result and the intended external effect. Direct actions do not create workflow execution IDs.
+
+For a pending approval, inspect the exact request first:
+
+```bash
+cai agent conversation approve <conversationId> --request <requestId> --json
+cai agent conversation deny <conversationId> --request <requestId> --message "<reason>" --json
+```
+
+The server resolves the tool from the request ID. Do not approve merely to continue. Resolve every pending request before publishing; approval or denial resumes this conversation, while publishing expires it.
+
+After `cai agent remove-tool`, test one request that must no longer use the removed capability and one retained capability.
+
+## 5. Publish in dependency order
+
+For attached workflows only:
+
+```bash
+cai use <workflowId>
+cai workflow status --json
+cai workflow publish --name "<release>" --json
+```
+
+MCP: there is no `use`; pass `workflowId` to `workflow_status` and `workflow_publish`.
+
+Publish a workflow only when its verified development state must go live and the user authorized it. A workflow publish already followed by a live agent changes that tool's live behavior immediately; do not republish the agent merely to pick it up.
+
+For a draft-only request, stop after Test evidence. Do not publish a workflow or agent merely because it is ready.
+
+Then publish the agent:
+
+```bash
+cai agent publish-preflight <agentId> --json
+cai agent publish <agentId> --name "<release>" --json
+cai agent versions <agentId> --json
+cai agent test <agentId> --live --message "<representative request>" --json
+```
+
+MCP: `agent_test` requires `rail: draft` or `rail: live` and takes `waitSeconds`.
+
+`publish-preflight` is the arbiter of structural readiness. Report blockers and stop. With none and an authorized release, publish, except an error you actually watched happen; that blocks even a green preflight.
+
+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.
+
+Use one loop: edit draft, read back, verify Test, publish, verify Live. Published versions have no rollback. Recover forward from `agent versions`; restore workflow definitions with history/restore, then republish. Workflow releases, action grants, and runtime files are live-bound; see [instructions-and-versioning.md](instructions-and-versioning.md). After detaching an action, publish to remove it from the published list.
+
+Draft evidence does not prove the live agent. Test is owner-only; shared users always run the latest published agent version and never see draft instructions, tools, or knowledge.
+
+## 6. Offer Slack and organization sharing
+
+After publish, offer product setup for Slack. Agents remain private unless the user requests organization access:
+
+```bash
+cai agent visibility <agentId> --value organization --json
+```
+
+Members use the published version. Direct actions use the owner's external account and organization usage pool. Grant changes affect Live immediately; private visibility revokes access.
+
+## Before you finish
+
+```bash
+cai agent tools <agentId> --json
+cai agent conversation list <agentId> --mode dev --json
+cai data query --type custom.<type> --env dev --json
+cai agent conversation history <conversationId> --json
+cai agent publish-preflight <agentId> --json
+cai agent versions <agentId> --json
+cai agent test <agentId> --live --message "<representative request>" --json
+```
+
+Run the last three commands only for an authorized release. For Live verification, use `--mode live` and `--env live` in the same pair.
+
+- Conversation list must show the captured ID on the requested rail, without retry-created duplicates.
+- History must show the intended tool arguments, terminal result, and no unresolved permission request.
+- For stateful behavior, the same-rail data query must show the expected record; an assistant reply is not proof.
+- A release requires clean preflight, agent version read-back, and one fresh Live conversation. Draft-only work must remain unpublished.
+
+Report the agent ID/version, tools and confirmation policies, execution or direct-action evidence, rail state, connections, access, and anything unverified.

package/skills/controllerai-ai-nodes/SKILL.md

@@ -1,105 +1,24 @@
 ---
 name: controllerai-ai-nodes
-description: Configure and verify AI-powered Controller AI workflow nodes, especially Ask AI and actions that interact with Controller AI agents. Use when a workflow needs generation, classification, extraction, summarization, structured AI output, model/provider selection, or a workflow action that creates or messages an agent conversation.
+description: Configure Controller AI AI-powered workflow actions for generation, extraction, classification and structured results, or call a Controller AI agent from a flow. Use when deterministic workflow steps need language-model reasoning.
 ---
 
-# Controller AI AI nodes
+# AI inside a workflow
 
-The `cai ...` examples are canonical grammar. Use the transport selected in `controllerai-start` and its MCP tool map; never mix transports in one task.
+Use an AI action when a flow needs generation, extraction, classification or summarization. Use ordinary data/condition nodes for exact validation and CRUD. A user-facing conversational assistant is an agent; an AI node is one step in a workflow.
 
-## Rules that break tasks when skipped
+Discover the available AI action and current properties. Configure the connection/model, prompt and output contract using the action's actual schema. For an action calling a Controller AI agent, select the intended agent and verify which conversation/result fields it returns.
 
-- Use native Ask AI for a bounded AI step; see Configure Ask AI in dependency order.
-- Keep an existing Ask AI node unless the requested component changes; see Configure Ask AI in dependency order.
-- Set reload selectors before fetching live model options; see Configure Ask AI in dependency order.
-- Never invent or hardcode a model ID; see Configure Ask AI in dependency order.
+## Structured results
 
-## Choose the AI surface
+Define the schema before downstream mappings. State the required fields, allowed statuses and missing-data behavior in the prompt. Configure the action's structured output mechanism when available. A prompt saying “return JSON” alone does not establish a typed output contract.
 
-- Use Ask AI for one bounded transformation with explicit inputs and output contract.
-- Use a Controller AI agent for conversational judgment, multiple tools, durable instructions, and knowledge files. Load `controllerai-agents`.
-- Use `registry_agent` workflow actions only when a workflow must create/message a platform agent conversation or manage its files; discover the exact action and props rather than treating the whole agent as one node.
+For contact research, separate evidence from interpretation. Return source URLs, matched identity, confidence and explicit missing/ambiguous status. “Not found in this search” does not establish that a contact method does not exist. Do not fill an email field with an invented pattern.
 
-## Configure Ask AI in dependency order
+A research provider can return variable or unstructured material. Add a typed normalization step when the final flow promises stable fields. Test missing fields, conflicting matches and provider failure as well as the happy path.
 
-For a bounded workflow transformation, use the native Ask AI component. Do not replace it with a provider integration action or delete an existing Ask AI node to bypass configuration.
+## Verify
 
-Discover the current component instead of hardcoding a key:
+Run with representative input, inspect the actual output schema and value, then wire downstream nodes from the confirmed output. Verify the final flow return contract. If a connected provider rejects authentication, report the connection and error code without echoing credentials.
 
-```bash
-cai integration actions "ask AI" --json
-cai integration action --integration <nodeSlug> --key <nodeKey> --json
-cai node init --flow <flowId> --node <nodeSlug> --key <nodeKey> --name "<result produced>" --json
-cai node status <nodeId> --json
-```
-
-Typical selectors are provider, model, prompt/user message, and response data type. Trust current prop metadata over these names.
-
-1. Set the provider or other `reloadProps` selector.
-2. Re-read props.
-3. Fetch live model options; never invent a model identifier.
-4. Set the returned model value.
-5. Set the response type.
-6. Author the prompt with expression context.
-
-```bash
-cai node set <nodeId> --prop <providerProp> --value '<provider>' --json
-cai node props <nodeId> --json
-cai node options <nodeId> --prop <modelProp> --query '<model family>' --json
-cai node set <nodeId> --prop <modelProp> --value '<returned value>' --label '<returned label>' --json
-cai expr set <nodeId> --prop <promptProp> --js '<prompt expression>' --json
-```
-
-MCP: `node set` and `expr set` both use `node_prop_set`; pass exactly one of `value` or `js` here.
-
-Model catalogs, availability, and prices change. Use current options and the user's cost/quality preference. If the requested model is absent, leave it unset, report it, and ask; never substitute.
-
-## Prefer typed output for downstream logic
-
-If downstream nodes need fields, create a small `custom.*` shape first:
-
-```bash
-cai schema create custom.classification \
-  --field category:text:"Category" \
-  --field confidence:number:"Confidence" \
-  --field rationale:text:"Rationale" \
-  --json
-cai node set <nodeId> --prop <responseTypeProp> --value 'custom.classification' --json
-```
-
-Tell the model exactly what each field means, allowed values, and how to represent uncertainty. Never parse free-form prose downstream when a structured response contract is available.
-
-## Prompt contract
-
-A useful workflow prompt contains only behavior-changing material:
-
-- Task and audience
-- Actual input data through exact bindings
-- Decision rules and constraints
-- Required output fields/format
-- Explicit uncertainty or no-data behavior
-
-Avoid filler personas, repeated instructions, and claims about data not present in expression context. For untrusted input, delimit it clearly and state that embedded instructions are data, not authority.
-
-Read [references/selection-and-testing.md](references/selection-and-testing.md) for node choice and evaluation.
-
-## Before you finish
-
-```bash
-cai node get <nodeId> --json
-cai node status <nodeId> --json
-cai node props <nodeId> --json
-cai run node <nodeId> --inputs values.json --json
-cai exec node <nodeExecutionId> --full --json
-```
-
-MCP: pass parsed values in `inputs` and set `waitSeconds` on `run_node`.
-
-Test at least: normal input, missing/ambiguous input, and an adversarial or boundary case relevant to the task. Check resolved prompt/config, output type, required fields, and values—not just that text was returned.
-
-- `node get` must identify the intended native Ask AI component.
-- `node status` must report ready.
-- Props must contain the exact returned provider/model value and label.
-- The execution must show the resolved prompt and typed output fields.
-
-AI execution inside the workflow is platform/API usage. Access through either builder transport does not transfer the coding-agent subscription to runtime AI nodes.
+Configuration commands: [reference](references/command-reference.md). Action selection and testing: [details](references/selection-and-testing.md).