@controllerai/cli 0.2.15 → 0.2.17

package/skills/controllerai-data/SKILL.md

@@ -12,8 +12,19 @@ Controller AI has two separate concerns:
 - A `custom.*` schema defines fields and makes a collection available.
 - Development and live record stores hold separate rows. Publishing graph/configuration does not copy records.
 
+## Rules that break tasks when skipped
+
+- Persisting data requires both a schema and a create-record node; see A type vs a stored record.
+- `schema update --field` replaces the full field list; see Define a schema deliberately.
+- Relabel a stable key instead of recreating it; see How schema changes affect stored records.
+- Query results and writes use different field keys; see Respect field-key asymmetry.
+- Read and write the requested dev or live store; see Work on the correct rail.
+- Remove only scratch schemas created for abandoned attempts; see Before you finish.
+
 ## A type vs a stored record
 
+When a request says store, save, log, or record with no external destination, create the schema and configure a create-record node. A flow output alone is not persistence.
+
 `custom.customer` and `dataRecord.custom.customer` are different things, and the difference carries through everything:
 
 - `custom.customer` is the TYPE — the shape, like a TypeScript interface. A value of this type is just data in that shape.
@@ -69,7 +80,13 @@ Schema changes never hard-delete data. There is no delete path for records in sc
 
 The truly destructive operations are record-level only: `data delete`, `data delete-many`, and overwriting edits. Those have no undo — treat them with explicit user intent; everything schema-shaped is safely reversible.
 
-One rename trap: renaming a type key is create-new + deactivate-old — all existing records stay stranded under the OLD key's collection, invisible. Migrate records explicitly (export/import) or rename back to recover.
+Relabel a type without changing its stable key:
+
+```bash
+cai schema update custom.customer --display "Customers" --json
+```
+
+Changing `custom.customer` itself is a key migration, not a relabel. It creates a new type and deactivates the old collection, stranding its records under the old key. Migrate records explicitly by export/import or restore the old key.
 
 ## Respect field-key asymmetry
 
@@ -150,3 +167,18 @@ The live schema must exist through a publish before copying. Treat copy-to-live
 `workflowData("custom.customer")` requires an active collection on the executing rail. Read `controllerai-expressions` for filtering. Test stateful behavior against development, then independently verify required live seed data.
 
 Read [references/data-rails.md](references/data-rails.md) before schema rewrites, deletion, bulk deletion, import, or copy-to-live.
+
+## Before you finish
+
+```bash
+cai schema get custom.<type> --json
+cai data collections --env <dev|live> --json
+cai data query --type custom.<type> --env <dev|live> --json
+cai workflow outline --json
+cai workflow validate --json
+```
+
+- Schema read-back must show the intended stable key, display, complete field list, and field types.
+- The same-rail query must prove the expected persisted records; node output alone is insufficient.
+- Compare schema and workflow inventory with the request. Remove only schemas created during abandoned attempts, never pre-existing user objects.
+- For a live request, verify the live collection after publish or copy and report the affected record count.

package/skills/controllerai-expressions/SKILL.md

