@controllerai/cli 0.2.17 → 0.2.20

package/skills/controllerai-data/SKILL.md

@@ -1,184 +1,59 @@
 ---
 name: controllerai-data
-description: Define Controller AI custom data types and safely read, write, import, copy, and debug workflow records across development and live stores. Use when a workflow needs durable state, custom structured types, collections, record queries, CSV import, workflowData expressions, or data migration between dev and live.
+description: Build durable application state in Controller AI workflow data stores: schemas, record identity, CRUD flows, search, partial updates, relationships, imports and development/live data. Use for CRM backends, trackers, data APIs and persistence.
 ---
 
-# Controller AI data
+# Workflow data as an application backend
 
-The `cai ...` examples are canonical grammar. Use the transport selected in `controllerai-start` and its MCP tool map; never mix transports in one task.
+Each workflow can own custom schemas and durable collections. Its flows share those collections, so an agent can use a set of flows as a CRM or application API. Creating a schema makes the collection available; creating a flow output only returns a value and does not store it.
 
-Controller AI has two separate concerns:
+`custom.contact` describes a shape. `dataRecord.custom.contact` is a stored record of that shape, including `id`, `createdAt` and `updatedAt`. Lists of fetched records preserve identity. Use real fetched records as inputs to native Get/Update/Delete actions; an object that merely looks like a contact does not prove record identity.
 
-- 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.
+## What is available
 
-## Rules that break tasks when skipped
+- Native Create, Get, Update, Update Multiple and Delete data-record actions.
+- `workflowData("custom.contact")` expressions for query/filter/sort/count and selecting records.
+- Typed record relationships, separate dev/live records, schema changes, CSV import validation/commit, and explicit copy-to-live.
+- MCP data tools for inspecting, creating, querying, patching and deleting records during setup or debugging. Native workflow nodes provide the reusable capability an agent calls later.
 
-- 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.
+Discover the current `registry_data` action keys and schemas. Do not infer unsupported database guarantees: unique business keys, permissions, relationship deletion policy and concurrent business rules need deliberate application logic or verified platform support.
 
-## A type vs a stored record
+## Recipe: CRM flows for an agent
 
-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.
+1. Create schemas with stable field IDs: companies, contacts, deals and activities. Use fields for business data, record references for relationships where appropriate, and a clear status/archive policy.
+2. Define create/get/update/delete/search flow contracts per entity. Include useful descriptions and explicit results for invalid inputs, missing records and duplicate business keys. Do not make an empty record look like success.
+3. Create validates input and referenced records before writing. Get selects by record ID. Update fetches the record and patches only requested fields. Delete applies the chosen relationship policy. Search returns matching records and count/page information.
+4. Add useful composite reads such as “contact plus company, deals and activity history.” Prefer explicit projections over large unbounded record graphs.
+5. Test create → get → search → update → get → delete → missing get. Also test duplicate keys, invalid references, omitted filters, empty matches, zero/false values, list membership, clearing a field and page boundaries.
+6. Attach each tested flow as an agent tool when a conversational CRM agent is requested.
 
-`custom.customer` and `dataRecord.custom.customer` are different things, and the difference carries through everything:
+## Search expressions
 
-- `custom.customer` is the TYPE — the shape, like a TypeScript interface. A value of this type is just data in that shape.
-- `dataRecord.custom.customer` is an ACTUAL STORED RECORD of that shape — the same fields plus record identity (`id`, `createdAt`, `updatedAt`) proving it lives in the collection.
+Use current `expr_context` bindings. Typical sources and operations:
 
