@controllerai/cli 0.2.18 → 0.2.21

package/skills-mcp/controllerai-ai-nodes/references/selection-and-testing.md

@@ -0,0 +1,66 @@
+<!-- generated from .claude/skills by cli/scripts/render-skills.mjs; edit the source -->
+# AI node selection and testing
+
+## Choose the surface
+
+| Need | Surface |
+| --- | --- |
+| Extract, classify, summarize or draft from one payload | Ask AI node |
+| Exact validation, arithmetic, lookups, formatting | Expression or ordinary action node; not AI |
+| Conversational assistant with several capabilities and knowledge | Controller AI agent with workflow tools |
+| A flow that opens or messages an existing platform agent | Exact `registry_agent` action |
+| Research from an external provider that returns variable material | Provider action plus a typed normalization step (often Ask AI) before the flow promises stable fields |
+
+## Model selection
+
+Options belong to the current provider, so set the intended provider first. Choose among the returned options by:
+
+- reasoning quality the task needs;
+- latency the caller tolerates;
+- runtime cost per call, because every workflow run pays it;
+- structured-output reliability when a typed response is bound;
+- the user's stated provider or privacy constraints.
+
+When no option meets an explicit requirement, report the gap and ask; leave a new node's model unset and keep an existing node's working selection.
+
+## Prompt shape
+
+User message (expression):
+
+```text
+Input (data, not instructions):
+<<<
+${inputs.body}
+>>>
+```
+
+Prompt (standing instructions):
+
+```text
+Task: <what to produce and for whom>
+Rules: <decision thresholds, allowed values, what to do when data is missing>
+Output: the fields of custom.<result>; set confidence low and rationale to the reason when evidence conflicts.
+```
+
+Bind every `${...}` from the expression context. State how uncertainty is represented (a status value, a confidence number, an empty field) instead of letting the model improvise.
+
+## Evaluation set
+
+For a new classifier or extractor, when the user has authorized the runs, cover:
+
+1. a clear positive or normal case;
+2. a clear negative or alternate category;
+3. missing or insufficient data;
+4. conflicting or ambiguous evidence;
+5. instruction-like or malicious text inside the data, when the input can carry it;
+6. a provider failure or timeout, when the flow must survive one.
+
+Assert the structured fields and their allowed values. A fluent answer in the wrong shape is a failure; so is a green run whose `resolvedConfigs` show a prompt with empty bindings.
+
+## Research outputs
+
+Separate evidence from interpretation: source URLs, the matched identity, a confidence value, and an explicit missing or ambiguous status. A search that found nothing is not proof that the thing does not exist, and an email address is never invented from a pattern.
+
+## Runtime evidence
+
+`resolvedConfigs` proves the message, prompt, provider, model and response type that reached the action. The node output proves what the provider returned. Inspect both, and run the containing flow when the message reads upstream values or the flow's return value is part of the promise. Report a provider authentication rejection by connection and error code, never by echoing a credential.