@@ -9,20 +9,25 @@ The `cai ...` examples are canonical grammar. Use the transport selected in `con
 
 Controller AI uses a restricted JavaScript-like authoring language that is compiled into the workflow engine's expression AST. It is not general JavaScript. Discover the real scope and compile before every write.
 
+## Rules that break tasks when skipped
+
+- Wire first; refresh context after structural changes. See Required write loop.
+- `--value` is static; dynamic values use `--js`. See Typed values and templates.
+- Copy current bindings, not labels or stale names. See Read the destination's exact scope.
+- Never use raw ASTs, general JavaScript, or private APIs. See Use only advertised syntax.
+- Keep ternaries in the destination type. See Typed values and templates.
+- Prove resolution in a containing-flow run. See Verify runtime resolution.
+
 Data types are the TypeScript types of workflows: every expression is typed, and an expression can only be written against a known type. Integration types describe what integration actions output (resolved by a successful dev run); `custom.*` types describe shapes for data-store records and AI-node structured outputs. Two wrappers matter: `dataRecord.custom.x` means "an actual stored record of that shape" — the fields plus record identity (`id`, `createdAt`) — while bare `custom.x` is just data in that shape; `list.` prefixes a list of any type. When an expression cannot be authored, the cause is usually a missing type — resolve the upstream node's output type first, don't guess field paths.
 
-`.every()` accepts the same multi-condition predicates as `.filter()` and compiles to the
-single-pass `:all match` op. A constraint whose field no longer exists in the schema makes
-`.every()` false; `.filter()` drops that constraint. Per-row missing, null, and unparseable values
-follow the comparator's own semantics, and negative comparisons can pass missing or null rows.
-For guard conditions, require field presence explicitly.
+`.every()` accepts the same multi-condition predicates as `.filter()` and compiles to `:all match`. A removed schema field makes `.every()` false but is dropped by `.filter()`. Comparator semantics govern missing, null, and unparseable values; guards must require presence explicitly.
 
 ## How empty values evaluate
 
-An empty input is not "nothing" — it evaluates to the type's empty form: empty text `""` for TEXT, null/undefined for objects. Two platform semantics follow, and both fail silently rather than erroring:
+An empty input evaluates to its typed empty form: `""` for TEXT, null/undefined for objects. Both cases below fail silently:
 
-- **A filter comparing against an empty value still filters — and matches NO records.** This is deliberate (fail-closed; matching everything by accident would be worse). If "empty should mean skip this filter", opt that constraint into ignore-empty mode explicitly (`ignoreEmptyConstraints`, see [references/dsl-and-recipes.md](references/dsl-and-recipes.md)).
-- **An optional TEXT input left empty arrives as `""`**, so an `equals` constraint against it matches nothing — the classic symptom is "search finds zero results only when the optional filter is blank", which then cascades (e.g. a create-if-missing step makes duplicates).
+- **A filter compared with empty matches no records.** To skip an omitted constraint, opt into `ignoreEmptyConstraints`; see [references/dsl-and-recipes.md](references/dsl-and-recipes.md).
+- **An omitted optional TEXT input arrives as `""`.** Equality then matches nothing and can make a create-if-missing step duplicate data.
 
 When a run unexpectedly returns zero results, check the resolved configs for empty comparison values first (`cai exec node <nodeExecutionId> --full`).
 
@@ -66,10 +71,16 @@ cai expr ops --workflow <workflowId> --type <text|number|date|list|boolean|file|
 
 The catalog is workflow-scoped because it is read from expression context. On CLI, an existing `cai use` or `CAI_WORKFLOW` selection can replace the explicit flag; MCP `expr_operation_list` always requires `workflowId`.
 
-Keep the program to optional `const` declarations followed by one final expression. Do not use loops, assignments, `new`, regular expressions, optional chaining, arbitrary library methods, or object construction unless the current compiler catalog explicitly supports them.
+Keep the program to optional `const` declarations followed by one final expression. Do not submit raw AST JSON or probe private APIs. Do not use loops, assignments, `new`, regular expressions, optional chaining, arbitrary library methods, or object construction unless the compiler catalog supports them.
 
 Date values are ISO-8601 strings on the wire (`"2026-06-05"` or `"2026-06-05T12:30:00Z"`). A `date`-typed flow input or field is used directly with date operations; only `text` values need `.toDate()` first. For epoch text, pass the unit literal explicitly: `flow.timestamp.toDate("epoch_seconds")` or `flow.timestamp.toDate("epoch_millis")`. The ops table renders that argument generically; never guess the unit from digit count.
 
+#### Typed values and templates
+
+`--value` stores a literal, so `flow.name`, `{inputs.Name}`, `{{name}}`, and `${name}` stay static. `--js` and `--js-file` compile typed expressions. `${...}` interpolates only inside a backtick template expression, which returns text. Keep non-text values as direct typed expressions.
+
+Ternaries preserve compatible scalar branch types: number and boolean branches stay number and boolean. A different inferred destination type means the write is incomplete. Report the compiler error; do not quote or coerce branches to text.
+
 Read [references/dsl-and-recipes.md](references/dsl-and-recipes.md) for canonical patterns.
 
 ### 4. Compile, write, and read back
@@ -109,6 +120,14 @@ cai expr validate <nodeId> --mode onlyWhen --js '<boolean expression>' --json
 cai node only-when <nodeId> --js '<boolean expression>' --json
 ```
 
