@controllerai/cli 0.2.20 → 0.2.21

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

@@ -1,8 +1,9 @@
+<!-- generated from .claude/skills by cli/scripts/render-skills.mjs; edit the source -->
 <!-- Generated by cli/scripts/generate-mcp-tool-map.mjs; do not edit by hand. -->
 
 # CLI to typed MCP tool map
 
-This registry-derived map covers 162 CLI commands and 149 typed MCP tools. CLI examples remain the canonical grammar; typed MCP calls use the tool and camelCase parameters shown here. Global `--json` and `--api-url` flags are host-controlled and omitted.
+This registry-derived map covers 165 CLI commands and 149 typed MCP tools. CLI examples remain the canonical grammar; typed MCP calls use the tool and camelCase parameters shown here. Global `--json` and `--api-url` flags are host-controlled and omitted.
 
 | `cai` command | MCP tool | Parameter mapping | Notes |
 | --- | --- | --- | --- |
@@ -25,6 +26,7 @@ This registry-derived map covers 162 CLI commands and 149 typed MCP tools. CLI e
 | `cai agent publish` | `agent_publish` | `<agentId>` → `agentId`; `--name` → `name` | — |
 | `cai agent publish-preflight` | `agent_publish_preflight` | `<agentId>` → `agentId` | — |
 | `cai agent remove-tool` | `agent_tool_remove` | `<agentId>` → `agentId`; `--tool` → `toolId` | — |
+| `agent setup` (CLI only) | — | — | dropped: Configures local coding assistants on the user machine; nothing to do on a hosted server. |
 | `cai agent test` | `agent_test` | `<agentId>` → `agentId`; `--message` → `message`; `--model` → `model`; `--timeout` → `waitSeconds`; `--title` → `title`; `--draft` → `rail=draft`; `--live` → `rail=live` | `waitSeconds` default 60, max 120 |
 | `cai agent tools` | `agent_tool_list` | `<agentId>` → `agentId` | — |
 | `cai agent update` | `agent_set_enabled`<br>`agent_update` | `agent_set_enabled`: `<agentId>` → `agentId`; `--enabled` / `--disabled` → `enabled`<br>`agent_update`: `<agentId>` → `agentId`; `--instructions` / `--instructions-file` → `instructions` (inline content); `--name` → `name` | split across typed tools |
@@ -32,24 +34,24 @@ This registry-derived map covers 162 CLI commands and 149 typed MCP tools. CLI e
 | `cai agent versions` | `agent_version_list` | `<agentId>` → `agentId` | — |
 | `cai agent visibility` | `agent_visibility_set` | `<agentId>` → `agentId`; `--value` → `value` | — |
 | `cai approval resume` | `approval_resume` | `<id>` → `approvalId`; `waitSeconds` (MCP-only) → `waitSeconds` | `waitSeconds` default 60, max 120 |
-| `cai auth key` | — | — | dropped: Mints a long-lived local credential and is not an MCP account operation. |
-| `cai auth login` | — | — | dropped: Starts a local device-code login even though the MCP request is already OAuth-authorized. |
-| `cai auth logout` | — | — | dropped: Deletes local CLI credentials; it is not integration connection revocation. |
-| `cai auth password` | — | — | dropped: Accepts a development email/password credential on the local machine. |
+| `auth key` (CLI only) | — | — | dropped: Mints a long-lived local credential and is not an MCP account operation. |
+| `auth login` (CLI only) | — | — | dropped: Starts a local device-code login even though the MCP request is already OAuth-authorized. |
+| `auth logout` (CLI only) | — | — | dropped: Deletes local CLI credentials; it is not integration connection revocation. |
+| `auth password` (CLI only) | — | — | dropped: Accepts a development email/password credential on the local machine. |
 | `cai auth status` | `account_status` | — | hosted: The host reports the authenticated grant and combines it with server health facts. |
-| `cai auth token` | — | — | dropped: Writes a bearer token into local CLI configuration. |
+| `auth token` (CLI only) | — | — | dropped: Writes a bearer token into local CLI configuration. |
 | `cai branch add` | `branch_add` | `<nodeId>` → `nodeId`; `--allow-duplicate` → `allowDuplicate`; `--condition-json` → `conditionJson`; `--js` / `--js-file` → `js` (inline content); `--name` → `name`; `--workflow` → `workflowId` | — |
 | `cai branch connect` | `branch_connect` | `<nodeId>` → `nodeId`; `--flow` → `flow`; `--route` → `branchId`; `--to` → `to`; `--workflow` → `workflowId` | — |
 | `cai branch delete` | `branch_delete` | `<nodeId>` → `nodeId`; `--route` → `branchId`; `--workflow` → `workflowId` | — |
 | `cai branch list` | `branch_list` | `<nodeId>` → `nodeId`; `--workflow` → `workflowId` | — |
 | `cai branch reorder` | `branch_reorder` | `<nodeId>` → `nodeId`; `--order` → `order`; `--workflow` → `workflowId` | — |
 | `cai branch update` | `branch_update` | `<nodeId>` → `nodeId`; `--condition-json` → `conditionJson`; `--js` / `--js-file` → `js` (inline content); `--name` → `name`; `--route` → `branchId`; `--workflow` → `workflowId` | — |
