@controllerai/cli 0.2.16 → 0.2.17

package/skills/controllerai-agents/SKILL.md

@@ -5,26 +5,31 @@ description: Design, assemble, test, publish, and share user-facing Controller A
 
 # Controller AI agents
 
-An agent has one mutable draft and immutable published versions. Capabilities are ready integration actions, workflow tools, or both. Build on the draft, verify through a draft conversation, publish last. Editing the draft never updates the live agent by itself.
-
-Build the draft in this order: instructions, tools and descriptions, user-decided permissions, reference files, Test verification, publish, then optional Slack and organization sharing.
+An agent has one mutable draft and immutable published versions. Build instructions, tools, permissions, and files on the draft; verify in Test; publish last. Draft edits never update Live by themselves.
 
 The `cai ...` examples are canonical grammar. Use the transport selected in `controllerai-start` and its MCP tool map; never mix transports in one task or call Controller AI REST routes directly.
 
-## 1. Choose the capability architecture
+## Rules that break tasks when skipped
+
+- Attach one ready action directly instead of wrapping it; see Choose the capability architecture.
+- Choose confirmation before attaching a consequential tool; see Create and assemble the draft.
+- Use one conversation on an explicit rail for each verification task; see Verify the draft as an agent.
+- Resolve pending requests in that same conversation; see Verify the draft as an agent.
+- Enablement is runtime state, not publication; see Create and assemble the draft.
+- Publish authorized workflow dependencies, preflight, then publish the agent; see Publish in dependency order.
+- Draft-only means stop before publish; draft evidence never proves Live. See Publish in dependency order.
 
-For each capability:
+## 1. Choose the capability architecture
 
 - Use `controllerai-integration-actions` when one existing app operation completes it.
 - Use a workflow tool for multiple steps, transformations, branching, looping, durable state, triggers, a custom typed contract, or reusable business logic.
-- Put conversational judgment, when-to-use rules, tone, and escalation in agent instructions.
-- Put stable source material in a knowledge file.
+- Put judgment, tool-selection rules, tone, and escalation in instructions; put stable sources in knowledge files.
 
 Do not create a one-node workflow merely to expose a ready action, or replace orchestration with several independent direct actions when ordering or data handling must be deterministic.
 
 ## 2. Build and verify capabilities
 
-For a ready action, follow `controllerai-integration-actions`: discover the exact integration/action, select a connection, decide confirmation policy, then attach it.
+For a ready action, follow `controllerai-integration-actions`: discover exact identities, select a connection, decide confirmation, then attach.
 
 For every workflow tool, load the relevant workflow skills and test the development state before attaching:
 
@@ -36,12 +41,11 @@ cai run flow <flowId> --inputs values.json --json
 
 MCP: there is no pin; pass `workflowId` to `flow_get` and `run_flow`, pass parsed `inputs`, and set `waitSeconds`.
 
-Capture the successful workflow execution ID. Inputs become tool parameters; outputs become its result.
-Before attaching, require a nonempty output contract and verify the completed run returns it; otherwise the agent receives an empty result.
+Capture the successful execution ID. Inputs become tool parameters and outputs its result. Require a nonempty output contract and verify the run returns it.
 
 ## 3. Create and assemble the draft
 
-Write short instructions covering role, tool-selection rules, expected inputs/results, safety boundaries, response style, and error behavior. Require: "If an action returns an error, tell the user what failed and what you were trying to do; do not retry more than once."
+Write short instructions for role, tool use, inputs/results, safety, response style, and errors. Require truthful failure reporting and at most one retry.
 
 Read [references/instructions-and-versioning.md](references/instructions-and-versioning.md) before publishing or explaining Test versus Live behavior.
 