package/skills-mcp/controllerai-data/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: controllerai-data
+description: Define Controller AI custom data types and read, write, import, promote and debug workflow records in the development and live stores. Use when a workflow needs durable state, a custom.* type, a collection, record reads or writes, a CSV import, workflowData expressions, or data moved between development and live.
+---
+<!-- generated from .claude/skills by cli/scripts/render-skills.mjs; edit the source -->
+
+# Data
+
+## Use this when
+
+- The user says store, save, log, record, track or remember with no external destination, or asks for a CRM-like backend, a tracker, a queue or a lookup table.
+- A flow must create, find, update or delete records, or a schema needs a new field, a relabel or a type change without losing rows.
+- A run works in a development test but a trigger or agent sees no data.
+
+Filtering records in expressions belongs to `controllerai-expressions`; configuring the native data nodes belongs to `controllerai-node-config`.
+
+## How it works
+
+**Type versus record.** A `custom.<name>` schema defines fields, and creating it makes a collection available. `custom.customer` is a shape, like an interface; `dataRecord.custom.customer` is a stored record of that shape with its identity (`id`, `createdAt`, `updatedAt`). Only real stored records satisfy a `dataRecord.*` input: a record fetched by a query, by `workflowData(...)` or returned by a native Create or Get. A `custom.*` value has no identity, and the identity paths resolve empty on it. In the app this is the "data record" checkbox on a flow input or a run-on-list item type: unchecked means data shaped like a customer, checked means a real stored customer. Users find that checkbox confusing; explain it in these terms.
+
+**Two stores.** Development and live hold separate rows. Publishing promotes the graph, props, expressions and schemas and creates the live collections; it never copies records and never touches existing live rows. Development runs, development trigger replays and an agent's Test conversations read the development store; published runs, ordinary live trigger dispatch and live agents read live. A flow that "works in the test but not for real" is often reading an empty live collection.
+
+**Native nodes.** The `registry_data` component provides Create, Get, Update, Update multiple and Delete record actions, so a flow owns its own persistence and deletion; the data commands here are for setup, seeding and debugging. Discover the current action keys instead of assuming them. A flow output is a return value, not persistence.
+
+**Update semantics.** The single Update node writes every enabled field that resolves to a value and keeps the other fields at their stored values, so enable only what should change; an enabled field that resolves to null or empty text overwrites the stored value, while one that resolves to nothing is left out. Update multiple takes `list.dataRecord.custom.<type>`, real records from a query or `workflowData(...)`, and runs as one transaction: a record that is missing, deleted since it was fetched, or from another collection fails the whole batch with zero changes to that collection; nodes that ran earlier in the flow keep their effects, so inspect the same-store records and those effects before any rerun the user asked for.
+
+**Field keys.** Direct writes use field IDs; query and get results and CSV columns use display names, plus `id`, `created time` and `updated time`. A query returns one page (`limit` up to 100, `offset`) plus `totalCount`, so a page is never the whole collection unless the count says so. Date fields take ISO-8601 text (`"2026-06-05"` or `"2026-06-05T12:30:00Z"`) in direct writes and CSV; a date-typed expression is accepted as it is; the reserved timestamps read as text and need `.toDate()` in expressions.
+
+**Schema changes never destroy rows.** Deleting a type deactivates its collection on the next saved state, and re-adding the same key reactivates it with every row. Removing a field hides its values; re-adding the same field ID exposes them again. Adding a field is additive and existing rows read it as null. Changing a field's type converts nothing: incompatible values read null and return when the type is restored, and the schema hash changes, which blocks copy-to-live until a publish syncs live. A schema update replaces the complete field list. Deleting a type also removes the fields on other types that referenced it; re-adding the type alone does not bring those fields back, while restoring an earlier workflow state restores every definition, never the records. The record store is not versioned and keeps whatever it holds now, so deleted records and overwritten values are gone for good.
+
+**Search.** The query's text search matches the serialized record and its metadata, not a field predicate; exact filtering happens in expressions.
+
+## Rules
+
+1. **Persisting in workflow data needs a schema and a create-record node.** A flow output or an AI structured result is not stored anywhere by itself; a named external destination is written through its integration.
+2. **Inspect existing schemas first and treat field IDs as contracts.** Relabel with `--display`; renaming the `custom.*` key or a field ID strands the stored values under the old key.
+3. **Read the whole schema before updating it, then read the echo.** The field list is replaced, not merged; disclose every removed field and confirm the persisted shape matches intent.
+4. **Never feed a query result into a direct create or update.** Its keys are display names; rebuild the fields object by write key and omit `id`, `createdAt` and `updatedAt`. The native Update, Update multiple and Delete nodes are the opposite case: they take the stored record itself.
+5. **Work on the store the request names; development is the default.** Before any live write, say that published and triggered runs read that store.
+6. **Record deletion and overwrites cannot be undone.** They need the user's explicit intent, and a schema mistake is never repaired with a broad delete; a schema mistake is repaired by restoring the key, the field ID or an earlier state.
+7. **A CSV commit is partial and additive.** It writes the valid rows, skips the invalid ones and appends on every run: run the dry run first, and commit only when it reports zero invalid rows, unless the user accepts a partial import.
+8. **Proof is a same-store read.** A query on the store the flow ran against proves persistence; a node's output alone does not.
+9. **Do not infer database guarantees.** Uniqueness, permissions, cascading deletes and concurrent business rules exist only when the flow implements them or the platform verifiably provides them.
+10. **Clean up only your own scratch schemas** from abandoned attempts, never a pre-existing user object.
+11. **A page is not the collection.** Read `totalCount` and page with the offset before calling a list complete, deduplicating or exporting.
+
+## Recipes
+
+### Define and inspect a type
+
+- `schema_type_list` — `all`, `workflowId`
+- `schema_type_get` — `name`, `workflowId`
+- `schema_type_create` — `name`, `display`, `field`, `fromJson`, `workflowId`
+- `schema_type_update` — `name`, `display`, `field`, `fromJson`, `workflowId`
+- `data_field_list` — `type`, `workflowId`
+
+`schema_type_create` takes `name` and either `field` as an array of `id:type[:display]` strings or `fromJson` as the full `{display, fields}` object; `schema_type_update` takes `name` and at least one of `display`, `field` (the complete replacement list) or `fromJson`. Creating the schema creates the collection; there is no separate collection tool. Deleting a type also removes fields on other types that referenced it.
+
+### Read and write records
+
+- `data_collection_list` — `env`, `workflowId`
+- `data_record_query` — `env`, `limit`, `offset`, `query`, `type`, `workflowId`
+- `data_record_get` — `recordId`, `env`, `type`, `workflowId`
+- `data_record_create` — `env`, `fields`, `type`, `workflowId`
+- `data_record_update` — `recordId`, `env`, `fields`, `type`, `workflowId`
+- `data_record_delete` — `recordId`, `env`, `type`, `workflowId`
+
+The update is a patch: omitted fields keep their values. A `get` of a missing record returns null rather than an error, because the two stores hold different rows. Live reads pass `env: "live"` on the same tools; `limit` and `offset` page a query. Every write requires an explicit `env`; reads default to `dev` when `env` is omitted.
+
+### Delete many
+
+- `data_record_delete_many` — `all`, `env`, `recordIds`, `type`, `workflowId`
+- `data_record_delete_many` — `all`, `env`, `recordIds`, `type`, `workflowId`
+
+Pass exactly one of `recordIds` or `all: true`; there is no confirmation parameter, which changes nothing about needing the user's intent.
+Soft deletes have no undo. On the live store the published workflow sees the change immediately.
+
+### Import a CSV
+
+- `data_record_import_commit` — `env`, `content`, `type`, `workflowId` / `data_record_import_validate` — `env`, `content`, `type`, `workflowId`
+- `data_record_import_commit` — `env`, `content`, `type`, `workflowId` / `data_record_import_validate` — `env`, `content`, `type`, `workflowId`
+
+The CSV travels inline as `content`; `data_record_import_validate` (`type`, `content`, `env`) is the dry run, and `data_record_import_commit` with the same arguments writes.
+Columns match display names, the opposite of a direct write. The dry run writes nothing on either store and reports valid and invalid rows; a live commit is visible to the published workflow at once. Read the result counts and query the imported rows on the same store.
+
+### Promote development data to live
+
+- `workflow_publish` — `acknowledgeDualDispatch`, `acknowledgeValidationErrors`, `name`, `workflowId`
+- `data_copy_to_live` — `type`, `workflowId`, `env`
+- `data_collection_list` — `env`, `workflowId`
+
+The live collection exists only after a publish, and a changed schema needs a new publish before copying. Copy upserts by record key: live-only rows stay, a live row with the same key is overwritten with the development value, and a deleted live row with that key comes back. Read both collections before an authorized copy, then report `createdCount`, `updatedCount` and the live total.
+`data_copy_to_live` takes `type` and the acknowledgement `env: "live"`.
+
+### Build a data backend
+
+For a CRM, tracker or lookup table that flows and agents will call: define each entity's schema with stable field IDs, a status or archive field and record references for relationships; give each flow one operation with an explicit result for invalid input, a missing record and a duplicate key (an empty record is not success); let Create validate references before writing, Get select by ID, Update fetch then patch only the requested fields, Delete follow the chosen relationship policy, and Search return the matches with the count and page; then test create, get, search, update, get, delete and a missing get, plus a duplicate key, a bad reference, an omitted filter, an empty result, a zero or false value and a page boundary. Uniqueness and concurrency exist only where a flow enforces them.
+
+### Diagnose development versus live
+
+- `data_collection_list` — `env`, `workflowId`
+- `data_collection_list` — `env`, `workflowId`
+- `data_record_query` — `env`, `limit`, `offset`, `query`, `type`, `workflowId`
+
+A live store with no collections usually means no publish since a store-eligible schema existed; an empty live collection next to a populated development one usually means the data was never promoted or was cleared since. Confirm with the publish status, the live schema and the record history before prescribing a copy. Different row counts between the stores are normal until data is written or copied on each.
+
+## Verify
+
+- `schema_type_get` — `name`, `workflowId`
+- `data_record_query` — `env`, `limit`, `offset`, `query`, `type`, `workflowId`
+- `workflow_validate` — `workflowId`
+
+The schema readback shows the intended key, display, complete field list and types; a same-store query shows the expected records with the right field values; expressions that reference the schema still compile; and for a live request, the live collection holds the promised rows.
+
+## Report
+
+Which types and fields exist, which store holds which rows and how many, any field you removed or type you changed, and what remains for the user: an unpublished schema, an empty live collection, or a production write you did not perform.
+
+Read [references/data-rails.md](references/data-rails.md) before a schema rewrite, a deletion, an import or a copy-to-live: what publishing copies, the safe schema-change sequence, and the destructive operations.