-| `cai config reset` | — | — | dropped: Clears a local workflow pin; typed MCP calls are stateless. |
-| `cai connect` | — | — | dropped: Installs local skills, opens a browser, and verifies a local project. |
+| `config reset` (CLI only) | — | — | dropped: Clears a local workflow pin; typed MCP calls are stateless. |
+| `connect` (CLI only) | — | — | dropped: Installs local skills, opens a browser, and verifies a local project. |
 | `cai connection connect` | `connection_connect_url` | `<nodeSlug>` → `nodeSlug` | — |
 | `cai connection delete` | `connection_delete` | `<connectionId>` → `connectionId` | — |
 | `cai connection list` | `connection_list` | `--integration` → `integration` | — |
-| `cai connection request` | — | — | dropped: Posts a connect card into build chat; connection_connect_url supplies the hosted outcome. |
+| `connection request` (CLI only) | — | — | dropped: Posts a connect card into build chat; connection_connect_url supplies the hosted outcome. |
 | `cai connection update` | `connection_update` | `<connectionId>` → `connectionId`; `--name` → `displayName`; `--default` / `--no-default` → `isDefault` | — |
 | `cai data collection create` | `schema_type_create` | `<dataType>` → `name`; `--display` → `display`; `--field` → `field`; `--from-json` → `fromJson` (inline content); `--workflow` → `workflowId` | merged: The CLI command is sugar over schema create; no separate collection-create route exists. |
 | `cai data collections` | `data_collection_list` | `--env` → `env`; `--workflow` → `workflowId` | — |
@@ -63,6 +65,7 @@ This registry-derived map covers 162 CLI commands and 149 typed MCP tools. CLI e
 | `cai data query` | `data_record_query` | `--env` → `env`; `--limit` → `limit`; `--offset` → `offset`; `--query` → `query`; `--type` → `type`; `--workflow` → `workflowId` | — |
 | `cai data update` | `data_record_update` | `<recordId>` → `recordId`; `--env` → `env`; `--fields` → `fields`; `--type` → `type`; `--workflow` → `workflowId` | `env` required |
 | `cai deps` | `dependency_map` | `--workflow` → `workflowId` | — |
+| `docs` (CLI only) | — | — | dropped: Fetches documentation into a local terminal; hosted clients read guide_get or the docs site. |
 | `cai doctor` | `account_status` | — | hosted: Local runtime checks do not apply; useful account and version facts are in account_status. |
 | `cai events` | `event_list` | `--cursor` → `cursor`; `--limit` → `limit`; `--since` → `since`; `--type` → `type`; `--for-workflow` / `--workflow` → `workflowId` | — |
 | `cai exec flow` | `execution_flow_get` | `<flowExecutionId>` → `flowExecutionId`; `--workflow` → `workflowId` | — |
@@ -107,7 +110,7 @@ This registry-derived map covers 162 CLI commands and 149 typed MCP tools. CLI e
 | `cai node duplicate` | `node_duplicate` | `<nodeId>` → `nodeId`; `--workflow` → `workflowId` | — |
 | `cai node enable-prop` | `node_optional_prop_set` | `<nodeId>` → `nodeId`; `--prop` → `prop`; `--workflow` → `workflowId`; `enabled` (MCP-only) → `enabled` | merged: The explicit enabled boolean replaces the separate enabling command. |
 | `cai node get` | `node_get` | `<nodeId>` → `nodeId`; `--workflow` → `workflowId` | — |
-| `cai node only-when` | `node_only_when_set` | `<nodeId>` → `nodeId`; `--clear` → `clear`; `--js` / `--js-file` → `js` (inline content); `--workflow` → `workflowId` | — |
+| `cai node only-when` | `node_only_when_set` | `<nodeId>` → `nodeId`; `--clear` → `clear`; `--groups-json` → `groups`; `--js` / `--js-file` → `js` (inline content); `--workflow` → `workflowId` | — |
 | `cai node optional-props` | `node_optional_prop_list` | `<nodeId>` → `nodeId`; `--workflow` → `workflowId` | — |
 | `cai node options` | `node_prop_options` | `<nodeId>` → `nodeId`; `--for` → `for`; `--page` → `page`; `--prev-context` → `prevContext`; `--prop` → `prop`; `--query` → `query`; `--workflow` → `workflowId` | — |
 | `cai node props` | `node_prop_list` | `<nodeId>` → `nodeId`; `--workflow` → `workflowId` | — |
@@ -121,19 +124,19 @@ This registry-derived map covers 162 CLI commands and 149 typed MCP tools. CLI e
 | `cai run flow` | `run_flow` | `<flowId>` → `flowId`; `--confirm-live` → `confirmLive`; `--inputs` → `inputs`; `--target` → `target`; `--timeout` → `waitSeconds`; `--workflow` → `workflowId` | `waitSeconds` default 60, max 120 |
 | `cai run inputs` | `run_inputs` | `<nodeIdOrFlowId>` → `nodeIdOrFlowId`; `--flow` → `flow`; `--workflow` → `workflowId` | — |
 | `cai run node` | `run_node` | `<nodeId>` → `nodeId`; `--inputs` → `inputs`; `--timeout` → `waitSeconds`; `--workflow` → `workflowId` | `waitSeconds` default 60, max 120 |