-In the product UI this appears as the "data record" checkbox when selecting a type for a flow input or run-subflow-on-list: unchecked means "data shaped like a customer", checked means "a real stored customer record". Users find this checkbox confusing — be ready to explain it in these terms.
-
-Consequences:
-
-- Only real records satisfy a `dataRecord.*` input. An expression that CONSTRUCTS record-shaped objects (e.g. a `.map()` that builds new objects) produces `custom.*`-shaped values with no identity — pass fetched records through instead.
-- Record metadata (`id`, `createdAt`) exists only on `dataRecord.*` values; on plain `custom.*` values those paths resolve empty.
-
-## Data nodes: update semantics
-
-- "Update multiple data records" takes an expression typed `list.dataRecord.custom.<type>` — real stored records passed through from a query or `workflowData(...)`. The batch is ONE transaction: if any resolved record is stale (deleted since fetched) or foreign to the collection, the node errors and NOTHING updates. A failed run therefore means zero changes — fix and rerun safely.
-- On the single-record "Update data" node, every ENABLED field is written. Enable only the fields you intend to change; disabled fields keep their stored values.
-
-## Define a schema deliberately
-
-Inspect existing types first:
-
-```bash
-cai schema list --json
-cai schema get custom.<name> --json
-```
-
-Create a type with stable field IDs:
-
-```bash
-cai schema create custom.customer \
-  --display "Customer" \
-  --field email:text:"Email" \
-  --field score:number:"Score" \
-  --json
-```
-
-Creating the schema creates/synchronizes its collection. `cai data collection create` is only an alias for schema creation.
-
-MCP: `cai data collection create` is merged into `schema_type_create`.
-
-`schema update --field` replaces the complete field list; it does not append — this is deliberate, so a subset CAN intentionally replace the whole schema. Read the current schema, preserve intended fields, and disclose any removals. The transport response warns about every field being dropped and echoes back the COMPLETE stored shape after the write — always read that echo and confirm it matches intent. Deleting a schema hides its collection and records and breaks dependent expressions — tell the user, and know it is recoverable (see below).
-
-## How schema changes affect stored records
-
-Schema changes never hard-delete data. There is no delete path for records in schema sync — everything is deactivation and hiding:
-
-- Delete a type → its collection goes INACTIVE on the next saved state; every record row survives. Re-add the same `custom.*` key and the same collection reactivates with all records intact.
-- Delete a field → its values stay inside each record, unaddressable. Re-add the SAME field id and the old values reappear.
-- Add a field → purely additive; existing records read the new field as null.
-- Change a field's type → values are never converted or erased; incompatible values read as null and return if the type is changed back. The schema hash changes, which blocks copy-to-live until dev and live match again.
-- Publish applies the same deactivate/reactivate logic to live. Live records are hidden, never deleted.
-- Restoring an older workflow state rolls back the DEFINITION (graph and schemas), never the data. The record store is not versioned and only moves forward: a deleted type reactivates with whatever the store holds NOW — records created, edited, or soft-deleted after the restored state stay exactly as they are. Restore is not a data snapshot.
-
-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.
-
-Relabel a type without changing its stable key:
-
-```bash
-cai schema update custom.customer --display "Customers" --json
+```javascript
+workflowData("custom.contact").filter(r => r.id === flow.recordId).first()
+workflowData("custom.contact").filter(r => r.owner === flow.owner, { ignoreEmptyConstraints: true })
+workflowData("custom.contact").filter(r => r.tags.includes(flow.tag))
+workflowData("custom.contact").skip(flow.offset).take(flow.limit)
 ```
 
-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.
+`ignoreEmptyConstraints` skips absent values, empty text and empty lists. `false` and `0` remain actual filter values. Without the option, an empty value remains a real comparison. List `.includes(value)` takes an **element**, not a list of elements. A text `.includes` is case-sensitive; for case-insensitive search, store normalized search text and normalize the query before comparing. Test the exact filter against representative rows.
 
-## Respect field-key asymmetry
+Use `.take(n)` for a count and `.skip(n)` for an offset. Legacy `.itemsFrom(n)`/`.itemsUntil(n)` use one-based boundaries: `.itemsUntil(51)` returns the first 50. Keep page counts and limits explicit; do not label a truncated list as a complete export.
 
-```bash
-cai data fields --type custom.customer --json
-```
-
-- `data create` and `data update` take field IDs.
-- Query/get results are keyed by field display names.
-- CSV columns are also matched by display names.
-
-Never feed a queried record directly into a write. Build a new fields object keyed by the `writeKey` mapping and omit reserved `id`, `createdAt`, and `updatedAt`.
+## Partial updates
 
-Fields may be typed `date`. Their values are strict ISO-8601 strings (`"2026-06-05"` or `"2026-06-05T12:30:00Z"`) on both write and read; anything else is rejected. Reserved `createdAt`/`updatedAt` are currently `text` — use `.toDate()` before date operations on them.
+Single Update writes every enabled field by default. Enable only intended fields for a fixed patch. For a dynamic API patch, enable the optional `$fieldMask` prop, bind it to a `list.text` of schema field IDs, and enable/configure the candidate fields. Only selected fields are written in one update. An empty mask selects none; an unknown or disabled selected field is an error. Omit the mask to keep the existing enabled-field behavior.
 
-## Work on the correct rail
-
-Development is the default:
-
-```bash
-cai data collections --env dev --json
-cai data query --type custom.customer --env dev --json
-cai data create --type custom.customer --fields '{"email":"a@example.com","score":5}' --env dev --json
-```
+This supports list/date/scalar updates without one node per field. Selected `false`, `0`, empty text and empty lists are real updates; omitted mask entries preserve the stored values. Distinguish clearing from omission in the flow contract. Update Multiple applies a patch transactionally to the selected real records; verify its failure behavior for stale or foreign IDs.
 
-MCP: every data write requires explicit `env`; reads default to `dev` when `env` is omitted.
+## Keys, schemas and environments
 
-Use `--env live` only when the user intends to inspect or mutate production state. Before a live write, say that published/triggered runs read this store.
+Inspect `data_field_list` for write keys. Data-tool writes use stable field IDs; query results can use display labels. Construct writes from the mapping instead of feeding a returned display-keyed object back into a write. Renaming a label is different from changing the stable schema/field key.
 
-`data query --query` is plain-text search over serialized records and metadata, not a field predicate. Perform exact field filtering inside workflow expressions or inspect results explicitly.
+Schema field updates replace the full declared field list. Read the existing schema and include every field intended to remain. Removing a schema or field hides its stored data; it does not snapshot or erase the underlying records. Restoring workflow history restores the definition only.
 
-## Delete records explicitly
-
-Record deletion is available only through the control surface; no workflow data node exposes it. Delete one known record or an explicit set of IDs:
-
-```bash
-cai data delete <recordId> --type custom.customer --env dev --json
-cai data delete-many --type custom.customer --records <id1,id2> --env dev --json
-```
-
-Delete every record in a collection only with explicit user intent; `--all` also requires `--yes`:
-
-```bash
-cai data delete-many --type custom.customer --all --yes --env dev --json
-```
-
-MCP: `data_record_delete_many` requires explicit `env: dev|live` and exactly one of `recordIds` or `all: true`; it has no `yes` parameter.
-
-The CLI default rail is development. Targeted and `--all --yes` bulk deletions also support `--env live`; a live deletion immediately changes the data read by the published workflow, so use it only with explicit production intent and query that rail afterward.
-
-## Import and promote
-
-Validate CSV before writing:
-
-```bash
-cai data import --type custom.customer --file customers.csv --mode dryRun --env dev --json
-cai data import --type custom.customer --file customers.csv --mode commit --env dev --json
-```
-
-MCP: pass CSV text inline as `content` with explicit `env: dev|live` to `data_record_import_validate`, then use `data_record_import_commit` to write the validated content.
-
-Both CLI modes support `--env live`: dry-run remains non-writing, while a live commit appends rows immediately visible to the published workflow. Verify result counts and query the imported rows on the same rail.
-
-To seed live from development:
-
-```bash
-cai workflow publish --json
-cai data copy-to-live --type custom.customer --json
-cai data collections --env live --json
-```
-
-MCP: call `data_copy_to_live` with the explicit acknowledgement `env: live`.
-
-The live schema must exist through a publish before copying. Treat copy-to-live as a production mutation and report counts/results.
-
-## Workflow expressions
-
-`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
-```
+Development is the default test store; MCP writes require explicit `env`. Publishing the workflow does not copy records to Live. Use explicit validated copy/import operations when data promotion is actually intended. Verify state in the same environment as the flow execution.
 
-- 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.
+Detailed schema, import and data commands: [command reference](references/command-reference.md). Environment and reference semantics: [data rails](references/data-rails.md).

package/skills/controllerai-data/references/command-reference.md

@@ -0,0 +1,177 @@
+# Controller AI data
+
+
+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.
+
+
+- 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.
+- `dataRecord.custom.customer` is an ACTUAL STORED RECORD of that shape — the same fields plus record identity (`id`, `createdAt`, `updatedAt`) proving it lives in the collection.
+
+In the product UI this appears as the "data record" checkbox when selecting a type for a flow input or run-subflow-on-list: unchecked means "data shaped like a customer", checked means "a real stored customer record". Users find this checkbox confusing — be ready to explain it in these terms.
+
+Consequences:
+
+- Only real records satisfy a `dataRecord.*` input. An expression that CONSTRUCTS record-shaped objects (e.g. a `.map()` that builds new objects) produces `custom.*`-shaped values with no identity — pass fetched records through instead.
+- Record metadata (`id`, `createdAt`) exists only on `dataRecord.*` values; on plain `custom.*` values those paths resolve empty.
+
+## Data nodes: update semantics
+
+- "Update multiple data records" takes an expression typed `list.dataRecord.custom.<type>` — real stored records passed through from a query or `workflowData(...)`. The batch is ONE transaction: if any resolved record is stale (deleted since fetched) or foreign to the collection, the node errors and NOTHING updates. A failed run therefore means zero changes — fix and rerun safely.
+- On the single-record "Update data" node, every ENABLED field is written. Enable only the fields you intend to change; disabled fields keep their stored values.
+
+## Define a schema deliberately
+
+Inspect existing types first:
+
+```bash
+cai schema list --json
+cai schema get custom.<name> --json
+```
+
+Create a type with stable field IDs:
+
+```bash
+cai schema create custom.customer \
+  --display "Customer" \
+  --field email:text:"Email" \
+  --field score:number:"Score" \
+  --json
+```
+
+Creating the schema creates/synchronizes its collection. `cai data collection create` is only an alias for schema creation.
+
+MCP: `cai data collection create` is merged into `schema_type_create`.
+
+`schema update --field` replaces the complete field list; it does not append — this is deliberate, so a subset CAN intentionally replace the whole schema. Read the current schema, preserve intended fields, and disclose any removals. The transport response warns about every field being dropped and echoes back the COMPLETE stored shape after the write — always read that echo and confirm it matches intent. Deleting a schema hides its collection and records and breaks dependent expressions — tell the user, and know it is recoverable (see below).
+
+## How schema changes affect stored records
+
+Schema changes never hard-delete data. There is no delete path for records in schema sync — everything is deactivation and hiding:
+
+- Delete a type → its collection goes INACTIVE on the next saved state; every record row survives. Re-add the same `custom.*` key and the same collection reactivates with all records intact.
+- Delete a field → its values stay inside each record, unaddressable. Re-add the SAME field id and the old values reappear.
+- Add a field → purely additive; existing records read the new field as null.
+- Change a field's type → values are never converted or erased; incompatible values read as null and return if the type is changed back. The schema hash changes, which blocks copy-to-live until dev and live match again.
+- Publish applies the same deactivate/reactivate logic to live. Live records are hidden, never deleted.
+- Restoring an older workflow state rolls back the DEFINITION (graph and schemas), never the data. The record store is not versioned and only moves forward: a deleted type reactivates with whatever the store holds NOW — records created, edited, or soft-deleted after the restored state stay exactly as they are. Restore is not a data snapshot.
+
+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.
+
+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
+
+```bash
+cai data fields --type custom.customer --json
+```
+
+- `data create` and `data update` take field IDs.
+- Query/get results are keyed by field display names.
+- CSV columns are also matched by display names.
+
+Never feed a queried record directly into a write. Build a new fields object keyed by the `writeKey` mapping and omit reserved `id`, `createdAt`, and `updatedAt`.
+
+Fields may be typed `date`. Their values are strict ISO-8601 strings (`"2026-06-05"` or `"2026-06-05T12:30:00Z"`) on both write and read; anything else is rejected. Reserved `createdAt`/`updatedAt` are currently `text` — use `.toDate()` before date operations on them.
+
+## Work on the correct rail
+
+Development is the default:
+
+```bash
+cai data collections --env dev --json
+cai data query --type custom.customer --env dev --json
+cai data create --type custom.customer --fields '{"email":"a@example.com","score":5}' --env dev --json
+```
+
+MCP: every data write requires explicit `env`; reads default to `dev` when `env` is omitted.
+
+Use `--env live` only when the user intends to inspect or mutate production state. Before a live write, say that published/triggered runs read this store.
+
+`data query --query` is plain-text search over serialized records and metadata, not a field predicate. Perform exact field filtering inside workflow expressions or inspect results explicitly.
+
+## Delete records explicitly
+
+Native workflow Delete Record actions provide reusable deletion inside a flow. Discover their exact keys under registry_data. The data tools below also delete one known record or an explicit set of IDs during setup and debugging:
+
+```bash
+cai data delete <recordId> --type custom.customer --env dev --json
+cai data delete-many --type custom.customer --records <id1,id2> --env dev --json
+```
+
+Delete every record in a collection only with explicit user intent; `--all` also requires `--yes`:
+
+```bash
+cai data delete-many --type custom.customer --all --yes --env dev --json
+```
+
+MCP: `data_record_delete_many` requires explicit `env: dev|live` and exactly one of `recordIds` or `all: true`; it has no `yes` parameter.
+
+The CLI default rail is development. Targeted and `--all --yes` bulk deletions also support `--env live`; a live deletion immediately changes the data read by the published workflow, so use it only with explicit production intent and query that rail afterward.
+
+## Import and promote
+
+Validate CSV before writing:
+
+```bash
+cai data import --type custom.customer --file customers.csv --mode dryRun --env dev --json
+cai data import --type custom.customer --file customers.csv --mode commit --env dev --json
+```
+
+MCP: pass CSV text inline as `content` with explicit `env: dev|live` to `data_record_import_validate`, then use `data_record_import_commit` to write the validated content.
+
+Both CLI modes support `--env live`: dry-run remains non-writing, while a live commit appends rows immediately visible to the published workflow. Verify result counts and query the imported rows on the same rail.
+
+To seed live from development:
+
+```bash
+cai workflow publish --json
+cai data copy-to-live --type custom.customer --json
+cai data collections --env live --json
+```
+
+MCP: call `data_copy_to_live` with the explicit acknowledgement `env: live`.
+
+The live schema must exist through a publish before copying. Treat copy-to-live as a production mutation and report counts/results.
+
+## Workflow expressions
+
+`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 [data-rails.md](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

@@ -1,173 +1,51 @@
 ---
 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, upstream node, loop item, workflow data, constant, calculation, template, or boolean rule, or when an expression compiles but resolves to null or the wrong input.
+description: Write and debug Controller AI typed expressions for flow inputs, upstream outputs, records, conditions and calculations. Use for data mapping, search, filtering, formatting, optional inputs and computed node props.
 ---
 
-# Controller AI expressions
+# Expressions: typed values inside a workflow
 
-The `cai ...` examples are canonical grammar. Use the transport selected in `controllerai-start` and its MCP tool map; never mix transports in one task.
+Expressions connect workflow data to node properties and conditions. The JavaScript-looking authoring language compiles to Controller AI's stored expression tree; it is a **typed subset**, not arbitrary JavaScript execution. You can navigate inputs and fields, calculate numbers, format text and dates, query workflow data and operate on lists.
 
-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.
+## Discover the real scope
 
-## Rules that break tasks when skipped
+`expr_operation_list` provides the method catalog, including before a workflow has nodes. `expr_context` for a node shows current flow/input bindings, available fields, upstream outputs not yet wired, and the target property's expected type. Use returned names; display labels and stored IDs are not interchangeable.
 
-- 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.
+Common sources are `flow.<binding>`, `inputs.<binding>`, `process.data`, loop `item`, `now`, `isLiveVersion` and `workflowData("custom.type")`. Upstream values appear under `inputs` only after the relevant output is wired in. Root routing nodes can use flow inputs directly.
 
-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.
+## Compose values
 
-`.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 evaluates to its typed empty form: `""` for TEXT, null/undefined for objects. Both cases below fail silently:
-
-- **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`).
-
-## Required write loop
-
-### 1. Wire first
-
-An upstream output is available only after it is connected to the target node. If context lists it under `unwiredUpstreamOutputs`, connect it, then fetch context again.
-
-```bash
-cai node connect --flow <flowId> --from <sourceNodeId> --to <targetNodeId> --json
-```
-
-Use `cai branch connect` for Router or If/Else outputs.
-
-### 2. Read the destination's exact scope
-
-```bash
-cai expr context <nodeId> --prop <propName> --json
-```
-
-Copy binding and field names exactly. Important sources include:
-
-- `flow.<name>`: flow input
-- `inputs.<name>`: wired node input; the payload is usually already unwrapped
-- `item`: injected current item, only where context exposes it
-- `workflowData("custom.type")`: records from an active workflow collection
-- `now`, `isLiveVersion`: constants shown by context
-
-Do not derive a binding from a display label. Context flags duplicate display names and supplies the de-duplicated JS name, input ID, and source node.
-
-When compilation reports an unknown field, copy a typeable display-derived accessor it advertises; field IDs appear second for disambiguation.
-
-### 3. Use only advertised syntax
-
-Get the current operation catalog when needed:
-
-```bash
-cai expr ops --workflow <workflowId> --type <text|number|date|list|boolean|file|custom> --json
-```
-
-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 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
-
-For a node prop, prefer:
-
-```bash
-cai expr set <nodeId> --prop <propName> --js '<expression>' --json
-```
-
-MCP: use `node_prop_set` with `js`; it merges `cai expr set` with `cai node set`.
-
-For multiline expressions or shell-sensitive templates on CLI, put the exact source in a UTF-8 file and use `--js-file <path>`. Use `--js-file -` to read stdin. It is mutually exclusive with inline `--js` and is available on `expr validate/set`, `node set/only-when`, and `branch add/update`.
-
-```bash
-cai expr set <nodeId> --prop <propName> --js-file expression.js --json
+```javascript
+flow.name.toLowerCase()
+`Hello ${flow.name}, score ${flow.score}`
+flow.score + 10
+flow.label ?? "Unknown"
+flow.enabled ? "Enabled" : "Disabled"
+workflowData("custom.contact").filter(r => r.id === flow.recordId).first()
 ```
 
-MCP: pass the file contents inline as `js`; the hosted process does not read the local path or stdin.
-
-This fetches target metadata, auto-enables a catalog-only optional target when needed, compiles before writing the value, persists to the correct channel, and verifies read-back. If validation or the value write then fails, the prop stays enabled; repair with `cai node disable-prop <nodeId> --prop <propName>`.
+Use field IDs with the provided dot/bracket spelling. Prefer templates for text composed from multiple values. Dates use the supported date methods and Moment format tokens, for example `now.format("YYYY-MM-DD")`; do not assume JavaScript Date constructors/getters exist.
 
-MCP: repair with `node_optional_prop_set` and `enabled: false`.
+A record query returns `list.dataRecord.custom.*`, including record identity. Plain custom values describe shape only. Optional filter semantics, membership and pagination are explained in `controllerai-data`.
 
-Array channels are not interchangeable. On a value-channel `SHORT_TEXT_ARRAY`, a scalar expression replaces the whole array with one dynamic element; it does not append. List-typed expressions on value-channel array props are rejected. Use `cai node set <nodeId> --prop <propName> --value '["a","b"]'` for a static list, or use a list-typed expression only where prop metadata exposes whole-array expression mode.
+## Conditions and list predicates
 
-For a side-effect-free check:
+A single comparison or supported boolean expression can be a condition. Router/only-when groups support OR-of-AND groups through the structured condition input. Use that input for compound routing logic instead of assuming every JavaScript boolean expression is accepted everywhere.
 
-```bash
-cai expr validate <nodeId> --prop <propName> --js '<expression>' --json
-```
+List `.filter`, `.some`, `.find` and `.every` accept the predicate grammar in the catalog. `.map` is field projection, not an arbitrary object-building callback. List membership compares an element; text membership finds a case-sensitive substring.
 
-For conditions:
+Scalar text/number/boolean ternaries are supported; list, date and record branches need typed routing or a field-mask update instead. Do not assume methods on literals, arbitrary null literals, JavaScript constructors or object-building callbacks are accepted.
 
-```bash
-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
-```
+If the compiler rejects an idiom, use the error's supported alternative and validate it. Do not invent raw expression trees to bypass a missing language feature. Use routing, typed inputs or a native action where they express the operation more clearly.
 
-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`.
+## Save and verify
 
