@controllerai/cli 0.2.17 → 0.2.20

package/skills/controllerai-triggers/SKILL.md

@@ -1,222 +1,28 @@
 ---
 name: controllerai-triggers
-description: Discover, configure, create, sample, enable, test, and debug Controller AI triggers. Use when working with schedules, webhooks, email or app events, captured sample payloads, trigger-to-flow mappings, replay, or any question about why an automation did or did not start.
+description: Build and verify Controller AI event-driven workflows using schedules, webhooks, email and integration events. Use for trigger discovery, configuration, samples, event mapping, replay and enabling live execution.
 ---
 
-# Controller AI triggers
+# Run workflows from events
 
-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 captures a schedule, webhook, email or integration event and maps it into a flow's typed inputs. It lets the same reusable processing run without a chat message. The trigger configuration, captured samples and execution state are separate concerns.
 
-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.
+## Build the event path
 
-## Rules that break tasks when skipped
+1. Discover the trigger component and inspect its properties, authorization and output schema.
+2. Create/select the destination flow and define the inputs it needs.
+3. Configure the trigger using the exact component identity. Choose selectors before dependent properties and bind any required connection.
+4. Capture a representative event. Use the returned webhook URL, trigger email address or provider action; do not invent an endpoint.
+5. Inspect/select the captured sample and map its fields into flow inputs using the actual expression context.
+6. Replay the sample on development and verify received inputs, flow outputs and expected record or external effects.
+7. When live operation is authorized, publish the workflow, enable the trigger as needed and verify an actual live event.
 
-- Preserve trigger ID and source during repair; see Create and map.
-- Delete a retired start; disable a reversible pause. See Remove or disable an automatic start.
-- Lifecycle uses `--enable|--disable`; test events use `--allow|--disallow`. See Remove or disable an automatic start and Finish trigger setup.
-- Disarm capture when setup ends; see Finish trigger setup.
-- Lifecycle edits are development-only; publish only for Live. See Verify development, then publish.
-- Replay with `--target dev`; Live also requires `--confirm-live`. See Verify development, then publish.
+Use `trigger_set_enabled` for a reversible pause/resume and `trigger_delete` to remove a retired trigger. Capture can exist before publication; publication controls the live executable definition. Replaying an event can perform real external actions, so use the existing authorization and intended test scope. A recorded event is not proof the flow executed.
 
-## Require a real source decision
+## Diagnose by stage
 
-Determine how the trigger choice was established:
+If there is no event, inspect trigger identity, connection, registration and the source action. If the event exists but inputs are wrong, inspect selected sample and mappings. If the flow starts but fails, follow the execution ID with `controllerai-runs`. Inspect enabled state and published configuration when development works but live does not.
 
-- `explicit-in-request`: user named it in the request
-- `user-answer`: user chose after clarification
-- `inferred-from-existing-workflow`: preserving an existing source
+Schedules need an explicit timezone and intended cadence. Follow the user's cadence; do not infer a production schedule from a test sample. Avoid duplicate triggers while debugging: keep the original trigger and event IDs.
 