-| `cai run workflow` | — | — | dropped: Excluded dead stub whose handler always throws NOT_IMPLEMENTED. |
+| `run workflow` (CLI only) | — | — | dropped: Excluded dead stub whose handler always throws NOT_IMPLEMENTED. |
 | `cai schema create` | `schema_type_create` | `<name>` → `name`; `--display` → `display`; `--field` → `field`; `--from-json` → `fromJson` (inline content); `--workflow` → `workflowId` | — |
 | `cai schema delete` | `schema_type_delete` | `<name>` → `name`; `--workflow` → `workflowId` | — |
 | `cai schema get` | `schema_type_get` | `<name>` → `name`; `--workflow` → `workflowId` | — |
 | `cai schema list` | `schema_type_list` | `--all` → `all`; `--workflow` → `workflowId` | — |
 | `cai schema resolve` | `schema_type_resolve` | `<typeId>` → `typeId`; `--workflow` → `workflowId` | — |
 | `cai schema update` | `schema_type_update` | `<name>` → `name`; `--display` → `display`; `--field` → `field`; `--from-json` → `fromJson` (inline content); `--workflow` → `workflowId` | — |
-| `cai signup` | — | — | dropped: The OAuth-authorized caller already has a provisioned account; root signup is local bootstrap. |
+| `signup` (CLI only) | — | — | dropped: The OAuth-authorized caller already has a provisioned account; root signup is local bootstrap. |
 | `cai signup email` | `account_claim_start` | `<address>` → `email` | hosted: Uses the OAuth grant durable email-claim adapter instead of local CLI credential replacement. |
 | `cai signup verify` | `account_claim_verify` | `<code>` → `code` | hosted: Uses the OAuth grant durable email verification adapter. |
-| `cai skills install` | — | — | dropped: Writes guidance into a caller local project, which the hosted server cannot access. |
+| `skills install` (CLI only) | — | — | dropped: Writes guidance into a caller local project, which the hosted server cannot access. |
 | `cai skills status` | `guide_get`<br>`guide_list` | `guide_get`: `name` (MCP-only) → `name`<br>`guide_list`: — | hosted: guide_list and guide_get serve the bundled server guidance without inspecting a local project. |
-| `cai skills update` | — | — | dropped: Updates guidance files in a caller local project. |
+| `skills update` (CLI only) | — | — | dropped: Updates guidance files in a caller local project. |
 | `cai trigger audit` | `trigger_audit` | `--workflow` → `workflowId` | — |
 | `cai trigger create` | `trigger_create` | `--connection` → `connection`; `--dynamic-props-id` → `dynamicPropsId`; `--event` → `event`; `--flow` → `flow`; `--node` → `node`; `--props` → `props`; `--source-basis` → `sourceBasis`; `--workflow` → `workflowId` | — |
 | `cai trigger delete` | `trigger_delete` | `<triggerId>` → `triggerId`; `--workflow` → `workflowId` | — |
@@ -149,9 +152,10 @@ This registry-derived map covers 162 CLI commands and 149 typed MCP tools. CLI e
 | `cai trigger select-event` | `trigger_event_select` | `--event` → `eventId`; `--node` → `triggerNodeId`; `--workflow` → `workflowId` | — |
 | `cai trigger set-enabled` | `trigger_set_enabled` | `<triggerId>` → `triggerId`; `--enable` / `--disable` → `enabled`; `--workflow` → `workflowId` | merged: The explicit enabled boolean combines the mutually exclusive enable and disable flags. |
 | `cai trigger test-events` | `trigger_test_events_set` | `<triggerId>` → `triggerId`; `--acknowledge-dual-run` → `acknowledgeDualRun`; `--allow` / `--disallow` → `allowed`; `--workflow` → `workflowId` | — |
-| `cai use` | — | — | dropped: Persists a local workflow pin; every typed workflow call carries an explicit id. |
+| `upgrade` (CLI only) | — | — | dropped: Prints the local CLI upgrade command and updates local skills; nothing to do on a hosted server. |
+| `use` (CLI only) | — | — | dropped: Persists a local workflow pin; every typed workflow call carries an explicit id. |
 | `cai workflow create` | `workflow_create` | `--name` → `name` | — |
-| `cai workflow delete` | `workflow_delete` | `<workflowId>` / `--workflow` → `workflowId` | — |
+| `cai workflow delete` | `workflow_delete` | `<workflowId>` → `workflowId` | CLI requires positional `<workflowId>`; `--workflow` does not replace it |
 | `cai workflow document` | `workflow_document_get` | `--state` → `stateId`; `--workflow` → `workflowId` | — |
 | `cai workflow duplicate` | `workflow_duplicate` | `<workflowId>` / `--workflow` → `workflowId` | — |
 | `cai workflow get` | `workflow_get` | `<workflowId>` / `--workflow` → `workflowId` | — |