package/skills-mcp/controllerai-data/references/data-rails.md

@@ -0,0 +1,45 @@
+<!-- generated from .claude/skills by cli/scripts/render-skills.mjs; edit the source -->
+# Data rails and safety
+
+## What publishing copies
+
+| Asset | Workflow publish |
+| --- | --- |
+| Graph, props, expressions, schemas | Promoted to live; live collections are created or synced |
+| Development records | Never copied |
+| Existing live records | Untouched |
+
+Records reach live only through an explicit copy-to-live, a live import, a live write, or the published workflow's own runs.
+
+## Safe schema change
+
+1. Read the current schema and note every field ID and type.
+2. Search the workflow's expressions and node props for references to the fields you will change.
+3. Prepare the complete replacement field list; the update replaces the list.
+4. Name the fields that will be removed, renamed or retyped, and what their stored values will do: hidden until the same ID returns, null until the same type returns.
+5. Update, then read the persisted echo and compare it with the intent.
+6. Re-read the expression contexts that referenced the schema and rerun the stateful flows.
+
+Prefer a display change over an ID change. A new field ID is a new field: the old values stay under the old ID.
+
+## Destructive operations
+
+- A record delete is a soft delete with no undo.
+- A bulk delete of every record removes the whole collection's rows on the chosen store; on live the published workflow sees it immediately.
+- An update overwrites the stored value; on the single Update node every enabled field that resolves to a value is written, including one that resolves to empty text or null.
+- A CSV commit appends the valid rows and skips the invalid ones; re-running a commit appends again.
+- Deleting a type deactivates its collection (re-adding the key reactivates it) and removes the fields on other types that referenced it; re-adding the type does not restore those fields, restoring an earlier workflow state does.
+- Copy-to-live upserts development rows into production by record key: live-only rows stay, matching keys are overwritten, deleted matching keys are restored.
+
+Resolve the exact workflow, store, type and records before any of these. A schema mistake is fixed by restoring the key or the field ID, never by deleting data.
+
+## Development versus live diagnosis
+
+If a manual run passes but a trigger or agent tool does not, compare the two stores:
+
+- `data_collection_list` — `env`, `workflowId`
+- `data_collection_list` — `env`, `workflowId`
+- `data_record_query` — `env`, `limit`, `offset`, `query`, `type`, `workflowId`
+- `data_record_query` — `env`, `limit`, `offset`, `query`, `type`, `workflowId`
+
+No live collections usually means no publish since a store-eligible schema existed. An empty live collection with a populated development one usually means the data was never promoted or was cleared since. Confirm with publish status, the live schema and record history; different counts are normal until data is intentionally written on both stores.

