@controllerai/cli 0.2.0

package/skills/controllerai-node-config/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: controllerai-node-config
+description: Discover, initialize, configure, connect, and verify Controller AI workflow nodes. Use when adding an action, selecting an integration component, binding an account, setting node props, enabling optional or dynamic props, choosing provider-backed options, wiring nodes, or fixing a node that is not ready to run.
+---
+
+# 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 node find "<capability>" --json
+cai node component --node <nodeSlug> --key <nodeKey> --json
+```
+
+Use the returned `nodeSlug` and full `nodeKey`. Do not infer a component key from its display name. If discovery is broad, narrow it with:
+
+```bash
+cai node search "<integration>" --actions --json
+cai node components "<action>" --node <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 `connectionId`.
+- Several: use an explicit user preference; otherwise ask which account.
+- None: run `cai connection connect <nodeSlug> --wait`, share the printed link with the user, and the command returns automatically the moment they finish connecting (structured timeout otherwise — the link stays valid).
+
+Never substitute a connection from a similar slug.
+
+### 3. Initialize once
+
+```bash
+cai node init \
+  --flow <flowId> \
+  --node <nodeSlug> \
+  --key <nodeKey> \
+  --name "<data this node produces>" \
+  --connection <connectionId> \
+  --after <upstreamNodeId> \
+  --json
+```
+
+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.
+
+### 4. Follow readiness, not guesses
+
+```bash
+cai node status <nodeId> --json
+cai node props <nodeId> --json
+```
+
+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
+
+Re-run `node props` after every reload selector or connection change. Dynamic props can appear, disappear, or reset.
+
+### 5. Set props safely
+
+Static value:
+
+```bash
+cai node set <nodeId> --prop <exactName> --value '<literal-or-json>' --json
+```
+
+Optional prop:
+
+```bash
+cai node optional-props <nodeId> --json
+cai node enable-prop <nodeId> --prop <exactName> --json
+cai node props <nodeId> --json
+```
+
+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
+```
+
+For a remote option, preserve both fields from the same returned option. The label is not cosmetic: the CLI uses it to search providers that do not index opaque IDs, then verifies that the returned value still matches before writing. For a multi-select, pass a JSON array of returned values and one `--label` argument per value, in the same order. The CLI supplies the persisted label shape, chooses the correct expression storage channel, and verifies read-back. If metadata or options cannot be fetched, it fails closed; do not bypass that with a raw API call.
+
+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
+```
+
+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.
+
+Read [references/prop-and-readiness.md](references/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`.
+- Enable catalog-only optional props before writing them.
+- 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. Never fabricate an output schema.

package/skills/controllerai-node-config/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Controller AI Node Configuration"
+  short_description: "Discover, initialize, and configure workflow nodes"
+  default_prompt: "Configure the required Controller AI nodes using live schemas and verify every write."

package/skills/controllerai-node-config/references/prop-and-readiness.md

@@ -0,0 +1,72 @@
+# Prop and readiness reference
+
+## What `cai node status` means
+
+The JSON response reports:
+
+- `missingConnection`: an authenticated component has no account bound.
+- `missingRequiredProps`: materialized required props without a value.
+- `pendingReloadProps`: selectors that must be set before dependent props are trustworthy.
+- `outputTypeStatus`: `concrete`, `unresolved`, or `none`. Connection-port wrappers never count as a concrete process output.
+- `readyForExpressions`: connection and required/reload props are complete. The source still must be wired before its binding appears in expression context.
+- `readyForRun`: connection and required/reload props are complete; running may be the step that discovers a concrete output type.
+- `readyForDownstreamExpressions`: the node is runnable and its actual process output type is concrete enough for downstream field bindings.
+- `next`: the CLI's exact next diagnostic command.
+
+Follow `next`, then read status again. Do not treat `readyForRun` as proof that downstream fields are typed; require `readyForDownstreamExpressions` for that.
+
+For an existing node with a missing connection, a browser handoff alone is not enough. After the user connects, list the compatible accounts, bind the chosen ID, and re-read status:
+
+```bash
+cai connection connect <nodeSlug>
+cai connection list --node <nodeSlug> --json
+cai node set-connection <nodeId> --connection <connectionId> --json
+cai node status <nodeId> --json
+```
+
+## Prop channels
+
+Use `cai node set`; it selects the persisted shape from live metadata.
+
+| Intent | Command input | Persisted channel |
+| --- | --- | --- |
+| Static text, JSON text, scalar, object, or list | `--value` | `value` |
+| Dynamic text, JSON text, or custom data | `--js` | `valueJs` |
+| Dynamic non-text prop with expression mode | `--js` | `expressionValueJs` |
+
+Do not force a channel with internal fields. `cai node set` and `cai expr set` compile first and verify the actual channel after writing.
+
+## Option-backed props
+
+Static options are declared in component/prop metadata. Remote options require current connection and earlier prop values.
+
+```bash
+cai node options <nodeId> --prop <name> --query "<specific search>" --json
+cai node set <nodeId> --prop <name> --value '<option.value>' --label '<option.label>' --json
+```
+
+Pass the value and label from the same live option. Remote providers often search labels rather than opaque values, so omitting `--label` can make a valid copied ID impossible to re-verify. For multi-select, pass a JSON array of returned values plus one `--label` argument per value in matching order. The CLI constructs the required array of `{value,label}` records for read-back/UI compatibility.
+
+## Reload selectors
+
+A prop with `reloadProps:true` changes the downstream prop schema. Set it statically, wait for the mutation, and immediately re-read:
+
+```bash
+cai node set <nodeId> --prop <selector> --value '<value>' --json
+cai node props <nodeId> --json
+cai node status <nodeId> --json
+```
+
+Do not batch dependent values into stale metadata. A provider, model family, spreadsheet, database, or action selector commonly triggers this behavior.
+
+## Output type
+
+An unresolved output blocks trustworthy downstream field expressions. Resolve it by one of:
+
+- Set the component's supported output/data type selector.
+- Run the configured node with representative inputs.
+- Probe an action with `cai run discover` only when its real-world side effects are acceptable.
+
+After the run, read `cai node status` and `cai expr context` again. Do not infer fields from an example response alone if the platform did not adopt a concrete type.
+
+`cai run node` and `cai run flow` pass the exact completed node-execution ID back to the backend. The backend verifies ownership, workflow, node, component snapshot, and terminal status, then derives the persisted output shape; callers never supply the type name. Adoption updates only that non-static node, so separate instances of generic components such as HTTP can learn different schemas. Inspect `outputTypeAdoption`/`outputTypeAdoptions` in the run result. If it reports `no_observed_output`, use a representative input that returns data and rerun. If it reports `error`, stop and surface that error rather than inventing a schema.

package/skills/controllerai-runs/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: controllerai-runs
+description: Run and debug Controller AI nodes and flows on the development 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.
+---
+
+# Controller AI runs
+
+Think "dev run", not "test". The development version is a real environment with its own data store — like an app's dev environment — and there is NO simulation mode: a dev run executes real integration actions (messages send, records change, provider usage is spent). Dev 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 the job is never "avoid running"; it is to mitigate risk before running.
+
+## Consequential actions: mitigate with the user, don't refuse
+
+Before dev-running an action with external consequences (send, reject, delete, charge), tell the user plainly what will really happen and ask for a safe target:
+
+- 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?"
+
+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 —
+
+```bash
+cai node declare-output <nodeId> --sample-file shape.json
+```
+
+— 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.
+
+## First live run is part of development
+
+Publishing and running live is a legitimate, supervised development step — not a process failure. 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. The first live run under supervision is how remaining problems surface.
+
+## Prepare exact run inputs
+
+```bash
+cai run inputs <nodeId> --json
+cai run inputs <flowId> --flow --json
+```
+
+Use returned opaque input IDs. A compact input file can be a flat map:
+
+```json
+{
+  "<inputId>": "representative value"
+}
+```
+
+Do not key test values by a guessed display name.
+
+## 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
+```
+
+`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. Capture `workflowExecutionId` and `nodeExecutionId` from the result.
+
+For every node test, inspect:
+
+- `status` and `errorMessage`
+- `skipReason`
+- `runScope`, especially `upstreamNodesExecuted` and `endToEndValidationRequired`
+- `resolvedConfigs`
+- `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> --json
+cai exec get <workflowExecutionId> --json
+cai exec flow <flowExecutionId> --json
+cai exec node <nodeExecutionId> --json
+cai exec ports <nodeExecutionId> --json
+```
+
+Use the tree to locate the first unexpected status. Use ports to compare actual inputs, resolved configuration, and outputs at that node. 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
+```
+
+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. 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
+
+- 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-runs/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Controller AI Runs"
+  short_description: "Run, test, and debug workflow executions"
+  default_prompt: "Run and debug this Controller AI workflow using execution evidence and resolved configuration values."

package/skills/controllerai-runs/references/debugging.md

@@ -0,0 +1,53 @@
+# Execution debugging
+
+Use this order; it avoids changing a downstream node when the defect is upstream.
+
+## 1. Confirm rail and graph
+
+```bash
+cai workflow status --json
+cai flow get <flowId> --json
+```
+
+Manual node/flow tests use development. Trigger replay defaults to the development rail, but both development and live replay can call real providers and create external effects. Live replay additionally requires `--target live --confirm-live`.
+
+## 2. Find the first divergence
+
+```bash
+cai exec tree <workflowExecutionId> --json
+```
+
+Classify each node as completed, failed, skipped intentionally, skipped unexpectedly, or absent. The first divergence is usually the cause; later failures are often consequences.
+
+## 3. Inspect the node boundary
+
+```bash
+cai exec ports <nodeExecutionId> --json
+```
+
+Check:
+
+1. Inputs: did the expected upstream value arrive?
+2. Configs: did each expression resolve, and to the correct type/value?
+3. Outputs: did the component return the promised shape?
+4. Status/error: did the provider or engine reject the call?
+
+## 4. Fix by category
+
+| Evidence | Likely surface |
+| --- | --- |
+| Missing/wrong input | Wiring, branch connection, or test input ID |
+| Null dynamic config | Expression binding, field path, or missing source value |
+| Invalid option/account | Node connection or dependency-ordered props |
+| Provider error | Integration configuration, credentials, quota, or payload |
+| Green node, wrong output | Component choice, output contract, or prompt |
+| Unexpected skip | only-when, branch condition/order, or upstream failure |
+
+Re-read metadata/context before editing. Then rerun the smallest failed scope and finally the full flow.
+
+## 5. Avoid false confidence
+
+- A compile pass does not prove runtime data exists.
+- A node pass does not prove downstream mapping: `run node` does not execute wired upstream nodes. Require `run flow` for any `inputs.<name>` expression.
+- A dev pass does not prove live data or live release state.
+- A top-level completed status does not prove every intended branch ran.

package/skills/controllerai-start/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: controllerai-start
+description: Connect, orient, and route work across Controller AI agents and no-code automations. Use when starting a Controller AI coding-agent session, after `cai connect`, or when deciding whether an outcome should be a ready integration action, a workflow, an agent, or a combination.
+---
+
+# Start with Controller AI
+
+Use the installed `cai` CLI as the supported platform interface. Do not call Controller AI REST or MCP routes directly.
+
+## Confirm the setup
+
+Run:
+
+```bash
+cai doctor
+```
+
+If authentication is missing, run `cai connect`. If `cai doctor` reports missing, stale, or damaged managed skills, run `cai skills update`, then run `cai doctor` again. Skill updates are setup maintenance, not a step to repeat during every build. Never ask the user to paste a password, provider token, or Controller AI credential into chat.
+
+## 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.
+
+## Keep rails explicit
+
+- Agent Test mode uses the owner's mutable draft, current workflow development heads, current draft knowledge, and live runtime files overlaid by development/test runtime files. Live mode uses the latest published agent version, each workflow's latest live release, frozen published knowledge, and live runtime files only.
+- Agent draft edits require another agent publish to reach Live. Publishing restamps existing live conversations; shared users always receive the latest published version and never the draft.
+- Workflow publishes and direct-action connection/authorization grants are live bindings: a rebind can redirect Live, while revocation or detachment can block Live without another agent publish.
+- Local coding-agent subscriptions cover builder reasoning, not Controller AI hosted-agent runtime usage.
+- 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.
+
+At completion, report what was created, what is still draft or live, the evidence actually observed, and any connection or user decision still required.

package/skills/controllerai-start/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Controller AI Start"
+  short_description: "Route agent and automation building safely"
+  default_prompt: "Use $controllerai-start to connect Controller AI and help me build an agent or automation."

package/skills/controllerai-triggers/SKILL.md

@@ -0,0 +1,174 @@
+---
+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.
+---
+
+# 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.
+
+## 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>
+```
+
+## 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 CLI intentionally omits unresolved required option props rather than emitting a plausible placeholder.
+
+For each name in `unresolvedOptionProps`, run the complete option command printed by the CLI, or equivalently:
+
+```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 CLI prints this complete 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 discard timezone by passing a bare cron string.
+
+## 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/toggle/delete. `backendTriggerId` is numeric and used for captured events and replay. They are not interchangeable.
+
+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.
+
+## 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
+```
+
+The armed state is sticky: nothing disarms it for you, and dev dispatch and live dispatch are independent gates. A trigger that is armed while the workflow is also live runs ONE real event TWICE — both executions real, both billed. The starkest case is a schedule trigger: armed + enabled + published, the cron fires BOTH dev and live at every interval, forever, with no external event involved — until someone edits and republishes.
+
+Keeping a trigger armed alongside live on purpose (side-by-side comparison on real events) is legitimate but uncommon; it is a user decision, never a default.
+
+## Verify development, then publish
+
+Use `cai run flow` for direct development verification, then replay one captured event through the development trigger path:
+
+```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.
+
+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.

package/skills/controllerai-triggers/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Controller AI Triggers"
+  short_description: "Create and debug workflow triggers"
+  default_prompt: "Create or repair the Controller AI trigger, test the downstream flow, and explain the live publish boundary."

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

@@ -0,0 +1,54 @@
+# Trigger lifecycle
+
+## State sequence
+
+```text
+source decision
+  -> exact node/event discovery
+  -> 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
+  -> optional live replay
+```
+
+Skipping capture/sample selection commonly leaves downstream output untyped. Skipping mapping commonly produces a green trigger execution with empty flow inputs.
+
+## IDs
+
+| ID | Used by |
+| --- | --- |
+| Canvas `triggerId` | `trigger get`, `rename`, `toggle`, `delete` |
+| Numeric `backendTriggerId` | `trigger events`, `replay` |
+| `triggerNodeId` | `trigger select-event` |
+| Captured `eventId` | `trigger event`, `select-event`, `replay --event` |
+
+Always copy these from CLI output.
+
+Development replay is the normal pre-publish check:
+
+```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 toggle <triggerId>` flips state; it is not a setter. Read `cai trigger list --json` before and after. Do not toggle blindly.
+
+## Debugging a missing run
+
+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?
+
+No captured event means source/delivery/configuration. Captured event with no execution means enable/live/ingestion routing. An execution with empty inputs means mapping.