@@ -169,8 +173,3 @@ This registry-derived map covers 162 CLI commands and 149 typed MCP tools. CLI e
 | `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`.

package/skills/controllerai-triggers/SKILL.md

@@ -1,28 +1,125 @@
 ---
 name: controllerai-triggers
-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.
+description: Discover, configure, create, capture, map, test, enable and debug Controller AI triggers: schedules, webhooks, email and app events. Use when an automation must start without a chat message, when a captured payload must become typed flow input, when replaying an event, or when asking why an automation did or did not start.
 ---
+<!-- generated from .claude/skills by cli/scripts/render-skills.mjs; edit the source -->
 
-# Run workflows from events
+# Triggers
 
-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.
+## Use this when
 
-## Build the event path
+- A workflow must start on a schedule, a webhook, an email or an app event.
+- A captured event must become the typed input of a flow, or a trigger's mapping is wrong.
+- A trigger must be paused, resumed, retired or replaced, or a run did not start.
 
-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.
+Flow inputs and mapping expressions belong to `controllerai-expressions`; reading a run belongs to `controllerai-runs`; publishing belongs to `controllerai-workflows`.
 
-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.
+## How it works
 
-## Diagnose by stage
+**One trigger, one flow.** A trigger binds a source (node slug plus exact event key, its connection and props) to exactly one flow, and its payload does not populate that flow by itself: the flow needs declared inputs, and the mapping props live on the trigger canvas's run-subflow node (`runSubflowNodeId`, wired automatically, never connected by hand), one per flow input, synthesized after the inputs exist. Creating the source, capturing and selecting a sample, mapping, testing on development, publishing and verifying live are separate steps.
 
-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.
+**Two rails, three switches.** Events are captured from the moment the source exists, and ordinary event execution runs the live release, so a trigger does not run live until the workflow is published; before that it can execute on development only through a replay or armed ambient dispatch. `set-enabled` (enable or disable) is the trigger's definition state and edits development only; the prior live trigger keeps running until an authorized publish. `test-events` (allow or disallow) sets a sticky permission bit for ambient development dispatch: real events then also execute the development canvas. `replay` targets one rail explicitly. The bit survives a disable (`devDispatchArmed` is enabled-and-allowed), and once the workflow is published with the trigger enabled on both rails and routable, every real event can execute on both rails (a schedule every interval), which is why publish refuses an armed trigger unless the user explicitly acknowledges dual dispatch.
 
-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.
+**Four IDs.** The canvas `triggerId` addresses get, rename, set-enabled, delete and test-events. The numeric `backendTriggerId` addresses captured events and replay. The `triggerNodeId` selects the typed sample. The captured `eventId` addresses event, select-event and replay. Copy them from the responses; they are never interchangeable.
 