+Node `only-when` takes one restricted boolean through `--js` or `--js-file`, or grouped conditions through `--groups-json '[["a","b"],["c"]]'` (inner arrays are AND, outer rows are OR). Root scalar `&&` or `||` inside one expression is unsupported; use `--groups-json` for compound guards. Branch add/update accepts `string[][]`: outer rows are OR, inner entries are AND, and each entry compiles separately.
+
+```bash
+cai branch update <nodeId> --route <routeId> --condition-json '[["flow.email.isNotEmpty()","flow.units < 5"],["flow.override === true"]]' --json
+```
+
+Use grouping only when branch semantics fit. For a compound node-only guard, use `--groups-json`; do not weaken the rule or probe private APIs. To make missing numeric input fail `< 5`, use `(flow.unitsLeft ?? 5) < 5`.
+
 Router and If/Else conditions are written with `cai branch add` or `cai branch update` after the same context/validation discipline.
 
 ### 5. Verify runtime resolution
@@ -139,3 +158,16 @@ Inspect `runScope` and `resolvedConfigs` in the run result. A null or missing dy
 - Preserve `0` and `false`; they are values, not missing data.
 - Optional filters need an explicit behavior decision. Do not silently change fail-closed filtering to match-all.
 - A compiler success proves syntax and types, not correct source selection. Verify the source node/input IDs when names are ambiguous and inspect runtime values.
+
+## Before you finish
+
+```bash
+cai expr context <nodeId> --prop <propName> --json
+cai expr validate <nodeId> --prop <propName> --js '<expression>' --json
+cai expr decompile <nodeId> --prop <propName> --json
+cai run flow <flowId> --inputs <values.json> --json
+```
+
+- Context must show current source IDs and bindings.
+- Validation and decompile must agree on source and type.
+- The flow run must show the intended value in `runScope` and `resolvedConfigs`.

package/skills/controllerai-expressions/references/dsl-and-recipes.md

@@ -10,6 +10,16 @@ The live compiler and `cai expr context`/`cai expr ops` are authoritative. These
 
 Use the exact bindings and fields returned for the destination node.
 
+## Text prefix
+
+When `.startsWith()` is unavailable, test a prefix with:
+
+```js
+flow.subject.isNotEmpty() ? flow.subject.split("urgent")[0] === "" : false
+```
+
+The typed conditional keeps empty text from matching. Replace the binding and prefix literal with exact values from context. Do not split on whitespace unless the requirement is first-word equality. Test punctuation immediately after the prefix, such as `urgent-alpha`, plus a near miss.
+
 ## HTTP JSON body
 
 An HTTP node's JSON/body prop is stored as JSON text. The expression language does not support object literals or `JSON.stringify`. Build the document as a template and insert complete JSON tokens:

package/skills/controllerai-flow-control/SKILL.md

@@ -7,7 +7,18 @@ description: Design and configure Controller AI execution paths using only-when
 
 The `cai ...` examples are canonical grammar. Use the transport selected in `controllerai-start` and its MCP tool map; never mix transports in one task.
 
-Choose the primitive from the intended execution semantics before adding nodes.
+Choose by intended runtime semantics.
+
+## Rules that break tasks when skipped
+
+- Guard the exact action with node `only-when`; see Conditions.
+- Use If/Else for one path and Router for all matches; see Pick the correct primitive.
+- Keep downstream wiring after node-only skip; see Conditions.
+- Never invent a missing condition or Router order; see If/Else and Router.
+- Build standard loops only with `flow for-each`; see Loops.
+- Converge paths through Join Paths; see Subflows and convergence.
+- Fail missing comparisons closed; keep money paths blocking. See Conditions, Loops, and the error pattern.
+- Never acknowledge validation errors without explicit approval; see `controllerai-workflows` Lifecycle rules.
 
 ## Pick the correct primitive
 
