@controllerai/cli 0.2.17 → 0.2.20

package/skills/controllerai-node-config/references/command-reference.md

@@ -0,0 +1,186 @@
+# Controller AI node configuration
+
+
+A node is ready only after its component, connection, dependency-ordered props, wiring, and output type are valid. Treat configuration as a state machine, not a bag of property writes.
+
+## Deterministic sequence
+
+### 1. Find an exact component
+
+```bash
+cai integration actions "<capability>" --json
+cai integration action --integration <nodeSlug> --key <nodeKey> --json
+```
+
+Use the returned `nodeSlug` and full `key`. Do not infer a component key from its display name. If discovery is broad, narrow it with:
+
+```bash
+cai integration search "<integration>" --actions --json
+cai integration actions "<action>" --integration <nodeSlug> --json
+```
+
+Inspect static prop metadata before creating the node. `required`, `remoteOptions`, and `reloadProps` determine configuration order.
+
+### 2. Resolve the account
+
+If the component requires auth:
+
+```bash
+cai connection list --node <nodeSlug> --json
+```
+
+- One active connection: use its exact `id` as the `connectionId`.
+- Several: use an explicit user preference; otherwise ask which account.
+- None: add the real component without `--connection`; `missingConnection: true` is a valid handoff state. On CLI, get the link with `cai connection connect <nodeSlug> --no-open` and share it right away; do not block on `--wait` before sharing.
+
+  MCP: call `connection_connect_url` with `nodeSlug`, show its `url` as a markdown link, ask the user to finish, then confirm with `connection_list` using its `integration`.
+
+  After they confirm, run `cai connection list --integration <nodeSlug> --json` and bind the new ID with `cai node set-connection <nodeId> --connection <connectionId>`.
+
+Never substitute a connection from a similar slug.
+
+Rename or change the default with `cai connection update <id> [--name "<displayName>"] [--default|--no-default]` (MCP: `connection_update`); delete only intentionally with `cai connection delete <id> --yes` (MCP: `connection_delete`).
+Deleting a connection immediately removes authorization from bound nodes and agent tools.
+
+A missing connection is never a reason to substitute `registry_http-http-request` for a catalog component. A raw endpoint mentioned by the user is background context, not an instruction to hand-roll the call.
+
+### 3. Initialize once
+
+```bash
+cai node init \
+  --flow <flowId> \
+  --node <nodeSlug> \
+  --key <nodeKey> \
+  --name "<data this node produces>" \
+  --connection <connectionId> \
+  --after <upstreamNodeId> \
+  --json
+```
+
+MCP: use `node_add`; `cai node init` is the CLI alias of `cai node add`.
+
+Omit flags that do not apply. `--after` creates the ordinary main/error wire at creation. Use it when later props need upstream data. Initialization also accepts `--props`, but use it only for static, non-option values already present in the inspected component metadata. Never inline a `remoteOptions` value, a reload selector and its dependents, or a prop that has not materialized yet; initialize first and set those sequentially. Use `--enable-prop <name...>` only for optional props confirmed by component metadata.
+
+Capture the returned `nodeId`; do not rediscover it by name. Inspect the complete create result before projecting fields. A missing projection is not proof that creation failed, so read the captured ID or exact flow inventory before any retry.
+
+When repairing an existing node, keep its node ID and configure it in place. Do not delete and recreate it merely to clear bad props, select a component, or refresh generated props; deletion discards wiring, conditions, and identity-based references. Replace it only when the requested component itself must change. Then capture the replacement ID, reconnect every dependent, and revalidate them.
+
+### 4. Follow readiness, not guesses
+
+```bash
+cai node status <nodeId> --json
+cai node props <nodeId> --json
+```
+
+For option-backed props, `node props` and write readback may report `optionsAvailability`: `available`, `blocked_upstream` with `blockedBy`, or `dynamic_upstream`. It is positional: earlier single `DROPDOWN` selectors gate later options. Older backends, and responses without a dependency catalog, may omit it; treat absence as unknown, not available.
+
+Work through blockers in this order:
+
+1. Missing connection
+2. Required selector props with `reloadProps`
+3. Newly revealed required props
+4. Static and remote-option props
+5. Wiring required for expressions
+6. Expressions
+7. Unresolved output type
+
+Follow `next`. When a disabled required prop has an activating selector, its blocker names that selector; when it is the next blocker, `next` gives the exact `cai node set` command. `dynamicSelectorNotes` is non-blocking: a node may read ready while its dynamic selector's dependents still reflect the last concrete resolution.
+
+After every concrete reload-selector or connection change, re-run `node props`; dynamic props can appear, disappear, or reset. Use `cai node reload <nodeId> --json` to re-resolve without re-setting a selector. If an explicit reload finds an unset materialized reload selector, it returns `reconcileSkipped: "unset_selector"` plus a note and preserves materialized dependent props instead of reconciling them.
+
+### 5. Set props safely
+
+Static value:
+
+```bash
+cai node set <nodeId> --prop <exactName> --value '<literal-or-json>' --json
+```
+
+MCP: use `node_prop_set` with `value`; it also handles expression writes through `js`.
+
+Optional prop:
+
+```bash
+cai node optional-props <nodeId> --json
+cai node set <nodeId> --prop <exactName> --value '<literal-or-json>' --json
+# or: cai expr set <nodeId> --prop <exactName> --js '<expression>' --json
+```
+
+MCP: `cai expr set` is the `js` form of `node_prop_set`.
+
+`node set` and `expr set` auto-enable a catalog-only optional prop, refresh its metadata, then write. Do not run a separate enable step first. If validation or the later write fails, the prop stays enabled; repair with `cai node disable-prop <nodeId> --prop <exactName>` and re-read props. This is also the repair for the Update-data wipe footgun: that action writes every enabled field, so disable any accidentally enabled field before running it.
+
+MCP: use `node_optional_prop_set` with `enabled: false` to disable or `enabled: true` to enable.
+
+Remote or dynamic option:
+
+```bash
+cai node options <nodeId> --prop <exactName> --query "<specific label>" --json
+cai node set <nodeId> \
+  --prop <exactName> \
+  --value '<returned value>' \
+  --label '<returned label>' \
+  --json
+```
+
+`node options` also supports `--prev-context '<context JSON>'` from the preceding page and repeatable `--for '<earlierProp>=<value>'` overrides for read-only hypothetical resolution; JSON literals are accepted and bare text stays a string. If options are `blocked_upstream`, both `node options` and `node set` name the blocking prop and print the exact `cai node set` command to run first.
+
+For an ordinary remote option, preserve both fields from the same returned option. The label is not cosmetic: it is used to search providers that do not index opaque IDs, then the returned value is verified before writing. For a multi-select, pass a JSON array of returned values and one `--label` argument per value, in the same order. The write supplies the persisted label shape, chooses the correct expression storage channel, and verifies read-back.
+
+When an earlier selector makes the prop `dynamic_upstream`, no option list exists. Use a known exact ID or an expression:
+
+```bash
+cai node set <nodeId> --prop <exactName> --value '<exact-id>' --label '<display label>' --json
+cai node set <nodeId> --prop <exactName> --js '<expression>' --json
+```
+
+`--value` stores the literal without provider-option validation and prints a note; on a label-bearing selector, `--label` controls its display label. This is the sole raw `--value` exception when the CLI has an advertised option set: outside `dynamic_upstream`, a missing prop row, a failed or empty advertised remote-options lookup, or a value absent from advertised options fails closed. The exception still requires prop metadata and verified read-back. Do not bypass failures with a raw API call.
+
+For components whose dependent props exist only after a concrete selector value, use a template first: set one concrete value, re-read `node props`, configure or record the revealed dependents, then switch the selector to `--js`. Those materialized props persist as the last concrete schema. Starting dynamic leaves them absent; neither that write nor `node reload` materializes them until one concrete selection is made.
+
+For dynamic values, load `controllerai-expressions` and prefer `cai expr set`.
+
+### 6. Wire and verify
+
+Ordinary outputs:
+
+```bash
+cai node connect --flow <flowId> --from <sourceNodeId> --to <targetNodeId> --output main --json
+```
+
+Use `--output error` only for the automatic error path. Router and If/Else outputs require `cai branch connect` from the flow-control skill.
+
+Finish with:
+
+```bash
+cai node status <nodeId> --json
+cai run node <nodeId> --inputs <values.json> --json
+```
+
+MCP: `run_node` takes the parsed `inputs` object and `waitSeconds` (default 60, max 120).
+
+If the node has a wired input or consumes `inputs.<name>`, the node test is only an isolated configuration check. Run `cai run flow <flowId> --inputs <values.json> --json` before declaring its upstream expressions verified.
+
+MCP: `run_flow` takes the parsed `inputs` object and `waitSeconds` (default 60, max 120).
+
+If a dynamic provider action cannot be run but its response is documented, declare an unverified output contract:
+
+```bash
+cai node declare-output <nodeId> --sample-file provider-response.json --json
+```
+
+MCP: call `node_output_type_declare` with the parsed provider response in `sample`; the server cannot read `provider-response.json`.
+
+The sample must be a JSON object or a non-empty JSON array of provider items. Re-read status and expression context afterward; the first real completed run verifies the declaration.
+
+Read [prop-and-readiness.md](prop-and-readiness.md) when a prop is dynamic, option-backed, expression-capable, or unexpectedly absent.
+
+## Hard rules
+
+- Configure props in returned order; later props may depend on earlier values.
+- Never write a prop absent from `node props`.
+- Let `node set` or `expr set` auto-enable catalog-only optional props; disable the prop explicitly after a failed write.
+- Wire before authoring an expression that consumes upstream data.
+- Changing a connection invalidates connection-scoped options; re-read props and options.
+- A successful write is not completion. Require read-back plus `node status`.
+- If output type remains unresolved, perform a realistic development test and inspect the resulting execution. Declare only a documented provider sample; never fabricate an output schema.