-Commands: [reference](references/command-reference.md). Capture, replay and lifecycle details: [lifecycle](references/lifecycle.md).
+**Props are resolved, not guessed.** The props read returns a shape-correct `propsExample`, `readyForCreate`, and `unresolvedOptionProps`; unresolved required option props are omitted rather than filled with a plausible placeholder, and hidden props stay unset (they are provider reload plumbing). Option values are resolved by the options read with the same node, event, connection and configured values. The dynamic schema is identified by the response's `id`, passed back as `dynamicPropsId`; a selector that reloads props can mint a new one, so always pass the latest and keep every earlier configured value on each reload (registry events have no dynamic schema). Timer values are objects, `{"cron":{"cron":"0 9 * * *","timezone":"America/Chicago"}}` or `{"cron":{"intervalSeconds":900}}`, never a bare cron string.
+
+**A sample makes the type.** A captured event becomes the trigger node's output type only when it is selected; the mapping props are bound after that, from the re-read expression context, and a payload without a platform data type can stay untyped.
+
+## Rules
+
+1. **The start condition is the user's decision.** Create a source only with an explicit `--source-basis`: `explicit-in-request`, `user-answer`, or `inferred-from-existing-workflow` when preserving an existing source. The backend rejects an assumption; when the request does not say when the automation runs, ask one focused question first.
+2. **Copy the exact `nodeSlug` and `eventKey`** from the search result; never derive an event key from its display name, because keys are opaque and display names collide across providers.
+3. **Ask for the timezone** when the user says "at 9am" without one, and never infer a production cadence from a test sample, whose timing is a test artifact.
+4. **Repair in place.** Keep the trigger's canvas ID and source when fixing its mapping or readiness; replacing a trigger changes captured IDs and may change a webhook URL, so replace only when the source itself must change, then recapture every ID.
+5. **Delete a retired start; disable a paused one.** "Stop starting itself", "retire" and "no longer" mean delete: a disabled trigger still exists and can be re-enabled, so it is not retired. Never delete the owning flow to remove a trigger (that destroys the graph and its callers), and pass exactly one state flag.
+6. **Arm ambient dispatch only on the user's decision, and disarm when setup ends**, including a failed or abandoned setup. Capture needs no arming; arming executes a half-built development flow on real traffic, so explain that before adding the acknowledgement. Keeping both rails armed is an uncommon, explicit user choice, never a default, and routine tests use replay.
+7. **Never mix the flag families or the acknowledgements.** `--enable|--disable`, `--allow|--disallow`, `--target dev|live`; `--acknowledge-dual-run` only while arming, `--acknowledge-dual-dispatch` only while publishing an armed trigger, `--confirm-live` only for one live replay. Never add an acknowledgement on your own initiative.
+8. **Audit every trigger before a publish**, not only the one you touched; users forget starts left enabled or armed in other flows.
+9. **A captured event is not a run.** For create or mapping work, verify received inputs, outputs and effects on a development replay; an event with no execution and an execution with empty inputs are different faults. Read-only diagnosis, a deletion (verified through the list and status) and a user-declined test need no replay.
+10. **A draft-only request stops at development proof**, and a delete-only or disable-only task needs no replay.
+
+## Recipes
+
+### Discover and resolve
+
+```bash
+cai trigger search "<event intent>" --json
+cai trigger search --node <nodeSlug> --events-per-node 50 --json
+cai trigger props --node <nodeSlug> --event <eventKey> --connection <connectionId> --json
+cai trigger options --node <nodeSlug> --event <eventKey> --prop <propName> --connection <connectionId> --configured '<configuredPropsJson>' --dynamic-props-id <dynamicPropsId> --query "<option label>" --json
+cai trigger props --node <nodeSlug> --event <eventKey> --connection <connectionId> --configured '<configuredPropsJson>' --dynamic-props-id <dynamicPropsId> --json
+```
+
+Omit the connection for a source without auth. Copy the returned option `value`, not its `label`, into the configured props, then re-read the props until `readyForCreate` is true. Use `--page` with the returned context (`--prev-context`) when a search does not find the option. A missing connection is handled as in `controllerai-node-config`: `cai connection list --node <nodeSlug> --json`, then `cai connection connect <nodeSlug> --no-open`.
+
+### Create and map
+
+```bash
+cai trigger create --flow <targetFlowId> --node <nodeSlug> --event <eventKey> --source-basis <basis> --connection <connectionId> --props '<json>' --dynamic-props-id <dynamicPropsId> --json
+cai trigger get <triggerId> --json
+```
+
+Capture every returned ID (`triggerId`, `backendTriggerId`, `triggerNodeId`, `runSubflowNodeId`) plus the `webhookUrl` or `emailAddress` when the source has one, and follow `nextSteps` in order: declare the flow inputs, capture and select a sample, then bind one mapping prop per input on the run-subflow node from its re-read expression context. Read-back is `get`; there is no describe command.
+
+### Capture and select a sample
+
+```bash
+cai trigger events --trigger <backendTriggerId> --json
+cai trigger event <eventId> --json
+cai trigger select-event --node <triggerNodeId> --event <eventId> --json
+```
+
+A representative event has to reach the source: through the provider, the returned webhook URL or email address; never invent an endpoint. Inspect the payload before selecting it and re-read the run-subflow node's expression context after selecting.
+
+### Arm ambient development dispatch (only on request)
+
+```bash
+cai trigger test-events <triggerId> --allow --acknowledge-dual-run --json
+cai trigger test-events <triggerId> --disallow --json
+```
+
+Arming makes every real event also execute the development canvas while it is half built; use it only when the user wants that after hearing it, and disarm at the end of setup.
+
+### Pause, resume, retire
+
+```bash
+cai trigger set-enabled <triggerId> --enable --json
+cai trigger set-enabled <triggerId> --disable --json
+cai trigger delete <triggerId> --json
+```
+
+### Test, audit, publish
+
+```bash
+cai run flow <targetFlowId> --inputs <values.json> --json
+cai trigger replay --trigger <backendTriggerId> --event <eventId> --target dev --json
+cai exec tree <workflowExecutionId> --json
+cai trigger audit --json
+cai trigger list --json
+```
+
+Run the target flow directly first, then replay one captured event through the development trigger path; a development replay never dispatches live but still calls real providers and spends usage. `--payload` replays a custom raw payload instead of `--event`. The audit reports coverage, armed development dispatch and double-run risk; the list and get reads show `devCanvasEnabled` at the top level and `deployment.liveCanvasEnabled`, `deployment.inLiveVersion`, `deployment.devDispatchArmed` and `deployment.dualDispatchLive` (live fields are null when no live canvas exists yet: never published, or this trigger added after the last publish). Publish through `controllerai-workflows` only for an authorized live change. A publish refused because a trigger is still armed is the designed backstop: disarm and republish; publishing armed needs the user's informed choice after hearing about double runs and double billing, and only then `cai workflow publish --acknowledge-dual-dispatch --json`.
+
+### Verify live
+
+```bash
+cai trigger replay --trigger <backendTriggerId> --event <eventId> --target live --confirm-live --json
+cai exec tree <workflowExecutionId> --json
+```
+
+A live replay executes the published workflow, calls live third-party actions and spends usage; it needs its own authorization and is optional.
+
+## Verify
+
+```bash
+cai trigger get <triggerId> --json
+cai trigger list --json
+cai workflow status --json
+```
+
+The trigger, source, target flow, connection, props and mapping match the request; `devCanvasEnabled` and `deployment.liveCanvasEnabled` / `deployment.inLiveVersion` match the requested rail state; `deployment.devDispatchArmed` is false unless the user chose dual dispatch; for create or mapping work, the development replay's execution tree shows the flow receiving the mapped inputs and producing the expected effect; for a deletion, the list no longer shows the trigger and the status shows what remains live. Read [references/lifecycle.md](references/lifecycle.md) for the state sequence, the ID table and the missing-run diagnosis.
+
+## Report
+
+The trigger and its source, the IDs the user needs, whether it is enabled on development and on live, whether ambient dispatch is armed and why, what the development replay proved, and what remains: an unpublished change, a live verification not yet run, or a source decision still open.

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