@@ -39,6 +50,10 @@ cai node only-when <nodeId> --js '<boolean expression>' --json
 
 Use `--clear` only when the user's intent is to remove the guard.
 
+Guard the action that must skip. Do not substitute If/Else for a node-only skip. Its `only_when_false` does not block ordinary output; downstream remains eligible. Keep wiring. Guard downstream separately or branch if it must also skip.
+
+Node `only-when` takes one restricted boolean through `--js` or `--js-file`, or grouped conditions through `--groups-json '[["a","b"],["c"]]'` (inner arrays are AND, outer rows are OR). Root scalar `&&` or `||` inside one expression is unsupported; use `--groups-json` for compound guards. Grouped `string[][]` conditions exist only on branch add/update, with outer rows OR and inner entries AND. Use them only when branch semantics fit. If an exact compound node-only guard is required, report it as unsupported; do not weaken the rule or probe private APIs. For a missing number that must fail `< 5`, use a same-type boundary such as `(flow.unitsLeft ?? 5) < 5`.
+
 Choose the primitive by the runtime signal that callers and tests need. A false node `only-when` records `skipReason: "only_when_false"`; a node on an untaken If/Else branch or unmatched Router route records `skipReason: "upstream_skipped"`.
 
 ## If/Else and Router
@@ -51,6 +66,8 @@ cai branch list <controlNodeId> --json
 
 A fresh If/Else already contains one blank `If` branch and an Else branch. The blank condition is a publish/runtime blocker: copy that default branch ID from `branch list` and update it before adding another condition branch. Do not leave the default blank and create a replacement beside it.
 
+Never invent a missing condition from node names, current values, or one observed run. If no authoritative platform surface supplies the business rule, leave the branch blank, report the blocker, and ask the user.
+
 ```bash
 cai branch update <ifElseNodeId> \
   --route <defaultIfBranchId> \
@@ -73,7 +90,7 @@ For If/Else, order is behavior:
 cai branch reorder <ifElseNodeId> --order <conditionId1,conditionId2> --json
 ```
 
-List every condition branch exactly once and omit Else; the operation keeps Else last. Router routes cannot be reordered because every match runs.
+List every condition branch exactly once and omit Else; the operation keeps Else last. Router routes cannot be reordered because every match runs. Do not simulate order by deleting a route or serializing its downstream nodes. Leave the fan-out unchanged unless the user explicitly authorizes a redesign.
 
 After edits, run `cai branch list` again. Treat its warnings about missing conditions or unwired paths as blockers: an unwired selected path can end with an apparently green execution.
 
@@ -136,19 +153,26 @@ MCP: `cai node set-flow` maps to `node_subflow_set`.
 
 Setting the target flow creates mapping props from the target's current inputs. If those inputs later change, run `set-flow` again and reconfigure mappings.
 
-When paths converge, inspect the concrete graph and execution behavior. Do not assume wiring two paths to one action creates a barrier or waits for both. If the requirement is a true join, discover a join-capable component and verify it with representative branch timing.
+For one action after whichever exclusive branch runs, use `registry_flow-merge` (Join Paths) in `chooseActivePath` mode, then place the shared action after it. Never wire several branches directly to an ordinary node or duplicate the shared action. Follow the exact recipe in [references/patterns.md](references/patterns.md) and test each branch once.
 
-Return semantics: a flow that should return data needs a Return response node — without one it returns nothing, and callers (including agents invoking it as a tool) see silent success with empty output. If several Return response nodes complete in one execution, their result objects merge in execution order and a later node silently overwrites an earlier value for the same field. Design for exactly one Return per path unless merging is the intent.
+Return semantics: a flow that should return data needs `registry_flow-return-response`; without it callers see empty success. Declare outputs first, initialize that exact component after the producer, then bind its generated prop with `cai expr set`. Do not guess component keys. See [references/patterns.md](references/patterns.md). Multiple completed Return nodes merge, with later values overwriting earlier ones; design for one Return per path unless merging is intended.
 