package/skills-mcp/controllerai-expressions/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: controllerai-expressions
+description: Author, validate, persist, and debug Controller AI expressions for node props and conditions. Use when a value comes from a flow input, an upstream node, a loop item, workflow data, a constant, a calculation, a template or a boolean rule, and when an expression compiles but resolves to null or the wrong input.
+---
+<!-- generated from .claude/skills by cli/scripts/render-skills.mjs; edit the source -->
+
+# Expressions
+
+## Use this when
+
+- A node prop or condition needs a dynamic value: a flow input, a wired upstream output, the current loop item, workflow records, a date calculation, a text template, a boolean guard.
+- An expression compiles but the run shows null, an empty value, or the wrong source.
+
+Node discovery, connections and static props belong to `controllerai-node-config`; Router, If/Else and loop structure to `controllerai-flow-control`; execution evidence to `controllerai-runs`.
+
+## How it works
+
+Expressions are written in a restricted JavaScript-like language and compiled into the engine's expression tree. It is not JavaScript: no loops, assignments, `new`, regular expressions, optional chaining, object literals (the `{ ignoreEmptyConstraints: true }` filter options object is the one accepted object) or library methods beyond what the compiler catalog advertises. A program is optional `const` declarations followed by one final expression.
+
+**Everything is typed.** An expression can only be written against a known type. An integration node's output type is usually learned from a representative development run, or from a supported output selector or a declared provider sample, and `node status` says which route applies; `custom.*` types describe data-store records and AI structured outputs; `dataRecord.custom.x` is a stored record of that shape with its identity (`id`, `createdAt`, `updatedAt`), while bare `custom.x` is the shape alone; `list.` prefixes a list of any type. When an expression cannot be authored, the cause is usually a missing upstream type.
+
+**Scope** comes from the destination's expression context: `flow.<name>` is a flow input, `inputs.<name>` a wired node input (usually already unwrapped), `item` the current loop item where the context exposes it, `workflowData("custom.type")` the records of an active collection on the current rail, and `now` and `isLiveVersion` constants. Bindings are display-derived and de-duplicated by the context; display labels and old spellings are not bindings.
+
+**Empty values.** An omitted input arrives in its typed empty form: `""` for text, null for objects, and it is compared like any other value: `=== ""` matches only rows whose field is empty, `!==` passes every other row including rows with a missing value, `includes("")` matches every text row, and a negative membership check against a missing list passes everything. An omitted optional input therefore does not close a filter by itself: equality usually returns nothing, a negation or containment returns everything, and an omitted lookup key can turn a create-if-missing step into a duplicate. With `ignoreEmptyConstraints` on, a constraint whose value is null, empty text or an empty list is skipped; `0`, `false`, whitespace and dates stay real constraints. `.every()` takes the same predicates as `.filter()` and compiles to a single-pass "all match"; a constraint on a field the item does not have compiles, makes `.every()` false and is dropped by `.filter()`, which then matches every item. Predicates compare a field of the item, so a list of numbers or text cannot be filtered by its values: count or classify primitives with a per-item loop that returns a flag, then sum the flags. Comparators decide what missing, null or unparseable values do, and negative comparisons can pass rows with missing values, so a guard states presence explicitly.
+
+**Dates** travel as ISO-8601 text. A `date`-typed input or field takes date operations directly; text needs `.toDate()` first, and epoch text needs an explicit unit, `.toDate("epoch_seconds")` or `.toDate("epoch_millis")`. Format with Moment tokens such as `format("YYYY-MM-DD")`.
+
+**Templates and ternaries.** A backtick template with `${...}` returns text; keep non-text values as direct typed expressions. A ternary keeps its type when both branches are numbers or both are booleans; any other pair renders as text, so give both branches the same type when a number or boolean is needed, and never quote or coerce a branch to hide a type mismatch.
+
+**Channels.** A literal value and an expression are stored on different channels; the setters pick the channel from the prop's metadata. On a value-channel text array, a scalar expression replaces the whole array with one dynamic element and a list expression is rejected; a static list is written as a literal array, and a list expression only where the prop exposes whole-array expression mode.
+
+## Rules
+
+1. **Wire first, then read the context, then write.** An upstream output listed under `unwiredUpstreamOutputs` is discovery, not scope. Re-read the context after rewiring, renaming an input, changing a schema, changing a dynamic selector, or resolving an output type.
+2. **Copy bindings exactly.** Never derive one from a label, never add `.data` on your own, and when a diagnostic advertises a typeable accessor, use it. For duplicate names, use the de-duplicated binding, input ID and source node the context gives.
+3. **Use only advertised operations.** Read the catalog for the type; never author a raw expression tree or probe a private API. When an idiom is rejected, use the advertised alternative, or express the logic through routing, typed inputs or a native action.
+4. **A literal is a literal.** `flow.name`, `{{name}}` and `${name}` inside a literal stay text. Dynamic values go through the expression setter.
+5. **Preserve `0` and `false`.** Fallbacks are same-type literals (`flow.count ?? 0`, `flow.enabled ?? false`) and never swallow a real zero or false.
+6. **Optional filters are a decision, not a default.** An omitted value is a real comparison, not a skipped constraint; turn on `ignoreEmptyConstraints` only when omitting that constraint is what the user wants, and test both the supplied and the omitted case.
+7. **Compiler success proves syntax and types, not the source.** When names are ambiguous, check the source node and input IDs, then look at runtime values.
+8. **An expression that reads `inputs.<name>` is verified only by running the containing flow.** A node run never executes upstream nodes.
+9. **Empty results need a reason.** An intentional empty (a closed filter, an absent optional) is valid; an unexpected null or partial value in `resolvedConfigs` is a failure to trace, not something to fix by rewriting valid syntax.
+
+## Recipes
+
+### Discover the scope and the operations
+
+- `expr_context` — `nodeId`, `methods`, `prop`, `workflowId`
+- `expr_operation_list` — `type`, `workflowId`
+
+`expr_context` and `expr_operation_list` take an explicit `workflowId`; the catalog needs a workflow with at least one node.
+
+If the source is not wired yet:
+
+- `node_connect` — `flow`, `from`, `output`, `to`, `workflowId`
+
+Router and If/Else outputs connect through `branch_connect`.
+
+### Validate, write, read back
+
+- `expr_validate` — `nodeId`, `js`, `mode`, `prop`, `workflowId`
+- `node_prop_set` — `nodeId`, `js`, `label`, `prop`, `rawExpressionJson`, `value`, `workflowId`, `valueJson`
+- `expr_decompile` — `nodeId`, `prop`, `workflowId`
+
+The setter fetches the prop's metadata, enables a catalog-only optional prop when needed, compiles, writes the right channel and verifies the readback. If the write fails after enabling, the prop stays enabled: disable it with `node_optional_prop_set` and re-read. Decompile returns the stored source and channel, not a type: validate the decompiled source against the current destination to confirm the type still holds.
+
+`node_prop_set` is the single setter: for expression authoring pass `js` alone (it accepts exactly one of `value`, `valueJson`, `js` or `rawExpressionJson`; the raw form round-trips a compiled tree and is not for authoring), inline (there is no file or stdin). Disable a wrongly enabled optional prop with `node_optional_prop_set` and `enabled: false`.
+
+### Conditions
+
+- `expr_validate` — `nodeId`, `js`, `mode`, `prop`, `workflowId`
+- `node_only_when_set` — `nodeId`, `clear`, `groups`, `js`, `workflowId`
+- `node_only_when_set` — `nodeId`, `clear`, `groups`, `js`, `workflowId`
+- `branch_update` — `nodeId`, `conditionJson`, `js`, `name`, `branchId`, `workflowId`
+
+A node guard takes one boolean expression, or groups where each inner list is AND and the outer list is OR; a root `&&` or `||` inside one expression is not supported, so compound guards use groups. Branch conditions use the same grouped shape, each string compiled separately. Make a missing number fail a comparison with a same-type boundary: `(flow.unitsLeft ?? 5) < 5`.
+
+`expr_validate` takes `mode: "onlyWhen"` and no `prop`; `node_only_when_set` takes `js` or `groups` as the nested string arrays above; `branch_update` takes `conditionJson` in the same shape.
+
+### Prove the value at runtime
+
+- `run_node` — `nodeId`, `inputs`, `waitSeconds`, `workflowId`
+- `run_flow` — `flowId`, `confirmLive`, `inputs`, `target`, `waitSeconds`, `workflowId`
+- `execution_node_get` — `nodeExecutionId`, `full`, `workflowId`
+
+`run_node` and `run_flow` take the parsed `inputs` and `waitSeconds` (default 60, maximum 120); `execution_node_get` with `full: true` returns the untruncated result.
+
+The node run isolates the destination's own configuration. The flow run proves an upstream-derived value. Inspect `runScope` and `resolvedConfigs`; when a search unexpectedly returns nothing, look at the resolved comparison values first.
+
+## Verify
+
+The current context shows the intended source IDs and bindings; the decompiled source validates against the current destination; the run's `resolvedConfigs` hold the intended value, with intentional empties explained; the edge cases the task implies were exercised: omitted input, `0`, `false`, empty text or list, missing record.
+
+## Report
+
+Which values are dynamic and what they read from, any optional-filter or fallback decision you made, and what the run showed.
+
+Read [references/dsl-and-recipes.md](references/dsl-and-recipes.md) for the canonical patterns: templates, prefix tests, HTTP JSON bodies, fallbacks, dates, workflow records, optional filters, loop items and outputs, and the troubleshooting order.

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