@@ -1,71 +1,59 @@
+<!-- generated from .claude/skills by cli/scripts/render-skills.mjs; edit the source -->
 # Trigger lifecycle
 
 ## State sequence
 
 ```text
-source decision
-  -> exact node/event discovery
+source decision (basis)
+  -> exact node and event
   -> connection
-  -> dynamic prop resolution
-  -> create source + canvas
-  -> map payload into target flow
-  -> capture representative event
-  -> select typed sample
-  -> test target flow on development
-  -> replay captured event against development
-  -> publish workflow
+  -> prop and option resolution (latest dynamicPropsId)
+  -> create source and canvas trigger (triggerId, backendTriggerId, triggerNodeId, runSubflowNodeId)
+  -> declare the flow inputs
+  -> capture a representative event, select it
+  -> bind one mapping prop per input on the run-subflow node
+  -> run the target flow on development
+  -> replay the captured event on development
+  -> audit every trigger, then authorized publish
   -> optional live replay
 ```
 
-Skipping capture/sample selection commonly leaves downstream output untyped. Skipping mapping commonly produces a green trigger execution with empty flow inputs.
+Skipping capture or selection leaves the trigger output untyped. Skipping the mapping produces a green trigger execution with empty flow inputs. Leaving ambient dispatch allowed can produce double runs after publish.
 
 ## IDs
 
 | ID | Used by |
 | --- | --- |
-| Canvas `triggerId` | `trigger get`, `rename`, `set-enabled`, `delete`, `test-events` |
-| Numeric `backendTriggerId` | `trigger events`, `replay` |
-| `triggerNodeId` | `trigger select-event` |
-| Captured `eventId` | `trigger event`, `select-event`, `replay --event` |
+| Canvas `triggerId` | get, rename, set-enabled, delete, test-events |
+| Numeric `backendTriggerId` | captured events, replay (`--trigger`) |
+| `triggerNodeId` | select-event |
+| `runSubflowNodeId` | the mapping props, one per flow input |
+| Captured `eventId` | event read, select-event, replay |
 
-Always copy these from the transport output.
+Copy them from the responses. A replaced trigger has new IDs and possibly a new webhook URL.
 
-Development replay is the normal pre-publish check:
+## Switches and acknowledgements
 
-```bash
-cai trigger replay --trigger <backendTriggerId> --event <eventId> --target dev --json
-```
-
-Use `--target live --confirm-live` only for an intentional post-publish live verification.
-
-## Enable/disable
-
-`cai trigger set-enabled <triggerId> --enable|--disable` sets the requested state idempotently. Pass exactly one state flag.
+| Switch | Flags | Meaning |
+| --- | --- | --- |
+| Definition state | `set-enabled --enable` / `--disable` | Whether the trigger starts its flow; development edit until published |
+| Ambient development dispatch | `test-events --allow --acknowledge-dual-run` / `--disallow` | Real events also execute the development canvas; sticky permission bit, survives disable |
+| Replay rail | `replay --target dev` / `--target live --confirm-live` | Which version one captured event executes |
+| Publish while armed | `workflow publish --acknowledge-dual-dispatch` | User's informed acceptance of double runs and double billing |
 
-MCP: call `trigger_set_enabled` with `enabled: true` or `enabled: false`.
-
-## Lifecycle flag families
-
-```bash
-cai trigger set-enabled <triggerId> --enable|--disable --json
-cai trigger test-events <triggerId> --allow [--acknowledge-dual-run] --json
-cai trigger test-events <triggerId> --disallow --json
-cai trigger replay --trigger <backendTriggerId> --target dev --json
-cai trigger replay --trigger <backendTriggerId> --target live --confirm-live --json
-cai workflow publish --acknowledge-dual-dispatch --json
-```
+Each acknowledgement belongs to exactly one operation. Arming, publishing armed and live replay are three separate user decisions.
 
-Use enable/disable for the trigger definition, allow/disallow for ambient development capture, and target for replay rail. `--acknowledge-dual-run` applies only while arming. `--acknowledge-dual-dispatch` applies only when publishing an armed trigger. `--confirm-live` applies only to one Live replay. These acknowledgements are not interchangeable.
+## Lifecycle fields
 