-Do not use `assumption`; the backend rejects it. If the request does not determine when the automation runs, ask one focused question before creating a source.
-
-## Discover the exact event
-
-```bash
-cai trigger search "<event intent>" --json
-cai trigger search --node <nodeSlug> --events-per-node 50 --json
-```
-
-Copy the exact `nodeSlug` and `eventKey`. Never infer an event key from its display name.
-
-If authentication is required:
-
-```bash
-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
-cai trigger props \
-  --node <nodeSlug> \
-  --event <eventKey> \
-  --connection <connectionId> \
-  --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 response intentionally omits unresolved required option props rather than emitting a plausible placeholder.
-
-For each name in `unresolvedOptionProps`, run the complete canonical option command returned by the transport, or equivalently:
-
-```bash
-cai trigger options \
-  --node <nodeSlug> \
-  --event <eventKey> \
-  --prop <propName> \
-  --connection <connectionId> \
-  --configured '<configuredPropsJson>' \
-  --dynamic-props-id <dynamicPropsId> \
-  --query "<human option label>" \
-  --json
-```
-
-Copy the exact returned `value`, not its display `label`, into `--configured`, then rerun `trigger props`. Use `--page` and returned `context` via `--prev-context` only when search is unavailable.
-
-When a selector has `reloadProps`, rerun with its configured values and returned `dynamicPropsId` before creating the trigger.
-
-```bash
-cai trigger props \
-  --node <nodeSlug> \
-  --event <eventKey> \
-  --connection <connectionId> \
-  --configured '<configuredPropsJson>' \
-  --dynamic-props-id <dynamicPropsId> \
-  --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 response provides the complete canonical command; do not shorten it to only `--configured`.
-
-Timer values are objects:
-
-```json
-{"cron":{"cron":"0 9 * * *","timezone":"America/Chicago"}}
-```
-
-or
-
-```json
-{"cron":{"intervalSeconds":900}}
-```
-
-Do not pass a bare cron string or assume a timezone. Ask when the user says "at 9am" without one.
-
-## Create and map
-
-```bash
-cai trigger create \
-  --flow <targetFlowId> \
-  --node <nodeSlug> \
-  --event <eventKey> \
-  --source-basis <basis> \
-  --connection <connectionId> \
-  --props '<json>' \
-  --dynamic-props-id <id> \
-  --json
-```
-
-Capture all returned IDs. `triggerId` is the canvas ID used for get/rename/set-enabled/delete/test-events. `backendTriggerId` is numeric and used for captured events and replay. They are not interchangeable.
-
-When repairing an existing trigger, preserve its canvas ID and source. Repair its mapping in place; do not delete and recreate it merely to clear readiness. Replacement changes captured IDs and may change a webhook URL. Replace only when the requested source itself must change, then recapture every returned ID.
-
-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).
-
-Follow returned `nextSteps` in order. Trigger payload does not automatically populate the target flow; define flow inputs, relink the run-subflow node if needed, and configure its mapping props.
-
-## 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. Never delete its owning flow merely to remove the trigger. `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 only for an authorized Live change; otherwise the prior Live trigger remains active.
-
-## Establish a typed sample
-
-After sending a representative event to the source:
-
-```bash
-cai trigger events --trigger <backendTriggerId> --json
-cai trigger event <eventId> --json
-cai trigger select-event --node <triggerNodeId> --event <eventId> --json
-```
-
-Then re-read expression context on downstream nodes. A sample without a platform data type may remain untyped.
-
-## Finish trigger setup: disarm test events
-
-Armed test events let real events reach the DEV version while you set the trigger up. They exist for one purpose: capturing the real data shape so it becomes the trigger node's output type. Arming is the START of trigger setup; **disarming is how trigger setup ENDS.** Once the shape is captured, selected, and typed, turn it off — also when a build fails or is abandoned midway:
-
-```bash
-cai trigger test-events --id <triggerId> --disallow
-```
-
-MCP: call `trigger_test_events_set` with `allowed: false`, or `allowed: true` to arm it.
-
-Do not mix the flag families. `set-enabled` takes `--enable` or `--disable`; `test-events` takes `--allow` or `--disallow`; replay takes `--target dev` or `--target live`, with `--confirm-live` for Live.
-
-The acknowledgements are distinct: `--acknowledge-dual-run` applies only while arming, `--acknowledge-dual-dispatch` only while publishing an armed trigger, and `--confirm-live` only to one Live replay.
-
-Arming is sticky and independent from enablement. Armed plus live dispatch runs each real event twice; a schedule does so every interval. Disabling does not clear the allow flag, so always disallow after capture.
-
-Keeping both rails armed is an uncommon 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. MCP `run_flow` calls take `waitSeconds`.
-
-```bash
-cai trigger replay --trigger <backendTriggerId> --event <eventId> --target dev --json
-cai exec tree <workflowExecutionId> --json
-```
-
-A development replay never dispatches live, but nodes still call real providers and can create side effects or spend usage. Publish only after mappings and development behavior pass.
-
-A draft-only request stops after development proof. Do not publish merely because the trigger is ready.
-
-Before publishing, audit EVERY trigger in the workflow — not just the one you worked on. Users forget triggers left enabled or armed in other flows. Read each row's lifecycle fields from `cai trigger list --json` (`devCanvasEnabled`, `deployment.liveCanvasEnabled`, `deployment.inLiveVersion`, `deployment.devDispatchArmed`, `deployment.dualDispatchLive`) and confirm with the user which triggers should be starting this workflow live:
-
-```bash
-cai trigger list --json
-cai workflow publish --name "<release>" --json
-```
-
-If publish fails because a trigger still has test events armed, that error is the designed backstop, not a malfunction: trigger setup was never finished. The normal resolution is to disarm and republish. Publishing WITH an armed trigger requires the user's explicit, informed choice — explain the double-run and double-billing consequence first, then pass the intent flag:
-
-```bash
-cai workflow publish --name "<release>" --acknowledge-dual-dispatch --json
-```
-
-Never pass `--acknowledge-dual-dispatch` on your own initiative.
-
-Live replay is optional and requires an explicit acknowledgement:
-
-```bash
-cai trigger replay \
-  --trigger <backendTriggerId> \
-  --event <eventId> \
-  --target live \
-  --confirm-live \
-  --json
-cai exec tree <workflowExecutionId> --json
-```
-
-It executes the published workflow, calls live third-party actions, and spends usage. Obtain appropriate user intent before replaying a side-effectful event.
-
-Read [references/lifecycle.md](references/lifecycle.md) for trigger state and debugging.
-
-## Before you finish
-
-```bash
-cai trigger get <triggerId> --json
-cai trigger list --json
-cai workflow status --json
-# Only after an authorized create or mapping test:
-cai exec tree <workflowExecutionId> --json
-```
-
-- Read-back must retain the intended trigger, source, target flow, connection, props, and mapping.
-- `devCanvasEnabled`, `liveCanvasEnabled`, and `inLiveVersion` must match the requested rail state.
-- `devDispatchArmed` must be false unless the user explicitly chose dual dispatch; report `dualDispatchLive`.
-- For authorized create/mapping work, the development test must produce the expected tree. Never replay for delete/disable-only work. Live replay needs separate authorization.
+Commands: [reference](references/command-reference.md). Capture, replay and lifecycle details: [lifecycle](references/lifecycle.md).

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