package/skills/controllerai-runs/SKILL.md

@@ -1,133 +1,41 @@
 ---
 name: controllerai-runs
-description: Run and debug Controller AI nodes on development and flows on development or the published live version — execution history, ports, outputs, skip reasons, and resolved configs. Use when verifying or testing a build, investigating a failed or green-but-wrong run, resolving an unknown output type, checking expression values, or proving what data and configuration reached each node.
+description: Test and debug Controller AI workflows, flows and nodes using execution history, inputs, resolved configuration, ports, output values and record effects. Use to prove a build works or investigate a failed or suspicious result.
 ---
 
-# Controller AI runs
+# Prove workflow behavior
 
-The `cai ...` examples are canonical grammar. Use the transport selected in `controllerai-start` and its MCP tool map; never mix transports in one task.
+Execution tools show what the platform actually ran: inputs, node configuration, output values, selected ports, skips and errors. Use them to verify contracts and effects, not just a green status.
 
-Think "real run", not "simulation". `run node` always uses development; `run flow` defaults to development and can target the published live version. Both rails execute real integration actions (messages send, records change, provider usage is spent); development isolation covers the data store only. Running is a required part of building — one successful run is how a dynamic node's output type gets resolved for the next step — so mitigate risk before running.
+## Select the right test
 