-The allow flag is sticky even when the trigger is disabled. Always disallow after capture or an abandoned setup so later re-enablement cannot silently rearm development dispatch.
+The list and get reads report `devCanvasEnabled` at the top level and, under `deployment`, `liveCanvasEnabled` (null when no live canvas exists: never published, or this trigger was added after the last publish), `inLiveVersion`, `devDispatchArmed` (enabled and allowed) and `dualDispatchLive`; get adds captured event counts and issues. The audit summarizes coverage and double-run risk before a publish and names the disarm step for each armed trigger.
 
-## Debugging a missing run
+## Missing-run diagnosis
 
-1. `cai trigger list --json`: enabled, correct flow, recoverable backend ID.
-2. `cai workflow status --json`: published/active live state.
-3. `cai trigger events --trigger <backendId>`: did ingestion capture the event?
-4. `cai trigger event <eventId>`: does payload match the selected sample?
-5. `cai exec list --json`: did execution start?
-6. `cai exec tree <executionId> --json`: where did it stop?
+1. The trigger list: enabled, correct flow, recoverable backend ID?
+2. The workflow status: published, and is the live version active?
+3. The captured events for the backend trigger ID: did ingestion capture the event?
+4. The event read: does the payload match the selected sample?
+5. The execution list: did an execution start?
+6. The execution tree: where did it stop?
 
-No captured event means source/delivery/configuration. Captured event with no execution means enable/live/ingestion routing. An execution with empty inputs means mapping.
+No captured event points to the source, delivery or configuration. A captured event with no execution points to enablement, publish state or ingestion routing. An execution with empty inputs points to the mapping. Development works but live does not: compare the enabled state and the published configuration, and remember that live runs read the live data store.

package/skills/controllerai-workflows/SKILL.md

@@ -1,46 +1,126 @@
 ---
 name: controllerai-workflows
-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.
+description: Build, inspect, edit, recover, and publish Controller AI workflows and their flows. Use when a user asks to create or change an automation, a flow, or a workflow release, and for the lifecycle rules every other workflow skill relies on.
 ---
+<!-- generated from .claude/skills by cli/scripts/render-skills.mjs; edit the source -->
 
-# Controller AI workflows
+# Workflows
 
-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.
+## Use this when
 
-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.
+- Creating a workflow, adding or repairing flows, orienting inside an existing graph, validating, checkpointing, restoring, publishing, or deleting.
+- Another skill needs the shared lifecycle rules: which rail an edit lands on, how contracts and IDs behave, what validation and publishing require.
 
-## Start with the contract
+Load the narrow skill when the work reaches it: nodes, connections, props and wiring → `controllerai-node-config`; computed values and conditions → `controllerai-expressions`; Router, If/Else, loops, joins, subflows → `controllerai-flow-control`; runs and debugging → `controllerai-runs`; schedules, webhooks, app events → `controllerai-triggers`; schemas and records → `controllerai-data`; Ask AI and agent nodes → `controllerai-ai-nodes`; user-facing agents → `controllerai-agents`.
 
-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.
+## How it works
 
-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.
+A **workflow** groups flows, custom schemas, data collections and triggers, and its flows share one data store per environment. A **flow** is one canvas and one callable contract: typed inputs, connected nodes, typed outputs. A Return node maps values into the declared outputs; declaring an output does not fill it. Workflow, flow, node, input and output IDs are distinct identities; never swap one for another.
 
-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.
+Every graph edit lands on the **development** version. Publishing creates the **live** release; a live agent that uses the workflow as a tool follows its latest live release without an agent publish, while the owner's Test conversations run the development version. Publishing never copies development records into the live store, and every environment keeps its own data.
 
-## Assemble and test
+Every save is a **state**. History lists states in groups and gives candidate state IDs; a restore rolls the definition back to one state and leaves records and external effects untouched. How far back history is listed and how far back a state can be restored are two separate plan limits, so a listed state is not always restorable.
 
-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.
+Deleting a workflow tears down its deployed triggers and soft-deletes it. It is refused while any draft or live agent depends on the workflow, and nothing undeletes. The dependency map shows a workflow's agent and workflow callers and the connections it uses. Deleting a flow removes its graph, its contract and the triggers targeting it, and breaks every caller bound to it.
 
-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.
+The account event feed records only supported events: connections created, workflows created, updated, deleted, published and run, agents created and published, members added. Settings changes, member removals and label edits are not in it, and a past change that is not recorded cannot be reconstructed from names or current state.
 
-## Files and agents
+## Rules
 