@@ -0,0 +1,215 @@
+# Controller AI triggers
+
+
+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.
+
+
+- Preserve trigger ID and source during repair; see Create and map.
+- Delete a retired start; disable a reversible pause. See Remove or disable an automatic start.
+- Lifecycle uses `--enable|--disable`; test events use `--allow|--disallow`. See Remove or disable an automatic start and Finish trigger setup.
+- Disarm capture when setup ends; see Finish trigger setup.
+- Lifecycle edits are development-only; publish only for Live. See Verify development, then publish.
+- Replay with `--target dev`; Live also requires `--confirm-live`. See Verify development, then publish.
+
+## Require a real source decision
+
+Determine how the trigger choice was established:
+
+- `explicit-in-request`: user named it in the request
+- `user-answer`: user chose after clarification
+- `inferred-from-existing-workflow`: preserving an existing source
+
+Do not use `assumption`; the backend rejects it. If the request does not determine when the automation runs, ask one focused question before creating a source.
+
+## Discover the exact event
+
+```bash
+cai trigger search "<event intent>" --json
+cai trigger search --node <nodeSlug> --events-per-node 50 --json
+```
+
+Copy the exact `nodeSlug` and `eventKey`. Never infer an event key from its display name.
+
+If authentication is required:
+
+```bash
+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
+cai trigger props \
+  --node <nodeSlug> \
+  --event <eventKey> \
+  --connection <connectionId> \
+  --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 response intentionally omits unresolved required option props rather than emitting a plausible placeholder.
+
+For each name in `unresolvedOptionProps`, run the complete canonical option command returned by the transport, or equivalently:
+
+```bash
+cai trigger options \
+  --node <nodeSlug> \
+  --event <eventKey> \
+  --prop <propName> \
+  --connection <connectionId> \
+  --configured '<configuredPropsJson>' \
+  --dynamic-props-id <dynamicPropsId> \
+  --query "<human option label>" \
+  --json
+```
+
+Copy the exact returned `value`, not its display `label`, into `--configured`, then rerun `trigger props`. Use `--page` and returned `context` via `--prev-context` only when search is unavailable.
+
+When a selector has `reloadProps`, rerun with its configured values and returned `dynamicPropsId` before creating the trigger.
+
+```bash
+cai trigger props \
+  --node <nodeSlug> \
+  --event <eventKey> \
+  --connection <connectionId> \
+  --configured '<configuredPropsJson>' \
+  --dynamic-props-id <dynamicPropsId> \
+  --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 response provides the complete canonical command; do not shorten it to only `--configured`.
+
+Timer values are objects:
+
+```json
+{"cron":{"cron":"0 9 * * *","timezone":"America/Chicago"}}
+```
+
+or
+
+```json
+{"cron":{"intervalSeconds":900}}
+```
+
+Do not pass a bare cron string or assume a timezone. Ask when the user says "at 9am" without one.
+
+## Create and map
+
+```bash
+cai trigger create \
+  --flow <targetFlowId> \
+  --node <nodeSlug> \
+  --event <eventKey> \
+  --source-basis <basis> \
+  --connection <connectionId> \
+  --props '<json>' \
+  --dynamic-props-id <id> \
+  --json
+```
+
+Capture all returned IDs. `triggerId` is the canvas ID used for get/rename/set-enabled/delete/test-events. `backendTriggerId` is numeric and used for captured events and replay. They are not interchangeable.
+
+When repairing an existing trigger, preserve its canvas ID and source. Repair its mapping in place; do not delete and recreate it merely to clear readiness. Replacement changes captured IDs and may change a webhook URL. Replace only when the requested source itself must change, then recapture every returned ID.
+
+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).
+
+Follow returned `nextSteps` in order. Trigger payload does not automatically populate the target flow; define flow inputs, relink the run-subflow node if needed, and configure its mapping props.
+
+## 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. Never delete its owning flow merely to remove the trigger. `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 only for an authorized Live change; otherwise the prior Live trigger remains active.
+
+## Establish a typed sample
+
+After sending a representative event to the source:
+
+```bash
+cai trigger events --trigger <backendTriggerId> --json
+cai trigger event <eventId> --json
+cai trigger select-event --node <triggerNodeId> --event <eventId> --json
+```
+
+Then re-read expression context on downstream nodes. A sample without a platform data type may remain untyped.
+
+## Finish trigger setup: disarm test events
+
+Armed test events let real events reach the DEV version while you set the trigger up. They exist for one purpose: capturing the real data shape so it becomes the trigger node's output type. Arming is the START of trigger setup; **disarming is how trigger setup ENDS.** Once the shape is captured, selected, and typed, turn it off — also when a build fails or is abandoned midway:
+
+```bash
+cai trigger test-events --id <triggerId> --disallow
+```
+
+MCP: call `trigger_test_events_set` with `allowed: false`, or `allowed: true` to arm it.
+
+Do not mix the flag families. `set-enabled` takes `--enable` or `--disable`; `test-events` takes `--allow` or `--disallow`; replay takes `--target dev` or `--target live`, with `--confirm-live` for Live.
+
+The acknowledgements are distinct: `--acknowledge-dual-run` applies only while arming, `--acknowledge-dual-dispatch` only while publishing an armed trigger, and `--confirm-live` only to one Live replay.
+
+Arming is sticky and independent from enablement. Armed plus live dispatch runs each real event twice; a schedule does so every interval. Disabling does not clear the allow flag, so always disallow after capture.
+
+Keeping both rails armed is an uncommon 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. MCP `run_flow` calls take `waitSeconds`.
+
+```bash
+cai trigger replay --trigger <backendTriggerId> --event <eventId> --target dev --json
+cai exec tree <workflowExecutionId> --json
+```
+
+A development replay never dispatches live, but nodes still call real providers and can create side effects or spend usage. Publish only after mappings and development behavior pass.
+
+A draft-only request stops after development proof. Do not publish merely because the trigger is ready.
+
+Before publishing, audit EVERY trigger in the workflow — not just the one you worked on. Users forget triggers left enabled or armed in other flows. Read each row's lifecycle fields from `cai trigger list --json` (`devCanvasEnabled`, `deployment.liveCanvasEnabled`, `deployment.inLiveVersion`, `deployment.devDispatchArmed`, `deployment.dualDispatchLive`) and confirm with the user which triggers should be starting this workflow live:
+
+```bash
+cai trigger list --json
+cai workflow publish --name "<release>" --json
+```
+
+If publish fails because a trigger still has test events armed, that error is the designed backstop, not a malfunction: trigger setup was never finished. The normal resolution is to disarm and republish. Publishing WITH an armed trigger requires the user's explicit, informed choice — explain the double-run and double-billing consequence first, then pass the intent flag:
+
+```bash
+cai workflow publish --name "<release>" --acknowledge-dual-dispatch --json
+```
+
+Never pass `--acknowledge-dual-dispatch` on your own initiative.
+
+Live replay is optional and requires an explicit acknowledgement:
+
+```bash
+cai trigger replay \
+  --trigger <backendTriggerId> \
+  --event <eventId> \
+  --target live \
+  --confirm-live \
+  --json
+cai exec tree <workflowExecutionId> --json
+```
+
+It executes the published workflow, calls live third-party actions, and spends usage. Obtain appropriate user intent before replaying a side-effectful event.
+
+Read [lifecycle.md](lifecycle.md) for trigger state and debugging.
+
+## Before you finish
+
+```bash
+cai trigger get <triggerId> --json
+cai trigger list --json
+cai workflow status --json
+# Only after an authorized create or mapping test:
+cai exec tree <workflowExecutionId> --json
+```
+
+- Read-back must retain the intended trigger, source, target flow, connection, props, and mapping.
+- `devCanvasEnabled`, `liveCanvasEnabled`, and `inLiveVersion` must match the requested rail state.
+- `devDispatchArmed` must be false unless the user explicitly chose dual dispatch; report `dualDispatchLive`.
+- For authorized create/mapping work, the development test must produce the expected tree. Never replay for delete/disable-only work. Live replay needs separate authorization.