@@ -75,9 +79,7 @@ cai agent tools <agentId> --json
 cai agent get <agentId> --json
 ```
 
-MCP: use `agent_knowledge_file_add` for knowledge or `agent_workspace_file_add` for shared/runtime, and pass file text inline as `content`. `agent_file_list` uses `environment: dev` or `environment: live` instead of `--live`.
-
-Adding with `--space shared` updates the live runtime file space immediately without publishing; an active agent sees it on the next turn, a disabled agent after enablement.
+MCP: use `agent_knowledge_file_add` or `agent_workspace_file_add` with inline `content`; `agent_file_list` uses `environment: dev|live`. Shared runtime files update live immediately.
 
 The default is no approval: attached actions and workflow tools run without a human approval step unless `requireConfirmation` is `true`, and omitting `--require-confirmation` has the same behavior. When attaching an action that sends, posts, spends, or deletes, choose `true` or explicitly tell the user that it will run unattended. Mention the confirmation choice in the report to the user; `cai agent update-tool` can change it later.
 
@@ -91,11 +93,9 @@ Keep the two modes straight:
 | Runtime files | Current live runtime files, overlaid by development/test runtime files at the same path | Current live runtime files only |
 | Access | Owner only | Owner, plus organization members when shared; non-owners never see the draft |
 
-Version pinning for workflow tools does not exist: live tools always track the workflow's latest release; publishing the workflow is what changes tool behavior. If the user asks to freeze a tool's version, say so plainly — even when framed as a condition — and still attach it (policy `latest`); never abandon the attachment over it.
-
-Publishing the agent snapshots name, instructions, tool identities, descriptions, approval policies, and knowledge files; it moves the live pointer and restamps every existing live conversation to the new version. It does not snapshot the runtime model.
+Version pinning for workflow tools does not exist. Live tools track the latest release. If asked to freeze one, explain this, attach with policy `latest`, and never abandon the attachment.
 
-Publishing is a hard cutover: mid-turn live conversations are interrupted (the person's in-flight answer never arrives), unexecuted approval requests expire, and each conversation reopens on its next message running the new version. Time publishes accordingly and tell the user.
+Publishing snapshots versioned fields, moves the live pointer, and restamps every existing live conversation. It does not snapshot the runtime model. This cutover interrupts in-flight answers and expires pending approvals; time it accordingly.
 
 Runtime lifecycle changes do not require publishing:
 
@@ -105,9 +105,7 @@ cai agent update <agentId> --enabled --json
 cai agent delete <agentId> --confirm --json
 ```
 
-MCP: draft edits use `agent_update`; runtime state uses `agent_set_enabled` with `enabled`; `agent_delete` has no `confirm` parameter.
-
-Disable pauses runtime immediately; enable resumes it. Delete is soft: it revokes live access, requests best-effort termination of active sessions and pending approvals, keeps history but makes it inaccessible, has no CLI restore, and does not guard dependent workflows.
+MCP: draft edits use `agent_update`; runtime uses `agent_set_enabled`; `agent_delete` has no `confirm`. Disable pauses runtime. Soft delete revokes access and requests session termination; there is no CLI restore.
 
 ## Runtime usage boundary
 
@@ -124,11 +122,16 @@ cai agent conversation history <conversationId> --json
 
 MCP: `agent_test` requires `rail: draft` or `rail: live` and takes `waitSeconds`.
 
-Test requests that should and should not select each tool. Verify exact arguments, truthful use of results, errors, and knowledge behavior.
+`agent test` always creates a conversation. Use it for a one-shot check. When a task may need follow-up or approval, create one conversation on the requested rail, capture its ID, and reuse it:
+
+```bash
+cai agent conversation create <agentId> --draft --title "<test case>" --json
+cai agent conversation send <conversationId> --message "<request>" --wait --json
+```
 
-Also offer the agent's app page so the user can try the draft hands-on before publishing (outputs include `appUrl` when the app origin is known); their impression outweighs your transcript reading.
+Do not resend the request or create a replacement after an approval pause. A required post-publish Live check is a separate rail task and gets one fresh Live conversation.
 
-MCP: call `agent_present` for the finished agent and relay the returned card with its name, purpose, tools, and link.
+Test positive and negative tool selection, exact arguments, results, errors, and knowledge. Offer the returned `appUrl`; on MCP, call `agent_present` and relay the returned card.
 
 - For a workflow tool, correlate a side-effectful call with its terminal workflow execution ID.
 - For a direct integration action, inspect persisted conversation action events/run result and the intended external effect. Direct actions do not create workflow execution IDs.