-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.
+1. **Before changing an existing workflow, read its outline and the affected flow**, then repair those IDs rather than creating a replacement workflow or flow. A repair that recreates loses history, triggers and callers.
+2. **Rename contracts in place.** Deleting and recreating an input or output breaks every expression, subflow mapping and agent tool bound to it. After a rename or deletion, re-read the flow and repair the affected dependents before validating or running; a stored input-ID binding survives a rename, so the readback may show nothing to repair.
+3. **"Store, save, log, record" without a named destination means a custom data type plus a create-record node.** A flow output alone persists nothing. When the user names a destination (a sheet, a CRM, an app, a file), write there through that integration; add a platform record only if they also want a copy kept here.
+4. **Validate after structural edits and before publishing.** Fix every listed prop, wire, expression, type, subflow, branch and trigger error, or report each one with what it breaks. Publish refuses errors; `--acknowledge-validation-errors` is for issues the user has seen and accepted, never a shortcut. If the user forbids a repair, report and stop.
+5. **Validation counts are status.** Do not write them into unrelated workflow properties unless the user asks for exactly that.
+6. **Deleting a workflow needs the user's explicit intent.** A confirmation flag is not authorization. Check dependencies first; detach draft tools with `cai agent remove-tool <agentId> --tool <toolId>`, and treat a live agent's republish as its own decision.
+7. **Layout once per changed flow.** After adds, deletes or rewires, run the flow layout as the last structural step; placement at add time only avoids overlap.
+8. **Never weaken the request to make a test pass.** Report an unsupported capability or ask the product question. Keep deliberately armed triggers and advisory-only nodes the user chose.
+9. **A conflict means re-read, then reapply the intent to the current graph.** Never replay a stale document or old IDs; the retried write uses the IDs the current state holds.
+10. **Say "not recorded" and change nothing** when asked to reconstruct history the feed does not hold.
 
-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.
+## Recipes
 
-## Release and recovery
+### Establish context
 
-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.
+```bash
+cai auth status --json
+cai workflow list --json
+cai use <workflowId>
+cai workflow status --json
+```
 
-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.
+A create or `cai use` may not win the effective pin: read `selected`, `effectiveWorkflowId` and `pinSource`, and resolve as `pinSource` says (drop the command flag, use `cai use <id>`, or clear an inherited `CAI_WORKFLOW`). `cai config reset` clears stored pins only; `cai doctor` confirms the effective pin and development head.
 
-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.
+### Create
 
-Detailed CLI/MCP sequences and lifecycle operations: [command reference](references/command-reference.md). Multi-domain command lookup: [command map](references/command-map.md).
+```bash
+cai workflow create --name "<clear outcome-oriented name>" --json
+```
+
+Create with the final name. Read `flowCount` and `nextStep`: with 0 flows, create the first flow with `cai flow create --name "<name>" --json`; with one empty default flow, rename it and build in it; when either field is missing, list the flows before deciding. Add flows only for genuinely separate canvases, and stop at an empty workflow when that is what was asked. A missing projected field is not a failed create: read the full result or the exact inventory before retrying.
+
+### Orient
+
+```bash
+cai workflow outline --json
+cai workflow state --flow <flowId> --json
+cai flow get <flowId> --json
+```
+
+The outline shows flows, contracts, graph dependencies, triggers and data inventory in one call. State is a bounded projection; pass the flow ID for node and edge identities. The flow read exposes props and expressions.
+
+### Build
+
+1. Translate the request into inputs, steps, outputs, trigger, integrations, failure behavior and publish intent.
+2. Declare flow inputs and outputs before nodes whose props derive from them. Pass a human display label; use the current binding from `flow get` (`jsBinding`) or the outline (`binding`), never the diagnostic `legacyBinding`.
+3. Add nodes in execution order and name each after the data it produces; downstream bindings are seeded from that name when wired.
+4. Lay out each changed flow, validate, test on development, re-read status. Publish only when the user asked for a live change or authorized deployment.
+
+### Publish
+
+```bash
+cai workflow status --json
+cai trigger list --json
+cai workflow publish --json
+```
+
+Read status and every trigger first: publishing activates enabled triggers on the live release. The publish refuses validation errors and may return an approval that the user must grant.
+
+When the publish returns an approval, the CLI polls it; if polling is interrupted, `cai approval resume <approvalId>` continues the same intent instead of publishing again.
+
+### Checkpoint and recover
+
+```bash
+cai workflow save --name "<checkpoint>" --json
+cai workflow history --json
+cai workflow history --group <groupId> --json
+cai workflow restore --state <stateId> --json
+```
+
+Save before a risky rewrite. Expand a group to find the state ID; restore by state, not by group.
+
+### Delete
+
+```bash
+cai deps --json
+cai workflow delete <workflowId> --yes
+```
+`cai deps --account` maps the whole account. The `--force` flag is deprecated and inert.
+
+## Verify
+
+```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
+```
+
+Evidence that a build works: validation reports zero errors, or each remaining error is reported with its effect; required connections and props are complete; expressions resolve to the expected values, with intentional empties explained; the expected branch and error paths ran where practical; the flow outputs contain the promised values; the development or live state matches the request; the final outline matches the request, with only your own abandoned scratch objects removed. A checkpoint or a rename needs its readback, not a run. Once the requested blockers are fixed and each changed path ran once, stop; warnings alone do not justify a redesign.
+
+## Report
+
+What was built, what ran and what it returned, whether it is published, and any connection or product decision still pending. Share returned product links only; never guess one.
+
+Read [references/command-map.md](references/command-map.md) for the command families by domain when a task spans several areas.