package/skills/controllerai-workflows/SKILL.md

@@ -1,126 +1,46 @@
 ---
 name: controllerai-workflows
-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.
+description: Build, inspect, repair, test and publish Controller AI workflows: typed callable flows, deterministic actions, branching, durable workflow data and triggers. Use for automations or an agent-callable application backend.
 ---
 
 # Controller AI workflows
 
-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.
+A workflow groups **flows**, **custom schemas**, **data collections** and **triggers**. A flow is one callable function with typed inputs and outputs; its connected nodes implement the function. Several flows can share the workflow's data store and call one another.
 
-## Rules that break tasks when skipped
+Flows are useful as API-like tools for agents. For example one “Investor CRM” workflow can expose create/get/update/delete/search flows for contacts, companies, deals and activities, plus a contact history view. An agent chooses a tool; the flow enforces its contract and performs the work.
 
-- Lock the effective workflow ID and exact flow ID; see Establish context.
-- Repair the selected workflow and flow instead of creating replacements; see Build protocol.
-- Keep workflow, flow, node, input, and output IDs distinct; see Lifecycle rules.
-- Preserve contract fields in place and refresh their dependents; see Lifecycle rules.
-- Use save, history, and restore for recovery instead of rebuilding; see Lifecycle rules.
-- Treat validation counts as status; prove the requested rail and stop. See Lifecycle rules and Before you finish.
+## Start with the contract
 