@@ -0,0 +1,136 @@
+<!-- generated from .claude/skills by cli/scripts/render-skills.mjs; edit the source -->
+# Expression DSL and recipes
+
+The live compiler, `expr_context` and `expr_operation_list` are authoritative. These examples show structure; take every binding, field and operation name from the context.
+
+## Text template
+
+```js
+`Hello ${flow.firstName.trim()}, order ${inputs.order.id} is ready`
+```
+
+## Text prefix
+
+When `.startsWith()` is not advertised, test a prefix with a guarded split:
+
+```js
+flow.subject.isNotEmpty() ? flow.subject.split("urgent")[0] === "" : false
+```
+
+The guard keeps empty text from matching. Prefix matching is not first-word matching: do not split on whitespace unless first-word equality is the requirement, and test a value with punctuation right after the prefix (`urgent-alpha`) plus a near miss.
+
+## HTTP JSON body
+
+A JSON body prop is JSON text. The language has no constructed object literals and no `JSON.stringify`, so build the document as a template of complete JSON tokens:
+
+```js
+`{"message":${flow.name.jsonEncode()},"payload":${flow.user.stringify()}}`
+```
+
+`.jsonEncode()` returns a JSON-safe token: quoted for text, bare `true`/`false` for a boolean, so never add a second pair of quotes. `.stringify()` serializes a custom object or list. Keep the JSON punctuation outside the interpolations and validate against the exact body prop before writing.
+
+## Same-type fallback
+
+```js
+flow.count ?? 0
+flow.label ?? "unknown"
+flow.enabled ?? false
+```
+
+`0` and `false` are values; a fallback never replaces them.
+
+## Boolean condition
+
+```js
+flow.email.isNotEmpty()
+inputs.score >= 80
+```
+
+Validate a condition with `expr_validate`, `mode: "onlyWhen"` and no `prop`.
+
+## Dates
+
+```js
+inputs.createdAt.toDate() > now.plusDays(-7)
+inputs.createdAt.toDate().format("YYYY-MM-DD")
+```
+
+Convert text to a date before date math; a negative amount moves backward. Use Moment format tokens, never JavaScript `Date` constructors or getters.
+
+## Workflow records
+
+Filter immediately after `workflowData` so supported predicates are pushed into storage, then sort by an advertised field:
+
+```js
+workflowData("custom.lead")
+  .filter(row => row.status === "active")
+  .sortBy("createdAt", "desc")
+```
+
+The collection must exist on the current rail; a schema declaration alone does not put rows in it. Record identity fields are `id`, `createdAt`, `updatedAt`.
+
+## Optional filter inputs
+
+An empty right-hand value is a real comparison: equality matches only empty fields, a negation or containment matches every row. Skip an omitted constraint only when the requirement allows it:
+
+```js
+workflowData("custom.lead").filter(
+  row => row.ownerId === flow.ownerId,
+  { ignoreEmptyConstraints: true }
+)
+```
+
+With the option on, null, empty text and an empty list skip the constraint; `0`, `false`, whitespace and dates remain real constraints. Test the supplied and the omitted case.
+
+## List membership
+
+For a list field such as tags, membership is a single element: `row.tags.includes(flow.tag)`. `filter`, `some`, `find` and `every` share the same predicate grammar; `map` projects fields rather than building objects.
+
+## Primitive lists
+
+A predicate compares a field of the item, so `flow.weights.filter(w => w >= flow.threshold)` is rejected, and `w.value` on a number compiles as a missing field whose constraint is dropped, matching every item. Aggregate a primitive list with the advertised list operations (`.sum()`, `.count()`, `.max()`), and classify or count its items with a per-item loop whose body returns a flag:
+
+```js
+inputs.runFlowOnList.filter(row => row.status === "completed").map(row => row.outputs).map(row => row.heavyFlag).sum()
+```
+
+`.map()` picks one field per call, so nested picks are chained; the `status` filter keeps failed iterations out of the total.
+
+## Loop item
+
+Where the context exposes `item`, a primitive list uses it directly:
+
+```js
+item
+```
+
+An object list uses an advertised field:
+
+```js
+item.email
+```
+
+Inside the child flow the item arrives as a flow input and is `flow.<name>`, never `item`. A root routing node can read flow inputs directly; no producer node is needed to expose them.
+
+## Loop output
+
+Run-on-list output is a list of iteration records; child outputs sit under `outputs`:
+
+```js
+inputs.enrichEach[0].outputs.score
+```
+
+Confirm the binding and the path in the context.
+
+## Troubleshooting order
+
+1. `expr_context`
+2. Confirm the intended source is wired and its `sourceNodeId` is right.
+3. `expr_validate`
+4. `node_prop_set`
+5. `expr_decompile`
+6. `run_node` for the destination alone
+7. `run_flow` when the expression consumes a wired input
+8. `execution_node_get`
+
+If compilation succeeds but the runtime value is empty or partial, inspect `runScope`, the actual input value and `resolvedConfigs` before touching the syntax again. A node-only run cannot prove an `inputs.<name>` binding because it does not execute upstream nodes.

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