@@ -140,7 +143,7 @@ cai agent conversation approve <conversationId> --request <requestId> --json
 cai agent conversation deny <conversationId> --request <requestId> --message "<reason>" --json
 ```
 
-The server resolves the tool from the permission request; do not pass a human-readable tool name, and do not approve merely to make a test continue.
+The server resolves the tool from the request ID. Do not approve merely to continue. Resolve every pending request before publishing; approval or denial resumes this conversation, while publishing expires it.
 
 After `cai agent remove-tool`, test one request that must no longer use the removed capability and one retained capability.
 
@@ -158,6 +161,8 @@ MCP: there is no `use`; pass `workflowId` to `workflow_status` and `workflow_pub
 
 Publish a workflow only when its verified development state must go live and the user authorized it. A workflow publish already followed by a live agent changes that tool's live behavior immediately; do not republish the agent merely to pick it up.
 
+For a draft-only request, stop after Test evidence. Do not publish a workflow or agent merely because it is ready.
+
 Then publish the agent:
 
 ```bash
@@ -169,31 +174,41 @@ cai agent test <agentId> --live --message "<representative request>" --json
 
 MCP: `agent_test` requires `rail: draft` or `rail: live` and takes `waitSeconds`.
 
-`publish-preflight` is the arbiter of structural readiness, with blocker parity with the publish gate (missing/unpublished/unrunnable tool flows, broken connections). When it lists blockers, report them and stop. When `hasBlockers` is false and the user asked for a release, publish — except an error you actually watched happen (a failed Test turn, an errored tool call), which blocks even a green preflight; the shape or style of successful output never does.
+`publish-preflight` is the arbiter of structural readiness. Report blockers and stop. With none and an authorized release, publish, except an error you actually watched happen; that blocks even a green preflight.
 
 Email verification is not a publishing prerequisite. An unclaimed agent-created account may publish; email claiming only raises its monthly usage cap and enables account recovery.
 
-Versioned agent state follows one loop: edit the draft, read back, verify in Test, publish, verify Live. Name, instruction, tool identity/description, approval-policy, and knowledge-file changes reach the published version only on the next agent publish.
-
-Published agent versions have no rollback — never promise to "revert" one. Recover forward: restore the wanted DRAFT and publish anew — for agents, reapply an earlier snapshot from `cai agent versions`; for workflow tools, `cai workflow history` + `cai workflow restore --state <stateId>` restores the dev DEFINITION (not record data), then republish.
-
-Follow the live-bound exceptions in [references/instructions-and-versioning.md](references/instructions-and-versioning.md): workflow releases, direct-action grants, and runtime files can change Live without an agent publish. Verify them with a fresh Live conversation; after detaching an action, publish to remove the unavailable tool from the published list.
+Use one loop: edit draft, read back, verify Test, publish, verify Live. Published versions have no rollback. Recover forward from `agent versions`; restore workflow definitions with history/restore, then republish. Workflow releases, action grants, and runtime files are live-bound; see [references/instructions-and-versioning.md](references/instructions-and-versioning.md). After detaching an action, publish to remove it from the published list.
 
 Draft evidence does not prove the live agent. Test is owner-only; shared users always run the latest published agent version and never see draft instructions, tools, or knowledge.
 
 ## 6. Offer Slack and organization sharing
 
-After a successful publish, offer the next steps unprompted:
-
-- **Slack**: talking to the agent in Slack needs the Slack ↔ Controller AI connection plus per-agent Slack configuration (slug, channel), both set up in the product — point the user there and offer a walkthrough.
-- **Sharing**: agents remain private unless the user explicitly asks for organization access:
+After publish, offer product setup for Slack. Agents remain private unless the user requests organization access:
 
 ```bash
 cai agent visibility <agentId> --value organization --json
 ```
 
-Organization members use the published version. Direct actions run through the owner's connected external account; usage comes from the organization's pool. Rebinding or revoking that live grant immediately affects published agents; return to private visibility to revoke access.
+Members use the published version. Direct actions use the owner's external account and organization usage pool. Grant changes affect Live immediately; private visibility revokes access.
+
+## Before you finish
+
+```bash
+cai agent tools <agentId> --json
+cai agent conversation list <agentId> --mode dev --json
+cai data query --type custom.<type> --env dev --json
+cai agent conversation history <conversationId> --json
+cai agent publish-preflight <agentId> --json
+cai agent versions <agentId> --json
+cai agent test <agentId> --live --message "<representative request>" --json
+```
+
+Run the last three commands only for an authorized release. For Live verification, use `--mode live` and `--env live` in the same pair.
 
-## Final report
+- Conversation list must show the captured ID on the requested rail, without retry-created duplicates.
+- History must show the intended tool arguments, terminal result, and no unresolved permission request.
+- For stateful behavior, the same-rail data query must show the expected record; an assistant reply is not proof.
+- A release requires clean preflight, agent version read-back, and one fresh Live conversation. Draft-only work must remain unpublished.
 
-State the agent ID/version, tools and confirmation policies, workflow execution IDs and direct-action conversation evidence, draft/live status, live connection bindings, organization access, and anything unverified.
+Report the agent ID/version, tools and confirmation policies, execution or direct-action evidence, rail state, connections, access, and anything unverified.

package/skills/controllerai-ai-nodes/SKILL.md

@@ -7,7 +7,14 @@ description: Configure and verify AI-powered Controller AI workflow nodes, espec
 
 The `cai ...` examples are canonical grammar. Use the transport selected in `controllerai-start` and its MCP tool map; never mix transports in one task.
 
-First decide whether the capability belongs inside a deterministic workflow or in a user-facing Controller AI agent:
+## Rules that break tasks when skipped
+
+- Use native Ask AI for a bounded AI step; see Configure Ask AI in dependency order.
+- Keep an existing Ask AI node unless the requested component changes; see Configure Ask AI in dependency order.
+- Set reload selectors before fetching live model options; see Configure Ask AI in dependency order.
+- Never invent or hardcode a model ID; see Configure Ask AI in dependency order.
+
+## Choose the AI surface
 
 - Use Ask AI for one bounded transformation with explicit inputs and output contract.
 - Use a Controller AI agent for conversational judgment, multiple tools, durable instructions, and knowledge files. Load `controllerai-agents`.
@@ -15,6 +22,8 @@ First decide whether the capability belongs inside a deterministic workflow or i
 
 ## Configure Ask AI in dependency order
 
+For a bounded workflow transformation, use the native Ask AI component. Do not replace it with a provider integration action or delete an existing Ask AI node to bypass configuration.
+
 Discover the current component instead of hardcoding a key:
 
 ```bash