-## Establish context
+Define each flow's inputs, outputs and failure behavior. Keep one operation per agent tool when that makes selection clearer than a giant operation dispatcher. Choose useful names and descriptions: “Search contacts by name, owner, tags and status” tells an agent when to call it.
 
-```bash
-cai auth status --json
-cai workflow list --json
-cai use <workflowId>
-cai workflow status --json
-```
+Create the workflow, then explicitly create the first flow. `workflow_outline` provides a compact inventory; `flow_get` provides a flow's contracts, graph and configured values. Workflow IDs, flow IDs and node IDs are different identities.
 
-MCP: use `account_status`, then call `workflow_list` and `workflow_status` with explicit `workflowId`; there is no `cai use` or stored pin.
+Before changing an existing workflow, read its outline and the affected flow. Repair the existing IDs instead of creating replacements. For a substantial rewrite, save a named checkpoint. Restore rolls back the definition, not record changes or external effects.
 
-If no workflow exists, create it with its final name:
+## Assemble and test
 
-```bash
-cai workflow create --name "<clear outcome-oriented name>" --json
-```
+1. Create any custom schemas and flow inputs/outputs first.
+2. Discover actions and add nodes in execution order. Configure the type or action selector before dependent props; reload props if the selector changes.
+3. Bind expressions using current `expr_context` names. Wire the source output to the destination so it appears in `inputs`.
+4. Use a Return node to map promised flow outputs. Merely declaring an output does not populate it.
+5. Test a complete development path with explicit representative input. Check the returned contract and same-environment data changes.
+6. Apply the proven pattern to additional paths. Batch independent configuration when the available tool supports it; do not combine operations whose IDs depend on earlier responses.
+7. Layout each changed flow, validate the saved workflow, and re-read its outline.
 
