@lotics/cli 0.315.18 → 0.316.1

package/docs/workflows.md

@@ -6,13 +6,27 @@ Only the forms below are accepted; anything else is refused at save with the lin
 what to write instead. A save that succeeds may still return `warnings` — advisory hints such as a
 loop that may never end. Read them.
 
-The same grammar serves an automation and an app's workflow, and the expressions of a table check.
-Only an automation's source opens with a trigger declaration; an app workflow takes its trigger from
-the app that calls it.
+A workflow changes records, calls integrations, notifies and makes papers. A tool for anything else — views, history,
+tables and apps, members, knowledge, skills, editing a file — is an agent's, on chat, MCP or the CLI, and a body that
+calls one is refused at save with that reason. One saved before is refused at run, before its first step.
+
+The same grammar serves an app's workflow, which `set_app_workflow` saves, an automation and the expressions of a table
+check. An app workflow takes its trigger from the app that calls it; only an automation's source opens with a trigger
+declaration.
 
 ## Triggers
 
-An automation answers an event outside the records: a schedule, a webhook, an inbound email.
+An app workflow reads its call as `trigger.app_workflow.inputs.<name>`, or `inputs.<name>`, which is the same read. A Workflow node receives the inputs it declares;
+an Act's `workflow` receives `record_id` (`record_ids` on an act over several rows) and what the Act asks.
+
+### Automations
+
+An automation answers an event outside the records: a schedule, a webhook, an inbound email. `set_automation` saves one
+from its source — the `on({...})` declaration, then its steps — and, given its `automation_id`, replaces it: the
+trigger config is the one the header states, a key it leaves out removed, and steps left as it runs them are checked again
+only when the call turns it on, so one a later rule refuses can still be switched off. `get_automation` reads that source back with its latest
+runs, and `dry_run_workflow` rehearses a source before it is saved. It runs with its owner's current permissions, a connected service it names is its owner's account, and only its
+owner or an admin reads, changes or deletes it.
 
 ```
 on({ type: "recurring_schedule", cron_expression: "0 9 * * MON" });
@@ -27,29 +41,13 @@ All three carry `trigger.trigger_id`.
 | `receive_webhook` | `secret`? | `trigger.method`, `trigger.headers[...]`, `trigger.query[...]`, `trigger.body` (any JSON, or raw text when the request is not JSON), `trigger.received_at` |
 | `receive_gmail_email` / `receive_outlook_email` | `connected_account_id`, `filter` | `trigger.email_id`, `trigger.from`, `trigger.to`, `trigger.cc`, `trigger.bcc`, `trigger.subject`, `trigger.date`, `trigger.body` (plain text), `trigger.reply_to`, `trigger.in_reply_to`, `trigger.attachments` (file refs — assign them straight to a files field). One type serves both providers, so `labels`, `thread_id`, `importance` and `conversation_id` are not readable. |
 
-A whole automation:
-
-```
-on({ type: "recurring_schedule", cron_expression: "0 9 * * MON" });
-
-const open = await query_records({
-  table_id: "tbl_tickets",
-  filters: { node_type: "condition", field_key: "fld_status", operator: "has_any_of", value: ["opt_open"] },
-});
-await send_email({
-  to: "team@example.com",
-  subject: "Weekly digest",
-  body: `${size(open.records)} tickets open as of ${formatDate(now(), "yyyy-MM-dd")}.`,
-});
-```
-
 ## Steps
 
 | step | syntax |
 |---|---|
 | tool call, kept | `const <id> = await <tool>({ ...inputs });` — also `let x = await …` and `x = await …` |
-| tool call | `await <tool>({ ...inputs });` — a connection's tools too, each a workflow step (`bkav_submit_invoices`, `gmail_send_email`, …); a step that fails ends the run with its reason unless a `try`/`catch` around it handles it |
-| agent | `const <id> = await agent({ instructions, input, tools, model, output });` — see **An agent step** |
+| tool call | `await <tool>({ ...inputs });` — the platform's own steps (`send_notification`, `generate_document`, …) and a connection's tools, each a workflow step (`bkav_submit_invoices`, `kiotviet_create_order`, …); a step that fails ends the run with its reason unless a `try`/`catch` around it handles it |
+| agent | `const <id> = await agent({ instructions, input, model, output });` — see **An agent step** |
 | app agent | `const <id> = await app_agent({ alias: "<agent alias>", input: { ... } });` — runs one of the app's declared agents, in an app workflow only, and resolves to its declared outputs or its final text. `wait: false` only starts the run and resolves to `{ run_id }`; the run's failure is then its own, not the workflow's. Refused in a run an agent started. |
 | bind | `const <id> = <expression>;` — evaluated once; later steps read `<id>`. Bind any expression used twice. |
 | if / else | `if (<expr>) { ... } else { ... }` — `else` optional, `else if` chains allowed |
@@ -58,16 +56,25 @@ await send_email({
 | wait | `await wait({ duration_in_minutes: 5 });` |
 | wait for an event | `await wait_for_event({ event_type: "webhook", event_ref: <expr>, timeout_in_minutes: 60 });` |
 | wait for an approval | `await wait_for_approval({ approvers: <expr>, prompt: <expr> });` — see **Waiting for an approval** |
-| return | `return({ status: "success" \| "error", message: <expr>, field_errors: { ... }? });` |
+| return | `return({ status: "success" \| "error", message: <expr>, field_errors: { ... }?, data: { ... }? });` — `data` holds the outputs a Workflow node declares |
 | validate | `validate({ checks: [{ fail_when: <expr>, field_key: "...", message: <expr> }, ...] });` |
 
-Every step's inputs, the values each takes and its answer: `lotics tools <name>` prints them; the steps only a body
-runs — a connection's, a mail's — are all in `workflow_steps`. A person connects a service in Lotics under
-Settings → Connections; a step names that connection by its `connected_account_id`.
+A delayed run is never cancelled from a workflow: after a `wait`, it reads the row's state and acts only if it still holds.
+
+A tool's inputs and answer are in its own description; the steps only a body runs — a connection's, a mail's — are each
+an entry of `workflow_steps`. A person connects a service in Lotics under Settings → Connections; a step names that
+connection by its `connected_account_id`, which `get_workspace` with `kind: "connection"` lists for the connections the
+caller can use. The app's owner and whoever saves the body must both be able to use that connection.
+
+In a workflow, email reaches a member of the workspace through the step `send_notification`: Lotics shows it to them and
+mails it to their own address, with no connection. Its recipients are members by `member_id` (`get_workspace` with
+`kind: "member"` lists them), member groups or the whole organization. Mail to anyone else goes from a person's
+connected Gmail or Outlook (`gmail_send_email`, `outlook_send_email`), which leaves an unsent draft unless `draft` is
+`false`.
 
 `return` is a call, not a JavaScript `return` statement. `validate` ends the workflow with an error
 when a check's `fail_when` is truthy; the check's `field_key` names the control its message lands on —
-in an app workflow a declared input, or the `fld_` key of a field on a table the body names; in an
+in an app workflow a declared input, or the alias of a field on a table the body names; in an
 automation it is not checked.
 
 The name in `const x = await tool({...})` is the step's id; later expressions read its output as
@@ -82,8 +89,8 @@ test, a `validate` check — is refused; write the `if`.
 
 **Names are block-scoped, as in JavaScript** — `const`, `let`, loop items and `catch (e)`: sibling
 blocks may reuse a name and an inner block may shadow an outer one. A local may take a helper's name
-(`const size = 3;`), but calling `size(...)` while it is in scope is refused. Tool names, the reserved
-roots, `linked` and `_s` followed by digits cannot be bound.
+(`const size = 3;`), but calling `size(...)` while it is in scope is refused. The names of the tools a
+workflow calls, the reserved roots, `linked` and `_s` followed by digits cannot be bound.
 
 ### Waiting for an approval
 
@@ -112,34 +119,63 @@ is.
 
 ### An agent step
 
-`const x = await agent({ instructions, input, tools, model, output });` runs a model with tools as one
-step — summarize a record, classify, draft text.
+`const x = await agent({ instructions, input, model, output });` runs a model as one step — read a paper, classify,
+draft text. It calls no tool: the workflow's own steps write, send and notify with what it returns, and a step that
+states `tools` is refused.
 
 - `instructions` — a fixed string.
 - `input` — an object literal; its fields are expressions, evaluated and handed to the model (`{}` for
   none). It is the ONLY workflow data the agent sees: read the trigger, prior steps, `runtime` or the loop
-  item here, never inside `instructions` or `tools`, which are fixed literals and read no binding.
-- `tools` — the names of the tools it may call.
+  item here, never inside `instructions`, which is a fixed literal and reads no binding. A field holding a file, or a
+  list of files (a files field, a mail's attachments), hands the agent the files themselves: a picture or a PDF it
+  sees, any other paper read into text.
 - `model` — optional; omit it to follow the platform's default model.
 - `output` — `{ mode: "text" }` resolves to a string; `{ mode: "object", schema }` to a typed object.
 
 Only `x` comes back: in text mode `x` is the string itself, in object mode `x.field` reads a field the
-`schema` declares. The agent's own tool calls are not readable.
-
-## Keys, not names
-
-1. **Fields and options are named by key.** A field reads as `record["fld_status"]`, an option as
-   `"opt_done"`, a linked field as `linked(record["fld_customer"])[0]["fld_name"]`. `get_table` lists
-   each field's `key` and each option's `key`; a display name is refused at save with the key to use.
-2. **`==` against a multi-select means "includes".** `record["fld_tags"] == "opt_urgent"` on a
-   multi-select is stored as `includes(record["fld_tags"], "opt_urgent")`; either spelling works.
-3. **Text renders labels.** Inside a template or a text tool input, a select, member or link value
-   renders its display text: `` `${record["fld_status"]}` `` writes "Done", not `opt_done`.
+`schema` declares.
+
+## Naming tables and templates
+
+A body names a table or document template by its alias (`query_records({ table_id: "orders" })`); ids still work. `get_app_workflow` and `get_automation` show aliases. An app's workflow reaches only the tables the app uses.
+
+## Fields and options
+
+1. **A body names a table's fields and select options by alias**, the names the table's document states: a field reads
+   as `record["status"]`, an option as `"done"`, a linked field as `linked(record["customer"])[0]["name"]`, in the
+   body of a Workflow node, of an Act's own `workflow`, of an automation (`set_automation`) and of a table's workflow. It is stored by key and `get_app_workflow`, `get_automation` and `get_table` show it by alias
+   again. A field's or option's key is accepted where its alias is and is kept as written; a display name is refused with the
+   aliases there are, and a row that names one field by both its alias and its key is refused. A row written to a table is
+   stored by field key wherever the save can follow it to the record tool that writes it: a row or list written in the call,
+   a conditional of them, a name holding them, pushed to a `let`, and through `map`, `flatMap`, `concat`, `filter`, `sortBy`,
+   `slice` and `reverse`. A field of such rows is read by alias as well (`picks.toSorted((a, b) => a.quantity - b.quantity)`,
+   `sortBy(picks, "quantity")`, `rows[0].note`) and stored by key. A body that cannot be stored by key is refused at save,
+   naming the statement.
+2. **An Act's own `workflow`** has the app's guards placed at the top of the body, between `<lotics:guards>` tags,
+   replaced on every save: a save that leaves them out or edits them gets the app's again, at the top wherever the tags
+   sat, so the act's row rule, `when`, `requires`, checks and locks always run first.
+3. **A value is read as the record tools store it.** A single select reads as its option and a member as its id; an
+   option is written by its alias wherever it meets a select — compared, listed, switched on, written — also beside a
+   name set from the field (`const s = record.status; s == "done"`), and a select
+   value handed on whole (returned, written to a text field) is its key. An option's alias searched for in a list the
+   save cannot place it against (`includes(filter(record.tags, …), "hot")`) is refused: search the field itself. A link reads as the list of its row ids, a
+   one-row link too: `first(record.customer)` is the one id, and `record.customer` used as one id is refused at save,
+   naming `first(record.customer)`. A one-row link is written with its one id or a list of one; a many-row link with a list. A lookup reads as one flat list of the values it looks up: `includes(record.owner,
+   me)`. A select's value is one of another select's options only where that table shares its keys, by having been
+   duplicated from it, not where an option merely shares its alias. A row that takes its parent's option gets it from
+   `default_from`, and a lookup shows it.
+4. **What an app sends takes an option by alias or key.** An input or output drawn from a field (`field`, written
+   `<table id>.<alias>`) compares and returns by alias in the body, and the run hands it on as the option's key. A
+   refusal's `field_errors` and a `validate` check's `field_key` name a declared input or a field's alias.
+5. **`==` against a multi-select means "includes".** `record["tags"] == "urgent"` on a multi-select is stored as
+   `includes(record["tags"], "urgent")`; either spelling works.
+6. **Text renders labels.** Inside a template or a text tool input, a select, member or link value renders its display
+   text: `` `${record["status"]}` `` writes "Done", not `done`.
 
 ## What an expression reads
 
 - `record`, `prev_record`, `changes` — in a table check, the write it checks (see **Table checks**).
-  `changes` is a PARTIAL map: `changes["fld_x"]?.next_value` and `?.prev_value`, the `?.` required.
+  `changes` is a PARTIAL map: `changes["x"]?.next_value` and `?.prev_value`, the `?.` required.
 - `trigger` — what the trigger carries (see **Triggers**).
 - a loop's item name, and `index`, the iteration's 0-based index.
 - `<step id>` — an earlier step's output (`dup.records`).
@@ -149,17 +185,18 @@ Only `x` comes back: in text mode `x` is the string itself, in object mode `x.fi
 
 ## Paths
 