@@ -43,7 +52,7 @@ cai expr set <nodeId> --prop <promptProp> --js '<prompt expression>' --json
 
 MCP: `node set` and `expr set` both use `node_prop_set`; pass exactly one of `value` or `js` here.
 
-Model catalogs, availability, and prices change. Use current options and honor the user's cost/quality preference; do not claim a model exists because it appears in an old example.
+Model catalogs, availability, and prices change. Use current options and the user's cost/quality preference. If the requested model is absent, leave it unset, report it, and ask; never substitute.
 
 ## Prefer typed output for downstream logic
 
@@ -74,10 +83,12 @@ Avoid filler personas, repeated instructions, and claims about data not present
 
 Read [references/selection-and-testing.md](references/selection-and-testing.md) for node choice and evaluation.
 
-## Verify
+## Before you finish
 
 ```bash
+cai node get <nodeId> --json
 cai node status <nodeId> --json
+cai node props <nodeId> --json
 cai run node <nodeId> --inputs values.json --json
 cai exec node <nodeExecutionId> --full --json
 ```
@@ -86,4 +97,9 @@ MCP: pass parsed values in `inputs` and set `waitSeconds` on `run_node`.
 
 Test at least: normal input, missing/ambiguous input, and an adversarial or boundary case relevant to the task. Check resolved prompt/config, output type, required fields, and values—not just that text was returned.
 
+- `node get` must identify the intended native Ask AI component.
+- `node status` must report ready.
+- Props must contain the exact returned provider/model value and label.
+- The execution must show the resolved prompt and typed output fields.
+
 AI execution inside the workflow is platform/API usage. Access through either builder transport does not transfer the coding-agent subscription to runtime AI nodes.

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