-Read `selected`, `effectiveWorkflowId`, and `pinSource`; creation may not win the pin. If unselected, remove a command flag, use `cai use <id>` for a stored pin, or clear inherited `CAI_WORKFLOW`, as `pinSource` directs, then re-check. `cai config reset` clears only stored pins. `cai doctor` verifies the effective pin and development head. On MCP, capture and pass the new `workflowId`. Create with the final name.
+Use `controllerai-node-config` for action configuration, `controllerai-expressions` for computed values, `controllerai-flow-control` for routing/loops, `controllerai-data` for storage and `controllerai-runs` for execution evidence.
 
-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.
+## Files and agents
 
-Use IDs returned by the selected transport. For account-wide lists, filter by exact ID or name and owning workflow; never choose the first or latest similar result. Read the selected object's ID, name, and owner once, reuse those IDs, and never rediscover the target by name. A missing projected create field is not failure: inspect the complete result and exact inventory before retrying. Never invent identifiers.
+A chat attachment is handled by a user-facing agent. For CSV enrichment, make a per-row flow accepting `investorName` and optional `company`, returning normalized contact information and evidence. The agent reads and writes the CSV. The native Create File action can generate files; it does not imply a native CSV reader/upload trigger.
 
-To orient inside a workflow, prefer one call over many:
+For an agent tool, attach the tested flow with `agent_tool_workflow_add`. Its flow inputs and outputs are the tool contract. For unattended operation, add a trigger and map its event into these same inputs.
 
-```bash
-cai workflow outline --json
-```
+## Release and recovery
 
-`cai workflow state --json` is bounded; add `--flow <flowId>` for node and edge identities. Use `workflow document` only for complete opaque JSON. `workflow outline` shows flows, contracts, graph `deps`, triggers, and data inventory. Use `flow get` for props and expressions.
+Graph edits affect development. Publishing creates the workflow's live release; attached live agents follow its latest release without another agent publish. The development/live record stores remain separate.
 
-## Build protocol
+Use the user's existing authorization when deciding whether to publish. If publication is authorized, fix validation errors, publish, then verify Live. For a draft-only request, deliver the tested draft and its link.
 
-1. Translate the request into inputs, steps, outputs, trigger, integrations, failure behavior, and publish intent. When the request says to store, save, log, or record something and names no external destination, that means a data type plus a create-record node (`controllerai-data`) — a flow output alone does not persist anything. When the user names the destination (a spreadsheet, a CRM, another app, a file), write there with that integration's node instead; add a platform record only when the user also wants a copy kept here.
-2. Inspect the current workflow before editing: `cai workflow outline`, then `cai flow get <flowId>`. Repair those IDs; do not create replacements for a repair.
-3. Create or select a flow. Define flow inputs and outputs before nodes that derive props from them.
-4. Build in execution order. After each material change, read it back with the corresponding `get`, `props`, `status`, or `list` command.
-5. Run `cai flow layout <flowId>` once per changed flow as the LAST step after a headless build or any batch of structural edits (adds, deletes, rewires) — add-time placement avoids overlap, but only layout produces clean left-to-right columns. An open builder adopts your layout automatically.
-6. Test on the development rail. Debug every failed or suspicious node; a green top-level status alone is insufficient.
-7. Re-read `cai workflow status`. Publish only when the user asked for a live change or clearly authorized deployment.
+On a state conflict, re-read the current saved version and reapply the intended change. Do not overwrite a newer graph with an old document. Report validation issues by their practical effect and inspect empty results where data was expected.
 