-- `record.fld_x` and `record["fld_x"]` read a field; `[n]` reads a list's n-th item.
-- A path may start at an awaited call: `(await get_record({...})).data["fld_x"]`. It may not start at a
-  helper's result — `first(found.records).id` is refused; bind `first(found.records)`, then read it.
+- `record.x` and `record["x"]` read a field; `[n]` reads a list's n-th item.
+- A path may start at any expression: an awaited call `(await get_record({...})).data["x"]`, a helper's
+  result `first(found.records).id`, a filter `rows.filter((r) => r.ok)[0].n`, a `(a ?? b).c`. `?.` reads
+  through a null as usual, except on a value drawn at random (`sample(xs)?.id` is refused: bind it first).
 - A record reads in its declared shape wherever it comes from — the trigger, a tool result, a `let`, a
-  callback parameter: a single select or member as its key or null, a link as its ids. (The record
+  callback parameter: a single select as its option alias or null, a member as its id, a link as its ids. (The record
   tools called outside a workflow return the stored arrays instead.)
-- `linked(record["fld_link"])[n]["fld_x"]` fetches the n-th linked row and reads a field of it; bare
-  `linked(record["fld_link"])` is every linked row, one fetch per row. Its argument is a path ending on
-  a link field and carries the guard: `linked(record?.["fld_link"])[0]`.
-- `changes["fld_link"]?.next_value` is the same list of ids; `linked()` over a change is refused —
-  read `linked(record["fld_link"])` or `linked(prev_record["fld_link"])`.
+- `linked(record["link"])[n]["x"]` fetches the n-th linked row and reads a field of it; bare
+  `linked(record["link"])` is every linked row, one fetch per row. Its argument is a path ending on
+  a link field and carries the guard: `linked(record?.["link"])[0]`.
+- `changes["link"]?.next_value` is the same list of ids; `linked()` over a change is refused —
+  read `linked(record["link"])` or `linked(prev_record["link"])`.
 
 ## Operators and statements
 
@@ -174,9 +211,9 @@ prefix `! -`.
 - `??` is `coalesce(left, right)`; `?.` reads through a null (`a?.b`, `a?.[0]`, and `s?.trim()` for the
   method names listed under **Helpers**). `x?.()` is refused: helpers and tools are not values.
 - Templates use backticks and `${...}`.
-- Destructuring — `const { fld_status, fld_name } = record;` binds each name. Renames
-  (`{ fld_status: s }`), quoted keys (`{ "fld_ref": ref }`), array patterns with holes
-  (`const [first, , third] = xs;`) and defaults (`{ fld_note = "" }`, which apply on null too) work on
+- Destructuring — `const { status, name } = record;` binds each name. Renames
+  (`{ status: s }`), quoted keys (`{ "ref": ref }`), array patterns with holes
+  (`const [first, , third] = xs;`) and defaults (`{ note = "" }`, which apply on null too) work on
   `const`, `let` and `for (const { id } of rows)`. A tool result destructures directly:
   `const { records } = await query_records({...});`. `const a = 1, b = 2;` declares both. Nested
   patterns and rest are refused.
@@ -186,9 +223,11 @@ prefix `! -`.
 - `xs.push(a, b);` appends, also on a key (`o.items.push(v)`); `o.a.b = v;` sets a nested key;
   `x ??= v`, `x ||= v` and `x &&= v` assign. A `const` may be pushed to or have a key set, as in
   JavaScript; a loop item is read-only.
-- `undefined` is the same value as `null`. `=== undefined` and `!== undefined` are refused, since they
-  cannot tell a missing key from null: test `isNull(x)`, or `includes(keys(o), "k")` for whether a key
-  was sent.
+- `undefined` is the same value as `null`, so `x === undefined` is `isNull(x)` and `x !== undefined` is
+  `isNotNull(x)`; a key set to null and a key never sent are not told apart (`"k" in o` tells a key that
+  is there).
+- `typeof x` answers JavaScript's words, and a null (a missing value too) is `"object"`. `k in o` tests an
+  object's own keys, or a list's indexes and `length`.
 - A filter node may leave out `node_type` when its keys say which it is: `field_key` / `operator` /
   `value` a condition, `logic` / `children` a group, `path` / `condition` a traversal.
 - `function name(p = <default>) { return <expr>; }` — top level only, expanded at every call (a call
@@ -211,16 +250,52 @@ on the innermost loop; labels and `for-in` are refused.
 the same block is refused; shadowing in a nested block is allowed. A `let` keeps its value across a
 `wait`, `wait_for_event` or `wait_for_approval`.
 
-**Refused:** regex, `new`, `typeof`, `instanceof`, `in`, `delete`, `void`, rest elements, computed keys,
-classes, `throw`, `import`, `export`, and a function as a value (`const f = (x) => ...`).
+**Refused, each because a save must know what runs and a run must give the same answer twice:** regex
+(unbounded matching: use the string methods), `Math.random`, `Date.now()` and `new Date()` (use `now()` and
+`parseDate`), a tool or helper as a value or a computed callee (callees are named), `new` of anything,
+`instanceof`, `delete`, `void`, rest elements, computed keys, classes, `throw`, `finally`, `import`,
+`export`, `eval`, labels, and a function as a value (`const f = (x) => ...`: pass the arrow to the helper
+that takes it). `xs.sort(...)` on a name or path is refused too, since a value is never changed in place:
+write `xs.toSorted(...)` or `[...xs].sort(...)`.
+
+## Typing
+
+- The body is type-checked as TypeScript before it is read: annotations, `as`, `satisfies` and a non-null `!`
+  are accepted and erased, and the checker is strict about null. The stored body keeps none of them and is checked again as
+  stored, by field key, as every later change to its app or tables checks it: a body that types only through one of them is
+  refused at save.
+- Narrow what is not typed (a connector's JSON is `unknown`) with `typeof`, `in`, `Array.isArray` and `isNull`.
+- `first(xs)` may be undefined; `requireFirst(xs)` is the list's first item or an error.
+- `obj[key]` needs `key` to be a key of `obj`, or `obj` to be a record with a string index.
 
 ## Helpers
 
-Called as `size(arr)`. The method form works only where the name is also a JavaScript method —
+Ordinary JavaScript works — the standard library below, the array and string methods, `Math`, `JSON`,
+`Object`, `Array`, `Number`, `parseInt` — and means what it means in JavaScript, with the differences
+listed here. Where JavaScript answers NaN, Infinity or undefined, a workflow has none of them and the
+answer is `null`.
+
+- Standard library: `Math.abs/ceil/floor/trunc/sign/min/max/pow/sqrt`, `Number(x)`, `String(x)`,
+  `Boolean(x)`, `parseInt(s, radix?)`, `parseFloat(s)`, `Number.isFinite/isInteger`,
+  `Object.keys/values/entries/fromEntries`, `Array.isArray/from` (a list, text, or `{ length: n }`),
+  `JSON.parse/stringify`.
+- Arrays: `length, map, filter, find, findIndex, findLast, some, every, reduce, includes, indexOf, join,
+  slice, concat, flat, flatMap, at, reverse, toReversed, toSorted` and `[...xs].sort(compare?)`.
+- Strings: `length, toLowerCase, toUpperCase, trim, trimStart, trimEnd, startsWith, endsWith, includes,
+  indexOf, slice, substring, split, replace, replaceAll, padStart, padEnd, repeat, charAt, at,
+  localeCompare` (en-US order, wherever it runs). Numbers: `toFixed, toString`.
+- Differences from JavaScript: `Math.round` is the engine's `round` (a half goes away from zero:
+  `Math.round(-2.5)` is `-3`); `Number(x)` and `parseFloat(x)` are `toNumber`, which refuses text that is no
+  number; `String(null)` is `""`; `join` writes a null item as `null`; `concat` skips a null; `toFixed`
+  rounds the decimal, not the binary double; `replaceAll` writes the replacement as text
+  (`$&` stays as typed), while `replace` expands `$&`, `$$`, `` $` `` and `$'` in it as JavaScript does; `split` takes no limit; `sort` without a comparator orders by text, as JavaScript does. `==`, `!=`, `===` and `!==` between two list values (files, a multi-select, a link of any cardinality, a lookup) are refused at save, since a list compares by identity, not by its items: `!isNull(changes.<field>)` asks whether one changed.
+
+The same work can be written with the helpers below, which are additions to JavaScript. They are called as
+`size(arr)`; the method form works only where the name is also a JavaScript method —
 `x.trim()`, `arr.includes(v)`, `arr.at(-1)`, `arr.map(fn)`, `s.split(",")`; `arr.size()` is refused.
 
 - **Null and type**: `isNull`, `isNotNull`, `isEmpty`, `isString`, `isNumber`, `isBoolean`, `isArray`,
-  `isObject`, `coalesce`, `get`, `toNumber`, `toString`, `typeOf`, `parseJson`, `toJson`
+  `isObject`, `coalesce`, `get`, `toNumber`, `toFigure`, `toString` (a text, number, yes/no or date; a record, file or list is refused at save, an object at run), `typeOf`, `parseJson`, `toJson`. `isNull` is strict (`null` and `undefined` only), but on a list field of the record (a link, files, a multi-select) it asks whether the list holds nothing, since a cleared list is `[]`: `!isNull(record.vehicle)` reads as `!isEmpty(record.vehicle)`. `isNull(changes.<field>)` stays strict: null there means unchanged
 - **Lists**: `size`, `first`, `requireFirst` (the first item, refusing an empty list — after a
   `validate` on the size it saves an `if`), `last`, `nth`, `at` (`at(arr, -1)` counts from the end),
   `includes`, `filter`, `find`, `some`, `every`, `pluck`, `sortBy`, `groupBy`, `countBy`, `unique`,
@@ -230,19 +305,24 @@ Called as `size(arr)`. The method form works only where the name is also a JavaS
 - **Math**: `sum`, `sumBy`, `mean`, `meanBy`, `minBy`, `maxBy`, `round`, `ceil`, `floor`, `min`, `max`,
   `abs`, `mod`, `pow`, `sqrt`, `clamp`, `percentage`
 - **Text**: `upper`, `lower`, `capitalize`, `trim`, `contains`, `startsWith`, `endsWith`, `replace`,
-  `replaceAll`, `substring`, `length`, `split`, `join`, `padStart(str, length, char)`,
+  `replaceAll`, `removeChars(str, chars)` (without every character that occurs in `chars`),
+  `removeSpaces(str)` (without any whitespace; a Word template command calls both too), `substring`, `length`, `split`, `join`, `padStart(str, length, char)`,
   `padEnd(str, length, char)`, `formatNumber(x, decimals)` (ungrouped; rounds the decimal, a half away
   from zero: `formatNumber(1.005, 2)` is `1.01`),
   `formatDecimal(x, decimals, locale)` (grouped: `formatDecimal(151000, 0, "vi-VN")` is `151.000`),
-  `numberToWords(x, lang?)` (an integer in words: Vietnamese, or English with `"en"`)
+  `numberToWords(x, lang?)` (an integer in words: Vietnamese, or English with `"en"`),
+  `uuidFrom(text)` (the same UUID for the same text, refusing null and empty text: `uuidFrom(record.id)`)
 - **Objects**: `keys`, `values`, `entries`, `nonNullKeys`, `pick`, `omit`, `merge`
 - **Dates**, in the workspace's timezone: `now`, `formatDate`, `parseDate`, `addDays`, `subDays`,
   `addHours`, `subHours`, `addMinutes`, `subMinutes`, `startOfDay`, `endOfDay`,
   `differenceInCalendarDays`, `differenceInHours`, `differenceInMinutes`, `isBefore`, `isAfter`,
-  `isSameDay`, `isToday`, `isWithinRange`
+  `isSameDay`, `isToday`, `isWithinRange`, `meetsBounds`
 - **Other**: `formatCurrency(amount, locale, currency)`, `randomNumber(len)`,
   `randomAlphaNumeric(len)`, `sample(items)` (a random item)
 
+Over a null or empty list `mean`, `meanBy`, `min`, `max`, `minBy` and `maxBy` answer null, while `sum`
+and `sumBy` answer 0: `maxBy(pieces, "reach")?.Name` prints a blank for a month with no pieces.
+
 A date helper given a null or empty date returns null, so guard its result before comparing or
 writing it: `differenceInCalendarDays(a, b) ?? 0`.
 
@@ -261,12 +341,12 @@ rows once, then read each group by its key. `groupBy` answers an object of lists
 is the group a code names, or an empty list:
 
 ```
-const parties = await query_records({ table_id: "tbl_parties" });
-const lines = await query_records({ table_id: "tbl_sheet_lines" });
-const byCode = groupBy(parties.records, (p) => p.data["fld_code"] ?? "");
+const parties = await query_records({ table_id: "parties" });
+const lines = await query_records({ table_id: "sheet_lines" });
+const byCode = groupBy(parties.records, (p) => p.data["code"] ?? "");
 const holders = lines.records.map((line) => ({
   line: line.id,
-  parties: (byCode[line.data["fld_code"] ?? ""] ?? []).map((p) => p.id),
+  parties: (byCode[line.data["code"] ?? ""] ?? []).map((p) => p.id),
 }));
 ```
 
@@ -281,7 +361,7 @@ In `update_records`' `set` and `create_records`' `records`:
 - `null` clears the field.
 - `undefined`, or leaving the key out, leaves the field as it is.
 
-So passing a read that may be null (`record["fld_x"]`) keeps a value when there is one and clears the
+So passing a read that may be null (`record["x"]`) keeps a value when there is one and clears the
 field when there is none. Use `coalesce(x, fallback)` only for a real fallback value.
 
 ## Examples
@@ -291,13 +371,13 @@ string is a type error:
 
 ```
 const found = await query_records({
-  table_id: "tbl_customers",
-  filters: { node_type: "condition", field_key: "fld_name", operator: "equals", value: "ACME Corp" },
+  table_id: "customers",
+  filters: { node_type: "condition", field_key: "name", operator: "equals", value: "ACME Corp" },
 });
 const customer = first(found.records);
-const order = await get_record({ table_id: "tbl_orders", record_id: trigger.app_workflow.inputs.order_id });
+const order = await get_record({ table_id: "orders", record_id: trigger.app_workflow.inputs.order_id });
 
-if (customer && includes(order.data["fld_customer"], customer.id)) {
+if (customer && includes(order.data["customer"], customer.id)) {
   // …
 }
 ```
@@ -314,11 +394,11 @@ A sheet past what one call reads is refused with its size, never cut short: the
 names the fields that identify a row, compared as trimmed text with case ignored: a row matching no live
 row is added, one matching a row changes only the cells that differ, and one that changes nothing is
 counted and not written, so the same file run twice writes nothing the second time. `values` holds a
-row's cells by field key, as `create_records` takes them; a key the row omits is left as the table holds
-it, and `null` is an empty cell, which differs from a filled one as any other value does.
+row's cells by field alias, as `create_records` takes them; a key the row omits is left as the table holds
+it, and `null` is an empty cell, which differs from a filled one as any other value does. `dry_run: true` judges the import as a real one would be, rolls it back and answers what it would write or why it is refused.
 
 A `match` field may also be a link field holding one row, compared by the row linked: lines keyed by
-their parent and a line number state `match: ["fld_invoice", "fld_line"]`, the parent given as its
+their parent and a line number state `match: ["invoice", "line"]`, the parent given as its
 record id or as `{ lookup: "<text>" }`.
 
 What the step is not certain of is held — answered with why, and not written: a row carrying `hold`
@@ -352,25 +432,15 @@ reach of the table, and a workflow hands its caller only what it returns. Two ca
 by the same fields take turns, so the second matches the rows the first added. The step's entry in
 `workflow_steps` states its bounds.
 
-`undo_record_changes`, a workflow step, puts back what one run wrote on records of a table. It takes the
-table, up to 500 record ids and the run — what `runtime.execution_id` held in it. A field goes back
-where the row still holds what the run wrote. A row the run created goes to the trash
-where nothing else has written it or linked a row to it since; in a table where a workflow writes each
-new row, every row created reads as written since, and is kept. A row the run moved to the trash comes
-back where nothing has touched it since, without the links to it that its removal took off other rows.
-A row the run brought back from the trash stays out of it. A write of the run that was itself an undo is
-not put back. What the step leaves as it stands is answered in `kept`, one entry a record and reason:
-something changed it since, it is outside the rows the member may write, the table refused the write,
-what the run wrote on it cannot be read, or the run brought it back from the trash.
-
-Two more workflow steps read and settle one record's saves: `get_record_activity`, a workflow step,
-lists them, and `undo_record_change`, a workflow step, puts one back. What they read is the run's to
-read; inside an app's workflow it is what the app reads — the fields of the app's entity over the table,
-a record that entity's own read reaches. An undo, of one save or of a run's writes, is the own save of the
-member the run acts for — whoever started the app's workflow, pressed the button, or made the write a
-table's workflow followed: that member holds the table's write as the step runs, each row within the
-rows they may write, and the table's locks, checks and write rules answer for them. A run that acts for
-no member — a schedule's, a public visitor's — reads, and its undos are refused.
+A workflow does not put an import back: that reads the history of what the run wrote, which a member's agent reads
+under the member's own access to the table and no workflow does. On chat, MCP or the CLI, `undo_record_changes` takes the
+table, up to 500 record ids and the run — what `runtime.execution_id` held in it, which a body keeps on a row of its own —
+and puts back what that run wrote, as the member's own writes. A field goes back where the row still holds what the run
+wrote. A row the run created goes to the trash where nothing else has written it or linked a row to it since; in a table
+where a workflow writes each new row, every row created reads as written since, and is kept. A row the run moved to the
+trash comes back where nothing has touched it since. A row the run brought back from the trash stays out of it. What the
+tool leaves as it stands is answered in `kept`, one entry a record and reason. `undo_record_change` puts back one edit
+named by its audit-log entry, the same way.
 
 What a business keeps of an import — the file, its counts, the lines waiting for a person — is rows of
 its own tables, written by the workflow that ran the step. A garden centre brings its grower's price
@@ -379,8 +449,8 @@ holding many rows: one holding a single row would make the line that plant's own
 lines belong to is not moved to the trash.
 
 These tables are shown beside the plants, in the same app: the sheets as a log of the plants' register
-(`logs`, `lotics docs model/logs`), a sheet's lines on the page it opens. A line keeping what a cell held
-and what it holds now in two fields reads one against the other (`compare`, `lotics docs model/blocks`).
+(a further List at the root, `model/app-node`), a sheet's lines on the page it opens. A line keeping what a cell held
+and what it holds now in two fields reads one against the other (`compare`, `model/list-node`).
 
 ```
 const sheet = await excel_get_rows({ // a workflow step
@@ -389,57 +459,57 @@ const sheet = await excel_get_rows({ // a workflow step
 });
 
 const imported = await import_rows({ // a workflow step
-  table_id: "tbl_plants",
-  match: ["fld_code"],
+  table_id: "plants",
+  match: ["code"],
   rows: sheet.rows.map((row, at) => ({
     line: at + 2,
     hold: isNull(row["Price"]) ? "The sheet states no price" : null,
     values: {
-      fld_code: toString(row["Code"]),
-      fld_name: toString(row["Name"]),
-      fld_price: toNumber(row["Price"]),
+      code: toString(row["Code"]),
+      name: toString(row["Name"]),
+      price: toNumber(row["Price"]),
     },
   })),
 });
 
 const kept = await create_records({
-  table_id: "tbl_price_sheets",
+  table_id: "price_sheets",
   records: [{
-    fld_file: [trigger.app_workflow.inputs.file],
-    fld_run: runtime.execution_id,
-    fld_read: imported.read,
-    fld_created: imported.created,
-    fld_changed: imported.changed,
-    fld_held: imported.held,
+    file: [trigger.app_workflow.inputs.file],
+    run: runtime.execution_id,
+    read: imported.read,
+    created: imported.created,
+    changed: imported.changed,
+    held: imported.held,
   }],
 });
 const sheet_id = kept.record_ids[0];
 
 for (let start = 0; start < size(imported.written); start += 50) {
   await create_records({
-    table_id: "tbl_sheet_lines",
+    table_id: "sheet_lines",
     records: slice(imported.written, start, start + 50).map((one) => ({
-      fld_sheet: [sheet_id],
-      fld_plant: [one.record_id],
-      fld_line: one.line,
-      fld_outcome: one.kind,
-      fld_changes: join(one.changes.map((change) => `${change.label}: ${change.before ?? "—"} → ${change.after ?? "—"}`), "; "),
+      sheet: [sheet_id],
+      plant: [one.record_id],
+      line: one.line,
+      outcome: one.kind,
+      changes: join(one.changes.map((change) => `${change.label}: ${change.before ?? "—"} → ${change.after ?? "—"}`), "; "),
     })),
   });
 }
 for (let start = 0; start < size(imported.held_rows); start += 50) {
   await create_records({
-    table_id: "tbl_sheet_lines",
+    table_id: "sheet_lines",
     records: slice(imported.held_rows, start, start + 50).map((one) => ({
-      fld_sheet: [sheet_id],
-      fld_plant: isNull(one.record_id) ? [] : [one.record_id],
-      fld_line: one.line,
-      fld_outcome: "held",
-      fld_why: one.message,
-      fld_code: one.key["fld_code"],
-      fld_name: toString(one.values["fld_name"]),
-      fld_price: toNumber(one.values["fld_price"]),
-      fld_changes: join(one.changes.map((change) => `${change.label}: ${change.before ?? "—"} → ${change.after ?? "—"}`), "; "),
+      sheet: [sheet_id],
+      plant: isNull(one.record_id) ? [] : [one.record_id],
+      line: one.line,
+      outcome: "held",
+      why: one.message,
+      code: toString(sheet.rows[coalesce(one.line, 2) - 2]["Code"]),
+      name: toString(sheet.rows[coalesce(one.line, 2) - 2]["Name"]),
+      price: toNumber(sheet.rows[coalesce(one.line, 2) - 2]["Price"]),
+      changes: join(one.changes.map((change) => `${change.label}: ${change.before ?? "—"} → ${change.after ?? "—"}`), "; "),
     })),
   });
 }
@@ -447,22 +517,23 @@ for (let start = 0; start < size(imported.held_rows); start += 50) {
 return({ status: "success", message: `${imported.created} added, ${imported.changed} changed, ${imported.held} held` });
 ```
 
-A held line keeps the `values` the step answered for it — its key and each cell it would write — in
-fields of its own. It is applied by the act on it, whose workflow hands the step those values again and
+A held line keeps the cells the sheet states for it, found by the `line` the step answered, in
+fields of its own. A held row's `key` and `values` name fields by their keys, as every record a step answers a body does, so
+the body reads the sheet again rather than those names. It is applied by the act on it, whose workflow hands the step those values again and
 lets it write over what the plant holds. A cell the line holds none of is left out, so a held line
 never empties a cell of the plant:
 
 ```
-const line = await get_record({ table_id: "tbl_sheet_lines", record_id: trigger.app_workflow.inputs.record_id });
+const line = await get_record({ table_id: "sheet_lines", record_id: trigger.app_workflow.inputs.record_id });
 const values = {
-  fld_code: line.data["fld_code"],
-  ...(isEmpty(line.data["fld_name"]) ? {} : { fld_name: line.data["fld_name"] }),
-  ...(isNull(line.data["fld_price"]) ? {} : { fld_price: line.data["fld_price"] }),
+  code: line.data["code"],
+  ...(isEmpty(line.data["name"]) ? {} : { name: line.data["name"] }),
+  ...(isNull(line.data["price"]) ? {} : { price: line.data["price"] }),
 };
 
 const applied = await import_rows({ // a workflow step
-  table_id: "tbl_plants",
-  match: ["fld_code"],
+  table_id: "plants",
+  match: ["code"],
   conflicts: { default: "overwrite" },
   rows: [{ values }],
 });
@@ -470,47 +541,12 @@ if (applied.held > 0) {
   return({ status: "error", message: applied.held_rows[0].message });
 }
 
-await update_records({ table_id: "tbl_sheet_lines", record_ids: [line.id], set: { fld_outcome: "applied" } });
+await update_records({ table_id: "sheet_lines", record_ids: [line.id], set: { outcome: "applied" } });
 return({ status: "success", message: "Applied." });
 ```
 
-A sheet is undone by the act on it, whose workflow hands the step the run the sheet kept and the
-plants its lines name, 500 at a time:
-
-```
-const sheet = await get_record({ table_id: "tbl_price_sheets", record_id: trigger.app_workflow.inputs.record_id });
-
-let reverted = 0;
-let left = 0;
-let offset = 0;
-let more = true;
-while (more) {
-  const lines = await query_records({
-    table_id: "tbl_sheet_lines",
-    filters: {
-      logic: "and",
-      children: [
-        { field_key: "fld_sheet", operator: "has_any_of", value: [sheet.id] },
-        { field_key: "fld_outcome", operator: "is_any_of", value: ["created", "changed"] },
-      ],
-    },
-    pagination: { offset, limit: 500 },
-  });
-  if (size(lines.records) > 0) {
-    const undone = await undo_record_changes({ // a workflow step
-      table_id: "tbl_plants",
-      record_ids: flatten(lines.records.map((line) => line.data["fld_plant"])),
-      workflow_execution_id: toString(sheet.data["fld_run"]),
-    });
-    reverted += undone.reverted;
-    left += size(undone.kept);
-  }
-  more = size(lines.records) == 500;
-  offset += 500;
-}
-
-return({ status: "success", message: `${reverted} put back, ${left} left as they stand` });
-```
+A sheet is put back by a member's agent on chat, MCP or the CLI: `undo_record_changes` over the plants its lines name,
+500 at a time, with the run the sheet kept.
 
 A shop matches a bank statement to the notes it is owed by an act that states `review`. That act's workflow only
 proposes: its body calls steps that read and no other, and runs no agent — either is refused when the body is saved —
@@ -530,7 +566,7 @@ Each row's `data` holds only stored fields that change — never one the platfor
 a `note` and a `ticked` the reader starts from, and `unplaced` lists what was read and matched nothing. Every approved
 row is checked against its fields before any is written, and they are written in one transaction, so a flawed one
 writes none. The status history of every row written that moved, or was made holding a status, is recorded in the
-same run, so the workflow step `undo_record_changes` with the run's id takes back both. A body that stops proposing a row once it is
+same run. The answer's `applied.previous` holds what each updated record's written fields held before, so one `update_records` of it puts the values back, and `delete_records` of a `created` record takes that row away. A body that stops proposing a row once it is
 written — it matches against what the rows hold now — makes approving twice write once.
 
 ```
@@ -541,13 +577,13 @@ const sheet = await excel_get_rows({ // a workflow step
   columns: ["Reference", "Amount", "Paid on"],
 });
 const unpaid = await query_records({
-  table_id: "tbl_notes",
-  filters: { field_key: "fld_paid_on", operator: "is_empty" },
+  table_id: "notes",
+  filters: { field_key: "paid_on", operator: "is_empty" },
   pagination: { offset: 0, limit: 500 },
 });
 const acted = groupBy(inputs.record_ids, (id) => toString(id));
 const owed = filter(unpaid.records, (one) => size(acted[toString(one.id)] ?? []) > 0);
-const byRef = groupBy(owed, (one) => toString(one.data["fld_ref"]));
+const byRef = groupBy(owed, (one) => toString(one.data["ref"]));
 
 const lines = sheet.rows.map((line) => ({
   line,
@@ -556,8 +592,8 @@ const lines = sheet.rows.map((line) => ({
 const updates = filter(lines, (one) => !isNull(one.note)).map((one) => ({
   record_id: toString(one.note?.id),
   note: `Transfer of ${toString(one.line["Amount"])}`,
-  ticked: toNumber(one.line["Amount"]) == one.note?.data["fld_amount"],
-  data: { fld_paid_on: toString(one.line["Paid on"]) },
+  ticked: toNumber(one.line["Amount"]) == sumBy(filter(owed, (owing) => owing.id == one.note?.id), (owing) => coalesce(owing.data["amount"], 0)),
+  data: { paid_on: toString(one.line["Paid on"]) },
 }));
 const unplaced = filter(lines, (one) => isNull(one.note)).map((one) => ({
   title: `${toString(one.line["Reference"])}: ${toString(one.line["Amount"])}`,
@@ -567,7 +603,7 @@ const unplaced = filter(lines, (one) => isNull(one.note)).map((one) => ({
 return({
   status: "success",
   message: `${size(updates)} of ${size(lines)} transfers match a note`,
-  data: { review: { version: 1, table_id: "tbl_notes", creates: [], updates, unplaced } },
+  data: { review: { version: 1, table_id: "notes", creates: [], updates, unplaced } },
 });
 ```
 
@@ -606,16 +642,16 @@ const sheet = await excel_get_rows({ // a workflow step
 });
 
 const saved = await save_record({ // a workflow step
-  table_id: "tbl_release_orders",
-  match: { fld_number: inputs.number },
-  set: { fld_note: "Read from the paper" },
+  table_id: "release_orders",
+  match: { number: inputs.number },
+  set: { note: "Read from the paper" },
   lines: [{
-    table_id: "tbl_release_lines",
-    link: "fld_order",
-    match: ["fld_size"],
+    table_id: "release_lines",
+    link: "order",
+    match: ["size"],
     rows: sheet.rows.map((row) => ({
-      fld_size: toString(row["Size"]),
-      fld_quantity: toNumber(row["Quantity"]),
+      size: toString(row["Size"]),
+      quantity: toNumber(row["Quantity"]),
     })),
   }],
 });
@@ -627,6 +663,43 @@ return({
 });
 ```
 
+## Reaching a connected service
+
+A service is reached only by a workflow step, and a step is called inside an app's workflow or an automation. From
+nothing to an app's run:
+
+1. `get_workspace` with `kind: "connection"` lists each `connected_account_id`.
+2. `set_app` declares a Workflow node that states what a call takes and hands back:
+
+```json
+{
+  "type": "Workflow",
+  "key": "invoice_order",
+  "description": "Issues the KiotViet invoice for a confirmed order and hands back its code.",
+  "inputs": { "order": { "type": "record_link", "entity": "order" } },
+  "outputs": { "invoice_code": { "type": "text" } }
+}
+```
+
+3. `set_app_workflow` with the app, the alias `invoice_order` and this `source` (the step's entry is in `workflow_steps`):
+
+```
+const order = await get_record({ table_id: "orders", record_id: trigger.app_workflow.inputs.order });
+const made = await kiotviet_create_invoice({ // a workflow step
+  connected_account_id: "cac_…",
+  branch_id: 1,
+  sold_by_id: 7,
+  lines: [{ product_id: 42, quantity: toNumber(order.data["quantity"]), price: toNumber(order.data["price"]) }],
+});
+return({ status: "success", message: "Invoiced", data: { invoice_code: made.invoice.code } });
+```
+
+4. `run_app_workflow` with `dry_run: true`, then the same call without it.
+
+A step wants the provider's own ids (`branch_id`, `sold_by_id`, `product_id`) and no tool lists them: declare a Workflow
+whose body calls the provider's `list_*` workflow step (`kiotviet_list_branches`), run it, and read the ids from its answer.
+No step lists KiotViet's users: read `sold_by_id` off a row `kiotviet_list_invoices` returns (KiotViet's `soldById`), or ask the owner.
+
 ## Table checks
 
 A table check is one condition its table's record writes must not meet, declared beside the table's
@@ -635,54 +708,181 @@ cannot change data. It runs inside the write, on every create, update or delete
 surface makes it — a person, the API, the CLI, an agent, a workflow. A refusal writes nothing and
 answers with the check's message, under its field when the check names one, and names the check.
 
-On the CLI or in chat, `set_table_check` creates one, or changes one when given its `table_check_id`
-and only the parts that change, and `remove_table_check` removes one. `get_table` lists a table's
-checks in the source they are written in.
+A check is stated in its table's document, under `checks`, each under an alias of its own, and
+`set_tables` writes it with the rest of the table: a merge patch edits one, `null` removes it, and a
+call that makes a table can state its checks, a lookup naming another table of the call by its `ref`.
+`get_table` states a table's checks in its document.
 
 | part | what it holds |
 |---|---|
 | `on` | the writes it checks: any of `create`, `update`, `delete` |
 | `when` | optional expression; the check runs only on a write where it is truthy. It cannot read lookups. |
-| `lookups` | optional, by name, the rows to read: `{ table_id, filter, limit }`, the filter as `query_records` takes it, `limit` from 1 to 50 (50 when left out). A filter value may read the record. |
+| `lookups` | optional, by name, the rows to read: `{ table, filter, limit }`, `table` an id or the `ref` of a table of the call, the filter as `query_records` takes it with fields and select options named by alias (`id` matches a row by its own record id), `limit` from 1 to 50 (50 when left out). A filter value that reads the record is `{ "$expr": "record.code" }`. |
 | `fail_when` | expression; truthy refuses the write |
 | `message` | expression for the refusal's text — a fixed text is a quoted string |
-| `field_key` | optional; the field the refusal is shown under |
+| `field` | optional; the alias of the field the refusal is shown under |
+| `enabled` | `false` keeps the check without deciding writes; absent, it decides |
 
-Every expression is written in the grammar above and reads:
+Every expression is written in the grammar above, names a table's fields and select options by
+alias (`record.status == "closed"`), and reads:
 
 - `record` — the record as it will be stored; on a delete, the record being deleted.
 - `prev_record` — on an update or a delete, the record before.
-- `changes` — on an update, the fields it changes.
-- `lookups.<name>` — in `fail_when` and `message`, the rows that lookup read.
+- `changes` — on an update, the fields it changes. `!isNull(changes.photos)` asks whether a field changed.
+- `lookups.<name>` — in `fail_when` and `message`, the rows that lookup read. A row reads as `record` does: its fields by alias beside `id` (`row.start_on`), and a lookup field as the flat list of what it looks up (`first(row.booking_start)` through a one-row link). A lookup over the written table never returns the row being checked, and finds its other rows as the write leaves them, this call's other rows included. A field given to a helper as text names it by alias too (`sumBy(lookups.paid, "amount")`); text that names no field of the rows' table is refused when the check is saved.
 - `runtime.timezone`, `runtime.workspace_id`, `runtime.organization_id`, `runtime.change_origin` (the
   write's origin), `runtime.triggered_by_member_id` (the member writing; null for a write no member
-  made), and `now()`.
+  made), `now()`, and `member_of("grp_…")` — true when the member writing belongs to the group.
+
+In a check a select reads as its one value (`record.kind == "retail"`), and a link (a one-row link too) and a lookup read as lists (`first(record.customer)`).
 
 A check on several operations reads only what all of them carry, so one on creates and updates reads
 neither `prev_record` nor `changes`.
 
+A write that recomputes another table's rows (a rollup over lines, a lookup or a formula over a parent) judges each recomputed row as an update, by the checks `on` `update` that read a field the recompute changed; `changes` is what the recompute changed. A check that refuses on `changes` or on a status the row holds can therefore refuse the write that moved the parent, so it is gated on the field it means (`!isNull(changes.status)`).
+
 A lookup reads with the access of the member who last saved the check, so saving one requires reading
 every table its lookups read. It reads committed rows: two writes at the same moment can each pass a
 check the other would fail, so values no two rows may share are the table's `unique`, not a check.
 
 A `when`, a lookup or a `fail_when` that cannot decide — it fails, or the write's time runs out —
-refuses the write. A draft is checked when it is submitted, as a create; its edits before that are
+refuses the write, naming the part it was reading and, for an expression or a filter, what it met
+(`lookups.clash: Filter on "start_on": date 'before' value … is not a date`). A draft is checked when it is submitted, as a create; its edits before that are
 not. A restored record is checked as a create. Cloning a table copies its checks to the member who
 clones it, and is refused when that member cannot read a table a check's lookup reads.
 
 One open order per reference, a row never counting against itself:
 
+```json
+{
+  "tables": [
+    {
+      "ref": "orders",
+      "label": "Orders",
+      "fields": {
+        "reference": { "type": "text", "label": "Reference" },
+        "closed_at": { "type": "date", "label": "Closed at" }
+      },
+      "checks": {
+        "one_open_order_per_reference": {
+          "on": ["create", "update"],
+          "when": "isNull(record.closed_at)",
+          "lookups": {
+            "same_ref": {
+              "table": "orders",
+              "filter": {
+                "node_type": "group",
+                "logic": "and",
+                "children": [
+                  { "node_type": "condition", "field_key": "reference", "operator": "equals", "value": { "$expr": "record.reference" } },
+                  { "node_type": "condition", "field_key": "closed_at", "operator": "is_empty" }
+                ]
+              },
+              "limit": 2
+            }
+          },
+          "fail_when": "some(lookups.same_ref, (r) => r.id != record.id)",
+          "message": "\"An open order already has this reference.\"",
+          "field": "reference"
+        }
+      }
+    }
+  ]
+}
 ```
+
+## Table workflows
+
+A table workflow is what follows every committed write of a table's rows, whoever makes it: the grid, an import, an agent or
+any app. An effect that must hold for all of them belongs to the table. A button on one screen is that app's act, a value fixed
+when a row is made is `default_from`, and a rule that refuses a write is a check; a table workflow runs after the write has
+committed and cannot refuse it.
+
+It is stated in the table's document, under `workflows`, each under an alias of its own, and `set_tables` writes it with the
+rest of the table: a merge patch edits one, `null` removes it, and `get_table` states a table's workflows in its document, with
+the failures of the last 7 days beside them, to whoever manages the table. A dry run of `set_tables` with a `record_id` says what
+each workflow the call adds or changes would write on that row; reads are real and nothing is written.
+
+| part | what it holds |
+|---|---|
+| `on` | the write it follows: `create`, `update` or `delete` |
+| `when` | optional expression over `record`, `prev_record` and `changes`; the workflow runs only after a write where it is truthy |
+| `changed` | optional, with `on: update`: field aliases; the workflow runs only after an update that changes any one of them |
+| `body` | the steps, written as an app workflow's body is |
+| `enabled` | `false` keeps the workflow without running it; absent, it runs |
+
+```json
 {
-  "table_id": "tbl_orders",
-  "name": "One open order per reference",
-  "on": ["create", "update"],
-  "when": "isNull(record[\"fld_closed_at\"])",
-  "lookups": {
-    "same_ref": "{ table_id: \"tbl_orders\", filter: { node_type: \"group\", logic: \"and\", children: [ { field_key: \"fld_ref\", operator: \"equals\", value: record[\"fld_ref\"] }, { field_key: \"fld_closed_at\", operator: \"is_empty\" } ] }, limit: 2 }"
-  },
-  "fail_when": "some(lookups.same_ref, (r) => r.id != record.id)",
-  "message": "\"An open order already has this reference.\"",
-  "field_key": "fld_ref"
+  "tables": [
+    {
+      "ref": "repairs",
+      "label": "Repairs",
+      "fields": {
+        "status": { "type": "select", "label": "Status", "options": [{ "alias": "queued", "label": "Queued" }, { "alias": "fixed", "label": "Fixed" }] },
+        "fixed_on": { "type": "date", "label": "Fixed on" }
+      },
+      "workflows": {
+        "stamp_fixed": {
+          "on": "update",
+          "changed": ["status"],
+          "when": "record.status == \"fixed\"",
+          "body": "await update_records({ table_id: \"repairs\", record_ids: [trigger.record_id], set: { fixed_on: formatDate(now(), \"yyyy-MM-dd\") } });"
+        }
+      }
+    }
+  ]
 }
 ```
+
+The body names the table's fields, select options and other tables by alias, and reads the write as `record`,
+`prev_record` and `changes` and the row's id as `trigger.record_id`. It operates on records and integrations: a body
+that calls a tool changing a table, an app or any other structure is refused when it is saved. It runs as the table's owner, so
+it reaches the tables the owner reaches, and its writes meet the table's checks like any other write; a write refused by a
+check fails that run and leaves the row as it was. A body names a field by alias where it can tell which table's field it is: a
+read of `record`, `prev_record` or `changes`, a row from `get_record` or `query_records` called with a literal `table_id`, and a
+loop over such rows. A name it cannot tie to a table, and an option compared to a value of unknown type (not a read of a field, and
+not a text, number or other value the type proves holds no option), are refused with what to change. A link reads as the list of the row ids it holds, a one-row link too: compare `first(record.customer) == id`. A lookup reads as one flat list of what it looks up: `record.x != prev_record.x` on one is refused, so compare `first(record.x)` with `first(prev_record.x)`. A single member, a single select, a number or a text reads as the value itself: `first(record.technician)` is refused at save, naming the read.
+
+A write the workflow itself makes sets off the workflows of its table in turn, and a chain of them stops after five. A workflow
+that writes the row it follows is gated by a `changed` or a `when` that its own write does not satisfy. One run is queued for a
+row and a workflow at a time, so a burst of writes to one row runs it once more after the run in flight. A field a workflow
+reads cannot be deleted or retyped until the workflow is changed or removed in the same call or before. Cloning a table copies its
+workflows for whoever manages it (`include_workflows: false` leaves them), each with a body of its own, and is refused when a
+body names a table the cloner cannot reach. A workflow runs as the table's owner, so whoever saves or rehearses one must manage the
+table and read every table it reads in full: the body's, the gate's links', the written table. An option is written where
+it is compared to, listed against or set on its field; a constant holding one is refused.
+
+A lock is the table's: a table workflow calls `lock_records` on a row (an app's act may too), and every door then refuses
+the row's writes until whoever manages the table calls `unlock_records` — in an app's run, judged as the member who pressed.
+A locked row reads locked in every app. An app's own Check or `edit: false` only makes a row read-only in that app.
+
+## Runs
+
+Each start of a workflow is a run: an app's workflow or act, a table workflow, a button, an automation. An agent finds,
+reads, retries and stops runs on chat, MCP and the CLI. A run is read by whoever manages what its workflow belongs to: its
+automation or its table, and for an app's workflow the app's owner or an admin, never a manager of the app.
+
+- **Find.** `query_workflow_executions` lists one workflow's runs (`workflow_id`), every run started for one row
+  (`record_id`) — a table workflow's written row, a pressed button's row, an app run's `record_id` input — or both, newest
+  first, a page at a time (`next_cursor`). Each run names its workflow and kind, what started it, its row and how it ended:
+  for a failure, the step that threw, its tool and the error; for a waiting run, when it wakes, or the approval and the
+  approvers it waits on, or the payment. A run started before runs recorded their row carries no `record_id`.
+- **Read.** `get_workflow_execution` gives one run's steps in order with each one's tool, input, output and error, what it
+  returned, how many rows it wrote (a row's own history is in `query_audit_logs`) and the runs its writes started. Ninety days
+  after a run starts, its trigger and its steps' input and output are pruned; the read says so and gives the rest.
+  `run_app_workflow` answers each run it makes with its `execution_id`.
+- **Retry.** `retry_workflow_execution` runs a failed, refused or cancelled run again as a new run linked to the first
+  (`retry_of`): the first run's trigger and row, the workflow's current steps and its owner's current access, with the
+  member who retries it as the one who started it. A run is retried once; a retry that fails is retried in turn. It asks
+  first when the run, or a run it retried, already wrote rows or called a service no delete reverses. An automation's or a
+  table workflow's retry runs in the background, as its runs do, and answers `queued`; a button's and an app's run while
+  the call waits. An app's call is checked again against the workflow's current inputs. A pruned run, a run of a workflow
+  that is off, a reviewed act's run (call the act again) and a recording's filing (the recording retries its delivery)
+  are not run again.
+- **Stop.** `cancel_workflow_execution` stops a waiting run and withdraws its pending approvals.
+
+Off means off: a waiting run whose workflow was turned off, deleted, or taken off its automation, table, button or app ends
+`cancelled` when it would resume, saying why, and runs no further step.
+
+A waiting run keeps its version: when it resumes, it runs the steps of the version it started with, so an edit saved while it
+waited changes later runs only. When that version is gone, the run ends failed and says why.