-Deleting a flow is a normal, undoable edit: it removes the flow's nodes, edges, inputs/outputs, and attached triggers, and unlinks run-subflow callers in other flows — the same way deleting a function breaks its call sites. No confirmation ceremony is needed; run `cai workflow validate` afterwards to see every break, fix or remove the callers it lists, and `cai workflow restore` if the deletion was a mistake. Turning `continueOnError` off is the same class: it deletes the node's Error output and every edge from it — validate after, restore if regretted.
+Deleting a flow removes its graph, contract, triggers, and caller links. Validate and restore if mistaken. Turning `continueOnError` off also deletes its Error output and edges; validate and restore likewise.
 
 Read [references/patterns.md](references/patterns.md) for concise canonical patterns.
 
-## Completion gate
+## Before you finish
+
+```bash
+cai branch list <controlNodeId> --json
+cai workflow validate --json
+cai run flow <flowId> --inputs <values.json> --json
+cai exec tree <workflowExecutionId> --json
+```
 
 - Every branch has the intended condition and a wired target.
 - If/Else ordering matches priority and Else remains last.
 - Router fan-out is intentional when more than one condition can be true.
 - Loop item type and list expression compile against actual source data.
 - Expected true, false/Else, empty-list, one-item, several-item, over-limit, and error paths are tested.
-- `cai exec tree <workflowExecutionId>` contains no unexplained skipped or missing nodes.
+- The execution tree shows intended `only_when_false` or `upstream_skipped` reasons and no unexplained missing nodes.

package/skills/controllerai-flow-control/references/patterns.md

@@ -36,6 +36,19 @@ New order -> Router
 
 One order may take all three routes. If that is not acceptable, use If/Else.
 
+## Grouped branch condition
+
+Only Router and If/Else branch commands accept grouped conditions. The outer rows are OR and the expressions within one row are AND:
+
+```bash
+cai branch update <controlNodeId> \
+  --route <routeId> \
+  --condition-json '[["flow.email.isNotEmpty()","flow.units < 5"],["flow.override === true"]]' \
+  --json
+```
+
+Each string must compile independently. Node `only-when` has no `--condition-json`; if exact compound node-only semantics are required, report the limitation instead of using a private API or weakening the guard.
+
 ## Per-item subflow
 
 Use `cai flow for-each` to create the item flow, typed item input, loop node, and list wiring atomically. First run `cai node get <sourceNodeId> --json`, choose the intended `outputs[]` entry, and pass its exact opaque `id` as `--source-output`; never pass its label or assume the first output. Omit list-selection flags when the whole selected output payload is a list; use `--list-field <nested.path>` for a list below `.data`; reserve `--list-js` for an exact advanced expression or `--js-file <path|->` for that expression in a UTF-8 file/stdin. The three selection forms are mutually exclusive.