-For multi-domain work, read [references/command-map.md](references/command-map.md) before editing.
-
-## Route specialized work
-
-Load the narrow skill when the task reaches that surface:
-
-- Node discovery, initialization, connections, props, or wiring: `controllerai-node-config`
-- Dynamic values or conditions: `controllerai-expressions`
-- Router, If/Else, loops, joins, or subflows: `controllerai-flow-control`
-- Test execution or debugging: `controllerai-runs`
-- Scheduled, webhook, or integration events: `controllerai-triggers`
-- Schemas or records: `controllerai-data`
-- Ask AI or Agent nodes: `controllerai-ai-nodes`
-- User-facing agents and their workflow tools: `controllerai-agents`
-
-## Lifecycle rules
-
-- 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.
-- 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 current binding from `flow get` (`jsBinding`) or `workflow outline` (`binding`). Rename an existing contract input or output in place; do not delete and recreate it. After any rename or deletion, re-read the flow and repair every expression and subflow mapping before validation or execution. `legacyBinding` is diagnostic-only.
-- Name nodes after the data they produce. Downstream input bindings are seeded from that name when wired.
-- Use `cai workflow save --name "<checkpoint>"` before a risky rewrite. Named saves and state renames work on every plan.
-
-```bash
-cai workflow history --json
-cai workflow history --group <groupId> --json
-cai workflow restore --state <stateId> --json
-```
-
-- **Use version history for recovery.** Each save is a state. History retention is unlimited on Free, Max, and custom plans and 90 days on Pro/Starter; restore eligibility is 7 days on Free, 90 on Pro/Starter, and unlimited on Max/custom. Expand groups to capture state IDs. Restore rolls back the definition only; records and external effects remain.
-- **Validate after structural edits and before publish.** Fix every listed prop, wire, expression, type, subflow, branch, and trigger error. Publish refuses errors; use `--acknowledge-validation-errors` only after explicit approval of the listed issues. Flow deletion also removes its contract, graph, and triggers and breaks callers; validation shows each break.
-- Treat validation warning and error counts as status only. Never write them or their messages into unrelated workflow properties.
-- 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. 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.
-- **Check dependencies before shared-resource changes.** `cai deps` shows attached agents, workflow callers, and connections; `cai deps --account` maps the account. Deleting a workflow with agent dependents is refused server-side, and `--force` is a deprecated, inert compatibility flag. Detach draft tools with `cai agent remove-tool <agentId> --tool <toolId>`. If still LIVE, use `cai agent publish <agentId>` after explicit approval. A dependent agent publish or delete is its own live/destructive decision. Then retry deletion.
-- **Use the account feed only for recorded history.** Filter `cai events` by type, time, workflow, and cursor. It omits deletions, settings, member removals, and labels. For an unrecorded past change, say it is not recorded and change nothing; names and current state are not proof.
-- **Share real product links.** Relevant publish, development run, agent, connection, workflow get/status, and agent get outputs include `appUrl` when known. Share returned links; never guess one. MCP `connection_connect_url` returns its link immediately.
-- Never silently weaken the request to make a test pass. Report an unsupported capability or ask about a real product decision.
-
-## Before you finish
-
-Before claiming success, verify all of the following:
-
-```bash
-cai workflow outline --json
-cai workflow validate --json
-cai workflow status --json
-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.
-- Required node connections and props are complete.
-- Expressions compiled and their resolved configs are non-null.
-- Expected branch or error paths were exercised where practical.
-- Flow outputs contain the promised values.
-- The reported live/dev state matches what the user asked for.
-- Final outline inventory matches the request. Remove only scratch schemas, flows, nodes, and triggers created during abandoned attempts.
-- After fixing requested blockers and testing each changed path once, stop. Do not redesign for non-blocking warnings.
-
-State what was built, what was tested, whether it was published, and any user-owned connection or product choice still pending.
+Detailed CLI/MCP sequences and lifecycle operations: [command reference](references/command-reference.md). Multi-domain command lookup: [command map](references/command-map.md).