@@ -0,0 +1,114 @@
+---
+name: controllerai-flow-control
+description: Design and configure Controller AI execution paths with only-when guards, If/Else branches, Router routes, for-each loops, subflows, Join Paths and error handling. Use when work must skip, branch, fan out, iterate over a list, call another flow, converge, return a value, or continue after a failure without changing the user's intended semantics.
+---
+<!-- generated from .claude/skills by cli/scripts/render-skills.mjs; edit the source -->
+
+# Flow control
+
+## Use this when
+
+- A flow must skip an action, choose one path, run every matching path, repeat work per item, call another flow, converge exclusive paths, return a value, or continue after a failure.
+- A run shows an unexpected skip, a branch that never fires, an empty return, or a loop that stops early.
+
+Conditions are written with the expression discipline in `controllerai-expressions`; components are found and configured with `controllerai-node-config`; runs are read with `controllerai-runs`.
+
+## How it works
+
+| Intent | Primitive | Runtime semantics |
+| --- | --- | --- |
+| Skip one action when a condition is false | node `only-when` | No alternate path; the node records `only_when_false`, downstream stays eligible |
+| Choose exactly one path | If/Else | The first matching branch runs; Else is the mandatory last fallback |
+| Run every matching path | Router | Conditions are independent; every matching route runs, possibly several |
+| Do work for every list item | `flow for-each` loop | A typed body flow runs once per item, sequentially, under an item cap |
+| Reuse a typed unit of work once | Run flow (subflow) | Explicit input and output mapping to another flow's contract |
+| Continue after a failed action | continue-on-error / Error output | The error is captured, downstream sees null for that node, the run ends `completed_with_error` |
+| One action after whichever exclusive path ran | Join Paths (`registry_flow-merge`) | `chooseActivePath` passes the single active input's value on; `passThrough` returns one field per connected input (blocked ones null) and suits fan-out that can overlap |
+| Give a flow its return value | Return response (`registry_flow-return-response`) | Maps producer values into the declared outputs; without it an otherwise successful flow returns empty outputs |
+
+Skip reasons are the evidence: a false guard records `only_when_false`; a node on an untaken branch or an unmatched route records `upstream_skipped`. Choose the primitive by the semantics the caller and the tests need, never because a component was easier to find.
+
+A fresh If/Else ships with one blank `If` branch and an Else; the blank condition is a validation blocker until it is set. Router routes cannot be reordered because every match runs. Loops run sequentially with a cap that defaults to 500 items (1 to 10000); a list over the cap fails before any iteration, never truncates. `continueOnIterationError` on a loop node continues past a failed child iteration and cannot help when the list or mapping expression fails before any child starts; node-level continue-on-error on the loop node lets the parent flow continue past that failed loop with a null output, but repairs nothing and resumes no iteration. With `chooseActivePath`, zero active inputs stop the flow at the join unless `continueIfNoActivePath` is enabled, which passes null on. Setting a subflow's target synthesizes mapping props from the target's current inputs; when those inputs change, set the target again and remap. Deleting a flow removes its graph, contract, triggers and caller links; turning continue-on-error off deletes the node's Error output and its edges.
+
+## Rules
+
+1. **Guard the action that must skip with `only-when`; do not replace a node skip with If/Else.** A false guard does not stop downstream execution (the skipped node just yields no value), so guard downstream separately or branch when it must skip too.
+2. **Never invent a missing condition** from names, sample values or one observed run. Leave the branch blank, report the blocker and ask; a missing business rule is not yours to guess.
+3. **Update the blank default If branch before adding another branch.** Adding beside it leaves a blocker and a duplicate.
+4. **Order is behavior only for If/Else.** Put the most specific condition first, never write a complement condition for Else, and never simulate Router order by deleting routes or chaining descendants; leave a fan-out unchanged unless the user authorizes a redesign.
+5. **Build per-item work with `flow for-each`**, never by hand-assembling the injection and mapping pattern. Put the real work in the generated body flow and declare its outputs before consuming aggregate results. Continue past failed iterations only when partial completion is acceptable and the downstream logic handles failed iteration records.
+6. **Compound guards are supported**: a node guard takes one boolean expression or grouped conditions (inner list AND, outer list OR); a root `&&` or `||` inside one expression is not. Never weaken a rule to fit the grammar, and never probe a private API.
+7. **Fail missing comparisons closed** with a same-type boundary (`(flow.unitsLeft ?? 5) < 5`), and keep money paths blocking: charges, purchases, transfers and refunds never continue on error, and never enable continue-on-error just to make a run green.
+8. **Converge exclusive paths through Join Paths**; never wire several branches straight into an ordinary node and never duplicate the shared action.
+9. **A flow that returns data needs a Return response node** bound to declared outputs. Every Return writes every declared output, unbound ones as null, and a later Return (in execution order) overwrites an earlier one, so a partial Return can erase a value; design one Return per path unless merging is intended.
+10. **Read the branch list after every edit.** Warnings about missing conditions or unwired paths are blockers even when a run looks green.
+
+## Recipes
+
+### Guard one action
+
+- `expr_context` — `nodeId`, `methods`, `prop`, `workflowId`
+- `expr_validate` — `nodeId`, `js`, `mode`, `prop`, `workflowId`
+- `node_only_when_set` — `nodeId`, `clear`, `groups`, `js`, `workflowId`
+- `node_only_when_set` — `nodeId`, `clear`, `groups`, `js`, `workflowId`
+
+`expr_validate` takes `mode: "onlyWhen"` and no `prop`. `node_only_when_set` takes `js` for one expression or `groups` as the parsed arrays, for example `groups: [["flow.email.isNotEmpty()", "flow.units < 5"], ["flow.override === true"]]`; pass `clear: true` only when removing the guard is the user's intent.
+
+### If/Else and Router
+
+- `branch_list` — `nodeId`, `workflowId`
+- `branch_update` — `nodeId`, `conditionJson`, `js`, `name`, `branchId`, `workflowId`
+- `branch_add` — `nodeId`, `allowDuplicate`, `conditionJson`, `js`, `name`, `workflowId`
+- `branch_update` — `nodeId`, `conditionJson`, `js`, `name`, `branchId`, `workflowId`
+- `branch_connect` — `nodeId`, `flow`, `branchId`, `to`, `workflowId`
+- `branch_reorder` — `nodeId`, `order`, `workflowId`
+
+Find the control component with `controllerai-node-config`, then read the branch IDs. Grouped conditions are OR of AND rows, each string compiled separately. Add an If branch only for another non-Else case; add a Router route for each intended independent match. Reorder lists every condition branch exactly once and omits Else, which stays last. Wire every returned route ID explicitly.
+
+`branch_update` and `branch_add` take `js` or `conditionJson` as the parsed arrays (`conditionJson: [["flow.email.isNotEmpty()", "flow.units < 5"], ["flow.override === true"]]`) with `branchId` for the route; `branch_connect` takes `branchId`, `to` and `flow`; `branch_reorder` takes `order` as the array of condition IDs.
+
+### Loop over a list
+
+- `node_get` — `nodeId`, `workflowId`
+- `flow_for_each_scaffold` — `continueOnError`, `flow`, `from`, `itemField`, `itemName`, `itemType`, `listField`, `listJs`, `maxItems`, `name`, `sourceOutput`, `workflowId`
+- `node_prop_set` — `nodeId`, `js`, `label`, `prop`, `rawExpressionJson`, `value`, `workflowId`, `valueJson`
+- `node_prop_set` — `nodeId`, `js`, `label`, `prop`, `rawExpressionJson`, `value`, `workflowId`, `valueJson`
+
+`sourceOutput` is the exact `outputs[].id` of the selected node, never a display name, and there is no first-output default (branch and error outputs included). When the whole output is the list, omit the list selectors; for a nested list pass `listField` with the dot path below `.data`; reserve `listJs` for an exact advanced expression whose shape you took from the context; the two are mutually exclusive. `itemField` (an array of `id:type[:display]` strings) is only for creating a new `custom.*` item type; stored records use `dataRecord.custom.*`. Set `maxItems` on purpose when the requirement differs from 500, decide `continueOnError` explicitly, then read the returned warnings and follow `nextSteps` in order; a list/item type mismatch means created but unverified. In mappings, `item` exists only where the context exposes it; inside the body flow the item is `flow.<itemInput>`; aggregate results are iteration records with child outputs under `outputs`.
+
+`flow_for_each_scaffold` takes `listField` or `listJs` inline; the server reads no local file. Later changes go through `node_prop_set` on the loop node: `prop: "maxItems"` with a number, or `prop: "continueOnIterationError"` with `value: true`.
+
+### Call another flow
+
+- `node_subflow_set` — `nodeId`, `flow`, `workflowId`
+- `node_prop_list` — `nodeId`, `workflowId`
+
+Define the called flow's inputs and outputs first, add the Run flow component, set the target, then bind the generated mapping props with expressions.
+
+### Converge, return, handle errors
+
+- `node_add` — `after`, `connection`, `enableProp`, `flow`, `key`, `name`, `node`, `output`, `props`, `workflowId`
+- `node_prop_set` — `nodeId`, `js`, `label`, `prop`, `rawExpressionJson`, `value`, `workflowId`, `valueJson`
+- `flow_output_add` — `flowId`, `description`, `display`, `name`, `type`, `workflowId`
+- `node_add` — `after`, `connection`, `enableProp`, `flow`, `key`, `name`, `node`, `output`, `props`, `workflowId`
+- `node_continue_on_error_set` — `nodeId`, `enabled`, `workflowId`
+- `node_connect` — `flow`, `from`, `output`, `to`, `workflowId`
+
+Join Paths: connect every type-compatible branch tail to it (all connected input types are checked, inactive paths included, which is why `pathDataType` is asked for once `chooseActivePath` reveals it), set `pathDataType` from the returned options, and place the shared action after it (`after: "<joinNodeId>"`, or connect the existing action). Return: declare the output first so its generated prop exists, add the exact component after the producer, then bind the prop through the expression setter. Error output wiring is optional; add it only when a failure needs explicit handling.
+
+`node_add` takes `node: "registry_flow"`, `key: "registry_flow-merge"` (or `"registry_flow-return-response"`), `name` and `after`; `node_prop_set` sets `prop: "mode"`, `value: "chooseActivePath"` and `prop: "pathDataType"`; `node_continue_on_error_set` takes `enabled: true`; `node_connect` takes `output: "error"` for the error path.
+
+## Verify
+
+- `branch_list` — `nodeId`, `workflowId`
+- `workflow_validate` — `workflowId`
+- `run_flow` — `flowId`, `confirmLive`, `inputs`, `target`, `waitSeconds`, `workflowId`
+- `execution_tree` — `workflowExecutionId`, `cursor`, `flowId`, `limit`, `status`, `workflowId`
+
+Every branch has its intended condition and a wired target; If/Else order matches priority with Else last; Router fan-out is intentional where more than one condition can be true; the loop's item type and list expression compile against real data; the paths the task implies ran: true, false or Else, empty list, one item, several, over the cap, and the intended error path; the execution tree explains every `only_when_false` and `upstream_skipped` and shows no unexplained missing node; a loop's outer success is not proof for every item, so inspect iteration records and surface individual failures.
+
+## Report
+
+Which primitive carries each decision and why, the tested paths with their outcomes, any rule you could not set because the business rule was missing, and any error-continuation you enabled and where.
+
+Read [references/patterns.md](references/patterns.md) for the canonical shapes: guard, exclusive decision, fan-out, grouped conditions, per-item subflow, convergence, return, error path.