@@ -46,6 +59,58 @@ The runtime limit defaults to 500 items and supports 1 through 10000. Use `--max
 
 Decide explicitly whether one child-flow failure should stop the sequential loop. Use `--continue-on-error` only when partial completion is acceptable and downstream logic handles failed iteration records. It does not recover a list or mapping expression that fails before an iteration starts.
 
+## Converge exclusive paths
+
+Initialize Join Paths and select its active-path mode:
+
+```bash
+cai node init \
+  --flow <flowId> \
+  --node registry_flow \
+  --key registry_flow-merge \
+  --name "Join paths" \
+  --json
+cai node set <joinNodeId> --prop mode --value chooseActivePath --json
+cai node props <joinNodeId> --json
+# If returned props require it:
+cai node set <joinNodeId> --prop pathDataType --value <returnedTypeValue> --json
+cai node connect --flow <flowId> --from <firstBranchTailNodeId> --to <joinNodeId> --json
+cai node connect --flow <flowId> --from <secondBranchTailNodeId> --to <joinNodeId> --json
+cai node init \
+  --flow <flowId> \
+  --node <sharedNodeSlug> \
+  --key <sharedNodeKey> \
+  --name "<shared action>" \
+  --after <joinNodeId> \
+  --json
+```
+
+Set `pathDataType` only when returned props require it, using an exact returned option. Repeat the branch-tail connection for every type-compatible exclusive path. If the shared action already exists, connect it after Join Paths instead of initializing a replacement. Do not connect several branches directly to an ordinary node or duplicate the action. `chooseActivePath` requires at most one active input, so do not use it after a Router whose routes can overlap. Run one test per branch and stop after all pass.
+
+## Return a flow value
+
+Declare the output before the Return response node so its generated prop exists:
+
+```bash
+cai flow output add <bodyFlowId> \
+  --display "<output label>" \
+  --name <output_key> \
+  --type <type> \
+  --json
+cai node init \
+  --flow <bodyFlowId> \
+  --node registry_flow \
+  --key registry_flow-return-response \
+  --name "Return <value>" \
+  --after <producerNodeId> \
+  --json
+cai node props <returnNodeId> --json
+cai expr context <returnNodeId> --prop <generatedOutputProp> --json
+cai expr set <returnNodeId> --prop <generatedOutputProp> --js '<producer binding>' --json
+```
+
+Do not guess `registry_flow-return` or `registry_flow-response`. Run the body flow and verify its top-level output contains the promised value.
+
 ## Error path
 
 Continue-on-error is for steps whose failure must not block the main path — notifications, logging, optional enrichment. Enabling it captures the node's error, downstream nodes still execute (receiving null for the failed node's output), and the run ends `completed_with_error`:

package/skills/controllerai-integration-actions/SKILL.md

@@ -9,6 +9,13 @@ The `cai ...` examples are canonical grammar. Use the transport selected in `con
 
 Ready integration actions give a hosted agent one app operation without first building a workflow. Use the canonical operations below through the selected transport; do not call Controller AI REST routes directly.
 
+## Rules that break tasks when skipped
+
+- Attach one existing app operation directly; never wrap it in a one-node workflow. See Choose direct action or workflow.
+- Capture the exact integration, action, connection, and tool IDs. See Discover exact identities.
+- Decide confirmation before attachment, especially for writes or spend. See Decide approval before attaching.
+- Verify persisted direct-action events, not a workflow execution ID. See Verify through the hosted agent.
+
 ## Choose direct action or workflow
 
 Use a direct action for one existing operation such as sending one message, creating one record, or adding one row.
@@ -105,3 +112,14 @@ If confirmation is required, inspect the pending action and exact arguments befo
 Publishing snapshots the action identity, description, and approval policy into the agent version. The connection and authorization grant remain live security bindings: rebinding can redirect the published action, while breakage, revocation, or detachment can stop it immediately without another agent publish. Detachment also removes the draft tool; publish afterward to remove the unavailable tool from the published list.
 
 Organization members use the published agent, never its mutable draft. Direct actions run through the agent owner's connected external account. Controller AI usage draws from the organization's shared usage pool, regardless of which member calls the agent. State that credential boundary before organization sharing.
+
+## Before you finish
+
+```bash
+cai agent tools <agentId> --json
+cai agent conversation history <conversationId> --json
+```
+
+- Tools must show one intended direct attachment with the exact returned identities, connection, description, and confirmation policy.
+- History must contain the persisted action event, exact arguments, and result; confirm any requested external effect separately.
+- No wrapper workflow should exist unless the capability actually required orchestration or reuse.

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