-## Consequential actions: mitigate with the user, don't refuse
+- Test a **node** to establish its configuration, provider connection or output shape. Node tests use development state.
+- Run a **flow** to verify connected steps and the return contract. Choose development or the published live version explicitly.
+- Test an **agent conversation** to verify its tool choice and file handling, then correlate workflow calls with their executions.
+- Replay a **trigger sample** into development to verify event-to-flow mapping before enabling live behavior.
 
-Before running an action with external consequences (send, reject, delete, charge), tell the user plainly what will really happen and ask for a safe target:
+Development and live use different data stores, but development provider actions can still perform real external operations. Test within the user's authorized scope and use synthetic data where appropriate.
 
-- Email/message sends → "What address/channel can I send the dev run to?" (often the user's own).
-- Record deletes/updates → "Is there a record I can safely use, or shall I create one first and delete that?"
-- People-affecting actions (e.g. reject a candidate) → "Which one is safe to use for this run?"
+## Run and inspect
 
-If the user declines running the action, accept it. Then keep the build honest: declare the node's output contract from the provider's documented response —
+Inspect required inputs, pass explicit representative values, and capture the returned execution ID. MCP runs support a bounded wait. A timeout or running status means inspect that execution later; it does not mean repeat the operation.
 
-```bash
-cai node declare-output <nodeId> --sample-file shape.json
-```
+Start with the compact execution summary or tree. Drill into a failing, skipped or suspicious node to inspect its received inputs, resolved config and output. Check the expected port before moving downstream. Compare an actual returned value with the promised flow contract.
 
-MCP: call `node_output_type_declare` with parsed JSON in `sample`; the server cannot read `shape.json`.
+For data changes, query the affected records on the same environment. For files, verify the returned artifact and contents. For direct provider actions, verify the provider result or intended external state rather than expecting a workflow ID.
 
-— where `shape.json` is a representative response object from the provider's API reference. The contract is marked `declared (unverified)`; the first real completed run verifies and upgrades it automatically. State clearly that it is unverified until then, and make the first live run the explicit verification step. Never silently skip the question and never present an unrun action as verified.
+## Diagnose common failures
 
-## First live run is part of development
+| Symptom | Inspect next |
+| --- | --- |
+| Missing required config | Selector choice, refreshed props, enabled fields and literal/expression mode |
+| Unknown field/binding | Node expression context, exact connection output and current input binding |
+| Empty query | Record environment, field key, optional-filter handling and matching semantics |
+| Provider authentication failure | Connection identity and provider error code; saved active status is not a fresh credential test |
+| Green run but no useful output | Return-node mappings, skipped branches and resolved empty values |
+| Mutation result too large or uncertain | Download/reference receipt and exact current target state before retrying |
+| Graph changed unexpectedly | Saved-state history and current node/edge identities; do not replace a newer graph with a cached copy |
 
-After publishing, run the published version directly under supervision:
+Fix the cause and rerun the affected scenario. Broaden tests when the fix changes shared behavior. Keep failed-run evidence with a clear distinction between historical failures and the final verified result.
 
-```bash
-cai run flow <flowId> --inputs values.json --target live --confirm-live --json
-```
-
-MCP: pass parsed values in `inputs` and set `waitSeconds` on `run_flow`.
-
-This command fires external actions and spends usage. For risky sends, build the safe-audience harness: branch on the `isLiveVersion` data source with If/Else — the false branch targets the developer (own email/channel), the true branch targets the real audience. Use this direct live run for explicit verification; do not wait for a real trigger event.
-
-## Prepare exact run inputs
-
-```bash
-cai run inputs <nodeId> --json
-cai run inputs <flowId> --flow --json
-```
-
-Use returned opaque input IDs. Flow mode lists EVERY declared input with a `used` flag: supply the used ones (an unsupplied used input falls back to its saved test value), while values keyed to unused inputs are accepted and ignored. The input object can be a flat map; the CLI may load it from a file:
-
-```json
-{
-  "<inputId>": "representative value"
-}
-```
-
-Do not key test values by a guessed display name.
-
-Before an isolated node run, `cai run inputs <nodeId> --json` calls `get_node_test_inputs`; supply every referenced `flowInputs[].id` explicitly. Missing one fails before execution with `ISOLATED_FLOW_CONTEXT_REQUIRED`. Explicit `null`, `""`, `false`, and `0` are valid supplied values.
-
-Date-typed inputs take plain ISO-8601 strings, e.g. `"2026-06-05"` or `"2026-06-05T12:30:00Z"` (no double-encoding, no epoch strings).
-
-## Run the smallest useful scope
-
-Start with a changed node, then run its containing flow:
-
-```bash
-cai run node <nodeId> --inputs values.json --json
-cai run flow <flowId> --inputs values.json --json
-```
-
-MCP: pass parsed values in `inputs` and set `waitSeconds` on `run_node` or `run_flow`.
-
-`run node` is deliberately isolated: it does not execute wired upstream nodes. Read its `runScope`. If `endToEndValidationRequired` is true, values derived from upstream can be empty even when the selected node is green; do not accept that run as expression proof. `run flow` is the end-to-end check that executes upstream wiring.
-
-The CLI waits for a terminal execution state by default. MCP polling is bounded by `waitSeconds` and may return an unfinished execution ID. Capture `workflowExecutionId` and `nodeExecutionId` from the result.
-
-For every node test, inspect:
-
-- `status` and `errorMessage`
-- `skipReason`
-- `runScope`, especially `upstreamNodesExecuted` and `endToEndValidationRequired`
-- `resolvedConfigs`
-- `resolvedConfigs[].resolutionWarnings`: trust every structured entry; `[]` is authoritatively clean. Also read any transport warnings; CLI runs may mirror them on stderr.
-- `outputTypeAdoption`: the server verifies the exact completed `nodeExecutionId`, derives its persisted output shape, and updates only that non-static node. `adopted` or `already_typed` lets the next `node status` converge; `no_observed_output` means the representative run returned no reusable shape. `adoptedNodeIds` must be empty or contain only the tested node; stop if it names a sibling.
-- output shape and values
-
-A dynamic prop with a null/empty resolved config is a failure even when status is green. `0` and `false` are valid resolved values.
-
-## Debug from the execution tree
-
-```bash
-cai exec tree <workflowExecutionId> --limit 50 --json
-cai exec get <workflowExecutionId> --json
-cai exec flow <flowExecutionId> --json
-cai exec node <nodeExecutionId> --full --json
-```
-
-Page with the returned `nextCursor` via `--cursor`; narrow large runs with repeatable `--status`
-or `--flow <flowId>`. Use the tree to locate the first unexpected status. Use the full node
-execution to inspect its status, resolved configuration, and untruncated output. Read
-[references/debugging.md](references/debugging.md) for the fault-isolation order.
-
-## Output discovery
-
-Prefer a configured node test. If a component is not yet in the graph, `run discover` creates a scratch node and deletes it after execution:
-
-```bash
-cai run discover \
-  --node <nodeSlug> \
-  --key <nodeKey> \
-  --connection <connectionId|none> \
-  --props '<json>' \
-  --json
-```
-
-MCP: `run_discover` always removes the scratch graph and exposes neither `keep` nor `waitSeconds`.
-
-This calls the real third-party action and spends usage. For a destructive action, do not probe merely to learn its output — first ask the user for a safe target (see "Consequential actions" above); if they decline, declare the expected shape instead. On CLI, use `--keep` only when the user wants the scratch node retained.
-
-After successful output discovery, re-read `cai node status` and downstream `cai expr context`; verify the adopted output type is concrete.
-
-## Completion gate
-
-- CLI scripts may gate on `cai workflow validate` exiting 1; MCP callers inspect `valid` and `errors`.
-- The test exercised the changed path with credible values.
-- The first unexpected node, if any, was identified rather than inferred from the final error.
-- All dynamic configs resolved to intended values.
-- Output fields and types match downstream expectations.
-- Branch skips are intentional and error paths are accounted for.
-- A full flow test passes after isolated node fixes.
-- `completed` with an empty or null output is treated as a failure until the output values are read and explained — an empty result usually means a mis-mapped input or an expression that null-propagated silently.
-- The final report cites execution IDs and distinguishes development testing from live verification.
+Commands: [reference](references/command-reference.md). Execution details: [debugging](references/debugging.md).

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

@@ -0,0 +1,113 @@
+# Controller AI runs
+
+
+Think "real run", not "simulation". `run node` always uses development; `run flow` defaults to development and can target the published live version. Both rails execute real integration actions (messages send, records change, provider usage is spent); development isolation covers the data store only. Running is a required part of building — one successful run is how a dynamic node's output type gets resolved for the next step — so mitigate risk before running.
+
+## Consequential actions: mitigate with the user, don't refuse
+
+Use the task's existing authorization and a safe test target for actions with external consequences. For authorized CRUD testing, create synthetic records and exercise updates/deletion on those. Ask only when a needed external side effect or target is not covered by the user's request. Test runs execute real actions.
+
+## First live run is part of development
+
+After publishing, run the published version directly under supervision:
+
+```bash
+cai run flow <flowId> --inputs values.json --target live --confirm-live --json
+```
+
+MCP: pass parsed values in `inputs` and set `waitSeconds` on `run_flow`.
+
+This command fires external actions and spends usage. For risky sends, build the safe-audience harness: branch on the `isLiveVersion` data source with If/Else — the false branch targets the developer (own email/channel), the true branch targets the real audience. Use this direct live run for explicit verification; do not wait for a real trigger event.
+
+## Prepare exact run inputs
+
+```bash
+cai run inputs <nodeId> --json
+cai run inputs <flowId> --flow --json
+```
+
+Use returned opaque input IDs. Flow mode lists EVERY declared input with a `used` flag: supply the used ones (an unsupplied used input falls back to its saved test value), while values keyed to unused inputs are accepted and ignored. The input object can be a flat map; the CLI may load it from a file:
+
+```json
+{
+  "<inputId>": "representative value"
+}
+```
+
+Do not key test values by a guessed display name.
+
+Before an isolated node run, `cai run inputs <nodeId> --json` calls `get_node_test_inputs`; supply every referenced `flowInputs[].id` explicitly. Missing one fails before execution with `ISOLATED_FLOW_CONTEXT_REQUIRED`. Explicit `null`, `""`, `false`, and `0` are valid supplied values.
+
+Date-typed inputs take plain ISO-8601 strings, e.g. `"2026-06-05"` or `"2026-06-05T12:30:00Z"` (no double-encoding, no epoch strings).
+
+## Run the smallest useful scope
+
+Start with a changed node, then run its containing flow:
+
+```bash
+cai run node <nodeId> --inputs values.json --json
+cai run flow <flowId> --inputs values.json --json
+```
+
+MCP: pass parsed values in `inputs` and set `waitSeconds` on `run_node` or `run_flow`.
+
+`run node` is deliberately isolated: it does not execute wired upstream nodes. Read its `runScope`. If `endToEndValidationRequired` is true, values derived from upstream can be empty even when the selected node is green; do not accept that run as expression proof. `run flow` is the end-to-end check that executes upstream wiring.
+
+The CLI waits for a terminal execution state by default. MCP polling is bounded by `waitSeconds` and may return an unfinished execution ID. Capture `workflowExecutionId` and `nodeExecutionId` from the result.
+
+For every node test, inspect:
+
+- `status` and `errorMessage`
+- `skipReason`
+- `runScope`, especially `upstreamNodesExecuted` and `endToEndValidationRequired`
+- `resolvedConfigs`
+- `resolvedConfigs[].resolutionWarnings`: trust every structured entry; `[]` is authoritatively clean. Also read any transport warnings; CLI runs may mirror them on stderr.
+- `outputTypeAdoption`: the server verifies the exact completed `nodeExecutionId`, derives its persisted output shape, and updates only that non-static node. `adopted` or `already_typed` lets the next `node status` converge; `no_observed_output` means the representative run returned no reusable shape. `adoptedNodeIds` must be empty or contain only the tested node; stop if it names a sibling.
+- output shape and values
+
+A dynamic prop with a null/empty resolved config is a failure even when status is green. `0` and `false` are valid resolved values.
+
+## Debug from the execution tree
+
+```bash
+cai exec tree <workflowExecutionId> --limit 50 --json
+cai exec get <workflowExecutionId> --json
+cai exec flow <flowExecutionId> --json
+cai exec node <nodeExecutionId> --full --json
+```
+
+Page with the returned `nextCursor` via `--cursor`; narrow large runs with repeatable `--status`
+or `--flow <flowId>`. Use the tree to locate the first unexpected status. Use the full node
+execution to inspect its status, resolved configuration, and untruncated output. Read
+[debugging.md](debugging.md) for the fault-isolation order.
+
+## Output discovery
+
+Prefer a configured node test. If a component is not yet in the graph, `run discover` creates a scratch node and deletes it after execution:
+
+```bash
+cai run discover \
+  --node <nodeSlug> \
+  --key <nodeKey> \
+  --connection <connectionId|none> \
+  --props '<json>' \
+  --json
+```
+
+MCP: `run_discover` always removes the scratch graph and exposes neither `keep` nor `waitSeconds`.
+
+This calls the real third-party action and spends usage. For a destructive action, do not probe merely to learn its output — first ask the user for a safe target (see "Consequential actions" above); if they decline, declare the expected shape instead. On CLI, use `--keep` only when the user wants the scratch node retained.
+
+After successful output discovery, re-read `cai node status` and downstream `cai expr context`; verify the adopted output type is concrete.
+
+## Completion gate
+
+- CLI scripts may gate on `cai workflow validate` exiting 1; MCP callers inspect `valid` and `errors`.
+- The test exercised the changed path with credible values.
+- The first unexpected node, if any, was identified rather than inferred from the final error.
+- All dynamic configs resolved to intended values.
+- Output fields and types match downstream expectations.
+- Branch skips are intentional and error paths are accounted for.
+- A full flow test passes after isolated node fixes.
+- `completed` with an empty or null output is treated as a failure until the output values are read and explained — an empty result usually means a mis-mapped input or an expression that null-propagated silently.
+- The final report cites execution IDs and distinguishes development testing from live verification.

package/skills/controllerai-start/SKILL.md

@@ -1,89 +1,58 @@
 ---
 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 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.
+description: Understand Controller AI and choose, build, test, or operate its agents, workflows, integrations, triggers and workflow data stores through MCP or the cai CLI. Use at the start of a Controller AI task, especially when a user describes an outcome without naming the right platform surface.
 ---
 
-# Start with Controller AI
+# Build with Controller AI
 
-## Transports
+Controller AI is a platform for agents that do work and reusable automations that those agents can call. You are the builder: create and operate the user's artifacts through the connected tools. A **Controller AI agent** is the user-facing assistant you build, not you.
 
-The `cai ...` examples are canonical grammar. Use either the CLI or the typed MCP tools for a task; never mix transports within one task.
+## What the platform can do
 
-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.
+| Building block | What it provides | Choose it for |
+| --- | --- | --- |
+| Agent | Chat, reasoning, uploaded files, knowledge, integration actions and workflow tools | An assistant a person talks to, including “drop this CSV here and enrich it” |
+| Ready integration action | One existing operation in an external app or native service | Search the web, read a sheet, create a CRM contact; attach directly to an agent when sufficient |
+| Workflow | A container of reusable typed flows, shared schemas and durable data | Deterministic processing, business rules, reusable APIs, scheduled or event-driven work |
+| Flow | One callable contract: typed inputs, connected nodes, typed return values | `researchInvestor(name, company)`, `createContact(...)`, `searchContacts(...)` |
+| Nodes and expressions | Actions, calculations, branches, loops and subflow calls | Transform and route values without writing an application server |
+| Workflow data store | Custom schemas and persisted records, with separate development and live stores | A CRM, tracker, knowledge index, audit log or application state |
+| Trigger | Schedule, webhook, email or integration event mapped into a flow | Run an automation without a chat message |
 
-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.
+An agent can call several flows in one workflow. Their inputs become tool arguments and their flow outputs become tool results. The data store is shared by that workflow's flows on the selected environment. Reusable flow contracts make a workflow an agent's application backend.
 
-- **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.
+## Choose the deliverable from the experience
 
-## Your account on MCP
+Use the user's intended interaction, even when they casually call everything a “workflow.”
 
-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.
+- **File dropped into chat → enriched file back:** build an agent plus a per-record enrichment flow. The agent reads the attachment, handles rows and CSV formatting, calls the flow, and shares the resulting file. A workflow's `file` value is hosted-file metadata; it is not a native chat attachment upload or CSV parser.
+- **CRM for an agent:** build a workflow containing typed CRUD/search flows over custom data schemas. Add a conversational agent only if requested or needed for the interaction.
+- **One app operation:** attach the discovered action directly to the agent. A workflow wrapper is useful when it adds validation, transformation, persistence or a stable contract.
+- **Several steps on an event:** build a workflow and trigger. Add an agent when a human also needs to ask questions or direct the process.
 
-## Confirm the setup
+Make reasonable routine choices from context. Ask for missing information only when it changes the intended result; meanwhile finish independent work. A limitation in one surface can often be solved by combining the platform's surfaces. Explain a necessary change in architecture and keep pursuing the original outcome.
 
-On the CLI, run:
+## Orient once, then build
 
-```bash
-cai doctor
-```
+Use `account_status` to identify the connected workspace. MCP is already authenticated and has no local workflow pin: pass the returned `workflowId` on scoped calls. Do not ask an authenticated user to sign up again. Account claiming is optional and relevant to recovery or usage limits, not a build or publishing prerequisite.
 
-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.
+For an existing artifact, resolve its exact ID and inspect its outline or tool list. Keep returned IDs during the task. For a new artifact, create it and use its returned ID; inspect `flowCount` and `nextStep`: reuse a returned default flow, or create the first flow when the workflow is empty.
 
-MCP: use `account_status`; local diagnosis, login, and `cai connect` do not exist.
+Use the tools actually available in the session. MCP takes inline JSON/text; CLI examples take files where shown and accept `--json` for machine-readable output. The [tool map](references/mcp-tool-map.md) maps the CLI grammar to MCP names and exceptions. There is no need to perform local CLI installation to use connected MCP.
 
-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`.
+## Build, verify and deliver
 
-MCP: the OAuth caller is already provisioned; use `account_claim_start` and `account_claim_verify` for optional email claiming.
+1. Define the experience and a small representative test. For a complex API, decide schemas, inputs, outputs and error behavior before assembling nodes.
+2. Discover capabilities and current schemas. Use exact action keys and the current expression bindings rather than guessing names.
+3. Build a complete path, then test its actual outputs and stored or external effects. Expand the proven pattern to the remaining paths.
+4. Validate the graph, inspect suspicious runs, and re-read saved state. A green run alone does not prove returned data or persistence is correct.
+5. Publish when the user's request authorizes a live result. Explicit authorization persists; do not ask again just because publishing is the next step. Verify the live result after publication.
+6. Return product links, the observed result, environment and any concrete limitation. Remove only scratch artifacts you created for abandoned attempts.
 
-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.
+Development graph edits are separate from the published live graph. Publishing does **not** copy development records into the live data store. Agents have their own draft/published versions; agent Test calls development workflows, while Live calls each workflow's latest live release.
 
-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.
+For mutation errors or large-result downloads, inspect the complete result and the target state before retrying a create. Missing projected fields do not prove failure. Never treat an unknown outcome as permission to repeat a write.
 
-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.
+## Go deeper when needed
 
-## Route the outcome
-
-Identify the deliverable before mutating anything:
-
-| Outcome | Load next |
-| --- | --- |
-| A user-facing agent that can converse and act | `controllerai-agents` |
-| One ready app operation attached to an agent | `controllerai-integration-actions` and `controllerai-agents` |
-| A multi-step, triggered, stateful, or reusable automation | `controllerai-workflows` plus the relevant workflow skills |
-| An agent with orchestrated capabilities | `controllerai-agents`, then both integration-action and workflow skills as needed |
-
-Prefer a ready integration action when one existing operation completes the capability. Use a workflow when the behavior needs multiple steps, transformations, branches, loops, durable data, triggers, custom typed input/output, or reuse outside the agent.
-
-If the user's outcome does not reveal whether they want an agent or an automation that runs on an event, ask one short clarifying question. Otherwise proceed with the smallest suitable surface.
-
-## Lock targets before mutation
-
-Before the first write, resolve every existing target against the effective workflow. Prefer an explicit ID or an object already connected to the pinned workflow. When a list is account-wide, filter it by exact name or ID; never take the first, latest, or similarly named result. Read back the chosen object's ID, name, and owning workflow or flow. Keep those IDs for the task and never rediscover the target by name.
-
-Check `ok` and the complete `data` object from every mutation before projecting fields. A missing projected field is not proof that the mutation failed. Read back the returned ID or list the exact target before retrying. Never repeat a create until readback proves the first call created nothing.
-
-## 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 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.
-- 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.
-- A missing business rule is a blocker, not permission to infer one from names or sample data. Ask the user and leave the affected state unchanged.
-- Stop when the requested state and its required evidence are reached. Do not add objects, publish, or keep probing beyond that boundary.
-- When a platform limitation blocks the outcome, STOP and report the partial result with the blocking error; never keep probing until the clock expires.
-
-At completion, report what was created, what is still draft or live, the evidence actually observed, and any connection or user decision still required.
+Load the relevant skill at the point of use: `controllerai-agents`, `controllerai-workflows`, `controllerai-data`, `controllerai-expressions`, `controllerai-node-config`, `controllerai-flow-control`, `controllerai-triggers`, `controllerai-runs`, `controllerai-ai-nodes`, or `controllerai-integration-actions`. Each explains its capability and links detailed command examples. Platform reference: https://docs.getcontroller.ai/llms.txt; hosted current guides: `guide_list` and `guide_get`.

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

@@ -168,3 +168,9 @@ This registry-derived map covers 162 CLI commands and 149 typed MCP tools. CLI e
 | `cai workflow status` | `workflow_status` | `--workflow` → `workflowId` | — |
 | `cai workflow validate` | `workflow_validate` | `--workflow` → `workflowId` | — |
 | `cai workflow versions` | `workflow_version_list` | `<workflowId>` / `--workflow` → `workflowId` | — |
+
+## Conversation files and compact history
+
+`agent_conversation_file_add` accepts `conversationId`, `name`, `type`, and inline text `content`. `agent_conversation_file_list` returns both chat attachments and context files, with `cursor`, `limit`, and `search`. Read UTF-8 content using `agent_conversation_file_read`; retrieve original bytes through `agent_conversation_file_download`, which returns a temporary downloadable URL. Both take the conversation and file IDs.
+
+Conversation history defaults to a compact, paginated message view. Use `limit` and `before`; `raw: true` is for SDK diagnostics only. On the CLI, the corresponding commands are `agent conversation add-file`, `files`, `read-file`, and `download-file --out <path>`. CLI upload uses `--file`, while MCP upload uses inline `content`.