-Router and If/Else conditions are written with `cai branch add` or `cai branch update` after the same context/validation discipline.
+1. Inspect the property and its expected type.
+2. Validate the proposed expression with `expr_validate` against the node scope.
+3. Persist with `node_prop_set` using `js` (or the relevant condition tool). Literal `value` and compiled `js` are different sources.
+4. Read the stored property and resolved status; run representative inputs.
+5. Check resolved configs and actual results, including omission, `false`, `0`, empty text/list and missing record cases relevant to the task.
 
-### 5. Verify runtime resolution
-
-```bash
-cai expr decompile <nodeId> --prop <propName> --json
-cai run node <nodeId> --inputs <values.json> --json
-```
-
-MCP: `run_node` takes the parsed `inputs` object and `waitSeconds` (default 60, max 120).
-
-Use `run node` to isolate the destination's own configuration. It never executes wired upstream nodes. If the expression consumes `inputs.<name>`, also run its containing flow:
-
-```bash
-cai run flow <flowId> --inputs <values.json> --json
-```
-
-MCP: `run_flow` takes the parsed `inputs` object and `waitSeconds` (default 60, max 120).
-
-Inspect `runScope` and `resolvedConfigs` in the run result. A null or missing dynamic config is an expression failure, not success; a partially empty value is equally suspect. Only the full flow run proves an upstream-derived value. Use `cai exec node <nodeExecutionId> --full --json` to inspect the final status, resolved configs, and untruncated output.
-
-## Hard rules
-
-- Never guess a binding, field, method, or target type.
-- Never author against an unwired output.
-- Never add `.data` automatically. Use the exact path shown by context.
-- Re-read context after rewiring, renaming inputs, changing schemas, changing dynamic selectors, or resolving an output type.
-- 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
-```
+A successful compile proves grammar and type compatibility, not that a query finds data. An intentional empty result can be valid; an unexpected empty value needs tracing to the binding, environment or filter.
 
-- 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`.
+Reference syntax and mapping commands: [command reference](references/command-reference.md). Supported grammar and recipes: [DSL reference](references/dsl-and-recipes.md).