@@ -67,7 +67,9 @@ MCP: use `node_add`; `cai node init` is the CLI alias of `cai node add`.
 
 Omit flags that do not apply. `--after` creates the ordinary main/error wire at creation. Use it when later props need upstream data. Initialization also accepts `--props`, but use it only for static, non-option values already present in the inspected component metadata. Never inline a `remoteOptions` value, a reload selector and its dependents, or a prop that has not materialized yet; initialize first and set those sequentially. Use `--enable-prop <name...>` only for optional props confirmed by component metadata.
 
-Capture the returned `nodeId`; do not rediscover it by name.
+Capture the returned `nodeId`; do not rediscover it by name. Inspect the complete create result before projecting fields. A missing projection is not proof that creation failed, so read the captured ID or exact flow inventory before any retry.
+
+When repairing an existing node, keep its node ID and configure it in place. Do not delete and recreate it merely to clear bad props, select a component, or refresh generated props; deletion discards wiring, conditions, and identity-based references. Replace it only when the requested component itself must change. Then capture the replacement ID, reconnect every dependent, and revalidate them.
 
 ### 4. Follow readiness, not guesses
 

package/skills/controllerai-start/SKILL.md

@@ -29,13 +29,20 @@ On the CLI, run:
 cai doctor
 ```
 
+For a new terminal assistant, `cai agent setup` detects Claude Code, Codex, and
+Cursor, ensures login, and installs the best available plugin or MCP-and-skills
+fallback; use `cai agent setup --status --json` for a read-only machine plan.
+Use `cai doctor` to compare installed version stamps and see the exact update
+command, and `cai docs [path]` (or `cai docs --list`) to read platform docs in
+the terminal.
+
 MCP: use `account_status`; local diagnosis, login, and `cai connect` do not exist.
 
 On the CLI, if authentication is missing and the human already has an account, run `cai connect`. If no account exists, run `cai signup` to create a provisional workspace and start building immediately. An unclaimed signup has the same functional access as a free account, including workflow and agent publishing; its workspace is not automatically deleted, and it has a $1 monthly usage cap (`cai signup` prints the exact amount). Email claiming is optional: run `cai signup email <address>`, ask the human account owner for the 6-digit code delivered to their inbox (never guess it), then run `cai signup verify <code>` to raise the monthly cap to $5 and enable durable account recovery. If agent signup is disabled, ask the human to register at https://app.getcontroller.ai/register, then run `cai connect`.
 
 MCP: the OAuth caller is already provisioned; use `account_claim_start` and `account_claim_verify` for optional email claiming.
 
-On the CLI, if `cai doctor` reports missing, stale, or damaged managed skills, run `cai skills update`, then run `cai doctor` again. When the `CLI version` row says a newer cai is available, upgrade before continuing (`npm install -g @controllerai/cli@latest`, then `cai skills update`) — new versions carry fixes the rest of these skills assume. Skill updates are setup maintenance, not a step to repeat during every build.
+On the CLI, if `cai doctor` reports missing, stale, or damaged managed skills, run `cai skills update`, then run `cai doctor` again. When the `CLI version` row says a newer cai is available, run `cai upgrade` before continuing — it prints the explicit CLI install command and updates detected skills, and new versions carry fixes the rest of these skills assume. Skill updates are setup maintenance, not a step to repeat during every build.
 
 MCP: use `guide_list` and `guide_get`; skill installation, updates, and CLI upgrades are not hosted-session steps. Never ask the user to paste a password, provider token, or Controller AI credential into chat.
 
@@ -57,6 +64,12 @@ Prefer a ready integration action when one existing operation completes the capa
 
 If the user's outcome does not reveal whether they want an agent or an automation that runs on an event, ask one short clarifying question. Otherwise proceed with the smallest suitable surface.
 
+## Lock targets before mutation
+
+Before the first write, resolve every existing target against the effective workflow. Prefer an explicit ID or an object already connected to the pinned workflow. When a list is account-wide, filter it by exact name or ID; never take the first, latest, or similarly named result. Read back the chosen object's ID, name, and owning workflow or flow. Keep those IDs for the task and never rediscover the target by name.
+
+Check `ok` and the complete `data` object from every mutation before projecting fields. A missing projected field is not proof that the mutation failed. Read back the returned ID or list the exact target before retrying. Never repeat a create until readback proves the first call created nothing.
+
 ## Platform docs
 
 The platform reference lives at https://docs.getcontroller.ai. Fetch https://docs.getcontroller.ai/llms.txt for the machine-readable index of every page; append `.md` to any page path for raw markdown (for example https://docs.getcontroller.ai/start/safety.md), or fetch /llms-full.txt for the whole corpus at once. Skills remain the procedural authority — consult the docs for what they do not carry: the execution and cost models, type-system and version-rail contracts, the full CLI and expression-operation references, and the workflow API. When a docs page and a skill disagree, prefer the skill and its live platform queries (`cai expr ops`, `cai integration actions`).
@@ -69,6 +82,8 @@ The platform reference lives at https://docs.getcontroller.ai. Fetch https://doc
 - Coding-agent subscriptions cover builder reasoning, not Controller AI hosted-agent runtime usage.
 - Provider actions can send messages, mutate or delete records, and incur provider charges. Decide the per-action confirmation policy before attaching one.
 - Never publish, share with the organization, replay a live trigger, or perform a consequential external test without clear user intent.
+- A missing business rule is a blocker, not permission to infer one from names or sample data. Ask the user and leave the affected state unchanged.
+- Stop when the requested state and its required evidence are reached. Do not add objects, publish, or keep probing beyond that boundary.
 - When a platform limitation blocks the outcome, STOP and report the partial result with the blocking error; never keep probing until the clock expires.
 
 At completion, report what was created, what is still draft or live, the evidence actually observed, and any connection or user decision still required.

package/skills/controllerai-triggers/SKILL.md

@@ -9,6 +9,15 @@ The `cai ...` examples are canonical grammar. Use the transport selected in `con
 
 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.
 
