@lotics/cli 0.276.0 → 0.278.0

package/docs/app_bindings.md

@@ -0,0 +1,181 @@
+# App bindings — the queries, workflows and agents an app calls
+
+A custom-code app reaches workspace data through three kinds of binding, each declared on the app
+under an alias — a JS identifier (`/^[a-zA-Z_$][a-zA-Z0-9_$]*$/`):
+
+| Binding | Declared with | The app calls it with | An agent calls it with |
+|---|---|---|---|
+| Query | `set_app_query`, `set_app_queries` | `useQuery("<alias>", params?)` | `run_app_query` |
+| Workflow | `set_app_workflow` | `useWorkflow("<alias>")({ ...inputs })` | `run_app_workflow` |
+| Agent | `set_app_agent` | `useAgentRun("<alias>")({ ...inputs })` | — |
+
+Each runs under the app's authority (`{ type: "app", app_id }`), the app owner's reach — never the
+calling member's. Declaring one needs the app's owner or an admin. A write is live: the app's next
+call uses it. `get_app_capabilities` lists an app's aliases with their params and inputs.
+
+## Queries
+
+A query declaration is `{ ast, params?, description?, templates? }`:
+
+- `ast` — a query template (a QueryNode, below). It fixes the tables, filters and columns the alias
+  reads, so a caller cannot widen it.
+- `params` — the typed value holes the caller fills, each an input declaration (see **Inputs**),
+  named in the ast as `{{params.<name>}}`. A param fills a VALUE position only — a filter value, a
+  `search` — never a `table_id` or a field key. Every token the ast names is declared. An optional
+  param left unset drops the conditions that read it; a required param that arrives empty is
+  refused where a filter reads it.
+- `description` — one line saying what the query returns, for an agent choosing between aliases.
+- `templates` — the document templates an export of its rows may fill, by name:
+  `{ <name>: { template_id: "dtl_…", rows: "<key the template lists the rows under>" } }`.
+
+A save checks what a deploy checks: every table is in this workspace and within the owner's reach,
+every projected, filtered and sorted field resolves, every param token is declared, and a key a
+node's kind does not take (a stray `sort`, `limit`, `filter`, `search`) is refused by name.
+
+`set_app_query` edits ONE alias and merges: send only the fields you change, `null` clears
+`params`, `description` or `templates`, and a new alias needs an `ast`. `set_app_queries` writes
+several at once: an alias it names is replaced whole, an alias it omits is kept.
+`remove_app_query` deletes one; `get_app_query` reads one back.
+
+### The query tree
+
+Every node has a `kind`; all but `from_table` read the node under `from` (`join`: `left`/`right`,
+`union`: `sources`).
+
+| `kind` | Keys |
+|---|---|
+| `from_table` | `table_id`, `filter?`, `search?`, `sort?`, `limit?` |
+| `project` | `columns` — the output columns |
+| `filter` | `predicate` — a filter tree over the input's columns |
+| `join` | `left`, `right`, `on: { left_column, right_column }`, `type: "inner" \| "left"` |
+| `union` | `sources` (at least two, columns aligned by name and type) |
+| `group` | `by` (columns, or `{ bucket: { source, granularity, output } }`), `aggregates` |
+| `window` | `partition_by`, `order_by`, `frame?`, `aggregates?`, `functions?` |
+| `sort` | `by: [{ field_key, order }]` |
+| `limit` | `n`, `offset?` or `keyset?` |
+| `unpivot` | `passthrough`, `row_columns`, `rows` — one source row into several |
+| `unnest` | `source`, `output`, `display_output?`, `keep_empty?` — one row per element of a multi-value cell |
+
+Filters (`from_table.filter`, `filter.predicate`, an aggregate's `filter`) are the filter grammar — the
+`filters` reference — over the input's columns, taking `{{params.x}}` as values. `search` matches
+every text-bearing field of the row, accent- and case-insensitive.
+
+A `project` column is a field key as a bare string (output name and type come from the field), or
+`{ output?, type?, source, writable_target?, limit? }` to rename, compute or bound one. A computed
+`source` is a field key, `{ literal }`, `{ eq: [a, b] }`, `{ neq: [a, b] }`, `{ isEmpty }`,
+`{ isNotEmpty }`, `{ coalesce: [...] }`, `{ concat: [...] }`, `{ record_id: true }`,
+`{ link: { source, field } }` (a field of the first linked record),
+`{ link_agg: { source, field, operation } }` (`sum`, `avg`, `min`, `max`, `count`, `string_agg`
+over every linked record), or `{ expression }`. A computed column states its `type`: `text`,
+`number`, `boolean`, `date`, `datetime`, `select`, `select_record_link`, `select_member`, `files`
+or `json`. `limit` (1–10) bounds a `files` column's entries per cell.
+
+An aggregate column is `{ output, type, operation, input_column?, filter? }` — `string_agg` also
+takes `separator`, `distinct` and `max_values`. A `window` function is
+`{ output, fn }` for `row_number`, `rank`, `dense_rank`, `percent_rank`, `cume_dist`, plus
+`buckets` for `ntile` and `input_column`, `offset?`, `default?` for `lag` / `lead`; functions need
+a non-empty `order_by`.
+
+## Inputs
+
+A query's `params`, a workflow's `inputs` and an agent's `inputs` are one vocabulary: a map of
+name → `{ type, required?, description?, …per type }`. An entry is required unless it states
+`required: false`.
+
+| `type` | Takes |
+|---|---|
+| `text`, `number`, `boolean`, `date`, `datetime`, `email` | — |
+| `record_link` | `table_id`; `multi?`; `max?` (with `multi`, the most ids one call carries) |
+| `select` | exactly one of `options: [{ label, value }]` or `field: "fld_…"` (a select field whose CURRENT options back it); `multi?` |
+| `date_range` | `include_time?` |
+| `member` | `multi?`; `group?` (a member group the value must belong to) |
+| `file` | `multi?` — an uploaded `fil_…` id, for a files field |
+| `json` | — any value |
+| `object` | `fields` — a nested map of entries |
+| `array` | `items` — one entry |
+
+Nesting stops at depth 8. A `field`-form select tracks the field's options as they change; an
+inline `options` set is a fixed list.
+
+## Outputs
+
+A workflow's and an agent's `outputs` declare the structured data handed back: a map of
+name → `{ type, required?, description?, …per type }`, every entry present unless it states
+`required: false`.
+
+| `type` | Takes |
+|---|---|
+| `text`, `number`, `boolean`, `date`, `datetime`, `email`, `json` | — |
+| `record_link` | `table_id`, `multi?` |
+| `select` | exactly one of `options: [{ label, value }]` or `field: "fld_…"`; `multi?` |
+| `object` | `fields` |
+| `array` | `items` |
+
+The returned value is checked against it, and the app reads it typed. An inline `options` set is
+also enforced on the value returned, so the producer is told the legal keys; a `field`-form select
+keeps the type tracking the live field.
+
+## Workflows
+
+`set_app_workflow` binds a workflow body to an alias: `{ app_id, alias, source, inputs?, outputs?,
+name?, description? }`.
+
+- `source` is the body with no `on({...})` trigger — the app is the trigger. It reads each declared
+  input as `trigger.app_workflow.inputs.<name>`; no record is in scope, so it reads each one by id
+  with `get_record`.
+  The body's steps are the `workflows` reference.
+- `inputs` is the payload the call site passes (see **Inputs**). Omitted, an existing workflow keeps
+  its inputs; on a first bind it takes an untyped payload. `{}` clears them.
+- `outputs` is what `return({ data })` hands back (see **Outputs**). Usually omit it: the type is
+  derived from the body's `return({ data })`, and the result echoes the bound `outputs`. Declared,
+  the body does not save unless its return matches.
+- A save checks the body — parse, type-check against the declared inputs, names, lint, structure —
+  and answers with `[source/code] location: message` lines. `verify_only: true` makes every check
+  and writes nothing. A call naming a live alias replaces its body in place, keeping its run history.
+- A call whose payload does not match `inputs` is refused before the body runs.
+
+`get_app_workflow` reads the body back; `dry_run_workflow` with `trigger_type: "app_workflow"`
+runs it against sample inputs before binding; `remove_app_workflow` unbinds it.
+
+## Agents
+
+`set_app_agent` binds a streaming tool-loop agent to an alias. A run streams its work to the app,
+returns a typed result and keeps a run history per session. The declaration:
+
+- `instructions` — the task, every run. A new alias needs it.
+- `tool_names` — the tools it may call, from these and no other: `analyze_pdf_template`,
+  `code_edit_file`, `code_exec`, `code_read_file`, `code_write_file`, `excel_create_file`,
+  `excel_find_cells`, `excel_format_range`, `excel_get_range`, `excel_update_range`,
+  `generate_bank_qr_code`, `generate_excel_from_template`, `generate_image`,
+  `generate_pdf_from_template`, `generate_qr_code`, `generate_word_from_template`, `get_template`,
+  `grep_knowledge`, `list_banks`, `list_knowledge`, `lookup_business`, `query_templates`,
+  `read_knowledge`, `run_app_query`, `run_app_workflow`, `validate_excel_template`,
+  `vietcombank_convert_currency`, `view_files`, `word_create_document`, `word_find_text`,
+  `word_get_content`, `word_get_table_data`, `word_insert_conditional`, `word_insert_loop`,
+  `word_replace_text`. `[]` is a reasoning-only agent. A few fields of a document read well through
+  the `excel_*` / `word_*` tools; a cross-check, reconciliation or transform a decision rests on
+  belongs in the code tools.
+- `query_aliases` / `workflow_aliases` — the app's own queries and workflows it may call through
+  `run_app_query` / `run_app_workflow`. They are its whole reach over records: no agent tool takes a
+  `table_id`, so a read is bounded by the query's tables, rows and columns, and a write goes through
+  the app's own workflow.
+- `knowledge_doc_ids` — knowledge docs it may read with `grep_knowledge` / `read_knowledge`
+  (declare them in `tool_names`). Each must be one the app owner and you can use. Nothing is
+  inlined and size does not matter. The list is the agent's whole reach — `list_knowledge` finds no
+  doc outside it — so name a doc's id in `instructions` to point it there. `code_exec` computes
+  across a corpus (counting, cross-referencing); reading needs only the knowledge tools.
+- `model_tier` — `haiku`, `sonnet` or `opus`. Omitted, the run follows the platform's default tier
+  and moves with new models; pin one only as a tested choice, and never `haiku`, a utility tier.
+- `effort_level` — `low`, `medium`, `high`, `xhigh` or `max`, one the pinned tier supports; it
+  needs `model_tier`.
+- `prefix_cache_ttl` — `5m` (the default) or `1h`. `1h` doubles the cache write price and pays only
+  when runs land 5 to 60 minutes apart, as a scheduled sweep does.
+- `inputs` — the per-run payload (see **Inputs**); omitted, the payload is untyped.
+- `outputs` — the structured result (see **Outputs**), checked before the run is saved and typed
+  as `run.output` in the app; omitted, the result is the final message.
+- `writes` — where the outputs land: `{ table_id, row, fields }`, `row` naming a single
+  `record_link` input to `table_id` and `fields` mapping each output name to a field key of that
+  table. A result that validates is written to that row under the app's authority.
+
+Send only what you change: an omitted field keeps its stored value, `null` clears an optional one.
+`get_app_agent` reads one back; `remove_app_agent` deletes it.

package/docs/data_model.md

@@ -1,15 +1,33 @@
-# The data model — how tables relate
+# The data model — tables, their fields, and how they relate
 
 The decisions here outlive any one app, and most become expensive the moment a second screen depends
-on them. They are separate from `lotics docs building_an_app` on purpose: **every workspace starts
-with tables and many never get a custom app**, so schema design is not a chapter of app building.
+on them. They stand apart from building an app on purpose: **every workspace starts with tables
+and many never get an app**, so schema design is not a chapter of app building.
 
-`ONE FACT, ONE COLUMN` — the rules governing a single table's own columns — is stated at the tools
-that add a field, `create_table` and `update_table`, where you meet it while deciding. This doc is
-the other half: how tables relate to each other.
+The rules below share one signature. **Both sides read correctly on their own**, so nothing reports
+the problem — no error, no empty column, no failing query. Each is found by looking for it. Then,
+under **Fields**, what each field type takes.
 
-Everything below shares one signature. **Both sides read correctly on their own**, so nothing reports
-the problem — no error, no empty column, no failing query. Each is found by looking for it.
+## One fact, one column
+
+**Read the table's existing fields first, and add nothing that stores a fact the table already
+stores.** A value written as text and the same value held as a `select_record_link` are one fact in
+two columns — a customer's city typed into a text box beside a link to the city record, a status
+word beside the select that decides it, a total beside the formula that computes it.
+
+Two columns for one fact do not stay equal. Some writer sets only one of them, and nothing reports
+the divergence: both rows still look correct on their own. A reader that then matches on the text
+half treats "Acme" and "Acme Ltd" as different records, so an import creates a duplicate every time
+it runs.
+
+- **Prefer the link, the select, or the formula.** Text is a RENDERING of a record; compose it when
+  you read, rather than storing it a second time.
+- **Renaming, retyping or re-pointing the existing field beats adding another.** A field's key is
+  stable, so a rename breaks nothing that addresses it by key.
+- **Superseding a field means DELETING it**, not leaving it beside its replacement with a
+  description that says which one is real.
+- **Empty is not the same as redundant.** A field nothing fills may still be the only home for a
+  real distinction — read what it MEANS before removing it.
 
 ## One entity, one table — and the test is measurable
 
@@ -69,6 +87,16 @@ it falls back to comparing displayed text — which is how one company arrives t
 spellings. Name the key: a reference number, a tax id, a link plus a period. Then match on `rec_…`
 and `opt_…`, never on rendered labels.
 
+## A state's HISTORY is rows, not columns
+
+A `changed at` column says only how long a row has been where it is now — the next move overwrites
+it — and a date column per state holds until something re-enters a state it already left.
+
+Measuring time-in-state or conversion needs one ROW per move: a link to the subject, the state left,
+the state entered, when. Hold those states as the source field's own `opt_` keys so the log carries
+no second vocabulary, and write the rows from that table's own lifecycle workflows, which covers
+every writer rather than one app's.
+
 ## Keep derived chains shallow
 
 Formulas and rollups are computed and STORED when a row is written, and one that reads another
@@ -90,3 +118,141 @@ the numbers themselves:
 And when a formula gains a new field, **test that the value IS the one you want, never that it
 differs from it** — an empty cell reads as `""`, which differs from every option key, so the inverted
 spelling silently zeroes every row written before the field existed.
+
+## Fields
+
+What `create_table` and `update_table` take in `add_fields`, and `update_table` in `update_fields`.
+
+### Types and formats
+
+`type` is one of `text`, `number`, `date`, `boolean`, `select`, `select_member`,
+`select_record_link`, `files`, `formula`, `rollup`, `lookup`, `autonumber`. `button` is retired: an
+existing button field keeps running, but none is created, converted to or edited.
+
+A URL, an email, markdown, a checkbox, a datetime, a currency or a percentage is a `format` on
+another type, never a `type`:
+
+| Wanted | Field |
+|---|---|
+| URL or external link | `{ type: "text", format: "link" }` |
+| Email or phone | `{ type: "text" }` |
+| Markdown | `{ type: "text", format: "markdown" }` |
+| Checkbox | `{ type: "boolean" }` |
+| Money | `{ type: "number", format: "currency", currency: "USD" }` |
+| Percentage | `{ type: "number", format: "percentage" }` |
+| Datetime | `{ type: "date", format: "datetime" }` |
+| Date range | `{ type: "date", format: "date_range" }` |
+
+### Properties
+
+A type's properties sit **directly on the field object** — there is no `config` wrapper. A property
+may itself hold an object (`formula`, `aggregate_option`, `filter`, `order_by`); its inner keys stay
+inside it. Each type takes only its own:
+
+- **text** — `format?` (`"text"` | `"link"` | `"markdown"`), `unique?`, `default_value?` (a string).
+- **number** — `format?` (`"number"` | `"currency"` | `"percentage"`), `currency?` (an ISO 4217
+  code), `unit?`, `unit_field?`, `currency_field?`, `default_value?` (a number). On `update_fields`,
+  null clears `currency`, `unit`, `unit_field` or `currency_field`.
+  - `unit`, beside format `"number"`: a measured code — g, kg, t, l, m3, cbm, mm, cm, m, km, m2,
+    min, h, day — or a counted noun such as `kiện`. A change between two units of one dimension
+    converts every stored figure; any other change relabels.
+  - `unit_field`: A single select on the same row, or a lookup of one through a one-link, whose chosen option is that row's unit: every option label is a unit as `unit` takes one. In place of `unit`; only beside format "number".
+  - `currency_field`: A single select on the same row, or a lookup of one through a one-link, whose chosen option is that row's currency: every option label is an ISO 4217 code. In place of `currency`; only beside format "currency".
+- **date** — `format?` (`"date"` | `"datetime"` | `"date_range"` | `"datetime_range"`), `timezone?`,
+  `derive_from?`, `default_value?` (a date string). `derive_from: "created_at"` stamps the row's
+  creation once, `"updated_at"` re-stamps on every update; the field is then read-only, takes no
+  `default_value`, and holds only the `date` and `datetime` formats.
+- **boolean** — `default_value?` (`true` | `false`).
+- **select** — `options` `[{ name, color?, mark? }]`, `multi?`, `default_value?`.
+- **select_member** — `multi?`, `default_value?` (member ids).
+- **select_record_link** — `table_id`, `display_field_keys?`, `sync_both_ways?`, `cardinality?`,
+  `paired_field_name?`, `paired_field_display_field_keys?`. Without `display_field_keys` a link shows
+  the target's autonumber, else its first text field. `sync_both_ways: true` on an existing one-way
+  link makes it two-way — never add a second link for that. `cardinality: "one"` marks the child
+  side of a parent-child pair (the linked record is this one's parent); two paired sides cannot both
+  be `"one"`. The `paired_*` keys name and label the back-reference the target gets.
+- **files** — no properties.
+- **autonumber** — `template` (`"INV-{YEAR}-{N:4}"`; tokens `{N}`, `{N:W}` zero-padded to W,
+  `{YEAR}`, `{YEAR:2}`, `{MONTH}`, `{DAY}`), or `prefix` + `padding` (1–20) for `PREFIX-0001`.
+- **any type**, at create — `confirm_before_update?`: a person confirms each later edit.
+
+`default_value` fills the field on a NEW record that states no value; existing records are never
+backfilled, and null clears it. A select's or a member field's default is an ARRAY even when the
+field holds one (`["Unread"]`, never `"Unread"`) — option names in `add_fields`, where the keys do
+not exist yet, and option keys (`opt_…`) in `update_fields`.
+
+### Computed fields
+
+Read-only in records. `formula` is one key holding an object; a rollup's and a lookup's properties
+are separate keys on the field — `rollup: {…}` and `lookup: {…}` are refused as unrecognized.
+
+formula: { expression, format?, currency?, unit?, unit_field?, currency_field? }
+
+- `{Field Name}` or `{fld_key}` names a field of the same table, stored as its key, so a rename never
+  breaks the formula. A reference to no field, or a call to something that is no helper, is refused.
+- A select reads as an ARRAY of option keys: `{Status}[0]` for a single select,
+  `includes({Tags}, "opt_…")` for a multi.
+- The operators, the helpers and how an empty cell reads are the `model` reference, section `formula` — a model
+  names fields by alias where a table tool names them by name or key; the language is the same.
+- On `update_fields` a key left out keeps its stored value, and null clears `currency`, `unit`,
+  `unit_field` or `currency_field`. `get_table` marks a formula that is null when every field it
+  reads is empty.
+
+rollup — `source_field_key`, `aggregate_option: { field_key?, operation }`, `filter?`
+
+- `source_field_key` is a `select_record_link` of this table; `aggregate_option.field_key` is a
+  field of the linked table, required by every operation but `count`, which counts linked records.
+- Operations by the aggregated field's type — none: `count`; any: `empty`, `filled`,
+  `percent_empty`, `percent_filled`, `unique`, `percent_unique`; number: `sum`, `avg`, `median`,
+  `min`, `max`, `range`; date: `earliest`, `latest`, `date_range`.
+- The cell's type comes from the OPERATION: `earliest` and `latest` hold a date, every other
+  operation a number (`date_range` counts days). A "most recent linked date" is `latest` — `min` and
+  `max` are numeric and refuse a date. A rollup takes no format, currency or unit of its own: `sum`
+  over money carries the aggregated field's currency, over a weight its unit.
+- Over a figure read in each row's own unit or currency (`unit_field` / `currency_field`), `sum`,
+  `avg`, `median`, `min`, `max` and `range` hold only where that select is a lookup, through the
+  link paired with `source_field_key`, of a single select on this table — the total reads in this
+  row's option of it. A lookup of such a field has no unit.
+- `filter` aggregates only the linked records it matches: a full group over the LINKED table's
+  fields — `{ node_type: "group", logic, children: [{ node_type: "condition", type, field_key,
+  operator, value }] }`, a select condition using `has_any_of` with an ARRAY value.
+
+lookup — `source_field_key`, `lookup_field_key`, `order_by?`
+
+- `lookup_field_key` is a field of the linked table. Without `order_by` the cell holds every linked
+  record's value; with `order_by: { field_key, direction }` (`desc` latest, `asc` earliest) it holds
+  the picked field of the single extreme record — a "latest linked X" that maintains itself.
+  Ordered lookups sharing one `order_by` resolve to the SAME record.
+
+### Examples
+
+```
+{ name: "Giá bán", type: "number", format: "currency", currency: "VND" }
+{ name: "Trọng lượng", type: "number", unit: "kg" }
+{ name: "Số lượng", type: "number", unit_field: "ĐVT" }
+{ name: "Trạng thái", type: "select", options: [{ name: "Mới" }, { name: "Xong" }] }
+{ name: "Mã đơn", type: "autonumber", template: "SR-{YEAR}-{N:4}" }
+{ name: "Khách hàng", type: "select_record_link", table_id: "tbl_x", sync_both_ways: true }
+{ name: "Total", type: "formula", formula: { expression: "{Price} * {Qty}", format: "currency", currency: "VND" } }
+{ name: "SL đã giao", type: "rollup", source_field_key: "Giao hàng", aggregate_option: { operation: "sum", field_key: "Số lượng" } }
+{ name: "Customer Name", type: "lookup", source_field_key: "Customer", lookup_field_key: "Name" }
+{ name: "Latest note", type: "lookup", source_field_key: "Calls", lookup_field_key: "Note", order_by: { field_key: "At", direction: "desc" } }
+```
+
+### Changing a field
+
+A field added by `update_table` shows in a view only when `add_to_views` names it, at the view's far
+right; `update_view` with `move_field` places it beside the columns it belongs with.
+
+An `update_fields` entry is `{ field_key, name?, description?, convert_to?, … }` with the same flat
+properties as `add_fields`, plus what only an update does:
+
+- A select's options change through `add_options` `[{ name, color?, mark? }]`, `update_options`
+  `[{ key, name?, color?, mark? }]`, `remove_option_keys` and `reorder_options` (every existing
+  option once, in order; options added in the same call follow). An option is named by its `opt_…`
+  key (its name also resolves); a rename keeps every record's value. `mark` is the option's brand
+  (`{ kind: "brand", name: "tiktok" }`) or kit glyph (`{ kind: "icon", name: "wrench" }`), drawn in
+  place of its colour dot — every option of a field has one or none does, so marking sets them all
+  in one call and `mark: null` on each clears them.
+- A link's `sync_both_ways: false` disconnects the pair; a new `table_id` re-points it and clears its
+  record data; `cardinality` is `"one"` for the child side of a parent-child pair, `"many"` for peers.

package/docs/filters.md

@@ -0,0 +1,114 @@
+# Filters — choosing records by their fields
+
+One grammar for every tool that takes a filter: `query_records`, `aggregate_records`, `update_records`
+and `delete_records` by filter, a view's filter, a rollup's filter, and the filters a caller passes
+to an app's query.
+
+## The shape
+
+A filter is a single condition, or a group of conditions.
+
+```
+{ "node_type": "condition", "field_key": "Status", "operator": "has_any_of", "value": ["Done"] }
+{ "node_type": "group", "logic": "and" | "or", "children": [ …conditions or groups ] }
+```
+
+Groups nest up to 4 levels. AND(OR(status = A, status = B), age > 40):
+
+```
+{ "node_type": "group", "logic": "and", "children": [
+  { "node_type": "group", "logic": "or", "children": [cond1, cond2] },
+  cond3
+] }
+```
+
+Every `field_key` resolves against the table being filtered — read each table's fields (`get_table`)
+and carry no name across tables: sibling tables holding the same concept routinely name it
+differently. A field is named by its `fld_…` key or by its name (`"Status"`).
+
+## Text
+
+| Operators | Value |
+|---|---|
+| `equals`, `not_equals`, `contains`, `does_not_contain`, `starts_with`, `ends_with` | a string |
+| `is_any_of`, `is_none_of` | a string array — exact, case-insensitive |
+| `contains_any_of` | a string array — the cell contains any of them, case- and accent-insensitive |
+| `is_empty`, `is_not_empty` | none |
+
+```
+{ "node_type": "condition", "field_key": "Title", "operator": "is_any_of", "value": ["hello", "world"] }
+```
+
+A text value is a string, never an array; `is_any_of` matches several. Its array has no length cap —
+pass the whole list in one condition rather than splitting it across calls.
+
+## Number
+
+| Operators | Value |
+|---|---|
+| `equals`, `not_equals`, `greater_than`, `less_than`, `greater_than_or_equal_to`, `less_than_or_equal_to` | a number |
+| `is_empty`, `is_not_empty` | none |
+
+A number whose field states `unit_field` or `currency_field` is read in each row's own unit or
+currency, so a comparison on it states `unit_option`: the option of that select its value is in.
+Rows holding another option are out; measured units of one dimension convert.
+
+```
+{ "node_type": "condition", "field_key": "Amount", "operator": "greater_than", "value": 100, "unit_option": "USD" }
+```
+
+## Boolean
+
+`equals` with `true` or `false`.
+
+## Select
+
+| Operators | Value |
+|---|---|
+| `has_any_of` (any of them — "A or B"), `has_none_of`, `has_all_of` (a multi-select only) | an ARRAY of option names, even for one |
+| `is_empty`, `is_not_empty` | none |
+
+```
+{ "node_type": "condition", "field_key": "Status", "operator": "has_any_of", "value": ["Done", "In Progress"] }
+```
+
+## Member
+
+| Operators | Value |
+|---|---|
+| `has_any_of`, `has_none_of`, `has_all_of` | an array of member ids |
+| `is_current_member`, `is_not_current_member`, `is_empty`, `is_not_empty` | none |
+
+## Date
+
+| Operators | Value |
+|---|---|
+| `before`, `after`, `on_or_before`, `on_or_after`, `on`, `starts_before`, `starts_after`, `ends_before`, `ends_after` | a point |
+| `between`, `overlaps`, `contains`, `within` | `{ start: point \| null, end: point \| null }` |
+| `time_of_day` | `{ start_time: "HH:mm" \| null, end_time: "HH:mm" \| null }` |
+| `duration_equals`, `duration_greater_than`, `duration_less_than` | `{ amount, unit: "minutes" \| "hours" \| "days" }` |
+| `is_empty`, `is_not_empty` | none |
+
+A point is one of:
+
+```
+{ "type": "exact", "date": "2025-03-14", "time": "09:00" }                       time optional
+{ "type": "relative", "offset": -7, "unit": "minutes" | "hours" | "days" | "weeks" | "months" | "years" }
+{ "type": "period", "period": "day" | "week" | "month" | "quarter" | "year", "boundary": "start" | "end", "offset": 0 }
+```
+
+## Link
+
+| Operators | Value |
+|---|---|
+| `has_any_of` (linked to any — filters by record identity), `has_none_of`, `has_all_of` (a multi-link only) | an array of record ids (`rec_…`) |
+| `contains`, `not_contains`, `starts_with`, `ends_with` | a string, matched against the linked record's display text |
+| `is_empty`, `is_not_empty` | none |
+
+```
+{ "node_type": "condition", "field_key": "Customer", "operator": "has_any_of", "value": ["rec_abc123"] }
+```
+
+## Sort
+
+A view's sort is a list, applied in order: `[{ "field_key": "Due", "order": "asc" | "desc" }]`.