+## Rules that break tasks when skipped
+
+- 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:
@@ -91,9 +100,7 @@ or
 {"cron":{"intervalSeconds":900}}
 ```
 
-Do not discard timezone by passing a bare cron string. The timezone is the user's to
-choose, not yours to assume: when they say "at 9am" without one, ask — a schedule in the
-wrong timezone runs at the wrong time every single day, and nothing ever errors.
+Do not pass a bare cron string or assume a timezone. Ask when the user says "at 9am" without one.
 
 ## Create and map
 
@@ -109,7 +116,9 @@ cai trigger create \
   --json
 ```
 
-Capture all returned IDs. `triggerId` is the canvas ID used for get/rename/set-enabled/delete. `backendTriggerId` is numeric and used for captured events and replay. They are not interchangeable.
+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).
 
@@ -117,11 +126,11 @@ Follow returned `nextSteps` in order. Trigger payload does not automatically pop
 
 ## 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. `cai trigger set-enabled <triggerId> --enable|--disable` changes the enabled state reversibly and idempotently; pass exactly one state flag.
+`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 after either so production follows; until then, the previous live trigger can still start the published workflow.
+Both are development edits. Publish only for an authorized Live change; otherwise the prior Live trigger remains active.
 
 ## Establish a typed sample
 
@@ -145,9 +154,13 @@ cai trigger test-events --id <triggerId> --disallow
 
 MCP: call `trigger_test_events_set` with `allowed: false`, or `allowed: true` to arm it.
 
-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.
+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.
 
-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.
+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
 
@@ -160,6 +173,8 @@ 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
@@ -190,3 +205,18 @@ 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.

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

@@ -23,7 +23,7 @@ Skipping capture/sample selection commonly leaves downstream output untyped. Ski
 
 | ID | Used by |
 | --- | --- |
-| Canvas `triggerId` | `trigger get`, `rename`, `set-enabled`, `delete` |
+| 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` |
@@ -44,6 +44,21 @@ Use `--target live --confirm-live` only for an intentional post-publish live ver
 
 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
+```
+
+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.
+
+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.
+
 ## Debugging a missing run
 
 1. `cai trigger list --json`: enabled, correct flow, recoverable backend ID.