@lotics/cli 0.321.75 → 0.321.77
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/src/cli.js +6 -6
- package/docs/agent_surface.md +2 -0
- package/docs/design.md +1 -1
- package/docs/document_templates.md +1 -1
- package/package.json +1 -1
package/dist/src/cli.js
CHANGED
|
@@ -1849,7 +1849,7 @@ async function saveSignedLinks(links, dir, timeoutMs) {
|
|
|
1849
1849
|
}
|
|
1850
1850
|
|
|
1851
1851
|
// src/version.ts
|
|
1852
|
-
var VERSION = "0.321.
|
|
1852
|
+
var VERSION = "0.321.77";
|
|
1853
1853
|
|
|
1854
1854
|
// src/timezone.ts
|
|
1855
1855
|
function machineTimezone() {
|
|
@@ -1871,7 +1871,7 @@ var getting_started_default = '# Getting started\n\nA workspace is where one bus
|
|
|
1871
1871
|
var build_default = '# Build \u2014 a workspace or an app, call by call\n\nBuild from this page, `design` and the treatment the rows call for; a refusal names the `reference/<id>` page for the rest. The worked business: a bakery takes cake orders at the counter, a customer and one line per cake from the menu, moving taken, baking, ready, collected, with a slip printed when ready.\n\n`get_workspace` shows what already exists and `get_app` an app\'s tree: an app added or changed later starts there and states only the difference (`reference/changing-an-app`). Each write to an app makes a new version of it, and the live app is the only copy; sending an earlier tree restores the app, never a table or a row a write made, so try a write on a throwaway row. Before the first write, send the person who asked one message covering: the jobs and lists this business runs beyond those named, the trade\'s usual ones stated as defaults that stand; who does each job (`get_workspace` kind `member` lists the organization\'s people, not who works in this business or what each does); and the lists and papers they already keep, attached. A busy owner answers what comes first, so the message\'s first line is its first question, and it asks only what their papers and your defaults cannot settle, among them the papers they keep, asked by what they hold, and what else they keep track of; the defaults come after. "Go ahead" is a full answer. No second round: build from the answer, and a paper or list that does not come with it is never waited for \u2014 build from your defaults now and say in your report which papers would sharpen it. A short request names a business, not everything it runs on, so the workspace holds what that kind of business can\'t run without, such as what must never happen, what people are paid for and the papers it sends; your report names what you assumed, for them to change. What no one could guess from the data goes into a knowledge doc with `set_knowledge` (`knowledge_docs`).\n\n## 1. Tables and their checks: `set_tables`\n\nLinked tables go in one call, since they name each other by `ref`; `records` and checks may follow in the next call, so a refusal costs a patch rather than the whole document. A new table is named by its `ref`, which becomes its alias. One table per kind of thing, one column per fact, a link wherever one record points at another (`data_model`). A status is the stage of the work; a touch ("called") is a log row, a money fact ("paid in full") a formula, a quantity a number with its unit in `notation`. Read `design` before stating `records`, since a row\'s face, picture and mark are stated there, and so is what goes wrong on a row and needs someone to act: an issue (`design/issues`). Over rows already there, read a sample before building on a field: one mostly empty holds up no screen. A table people work states `title` (who or what a row is; a code only where nothing else names it), `records` (an app over a table without it is refused) and `singular` (so is an Add over a table lacking it).\n\n```json\n{\n "tables": [\n {\n "ref": "customer", "label": "Customers", "singular": "Customer", "title": "name",\n "fields": {"name": {"type": "text", "label": "Name", "required": true}},\n "records": {"party": "person"}\n },\n {\n "ref": "menu_item", "label": "Menu", "singular": "Menu item", "title": "name",\n "fields": {\n "name": {"type": "text", "label": "Cake", "required": true},\n "price": {"type": "number", "label": "Price", "required": true, "notation": {"style": "currency", "currency": "USD"}}\n },\n "records": {"figure": "price"}\n },\n {\n "ref": "cake_order", "label": "Cake orders", "singular": "Cake order", "title": "reference",\n "fields": {\n "reference": {"type": "autonumber", "label": "Number", "prefix": "CK-"},\n "customer": {"type": "link", "label": "Customer", "table": "customer", "multi": false, "required": true},\n "due_on": {"type": "date", "label": "Pickup on"},\n "pay_by": {"type": "date", "label": "Pay balance by"},\n "lines": {"type": "link", "label": "Cakes", "table": "cake_line", "multi": true, "pair": "order"},\n "total": {"type": "rollup", "label": "Total", "via": "lines", "op": "sum", "field": "amount"},\n "prepaid": {"type": "number", "label": "Prepaid", "notation": {"style": "currency", "currency": "USD"}},\n "paid": {"type": "formula", "label": "Paid", "expression": "{total} > 0 && {prepaid} >= {total}", "output_type": "boolean"},\n "slip": {"type": "files", "label": "Slip"},\n "stage": {"type": "select", "label": "Stage", "default": ["taken"], "options": [\n {"alias": "taken", "label": "Taken", "color": "slate"}, {"alias": "baking", "label": "Baking", "color": "amber"},\n {"alias": "ready", "label": "Ready", "color": "blue"}, {"alias": "collected", "label": "Collected", "color": "green"}\n ]}\n },\n "records": {"subtitle": ["customer"], "figure": "total", "due": ["pay_by"], "settled": "paid", "status": {"field": "stage", "closed": ["collected"]}},\n "checks": {"pay_by_before_pickup": {"on": ["create", "update"], "field": "pay_by",\n "when": "!isNull(record.pay_by) && !isNull(record.due_on)", "fail_when": "record.pay_by > record.due_on",\n "message": "\\"The balance is due on or before the pickup day\\""}}\n },\n {\n "ref": "cake_line", "label": "Cakes on orders", "singular": "Cake", "title": "item",\n "fields": {\n "item": {"type": "link", "label": "Cake", "table": "menu_item", "multi": false, "required": true},\n "order": {"type": "link", "label": "Order", "table": "cake_order", "multi": false, "required": true, "pair": "lines"},\n "quantity": {"type": "number", "label": "Quantity", "required": true, "min": 1},\n "unit_price": {"type": "number", "label": "Unit price", "default_from": "item.price", "notation": {"style": "currency", "currency": "USD"}},\n "amount": {"type": "formula", "label": "Amount", "expression": "{quantity} * {unit_price}", "notation": {"style": "currency", "currency": "USD"}}\n },\n "unique": [["order", "item"]],\n "records": {"figure": "amount"}\n }\n ]\n}\n```\n\n`default_from` copies the menu\'s price when a line is made, so a later change leaves taken orders alone. `min`, `unique` and a check hold on every write; a check\'s language is `workflows/table-checks`, an effect after a write a table workflow (`workflows/table-workflows`). A check at its smallest, under an alias in the table\'s `checks`: `{"on": ["create"], "fail_when": "record.quantity < 1", "message": "\\"Quantity is at least 1\\""}`; `message` is an expression, so fixed text is a quoted string.\n\nA `date` field is a day, or a moment with `"format": "datetime"`; a time of day is a `text` field with `"format": "time"`. Days between two dates in a formula is `differenceInCalendarDays(later, earlier)`; the helpers are named exactly (`reference/formula`). Two rows that must not hold one resource at once are the table\'s `no_overlap`: `{"from": "start_at", "to": "end_at", "by": "room"}`, a list where a row holds two resources (`reference/no-overlap`).\n\n## 2. The paper: `set_template`\n\nAn Act names a template by its alias, made from its name (`order_slip`), so the paper comes first.\n\n```\nset_template {"type": "html", "name": "Order slip",\n "template": "<h1>{{reference}}</h1><p>{{customer}}, {{date due_on}}</p>{{#each lines}}<p>{{item}} \xD7 {{quantity}}</p>{{/each}}<p>{{money total \\"USD\\"}}</p>",\n "variables": {"reference": "string", "customer": "string", "due_on": "string", "lines": "array", "total": "string"}}\n```\n\nOne template per paper the owner sends. A slot is named after a field of the record; the cakes loop under the name of the link to them (`lines`). More: `document_templates`.\n\n## 3. The app and its acts: `set_app`\n\n**Which apps**, and who gets each, is `app_architecture`. **How each row reads** comes before the first List: `design/treatments` names the view per kind of row.\n\n**Start from one root List.** `{"type": "List", "entity": "cake_order"}` in the App\'s `children` is a whole app: the platform composes the page every row opens, the add and the Delete, and stores them. State only the difference from what it composes.\n\n```json\n{\n "body": {\n "type": "App", "key": "counter", "name": "Counter",\n "children": [\n {"type": "List", "entity": "cake_order", "filters": ["customer"], "create": ["customer", "due_on", "pay_by"], "children": [\n {"type": "Reading", "label": "By pickup day", "value": "total", "by": "due_on"}\n ]}\n ],\n "pages": [\n {"type": "Record", "entity": "cake_order", "children": [\n {"type": "Steps", "children": [\n {"type": "Section", "title": "Order", "at": ["taken", "baking"], "children": [\n "due_on",\n "pay_by",\n {"type": "List", "entity": "cake_line", "create": ["item", "quantity"]},\n {"type": "Act", "key": "start_baking", "label": "Start baking", "when": {"stage": ["taken"]}, "requires": ["due_on"], "asks": ["prepaid"], "set": {"stage": "baking"}},\n {"type": "Act", "key": "ready", "label": "Ready", "when": {"stage": ["baking"]}, "set": {"stage": "ready"}, "template": "order_slip", "into": "slip"}\n ]},\n {"type": "Section", "title": "Pickup", "at": ["ready"], "children": [\n {"field": "slip", "edit": false},\n {"type": "Act", "key": "collect", "label": "Collected", "when": {"stage": ["ready"], "paid": true}, "set": {"stage": "collected"}}\n ]}\n ]}\n ]}\n ]\n }\n}\n```\n\n**How a status draws follows the work, never this example.** The order states `Steps` because its stages hold something of their own: the lines it bakes from, the slip its Act files. A status whose Acts only move the row on states no `Steps` and draws as a line of steps. One a person sets by hand, closing nothing or moved by no Act, draws as its select (`design`, Stages).\n\n**Give each main List a band** of what its person watches, a figure or a chart in its `children`, never a bare count.\n\n**A press can be a mistake.** An Act also moves a row back (`when` the later stage, `set` the earlier), at the foot of the Section of the stage it leaves. **Someone with no seat** who signs or approves one record, a customer or a supplier, gets a Record\'s `Outside`: a link a member makes of that record.\n\n`dry_run` checks a body and writes nothing; then share each app (`app_architecture`). An Act\'s or stage\'s `owner` decides who presses.\n\n## 4. What the owner will ask an agent: Query and Workflow nodes\n\nWhat the business asks its assistant again and again (orders waiting for pickup) is a Query or Workflow node of the app, with a `description` for an agent that has not seen the screen (`agent_surface/declaring-more`). A figure\'s name is not its definition: which rows count, by which field, now or over a window, is the owner\'s; where no field holds it, say so rather than total a near one. The App\'s `description` heads what a member\'s chat agent reads every turn, so a standing process the app expects of it goes there. A connected service is reached by a Workflow node\'s step (`workflows`).\n\n## 5. The owner\'s rows: `create_records`\n\nBatch the owner\'s rows: the customers and menu, then the orders, linked by the ids those calls return, then each order\'s cakes (`field_values` has the value each type takes). Load as an admin: a row past the first stage is refused unless that stage\'s owner or an admin makes it, and a row loaded at a later stage states each earlier stage\'s date field (`<option>_at`). Example rows the papers ask for and do not list come from the owner\'s lists, each at the stage it should show, written like the owner\'s own rows (no flag field, no "Example" in a name) and listed in your report for the owner to keep or delete. An owner who sent no lists opens what you leave, so a few example rows, listed the same way, show them the app working.\n\n```\ncreate_records {"table_id": "cake_line", "field_keys": ["order", "item", "quantity"],\n "rows": [["<the order\'s record id>", "<Lemon cake\'s record id>", 2]]}\n```\n\n## 6. Verify: `run_app_workflow`, `screenshot_app`\n\nMove the owner\'s rows through the app as their person would, each only as far as the stage the owner says it is at. Every Act runs as `act_<key>`, the one name, handed what it asks. A dry run walks the moves and files nothing; then press each paper Act for real, on one row the owner\'s stage allows or on an example row left at its last stage: what is left on a row is what the owner opens. Prove a rule by sending the write with `dry_run: true`; never switch a check off. Only an admin passes `as_member`: it shows a member\'s view and reads, which is how each person\'s screen is checked. What the shots and runs must show is `design/the-rubric`.\n```\nrun_app_workflow {"app_id": "app_\u2026", "alias": "act_start_baking", "inputs": {"record_id": "rec_\u2026", "prepaid": 20}, "dry_run": true}\nscreenshot_app {"app_id": "app_\u2026", "as_member": "<member id>", "pages": [{}, {"record_id": "rec_\u2026"}]}\n```\n\n## 7. Hand over\n\nName the workspace and its organization after the business with `set_workspace` (`name`, `organization_name`, and `organization_language`: the language its papers, invitations and members default to, `vi` until set), and leave standing instructions there (`instructions`, one entry per rule): who the business is, its people\'s words, what any agent here must keep to. As an admin, invite the people named with `set_members` (`members` keyed by email, role `member` or `admin`), else say whom to invite.\n\nBefore you report, answer each question of `design/the-rubric` with a call, and put right or name each gap. Then show the owner what you built, job by job, each paper and what makes it, with the choices you made for them to change.\n';
|
|
1872
1872
|
|
|
1873
1873
|
// docs/design.md
|
|
1874
|
-
var design_default = '# Designing an app\n\nAn app is a tree of components: a List of one table, the Record a row opens, its Sections, the Acts that move it. The\ntree states COMPOSITION \u2014 which fields, lists and acts each job\'s screen holds; how each piece looks is the platform\'s,\none way per concept. A node the tree leaves out draws its default, from the table\'s facts (`records`, the stage, the\nwrite rules): a List\'s Readings band, the stage buttons, the picture. What a write stores, and the Section that follows the table: `reference/changing-an-app`. State a node to change it,\nor `false` at it to turn it off (`"readings": false`, a Record\'s `"row": { "image": false }`). A field is written where its Record declares it: a Section\'s Field, the table\'s face (title, line, picture, figure), or every field where the Record states no Section; the head, a line, a column or a board draws it, and never makes one written; every head part (`row.title`, each `row.subtitle` entry, `row.figure`, `row.image`) takes `edit: false` to be read. A drawn Field is a control unless it\nor its entity is read-only (`edit: false`); a stepped status is not, since Acts move it, unless its `row` states `status: { edit: true }`. Which apps a business needs is `app_architecture`.\n\n**The visual bar.** Every screen is judged against it; a miss is a change to the tree.\n\n- Each app looks like its own rows: the view its kind of row takes (`design/treatments`) \u2014 cards for things found by\n their photo, a calendar or lanes for dated work, faces for people and organisations. A List left as a table is drawn\n as one, the most common failure of an app; the answers of `set_app` and `get_app` note the view rows that are work in time call for (a calendar, lanes, a roster, a gantt where rows wait on one another).\n- What needs attention leads the row as an issue its table declares (`design/issues`): a derived flag is an issue, in the\n warning tone on the row\'s line (in the danger tone where a Check\'s `on` refuses an act the row offers); every other yes\n reads in the success tone. `records.mark` is a category\'s own mark, a select whose options carry a brand or glyph.\n- A list\'s columns: the name and its lead, the status, then the columns the job reads on every row, as many as fit a desk. Each\n fact once: a column the row draws itself stands once. A generated number (`autonumber`) as the title yields\n the row\'s name to the subtitle\'s first part and stands first on its line. A row listed under its record is named by its\n subtitle\'s first part where its title only reads that record (a join row\'s lookup through the link back): title a join row by one side, its subtitle the other.\n- A list worked by a date states `sort` on that date\'s column, newest first; without one, a register reads newest made\n first and a record\'s child List in the order its rows were added.\n- Someone is a face wherever they are read: a link to a table stating `records.party` draws its row\'s face; a member\n field is one already; select options naming people or organisations who are neither each take the `mark`\n `{"kind": "avatar", "name": "person"}`, never a colour dot.\n- A thing shows its picture, a file its preview, a plan its days on a time axis, a quantity a meter (`records.limits`) or\n a chart, a register its Readings, and long text reads whole (a markdown Field; `block: true` on plain long text).\n- An option with a `color` draws its dot where its select is drawn; one without reads as its word. A `mark` where a\n brand or glyph names the option, on every option of a select read down a column (how it was paid, the channel).\n- Every app states its tile\'s `color` and `icon`, each apart from the workspace\'s other apps where it can be: an\n app stating no icon draws the one glyph every such app shares.\n- The paperwork is the proof of the work: a files field per purpose (what arrived, what was issued to the customer, the\n carrier, the authority) in the Section where that work happens, and the source of a\n figure (a screenshot, an email, a sheet) on its row. Every files field is drawn somewhere. A paper a counterparty\n sends (a supplier\'s invoice, a delivery receipt) is added on the record it arrives with \u2014 the order it is for \u2014 and\n listed again where it is settled, never only in the counterparty\'s ledger.\n\n<!-- generated:start words -->\n\n**The words most builds state.** A node\'s page holds its rules and every other word: `reference/list-node`, `reference/records`, `reference/field`.\n\n**Table**\n\n- `ref` (alias): A created table\'s handle in this call\n- `label` (text, required): The table\'s name in the workspace\n- `singular` (text): One row of this table, in the business\'s own words\n- `title` (alias): The alias of the field that names a row wherever a link or a record shows one\n- `fields` (map of alias \u2192 Field, required): The table\'s columns, each under its alias, which is its key here and so is never stated inside it\n- `records` (any value): How a row is recognised\n- `checks` (map of alias \u2192 table check (`workflows/table-checks`)): The conditions a write of the table\'s rows may not meet, each under its alias\n- `unique` (list (at least one) of list of alias (at least one)): Sets of fields whose values no two live rows share\n\n**Any field**\n\n- `label` (text, required): The field\'s name in the workspace\n- `required` (boolean): Refuse a record whose cell for this field is empty\n- `default_from` (text): Copied when a record is made off the row a one-row link of this entity names\n\n**`number` field**\n\n- `notation` (notation): How the figure reads\n- `min` (number | text): Refuse a create or update whose value is below this\n\n**`select` field**\n\n- `options` (list of Select option (at least one), required): The choices, in the order every picker and every ladder lists them\n- `multi` (boolean): Allow multiple selections\n\n**`link` field**\n\n- `table` (text, required): The table the link points at\n- `multi` (boolean, required): Whether a row links to one row or many\n- `pair` (`true` | alias): Makes the link two-way\n\n**`formula` field**\n\n- `expression` (text, required): The expression, over fields of THIS entity by alias in braces\n- `output_type` (`"number"` | `"text"` | `"date"` | `"datetime"` | `"boolean"` | `"select"`): Holds a formula to the type its readers need\n\n**`rollup` field**\n\n- `via` (alias, required): The alias of a link of this table to roll up from\n- `op` (operation, required): The operation over the linked rows\n- `field` (alias): The alias of the field on the linked table the operation reads\n\n**`lookup` field**\n\n- `via` (alias, required): The alias of a link of this table to look up through\n- `field` (alias, required): The alias of the field on the linked table to show\n\n**`autonumber` field**\n\n- `prefix` (text): Literal prefix prepended to every display value (e.g. \'KH-\' \u2192 \'KH-001\')\n\n**`records`**\n\n- `subtitle` (list of alias (1\u20132)): Up to two fields read under the title wherever a row is drawn (a code, a date, a party)\n- `figure` (alias): The one number the row stands for, read at its right (a total, a quantity left)\n- `status` (Status): The stage a row moves through, a single select, drawn in the record\'s head, or its Side where the Side states it\n- `due` (list of alias (at least one)): Dates that are deadlines (stored, or computed as a date)\n- `image` (alias | list of alias (at least one)): A files field that pictures the row, or a one-row link to a table with a picture (or a lookup of one through a one-row link: a delivery led by its order\'s customer), whose picture the row leads with\n- `party` (`"person"` | `"organization"` | `"organisation"`): What each row is where the rows are people (a contact, a patient) or organisations (a customer, a supplier, a carrier)\n- `limits` (map of alias \u2192 (alias | number)): A number read against a bound\n- `starts` (map of alias \u2192 `"today"` | `"me"`): What a field of a row being added starts at, where that start is certain\n- `mark` (alias): A single select (or a lookup of one through a one-row link) whose option leads the row wherever a mark leads it\n- `settled` (alias): A yes/no of the row (stored, a formula: an invoice paid in full, or looked up through a one-row link: a line settled with its parent) that ends its deadlines\n\n**`records.status`**\n\n- `field` (alias, required): The single select that is the row\'s state, its options in the order the work goes through them, drawn as a line of steps on a record page where no Section states `at`\n- `closed` (list of alias (at least one)): Options that end the work\n- `history` (text): A table every write that sets or moves the status appends one row to (its link to this table, the new status, the moment and who)\n- `dates` (map of alias \u2192 alias): Option alias \u2192 a date field of this entity the record write path stamps with the moment a row moves into that option, or is made at it\n- `stages` (map of alias \u2192 Stage): Option alias \u2192 who owns that stage and how long it should take\n\n**App**\n\n- `key` (alias, required): The app\'s alias, its name among apps\n- `name` (text, required): The job, in the words of the people who do it\n- `children` (list of (List over a Query | List | Sheet | Query | Workflow) (at least one)): The App\'s Views in order\n- `color` (colour): The launcher tile\'s colour\n- `pages` (list of Record (at least one)): The page the rows of an entity open, one per entity, each a Record stating its `entity`\n\n**List**\n\n- `entity` (alias, required): The table whose rows the List draws\n- `create` (boolean | list of alias (at least one)): The fields an add asks\n- `columns` (list of (alias | Edit column)): Fields read after the row\'s title, each drawn though no row holds it\n- `label` (text): The register\'s name in the app\'s lists and tab strip\n- `filters` (list of (alias | Tiered filter | Listed filter) (at most 8)): Fields the reader narrows by every day, beside the stage chips, at most 3\n- `children` (list of (Tab | Reading | Export | Act | List) (at least one)): Its Tabs, band Readings, Exports and Acts over ticked rows or every row in view\n- `key` (alias): Names the List among its siblings and in a Query\'s `list`\n- `sort` (Sort key | list of Sort key (at least one)): The rows\' order\n- `layout` (layout): A word, or an object stating one layout with its data\n- `remove` (boolean): Rows offer a Delete\n- `search` (list of alias (at least one) | `false`): Fields the search box reads\n- `where` (narrowing): A fixed narrowing on the server, for every reader\n- `group` (alias | `false`): A field the rows stand grouped by, a gantt drawing the groups as its lanes, a lanes board of days its cards\' sub-headings inside each lane\n- `expect` (alias | Expect): What a record should hold, shown before it does\n- `opens` (narrowing): The view the register opens on, a chip the reader may take away\n\n**Record**\n\n- `entity` (alias, required): The table whose rows open on this page\n- `children` (list of (List over a Query in a Record | alias | Field | Fieldset | Section | Steps | Side | Outside | List | Reading | Statement | Comments | Act | Check) (at least one)): Parts (Section, Side, and one Steps holding the Sections that are its path), or for a one-part record its Fields, Fieldsets, Lists, Readings, Statements and Comments directly\n- `add` (`false` | list of alias (at least one)): What a new row asks where a picker of this entity offers one, anywhere in the App\n- `row` (Record row): How the App reads this entity\'s rows wherever it lists them\n- `door` (`"page"` | `"drawer"`): How a row opens, on a page or in a drawer\n\n**Section**\n\n- `title` (text): The part\'s heading\n- `key` (alias): Unique among its siblings\n- `children` (list of (List over a Query in a Record | alias | Field | Fieldset | List | Reading | Statement | Comments | Act | Check) (at least one)): What the part draws, in reading order\n- `at` (list of alias (at least one)): The status options this part is the work of\n- `when` (condition): Drawn only while this holds\n\n**Field**\n\n- `field` (alias, required): The field\'s alias\n- `edit` (boolean): Shows a value nobody changes here\n- `label` (text): The heading of the field\'s gallery or prose block, where it draws as one\n- `block` (boolean): Gives a field room of its own\n\n**Act**\n\n- `key` (alias, required): The act\'s name\n- `label` (text, required): The verb, as the reader says it\n- `when` (condition): The act works only while this holds\n- `set` (map of alias \u2192 value): What the act writes\n- `asks` (list of (alias | `{ "field": alias, "starts": "today" | "me" }` | Asked input) (at least one)): What the reader states on pressing\n- `confirm` (`true` | `"warnings"` | text): The press asks first\n- `requires` (list of alias (at least one)): Fields filled first, each drawn where the act stands\n- `template` (alias): A document template it makes a file from\n- `into` (alias): The record\'s files field keeping the document\n- `owner` (`"field"` | `"link.field"` | `{ "group": id }`): Who presses it\n- `workflow` (alias): The workflow it runs for what `set` cannot say\n- `danger` (`true`): The act destroys or cannot be undone\n\n**Check**\n\n- `field` (alias, required): A yes/no or text formula of the page\'s entity\n- `on` (`"all"` | list of (`"update"` | alias) (at least one)): What the standing issue refuses\n- `resolve` (alias): An Act on one row of this entity that clears it\n\n**Reading**\n\n- `label` (text): What the figure is called\n- `value` (alias | `{ "avg": alias }`): A number field summed over the rows, or `{ avg }` averaged over the rows holding one\n- `by` (alias | Tiered filter): Splits the rows into parts\n- `where` (narrowing): Only the rows whose select holds one of these options, whose yes/no is this value, whose number or date meets its bounds (`gt`, `gte`, `lt`, `lte`; a date\'s `{ "now": true }` is read when the rows are), whose field is `{ "empty": true | false }`, or whose member field holds the reader (`{ "me": true }`)\n- `entity` (alias): The List\'s rows\n- `over` (alias): The date that places a row in time\n\n<!-- generated:end words -->\n\n## Issues\n\nWhatever goes wrong on a row and needs a person to act \u2014 a line delivered short, a price missing, a customer over their\ncredit limit, a permit about to expire \u2014 is an issue its table declares in `records.issues`. A declared issue stands in\nevery app that draws its row, with no app stating it: first on the row\'s line (`+N` the others), in the record\'s callout (a count of child rows as pills on those rows), in the List\'s filter of what needs checking with how many rows hold it, and those rows first. It never makes an\napp draw a row it did not, and never shows on an `Outside` page. What needs no one\'s action is no issue: a stage is the\nstatus, a category a select. A record\'s callout says each issue by its label and what it means: a text issue\'s own sentence, a yes/no issue\'s field `description` \u2014 give a yes/no issue\'s field one, or its line shows the name alone.\n\nAn issue is a promise that someone will act every time it stands: people and their agents see it on every row it holds.\nDeclare one only where the owner confirms each flagged case is a problem; a rule that flags rows nobody fixes trains\neveryone to ignore the colour, real issues included. Where a flagged row may be accepted as it is (a price agreed by\nexception), give the acceptance a field the formula reads, so accepting it clears the issue.\n\n- An issue is a formula of the row stating `output_type`: `"boolean"` stands while true; `"text"` stands while not empty,\n its words the sentence the reader sees \u2014 use it when the sentence must say what or how much ("Short 4 of 10").\n Its label is its name. Put the moment it matters in the formula, so it clears itself when the work is done.\n- The list is priority: an issue blocking the next step leads, then the earlier in the list.\n- `{ "rows": <link> }` on a parent rolls up every issue its child table declares, through a many-link paired to the\n child\'s one-row link back. The platform keeps a count on the parent per child issue, `<link>_<issue>`, labelled\n "<link label> \xB7 <issue label>"; never write it. The parent reads "2 rows left: Lines \xB7 Short".\n- A formula reading `now()` or `isToday()` (overdue, expiring within 30 days) is judged again every night, to the day.\n- An app\'s `Check` says what the issue does not: `on`, what it refuses in that app (`"update"`, `"all"`, or that\n entity\'s Acts), and `resolve`, the Act that clears it; one stating neither is refused, and one without `on` names a\n declared issue. A parent\'s Act is refused by a Check on the parent\'s count `on` that Act (never `"update"` or `"all"`: editing the rows clears it); the act then holds\n the parent while it runs, so its own `workflow` cannot send mail, notify, run an agent or wait \u2014 start that work from a\n workflow the act starts after.\n- A lock is a Check, not an issue: a yes/no such as paid in full refusing `"update"`, in no `records.issues`, since nothing\n is wrong with the row.\n- `get_table` reports each issue: rows holding it now, opened in the last 30 days, median days to clear.\n\nAn order whose lines can arrive short or unpriced, invoiced only when no line is short:\n\n```json5\n// order_line\n"fields": {\n "short": { "label": "Short", "type": "formula", "output_type": "text",\n "expression": "!isEmpty({delivered}) && {delivered} < {quantity} ? \\"Short \\" + toString({quantity} - {delivered}) + \\" of \\" + toString({quantity}) : \\"\\"" },\n "no_price": { "label": "No price", "type": "formula", "output_type": "boolean", "expression": "isEmpty({price})" }\n},\n"records": { "issues": ["short", "no_price"] }\n// order \u2014 `lines` is its many-link to order_line; the platform adds lines_short and lines_no_price\n"records": { "issues": [{ "rows": "lines" }] }\n// the order\'s Record in the app\n{ "type": "Check", "field": "lines_short", "on": ["invoice"] },\n{ "type": "Check", "field": "paid_in_full", "on": ["update"] }\n```\n\n## Look at it\n\nAfter an apply, `screenshot_app` draws each app as its people see it \u2014 the register, and a record by its `path` or its `record_id`\n(with a `path` on that record: one Section is `/<record id>?section=<its title>`; `screen` for a later screen of a long one), up to six `pages` in one call \u2014 at a desk\'s width and a phone\'s, naming the columns a table left off at each width;\n`-o <dir>` saves the shots from the CLI. `set_app` with `app_id`, an empty `body` and `dry_run` answers what a write of the\nstored tree would be refused for now, and its notes. Answer `design/the-rubric`, change the tree with `nodes`, and write again. To go back,\nsend the tree saved before the change as `body` with `app_id`, nulling an App prop stated since (`words`, `scope`,\n`period`, `icon`); tables and rows stay as they are.\n\n## The rubric\n\nWhether the build does the owner\'s work, answered by a call each, never from what you meant to write:\n\n1. Each job the owner named, and each their kind of business cannot run without: which screen does it, and which press? Find each on a `screenshot_app` shot of the person who does it (`as_member`); one who cannot open the app is first invited (`set_members`) and given it (`set_access`) \u2014 an app nobody shares opens for admins alone.\n2. Can an agent do each job in one call, an `act_<key>` or a Query or Workflow node whose `description` names it? `get_app` lists them; `run_app_workflow` with `dry_run` proves one (`agent_surface/prove-an-app-as-an-agent`).\n3. Is each kind of row in its treatment (`design/treatments`)? Timed work reads in a calendar or lanes, and a weekly plan as the dated rows it makes.\n4. Does each screen show the least its next step needs, each fact once, the signal that a step is due leading?\n5. Is anything cramped at desk or phone width?\n6. Is every paper and every Export made, those this kind of business sends unasked too, with no blank? Press each paper Act and read the file it files; prove an Export with `run_app_query` and `export`.\n7. Is each thing that must never happen in this business (a step taken before its approval, stock below zero, a double booking) refused on every write? Prove each with a write sent `dry_run: true` that is refused (`workflows/table-checks`).\n\nA failed answer is a change to the tree, or a gap named to the owner.\n\n## Treatments\n\nThe answers of `set_app` and `get_app` note the view rows that are work in time call for (a calendar, lanes, a roster, a gantt\nwhere rows wait on one another), naming the node that would state it; a note refuses nothing. No other treatment below is noted.\nEach kind of row\'s view is chosen before its List is written:\n\n| The rows are | The treatment | Its own page |\n|---|---|---|\n| People or organisations | `records.party`, with a photo or logo as its `image` | |\n| Things with a photo, a scan or a paper | `records.image`; List `layout: "cards"` where the picture is how a row is found | `reference/cards` |\n| Read by their day | List `layout: "calendar"`; on a record, a child List with `layout: {"agenda": \u2026}` | `reference/calendar`, `reference/layouts` |\n| Ranked by a figure, or worked by a date | List `sort: {"field": \u2026, "desc": true}` on that column | |\n| Booked on a resource | List `layout: {"lanes": {"by": \u2026}}`, and the table\'s `no_overlap` \u2014 a list of rules where a row holds two (a room and a teacher) | `reference/lanes`, `reference/write-rules` |\n| A day\'s work given out to people or vehicles | List `layout: {"lanes": {"by": \u2026}}` over rows holding a day and no hour | `reference/lanes` |\n| A log of what happened | a child List with `layout: "timeline"` | `reference/layouts` |\n| Opened to be worked on | the Record\'s Sections \u2014 each one area of the record\'s data, its lists and field groups inside it; a status\'s stage acts stand at the foot of the rows they move; a stage that holds something of its own, a note included, is a Section inside `Steps`; fields only one kind of row holds (a delay\'s cause, a safety issue\'s hours lost) in a Section whose `when` names that kind | |\n| Rows that each belong to another row | a child List on that row\'s Record, with `create` and `remove` \u2014 and a child\'s own rows a List in that child\'s page, as deep as the data goes, and every row\'s \u22EF offers Duplicate; a List with `same` where read-only | |\n| A related row\'s value on the list (the newest contract\'s end date) | a `lookup` field of the table, ordered, as a column | `reference/lookup` |\n| Moving through a status | an Act per move, `status.dates` for the moment of each stage, and the register\'s Readings | |\n| Counted over a period | the register\'s Tabs over one `period`; a Tab\'s `totals` for a child\'s sums before, during and through it; an open Tab\'s `where` reads only what was true at the period\'s end, never a status the row moves on from | |\n| Papers a case gathers | a List with `expect`; the papers made, an Act\'s `templates` | |\n| A plan of spans | List `layout: {"gantt": {"start": \u2026}}` | `reference/gantt` |\n| Stood at a place on a plan, flat or in 3D \u2014 pallets, bins | List `layout: {"plan": \u2026}`; places state `plan_place` | `reference/plan` |\n| Checked item by item against a standard | a List with `checklist: {"photo": \u2026, "clause": \u2026, "failed": [\u2026], "passed": \u2026}`: each row a mark (passed at `closed`, failed at a `failed` option, or by the yes/no `passed` names \u2014 a measured verdict, no task or status needed), its photo and the clause it is checked against; with `expect` on the standard\'s items, each item is a line marked the same way and filled by the block\'s columns | |\n| A place before and after the work | a List with `compare: {"before": \u2026, "after": \u2026}`: two files fields read side by side, or two value fields read as one struck-then-new column | |\n| Spots on a drawing | `records.pin: {"on": \u2026, "x": \u2026, "y": \u2026}` on the spots\' table: a record listing rows that link to them draws the picture with a numbered pin at each; the picture is the `on` row\'s `records.image` | `reference/record-places-pins-and-cadence` |\n| Photos that must be taken on site | a files field with `photo_places: true` keeps where the device stood for each photo shot through the camera; judge them in a text formula `distance({photos}, {site_lat}, {site_lon})` listed in `records.issues` | `reference/formula` |\n| A number painted on the thing, or a barcode or QR code on it | `records.scan: "iso6346"` or `"text"` (read off one photo by an agent), or `"code"` (decoded on the device, no agent): the title read on a phone, beside each search matching it | `reference/record-places-pins-and-cadence` |\n| The rows a weekly pattern owes (a class\'s lessons on Tue and Thu at 16:00) | `records.cadence: [{"entity": \u2026, "on": "<a multi-select of mon\u2013sun>", "start": \u2026, "end": \u2026, "planned": \u2026, "except": \u2026}]` on the parent, and an Act `makes: "<child>"`: the press lists the rows still owed, each with what would stop it, and writes the ones ticked; pressed again it lists what is missing, and moves a row to the pattern\'s hours and copied fields where it differs and no person or linked row has touched it (ticked), else leaves it unticked saying why | `reference/record-places-pins-and-cadence` |\n| Who did what on which day | List `layout: "roster"` with the List of its cells inside | `reference/roster` |\n| Someone with no seat signs off one record (a buyer approves a proof, a client signs a handover) | the Record\'s `Outside`: the Fields and Lists the link shows as they are, and Acts that each move the status out of its `at` \u2014 a link a member makes of the record, never a seat; the link\'s page names the record only where the Outside states its title\'s field | |\n| Steps people drop out of between | a Reading with `steps` on the record whose child rows count them | |\n| A record\'s own numbers nobody keys, read at a glance | consecutive Readings with no `entity` (up to eight tiles) | |\n| Rows that are each a place a record is sent | a List with `expect` on the link to those places and `post`: each ticked, the post written there and read as its feed shows it | `reference/publish-desk` |\n| Papers an agent reads, where the owner asked for one | an Act\'s `intake` with `fills` | |\n| Calls and visits | an Act\'s `record` | |\n| Changes a workflow proposes that a person approves row by row \u2014 a price list applied, a statement matched to what is owed | an Act\'s `workflow` with `review`, its body returning a changeset in `data.review` | |\n| Documents covering lines | a List with `under` | |\n| Rows on file a record takes in | a List with `pick` | |\n| One owner\'s question across jobs | an App of Tabs and Readings and no register | |\n\nWhat these nodes do not state, a long-form writing page or a bespoke tool, is a custom-code app (`lotics app create <name> --custom`, `app_bindings`), never a new node.\n\n### Faces and pictures\n\n#### Party\n\n`records.party` is `"person"` where the rows are people (a contact, a patient, a driver) and\n`"organization"` where they are companies (a customer, a supplier, a carrier). Every surface drawing one of\nits rows then draws a face: its `image` (a photo, a logo), else its initials. Without it, a person is drawn as a thing. A workspace\nmember is a `member` field, and is drawn by their face already. A column holding a link to several rows of people,\nor several members, draws their faces as a stack that names them on hover. Worked: `examples/party`.\n\n#### Image\n\n`records.image` names the files field that pictures a row \u2014 a product\'s photo, a damage photo, a\nscan, a receipt. Every row of it then leads with its picture, or its paper\'s preview, wherever it is drawn \u2014\na row holding no picture leads with the placeholder; a link to it previews the file. `image` may instead name a\none-row link to a table with a picture (an order line\'s `item`), or a lookup of one through a one-row link (a delivery\'s `customer`, through its order): the row leads with that row\'s picture, still titled by\nits own words \u2014 or several in order (`["product", "bundle"]`, a line linking either), the first that holds a picture leading the row. Never a field an Act keeps the paper it makes in (`into`). List\n`layout: "cards"` where the picture is how a row is found. The table\'s `records.image_shape` (`portrait`, `square`, `landscape`) states the shape the register\'s cards and tiles and such a List draw it at. A files field the record keeps as a folder of\npapers is drawn as a Field, read whole. Worked: `examples/cards`.\n\n#### A link opens its row\n\nEvery row an app draws opens on its page, the one you state or the one a write stores for you. A link\'s row shows its name, line, status and figure. State `pages/<e>` to show more or to edit.\n\n### Rows in time\n\nRows that each stand on a day, or hold a run of days or hours, are read where they stand in time \u2014 never\nas two date columns. A row holds a span when two dates a person states are ordered, the second after the first by a\n`min` or a table check, both required or the second the row\'s `due`; else it is an appointment when one required date\nis stated that no Act stamps, that a new row does not start at `today` and that is not derived. A stamp is an event,\nand a `due` is a deadline, never the day a row is held on. A `no_overlap` by a person or a value alone keeps one row at\na time each \u2014 a member\'s periods in turn \u2014 read by what they hold.\n\n#### Calendar\n\n`layout: "calendar"`, or `{ "calendar": { "date": "starts_at", "end": "ends_at" } }`: the rows by their day \u2014 a\nmonth, a week, a day or a list; an entry at its hour where `date` holds one, over its span where `end` names the date it\nruns to. The bare word takes both from the rows\' facts and is refused, naming `date`, where they name none. An entry pressed opens its row beside the calendar; where the app saves the row, a drag or F2 moves it. Worked:\n`examples/calendar`.\n\n#### Lanes\n\n`layout: {"lanes": {"by": \u2026}}` with `by` naming a one-row link whose target\'s rows are the lanes (a chair, a\nmachine, a room), each drawn even when empty: every row a block from the first date on its line to the\nsecond, and a free stretch adds a row there. `loads` reads what a lane carries against what it holds: hours summed\nwithin each day (across days, the fullest day, named), any other number the most its rows add up to at one time. A\n`no_overlap` `by` the same link refuses two rows on one resource at once. A lane per person: `by` a member field\nand `of` a group of the workspace by its id, each member of it a lane, idle ones too. Worked: `examples/lanes`.\n\nA day\'s work given out (stops to drivers, jobs to technicians): rows holding a day and no hour read at one day as cards\nin lanes, those no lane holds, or holding no day, first in a tray. Each lane\'s head reads its count, its loads and its\nrow\'s status; a lane its link no longer admits (`options_where`) says so in its head and refuses a card. Where the app writes the link, cards ticked or\ndragged go to a lane in one write, every row checked before any is written, and the List\'s first `sort`, ascending on a\nnumber the app writes, is a card\'s place in its lane.\n\n#### Gantt\n\n`layout: {"gantt": {"start": \u2026}}` (and `end`, else the table\'s first `due`; a `due` is a deadline, never an appointment date): one bar a row over\nits run of days, read against today. `milestones` marks\ndates on the bar, `planned` the plan under it, `progress` how far it is done, `after` the rows it waits on;\nthe List\'s `group` is its lanes; a table holding rows under rows nests each bar under its row above, folded as the\nregister\'s outline is. A child List on a record with this layout draws the bars of the rows its link names. Worked: `examples/gantt`.\n\n#### Roster\n\n`layout: "roster"` with a List inside it over the child whose rows fill the days \u2014 one link back to the\nregister\'s table and a date on its line: what each row did on each day (shifts, runs, attendance). With\n`expect` (and `of`) on the cells the columns are the options of a select instead of days: which papers each row holds.\nAn `Export` with an html or Excel `template` prints the grid as the screen reads it (`document_templates/a-template`). Worked: `examples/roster`.\n\n#### Weekly pattern\n\nA row that owes a child\'s rows on set weekdays (a class\'s lessons, a person\'s shifts) states `records.cadence`, its days\na multi-select whose options are aliased `mon` to `sun`, and its times two `format: "time"` fields. The multi-select draws\nas a week strip wherever a person writes it; a Section holding the cadence\'s fields draws them as one week pattern; the\nrow\'s line reads it as one fact ("Tue, Thu \xB7 16:00\u201317:30"); a roster of the child reads each row\'s own days. An Act\n`makes: "<child>"` lists the rows still owed under the row each is made for, a group\'s count and tick at its head, a\nrow that would be refused unticked with why, and writes the ticked ones (`reference/record-places-pins-and-cadence`). A row that differs from a changed pattern is proposed as a move, ticked only where no person edited its day, end or a copied field and no row links to it; the class says how many rows differ.\n\n#### Agenda\n\nA child List with `layout: {"agenda": {\u2026}}` on a record: a child\'s planned entries by day, soonest first, today marked, each with its\npicture; within a day by the hour, or by a single select of the part of the day. `start` counts Day 1 from a\ndate of the record.\n\n#### Timeline\n\nA child List with `layout: "timeline"` on a record: a child read as a log of dated entries, newest first, with a composer \u2014 the\ncalls, visits and notes about the record, each with who and when, and its files where the child\'s `image`\nnames them. An app\'s Record draws no comment thread: a team\'s discussion on a record is a child table. Entries planned ahead are an agenda; the status\'s moves are its history. Worked:\n`examples/party`.\n\n### Moves and numbers\n\n#### Moves\n\nThe rows of a root List that a status stages towards its `closed` options move by Acts: each moves one option on to the next (`when` the\nstatus holds it, `set` to the next), at the foot of the Section whose work it ends. A status with nothing closed is a\ncondition a person sets. A value decided as a row reaches an outcome \u2014 why it was lost, refused, voided \u2014 is that\nAct\'s `asks`, never a field the reader must remember to fill. An Act reaching past the workspace \u2014 sending an invoice\nto a service, a letter by mail \u2014 runs its `workflow`, and what the workflow keeps from the answer (an invoice\'s id,\nits link) is named in the Act\'s `set`. Work sent back for changes moves back to the earlier\nstep; a hold is a yes/no field (and its reason) the step\'s Acts wait on in their `when`; work only some rows take is a\nstage\'s `when` (below); an issue to resolve is a row of its own. An Act also moves a row back (`when` the later\nstage, `set` the earlier): the row draws it beside the way on, and without one a row moved on by mistake stays until an\nadmin edits the table. What a `workflow` or a paper did stands, so a way back there is a correction of its own.\n\n#### Stages\n\nName each job\'s work plan by its shape: a status a person sets; a pipeline, where who holds the row and for how long\nmatter; or tasks, where only how many are done counts (`records.task`). A pipeline states each stage once in\n`records.status.stages` \u2014 its `owner` (a member field, a link\'s member field, or `{ "group": <id> }`, a member group) and its target\n`within` days \u2014 and the server holds it: only the owner\'s Acts move the row on, and a row created at a stage past the first is a move into that stage from nothing, which the stage\'s owner, an unowned stage\'s writer or a workspace admin (loading history) may make, on every path a row is written by, and a level an amount skips stands\nnamed with why. A move forward passes each owned stage between that binds the row, each its owner\'s. A stage\'s `when`\nnames the rows it binds, held as an Act\'s `when` holds them on the row\'s own fields (a total a rollup sums or a yes/no a formula yields among them), as the row stood before a write\nand as the write leaves it; with none, it binds every row. Expense claims over a limit wait for the finance group while\nsmaller ones go straight to payment: `"finance_review": { "owner": { "group": <id> }, "when": { "amount": { "gt": 5000000 } } }`.\nA row at a stage leaves it by its owner whatever its `when`; `dropped` names the closed options\nthat leave the work undone (cancelled, rejected), which whoever holds the row moves it to from any stage. A stage\'s owner gates who moves a row out of it; who may move a row into a stage ("only a bookkeeper marks an invoice paid") is a check. Late rows, rows due soon, a warning the line draws and rows waiting on the reader stand first in a\nregister; a register whose job is a strict order, a first-come queue, states `attention: false`.\n\nA status draws one of three ways, by what the author states, never by habit. With nothing `closed` it is a condition a person sets: its select, no steps. With `closed` it is a path: one a person moves by hand (no Act moves it, or its `row` states `status: { edit: true }`) keeps its select alone, and one Acts move draws its stages as a line of steps across the page, each only moving the row on. Where a stage holds something of its own \u2014 fields, blocks, an act that asks or files a paper, a note \u2014 the Record states it as a Section inside `Steps`, and the path draws down the page, each step holding what its stage holds.\n\n#### Stage dates and history\n\nWho changed what and when is the platform\'s audit trail, never a table and never shown by an app. When a stage\'s moment matters\nto the business \u2014 reported, filtered, printed \u2014 it is a date on the row that `records.status.dates` stamps as the row\nenters the option, whoever writes: the one way a status is timed, and the moment a stage\'s `within` runs from (each stage, and\neach open option of a status with stages, naming none gets `<option>_at`). A straight-line process is one select of its steps in order, each dated (a record that states no `Steps` draws it as a line of steps by itself: no date fields or formulas copy it); a move whose\nday may already be past `asks` that date with `starts: "today"`. `records.status.history` names a child the record write path appends one row to per\nstatus move (its link to the row, the new status, the moment and who) for a business that reports on every move: moves\nper person, or time in a stage a row re-enters. An event with facts of its own \u2014 a reason, an amount, a signature \u2014 is\nits own table, made by the act that records it. The rail reads the history. Worked: `examples/approval`, whose history is kept because a group\'s\nstage is signed once per person, read off who moved the row.\n\n#### Readings\n\nA List usually opens with one band of figures or a chart, chosen for what that person watches. Its Readings stand above the rows and its filters and read the rows under the open tab, never narrowed by the controls below them. Lead with the job\'s headline number \u2014\nits exception as a formula\'s yes/no in a Reading\'s `where` (what is short), never a stage the\nstatus chips already count, nor the overdue rows the register\'s summary line counts from `records.due` \u2014 then at most the mix (`by` a field) and the movement (`by` a date), varied by job. A movement over a date is stated, never defaulted; so is a sum, but for the one a status register with a money figure leads with by default: that figure over its open rows, titled by them ("Price (open)"). A register with no such figure and no single select to split by gets no default band.\nA grid (`by` and `across`) reads on a Sheet. A Sheet \u2014 a View of Readings at the App\'s root, beside its Lists or alone \u2014\nanswers one owner\'s question across jobs, each Reading windowed by the reader\'s period (the App\'s `period`), and a\nList on it hands over the rows to act on. Many Readings stand on several Sheets, each a View the reader picks. A\ndashboard varies its charts by the job. A question one app\'s rows answer goes on a Sheet there; one spanning apps gets a small app of its own. A Record\'s Readings read its own child rows. Sums of each row\'s child rows are a Tab\'s `totals`. Worked: `examples/approval`, `examples/dashboard`.\n\n#### Funnel\n\nA Reading with `steps` reads a record\'s child rows as steps, each a number column summed over them \u2014 an order\'s lines\nfrom ordered to shipped. It states how much of the first step\neach later one keeps, the share lost between two neighbours, and the last over the first. State two to six\n`steps` in one unit; where the path turns \u2014 reach, then conversion \u2014 state two Readings one straight after the\nother, so the second\'s bars are read over its own first step, on one grid. A step no row holds a number in reads as not measured: leave it empty, never a zero nobody measured.\n\n#### Priced lines\n\nA quote\'s items, an estimate\'s works, a repair sheet\'s damages are lines priced off a book: a table whose\n`records` names each item, puts the code people type on its line and its price as its `figure`. The line links to\nit, asks the link and its quantities in its List\'s `create`, and copies the price (`default_from`), so the quote\nkeeps what was quoted when the book moves. A line\'s amount is a formula, the record\'s total a rollup over the rows\nthe List shows \u2014 what is not paid for is a second rollup, never a filter on the first, so each group subtotals.\nGroup the lines by the parts the record is quoted in (a container, a room, a leg), a field the line asks. A book worked only while a quote is written is the picker on the quote\'s lines; a book with a keeper, Acts or a history of its own is\nan app (`app_architecture`).\n\n### The record\n\n#### Sections\n\nA record is a head, its parts and at most one Side. From three parts it shows one part at a time; fewer stack. A part is one area of the record\'s data a person comes to for its own job, like the tabs of a settings page; its related lists and field groups sit inside it under their headings. A status\'s stages are not areas: their acts stand at the foot of the rows they move, and a stage that holds something of its own \u2014 fields, blocks, acts, a note \u2014 is a Section inside `Steps`, one `Steps` to a record. State each\npart whole for the work there: a field may stand in any number of parts, and a field an Act requires draws beside it\nunstated. A stage that holds nothing needs no Section: the path draws it by its name. What a person needs in view at every part (who it is for, how to reach\nthem) goes in a Side: it leaves the head and stays on the rows; what only a stage\'s Act writes (an invoice\'s number,\na delivery\'s signature) stands empty before it, so it goes in that stage\'s Section inside `Steps`, never the Side. The status\nstands in the head or the Side, never a Section. `row` changes how the app\'s rows read, never a page nor what the app writes. A List, Reading, Statement or Act stated alike in several\nSections draws once, in the first; a Check stated in a Section guards the whole record.\n\nThe Record\'s Sections, in the order the work reaches them: the fields people write, a Field per paper the record\nkeeps, a child List per child, the Acts at each one\'s foot. A register\'s `columns` are in the order the job reads them, as many as fit a desk; what is read only on the way deeper is the Record\'s, and a figure that is final only from a stage is a Field of that stage\'s Section, never a column read on every row at every stage. A register laid out in time (calendar, lanes, roster) opens the\ndefault record: every field a person writes. Behaviour belongs in an Act.\n\nA Section of more than about six fields reads as Fieldsets of related facts: a patient\'s record holds "Contact" and\n"Insurance" rather than one run of nine, each Fieldset\'s `label` a few words. A gallery or prose Field stands beside the Fieldsets (`reference/fieldset-node`). Fields in a part come first, a Fieldset where they need a heading. Only where the arrangement itself is the need does the Fieldset state `Line`s \u2014 two weights and their difference on one line \u2014 and `heads` where several Lines repeat the same columns, a fee\'s amount, its payment and its invoice button per row (`reference/line-node`). A figure only that screen shows is a `Value`; one a list, a report or an export reads is a formula field of the table. Fields stand two\nto a line in the order stated, and files, prose and a link to several rows take the whole line: stated after a lone\nshort field, one leaves the half beside that field empty.\n\n#### Children\n\nRows that each belong to one row of another table (a one-row link to it) are drawn under that row: a List on\nits Record, `layout: "timeline"` where they are a log, `layout: {"agenda": \u2026}` where they are planned on a day and within it, or\n`layout: {"gantt": \u2026}` where they are bars on a schedule. Which children a record lists is the author\'s \u2014 one of them at least. A List\nlisting only some of them narrows by its `where`: a select (one leg\'s fees), or a yes/no \u2014 a formula\'s for what is\nstill owed \u2014 on a List that adds no rows. A child List stating no `create` asks the table\'s required fields, natural key and\ntitle; where defaults fill them all, it adds none. Rows on\nfile before the row they come to belong to \u2014 a job\'s cost lines before the supplier bill over them \u2014 are picked into\nit: a List with `pick`, often with no `create` and no `remove`.\n\n### Papers\n\n#### Expect\n\nA List with `expect` naming the child\'s title \u2014 a single select of kinds, or a one-row link to a\ncatalog: one line per kind, the ones not yet filled standing empty, filled in place. `of` narrows the kinds\nto the record\'s own multi-select of those it needs. The papers a case gathers, the fees a record knows it\nowes. Worked: `examples/case`.\n\n`only` lists the kinds a List holds a line for, so each kind stands in the Section whose job it is, once. The Act making a paper (`paper: "<child>.<kind>"`), stated in the Record beside its Sections and moving the record as any Act does, is its line\'s button while it applies, the upload in the \u22EF.\n\n#### Templates\n\nA paper the business makes is an Act\'s `template`, kept in the record\'s files field `into` \u2014 or several at\nonce, `templates`: listed where the Act stands, each made one as its file, each not yet made a placeholder,\nthe reader ticking which to make. Worked: `examples/case`.\n\n#### Intake\n\nA paper the business is brought and reads is an Act\'s `intake`: the press takes the papers, an agent reads\nthem, and each is filed as the line of its kind in the child the record `expect`s, while `fills` writes what\nthey state into the record\'s fields \u2014 a single link as a row the agent finds among those the app reads \u2014 shown before it is saved. Stated with `on: "view"` at the register\'s title, the papers make a NEW record instead: `fills` names what it requires, `<link>.<field>` fills the row a required link names (found on its entity\'s `natural_key`, else added), and the register opens the record made. Worked: `examples/case`.\n\nAn agent Act \u2014 an `intake`, a `record`\'s `fills` \u2014 spends a run on every press, so it is stated only where the\nowner asked for an agent to do that job; otherwise a paper brought is its `expect` line, and a person types what it states.\n\n#### Under\n\nA List with `under`: the documents that cover lines (an invoice over its fee lines) stand as headings\nover the lines they cover, and a line no document covers offers to make one. A document entered as it arrives over lines\nalready on file (a supplier bill) picks them with `pick` instead; choose one per document.\n\n### Calls\n\n#### Record act\n\nAn Act\'s `record`: the press records a call, visit or meeting \u2014 audio, transcript, screen where captured \u2014 and\nfiles it as a new row of the record\'s `timeline` child (`into`), stamped `at` and `by`; `fills` lets an agent fill\nthat row\'s fields from the transcript, where the owner asked. Worked: `examples/calls`.\n\n';
|
|
1874
|
+
var design_default = '# Designing an app\n\nAn app is a tree of components: a List of one table, the Record a row opens, its Sections, the Acts that move it. The\ntree states COMPOSITION \u2014 which fields, lists and acts each job\'s screen holds; how each piece looks is the platform\'s,\none way per concept. A node the tree leaves out draws its default, from the table\'s facts (`records`, the stage, the\nwrite rules): a List\'s Readings band, the stage buttons, the picture. What a write stores, and the Section that follows the table: `reference/changing-an-app`. State a node to change it,\nor `false` at it to turn it off (`"readings": false`, a Record\'s `"row": { "image": false }`). A field is written where its Record declares it: a Section\'s Field, the table\'s face (title, line, picture, figure), or every field where the Record states no Section; the head, a line, a column or a board draws it, and never makes one written; every head part (`row.title`, each `row.subtitle` entry, `row.figure`, `row.image`) takes `edit: false` to be read. A drawn Field is a control unless it\nor its entity is read-only (`edit: false`); a stepped status is not, since Acts move it, unless its `row` states `status: { edit: true }`. Which apps a business needs is `app_architecture`.\n\n**The visual bar.** Every screen is judged against it; a miss is a change to the tree.\n\n- Each app looks like its own rows: the view its kind of row takes (`design/treatments`) \u2014 cards for things found by\n their photo, a calendar or lanes for dated work, faces for people and organisations. A List left as a table is drawn\n as one, the most common failure of an app; the answers of `set_app` and `get_app` note the view rows that are work in time call for (a calendar, lanes, a roster, a gantt where rows wait on one another).\n- What needs attention leads the row as an issue its table declares (`design/issues`): a derived flag is an issue, in the\n warning tone on the row\'s line (in the danger tone where a Check\'s `on` refuses an act the row offers); every other yes\n reads in the success tone. `records.mark` is a category\'s own mark, a select whose options carry a brand or glyph.\n- A list\'s columns: the name and its lead, the status, then the columns the job reads on every row, as many as fit a desk. Each\n fact once: a column the row draws itself stands once. A generated number (`autonumber`) as the title yields\n the row\'s name to the subtitle\'s first part and stands first on its line. A row listed under its record is named by its\n subtitle\'s first part where its title only reads that record (a join row\'s lookup through the link back): title a join row by one side, its subtitle the other.\n- A list worked by a date states `sort` on that date\'s column, newest first; without one, a register reads newest made\n first and a record\'s child List in the order its rows were added.\n- Someone is a face wherever they are read: a link to a table stating `records.party` draws its row\'s face; a member\n field is one already; select options naming people or organisations who are neither each take the `mark`\n `{"kind": "avatar", "name": "person"}`, never a colour dot.\n- A thing shows its picture, a file its preview, a plan its days on a time axis, a quantity a meter (`records.limits`) or\n a chart, a register its Readings, and long text reads whole (a markdown Field; `block: true` on plain long text).\n- An option with a `color` draws its dot where its select is drawn; one without reads as its word. A `mark` where a\n brand or glyph names the option, on every option of a select read down a column (how it was paid, the channel).\n- Every app states its tile\'s `color` and `icon`, each apart from the workspace\'s other apps where it can be: an\n app stating no icon draws the one glyph every such app shares.\n- The paperwork is the proof of the work: a files field per purpose (what arrived, what was issued to the customer, the\n carrier, the authority) in the Section where that work happens, and the source of a\n figure (a screenshot, an email, a sheet) on its row. Every files field is drawn somewhere. A paper a counterparty\n sends (a supplier\'s invoice, a delivery receipt) is added on the record it arrives with \u2014 the order it is for \u2014 and\n listed again where it is settled, never only in the counterparty\'s ledger.\n\n<!-- generated:start words -->\n\n**The words most builds state.** A node\'s page holds its rules and every other word: `reference/list-node`, `reference/records`, `reference/field`.\n\n**Table**\n\n- `ref` (alias): A created table\'s handle in this call\n- `label` (text, required): The table\'s name in the workspace\n- `singular` (text): One row of this table, in the business\'s own words\n- `title` (alias): The alias of the field that names a row wherever a link or a record shows one\n- `fields` (map of alias \u2192 Field, required): The table\'s columns, each under its alias, which is its key here and so is never stated inside it\n- `records` (any value): How a row is recognised\n- `checks` (map of alias \u2192 table check (`workflows/table-checks`)): The conditions a write of the table\'s rows may not meet, each under its alias\n- `unique` (list (at least one) of list of alias (at least one)): Sets of fields whose values no two live rows share\n\n**Any field**\n\n- `label` (text, required): The field\'s name in the workspace\n- `required` (boolean): Refuse a record whose cell for this field is empty\n- `default_from` (text): Copied when a record is made off the row a one-row link of this entity names\n\n**`number` field**\n\n- `notation` (notation): How the figure reads\n- `min` (number | text): Refuse a create or update whose value is below this\n\n**`select` field**\n\n- `options` (list of Select option (at least one), required): The choices, in the order every picker and every ladder lists them\n- `multi` (boolean): Allow multiple selections\n\n**`link` field**\n\n- `table` (text, required): The table the link points at\n- `multi` (boolean, required): Whether a row links to one row or many\n- `pair` (`true` | alias): Makes the link two-way\n\n**`formula` field**\n\n- `expression` (text, required): The expression, over fields of THIS entity by alias in braces\n- `output_type` (`"number"` | `"text"` | `"date"` | `"datetime"` | `"boolean"` | `"select"`): Holds a formula to the type its readers need\n\n**`rollup` field**\n\n- `via` (alias, required): The alias of a link of this table to roll up from\n- `op` (operation, required): The operation over the linked rows\n- `field` (alias): The alias of the field on the linked table the operation reads\n\n**`lookup` field**\n\n- `via` (alias, required): The alias of a link of this table to look up through\n- `field` (alias, required): The alias of the field on the linked table to show\n\n**`autonumber` field**\n\n- `prefix` (text): Literal prefix prepended to every display value (e.g. \'KH-\' \u2192 \'KH-001\')\n\n**`records`**\n\n- `subtitle` (list of alias (1\u20132)): Up to two fields read under the title wherever a row is drawn (a code, a date, a party)\n- `figure` (alias): The one number the row stands for, read at its right (a total, a quantity left)\n- `status` (Status): The stage a row moves through, a single select, drawn in the record\'s head, or its Side where the Side states it\n- `due` (list of alias (at least one)): Dates that are deadlines (stored, or computed as a date)\n- `image` (alias | list of alias (at least one)): A files field that pictures the row, or a one-row link to a table with a picture (or a lookup of one through a one-row link: a delivery led by its order\'s customer), whose picture the row leads with\n- `party` (`"person"` | `"organization"` | `"organisation"`): What each row is where the rows are people (a contact, a patient) or organisations (a customer, a supplier, a carrier)\n- `limits` (map of alias \u2192 (alias | number)): A number read against a bound\n- `starts` (map of alias \u2192 `"today"` | `"me"`): What a field of a row being added starts at, where that start is certain\n- `mark` (alias): A single select (or a lookup of one through a one-row link) whose option leads the row wherever a mark leads it\n- `settled` (alias): A yes/no of the row (stored, a formula: an invoice paid in full, or looked up through a one-row link: a line settled with its parent) that ends its deadlines\n\n**`records.status`**\n\n- `field` (alias, required): The single select that is the row\'s state, its options in the order the work goes through them, drawn as a line of steps on a record page where no Section states `at`\n- `closed` (list of alias (at least one)): Options that end the work\n- `history` (text): A table every write that sets or moves the status appends one row to (its link to this table, the new status, the moment and who)\n- `dates` (map of alias \u2192 alias): Option alias \u2192 a date field of this entity the record write path stamps with the moment a row moves into that option, or is made at it\n- `stages` (map of alias \u2192 Stage): Option alias \u2192 who owns that stage and how long it should take\n\n**App**\n\n- `key` (alias, required): The app\'s alias, its name among apps\n- `name` (text, required): The job, in the words of the people who do it\n- `children` (list of (List over a Query | List | Sheet | Query | Workflow) (at least one)): The App\'s Views in order\n- `color` (colour): The launcher tile\'s colour\n- `pages` (list of Record (at least one)): The page the rows of an entity open, one per entity, each a Record stating its `entity`\n\n**List**\n\n- `entity` (alias, required): The table whose rows the List draws\n- `create` (boolean | list of alias (at least one)): The fields an add asks\n- `columns` (list of (alias | Edit column)): Fields read after the row\'s title, each drawn though no row holds it\n- `label` (text): The register\'s name in the app\'s lists and tab strip\n- `filters` (list of (alias | Tiered filter | Listed filter) (at most 3)): Fields the reader narrows by every day, beside the stage chips, at most 3\n- `children` (list of (Tab | Reading | Export | Act | List) (at least one)): Its Tabs, band Readings, Exports and Acts over ticked rows or every row in view\n- `key` (alias): Names the List among its siblings and in a Query\'s `list`\n- `sort` (Sort key | list of Sort key (at least one)): The rows\' order\n- `layout` (layout): A word, or an object stating one layout with its data\n- `remove` (boolean): Rows offer a Delete\n- `search` (list of alias (at least one) | `false`): Fields the search box reads\n- `where` (narrowing): A fixed narrowing on the server, for every reader\n- `group` (alias | `false`): A field the rows stand grouped by, a gantt drawing the groups as its lanes, a lanes board of days its cards\' sub-headings inside each lane\n- `expect` (alias | Expect): What a record should hold, shown before it does\n- `opens` (narrowing): The view the register opens on, a chip the reader may take away\n\n**Record**\n\n- `entity` (alias, required): The table whose rows open on this page\n- `children` (list of (List over a Query in a Record | alias | Field | Fieldset | Section | Steps | Side | Outside | List | Reading | Statement | Comments | Act | Check) (at least one)): Parts (Section, Side, and one Steps holding the Sections that are its path), or for a one-part record its Fields, Fieldsets, Lists, Readings, Statements and Comments directly\n- `add` (`false` | list of alias (at least one)): What a new row asks where a picker of this entity offers one, anywhere in the App\n- `row` (Record row): How the App reads this entity\'s rows wherever it lists them\n- `door` (`"page"` | `"drawer"`): How a row opens, on a page or in a drawer\n\n**Section**\n\n- `title` (text): The part\'s heading\n- `key` (alias): Unique among its siblings\n- `children` (list of (List over a Query in a Record | alias | Field | Fieldset | List | Reading | Statement | Comments | Act | Check) (at least one)): What the part draws, in reading order\n- `at` (list of alias (at least one)): The status options this part is the work of\n- `when` (condition): Drawn only while this holds\n\n**Field**\n\n- `field` (alias, required): The field\'s alias\n- `edit` (boolean): Shows a value nobody changes here\n- `label` (text): The heading of the field\'s gallery or prose block, where it draws as one\n- `block` (boolean): Gives a field room of its own\n\n**Act**\n\n- `key` (alias, required): The act\'s name\n- `label` (text, required): The verb, as the reader says it\n- `when` (condition): The act works only while this holds\n- `set` (map of alias \u2192 value): What the act writes\n- `asks` (list of (alias | `{ "field": alias, "starts": "today" | "me" }` | Asked input) (at least one)): What the reader states on pressing\n- `confirm` (`true` | `"warnings"` | text): The press asks first\n- `requires` (list of alias (at least one)): Fields filled first, each drawn where the act stands\n- `template` (alias): A document template it makes a file from\n- `into` (alias): The record\'s files field keeping the document\n- `owner` (`"field"` | `"link.field"` | `{ "group": id }`): Who presses it\n- `workflow` (alias): The workflow it runs for what `set` cannot say\n- `danger` (`true`): The act destroys or cannot be undone\n\n**Check**\n\n- `field` (alias, required): A yes/no or text formula of the page\'s entity\n- `on` (`"all"` | list of (`"update"` | alias) (at least one)): What the standing issue refuses\n- `resolve` (alias): An Act on one row of this entity that clears it\n\n**Reading**\n\n- `label` (text): What the figure is called\n- `value` (alias | `{ "avg": alias }`): A number field summed over the rows, or `{ avg }` averaged over the rows holding one\n- `by` (alias | Tiered filter): Splits the rows into parts\n- `where` (narrowing): Only the rows whose select holds one of these options, whose yes/no is this value, whose number or date meets its bounds (`gt`, `gte`, `lt`, `lte`; a date\'s `{ "now": true }` is read when the rows are), whose field is `{ "empty": true | false }`, or whose member field holds the reader (`{ "me": true }`)\n- `entity` (alias): The List\'s rows\n- `over` (alias): The date that places a row in time\n\n<!-- generated:end words -->\n\n## Issues\n\nWhatever goes wrong on a row and needs a person to act \u2014 a line delivered short, a price missing, a customer over their\ncredit limit, a permit about to expire \u2014 is an issue its table declares in `records.issues`. A declared issue stands in\nevery app that draws its row, with no app stating it: first on the row\'s line (`+N` the others), in the record\'s callout (a count of child rows as pills on those rows), in the List\'s filter of what needs checking with how many rows hold it, and those rows first. It never makes an\napp draw a row it did not, and never shows on an `Outside` page. What needs no one\'s action is no issue: a stage is the\nstatus, a category a select. A record\'s callout says each issue by its label and what it means: a text issue\'s own sentence, a yes/no issue\'s field `description` \u2014 give a yes/no issue\'s field one, or its line shows the name alone.\n\nAn issue is a promise that someone will act every time it stands: people and their agents see it on every row it holds.\nDeclare one only where the owner confirms each flagged case is a problem; a rule that flags rows nobody fixes trains\neveryone to ignore the colour, real issues included. Where a flagged row may be accepted as it is (a price agreed by\nexception), give the acceptance a field the formula reads, so accepting it clears the issue.\n\n- An issue is a formula of the row stating `output_type`: `"boolean"` stands while true; `"text"` stands while not empty,\n its words the sentence the reader sees \u2014 use it when the sentence must say what or how much ("Short 4 of 10").\n Its label is its name. Put the moment it matters in the formula, so it clears itself when the work is done.\n- The list is priority: an issue blocking the next step leads, then the earlier in the list.\n- `{ "rows": <link> }` on a parent rolls up every issue its child table declares, through a many-link paired to the\n child\'s one-row link back. The platform keeps a count on the parent per child issue, `<link>_<issue>`, labelled\n "<link label> \xB7 <issue label>"; never write it. The parent reads "2 rows left: Lines \xB7 Short".\n- A formula reading `now()` or `isToday()` (overdue, expiring within 30 days) is judged again every night, to the day.\n- An app\'s `Check` says what the issue does not: `on`, what it refuses in that app (`"update"`, `"all"`, or that\n entity\'s Acts), and `resolve`, the Act that clears it; one stating neither is refused, and one without `on` names a\n declared issue. A parent\'s Act is refused by a Check on the parent\'s count `on` that Act (never `"update"` or `"all"`: editing the rows clears it); the act then holds\n the parent while it runs, so its own `workflow` cannot send mail, notify, run an agent or wait \u2014 start that work from a\n workflow the act starts after.\n- A lock is a Check, not an issue: a yes/no such as paid in full refusing `"update"`, in no `records.issues`, since nothing\n is wrong with the row.\n- `get_table` reports each issue: rows holding it now, opened in the last 30 days, median days to clear.\n\nAn order whose lines can arrive short or unpriced, invoiced only when no line is short:\n\n```json5\n// order_line\n"fields": {\n "short": { "label": "Short", "type": "formula", "output_type": "text",\n "expression": "!isEmpty({delivered}) && {delivered} < {quantity} ? \\"Short \\" + toString({quantity} - {delivered}) + \\" of \\" + toString({quantity}) : \\"\\"" },\n "no_price": { "label": "No price", "type": "formula", "output_type": "boolean", "expression": "isEmpty({price})" }\n},\n"records": { "issues": ["short", "no_price"] }\n// order \u2014 `lines` is its many-link to order_line; the platform adds lines_short and lines_no_price\n"records": { "issues": [{ "rows": "lines" }] }\n// the order\'s Record in the app\n{ "type": "Check", "field": "lines_short", "on": ["invoice"] },\n{ "type": "Check", "field": "paid_in_full", "on": ["update"] }\n```\n\n## Look at it\n\nAfter an apply, `screenshot_app` draws each app as its people see it \u2014 the register, and a record by its `path` or its `record_id`\n(with a `path` on that record: one Section is `/<record id>?section=<its title>`; `screen` for a later screen of a long one), up to six `pages` in one call \u2014 at a desk\'s width and a phone\'s, naming the columns a table left off at each width;\n`-o <dir>` saves the shots from the CLI. `set_app` with `app_id`, an empty `body` and `dry_run` answers what a write of the\nstored tree would be refused for now, and its notes. Answer `design/the-rubric`, change the tree with `nodes`, and write again. To go back,\nsend the tree saved before the change as `body` with `app_id`, nulling an App prop stated since (`words`, `scope`,\n`period`, `icon`); tables and rows stay as they are.\n\n## The rubric\n\nWhether the build does the owner\'s work, answered by a call each, never from what you meant to write:\n\n1. Each job the owner named, and each their kind of business cannot run without: which screen does it, and which press? Find each on a `screenshot_app` shot of the person who does it (`as_member`); one who cannot open the app is first invited (`set_members`) and given it (`set_access`) \u2014 an app nobody shares opens for admins alone.\n2. Can an agent do each job in one call, an `act_<key>` or a Query or Workflow node whose `description` names it? `get_app` lists them; `run_app_workflow` with `dry_run` proves one (`agent_surface/prove-an-app-as-an-agent`).\n3. Is each kind of row in its treatment (`design/treatments`)? Timed work reads in a calendar or lanes, and a weekly plan as the dated rows it makes.\n4. Does each screen show the least its next step needs, each fact once, the signal that a step is due leading?\n5. Is anything cramped at desk or phone width?\n6. Is every paper and every Export made, those this kind of business sends unasked too, with no blank? Press each paper Act and read the file it files; prove an Export with `run_app_query` and `export`.\n7. Is each thing that must never happen in this business (a step taken before its approval, stock below zero, a double booking) refused on every write? Prove each with a write sent `dry_run: true` that is refused (`workflows/table-checks`).\n\nA failed answer is a change to the tree, or a gap named to the owner.\n\n## Treatments\n\nThe answers of `set_app` and `get_app` note the view rows that are work in time call for (a calendar, lanes, a roster, a gantt\nwhere rows wait on one another), naming the node that would state it; a note refuses nothing. No other treatment below is noted.\nEach kind of row\'s view is chosen before its List is written:\n\n| The rows are | The treatment | Its own page |\n|---|---|---|\n| People or organisations | `records.party`, with a photo or logo as its `image` | |\n| Things with a photo, a scan or a paper | `records.image`; List `layout: "cards"` where the picture is how a row is found | `reference/cards` |\n| Read by their day | List `layout: "calendar"`; on a record, a child List with `layout: {"agenda": \u2026}` | `reference/calendar`, `reference/layouts` |\n| Ranked by a figure, or worked by a date | List `sort: {"field": \u2026, "desc": true}` on that column | |\n| Booked on a resource | List `layout: {"lanes": {"by": \u2026}}`, and the table\'s `no_overlap` \u2014 a list of rules where a row holds two (a room and a teacher) | `reference/lanes`, `reference/write-rules` |\n| A day\'s work given out to people or vehicles | List `layout: {"lanes": {"by": \u2026}}` over rows holding a day and no hour | `reference/lanes` |\n| A log of what happened | a child List with `layout: "timeline"` | `reference/layouts` |\n| Opened to be worked on | the Record\'s Sections \u2014 each one area of the record\'s data, its lists and field groups inside it; a status\'s stage acts stand at the foot of the rows they move; a stage that holds something of its own, a note included, is a Section inside `Steps`; fields only one kind of row holds (a delay\'s cause, a safety issue\'s hours lost) in a Section whose `when` names that kind | |\n| Rows that each belong to another row | a child List on that row\'s Record, with `create` and `remove` \u2014 and a child\'s own rows a List in that child\'s page, as deep as the data goes, and every row\'s \u22EF offers Duplicate; a List with `same` where read-only | |\n| A related row\'s value on the list (the newest contract\'s end date) | a `lookup` field of the table, ordered, as a column | `reference/lookup` |\n| Moving through a status | an Act per move, `status.dates` for the moment of each stage, and the register\'s Readings | |\n| Counted over a period | the register\'s Tabs over one `period`; a Tab\'s `totals` for a child\'s sums before, during and through it; an open Tab\'s `where` reads only what was true at the period\'s end, never a status the row moves on from | |\n| Papers a case gathers | a List with `expect`; the papers made, an Act\'s `templates` | |\n| A plan of spans | List `layout: {"gantt": {"start": \u2026}}` | `reference/gantt` |\n| Stood at a place on a plan, flat or in 3D \u2014 pallets, bins | List `layout: {"plan": \u2026}`; places state `plan_place` | `reference/plan` |\n| Checked item by item against a standard | a List with `checklist: {"photo": \u2026, "clause": \u2026, "failed": [\u2026], "passed": \u2026}`: each row a mark (passed at `closed`, failed at a `failed` option, or by the yes/no `passed` names \u2014 a measured verdict, no task or status needed), its photo and the clause it is checked against; with `expect` on the standard\'s items, each item is a line marked the same way and filled by the block\'s columns | |\n| A place before and after the work | a List with `compare: {"before": \u2026, "after": \u2026}`: two files fields read side by side, or two value fields read as one struck-then-new column | |\n| Spots on a drawing | `records.pin: {"on": \u2026, "x": \u2026, "y": \u2026}` on the spots\' table: a record listing rows that link to them draws the picture with a numbered pin at each; the picture is the `on` row\'s `records.image` | `reference/record-places-pins-and-cadence` |\n| Photos that must be taken on site | a files field with `photo_places: true` keeps where the device stood for each photo shot through the camera; judge them in a text formula `distance({photos}, {site_lat}, {site_lon})` listed in `records.issues` | `reference/formula` |\n| A number painted on the thing, or a barcode or QR code on it | `records.scan: "iso6346"` or `"text"` (read off one photo by an agent), or `"code"` (decoded on the device, no agent): the title read on a phone, beside each search matching it | `reference/record-places-pins-and-cadence` |\n| The rows a weekly pattern owes (a class\'s lessons on Tue and Thu at 16:00) | `records.cadence: [{"entity": \u2026, "on": "<a multi-select of mon\u2013sun>", "start": \u2026, "end": \u2026, "planned": \u2026, "except": \u2026}]` on the parent, and an Act `makes: "<child>"`: the press lists the rows still owed, each with what would stop it, and writes the ones ticked; pressed again it lists what is missing, and moves a row to the pattern\'s hours and copied fields where it differs and no person or linked row has touched it (ticked), else leaves it unticked saying why | `reference/record-places-pins-and-cadence` |\n| Who did what on which day | List `layout: "roster"` with the List of its cells inside | `reference/roster` |\n| Someone with no seat signs off one record (a buyer approves a proof, a client signs a handover) | the Record\'s `Outside`: the Fields and Lists the link shows as they are, and Acts that each move the status out of its `at` \u2014 a link a member makes of the record, never a seat; the link\'s page names the record only where the Outside states its title\'s field | |\n| Steps people drop out of between | a Reading with `steps` on the record whose child rows count them | |\n| A record\'s own numbers nobody keys, read at a glance | consecutive Readings with no `entity` (up to eight tiles) | |\n| Rows that are each a place a record is sent | a List with `expect` on the link to those places and `post`: each ticked, the post written there and read as its feed shows it | `reference/publish-desk` |\n| Papers an agent reads, where the owner asked for one | an Act\'s `intake` with `fills` | |\n| Calls and visits | an Act\'s `record` | |\n| Changes a workflow proposes that a person approves row by row \u2014 a price list applied, a statement matched to what is owed | an Act\'s `workflow` with `review`, its body returning a changeset in `data.review` | |\n| Documents covering lines | a List with `under` | |\n| Rows on file a record takes in | a List with `pick` | |\n| One owner\'s question across jobs | an App of Tabs and Readings and no register | |\n\nWhat these nodes do not state, a long-form writing page or a bespoke tool, is a custom-code app (`lotics app create <name> --custom`, `app_bindings`), never a new node.\n\n### Faces and pictures\n\n#### Party\n\n`records.party` is `"person"` where the rows are people (a contact, a patient, a driver) and\n`"organization"` where they are companies (a customer, a supplier, a carrier). Every surface drawing one of\nits rows then draws a face: its `image` (a photo, a logo), else its initials. Without it, a person is drawn as a thing. A workspace\nmember is a `member` field, and is drawn by their face already. A column holding a link to several rows of people,\nor several members, draws their faces as a stack that names them on hover. Worked: `examples/party`.\n\n#### Image\n\n`records.image` names the files field that pictures a row \u2014 a product\'s photo, a damage photo, a\nscan, a receipt. Every row of it then leads with its picture, or its paper\'s preview, wherever it is drawn \u2014\na row holding no picture leads with the placeholder; a link to it previews the file. `image` may instead name a\none-row link to a table with a picture (an order line\'s `item`), or a lookup of one through a one-row link (a delivery\'s `customer`, through its order): the row leads with that row\'s picture, still titled by\nits own words \u2014 or several in order (`["product", "bundle"]`, a line linking either), the first that holds a picture leading the row. Never a field an Act keeps the paper it makes in (`into`). List\n`layout: "cards"` where the picture is how a row is found. The table\'s `records.image_shape` (`portrait`, `square`, `landscape`) states the shape the register\'s cards and tiles and such a List draw it at. A files field the record keeps as a folder of\npapers is drawn as a Field, read whole. Worked: `examples/cards`.\n\n#### A link opens its row\n\nEvery row an app draws opens on its page, the one you state or the one a write stores for you. A link\'s row shows its name, line, status and figure. State `pages/<e>` to show more or to edit.\n\n### Rows in time\n\nRows that each stand on a day, or hold a run of days or hours, are read where they stand in time \u2014 never\nas two date columns. A row holds a span when two dates a person states are ordered, the second after the first by a\n`min` or a table check, both required or the second the row\'s `due`; else it is an appointment when one required date\nis stated that no Act stamps, that a new row does not start at `today` and that is not derived. A stamp is an event,\nand a `due` is a deadline, never the day a row is held on. A `no_overlap` by a person or a value alone keeps one row at\na time each \u2014 a member\'s periods in turn \u2014 read by what they hold.\n\n#### Calendar\n\n`layout: "calendar"`, or `{ "calendar": { "date": "starts_at", "end": "ends_at" } }`: the rows by their day \u2014 a\nmonth, a week, a day or a list; an entry at its hour where `date` holds one, over its span where `end` names the date it\nruns to. The bare word takes both from the rows\' facts and is refused, naming `date`, where they name none. An entry pressed opens its row beside the calendar; where the app saves the row, a drag or F2 moves it. Worked:\n`examples/calendar`.\n\n#### Lanes\n\n`layout: {"lanes": {"by": \u2026}}` with `by` naming a one-row link whose target\'s rows are the lanes (a chair, a\nmachine, a room), each drawn even when empty: every row a block from the first date on its line to the\nsecond, and a free stretch adds a row there. `loads` reads what a lane carries against what it holds: hours summed\nwithin each day (across days, the fullest day, named), any other number the most its rows add up to at one time. A\n`no_overlap` `by` the same link refuses two rows on one resource at once. A lane per person: `by` a member field\nand `of` a group of the workspace by its id, each member of it a lane, idle ones too. Worked: `examples/lanes`.\n\nA day\'s work given out (stops to drivers, jobs to technicians): rows holding a day and no hour read at one day as cards\nin lanes, those no lane holds, or holding no day, first in a tray. Each lane\'s head reads its count, its loads and its\nrow\'s status; a lane its link no longer admits (`options_where`) says so in its head and refuses a card. Where the app writes the link, cards ticked or\ndragged go to a lane in one write, every row checked before any is written, and the List\'s first `sort`, ascending on a\nnumber the app writes, is a card\'s place in its lane.\n\n#### Gantt\n\n`layout: {"gantt": {"start": \u2026}}` (and `end`, else the table\'s first `due`; a `due` is a deadline, never an appointment date): one bar a row over\nits run of days, read against today. `milestones` marks\ndates on the bar, `planned` the plan under it, `progress` how far it is done, `after` the rows it waits on;\nthe List\'s `group` is its lanes; a table holding rows under rows nests each bar under its row above, folded as the\nregister\'s outline is. A child List on a record with this layout draws the bars of the rows its link names. Worked: `examples/gantt`.\n\n#### Roster\n\n`layout: "roster"` with a List inside it over the child whose rows fill the days \u2014 one link back to the\nregister\'s table and a date on its line: what each row did on each day (shifts, runs, attendance). With\n`expect` (and `of`) on the cells the columns are the options of a select instead of days: which papers each row holds.\nAn `Export` with an html or Excel `template` prints the grid as the screen reads it (`document_templates/a-template`). Worked: `examples/roster`.\n\n#### Weekly pattern\n\nA row that owes a child\'s rows on set weekdays (a class\'s lessons, a person\'s shifts) states `records.cadence`, its days\na multi-select whose options are aliased `mon` to `sun`, and its times two `format: "time"` fields. The multi-select draws\nas a week strip wherever a person writes it; a Section holding the cadence\'s fields draws them as one week pattern; the\nrow\'s line reads it as one fact ("Tue, Thu \xB7 16:00\u201317:30"); a roster of the child reads each row\'s own days. An Act\n`makes: "<child>"` lists the rows still owed under the row each is made for, a group\'s count and tick at its head, a\nrow that would be refused unticked with why, and writes the ticked ones (`reference/record-places-pins-and-cadence`). A row that differs from a changed pattern is proposed as a move, ticked only where no person edited its day, end or a copied field and no row links to it; the class says how many rows differ.\n\n#### Agenda\n\nA child List with `layout: {"agenda": {\u2026}}` on a record: a child\'s planned entries by day, soonest first, today marked, each with its\npicture; within a day by the hour, or by a single select of the part of the day. `start` counts Day 1 from a\ndate of the record.\n\n#### Timeline\n\nA child List with `layout: "timeline"` on a record: a child read as a log of dated entries, newest first, with a composer \u2014 the\ncalls, visits and notes about the record, each with who and when, and its files where the child\'s `image`\nnames them. An app\'s Record draws no comment thread: a team\'s discussion on a record is a child table. Entries planned ahead are an agenda; the status\'s moves are its history. Worked:\n`examples/party`.\n\n### Moves and numbers\n\n#### Moves\n\nThe rows of a root List that a status stages towards its `closed` options move by Acts: each moves one option on to the next (`when` the\nstatus holds it, `set` to the next), at the foot of the Section whose work it ends. A status with nothing closed is a\ncondition a person sets. A value decided as a row reaches an outcome \u2014 why it was lost, refused, voided \u2014 is that\nAct\'s `asks`, never a field the reader must remember to fill. An Act reaching past the workspace \u2014 sending an invoice\nto a service, a letter by mail \u2014 runs its `workflow`, and what the workflow keeps from the answer (an invoice\'s id,\nits link) is named in the Act\'s `set`. Work sent back for changes moves back to the earlier\nstep; a hold is a yes/no field (and its reason) the step\'s Acts wait on in their `when`; work only some rows take is a\nstage\'s `when` (below); an issue to resolve is a row of its own. An Act also moves a row back (`when` the later\nstage, `set` the earlier): the row draws it beside the way on, and without one a row moved on by mistake stays until an\nadmin edits the table. What a `workflow` or a paper did stands, so a way back there is a correction of its own.\n\n#### Stages\n\nName each job\'s work plan by its shape: a status a person sets; a pipeline, where who holds the row and for how long\nmatter; or tasks, where only how many are done counts (`records.task`). A pipeline states each stage once in\n`records.status.stages` \u2014 its `owner` (a member field, a link\'s member field, or `{ "group": <id> }`, a member group) and its target\n`within` days \u2014 and the server holds it: only the owner\'s Acts move the row on, and a row created at a stage past the first is a move into that stage from nothing, which the stage\'s owner, an unowned stage\'s writer or a workspace admin (loading history) may make, on every path a row is written by, and a level an amount skips stands\nnamed with why. A move forward passes each owned stage between that binds the row, each its owner\'s. A stage\'s `when`\nnames the rows it binds, held as an Act\'s `when` holds them on the row\'s own fields (a total a rollup sums or a yes/no a formula yields among them), as the row stood before a write\nand as the write leaves it; with none, it binds every row. Expense claims over a limit wait for the finance group while\nsmaller ones go straight to payment: `"finance_review": { "owner": { "group": <id> }, "when": { "amount": { "gt": 5000000 } } }`.\nA row at a stage leaves it by its owner whatever its `when`; `dropped` names the closed options\nthat leave the work undone (cancelled, rejected), which whoever holds the row moves it to from any stage. A stage\'s owner gates who moves a row out of it; who may move a row into a stage ("only a bookkeeper marks an invoice paid") is a check. Late rows, rows due soon, a warning the line draws and rows waiting on the reader stand first in a\nregister; a register whose job is a strict order, a first-come queue, states `attention: false`.\n\nA status draws one of three ways, by what the author states, never by habit. With nothing `closed` it is a condition a person sets: its select, no steps. With `closed` it is a path: one a person moves by hand (no Act moves it, or its `row` states `status: { edit: true }`) keeps its select alone, and one Acts move draws its stages as a line of steps across the page, each only moving the row on. Where a stage holds something of its own \u2014 fields, blocks, an act that asks or files a paper, a note \u2014 the Record states it as a Section inside `Steps`, and the path draws down the page, each step holding what its stage holds.\n\n#### Stage dates and history\n\nWho changed what and when is the platform\'s audit trail, never a table and never shown by an app. When a stage\'s moment matters\nto the business \u2014 reported, filtered, printed \u2014 it is a date on the row that `records.status.dates` stamps as the row\nenters the option, whoever writes: the one way a status is timed, and the moment a stage\'s `within` runs from (each stage, and\neach open option of a status with stages, naming none gets `<option>_at`). A straight-line process is one select of its steps in order, each dated (a record that states no `Steps` draws it as a line of steps by itself: no date fields or formulas copy it); a move whose\nday may already be past `asks` that date with `starts: "today"`. `records.status.history` names a child the record write path appends one row to per\nstatus move (its link to the row, the new status, the moment and who) for a business that reports on every move: moves\nper person, or time in a stage a row re-enters. An event with facts of its own \u2014 a reason, an amount, a signature \u2014 is\nits own table, made by the act that records it. The rail reads the history. Worked: `examples/approval`, whose history is kept because a group\'s\nstage is signed once per person, read off who moved the row.\n\n#### Readings\n\nA List usually opens with one band of figures or a chart, chosen for what that person watches. Its Readings stand above the rows and its filters and read the rows under the open tab, never narrowed by the controls below them. Lead with the job\'s headline number \u2014\nits exception as a formula\'s yes/no in a Reading\'s `where` (what is short), never a stage the\nstatus chips already count, nor the overdue rows the register\'s summary line counts from `records.due` \u2014 then at most the mix (`by` a field) and the movement (`by` a date), varied by job. A movement over a date is stated, never defaulted; so is a sum, but for the one a status register with a money figure leads with by default: that figure over its open rows, titled by them ("Price (open)"). A register with no such figure and no single select to split by gets no default band.\nA grid (`by` and `across`) reads on a Sheet. A Sheet \u2014 a View of Readings at the App\'s root, beside its Lists or alone \u2014\nanswers one owner\'s question across jobs, each Reading windowed by the reader\'s period (the App\'s `period`), and a\nList on it hands over the rows to act on. Many Readings stand on several Sheets, each a View the reader picks. A\ndashboard varies its charts by the job. A question one app\'s rows answer goes on a Sheet there; one spanning apps gets a small app of its own. A Record\'s Readings read its own child rows. Sums of each row\'s child rows are a Tab\'s `totals`. Worked: `examples/approval`, `examples/dashboard`.\n\n#### Funnel\n\nA Reading with `steps` reads a record\'s child rows as steps, each a number column summed over them \u2014 an order\'s lines\nfrom ordered to shipped. It states how much of the first step\neach later one keeps, the share lost between two neighbours, and the last over the first. State two to six\n`steps` in one unit; where the path turns \u2014 reach, then conversion \u2014 state two Readings one straight after the\nother, so the second\'s bars are read over its own first step, on one grid. A step no row holds a number in reads as not measured: leave it empty, never a zero nobody measured.\n\n#### Priced lines\n\nA quote\'s items, an estimate\'s works, a repair sheet\'s damages are lines priced off a book: a table whose\n`records` names each item, puts the code people type on its line and its price as its `figure`. The line links to\nit, asks the link and its quantities in its List\'s `create`, and copies the price (`default_from`), so the quote\nkeeps what was quoted when the book moves. A line\'s amount is a formula, the record\'s total a rollup over the rows\nthe List shows \u2014 what is not paid for is a second rollup, never a filter on the first, so each group subtotals.\nGroup the lines by the parts the record is quoted in (a container, a room, a leg), a field the line asks. A book worked only while a quote is written is the picker on the quote\'s lines; a book with a keeper, Acts or a history of its own is\nan app (`app_architecture`).\n\n### The record\n\n#### Sections\n\nA record is a head, its parts and at most one Side. From three parts it shows one part at a time; fewer stack. A part is one area of the record\'s data a person comes to for its own job, like the tabs of a settings page; its related lists and field groups sit inside it under their headings. A status\'s stages are not areas: their acts stand at the foot of the rows they move, and a stage that holds something of its own \u2014 fields, blocks, acts, a note \u2014 is a Section inside `Steps`, one `Steps` to a record. State each\npart whole for the work there: a field may stand in any number of parts, and a field an Act requires draws beside it\nunstated. A stage that holds nothing needs no Section: the path draws it by its name. What a person needs in view at every part (who it is for, how to reach\nthem) goes in a Side: it leaves the head and stays on the rows; what only a stage\'s Act writes (an invoice\'s number,\na delivery\'s signature) stands empty before it, so it goes in that stage\'s Section inside `Steps`, never the Side. The status\nstands in the head or the Side, never a Section. `row` changes how the app\'s rows read, never a page nor what the app writes. A List, Reading, Statement or Act stated alike in several\nSections draws once, in the first; a Check stated in a Section guards the whole record.\n\nThe Record\'s Sections, in the order the work reaches them: the fields people write, a Field per paper the record\nkeeps, a child List per child, the Acts at each one\'s foot. A register\'s `columns` are in the order the job reads them, as many as fit a desk; what is read only on the way deeper is the Record\'s, and a figure that is final only from a stage is a Field of that stage\'s Section, never a column read on every row at every stage. A register laid out in time (calendar, lanes, roster) opens the\ndefault record: every field a person writes. Behaviour belongs in an Act.\n\nA Section of more than about six fields reads as Fieldsets of related facts: a patient\'s record holds "Contact" and\n"Insurance" rather than one run of nine, each Fieldset\'s `label` a few words. A gallery or prose Field stands beside the Fieldsets (`reference/fieldset-node`). Fields in a part come first, a Fieldset where they need a heading. Only where the arrangement itself is the need does the Fieldset state `Line`s \u2014 two weights and their difference on one line \u2014 and `heads` where several Lines repeat the same columns, a fee\'s amount, its payment and its invoice button per row (`reference/line-node`). A figure only that screen shows is a `Value`; one a list, a report or an export reads is a formula field of the table. Fields stand two\nto a line in the order stated, and files, prose and a link to several rows take the whole line: stated after a lone\nshort field, one leaves the half beside that field empty.\n\n#### Children\n\nRows that each belong to one row of another table (a one-row link to it) are drawn under that row: a List on\nits Record, `layout: "timeline"` where they are a log, `layout: {"agenda": \u2026}` where they are planned on a day and within it, or\n`layout: {"gantt": \u2026}` where they are bars on a schedule. Which children a record lists is the author\'s \u2014 one of them at least. A List\nlisting only some of them narrows by its `where`: a select (one leg\'s fees), or a yes/no \u2014 a formula\'s for what is\nstill owed \u2014 on a List that adds no rows. A child List stating no `create` asks the table\'s required fields, natural key and\ntitle; where defaults fill them all, it adds none. Rows on\nfile before the row they come to belong to \u2014 a job\'s cost lines before the supplier bill over them \u2014 are picked into\nit: a List with `pick`, often with no `create` and no `remove`.\n\n### Papers\n\n#### Expect\n\nA List with `expect` naming the child\'s title \u2014 a single select of kinds, or a one-row link to a\ncatalog: one line per kind, the ones not yet filled standing empty, filled in place. `of` narrows the kinds\nto the record\'s own multi-select of those it needs. The papers a case gathers, the fees a record knows it\nowes. Worked: `examples/case`.\n\n`only` lists the kinds a List holds a line for, so each kind stands in the Section whose job it is, once. The Act making a paper (`paper: "<child>.<kind>"`), stated in the Record beside its Sections and moving the record as any Act does, is its line\'s button while it applies, the upload in the \u22EF.\n\n#### Templates\n\nA paper the business makes is an Act\'s `template`, kept in the record\'s files field `into` \u2014 or several at\nonce, `templates`: listed where the Act stands, each made one as its file, each not yet made a placeholder,\nthe reader ticking which to make. Worked: `examples/case`.\n\n#### Intake\n\nA paper the business is brought and reads is an Act\'s `intake`: the press takes the papers, an agent reads\nthem, and each is filed as the line of its kind in the child the record `expect`s, while `fills` writes what\nthey state into the record\'s fields \u2014 a single link as a row the agent finds among those the app reads \u2014 shown before it is saved. Stated with `on: "view"` at the register\'s title, the papers make a NEW record instead: `fills` names what it requires, `<link>.<field>` fills the row a required link names (found on its entity\'s `natural_key`, else added), and the register opens the record made. Worked: `examples/case`.\n\nAn agent Act \u2014 an `intake`, a `record`\'s `fills` \u2014 spends a run on every press, so it is stated only where the\nowner asked for an agent to do that job; otherwise a paper brought is its `expect` line, and a person types what it states.\n\n#### Under\n\nA List with `under`: the documents that cover lines (an invoice over its fee lines) stand as headings\nover the lines they cover, and a line no document covers offers to make one. A document entered as it arrives over lines\nalready on file (a supplier bill) picks them with `pick` instead; choose one per document.\n\n### Calls\n\n#### Record act\n\nAn Act\'s `record`: the press records a call, visit or meeting \u2014 audio, transcript, screen where captured \u2014 and\nfiles it as a new row of the record\'s `timeline` child (`into`), stamped `at` and `by`; `fills` lets an agent fill\nthat row\'s fields from the transcript, where the owner asked. Worked: `examples/calls`.\n\n';
|
|
1875
1875
|
|
|
1876
1876
|
// docs/app_architecture.md
|
|
1877
1877
|
var app_architecture_default = '# App architecture \u2014 which apps, and who gets each\n\n**Which apps.** One app per main entity, a thing the owner\'s words give its own list. A row that makes sense only under one parent (an employee\'s contracts, an order\'s lines) is a child List on the parent\'s page, never another app or a Tab. A second root List is rare: one job working two unrelated entities side by side. A related row\'s value on the list is a lookup column; work over many rows (a month\'s payroll) an Act on the list\'s rows. A person\'s part of the work doesn\'t make an app; a different job may.\n\nOne bakery\'s wholesale arm, five people, seven apps:\n\n| App (its list) | Opened by | On a row\'s page |\n|---|---|---|\n| Customers | Sales rep, owner | Their prices, orders and unpaid invoices |\n| Products | Sales rep, head baker | Price breaks, recipe, stock on hand |\n| Orders | Sales rep, head baker, owner | Lines, the quote paper (an Act), the bake orders it starts |\n| Bake orders | Head baker | Steps, the Acts that move a stage, the tasting |\n| Suppliers | Buyer | Their price list and purchase orders |\n| Purchase orders | Buyer, storekeeper | Lines, goods received |\n| Materials | Storekeeper, buyer | Movements in and out, the Receive and Issue Acts |\n\nAn order\'s lines, a bake order\'s steps and a customer\'s prices make sense only under their parent: each is a child\nList on that row\'s page, never an app or a Tab. An order stands in the Orders app and on its customer\'s page: one\nrecord, one page. The owner reads the figures each register leads with. Each app\'s `name` is its list and its `description` says what is worked there:\n\n```json\n{\n "type": "App",\n "key": "orders",\n "name": "Orders",\n "description": "Takes a customer\'s order from quote to dispatch.",\n "children": [{ "type": "List", "entity": "order" }]\n}\n```\n\nHow each tree is composed is `design`.\n\n## Who gets each\n\nWho does which job is asked in `build`\'s one message before the first write. An app stays with admins until the answer comes, and sharing waits on it. `set_access` then gives each app to everyone who works its rows (ids from `get_workspace` kind `member`, which lists the people in this workspace); none loses access. Someone who works its rows and is not in the workspace is added first by an admin of the workspace (`set_members`, `role: "member"`), since a share reaches only people in the workspace. They need no\ntable access: an app runs as its owner. With no `rows` on the App they read every row; where people differ, `rows`\nstates one rule per table (`reference/read-scope`):\n\n| The business says | The app states |\n|---|---|\n| Everyone sees every order | nothing |\n| Each rep sees only their own deals | `"rows": { "deal": { "any": [{ "field": "rep", "is": "self" }] } }` |\n| Reps see their own deals; managers see all | `"rows": { "deal": { "any": [{ "field": "rep", "is": "self" }, { "member_of": "<managers group id>" }] } }` |\n| Each branch manager sees their branch\'s orders | `"rows": { "order": { "any": [{ "through": ["branch"], "field": "manager", "is": "self" }] } }` |\n| Each employee sees only their own payslips; HR sees all | two apps: one stating `"payslip": { "any": [{ "field": "employee", "is": "self" }] }`, one for HR stating none |\n| Team leads see people, not salaries | an app that draws no salary field |\n\nA public link or an API key reaches every alias an app declares, so what outsiders may call is a second app over the\nsame tables, and the team\'s desk stays private (`app_bindings/api-apps`).\n';
|
|
@@ -1883,13 +1883,13 @@ var permissions_default = "# Permissions\n\nWho can reach what, what runs under
|
|
|
1883
1883
|
var working_in_a_workspace_default = "# Working in a workspace \u2014 the right means for each job\n\nOnce tables and apps exist, an agent does the team's work through them. The means depends on what the work is.\n\n| The work | The means | Why |\n|---|---|---|\n| A business operation: move an order on, issue a paper, notify someone | `run_app_workflow` on the app's act, `act_<key>` | The outcome equals a person's press: status, stamps, documents, notifications. `update_records` on an act's field skips all of them. |\n| Data entry, a correction, loading the owner's lists | `create_records`, `update_records` | The table's rules hold for every writer. |\n| A rule or policy the business wrote | `get_workspace` with `search`, then `read_knowledge` | The business's own words, not a guess. |\n| A file someone hands over | `upload_file` to keep it; `download_file`, or `lotics file download <file_id>` on the CLI, to take one out | The upload files it in the workspace; the download hands you the file to open with your own tools. When your host passes no bytes, `upload_file` with `person: true` gives the person a link to drop it on. |\n| A paper an app makes | the act that makes it, which files it on the record | `generate_document` makes an unattached file, for a paper no app makes. |\n| A connected service (KiotViet, MISA, a carrier) | a workflow step, reached through a Workflow node | No tool calls a service directly (`workflows/reaching-a-connected-service`). |\n| A figure or list the business defines, or an operation it repeats | the app's declared Query or Workflow node: `run_app_query`, `run_app_workflow` | The node is the business's own definition, found by `get_workspace` with `search` and read in `get_app`. |\n| A count or sum no app answers | `query_records` with `aggregate` (grouped by `group_by`), or its rows; `record_ids` reads those records by id | |\n\nFind the means in this order: `get_workspace` maps the workspace; `search` it by what is asked (\"overdue\"), which matches an app's declared Query and Workflow keys and descriptions and names the matching keys under the app; `get_app` lists that app's queries and workflows with their inputs. Run the declared node. Only a question no node answers goes to `query_records`.\n\n## Workspace settings and standing instructions\n\n`get_workspace` shows the workspace's settings (name, timezone, default currency) and, with kind `instruction`, its standing instructions. `set_workspace` changes them in one all-or-nothing patch: a setting it leaves out is unchanged, and `instructions` is a map keyed by instruction name where an entry creates or merges and `null` removes. A workspace-wide instruction arrives with the connection, in the instructions a host reads when an agent connects; the answer of `set_workspace` names any that no longer fit that block. An admin of the workspace writes the settings, the instructions and the workspace's and its apps' credit limits; the organization's name and language and a member's credit limit are an organization owner's, and a call stating one without being one is refused naming which.\n\n## People\n\n`get_workspace` with kind `member` lists the name and id of each person in this workspace; an organization owner passes `all: true` for everyone in the organization. An admin of the workspace also sees each one's email, organization `role`, `workspace_role` (`admin`, `member`, or null for a person outside it), `managed` and `sign_in_name`, and, on kind `app`, `knowledge` or `template`, `not_listed`: how many more they can reach, which `all: true` lists. Listed docs and templates carry `access`. An admin also reads the credit limits there. With kind `group`, everyone lists the groups of this workspace.\n\n`set_members` is an admin's of this workspace or an organization owner's: `members` is a map keyed by an email address, a member id or, for a member who signs in by a name, that name, and `groups` a map keyed by a group id, or by a group's name, which sets the group of that name or creates it (refused where several groups share it: key that entry by id). In `members`, `role` is the person's role in THIS workspace, `member` or `admin`; `role: null` takes them out of it, ending their shares here and passing what they own here to the caller. An email no member holds invites that person into this workspace with `role` (`member` when omitted) and `name`, and the invitation email goes out; an address invited to another workspace gets a place here on that invitation. `role: null` on an address with an invitation pending here takes the invitation out of this workspace, canceling it when no other workspace holds it. A workspace admin who is not an organization owner never changes an organization owner, and adds only someone already in a workspace. Each result says which changed: `invited`, `invitation_canceled`, `added_to_workspace`, `workspace_role_changed`, `removed_from_workspace`. Renaming or removing a person, restoring a removed one, co-ownership, and a member who signs in by a name are a person's in Settings \u2192 Members: no tool takes them. The primary owner is never given a workspace role. A group belongs to this workspace and holds only its people. In `groups`, an entry sets `name`, `description` and the roster with `member_ids`, or with `add_member_ids` and `remove_member_ids` that leave the rest in place; a roster entry may be a key of `members`, so a person invited in the same call can join; `null` deletes the group. The whole input is checked before anything is written or sent; members are applied before groups, in the order given. A workspace admin's tool list carries `set_workspace` and `set_members`; a member's carries neither.\n\n`set_access` gives members or groups in the workspace, or everyone in it (`organization`), a role on resources. A share with someone outside the workspace, or with a group of another workspace, is refused as outside the workspace; an admin of the workspace adds them first with `set_members` (`role: \"member\"`), then the share is made again. Role `owner`, on one member, hands every resource listed to that member, who is in the resource's workspace and whom only the resource's owner or an admin may name; a call cannot share an app and hand it over together, an app handed to or from a member loses its sharing, and an automation is turned off until its new owner turns it on. Handovers are applied one resource at a time, and a failure part-way names what was already applied. `set_workspace` takes `credit_limits` (`workspace`, `apps` by app id, `members` by member id; a number is the daily ceiling in credits, `null` removes it and asks for approval).\n\n## Comments\n\nA record read carries `comment_count` (a workflow body gets it when it reads it). `query_records` takes `comments: true` to return the thread (`limit` defaults to 20, 20 at most). Comments are written by people, on the record in Lotics or through the product's chat.\n\n## Deleting and restoring\n\nA keyed entry is removed by `null`: a field, check, view, option, instruction, query alias, a member or a group. A resource addressed by its id is deleted with `delete: true` and brought back with `restore: true`, beside its id: a table in a `set_tables` item (`{ table_id, delete: true }`; `cascade` deletes the links that point at the deleted tables and is refused unless the call deletes; `force` goes with a patch that loses stored values and is refused on a call that only deletes or restores), a knowledge doc (`set_knowledge` with `knowledge_doc_id`), a template (`set_template` with `template_id`), an app (`set_app` with `app_id`) and a workflow (`set_workflow` with `workflow_id`; a deletion only). Records are deleted by `delete_records` and removed for good, once in the trash, by `delete_records` with `permanent: true` and `record_ids` or `filters` (an organization admin's own credential alone, never inside a workflow; the records and their comments go, their audit history stays), and brought back by `update_records` with `restore: true` and `record_ids` or `filters`: the rows their delete took come back with them, all or none, and a row needing its link stays deleted while the row it names does. `delete` takes no other key. A call that deletes asks for approval; one that does not never does.\n\n## Locking and changing a locked record\n\n`update_records` with `locked: true` locks the targets (write access) and `locked: false` unlocks them (the table's manager). Beside field edits, a record that is locked before and after the call is refused into `blocked`; an unlock lands before the edit and a lock after it. `request_change: { reason }` files one change request per blocked record instead, carrying the values the call resolves, and lists them in `requested` as `{ record_id, request_id }`; the unlocked targets of the same call are written, and the call and its requests are one transaction, so a request that cannot be filed leaves them unwritten too. A table whose `locked_change` is `tell` writes the locked record at once instead, tells the people who manage it, and lists the record in `applied`.\n\n## Undoing a write\n\nA write is put back by writing the value `query_audit_logs` shows before the change: `update_records` for a field, `update_records` with `restore: true` for a deleted record, with the rows its delete took, or an app's `restore_<entity>` where the row went by that app's Delete, `delete_records` for a record a run created.\n\n## Files\n\n`download_file` returns a `download_url` and, over MCP, the file itself as an embedded resource up to 12 MB (`bytes_omitted` says why it is absent). On the CLI, fetch the `download_url` or run `lotics file download <file_id>`. Open the file with your own tools. In the in-product chat the `download_url` is the stable address a signed-in member opens, so it is for the person, not a link a tool fetches.\n\n`upload_file` names one source:\n\n- `url`: a public http(s) address the server fetches.\n- `file`: the `{download_url, file_id}` reference a host hands over for a member's attachment (a ChatGPT file parameter arrives hydrated into this shape). Never construct one.\n- `files`: bytes you hold locally. Each entry gets an `upload_url`, valid for 5 minutes, on the same host as your other calls; PUT the bytes to it and the response is the `file_id`. Where your sandbox allows no outbound request to that host (in Claude, a Team or Enterprise owner lists it under Admin settings \u2192 Capabilities), the PUT fails before it leaves: give the person the file with `person: true` instead.\n- `person: true`: returns a `drop_url`, valid for an hour, to give the person, and a `ticket_id` per file; once they say they dropped the files, call again with each `ticket_id` for its `file_id`.\n\n## Doing an operation\n\n`get_app` lists the app's acts as `act_<key>` (or the `workflow` an Act names) with what each takes. `run_app_workflow` with `dry_run: true` writes nothing\nand answers what the run would do; the same call without it runs. An act refuses a row its conditions do not hold for,\nand says why (`agent_surface/a-refusal`).\n\n## Writing records\n\n`create_records` takes 50 records a call, 20 or more of one shape in columnar form (`field_keys` once, then `rows`);\n`update_records` changes one or many. Both name fields and select options by alias, and `field_values` gives each\ntype's value. Every write meets the table's rules (`reference/write-rules`): every broken rule is listed at once, and a\nlocked record answers under `blocked`. The owner's own lists (a menu with prices, customers, open orders) are rows of their\ntables, loaded this way after `set_tables`.\n\n## A business's tax ID\n\nNo tool resolves a business name to its tax ID. The customer's own papers carry the ID they are invoiced under: a PO's\ninvoicing footer, a contract, a past invoice. A web search limited to registry listings (`masothue.com`,\n`infodoanhnghiep.com`) shows each match's tax ID in its result, though those sites refuse a direct fetch; many companies\nshare a name, and the registered address is what tells them apart. For a\nVietnamese tax ID (a branch's with a `-00N` suffix), `https://api.vietqr.io/v2/business/{tax_id}` answers the\nregistered name, address and status (`NNT \u0111ang ho\u1EA1t \u0111\u1ED9ng` when active); it is rate-limited, answering 429 to a burst. A\nregistered address can differ from the one a PO prints. A company's code for paying a foreign contractor's tax on its\nbehalf shares its name and address; its registered name ends in `(NTNN)`, and it is not the code the company is invoiced\nunder.\n\n## Answering a question\n\n1. `get_app`: a Reading's query (its `key`) is the business's own figure for it. `run_app_query` with `alias` and\n `params` returns it; `filters`, `fields`, `sort` and `count` narrow the result.\n2. A period's total is one call per period, each with `from` and `to` or a date filter. `aggregate` groups a result by\n a column (`by`), a number's bands (`bands`) or a date column's day (`day`), and sums one (`sum`).\n3. A question no app answers is `query_records` over one table: its rows, or with `aggregate` counts and sums grouped by a\n field; `filters` is the grammar of both.\n\nA row `query_records` or an app's query returns carries its issues when it holds any: what the\nworkspace marks as needing a person's action, in its priority order, whatever columns the read asked for. `get_workspace`\nand `get_app` state how many rows hold each.\n\n## A worked day\n\nA customer asks for the status of order 1042, then the order is shipped:\n\n```\nget_workspace kind \"app\" \u2192 app_id of the sales desk\nget_app app_id \u2192 aliases: order_list, act_ship, \u2026\nrun_app_query app_id, alias \"order_list\", params {\"search\": \"1042\"}\nrun_app_workflow app_id, alias \"act_ship\", inputs {\"record_id\": \"rec_\u2026\"}, dry_run true\nrun_app_workflow the same call without dry_run\nquery_records table_id, aggregate {group_by \"stage\", count} \u2192 how many orders stand at each stage now\n```\n";
|
|
1884
1884
|
|
|
1885
1885
|
// src/reference.md
|
|
1886
|
-
var reference_default = '# Tables and apps\n\nThe tables of a workspace and the apps over them, each a JSON document. A table is a document, an item of\nthe tool `set_tables`: its fields, options, how a row is recognised, and the rules its writes\nfollow. An app is a tree of components, the `body` of the tool `set_app`: its Views \u2014 Lists of rows and Sheets of\nreadings \u2014 and the page each table\'s rows open. Each section is its own page, `reference/<section>`.\nWhich treatment each job\'s screen needs: the `design` reference. Each treatment worked through in an\napp: the `examples` reference.\n\n**What the documents compose with**\n\n- **Tables and fields** (`reference/tables`, `reference/read-scope`, `reference/field`) \u2014 a table\'s columns, options and links. A table document sits\n in the `tables` list of a `set_tables` call; a field sits under its alias in the table\'s `fields`.\n- **Records** (`reference/records`, then `reference/status`) \u2014 how a row of each table is RECOGNISED: its title, the line\n under it, its picture, its status, the one number it stands for. Stated once per table\n and read by every surface that draws one of its rows.\n- **Write rules** (`reference/write-rules`) \u2014 what a write finds, bounds and picks among.\n- **Apps** (`reference/app-tree`, then a page each) \u2014 the Lists and Sheets at the app\'s root, each a View of its own, and the\n page each table\'s rows open: which fields go where, the acts, and the checks that guard them.\n How each thing LOOKS is the runtime\'s, one treatment per concept; no prop here changes it.\n A screen the job needs and no component states is told to the person \u2014 the job, what the app\n drew, the word wanted \u2014 never props bent to approximate it.\n\n**The working order**\n\n1. The tables and fields the jobs touch, and a `records` entry for every table an\n app lists, opens or picks. Which apps a business needs is `app_architecture`.\n2. One `set_tables` call with the tables: a link names the table it points at by the `ref` of another\n item of the call, and the answer carries every table id and the aliases of the fields it added. A\n call carries at most 50 tables, 200 first rows a table, and 2000 rows and 2000 documents in all; more\n tables go in a further call, which names the earlier tables by alias. A call is checked whole and writes\n nothing when refused, listing everything wrong; `dry_run` is for reading the grants a write would make or\n deciding `force`.\n3. One `set_app` call per app. The tree names its tables and document templates by alias wherever it points at one;\n the App node\'s `tables` and `templates` maps are filled by `set_app`, never written.\n `set_app` with the tree as `body` creates the app, named by its `name`; a refused tree writes nothing and is listed whole, and `dry_run` is for reading the permissions the write\n would grant and remove (on the CLI, `lotics app apply <file>`, with `--check` for `dry_run`).\n4. Change an app afterwards one node at a time: `get_app` prints the `tree:`, each node\'s address under `node addresses:`\n and the `version` line, which is the `base_version_id` to send (the tree and addresses go to the app\'s author alone);\n `set_app` with `app_id`, `base_version_id` and `nodes`, a map from a node\'s address to a\n patch, changes it (`reference/changing-an-app`), and its answer states the permissions the change grants and removes. A table\n is changed by `set_tables` with its `table_id`, a merge patch over the document `get_table` answers. To go back,\n send the tree you saved before the change as `body` with `app_id`: it replaces `children` but keeps every App prop it\n omits (`words`, `scope`, `period`, `icon`), so null those. (On the CLI, `lotics app pull <app_id>` writes the tree as JSON and `lotics app apply\n <file>` sends an edited file, refused when the app has moved past the version the file was pulled at.) An app\n saved before apps were trees has no tree: `get_app` says so beside what it lets a person write, and `set_app` with\n `app_id` changes it by its whole tree as `body`, which replaces it, or by its name, description, icon and color alone.\n\n## The rules\n\n- **A `set_tables` call is all or nothing.** Every item is checked before any is written; an item\n without `table_id` makes a table, one with it patches that table.\n- **An app\'s labels decide its language.** A body names no locale \u2014 the words an\n app draws itself (its buttons, empty states, refusals) are in the language its\n own labels are written in, so a Vietnamese desk beside English ones answers in\n Vietnamese. The generated screens read the kit\'s\n pack, and a generated WRITE cannot: its refusals run on the server, so they are\n worded in that same language. Mix the two within one app and it answers in two. The app\'s own `words`\n (its words for a table, a field or an option) count as its labels: Vietnamese words over an English table\n make the app answer in Vietnamese.\n- **`set_tables` and `set_app` check all of it before anything is written**, and\n report every problem in one run rather than the first. The tables half of this\n page ends its keys with the rules the check enforces there, and `reference/app-rules` and the pages after it hold the app\'s, one sentence each\n under an id; a finding names its rule\'s id (`[list.filter]`), and\n `reference/<rule id>` is that one rule\'s page.\n\n## Top level\n\nEvery table of keys on this page is generated from the grammar a table document and an app tree are written in, so it is the whole of what a key may hold.\n\n<!-- generated:start top-level -->\n\n#### set_tables call\n\n| Key | Type | Meaning |\n|---|---|---|\n| `tables` | list of [Table item](#table-item), required | One or more, all or nothing; each item is a table document with these keys added. It creates a table (a `label` and `fields` at least) or, with `table_id`, patches one: the document it states merges into the table\'s own |\n| `rows` | map of alias \u2192 list of [Row](#row) | First records of the tables the call creates, keyed by each one\'s `ref` |\n| `force` | boolean | Consent to losing what rows hold: a field deleted, an option removed |\n| `dry_run` | boolean | Answer what the call would change, writing nothing: for reading the grants a write would make or deciding `force`. A refused call writes nothing too and lists every reason, so a dry run checks no more than the call does |\n\n#### Table item\n\n| Key | Type | Meaning |\n|---|---|---|\n| `ref` | alias | A created table\'s handle in this call: other items link to it, and `rows` are keyed by it |\n| `table_id` | text | The table to patch; absent, the item creates one. A patch states only what changes: `null` removes a key, a list replaces whole |\n\n<!-- generated:end top-level -->\n\n**A `set_tables` item is a table document** (`reference/tables`) with `ref` and `table_id` added, and the call\ntakes no other key. **A `set_app` body is an app tree** (`reference/app-tree`), whose root is an App node: its `tables` and\n`templates` each map a local alias the tree names to the id of the table or document template it means, from the\n`set_tables` answer or `get_table`. The tree is the only home of the app\'s `name`, `description`, `icon` and `color`;\n`set_app` takes it whole to create, or as a merge patch over the App node with `app_id`, or `nodes` with `app_id` to change one, and with `base_version_id` (the\nversion you read) it refuses a write over a newer one. Nothing is built code. An unknown key is an error, never ignored.\n\nA smallest call, two tables of plain fields, a select and a two-way link \u2014 nothing else is needed to write it:\n\n```json\n{\n "tables": [\n {\n "ref": "customer",\n "label": "Customers",\n "singular": "Customer",\n "fields": {\n "name": {"type": "text", "label": "Name", "required": true},\n "tier": {"type": "select", "label": "Tier", "options": [{"alias": "gold", "label": "Gold", "color": "yellow"}, {"alias": "standard", "label": "Standard", "color": "gray"}]},\n "orders": {"type": "link", "label": "Orders", "table": "order", "multi": true, "pair": "customer"}\n }\n },\n {\n "ref": "order",\n "label": "Orders",\n "singular": "Order",\n "fields": {\n "code": {"type": "text", "label": "Code", "required": true},\n "customer": {"type": "link", "label": "Customer", "table": "customer", "multi": false, "pair": "orders"},\n "amount": {"type": "number", "label": "Amount"}\n }\n }\n ]\n}\n```\n\n### Aliases\n\nEvery `alias` is a lowercase slug \u2014 a letter, then letters, digits and\nunderscores (`unit_price`, `so_1001`). Aliases are how a document and an app tree\nname a field, an option or a table; they are never shown to anyone. `label` is\nwhat a person sees.\n\nLabels must be unique within their namespace \u2014 two fields on one table, two options\non one field cannot share a label.\n\n## Tables\n\n<!-- generated:start table -->\n\n#### Table document\n\n| Key | Type | Meaning |\n|---|---|---|\n| `label` | text, required | The table\'s name in the workspace |\n| `singular` | text | One row of this table, in the business\'s own words \u2014 what a create\'s button and panel name |\n| `description` | text | The table\'s description, written onto the table in the workspace, where a caller of an app\'s queries and workflows reads it beside them |\n| `fields` | map of alias \u2192 [Field](#field), required | The table\'s columns, each under its alias, which is its key here and so is never stated inside it |\n| `read_scope` | [Read scope rule](#read-scope-rule) | Which rows a member reads. Absent, every member with access to the table reads every row. |\n| `unique` | list (at least one) of list of alias (at least one) | Sets of fields whose values no two live rows share \u2014 each a list of field aliases (text, number, date, a single select, a single member, or a link holding one row \u2014 `multi: false`); a single text field states `unique: true` on itself instead of a one-field set. A create or update landing a second row with the same values is refused. |\n| `locked_change` | `"tell"` | `tell`: a change stated with a reason to a locked row is written at once and the people who manage the table are told. Absent, it waits for one of them to approve it. |\n| `title` | alias | The alias of the field that names a row wherever a link or a record shows one; absent, the first text field |\n| `colors` | any value | Row colors: a list of { filters, color }, the filter reading fields of this table by alias and a select\'s options by alias; one condition on its own is a group of one |\n| `records` | any value | How a row is recognised: the keys of the Record, Status and Cadence tables below but `title`, which sits above; a table they name is an id or a `ref`. A status `history` that names a `ref` no item of the call declares is made by the call as a table, `dates` add each date field they name, and a status with stages each stage and each open option they name none for its `<option>_at`, unless the document declares it; each is listed in the result\'s notes |\n| `natural_key` | list of alias (at least one) | The field aliases a row of this table is RECOGNISED by: an app\'s add and find-or-create reuse the row they find by these values, minting one only where nothing matches. A record tool or the API creates the row it is handed. |\n| `no_overlap` | [No overlap](#no-overlap) \\| list of [No overlap](#no-overlap) (at least 2) | No two rows hold overlapping spans (one rule, or a list of rules a row must each meet) \u2014 a create or update that would is refused, and so is a change to the dates or states of the row a span is read through that would make two rows overlap |\n| `checks` | map of alias \u2192 table check (`workflows/table-checks`) | The conditions a write of the table\'s rows may not meet, each under its alias: a merge patch edits one, and `null` removes it. Expressions name fields by alias |\n\n<!-- generated:end table -->\n\n<!-- generated:start rules-entity -->\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `entity.singular` | A table a List\'s `create` is mounted over \u2014 a root List\'s or a child List\'s that adds rows \u2014 states its `singular`: one row of it, in the business\'s words. |\n| `entity.link-format` | A text field of `format: "link"` holds web addresses; one whose rows hold a phone or a mail address states no format. |\n| `entity.read-scope` | A `read_scope` clause names a group (`member_of`) or a field of its table reached through one-row links: `"self"` a member field, options a single select declares; an `any` or an `all` groups clauses, and groups nest. |\n| `entity.unique` | A `unique` set names fields of its table once each, each holding one value to compare \u2014 text, a number, a date, a single select, a one-row link \u2014 and is stated once; a lone text field is `unique: true` on it. |\n\n<!-- generated:end rules-entity -->\n\n**`unique` is a set of values no two live rows share.** Each entry names fields\nof this table holding ONE value \u2014 text, number, date, a single select, a link\nwith `multi: false` \u2014 and a create or update landing a second row with the\nsame values is refused. A set of one text field is that field\'s own `unique:\ntrue`, so it is refused here. A create carries each set in the names its panel\nsends, so the panel can name the duplicate before the write does.\n\n**`singular` is what a create says** \u2014 `New Order`, `Add Claim line`, `H\u1ED3 s\u01A1\nm\u1EDBi` \u2014 while `label` names the table, so without it the button reads `New\nOrders`. Nothing derives it: English plurals are irregular, and no language is\nexempt. In a language without plural forms it is usually the label itself,\nless any word for the collection. A List that leaves `create` to its default adds nothing over a table that states\nnone (nor does the app\'s `words` state one); a `create` list stated over such a table is refused (`entity.singular`).\n\n**An app that only reads a table\'s rows draws them with `edit: false`** and states `create: false` and `remove: false` \u2014 a log of what the system sent, a copy of\nwhat another system holds. The app keeps the section and opens each row at rest, with no Add and no Delete; a party\nof it is picked, never found or minted; and the app writes no create, update or remove for it. It shapes that app, not who may write: a direct write \u2014 the records\nAPI, the chat agent, an import \u2014 follows the table\'s access, as on any table, and another app over the same rows\nstates its own tree.\n\n**`read_scope`** \u2014 which rows a member reads \u2014 is its own page, `reference/read-scope`.\n\n## Read scope\n\n<!-- generated:start read-scope -->\n\n#### Read scope rule\n\n| Key | Type | Meaning |\n|---|---|---|\n| `any` | list of ([Read scope by role](#read-scope-by-role) \\| [Read scope by member](#read-scope-by-member) \\| [Read scope by option](#read-scope-by-option) \\| [Read scope rule](#read-scope-rule)) (at least one) | A row is readable when ANY of these holds |\n| `all` | list of ([Read scope by role](#read-scope-by-role) \\| [Read scope by member](#read-scope-by-member) \\| [Read scope by option](#read-scope-by-option) \\| [Read scope rule](#read-scope-rule)) (at least one) | A row is readable when ALL of these hold |\n\n#### Read scope by role\n\n| Key | Type | Meaning |\n|---|---|---|\n| `member_of` | text, required | The id of a group (from Settings, or chat): whoever is in it reads the row |\n\n#### Read scope by member\n\n| Key | Type | Meaning |\n|---|---|---|\n| `through` | list of alias (1\u20133) | link aliases from this entity outward, each holding one row (`multi: false`) \u2014 the clause\'s field is on the entity the last hop lands on |\n| `field` | alias, required | A member field alias on this entity, or on the entity `through` lands on |\n| `is` | `"self"`, required | The members this column names on a row read that row |\n\n#### Read scope by option\n\n| Key | Type | Meaning |\n|---|---|---|\n| `through` | list of alias (1\u20133) | link aliases from this entity outward, each holding one row (`multi: false`) \u2014 the clause\'s field is on the entity the last hop lands on |\n| `field` | alias, required | A single-select field alias on this entity, or on the entity `through` lands on |\n| `is` | list of alias (at least one), required | Its option aliases whose rows are readable \u2014 naming none would hide every row |\n\n<!-- generated:end read-scope -->\n\n**A row rule is enforced by the platform.** A table\'s `read_scope` is resolved into its own row filters, so\nthe table tools, the data view and the API answer the same rows, and it caps what an app\'s owner can hand out: an\napp never reads beyond its owner\'s reach. An app states its own rule of each table it reads in `rows` on the App\nnode (`reference/app-tree`), in the grammar above. A `"self"` clause reads a column of one member or several, and every group\nand option a clause names must exist.\n\n**A rule holds through a link.** A filter through a link and a List\'s linked column read the linked row under the\nreader\'s own rule of it, and a link to a row the writer cannot read is refused. A lookup, rollup or copy is stored, so\nit reads one value for everyone who reads its table: one over a table with a rule takes `manage` on that table, and\n`get_table` of that table lists them as `crossings`.\n\n**An app runs under its owner\'s authority**, so the people it is shared with need the app and no access to its\ntables. Where they differ in what they may read, `rows` states it: one rule per table, evaluated against the caller,\nnarrowing the app\'s screens, its queries (the AI and MCP path), its writes and acts, and its workflow bodies and app\nagents, every row they read or write. A table `rows` states no rule of is read whole by everyone the app is shared\nwith, so a desk whose audience its sharing already decides states nothing. The rule holds for admins too: an app with people who see every row names them, as a group.\n\n**A row rule is never inherited.** A child read under a ruled record states\nits own in `rows`: the record\'s `member_of` clauses as they are, and its column clauses\n`through` the one-row link the child hangs by \u2014 over one hop or several, each a\nlink with `"multi": false`, since over several rows the rule would admit a\nreader any one of them admits while the editor\'s guard reads the first. Only the\nstatus history takes its record\'s rule.\n\n## Field\n\nEvery field carries the keys below, and its `type`\'s section adds the rest; a\ntype whose section names no `default` takes none. `label` may not contain `{` or\n`}` (formulas reference fields by label at the platform level). Every row in `rows` states each\n`required` field it carries (neither a default nor a `default_from` copy is applied to them), and a required\nLINK is written with its row: the table it names is created first, and tables\nwhose required links name each other are refused, since none of their rows could\never be created.\n\n**A table states who keys nothing.** Whether a person may change a field in an app is that app\'s statement\n(what its tree draws, and `edit: false`, `reference/app-tree`): a post\'s id a publishing workflow brings back, a count a sync fills, a status an act moves\nare left out of the apps that do not save them, and written by a workflow, the records API, the chat agent and an\nimport as the table\'s access allows. A formula, a rollup, a lookup and an autonumber are no one\'s to key already.\n\n<!-- generated:start field -->\n\n#### Field\n\n| Key | Type | Meaning |\n|---|---|---|\n| `type` | `"text"` \\| `"number"` \\| `"date"` \\| `"boolean"` \\| `"select"` \\| `"member"` \\| `"link"` \\| `"files"` \\| `"formula"` \\| `"rollup"` \\| `"lookup"` \\| `"autonumber"`, required | What the field holds \u2014 each type takes the further keys its own section lists |\n| `label` | text, required | The field\'s name in the workspace |\n| `description` | text | The field\'s description, written onto the field in the workspace |\n| `required` | boolean | Refuse a record whose cell for this field is empty. Every write path \u2014 create, update, an agent\'s tool call, a workflow\'s set \u2014 refuses the row by field name. A stored field is flagged only once every row holds a value. |\n\n<!-- generated:end field -->\n\n### `text`\n\n<!-- generated:start field-text -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `default` | text | Value pre-filled into a new record when none is supplied for this field; the write that makes the field required also fills it into every row holding it empty. |\n| `unique` | boolean | Unique values required |\n| `format` | `"text"` \\| `"link"` \\| `"markdown"` \\| `"time"` | How the words are drawn \u2014 plain, as a link that opens, or as markdown |\n| `default_from` | text | Copied when a record is made off the row a one-row link of this entity names \u2014 `<link alias>.<field alias>` \u2014 or, reading on through one-row links, off the row the last of them names \u2014 `<link alias>.<link alias>.<field alias>` \u2014 and never re-read, so the source changing later leaves the row alone. A value the add states wins; a select copies each option as this field\'s option of the same alias. |\n| `suggest` | [Suggest](#suggest) | A text field whose control offers, as the reader types, the distinct values a text field of a catalog table holds (a damage position\'s code among the codes on file); any text is still written |\n| `min` | number \\| text | Refuse a create or update whose value is below this: a constant for a number, or a field \u2014 `<field alias>` of the same row, or `<link alias>.<field alias>` of the one row a link names \u2014 of the same type (a return date after the departure, a line\'s day inside its trip). On a figure whose unit or currency is per row (its notation\'s `per_row`) a constant bound is only 0; bound it by a field of the row |\n| `max` | number \\| text | Refuse a create or update whose value is above this: a constant for a number, or a field of the same row or of the one row a link names |\n\n<!-- generated:end field-text -->\n\n### `number`\n\n<!-- generated:start field-number -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `default` | number | Value pre-filled into a new record when none is supplied for this field; the write that makes the field required also fills it into every row holding it empty. |\n| `notation` | [notation](#number) | How the figure reads: { "style": "decimal" }; money, { "style": "currency", "currency": an ISO 4217 code (USD, VND) }; or a quantity, { "style": "unit", "unit": "percent" (10 reads "10%"), or a measured code (g, kg, t, l, m3, cbm, mm, cm, m, km, m2, min, h, day), which converts and scales within its dimension, or any other noun of at most 12 characters (ki\u1EC7n, pallet, TEU), which never does }. A currency or unit read on each row from a single select of that row is { "per_row": that select }. Omitted, a decimal. |\n| `rating` | [Rating](#rating) | The figure is a grade: whole numbers 1 to `max` (3 to 10), empty or one of them, drawn as stars. Only on a plain decimal figure. |\n| `default_from` | text | Copied when a record is made off the row a one-row link of this entity names \u2014 `<link alias>.<field alias>` \u2014 or, reading on through one-row links, off the row the last of them names \u2014 `<link alias>.<link alias>.<field alias>` \u2014 and never re-read, so the source changing later leaves the row alone. A value the add states wins; a select copies each option as this field\'s option of the same alias. |\n| `min` | number \\| text | Refuse a create or update whose value is below this: a constant for a number, or a field \u2014 `<field alias>` of the same row, or `<link alias>.<field alias>` of the one row a link names \u2014 of the same type (a return date after the departure, a line\'s day inside its trip). On a figure whose unit or currency is per row (its notation\'s `per_row`) a constant bound is only 0; bound it by a field of the row |\n| `max` | number \\| text | Refuse a create or update whose value is above this: a constant for a number, or a field of the same row or of the one row a link names |\n\n#### Rating\n\n| Key | Type | Meaning |\n|---|---|---|\n| `max` | integer, required | The scale\'s top: the most stars a grade holds |\n\n<!-- generated:end field-number -->\n\n`notation` is how the number reads, and every surface reads it:\n`{ "style": "currency", "currency": "USD" }` prints as money in its code,\n`{ "style": "unit", "unit": "kg" }` as a quantity with its unit after it,\n`{ "style": "unit", "unit": "percent" }` as a percent \u2014 10 is "10%", never\nmultiplied \u2014 and `{ "style": "decimal" }`, or no notation, as a plain number. One\nkey, so a figure reads one way.\n\nAn absent number is drawn blank, except a `sum` or count rollup read as a meter\'s measure: nothing accumulated yet reads 0.\n\nA unit \u2014 `{ "style": "unit", "unit": "kg" }` \u2014 is what a figure counts or\nmeasures; `percent` aside, it is measured or counted. A **measured** unit is a code of one catalog \u2014 mass `g`\n`kg` `t`, volume `l` `m3` `cbm` (a cubic metre under freight\'s name), length\n`mm` `cm` `m` `km`, area `m2`, duration `min` `h` `day` \u2014 so a figure typed in\nanother unit of its dimension converts (`12,5 t` into a `kg` field is 12 500),\nand a tile or a chart reads it in the largest unit it reaches (12 500 kg as\n12,5 t\u1EA5n; CBM never scales) while a cell, a fact and a column always read in the\nfield\'s own. Any other noun of at most 12 characters (`ki\u1EC7n`, `pallet`, `TEU`) is a\n**counted** unit: a word after the figure that never converts. A measured unit is\nwritten as its code \u2014 `t\u1EA5n`, `KG` or `m\xB3` is refused, naming the code. A formula\nstates its own as its `notation`; a rollup that keeps the value (`sum`, `avg`,\n`median`, `min`, `max`, `range`) and a lookup carry the unit of the figure they\nread, exactly as they carry a currency, and a count carries none. A quantity is a\nnumber with its unit, never words (`3 cartons` in a text field): only a number\nsums, converts and reads down a column.\n\nA field\'s cells always hold figures in its own unit, so moving it between two\nunits of one dimension (`kg` to `t`) converts every stored figure \u2014 a change made\nin the workspace, in the field\'s settings (which say how many first) or through\n`set_tables`. Any other change of unit\nrelabels.\n\nA figure whose unit or currency varies by row names a single select of its own\nrow as `per_row` \u2014 `{ "style": "unit", "unit": { "per_row": "uom" } }`,\n`{ "style": "currency", "currency": { "per_row": "currency" } }` \u2014 or a lookup of\none through a one-link, a line reading its shipment\'s currency. That select\'s\noptions are the vocabulary: each label a unit (`chi\u1EBFc`, `kg`), or an ISO 4217 code\n(`USD`). A label outside it is refused when the figure is written and when the\nselect is \u2014 its options, its type or its deletion while a figure names it. A row\nwhose select is empty reads its figure bare. Every app reads each row\'s figure in\nits own row\'s unit, and a sum never mixes units: totals are one per unit, most rows first and units tied on rows in their select\'s option order (past three units a total the runtime draws over a set of rows \u2014\nsummary line, group totals and feet, a Sheet\'s table foot \u2014\nstates the count alone; a reading an author states draws every unit), a chart draws one at a time. A rollup that keeps the value (`sum`, `avg`, `min`\u2026)\nover such a figure stands only where the child\'s select is a lookup, through\nthe rollup\'s own link, of a select on this table \u2014 the rollup reads that\nselect\'s unit; otherwise it is refused. A lookup of such a figure stands only\nwhere its table also looks up the figure\'s select (stored, or itself looked up\nthrough one-row links) through the same one-link, and reads in that lookup; otherwise it is refused. A count is unaffected. Moving a field between a\nfixed and a per-row unit relabels.\n\n### `date`\n\n<!-- generated:start field-date -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `default` | text | Value pre-filled into a new record when none is supplied for this field; the write that makes the field required also fills it into every row holding it empty. A date string in the field\'s format. |\n| `format` | `"date"` \\| `"datetime"` \\| `"month"` \\| `"date_range"` \\| `"datetime_range"` | Whether the field holds a day or a moment, alone or as a span; `month` (stored YYYY-MM) holds a calendar month, a payroll or billing period: a full date written to it keeps its month. |\n| `timezone` | text | IANA timezone |\n| `derive_from` | `"created_at"` \\| `"updated_at"` | Auto-populate from the row\'s system timestamp; the field becomes read-only. |\n| `default_from` | text | Copied when a record is made off the row a one-row link of this entity names \u2014 `<link alias>.<field alias>` \u2014 or, reading on through one-row links, off the row the last of them names \u2014 `<link alias>.<link alias>.<field alias>` \u2014 and never re-read, so the source changing later leaves the row alone. A value the add states wins; a select copies each option as this field\'s option of the same alias. |\n| `min` | number \\| text | Refuse a create or update whose value is below this: a constant for a number, or a field \u2014 `<field alias>` of the same row, or `<link alias>.<field alias>` of the one row a link names \u2014 of the same type (a return date after the departure, a line\'s day inside its trip). On a figure whose unit or currency is per row (its notation\'s `per_row`) a constant bound is only 0; bound it by a field of the row |\n| `max` | number \\| text | Refuse a create or update whose value is above this: a constant for a number, or a field of the same row or of the one row a link names |\n\n<!-- generated:end field-date -->\n\nA `default` is refused beside `derive_from`: the platform stamps that date.\n\n### `boolean`\n\n<!-- generated:start field-boolean -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `default` | boolean | Value pre-filled into a new record when none is supplied for this field; the write that makes the field required also fills it into every row holding it empty. |\n| `default_from` | text | Copied when a record is made off the row a one-row link of this entity names \u2014 `<link alias>.<field alias>` \u2014 or, reading on through one-row links, off the row the last of them names \u2014 `<link alias>.<link alias>.<field alias>` \u2014 and never re-read, so the source changing later leaves the row alone. A value the add states wins; a select copies each option as this field\'s option of the same alias. |\n\n<!-- generated:end field-boolean -->\n\n### `select`\n\n<!-- generated:start field-select -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `default` | list of alias | Value pre-filled into a new record when none is supplied for this field; the write that makes the field required also fills it into every row holding it empty. Option alias(es) this field declares \u2014 one for single-select. |\n| `options` | list of [Select option](#select-option) (at least one), required | The choices, in the order every picker and every ladder lists them |\n| `multi` | boolean | Allow multiple selections |\n| `default_from` | text | Copied when a record is made off the row a one-row link of this entity names \u2014 `<link alias>.<field alias>` \u2014 or, reading on through one-row links, off the row the last of them names \u2014 `<link alias>.<link alias>.<field alias>` \u2014 and never re-read, so the source changing later leaves the row alone. A value the add states wins; a select copies each option as this field\'s option of the same alias. |\n\n#### Select option\n\n| Key | Type | Meaning |\n|---|---|---|\n| `alias` | alias, required | Stable local alias, unique within the field |\n| `label` | text, required | Display label for the option |\n| `color` | [colour](#select) \\| `null` | The colour the option\'s badge is drawn in; omitted, the option holds none and reads as its word wherever its select is drawn (a status\'s option takes a distinct colour), and an existing one keeps its own; null clears it |\n| `mark` | [mark](#select) | The option\'s own mark, drawn in place of its colour dot wherever the option is shown: the brand it is ({kind: "brand", name: one of facebook, instagram, threads, meta, tiktok, google-ads, zalo, linkedin, x, google-meet, youtube, telegram, whatsapp, gmail, google-drive, outlook, excel, kiotviet, misa, lark, payos, easyinvoice, google, reddit, quora, grok, claude}) a kit glyph ({kind: "icon", name: "wrench"}) or the face of who it is, drawn from its label ({kind: "avatar", name: "person" or "organization"}). Every option of a field has one, or none does. A mark a reader does not draw falls back to the dot |\n| `short` | text | A few letters the option reads as where room is short \u2014 a table\'s column ("K5" for a long legal category) \u2014 its label shown on hover |\n\n<!-- generated:end field-select -->\n\nA patch of a select states its whole `options` list: a list replaces whole, so an option it leaves out is deleted. To\nrename or recolour one option, restate every option kept, each with its alias. Rows still holding a deleted option refuse\nthe patch unless `force`.\n\n```json\n{\n "options": [\n { "alias": "draft", "label": "Draft" },\n { "alias": "confirmed", "label": "Confirmed" },\n { "alias": "shipped", "label": "Shipped", "color": "green" }\n ]\n}\n```\n\n`color` is one of: `red`, `orange`, `amber`, `yellow`, `lime`, `green`,\n`emerald`, `teal`, `cyan`, `sky`, `blue`, `indigo`, `violet`, `purple`,\n`fuchsia`, `pink`, `rose`, `slate`, `gray`, `zinc`, `neutral`, `stone`.\nEvery option is drawn in its colour wherever it shows \u2014 a cell, a row\'s line,\na record, a picker, the bar a reading splits the rows by.\n\nAn option may carry its own `mark`, drawn in place of its colour dot wherever\nthe option is shown \u2014 a stage, a chip, a filter, a fact, an entry of a log, a\nreading\'s part, a lookup of the select on another table. Where the select is its\nrows\' `records` `mark`, a brand or glyph stands on the row\'s lead tile in the option\'s\ncolour, and an option with none leads with its colour dot there. A select a reader scans\ndown a column \u2014 how a payment was made, the channel, the mode \u2014 states one on every\noption, since a glyph reads before its word: the brand it IS\n(`{"kind": "brand", "name": "tiktok"}` \u2014 one of `facebook`, `instagram`,\n`threads`, `meta`, `tiktok`, `google-ads`, `zalo`, `linkedin`, `x`,\n`google-meet`, `youtube`, `telegram`, `whatsapp`, `gmail`, `google-drive`,\n`outlook`, `excel`, `kiotviet`, `misa`, `lark`, `payos`), a glyph the kit draws\n(`{"kind": "icon", "name": "wrench"}`; any other name is refused), or \u2014 where the\noptions name people or organisations who are no member and no row \u2014 the face of who\nit is, drawn from its label (`{"kind": "avatar", "name": "person"}` or\n`"organization"`). Every option of a select has one, or none does: a run of chips\nwhere one carries no mark reads as the one missing something. `set_tables` writes the\nmarks onto the table. The glyph names are `reference/field/option-glyphs`.\n\n```jsonc\n"options": [\n { "alias": "short_video", "label": "Short video", "color": "zinc", "mark": { "kind": "brand", "name": "tiktok" } },\n { "alias": "print", "label": "Print", "color": "amber", "mark": { "kind": "icon", "name": "newspaper" } }\n]\n```\n\n### Option glyphs\n\nThe kit\'s glyph names an option\'s `mark` takes:\n\n<!-- generated:start field-select-glyphs -->\n\nactivity, align-center, align-left, align-right, align-vertical-justify-center, align-vertical-justify-end, align-vertical-justify-start, arrow-down, arrow-down-a-z, arrow-down-up, arrow-down-wide-narrow, arrow-left, arrow-left-from-line, arrow-right, arrow-right-from-line, arrow-right-left, arrow-up, arrow-up-down, arrow-up-wide-narrow, arrow-up-z-a, ban, banknote, bed, bell, between-horizontal-start, between-vertical-start, bold, bolt, book-marked, book-open, book-text, bot, box, brackets, brain, briefcase, building-2, calculator, calendar, calendar-clock, calendar-off, camera, car, chart-column, check, chevron-down, chevron-left, chevron-right, chevron-up, chevrons-down-up, chevrons-up-down, circle-alert, circle-check, circle-x, clipboard-list, clipboard-paste, clock, code, code-xml, columns-3, columns-3-cog, combine, construction, container, copy, credit-card, database, decimals-arrow-left, decimals-arrow-right, dollar-sign, download, ellipsis, eraser, expand, external-link, eye, eye-off, file, file-csv, file-down, file-question, file-spreadsheet, file-stack, file-text, file-up, folder, folder-closed, folder-open, folder-pen, form, funnel-plus, funnel-x, gauge, globe, gpu, grid-2x2, grip-vertical, group, hand-coins, hash, heading, heading-1, heading-2, heading-3, history, house, image, inbox, info, italic, keyboard, languages, layout-dashboard, layout-grid, library-big, link-2, link-2-off, list, list-checks, list-collapse, list-filter, list-filter-plus, list-ordered, list-tree, loader, lock, lock-keyhole, lock-keyhole-open, lock-open, log-in, log-out, mail, map-pin, maximize-2, megaphone, menu, message-circle, message-circle-question-mark, message-square, messages-square, mic, minimize-2, minus, monitor, mouse, mouse-pointer-click, music, newspaper, notepad-text-dashed, package, paint-bucket, paintbrush-vertical, palette, panel-left, panel-left-close, panel-left-open, panel-right, panel-right-close, panel-right-open, paperclip, pause, pencil, percent, phone, pin, pin-off, plane, play, plug, plus, receipt, rectangle-ellipsis, redo, refresh-cw, repeat, rotate-ccw, rotate-cw, rows-3, scan, scan-line, scissors, search, send, settings, share, share-2, shield, shield-alert, shield-check, shopping-cart, sigma, sliders-horizontal, smile, smile-plus, snowflake, sparkles, split, square, square-check, square-pen, square-sigma, star, stethoscope, sticky-note, strikethrough, table, table-2, tag, target, text-quote, text-wrap, thumbs-down, thumbs-up, ticket, trash, trending-down, trending-up, triangle-alert, truck, tv-minimal, type, underline, undo, upload, user, user-check, user-pen, users, utensils, waypoints, workflow, wrench, x, zap, zoom-in, zoom-out\n\n<!-- generated:end field-select-glyphs -->\n\n### `member`\n\nA person picker over the workspace\'s members. No default. With no role it is still drawn \u2014\nface and name, ranked as a `party` \u2014 in a screen\'s `columns` and in the register\na record draws of these rows.\n\n<!-- generated:start field-member -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `multi` | boolean | Allow multiple selections |\n| `default_from` | text | Copied when a record is made off the row a one-row link of this entity names \u2014 `<link alias>.<field alias>` \u2014 or, reading on through one-row links, off the row the last of them names \u2014 `<link alias>.<link alias>.<field alias>` \u2014 and never re-read, so the source changing later leaves the row alone. A value the add states wins; a select copies each option as this field\'s option of the same alias. |\n\n<!-- generated:end field-member -->\n\n### `link`\n\n<!-- generated:start field-link -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `default_from` | text | Copied when a record is made off the row a one-row link of this entity names \u2014 `<link alias>.<field alias>` \u2014 or, reading on through one-row links, off the row the last of them names \u2014 `<link alias>.<link alias>.<field alias>` \u2014 and never re-read, so the source changing later leaves the row alone. A value the add states wins; a select copies each option as this field\'s option of the same alias. |\n| `options_where` | [filter](#filters) | Which rows of the target this link may point at \u2014 an `and` group of plain conditions over the TARGET table\'s own fields, each `field_key` a field alias. It narrows every picker of the link, and a save naming a row outside it is refused on every path \u2014 an app, the grid, an import, a workflow, the API. |\n| `same` | list of alias (at least one) | One-row links this row and each row this link points at must name alike \u2014 a fee\'s invoice is one of its own visit\'s, a box\'s seal one of its own shipping line\'s: each a one-row link of both tables to the same table, or a lookup of one (a line\'s shipping line looked up from its visit, never stored beside it). It narrows the picker\'s read to the rows naming what this row names, a row made from the picker names it too (set, never asked), and a write is refused wherever it lands \u2014 on the link, or on what the two rows compare. |\n| `table` | text, required | The table the link points at: its alias, or the `ref` of another item of the call |\n| `multi` | boolean, required | Whether a row links to one row or many: true, many; false, one. Where the link is paired, at most one of the two sides holds one |\n| `pair` | `true` \\| alias | Makes the link two-way: the alias of its partner field on the other table, which names this one back, or `true` to have the alias derived. Stated on one table, the partner is made on the other with the inverse cardinality; a many-to-many link states both sides |\n\n<!-- generated:end field-link -->\n\n**`multi` is stated on every link:** `true` holds several rows, `false` one \u2014 one customer on an\ninvoice, one project on a device. There is no default.\n\nA two-way link states `pair` on one table, as `true` or a free alias, and the partner is made on the\nother table with the inverse cardinality; a many-to-many link states both sides, since the inverse of\nmany is not decided. A pair stated on both sides is made once. Both tables are written in the one\ncall (`table` names the other item\'s `ref`). A link with no `pair` is one-way, and nothing is created on the target. Pair a link when\nthe target\'s own record should list what points at it, and leave it unpaired when it should not: either\nway the record plan draws the relation as a section on the side it points at, so an unpaired link costs\nthe target nothing. Of two paired links at most one holds one row.\nA link to its own table is paired with itself (a spouse) when `pair` is `true`, and with a second field of that table when `pair`\nnames its alias (a parent and its children, each stating the other); paired with itself it cannot hold one row.\n\n```jsonc\n// a field of table "order"\n"customer": { "type": "link", "label": "Customer", "table": "customer", "multi": false, "pair": "orders" }\n```\n\n```jsonc\n// a field of table "customer"\n"orders": { "type": "link", "label": "Orders", "table": "order", "multi": true, "pair": "customer" }\n```\n\n### `files`\n\nA row attaches documents to it (`reference/rows`). Each file\nis drawn by its kind, with no key to choose: a picture (an image, a video) as its\nthumbnail, a document (a PDF, a sheet) as its type\'s badge and its filename.\n\n<!-- generated:start field-files -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `photo_places` | `true` | Each photo shot through a phone\'s camera into this field keeps where the device stood, as the device reported it and never proof of where the photo was taken: for photos whose place matters (inspections, deliveries, proof of a visit). Formulas on the table read it through `distance`; apps holding the capability draw it to members of the organization only, never to a visitor or another organization |\n\n<!-- generated:end field-files -->\n\n### `formula`\n\nA formula states its keys on the field itself, beside `type` and `label`:\n`{ "type": "formula", "label": "Total", "expression": "{quantity} * {unit_price}", "notation": { "style": "currency", "currency": "USD" } }`.\n\n<!-- generated:start field-formula -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `expression` | text, required | The expression, over fields of THIS entity by alias in braces \u2014 `{quantity} * {unit_price}` |\n| `output_type` | `"number"` \\| `"text"` \\| `"date"` \\| `"datetime"` \\| `"boolean"` \\| `"select"` | Holds a formula to the type its readers need: absent, it is what the expression yields. Stated, it is checked against that and refused where they differ (a datetime is never stated date) |\n| `notation` | [notation](#number) | How the figure reads: { "style": "decimal" }; money, { "style": "currency", "currency": an ISO 4217 code (USD, VND) }; or a quantity, { "style": "unit", "unit": "percent" (10 reads "10%"), or a measured code (g, kg, t, l, m3, cbm, mm, cm, m, km, m2, min, h, day), which converts and scales within its dimension, or any other noun of at most 12 characters (ki\u1EC7n, pallet, TEU), which never does }. A currency or unit read on each row from a single select of that row is { "per_row": that select }. For a formula yielding a number. |\n| `link` | `true` | The formula yields a URL as text, drawn as a link that opens. |\n| `options` | list of [Select option](#select-option) (at least one) | The categories the formula yields, drawn as a single select\'s options are (read-only). The expression yields one of them as `{this_field:option}`, or null \u2014 `{days_idle} > 30 ? {warmth:cold} : {warmth:hot}`. Omit for a formula yielding a plain value. |\n\n<!-- generated:end field-formula -->\n\n`output_type` is what lets a role or a screen clause accept a computed value: a\ncaption over a derived name (`output_type: "text"`), a period over a settled date\n(`"date"`). A formula declaring no `output_type`, `notation` or `link` says nothing\nabout its result, and every rule that needs one refuses it by name. A formula stating\n`options` is a computed category: read-only, and read as a single select\nwherever it is drawn \u2014 a column, a filter, a reading\'s `by` or `where`.\n\n**A select reaches a formula as the KEYS of its chosen options**, a list \u2014\nnever their labels, and never their aliases \u2014 and a document has no keys: the\nworkspace mints them when the table is made. So an option is named in a formula\nas `{field:option}`, both aliases, and the write puts that option\'s key in its\nplace: `includes({kind}, {kind:crate})` for a select holding one or several,\n`{kind}[0] == {kind:crate}` for a single one. A select compared to its own words\n(`{kind} != "Crate"`) matches no row and computes the other branch everywhere,\nso the check refuses it and names the token. A select looked up through a link\nof one row (`multi: false`, or a chain of them) is named the same way:\n`{parent_stage} == {parent_stage:won}`. A lookup through a link holding several\nrows has no single option; it is tested on the table it lives on, in a formula of\nits own, and that result looked up.\n\n**The language.** The check refuses a call or a name the platform cannot run, naming what to write:\n\n<!-- generated:start field-formula-language -->\n\n- Operators: `+ - * / %`, `== != > < >= <=`, `&& || !`; `+` also joins text\n- Numbers: arithmetic is exact decimal (`0.1 * 3` is `0.3`), a division that does not end the nearest double; a comparison between two numbers reads both at 15 significant digits; `round` rounds a half away from zero (`round(-2.5)` is `-3`)\n- Conditionals: a ternary only \u2014 `{amount} > 100 ? "High" : "Low"`\n- Not supported: optional chaining (`?.`), nullish coalescing (`??`), template literals, arrow functions \u2014 use `get(obj, "path", default)`, `coalesce(v1, v2)`\n- Helpers are these names, spelled exactly; a spreadsheet function (`IF`, `SUM`, `LEN`, `DATEDIF`) is none of them, and a formula calling one is refused\n- Math: round(n,decimals?), ceil(n), floor(n), abs(n), min(a,b), max(a,b), sum(arr), mean(arr), clamp(n,min,max), percentage(part,total,decimals?), pow(base,exp), sqrt(n), mod(n,divisor), distance(lat1,lon1,lat2,lon2) (metres along the earth between two places in degrees; null when an argument is empty)\n- Photo places: distance(photos,lat,lon) over a files field stating `photo_places` is a list, one entry per file in order \u2014 the metres from where its photo was taken to (lat,lon), null for a file with no kept place; judge a cell with a list helper: `max(distance({photos},{site_lat},{site_lon})) > 150`\n- A select reads as its option keys: compare it with `{field:option}`; read its name as text with `label({field})`\n- Strings: label(select) (the option\'s name; a multi-select\'s names joined ", "), upper(s), lower(s), trim(s), capitalize(s), length(s), contains(s,search), join(arr,sep), split(s,sep), replace(s,search,rep), replaceAll(s,search,rep), removeChars(s,chars) (s without any character that occurs in chars), removeSpaces(s) (s without any whitespace), startsWith(s,prefix), endsWith(s,suffix), substring(s,start,end?), padStart(s,len,char), padEnd(s,len,char), numberToWords(n, lang?) (lang \'vi\' default, or \'en\'), uuidFrom(s) (the same UUID for the same text)\n- Lists: includes(list,value), first(list), last(list), unique(list), compact(list) \u2014 length(list) counts one; join, sum, mean, first, last, unique and compact read a single value as a list of it\n- Dates: now(), formatDate(d,fmt), addDays(d,n), subDays(d,n), addHours(d,n), subHours(d,n), addMinutes(d,n), subMinutes(d,n), startOfDay(d), endOfDay(d), startOfMonth(d), endOfMonth(d), addMonths(d,n), differenceInCalendarDays(later,earlier) (days between two dates, whatever it is searched as: `daysBetween`, `diffDays`, `dateDiff`), differenceInHours(later,earlier), differenceInMinutes(later,earlier), isBefore(d1,d2), isAfter(d1,d2), isSameDay(d1,d2), isToday(d), isWithinRange(d,start,end), datesOn(from,until,days) (the days from..until falling on weekdays named `mon` to `sun`, as a list of dates), meetsBounds(value,kind,{gt,gte,lt,lte},tz?), parseDate(d)\n- Null/type: isNull(v), isEmpty(v) (also true for "" and []), coalesce(v1,v2,...), isString(v), isNumber(v), isBoolean(v), isArray(v), toNumber(v), toFigure(v), toString(v)\n- Other: formatCurrency(amount,locale,currency), formatDecimal(value,decimals,locale) (grouped quantity, no symbol; without decimals, `formatDecimal(value,locale)`, the decimals it holds, at most two, as the app draws a figure), get(obj,"path",default?)\n- Empty cells: a cell nobody filled is null inside a formula, whatever its type; one holding 0, false or "0" is not empty. Test it with `isEmpty({note})` \u2014 `{note} == ""` and `{done} == false` are false on an unset cell\n- Arithmetic over an empty cell: `+` and `-` read it as 0 beside a value (`{fee} + {surcharge}` is `{fee}` when the surcharge is empty, null when both are); `*`, `/`, `%` and a unary `-` yield null (`{price} * {qty}` is null, not 0, when the quantity is empty)\n- No helper throws on an empty cell: the math helpers and toNumber return null, the string helpers "". A value of the wrong type still errors. When EVERY field a formula reads is empty it is null \u2014 unless it reads each only as the argument of isEmpty, isNull or isNotNull (`!isEmpty({file})` is false there, not null)\n\n<!-- generated:end field-formula-language -->\n\n### `rollup`\n\nAggregates the records reached through a link on this table.\n\n<!-- generated:start field-rollup -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `filter` | [filter](#filters) group | Only linked records matching this filter are aggregated; one condition on its own is a group of one. Every `field_key` in it names a field alias on the linked entity, and a select condition\'s value names an option alias there. A traversal node reaches past that entity, so its `path` hops and inner `field_key` are fully-qualified `entity.field` aliases. |\n| `via` | alias, required | The alias of a link of this table to roll up from |\n| `op` | [operation](#rollup), required | The operation over the linked rows |\n| `field` | alias | The alias of the field on the linked table the operation reads; absent for `count` |\n\n<!-- generated:end field-rollup -->\n\nA rollup states `via` (a link of this table), `op` and \u2014 except for `count` \u2014 `field`, an alias on the\nlinked table; `op` is one of `count`,\n`sum`, `avg`, `median`, `min`, `max`, `range`, `empty`, `filled`,\n`percent_empty`, `percent_filled`, `unique`, `percent_unique`, `earliest`,\n`latest`, `date_range`, `checked`, `unchecked`, `percent_checked`,\n`percent_unchecked`. The operation must be one the aggregated field\'s type\nallows \u2014 `sum` over a number, `earliest` over a date, `filled` over any stored or\nformula field. A lookup is never rolled up: roll up the child\'s own field, or a formula\nover it. A rollup states no `notation`: `sum`, `avg`, `median`, `min`, `max` and `range`\nread in the aggregated figure\'s, a count as a plain number, and a `percent_*` as a\npercent (0\u2013100), in the app as in the table.\n\n### `lookup`\n\nDisplays a field from the linked records: `via` names a link of this table, `field` a field of the table it\npoints at. Through a link holding several rows it holds every linked row\'s value, which an app reads whole: a sort by\nits first value, a filter matching any value, a grouping counting the row under each; `order_by` (`field`, `direction`)\npicks the one row whose value shows instead.\n\n<!-- generated:start field-lookup -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `via` | alias, required | The alias of a link of this table to look up through |\n| `field` | alias, required | The alias of the field on the linked table to show |\n| `order_by` | [Lookup order](#lookup-order) | Show ONE linked row\'s value \u2014 the first in this order \u2014 rather than every linked row\'s |\n\n#### Lookup order\n\n| Key | Type | Meaning |\n|---|---|---|\n| `field` | alias, required | A field alias on the linked table the rows are ordered by |\n| `direction` | `"asc"` \\| `"desc"`, required | Which end of that order the one row is taken from |\n\n<!-- generated:end field-lookup -->\n\nInside a formula, a lookup holding one value is that value (`{due_soon}` is\n`true`, not `[true]`); several values are a list.\n\n### `autonumber`\n\n<!-- generated:start field-autonumber -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `prefix` | text | Literal prefix prepended to every display value (e.g. \'KH-\' \u2192 \'KH-001\'). Ignored when `template` is set. |\n| `padding` | integer | Zero-pad the integer to this width. Default 1 (no padding). 3 \u2192 \'001\', \'012\', \'123\', \'1234\' (overflow uses the actual width). Ignored when `template` is set. |\n| `template` | text | Format template with placeholder tokens evaluated at insert time. Tokens: {N} (raw integer), {N:W} (zero-padded to width W, e.g. {N:3} \u2192 001), {YEAR} (4-digit year), {YEAR:2} (2-digit year), {MONTH} (2-digit month), {DAY} (2-digit day). Date tokens use the workspace timezone. Example: \'HM-{YEAR}-{N:3}\' yields \'HM-2026-001\'. Stored as the composed string; subsequent template edits do NOT re-format existing rows (date tokens would lose the original creation date). |\n| `next` | integer | Sets the number the next row takes, once, as the patch is written; never below one past the highest number issued. On a field added to a table with rows, those rows are numbered from it in creation order. It is no setting of the field: a read of the table shows none |\n\n<!-- generated:end field-autonumber -->\n\nA refused write and a dry run take no number, so a table\'s numbers run without a gap; a removed row\'s number is not\nissued again.\n\n<!-- generated:start rules-field -->\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `field.default` | A default names options its select declares \u2014 one on a single select \u2014 and a date stamped by `derive_from` states none. |\n| `field.default-from` | A field\'s `default_from` reads `<link>.<field>` off the row a one-row link of its table names \u2014 a link no copy fills \u2014 or, through further one-row links, `<link>.<link>.<field>` off the row the last names, into a field of the same type, date format and notation that `derive_from` does not stamp (a figure read per row, into one whose select is copied from or looked up off the source\'s select by the same links): a lookup only through a one-row link, a link only into one to the same table, a select\'s option as this field\'s of the same alias (one it lacks is not copied), several values only into a field holding several. The server copies it on every add that fills the link and leaves the field empty, so a List\'s `create` sure to fill the link \u2014 a required one, or the record it files the row under \u2014 does not ask it by default. |\n| `field.option-mark` | An option\'s `mark` is one the kit draws, and a select\'s options mark every one or none. |\n| `field.unit-select` | A notation\'s `per_row` names a single select of the same row, or a lookup of one through a one-link, whose every option label is a unit, or an ISO 4217 code. |\n| `field.link` | A link targets a table of the call or the workspace: its `pair` a link on that table naming this one back \u2014 and of two paired links at most one reads one row (`multi: false`). |\n| `field.formula` | A formula parses, reads fields of its own table by alias, names an option as `{field:option}` of a select it holds, or looks up through a link of one row, and compares a select to its options\' keys, never their words. |\n| `field.formula-type` | A formula yields what it states \u2014 its `output_type` (the type the platform stores: a `"datetime"` is never stated `date`), else a figure where it states a `notation` and text where it states `link` \u2014 as the platform infers it from the expression when the field is created. |\n| `field.rollup` | A rollup aggregates, through a link of its table (`via`), a field of the linked table (`field`) by an operation (`op`) that field\'s type takes \u2014 a figure read in each row\'s own unit or currency only by an `op` that keeps its values whose child select is a lookup, through the rollup\'s own link, of a select on this table \u2014 filtered on fields of the linked table. |\n| `field.lookup` | A lookup reads (`field`), through a link of its table (`via`), a field of the linked table \u2014 a figure read in each row\'s own unit or currency only where this table looks up that row\'s select through the same one-row link \u2014 ordered by a field of it (`order_by`). |\n| `field.computed-cycle` | Computed fields never wait on each other in a loop: each is computed after what it reads. |\n\n<!-- generated:end rules-field -->\n\n## Filters\n\nA table\'s saved views are not part of its document: `set_table_views` writes them and `get_table` lists them. A view\'s\nfilter, a color rule\'s filter, `options_where` and a rollup\'s `filter` share one grammar. Every field reference is a\nfield ALIAS on that table.\n\nA filter is a group \u2014 `{ "node_type": "group", "logic": "and" | "or",\n"children": [ \u2026 ] }` \u2014 or one condition on its own, `{ "node_type":\n"condition", "field_key": "tier", "operator": "has_any_of", "value": ["gold"] }`. A sort is a list of `{ "field_key": \u2026, "order": "asc" |\n"desc" | null }`. A condition states no `type`: its field\'s type decides which `operator` it admits: `has_any_of` / `has_none_of` / `has_all_of` / `is_empty` /\n`is_not_empty` for a select, `equals` / `greater_than` / `less_than` for a\nnumber, `on` / `before` / `after` / `between` for a date, `contains` /\n`is_any_of` for text. A select condition\'s `value` names option ALIASES.\n\n<!-- generated:start rules-color -->\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `color.fields` | A color rule\'s filters name fields of its table. |\n\n<!-- generated:end rules-color -->\n\n## Groups and templates\n\nA member group and a document template are made on their own, outside a table document and an app tree. A tree names a\ntemplate by its alias. A table document names a group by its id, where a `read_scope` clause (`member_of`),\na stage owner (`group`) or a check\'s `member_of("<id>")` takes one. `get_workspace` kind `group` lists the workspace\'s groups with their ids and members; `set_members` creates,\nchanges or deletes one in its `groups` (an admin\'s of the workspace). A group belongs to one workspace and holds only its people.\n\n`{{name}}` in an `html` or `email` template is filled from the workflow\'s data. Inline content is refused where it holds a\nscript, a frame, a `<link>`, an inline event handler or a `javascript:` URL; an `html` one may be a fragment, kept as\nwritten and printed as a whole document.\n\nA template\'s markup is the `template` of `set_template`, as one JSON string. A paper shaped like a counterparty\'s \u2014 a letterhead, a reference line, a seal, a signature block \u2014 is an `html` template with a shell around the body; `document_templates` covers the types.\n\n**What an act\'s template is handed** is its record\'s own fields by alias: a\nselect, a member and a link as their words (a link as the linked row\'s title), a\nnumber, a date and a computed value that declares its kind raw (`2800000`,\n`2026-09-14`) and a files field as its file cells (`{id, name, mime, url}`, the photos in the order held; a child row\'s\nfiles likewise) \u2014 never a computed select. On one record it is\nhanded, too, the rows of each child List the record draws, listed under that child\'s\nlink\'s name for `{{#each <link>}}` (and under the child entity\'s alias too): every row filed under the record, oldest first, each\nby its own fields as the record\'s are, less its link back to the record. A List that only reads is listed under its `key`, its rows reached by its link\nor, for a `<link>.<link>` path, by both. Over\nseveral rows (at most 200) the rows are listed under the table\'s alias, for\n`{{#each <alias>}}`, an html paper hands each row its own child rows under the same names, with `<name>_totals`.\n\n**Photos in a paper.** A file cell is drawn only if whoever makes the paper may read that file, by the rule the file\nproxy applies; a file they may not read is never drawn. html: `{{#each photos}}<img src="{{url}}">{{/each}}`, each\nphoto inline, only those the data\'s file cells carry (a url typed into a text field stays a link). Word:\n`{{IMAGE picture(cover, 8)}}` for one file cell, and `{{FOR p IN photos}}{{IMAGE picture($p, 8)}}{{END-FOR p}}` for\nmany. Excel: `{{cover | picture:6}}` as the whole cell, and `{{#each photos}}` with `{{this | picture}}` for many, each\nrow growing to its picture. The number is the width in centimetres (8 by default, 6 in Excel); the height follows the\npicture. `picture` takes one image file cell: a list, a file that is no image and a file that cannot be read are\nrefused by name. Photos are embedded at most 1600 pixels across.\n\nHelpers print a raw value in the template\'s `locale` \u2014 `vi` or `en`, the organization\'s language where it states\nnone; each prints `""` for an empty value:\n\n| Helper | Prints (`vi` / `en`) |\n|---|---|\n| `{{money total "USD"}}` | `1.250,50 US$` / `$1,250.50`, in the currency\'s minor units; no code, a number |\n| `{{number qty}}`, `{{number qty unit}}` | `1.234,5` / `1,234.5`: grouped, up to 2 decimals; a unit as the second argument follows it (`{{number qty item_unit}}` prints `6 kg`, `2 l\xEDt` / `2 L`: a measured unit in the language\'s label, a counted noun such as `th\xF9ng` as written) |\n| `{{date issued_on}}` | `14/09/2026`, `14 Sep 2026` in an English template; a date-fns pattern as the second argument, `{{date at "dd/MM/yyyy HH:mm"}}`, literal text quoted (`"\'Ng\xE0y\' dd"`). A moment prints on the workspace\'s timezone |\n| `{{words total "USD"}}` | `M\u1ED9t ngh\xECn hai tr\u0103m n\u0103m m\u01B0\u01A1i \u0111\xF4 la M\u1EF9 n\u0103m m\u01B0\u01A1i xu` / `One thousand two hundred fifty US dollars and fifty cents`; no code, VND (`\u0111\u1ED3ng`) |\n| `{{qr link}}`, `{{code128 position 6}}` | the value as a QR code, or as a Code 128 barcode (ASCII text only), a picture the width of the optional second argument in centimetres, by default sized to the value (a module prints 0.5 mm in a QR code, 0.33 mm in a barcode); a width too narrow to scan is refused, naming the least that does; not in an email template |\n| `{{date (add_days issued_on -1)}}` | `13/09/2026`: the date shifted by whole days (`-1`: the day before), for `date` to print; a number field as the days, empty shifting none |\n\nA value it cannot read (`{{money "abc"}}`, `{{date "14/09/2026"}}`) fails the render. A field named like a\nhelper and written alone (`{{number}}`) prints its own value.\n\nA field printed as a code in the other types: Excel `{{position | qr}}` or `{{position | code128:6}}` as the whole\ncell and the last helper \u2014 the picture is anchored on the cell and its row grows to hold it; Word `{{IMAGE qr(position)}}` or `{{IMAGE code128(position, 6)}}`. An empty field draws no picture.\n\n## Rows\n\n`rows` of a `set_tables` call are the first records of the tables the call creates, keyed by each one\'s `ref`;\na patch of an existing table seeds none, so write its rows into the table. A sample, not a data set: rows past it go in with `create_records` once the tables exist, in the batches its description bounds.\n\n```jsonc\n"rows": {\n "customer": [\n { "ref": "acme", "fields": { "name": "Acme Trading", "tier": "gold" } }\n ]\n}\n```\n\n`rows` sits beside `tables` in the call, not inside a table.\n\n<!-- generated:start rows -->\n\n#### Row\n\n| Key | Type | Meaning |\n|---|---|---|\n| `ref` | text, required | Local handle for this row, referenced by other rows\' link fields |\n| `fields` | map of text \u2192 any value, required | Field alias \u2192 the value, read against the field\'s declared type |\n\n<!-- generated:end rows -->\n\n<!-- generated:start rules-rows -->\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `rows.ref` | A row\'s `ref` is unique within its table. |\n| `rows.required` | A row states every field its table requires: it is created with what it states, its fields\' defaults and copies unapplied. |\n| `rows.value` | A row\'s value fits its field: an option alias for a select, `"<table ref>:<row ref>"` of a row of the linked table in this call or a stored record\'s id for a link, `"self"` for a member, a `fil_` id for files, a date in the date grammar (an hour only on a datetime), a text, number, yes/no or null otherwise \u2014 and none on a computed field. |\n\n<!-- generated:end rules-rows -->\n\nA `ref` is lowercase letters, digits and underscores, and is never persisted.\n\n`fields` is keyed by field alias, and every value is read against the field\'s\nDECLARED type:\n\n| Field type | Value |\n|---|---|\n| `text` / `number` / `boolean` | the value itself |\n| `date` | `"2026-03-14"`, or a relative expression (below) |\n| `select` | the option ALIAS \u2014 `"gold"`, or `["gold","vip"]` for a multi-select |\n| `link` | `"<table ref>:<row ref>"` naming another row of this call \u2014 `"customer:acme"` \u2014 or the id of a record the linked table already holds, or an array for several; a paired link is stated on ONE side (the child\'s link to its parent) and its partner fills itself |\n| `member` | `"self"` only \u2014 the member making the call |\n| `files` | the `fil_` id of a file already in this workspace, or a list of them |\n| `formula`, `rollup`, `lookup`, `autonumber` | not allowed \u2014 the platform writes these |\n\n### Relative dates\n\nA date cell holds a literal `YYYY-MM-DD`, or an expression relative to the day\nthe call is made, so a screen that opens on "this month" is not empty a month\nlater:\n\n- `@today` \u2014 the day of the run, in the workspace\'s timezone\n- `@month-start` \u2014 the 1st of that month\n- either with a whole-day offset: `@today-14`, `@month-start+9`\n- on a date that holds its hour (`format: "datetime"`), that hour after the day, and always stated:\n `@today 14:30`, `@today+1 06:00`\n\n`@month-start` exists because `@today-N` cannot promise a month: applied on the\n2nd, `@today-3` lands in the previous one.\n\n## Records\n\n`records` says how a row of a table is RECOGNISED \u2014 stated once in the table\'s document, beside its\n`title` \u2014 and every surface that draws one of its rows reads the same\nstatement: the register\'s row, a picker\'s option, a link\'s chip, a child table\'s\nrow and the record\'s header. Every table an app lists, opens or picks has one. The rarer keys \u2014 `scan`, `cadence`, `place`, `pin` and `plan_place` \u2014 are stated on `reference/record-places-pins-and-cadence`.\n\n```jsonc\n// table "visit"\n"title": "container_no",\n"records": {\n "subtitle": ["customer", "arrived_on"],\n "image": "photos",\n "status": { "field": "stage", "closed": ["gone"], "history": "visit_history" },\n "figure": "total_fees",\n "due": ["free_until"]\n}\n```\n\n```jsonc\n// table "release": a release order read against what it allows \u2014 a meter wherever it shows\n"title": "release_no",\n"records": { "figure": "issued", "limits": { "issued": "units" } }\n```\n\n```jsonc\n// table "dossier": a straight-line process \u2014 the stage a select, each step\'s day the date it stamps\n"title": "applicant",\n"records": { "status": { "field": "stage", "closed": ["signed"], "dates": { "received": "received_on", "appraised": "appraised_on", "signed": "signed_on" } } }\n```\n\n<!-- generated:start records -->\n\n#### Record\n\n| Key | Type | Meaning |\n|---|---|---|\n| `subtitle` | list of alias (1\u20132) | Up to two fields read under the title wherever a row is drawn (a code, a date, a party): the first at the body ink and the rest muted, one line at a desk, a second on a phone; a card shows one line per column |\n| `image` | alias \\| list of alias (at least one) | A files field that pictures the row, or a one-row link to a table with a picture (or a lookup of one through a one-row link: a delivery led by its order\'s customer), whose picture the row leads with \u2014 never a files field an act keeps the document it makes in. A list of them, each a different field, is read in order: the first that holds a picture pictures the row (a line linking either a product or a bundle). Absent, a table with exactly one files field is pictured by the first image in it \u2014 never a paper or other file \u2014 unless the entry states a `mark` or puts that field in the title or subtitle; an app turns it off with `row.image: false`. |\n| `image_shape` | `"portrait"` \\| `"square"` \\| `"landscape"` | The shape the register\'s cards and tiles, and a child List stating `layout: "cards"`, draw the row\'s picture at: portrait (4:5), square or landscape (16:9), whatever the pictures themselves measure; only where the rows lead with a picture (`image`, or the default lone files field \u2014 not where a `mark` leads or that field is in the title or subtitle). Absent, a card\'s banner is landscape and a tile square; a small lead keeps its size |\n| `mark` | alias | A single select (or a lookup of one through a one-row link) whose option leads the row wherever a mark leads it \u2014 a list\'s row, the record\'s head, a link naming the row: the option\'s brand or glyph, else its colour dot, on a tile. The field stays a field: a subtitle run, a column, a section\'s control. A write setting a formula mark is refused (a derived flag is an issue) and a stored one keeps drawing; never beside `image` or `party`, and never the status field |\n| `description` | alias | A text field saying what the row is about \u2014 a plan\'s brief, a customer\'s note: read in its record\'s head under the title\'s line, its first lines at rest and whole on a press, and written from the head\'s \u270E. Never on a row\'s line |\n| `party` | `"person"` \\| `"organization"` \\| `"organisation"` | What each row is where the rows are people (a contact, a patient) or organisations (a customer, a supplier, a carrier); absent, the rows are things (an order, an item, a paper) |\n| `status` | [Status](#status) | The stage a row moves through, a single select, drawn in the record\'s head, or its Side where the Side states it |\n| `figure` | alias | The one number the row stands for, read at its right (a total, a quantity left) |\n| `limits` | map of alias \u2192 (alias \\| number) | A number read against a bound \u2014 a field of the same row or a constant \u2014 drawn as a meter wherever it shows |\n| `gates` | map of alias \u2192 (alias \\| number) | A pass mark on a meter `limits` bounds \u2014 a field of the same row or a constant; a percent field is its share of the bound, any other number an amount. The meter marks it and fills complete once past it |\n| `due` | list of alias (at least one) | Dates that are deadlines (stored, or computed as a date): each counts down and turns overdue until the row is at a `closed` option or `settled` holds, whatever stage it has moved to. A deadline is never an appointment date or the day a stage starts |\n| `frees` | alias | A date ending the row\'s span of days on which what the row holds is free again (a check-out, a hire\'s return): a stay from the 3rd to the 5th holds the 3rd and the 4th, and another may start on the 5th \u2014 on a lanes board, a calendar, a roster and in `no_overlap` alike. Absent, a span of days holds its last day; a span of moments always frees its end |\n| `settled` | alias | A yes/no of the row (stored, a formula: an invoice paid in full, or looked up through a one-row link: a line settled with its parent) that ends its deadlines: while it is true, no `due` of the row counts down or turns overdue \u2014 in a cell, on its line, in its head, on a calendar or gantt, or in the overdue count. A Sheet\'s or reading\'s `where` reads it as any other yes/no |\n| `task` | `true` | A row is work someone finishes: wherever rows of it stand in a table \u2014 a register, a record\'s rows, the rows filed under one \u2014 each is led by a ring ticking it done and unticking it by the one write of the app making that move. Its status is a stored select with `closed` |\n| `applies` | map of alias \u2192 map of alias \u2192 (list of alias (at least one) \\| boolean) | Fields that apply only while their conditions hold (a length only on a line whose tariff charges by the metre): where one does not apply no add asks it and no surface shows it. Never the title; a required one starts at its `default` |\n| `starts` | map of alias \u2192 `"today"` \\| `"me"` | What a field of a row being added starts at, where that start is certain: `today` a date (a moment starts now), `me` a member, the reader adding it; every other field starts empty unless the reader narrowed the register to a value or the field declares a `default` |\n| `issues` | list of (alias \\| [Rolled issues](#rolled-issues)) (at least one) | What is wrong with a row, in priority order, standing in every app that draws it: a formula of the row stating `output_type` boolean (true stands) or text (non-empty stands, its words the sentence), named by alias \u2014 its label is the issue\'s name; or `{ rows: <link> }`, a many-link paired to a one-row link, which rolls up the issues the linked table declares itself, each kept as a count on this table (`<link>_<issue>`), at that position. A derived flag is an issue: state a yes/no formula for each case |\n\n#### Rolled issues\n\n| Key | Type | Meaning |\n|---|---|---|\n| `rows` | alias, required | A many-link of this table, paired to a one-row link on the linked table, which declares issues of its own: each is counted here as `<link>_<issue>`, a roll-up of the linked rows holding it |\n\n<!-- generated:end records -->\n\n<!-- generated:start rules-records -->\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `records.title` | A title is the one field naming the row \u2014 any field but a button or a yes/no \u2014 and the subtitle never names the title\'s own field. |\n| `records.image` | `image` is a files field, never one an Act keeps the documents it makes in (`into`), or a single link to a table with a picture \u2014 its own, or a lookup of one through a single link (never beside a `party`) \u2014 or several of them in order, each stated once. |\n| `records.image_shape` | `image_shape` is portrait, square or landscape, the shape of the register\'s cards and tiles and of a child List stating `layout: "cards"`, stated only where the rows lead with a picture (`image`, or the default lone files field \u2014 not where a `mark` leads or that field is in the title or subtitle). |\n| `records.mark` | `mark` is a single select or a lookup of one through a one-row link, never a formula (a write setting one is refused: a derived flag is an issue), never the status field, nor on the folder an App works inside (`scope`), which its switcher names by a picture or its initials. |\n| `records.description` | `description` is a text field, read in the record\'s head \u2014 never a Field of a part too. |\n| `records.issues` | An issue is a formula of the row stating `output_type` "boolean" or "text" (a derived flag is an issue, never a select), listed once among the table\'s issues, or `{ rows }` naming a many-link paired to a one-row link, listed once, to a table that declares issues of its own \u2014 each rolled issue held as the count `<link>_<issue>` on the table. |\n| `records.figure` | A figure is a number. |\n| `records.applies` | `applies` holds a field of the row other than its title to conditions of the same row \u2014 a yes/no (stored or a formula) by `true` or `false`, a single select by its options, its own or looked up through a one-row link \u2014 never to itself; a required field it holds starts at a `default`. |\n| `records.limits` | `limits` bounds a number by a number field of the row, in its unit or one of the same dimension \u2014 or by a constant, where every row reads the figure in one unit. |\n| `records.gates` | `gates` marks a pass on a meter `limits` bounds: a percent field (its share of the bound), another number in the bound\'s unit, or a constant. |\n| `records.starts` | `starts` starts a field a person writes \u2014 `"today"` a date or a moment (never a span), `me` a member \u2014 and a `create` that does not ask a field it starts writes that start. |\n| `records.due` | A deadline (`due`) is a date. |\n| `records.frees` | `frees` names a stored day, never a moment: a span of moments already frees its end. |\n| `records.settled` | `settled` names a yes/no of the row (stored, a formula, or looked up through a one-row link) beside a `due`: while it holds, the row\'s deadlines neither count down nor turn overdue. |\n| `records.task` | A task entity (`task`) states a `status` of a stored single select with `closed` options \u2014 its ring ticks a row done by moving it to one. |\n| `records.cadence-makes` | *Noted, never refused:* An entity with a multi-select of weekdays that no `cadence` reads, whose rows a one-row child holding a date stands under, states a `cadence` naming the child, and an Act `makes` its rows. |\n| `records.picture` | *Noted by the designer on a write, never refused:* Rows an App draws that each hold one files field no Act makes documents into, no call is filed into, no files gallery keeps and no List compares as a pair (`compare`) \u2014 and no figure \u2014 are pictured by it (`image`); where the workspace\'s files are known, the field holding images is the picture, a figure or not. |\n| `records.mark-derived` | *Noted, never refused:* A table whose `records.mark` is a formula keeps drawing it; a derived flag is an issue, so a write setting `mark` to a formula is refused (`records.mark`) and a stored one keeps drawing. |\n| `records.mark-lead` | *Noted by the designer on a write, never refused:* Rows an App draws of an entity that states a single select besides its status whose options state a mark, and states no `mark`, `image` or `party`, can lead with that field\'s option as their mark (`records.mark`). |\n| `records.stage-holder` | *Noted, never refused:* A stage owned by a member field of the row itself, where the table does not require that field and no `create` or Act of the App states it (asks, sets, requires or writes it), lets a row reach the stage with the field empty: require the field, or state it in a `create` or an Act. |\n\n<!-- generated:end rules-records -->\n\n- **The title names the row** by who or what it is \u2014 a link by the linked row (a job\n read by its customer). Any field but a button or a yes/no may title it, yet a code\n titles a row only where people name the row by it, else it is a `subtitle`; it is the table\'s own setting, which every link shows.\n- **One lead per row.** A row leads with its picture (`image`), a face (`party`) or the\n option of a single select it holds (`mark`) \u2014 never two. A `mark` draws that option\n on a tile: its brand or glyph, else its colour dot; a row holding none, a ring saying\n none is picked. The same tile heads the row\'s record and leads it where a link\n names it; the select stays a field \u2014 a subtitle run, a column, a section\'s control.\n- **A limit** reads a number against a bound \u2014 another field of the row, or a constant.\n A `gates` entry marks a pass on that meter: a percent field is its share of the\n bound, any other number an amount.\n- **A deadline** (`due`) counts down wherever it is drawn and is overdue once past while\n the work is open. A register over the table says how many rows in view are overdue on\n its summary line, and pressing that count narrows to them \u2014 no reading to state.\n- **A span\'s free day** (`frees`) is the end date on which what the row held is free\n again \u2014 a check-out, a hire\'s return. A stay from the 3rd to the 5th holds two nights:\n a lanes board, a calendar and a roster draw it through the 4th, and `no_overlap` lets\n the next stay start on the 5th. Without it a span of days holds its last day; a span of\n moments always ends as the next may begin.\n- **`starts`** is where an add\'s field begins, stated only where that is certain \u2014 a\n log\'s own day at `today`, a request\'s requester at `me`. Nothing else starts a field\n but its declared `default` and what the reader narrowed the register to.\n\n## Record places, pins and cadence\n\nThe rarer keys of `records`, stated beside the ones on `reference/records`: a title read off a photo (`scan`), the rows a child owes each day (`cadence`), where a row stands on a map (`place`) or on a picture (`pin`, `plan_place`).\n\n```jsonc\n// table "site": it owes a diary page each day it works, from breaking ground through handover\n"title": "name",\n"records": { "cadence": [{ "entity": "diary_page", "on": ["mon", "tue", "wed", "thu", "fri", "sat"], "from": "started", "until": "handed_over" }] }\n```\n\n<!-- generated:start records-places -->\n\n#### Record places\n\n| Key | Type | Meaning |\n|---|---|---|\n| `cadence` | list of [Cadence](#cadence) (at least one) | The rows of a child each row owes one of a day, on the days of the week listed or its own multi-select names (a site\'s diary page, Monday to Saturday; a class\'s Tuesdays and Thursdays at 16:00) \u2014 one entry a child, never owed on a day still to come; an Act\'s `makes` makes them. A roster of these rows over days marks a past day owed with none missing in the danger tone, counted in the legend; today\'s is due, offered to add and never marked; each row\'s total reads the days it holds of those owed |\n| `scan` | `"text"` \\| `"iso6346"` \\| `"code"` | Its title, a text field, is painted or printed on the thing a row is (a container\'s number, a seal\'s) and read off one photo on a phone, beside each search matching it and each field holding or picking it: `iso6346` a container number, refused unless its check digit holds; `text` as it stands; `code` a barcode or QR code on the thing, decoded on the device from the photo with no agent |\n| `place` | [Place](#place) | Where a row stands, as plain fields of it, drawn as one place where its record draws the address: how sure it is, a press opening it in the device\'s maps, and one taking it from where the device stands |\n| `plan_place` | [Plan place](#plan-place) | Each row is a place on the plan a `plan` register draws: its title the place\'s code, its subtitle a note. A flat list, no tree |\n| `pin` | [Pin](#pin) | Each row is a place on a picture (a snag on a flat\'s plan, a spot on a container\'s drawing): a List of these rows draws the picture its `on` row holds with a numbered pin at each row\'s own place, each row led by its number, the row opened lit on it and a pin pressed opening its row; where the List writes rows, a press on the bare picture adds one there, and a pin dragged moves its row. A List of rows that link to these by a single link draws their places the same way |\n\n#### Cadence\n\n| Key | Type | Meaning |\n|---|---|---|\n| `entity` | text, required | The table owed: each of its rows stands on one row of this table by its single link to it, and on the first date of its line (`records` title or subtitle) |\n| `on` | list of `"mon"` \\| `"tue"` \\| `"wed"` \\| `"thu"` \\| `"fri"` \\| `"sat"` \\| `"sun"` (at least one) \\| alias, required | The days of the week one is owed on: listed (`mon` to `sun`, each once), or a multi-select of this row whose option aliases are `mon` to `sun` |\n| `from` | alias | A date of this row: the first day one is owed (a site breaking ground, a contract\'s start); absent, no first day |\n| `until` | alias | A date of this row: the last day one is owed (a site\'s handover, a contract\'s end); empty or absent, through today |\n| `start` | alias | A `format: "time"` field of this row (a lookup too): the time of day the child\'s first date starts at, where that date holds a moment |\n| `end` | alias | A `format: "time"` field of this row, where the child\'s second date holds a moment: the same day, or the next where it is earlier; or a number field of this row, the days each runs, where the child\'s dates are days (its last day is the first plus the days less one; an empty length leaves the row unplaced) |\n| `planned` | alias | A stored date of the child, by its alias on that table: the day it was made for, kept when it moves. Set by what makes it, and read for what is still owed; state it with the child\'s link in `unique` |\n| `except` | text | A table of closed days: each of its rows closes the days from the first date on its line to the second. Nothing is owed on them |\n\n#### Place\n\n| Key | Type | Meaning |\n|---|---|---|\n| `address` | alias, required | A text field: the address, as people write it |\n| `latitude` | alias, required | A number field: degrees north, negative south |\n| `longitude` | alias, required | A number field: degrees east, negative west |\n| `accuracy` | alias | A number field: how many metres off the device that gave the place said it may be |\n\n#### Pin\n\n| Key | Type | Meaning |\n|---|---|---|\n| `on` | alias, required | A single link of this row to the row whose picture (its `records` `image`) the place is on \u2014 a container\'s drawing, a floor\'s plan |\n| `x` | alias, required | A number field of this row: how far across that picture the place stands, in percent from its left edge |\n| `y` | alias, required | A number field of this row: how far down that picture the place stands, in percent from its top edge |\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `records.scan` | A title read off a photo or a code (`scan`) is a text field the row stores. |\n| `records.cadence` | A `cadence` names each child once \u2014 its rows standing on one row of this entity by their single link and on the first date of their line \u2014 and its `on` lists each day of the week once, or names a multi-select of this entity whose options are all aliased mon to sun. `from` and `until` are two different days of this entity. `start` and `end` are `format: "time"` fields of this entity (a lookup too): `start` where the child\'s first date holds a moment, `end` where its second does, or `end` a number of days where its dates are days. `planned` is a stored date of the child, never its first or second. `except` is an entity whose line holds a date. |\n| `records.place` | A `place` names four different fields of the row: its address a text field, its latitude, longitude and accuracy number fields it stores. |\n| `records.plan_place` | A `plan_place` names `kind` and `reach_from` as single selects, `sheet` as a single select or a one-row link, `stacked` as a boolean and the rest as numbers, each a different field; `kind`, `x`, `y` required. `size` names three numbers (`across`, `along`, `up`) stating one cell in one length `unit` alike. A `sheet` linking to an entity that states an `image` draws that drawing under the places, `scale` (a number field of that entity) its width in cells; `scale` goes with such a `sheet` alone. |\n| `records.pin` | A `pin` names a single link of the row (`on`) to an entity whose `records` states its `image` (a PDF is drawn as its first page), and two different number fields of the row, how far across (`x`) and down (`y`) that picture in percent. A List of rows whose own entity states a `pin` is drawn over that picture; `on`, `x` and `y` are set by the press that adds a row, never asked. |\n\n<!-- generated:end records-places -->\n\n## Status\n\nA record\'s `status` is the stage a row moves through \u2014 a stored single select, each\noption\'s moment the date `dates` names. A record draws it as its dot and word where Act buttons on the page offer its moves, and as a control for the moves no drawn Act offers: choosing one runs its Act, asking and refusing as its button does.\n\n<!-- generated:start status -->\n\n#### Status\n\n| Key | Type | Meaning |\n|---|---|---|\n| `field` | alias, required | The single select that is the row\'s state, its options in the order the work goes through them, drawn as a line of steps on a record page where no Section states `at` |\n| `closed` | list of alias (at least one) | Options that end the work: a register opens on the rows not at them, and the badge reads muted |\n| `dropped` | list of alias (at least one) | Options of `closed` that leave the work undone (cancelled, rejected): whoever holds the row moves it to one from any stage, where every other move forward passes each owned stage between that binds the row (its `when`) and needs each one\'s owner, and a row leaving one enters a stage as a row made there does |\n| `history` | text | A table every write that sets or moves the status appends one row to (its link to this table, the new status, the moment and who) \u2014 by the record write path, whoever writes: for reporting on every move |\n| `dates` | map of alias \u2192 alias | Option alias \u2192 a date field of this entity the record write path stamps with the moment a row moves into that option, or is made at it \u2014 whoever writes. A value the same write states for that field wins, so past data loads as it happened \u2014 and the `history` records the move at that day, a row made at a later option recording each earlier one whose date the write states, in order; the platform never clears a stamp, so each is when the row last entered the option. A stage\'s date is made where none is named |\n| `stages` | map of alias \u2192 [Stage](#stage) | Option alias \u2192 who owns that stage and how long it should take: the owner alone takes a row out of it, by any write, and presses the acts offered there; every move forward past it of a row it binds (its `when`), and every such row made past it, is its owner\'s too. Its days run from the moment its `dates` field holds. In an app the status then moves only by acts that `set` one of its options \u2014 no save writes it and no act asks it |\n\n#### Stage\n\n| Key | Type | Meaning |\n|---|---|---|\n| `owner` | `"field"` \\| `"link.field"` \\| `{ "group": id }`, required | Who owns the stage: a member field of the row, `link.field` read through a one-row link (not at the stage a row opens at, whose owner made the row: a member field of the row itself), or `{ group }`. A member moves a row off only one stage that groups own, one at a time: the next waits on a different member, or on a stage stating no owner; a row made past a stage signs nothing there |\n| `within` | integer | Whole days the stage should take from the moment the row entered it |\n| `when` | map of alias \u2192 (list of alias (at least one) \\| boolean \\| [comparison](#values) \\| `{ "empty": true \\| false }`) | The rows that must pass this stage: a row meeting every entry on its own fields, as it stood before a write or as the write leaves it \u2014 a single select holding one of these options, a yes/no this value, a number or date meeting its bounds, a field empty or filled; a yes/no or a number may be one a formula yields, a number one a rollup counts or sums. Absent, every row must. A row at the stage leaves it by its owner either way |\n\n#### Stage group\n\n| Key | Type | Meaning |\n|---|---|---|\n| `group` | text, required | A group of the workspace, by id: its members press the act. One person moves a row off only one of the stages different groups own |\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `records.status` | A status is one single select, its options in the order the work goes through them, `closed` naming the ones that end it and `dropped` those of them reached from any stage. |\n| `records.history` | A declared status `history` has exactly one link to the row it records, one single select holding every option of the status (or a text), exactly one date and at most one member. |\n| `records.stages` | A stage\'s owner (`status.stages`) is a single member field of the row, one read through a one-row link (never at the stage a row opens at: its owner made the row, so it is a member field of the row itself), or a group, on an option that does not end the work; a group\'s stage needs the status `history` with who moved the row. Every write takes a row off a stage as its owner alone, and moves a row past it or makes a row past it as its owner alone where the stage binds the row (its `when`) \u2014 a move to a `dropped` option excepted, which whoever holds the row makes from any stage; a row leaving a dropped option, or holding none, enters a stage as one made there. Each stage\'s moment, and each open option\'s, is the date its `dates` names, made where none is named, which every write that opens or moves the status stamps; `within` runs from it. In an App a status with stages moves only by Acts that `set` one of its options \u2014 no save writes it or a date it stamps, and no Act asks either, sets it otherwise or writes either from a workflow; an Act moving a row forward past a stage another owner owns, into an option not `dropped`, keeps its `when` off every row that stage binds. |\n| `records.stage-when` | A stage\'s `when` names the rows that must pass it, as an Act\'s `when` holds them \u2014 single selects to their options, yes/nos to `true` or `false`, numbers and dates to bounds, any field to `{ "empty": true \\| false }` \u2014 on fields of the row itself, stored or computed of it \u2014 a yes/no or a number a formula yields, the number a rollup counts or sums: never the status, a lookup or a computed date or select, and never on the stage a row opens at. It binds a row meeting it as it stood before a write or as the write leaves it; absent, it binds every row. |\n\n<!-- generated:end status -->\n\n- **The status** is one single select. `closed` options end the work: a register opens\n on the rows not in them, a row holding no status among them. A `history` table gets one row per move \u2014 its link to this\n table, the new status (a select holding the same option aliases, or text), the\n moment (the stage\'s `dates` value where the write states a past one, so loaded rows keep\n the day they reached it) and who \u2014 appended by the record write path in every write that opens a row at a\n stage or moves it, whoever writes (the member behind the write is its `by`; an automation\n leaves it empty). A `history` the tables do not declare is derived, and needs no\n `records` of its own.\n- **When each step happened** is the date `dates` names for its option, stamped as the row\n enters it, whoever moves it. One way times a status: a straight-line process is a select\n whose options are its steps in order, each with its date \u2014 never a run of dates the stage\n is read off. An Act that moves the stage and `asks` the step\'s date with `starts: "today"`\n lets the reader record a day already past in the same press.\n\n## Write rules\n\nWhat a WRITE of a table\'s rows meets is stated in the table\'s document, where it applies: `min` and\n`max` on a number or date field, `options_where` and `same` on a link, `suggest` on a text field,\nand `no_overlap` and `natural_key` on the table. A key a field\'s type does not take is refused at\nits path, and a document has no `write_rules` key.\nEvery one but `natural_key` and `suggest` holds on every path a record is written by \u2014 the grid, a record\'s form, an import, a workflow, an\nagent, the API, an app \u2014 judged in the write\'s own transaction, every broken rule listed at once; the\nscreen and a picker only mirror them. A row that already breaks one stays editable until a write\ntouches what the rule reads. `natural_key` names the fields an app recognises a row by, to reuse it where an\nadd or a find-or-create meets it; a record tool or the API creates the row it is handed. `suggest` offers\nvalues in a text control and refuses none. An `options_where` link is refused where a write names a row the\nnarrowing does not admit, and every picker of the link offers only the rows it admits.\n\n```json\n{\n "tables": [\n {\n "ref": "customer",\n "label": "Customer",\n "fields": { "email": { "type": "text", "label": "Email", "unique": true } },\n "natural_key": ["email"]\n }\n ]\n}\n```\n\nA customer above is RECOGNISED by their address. An add that names one \u2014 from the customers\nregister or from a picker\'s "new" \u2014 reuses the row it matches and opens one only where nothing does,\nso the book never grows a second Acme.\n\n```json\n{\n "tables": [\n { "ref": "product", "label": "Product", "fields": { "name": { "type": "text", "label": "Name" }, "in_stock": { "type": "number", "label": "In stock" } } },\n {\n "ref": "order",\n "label": "Order",\n "fields": {\n "name": { "type": "text", "label": "Name" },\n "placed_on": { "type": "date", "label": "Placed on" },\n "due_on": { "type": "date", "label": "Due on" },\n "lines": { "type": "link", "label": "Lines", "table": "order_line", "multi": true, "pair": "order" }\n }\n },\n {\n "ref": "order_line",\n "label": "Order line",\n "fields": {\n "name": { "type": "text", "label": "Name" },\n "order": { "type": "link", "label": "Order", "table": "order", "multi": false, "pair": "lines" },\n "quantity": { "type": "number", "label": "Quantity", "min": 1, "max": 9999 },\n "ships_on": { "type": "date", "label": "Ships on", "min": "order.placed_on", "max": "order.due_on" },\n "product": {\n "type": "link",\n "label": "Product",\n "table": "product",\n "multi": false,\n "options_where": {\n "node_type": "group",\n "logic": "and",\n "children": [{ "node_type": "condition", "type": "number", "field_key": "in_stock", "operator": "greater_than", "value": 0 }]\n }\n }\n }\n }\n ]\n}\n```\n\nA line of nothing is not a line: `quantity` is refused on create and on update. A line ships inside\nits order\'s window \u2014 a bound read off the row a link names is judged when the line is written. Nothing is sold off an empty shelf: every picker of `product`\nreads only the rows that answer its `options_where`, and every save refuses the same rows again.\n\n```json\n{\n "tables": [\n {\n "ref": "booking",\n "label": "Booking",\n "fields": {\n "room": { "type": "text", "label": "Room" },\n "state": { "type": "select", "label": "State", "options": [{ "alias": "held", "label": "Held", "color": "blue" }, { "alias": "released", "label": "Released", "color": "gray" }] },\n "starts_on": { "type": "date", "label": "Starts on" },\n "ends_on": { "type": "date", "label": "Ends on", "min": "starts_on" }\n },\n "no_overlap": { "from": "starts_on", "to": "ends_on", "by": ["room"], "while": { "state": ["held"] } }\n }\n ]\n}\n```\n\nOne booking per room at a time, while it is held \u2014 a create or a save whose span overlaps another\nheld booking of the same room is refused.\n\nA table\'s `checks` (the conditions no write of its rows may meet) are stated in its document and hold on every path a record is written by; their keys, what they read and an example are on `workflows/table-checks`. What follows every committed write of its rows is a workflow, written with `set_workflow` (`workflows/table-workflows`).\n\n<!-- generated:start write-rules -->\n\n#### Suggest\n\n| Key | Type | Meaning |\n|---|---|---|\n| `table` | text, required | The table whose text field is offered from: its id, or its `ref` in this call |\n| `field` | alias, required | The alias of that table\'s stored text field; the field\'s control offers, as the reader types, the distinct values it holds, and any text is still written |\n\n#### No overlap\n\n| Key | Type | Meaning |\n|---|---|---|\n| `from` | text, required | The stored date (or datetime), or time of day (a `format: "time"` text field), a row\'s span starts on: `<field alias>` of the row, or `<link alias>.<field alias>` of the one row a one-row link names (a booking line\'s piece held for its booking\'s dates) |\n| `to` | text, required | The stored date (or datetime) a row\'s span ends on, named like `from` and through the same link \u2014 a day it holds, unless `records` names it the day the row `frees`; a moment another row may start at |\n| `by` | list of text (at least one) | Fields two rows share to compete for a span (the same employee, the same room): `<field alias>`, or `<link alias>.<field alias>` of the one row the span is read through. A field holding many values (a multi-select, a link to several rows, several members) competes where two rows share any one; absent, every row |\n| `while` | map of text \u2192 list of alias (at least one) | Only rows at these options of these selects hold their span (running, not closed), the select named like `from` \u2014 `<field alias>` or `<link alias>.<field alias>`; absent, every row |\n\n<!-- generated:end write-rules -->\n\n<!-- generated:start rules-write -->\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `write.natural-key` | A `natural_key` is text or a number a person types back, or a one-row link; a text key is unique \u2014 `unique: true`, or the key\'s fields as a set in the table\'s `unique`. |\n| `write.bounds` | `min` and `max` bound a number, a date or a time of day \u2014 by a constant a number, by a field of this row or of the one row a one-row link names either, of the same type and unit, never by itself \u2014 and `min` is never above `max`. |\n| `write.bound-per-row-unit` | On a figure whose unit or currency is the row\'s own (its notation\'s `per_row`) a constant bound is only 0 \u2014 bound it by a field of the row. |\n| `write.suggest` | `suggest` stands on a stored text field and names a `table` and a `field`, a stored text field of that table; the app reads that table, so it has a `records` entry. |\n| `write.same` | `same` stands on a link and names one-row links, or lookups of one, this table and the link\'s target both hold to one table. |\n| `write.options-where` | `options_where` narrows a link by an `"and"` group of plain conditions over the target\'s own fields \u2014 a number compared in one unit on every row, a select by options it declares. |\n| `write.no-overlap-night` | *Noted, never refused:* `no_overlap` between two times of day reads a span ending at or before its start within its own day: to midnight, then from midnight. |\n| `write.no-overlap-pair` | *Noted, never refused:* A dated table with a link to a person and a link to a resource, and a `no_overlap` by only one of them, lets the other be held twice: name each in a rule, in a list. |\n| `write.no-overlap` | `no_overlap` is a rule, or a list of rules a row must each meet, spanning two date fields or two `format: "time"` fields, the row\'s own or the one row a one-row link names (`booking.start_on`); `by` names values rows share \u2014 a link, a person, a text or a number, an option, a field of the one row the span is read through (`booking.room`), or a field of many values, which competes where two rows share any one; `while` names single selects by their options, the row\'s own or that linked row\'s. |\n\n<!-- generated:end rules-write -->\n\n- A `natural_key` is `text` or `number`, because a person types it back, or a\n one-row link, because a row is also recognised by the one row it belongs with (a\n fee by its visit and its kind). A key holding a `text` field is unique: `unique:\n true` on that field, or the key\'s fields as a set in the table\'s `unique` (a\n site by its customer and its name) \u2014 two rows sharing it would make\n find-or-create pick whichever the read answered first. An add asks the key by\n default.\n- A `same` link names only rows that name what this row names \u2014 a fee\'s invoice\n is one of its own visit\'s \u2014 through a one-row link both tables hold to one\n table; its picker offers nothing until the row names one. A row added under a\n record names what it copies off it (`default_from`) from the start, so a block\n expecting one line per row of the link lists that record\'s rows alone. A save\n of this row moving what the two compare is refused while they would name apart.\n- An `options_where` link may be left empty; a row it names is refused on every\n save that writes the link unless it holds the narrowing, and the refusal names\n the link and the row. A save that leaves the link alone is not judged, so a row\n still naming a row the narrowing no longer admits stays editable. A link naming\n one kind of a book\'s rows (a "Shipping line" among the parties) narrows to that\n kind, or its picker offers every row.\n\nA field\'s own `required` is not here: the field carries it, and every write\npath refuses the row by field name from it. `unique` is the text field\'s own\nclause (`reference/text`) \u2014 an add says so at the control before the column does. A\nfield the workspace writes (a formula, a rollup, a lookup, an autonumber, a date\nwith `derive_from`) is never asked, written or edited.\n\n## App tree\n\nAn app is a tree of components, assembled the way a page is written in JSX: pick a component, bind it to a table by\nname, and it draws well with no props, because its defaults come from the table\'s facts (`reference/records`, `reference/status`,\n`reference/write-rules`, `reference/field`). A prop overrides a default at its own node. No prop says how anything looks: the runtime\ndraws each concept one way, and a screen the job needs that no component states is told to the person \u2014 the job,\nwhat the app drew, the word wanted \u2014 never props bent to approximate it.\n\n**The smallest tree is one root List.** `{ "type": "App", "key": "orders", "name": "Orders", "children": [{ "type": "List", "entity": "order" }] }`\nis a whole app: the platform composes the rest from the tables and stores it \u2014 the page every row opens, a Section per stage with its moves\nat the foot, a child List per child, the add and the Delete \u2014 and draws the band of readings. What the platform composed beyond what you stated, the answer of `set_app` names (`scaffolded`) and says what it placed or folded in what you stated, so you state only\nthe difference. Lists at the root stand beside one another, two over one entity opening its one page.\n\nEach component is a page of its own: `reference/app-node`, `reference/list-node`, `reference/list-source`, `reference/list-over-a-query`, `reference/list-over-a-query-in-a-record`, `reference/record-node`, `reference/section-node`,\n`reference/steps-node`, `reference/side-node`, `reference/outside-node`, `reference/tab-node`, `reference/sheet-node`, `reference/field-node`, `reference/fieldset-node`, `reference/line-node`, `reference/value-node`, `reference/act-node`, `reference/check-node`,\n`reference/reading-node`, `reference/statement-node`, `reference/comments-node`, `reference/export-node`,\n`reference/query-node` and `reference/workflow-node`. Beside them: `reference/changing-an-app` and `reference/what-an-app-may-write`, `reference/layouts`, `reference/time-layouts`, `reference/plan-layout` and\n`reference/publish-desk` for a List\'s `layout`, `reference/tasks`, and the rules, `reference/app-rules`,\n`reference/reading-rules`, `reference/statement-rules`, `reference/check-rules`, `reference/list-rules`, `reference/record-rules`, `reference/act-rules` and `reference/template-rules`.\n\n<!-- generated:start app-components -->\n\n| Component | Draws | Holds |\n|---|---|---|\n| [App](#app-node) | the launcher tile, the app\'s words, its Views (Lists and Sheets), and its API | List, Sheet, Query, Workflow, Record |\n| [List](#list-node) | rows of an entity: the register, a record\'s child rows, a roster\'s cells, related rows | Tab, Reading, Export, Act, List |\n| [Record](#record-node) | what a row opens: the head and the parts | List, Field, Fieldset, Section, Steps, Side, Outside, Reading, Statement, Comments, Act, Check |\n| [Section](#section-node) | a titled part of a record | List, Field, Fieldset, Reading, Statement, Comments, Act, Check |\n| [Steps](#steps-node) | a record\'s path down the page: one step per Section, the fields, blocks and acts of a stage under its step | Section |\n| [Side](#side-node) | the part the rest is worked from, beside them | List, Field, Fieldset, Reading, Statement, Comments, Act, Check |\n| [Outside](#outside-node) | what one record shows, and which acts it allows, to a person with no seat who opens a link a member made of it | Field, List, Act |\n| [Tab](#tab-node) | one view of a List\'s rows over a period | \u2014 |\n| [Sheet](#sheet-node) | a grid of Readings and Lists over the App\'s rows in its period | Reading, List |\n| [Field](#field-node) | one field: a control, a gallery, prose, a link and its picker, the rows filed under a back-link | \u2014 |\n| [Fieldset](#fieldset-node) | fields of a part read together under a heading of their own, or as Lines of cells the author arranges | Field, Act, Line |\n| [Line](#line-node) | one line of a Fieldset: Fields, Acts and Values in the order stated, after its own label | Field, Act, Value |\n| [Value](#value-node) | a figure worked out on the screen from fields of the record, never stored | \u2014 |\n| [Act](#act-node) | a verb: what pressing it does | \u2014 |\n| [Check](#check-node) | an issue the table declares that refuses the writes and acts it names, or names the act that clears it | \u2014 |\n| [Reading](#reading-node) | a number over rows: one figure, its parts, a grid, per period, steps; or a record\'s own figure; with `planned` and `done`, the work against its plan, day by day | \u2014 |\n| [Statement](#statement-node) | a figure built from figures of the record | \u2014 |\n| [Comments](#comments-node) | the record\'s comment thread, with a box to write one | \u2014 |\n| [Export](#export-node) | a report file of the rows in view | \u2014 |\n| [Query](#query-node) | nothing: a read for agents | \u2014 |\n| [Workflow](#workflow-node) | nothing: a verb for agents | \u2014 |\n\n<!-- generated:end app-components -->\n\n### A node\n\nA node is `{ "type": <Component>, "key"?, ...props, "children"?: [...] }`. `type` names the component, `key` its\nname among its siblings, the other keys its props, `children` the nodes it holds. An unknown prop is refused.\n\n- **Two shorthands, both for Field.** A bare string child is a Field (`"due_date"`); an object with `field` and no\n `type` is a Field with props (`{ "field": "price", "edit": false }`). Both work in every prop that lists fields:\n `create`, a Record\'s `row.subtitle` and `add`, and the `children` of a Record or a part. A column is a field\'s alias, or\n `{ "field", "edit": true }` for the line\'s own control, and takes no other prop.\n- **Fields and options are named by alias**, never by label. A tagged value is an object, never a magic string.\n- **`false` turns a default off at its node:** `"edit": false` makes a field read-only, `"create": false` and\n `"remove": false` take a List\'s add and Delete away, `"readings": false` its band; on a Record, `"row": { "figure": false }`\n drops the row\'s figure, `"row": { "status": { "edit": false } }` the status buttons (another app moves the stage) and\n `"row": { "image": false }` the picture.\n\n### Keys and addresses\n\nA key is unique among its siblings, the way a React key is. A node that binds data takes its key from what it binds:\n\n| Node | Key when none is stated |\n|---|---|\n| Field, Check | its field alias |\n| List | its entity alias |\n| Record | its `entity` alias |\n\nEvery other node states its key. Three kinds of key are unique across the whole app, because each is an API name:\nan Act\'s (its workflow is `act_<key>`, or the one it names), a Reading\'s (its query name for `run_app_query`), and a Query\'s or\nWorkflow\'s.\n\nA node\'s **address** is the path of keys from the app, such as `pages/customer/orders`; the app itself is `/` (the `in` of a node at the root), and its own key is part of no address. A patch may use any ending\nof that path that names exactly one node (`orders`). The exact path wins where one exists; an ending naming two\nnodes is refused, and the refusal lists both paths. `get_app` prints the tree with each node\'s address.\n\n### Values\n\n| Value | Written |\n|---|---|\n| now, the reader, an asked input | `{ "now": true }`, `{ "me": true }`, `{ "input": "name" }` |\n| a computed value | `{ "formula": "{cost} * 1.2" }` over the acted row\'s fields |\n| a call\'s own value, in a Query | `{ "param": "name" }` |\n| cleared | `null` in an Act\'s `set` |\n| an option | its alias |\n\nA **condition** (`when`) maps a select to a list of its option aliases and a yes/no to `true` or `false`; every entry\nholds. A number (a number, currency or percent field, or a formula or rollup yielding one) takes a comparison with any\nof `gt`, `gte`, `lt`, `lte` (at least one, never both `gt` and `gte` or both `lt` and `lte`), each a number; a date\ntakes the same keys with a day (`"2026-03-01"`), a moment on a datetime (`"2026-03-01T09:30"`) or `{ "now": true }`\n\u2014 today, or the current minute on a datetime, read when the rows are, so overdue is `{ "due_on": { "lt": { "now": true } } }`;\nand any field but a yes/no takes `{ "empty": true }` or `{ "empty": false }`. A comparison on a field it does not fit is\nrefused, naming the field, its type and what it takes. A `when` on an Act, a Section or other block, and a List\'s `where`\n(the register\'s or a child List\'s) take these; a child List that adds, picks or expects rows refuses a comparison in its\n`where`, since a row it holds could stand outside it. A **narrowing** (`opens`, a Reading\'s, a Tab\'s or an Export\'s `where`) takes these and also `{ "me": true }` on a member\nfield or a lookup of one, the reader; `where` on a root List or a record\'s child rows fixes the rows on the server for every reader, so it refuses\n`{ "me": true }` \u2014 open on it with `opens`; on a record\'s related rows (`same`, `app`) and on a Sheet\'s List it\nnarrows by the reader and takes it, and those two take no comparison.\n\n## Changing an app\n\n1. `get_workspace` with `kind: "app"` names the app. `get_app` prints the `tree:`, the `node addresses:` (the address of\n each node the app draws, `(default)` on those the tree leaves to the platform) and the `version` line, whose id is the `base_version_id` to send. A member who is not the\n app\'s author is shown no tree. Keep the tree: no tool reads an earlier one.\n2. `set_app` with `app_id`, `base_version_id` (that version: a newer write is refused, not overwritten) and `nodes`,\n (a refused change writes nothing, so `dry_run` is for reading the permissions it would grant and remove). Every answer\n states the permissions the change grants and removes.\n3. `screenshot_app` shows the result.\n\n`nodes` maps an address to a patch of that node. Read against the customers List and page of the account review (`reference/a-complete-workspace`), the call below makes `tier` read-only, moves the Orders Section ahead of Account, adds an Act to\nAccount and removes the Reading:\n\n```json\n{\n "type": "App",\n "key": "account_review",\n "name": "Account review",\n "children": [{ "type": "List", "entity": "customer", "children": [{ "type": "Reading", "key": "ordered_by_tier", "by": "tier", "value": "total_ordered" }] }],\n "pages": [\n {\n "type": "Record",\n "entity": "customer",\n "children": [\n { "type": "Section", "key": "account", "title": "Account", "children": ["tier"] },\n { "type": "Section", "key": "orders", "title": "Orders", "children": [{ "type": "List", "entity": "order" }] }\n ]\n }\n ]\n}\n```\n\n```json\n{\n "app_id": "<id of the app>",\n "base_version_id": "<current_version_id>",\n "nodes": {\n "tier": { "edit": false },\n "orders": { "before": "account" },\n "mark_gold": { "type": "Act", "in": "account", "label": "Make gold", "when": { "tier": ["standard"] }, "set": { "tier": "gold" } },\n "ordered_by_tier": null\n }\n}\n```\n\nEach entry applies in order:\n\n- **An existing node:** a JSON merge patch (RFC 7396) of its props; `null` drops a prop, and a list (`children`,\n `columns`) replaces the node\'s whole, as `layout` does: a patch states the whole layout.\n- **`null`:** removes the node and everything under it.\n- **An address naming no node, with `type`:** adds a node into the node its path names (`"pages/<entity>": { "type":\n "Record", \u2026 }` adds a Record page), or, for a bare key, into the node `in` names (`/` the app); its key is the\n address\'s last word, and a Field states `field` in place of `type`.\n- **`in`, `before`, `after`:** move a node into another, or ahead of or behind a sibling.\n\nThe app\'s own props (`name`, `description`, `icon`, `color`, `words`, `scope`, `period`) change\nthrough `body`, a merge patch over the App node. `dry_run` checks a change and writes nothing.\n\n| To change | State |\n|---|---|\n| a field read-only | `"edit": false` on its Field, or on the Section, Side or Record that draws it |\n| a column added or dropped | `columns` of the List, every column kept: a List that never stated `columns` draws none beyond the row\'s title and its `records` line |\n| a button | an Act node (`reference/act-node`); `confirm` makes its press ask first |\n| a label | the table\'s field `label` in `set_tables`, for every app; for this app alone, `body: { "words": { "<table>": { "fields": { "fee": "Consultation" }, "options": { "urgency": { "rush": "Same day" } } } } }`; a List\'s `label`, a Section\'s `title`, an Act\'s `label`, `add_label` on the add. A Field\'s `label` heads only a gallery or prose block |\n| the order of nodes and rows | `before` or `after` a sibling, or `in` another parent, in the node\'s entry (a Section ahead of another, a Field ahead of another in its Section); a List\'s `columns` read in the order stated; its rows read in its `sort`: `{ "sort": { "field": "collected_on", "desc": true } }` |\n| the row\'s second line | `row: { "subtitle": ["mechanic"] }` on the List: up to two fields under the title, in place of the table\'s `records` line, which stays as it is |\n| a picker\'s add | `add` on the linked table\'s page: `{ "type": "Record", "entity": "pet", "add": ["species", "microchip"] }` asks those fields of the new row; absent, the picker only picks. It holds in every picker of that table in the app |\n| a linked row fixed or deleted where its link stands | the linked table\'s page in `pages`: the link\'s card opens the row in the drawer as that page draws it, saving what it writes, with a Delete where it states `remove: true`. A table a List of the app draws is worked in that List |\n| a headline figure | a Reading in the List: `{ "type": "Reading", "in": "orders", "label": "Prepaid owed", "value": "prepaid", "where": { "stage": ["awaiting_payment"] } }` sums the rows in view; without a `value` it counts them |\n| a calendar and its date | `layout: { "calendar": { "date": "pickup_on" } }` on the List, with `end` for the date a row runs to (both days or both moments); the bare `"calendar"` takes them from the rows\' facts and is refused, naming `date`, where those name none |\n| a record\'s child lines | a List inside the Record\'s Section over the child table: `{ "type": "List", "in": "details", "entity": "repair_line" }`; the child table (one link back to the record) and the record\'s rollup over its rows come from `set_tables` first. Lines priced off a book: `docs path="design/treatments/moves-and-numbers/priced-lines"` |\n\n**What a write stores.** A write stores the pages, platform parts, steps and child Lists the platform composed, and its answer\'s `scaffolded` names each by its path from the root; they are ordinary nodes: edit one, or remove a part, a step or a child List and it stays removed. A page is composed again while a List still opens it; a patch removing the List that alone opened a page takes the page with it where the platform composed all of it (the answer\'s notes say so), and is refused where the page holds what you stated. A Section stating no `children` and no `at` is the platform\'s part of its Record and follows the table: a field the table gains appears in it, while a new child table or stage is yours to add. A Record stating no `children` is composed again. `get_app` marks `(default)` the nodes still left to the platform (the status buttons, the band of readings); patch one by its address and the call states it first: the nearest node the tree does state gains the default child that leads to it, as drawn (every status button of the app, every reading of the band, since stating one stands the others down), then the patch applies. Removing every reading, or every status button, is refused: only `readings: false` on the List or `row.status: { "edit": false }` on the Record draws none. **A stated subtree stays as it is**: a field or option the tables gain later is not added to it, so name it in the tree. An address that ends several drawn nodes is refused, as for stated ones.\n\n**A write places what has one fix, and says so.** The stored tree is the placed one, `get_app` shows it, and the answer lists\neach placement at its address, so you read the difference instead of meeting a refusal:\n\n- `where: { "<field>": { "me": true } }` on a root List moves to `opens`, the chip that names the reader. A child List\n keeps the refusal: bound access with a row rule, or list the rows in a root List.\n- A read-only repeat of a field across a record\'s steps, or a Field beside the files or text block that draws it, is left\n out and said; the statement stays in the tree.\n- `door` on the page of an entity no root List and no Sheet\'s List is over, where the page states no Side, is\n not drawn and is said: its rows open in place. It stays stated, and applies once one of those or a root List does.\n\n## What an app may write\n\nAn app states no list of what it writes: the tree derives it, and the generated workflows accept exactly that, so it is\nalso what an agent can do through the app\'s API. `get_app` prints it beside the tree.\n\n1. **A save of field `f` of table `E`** exists when a node draws `f` on a page of `E`\'s rows (a Field in a Record,\n Section or Side, or a part of the head), the table lets a person write it (stored; not computed, stamped or the\n back side of a child\'s link), no Act of the app on `E`\'s rows writes it, and neither the node nor a container above it\n says `edit: false`. A row\'s stage is moved by an Act or the one button per move a status no Act moves gets, by hand only where its Record\'s `row.status` says `{ "edit": true }`, and by none where it says `{ "edit": false }`.\n2. **An add of `E`** exists for a List over `E` that writes its rows unless it says `create: false` (asking what it lists, and\n setting the link back to the record itself), and for every picker of `E` where `E`\'s page states `add`. An absent `create`\n stands down where the table states no `singular` (nor the app\'s `words`), or where `where` keeps a select at an option an\n Act sets other than the one a new row starts at; a stated `create` list over such a table is refused. A roster\'s cells and\n a document are added only where `create: true`.\n3. **A Delete of `E`** exists for a List over `E` unless it says `remove: false`, and for the table of each of that\n List\'s `sources` (a source has no `remove` of its own). A roster\'s cells, a document and a desk\'s rows are deleted only where `remove: true`.\n A Delete comes with `restore_<entity>`, which brings the row back with the rows its delete took, all or none.\n `remove: false` takes this app\'s Delete away and no more: the record tools, the API and other apps still delete. A row no\n surface may delete is a table check with `on: ["delete"]`.\n4. **An act** exists for each Act node. Every field it sets, asks, files into, signs or records is the act\'s, and read-only\n everywhere else in the app.\n5. **The table\'s contract holds on every path** and is not restated here: required, unique, no overlap, field rules, table\n checks, stage owners, history and the read scope. (`natural_key` is read by an app\'s add and find-or-create alone.)\n\nDrawing is reading or saving; a List that writes its rows also adds and deletes them, until it says `create: false` or `remove: false`, and a List below a part or a Record that says `edit: false` writes, adds and deletes none.\n\n### What a table gives a component\n\n| Table fact | Feeds |\n|---|---|\n| The title | every row\'s name: Lists, a Record\'s head, link chips, pickers, an add |\n| The row\'s line (`records` subtitle, figure, image, mark, party, description) | the row\'s line and head, cards, a checklist\'s photo |\n| The stage (`records` status) | the stage chips, a List\'s `opens`, the badge, an Act\'s moves, stage owners gating acts, a step\'s `at` |\n| Deadlines (`records` due, settled, frees) | countdowns and overdue marks, the default sort, attention order, spans on lanes, calendars and rosters |\n| Bounds (`records` limits, gates, tolerance) | the figure\'s meter, wherever it stands |\n| Tasks and cadence (`records` task, cadence) | the ring on task rows, a roster\'s owed days |\n| Applicability and starts (`records` applies, starts) | a field shown and asked only where it applies; an add\'s starting values |\n| A field\'s `required`, `default`, `default_from`, `natural_key`, `unique` | what an add asks, and what it starts at |\n| A field\'s `notation`, `format`, options, `options_where` | money, units, chips, and what a picker offers |\n| The table\'s `read_scope` | which rows each reader reads, in every List |\n\n### Where the rules stand\n\n`reference/app-rules` and the rule pages after it are every rule the check holds over an app, by id, whichever component it concerns. A\n**language** is decided by the app\'s own words: a tree names no locale, so what an app draws itself (its buttons, empty\nstates, refusals) is in the language its labels are written in, and `words` count as labels. Mix two languages in one\napp and it answers in two.\n\n## App node\n\nAn app draws its launcher tile, its words, its Views and its API. It binds the tables it names: `set_app` fills\n`tables` with the id of every table alias the tree uses, and `templates` with that of every document template alias.\nA relabel on either side is a rename and no tree points at another table by accident.\n\n<!-- generated:start node-app -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `key` | alias, required | The app\'s alias, its name among apps; the App node is addressed `/`, and no address in it starts with this key |\n| `name` | text, required | The job, in the words of the people who do it |\n| `description` | text | What the job is for, in a sentence |\n| `icon` | text | A Lucide icon name in kebab-case the launcher tile draws; absent, the tile draws the one glyph every app without an icon shares |\n| `color` | [colour](#select) | The launcher tile\'s colour |\n| `words` | map of alias \u2192 [Table labels](#table-labels) | A table \u2192 the words this app draws for it |\n| `scope` | alias | The table whose one row the app works inside \u2014 the folder: every List over a table holding a one-row link to it lists the open folder\'s rows and files each add under it; absent, the app reads every row |\n| `folders` | alias | The key of a root List over the table `scope` names: it draws the folders the app opens on \u2014 its columns, filters, grouping, order and summary \u2014 and a row pressed is the folder entered; absent, the folders are listed by their anatomy |\n| `rows` | map of alias \u2192 [Read scope rule](#read-scope-rule) | Each table\'s row rule in this app, by its alias (a table the app only reaches, by the table\'s own alias): who of the people the app is shared with reads which rows, on its screens, its queries, its writes and its workflows. A table the app states none of is read whole by everyone it is shared with |\n| `uses` | list of alias (at least one) | Tables the app\'s Query and Workflow nodes read without drawing them, by alias: they join the tables the app reaches, so a workflow may name them |\n| `period` | `"today"` \\| `"tomorrow"` \\| `"week"` \\| `"month"` \\| `"quarter"` \\| `"year"` \\| [Period days](#period-days) | The window every Sheet opens on: "today", "tomorrow", "week", "month", "quarter", "year" or { "days": n }; absent, the calendar month |\n| `tables` | map of alias \u2192 text | The id of each table the tree names, by its alias: filled by set_app, never written |\n| `templates` | map of alias \u2192 text | The id of each document template the tree names, by its alias: filled by set_app, never written |\n| `children` | list of ([List over a Query](#list-over-a-query) \\| [List](#list-node) \\| [Sheet](#sheet-node) \\| [Query](#query-node) \\| [Workflow](#workflow-node)) (at least one) | The App\'s Views in order \u2014 Lists and Sheets, the first where the App opens \u2014 and its Queries and Workflows. Queries and Workflows alone: an API app, which a server calls with an app key |\n| `pages` | list of [Record](#record-node) (at least one) | The page the rows of an entity open, one per entity, each a Record stating its `entity`; every List over the entity, anywhere in the App, opens it, and a link\'s row no List lists. Absent, the platform draws the page |\n\n#### Table labels\n\n| Key | Type | Meaning |\n|---|---|---|\n| `label` | text | The table\'s name in the plural (a register\'s heading, a block\'s, a link\'s picker) |\n| `singular` | text | One row of the table, as the add and empty sentences name it |\n| `fields` | map of alias \u2192 text | A field alias \u2192 the words this app draws wherever it names the field; the table\'s field keeps its own label |\n| `options` | map of alias \u2192 map of alias \u2192 text | A select field alias \u2192 option alias \u2192 its words |\n\n<!-- generated:end node-app -->\n\n- **Every View at the root is a peer**: a List or a Sheet, in the order stated, the first where the App opens and the\n others each one entry of the App\'s lists, picked under its title, each at its own address: the first at the app\'s root (`/`), any other at `/<key>`, inside the folder where the App is scoped. A List states\n its `label`, any layout, its own Tabs, Readings and Exports, and may read `sources`; two may stand over one entity, and\n both open its one page. Whoever the app is shared with is shown every View, each table narrowed by the App\'s `rows`.\n A list people work every day as a desk of their own is another app.\n- **A Sheet** draws Readings and read-only Lists over the App\'s rows. The App\'s one `period` windows every reading of\n its Sheets placed in time: the calendar month by default, or `today`, `tomorrow`, `week`, `quarter`, `year` or `{ "days": n }`. An App of Sheets alone\n draws the pages its Sheets\' Lists open (a List naming no `app`), each from `pages` as any page is. A Sheet\'s List\n naming no `app` opens its row\'s page in this app, in the drawer over the Sheet, at `/<sheet key>/<row>`.\n- **Query and Workflow** nodes stand at the root and are never drawn.\n- **Writes:** nothing itself.\n\n## List node\n\nA List draws rows of one table. What its rows are depends on where it stands:\n\n- at the App root: a register, a View of its own among the App\'s;\n- under a Record, Section or Side: the record\'s child rows, filed through the child\'s one link to the record\n (`via` where it has several);\n- under a roster List: the rows that fill the roster\'s cells;\n- with `same` or `app`, or on a Sheet: related rows, read only.\n\nA List below a row\'s page is a View too: it takes Tabs, Readings and Exports as a root List does, and its rows open at\n`/<view>/<row>/<key>`, drawn alone with its band, its way back the row\'s page. An Export of it is the file of that one\nrow\'s rows.\n\n<!-- generated:start node-list -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `key` | alias | Names the List among its siblings and in a Query\'s `list`; absent, the entity alias |\n| `entity` | alias, required | The table whose rows the List draws |\n| `sources` | list of [List source](#list-source) (at least one) | Further tables read as one List with this entity |\n| `source_column` | `false` | Reads a List\'s tables as one: false, no column naming each row\'s table and no filter by it; absent, a List with `sources` draws both |\n| `scope` | alias | Says which folder a row files in: with the App\'s `scope`, the one-row link, where the table holds several |\n| `via` | alias \\| text | The link that files the child\'s rows under the record; absent, the child\'s one link to it; a List that only reads may state `<link>.<link>`, reaching the record through a row of their own |\n| `same` | alias | A one-row link of the record: the rows sharing its row, the record left out, read only |\n| `where` | [narrowing](#app-tree) | A fixed narrowing on the server, for every reader: a condition (`reference/values`), and `<link>.<field>`, the rows whose one-row link names a row holding a select or yes/no so. A List that only reads (`same`, a Record with `edit: false`) also bounds a date or number by a field of the record, `{ "record": "<field>" }`: blank, it keeps no row; an Act\'s paper naming the List is handed the same rows; it is never an access bound, which the table\'s row rules are. An add holds only a select\'s option and a yes/no\'s value |\n| `expect` | alias \\| [Expect](#expect) | What a record should hold, shown before it does: one line per option of this select, or per row of this catalog link |\n| `under` | alias | Groups lines by the document covering them: a one-row link to it |\n| `covers` | integer | With a roster\'s cells over days: how many rows each day needs across every lane; a day holding fewer is marked Uncovered. Absent, no day is expected to hold any |\n| `edit` | `false` | Shows rows nobody changes here: false, this List only reads them |\n| `label` | text | The register\'s name in the app\'s lists and tab strip; absent, the entity\'s label. Never the noun of its rows, which is the table\'s label and singular (this app\'s `words`) |\n| `columns` | list of (alias \\| [Edit column](#edit-column)) | Fields read after the row\'s title, each drawn though no row holds it; `{ field, edit: true }` is the line\'s own control, at most 2. Absent: the title and the `records` line alone |\n| `filters` | list of (alias \\| [Tiered filter](#tiered-filter) \\| [Listed filter](#listed-filter)) (at most 8) | Fields the reader narrows by every day, beside the stage chips, at most 3 \u2014 a List drawn whole, as a plan is, at most 8, each a choice of what colours its boxes: a select, member, link, date, yes/no or number range of a field its rows draw (a column, the title, the line), never one drawn nowhere; a Reading\'s narrowing names the same; `tiers` bands a number or date; `values` states which values a pick lists |\n| `search` | list of alias (at least one) \\| `false` | Fields the search box reads; absent, every word of the row; false, no search box |\n| `group` | alias \\| `false` | A field the rows stand grouped by, a gantt drawing the groups as its lanes, a lanes board of days its cards\' sub-headings inside each lane; absent, the reader may group by a filter\'s field, a lanes board\'s reader none; false, no grouping |\n| `sort` | [Sort key](#sort-key) \\| list of [Sort key](#sort-key) (at least one) | The rows\' order; absent, a register reads newest made first, a record\'s rows as added |\n| `opens` | [narrowing](#app-tree) | The view the register opens on, a chip the reader may take away: `where`\'s entries but a record bound, and `{ "me": true }` on a member field or a lookup of one |\n| `period` | `"today"` \\| `"tomorrow"` \\| `"week"` \\| `"month"` \\| `"quarter"` \\| `"year"` \\| [Period days](#period-days) | The window a table\'s or cards\' dated Tabs read, or the day, week or month a calendar or lanes board opens on: "today", "tomorrow", "week", "month", "quarter", "year" or { "days": n }; absent, this month |\n| `chips` | `false` | The line\'s one chip row, the stage chips: false, none \u2014 the List then holds every row at every stage, and a filter on the status picks among its options. A root List without `sources` whose `where` keeps the status at one option draws none, unless its `opens` names the status |\n| `checks` | `false` | The filter picking among the Checks its rows hold, each with how many hold it: false, none |\n| `attention` | `false` | Keeps a list in its own order: false, the sort menu offers no attention-first order |\n| `readings` | `false` | Leaves a list without figures above it: false, no band; absent, rows that move, fall due or carry money lead with one. Never with Readings stated |\n| `layout` | [layout](#layouts) | A word, or an object stating one layout with its data; absent, a table |\n| `beside` | `true` | Keeps the list in view while a row is worked: true, a row pressed opens beside this table; a root List drawn as a table. Absent, the page\'s `door` |\n| `compare` | [Compare](#compare) | Each row\'s before against its after: two files fields as a pair of photos, or two values of one type as one column |\n| `current` | alias | A child List of revisions: the child\'s date or number field ordering them. The latest reads as current, the others fold under "superseded \xB7 N"; the record shows the current file through a lookup of the child ordered by it |\n| `create` | boolean \\| list of alias (at least one) | The fields an add asks; `false`: rows are not added here. Absent: where this List writes its rows, the table\'s required fields, natural key and title; nothing where the table states no `singular` (nor the app\'s `words`), or `where` keeps a select at an option an Act sets other than the one a new row starts at. A roster\'s cells and a document add only where `true` |\n| `add_label` | text | The add button\'s words; absent, the platform\'s word and the singular |\n| `remove` | boolean | Rows offer a Delete. Absent: where this List writes its rows; `false`: this app\'s Delete alone is gone, and a row no surface may delete is a table check with `on: ["delete"]`. A roster\'s cells, a document and a desk\'s rows delete only where `true` |\n| `pick` | `true` | Also picks rows of the child that no record holds yet |\n| `when` | [condition](#app-tree) | Drawn only while this holds |\n| `children` | list of ([Tab](#tab-node) \\| [Reading](#reading-node) \\| [Export](#export-node) \\| [Act](#act-node) \\| [List](#list-node)) (at least one) | Its Tabs, band Readings, Exports and Acts over ticked rows or every row in view; under a roster the List of its cells, with `under` the List of its documents. An Act on one row and every Check stand in `pages/<entity>` |\n\n#### Edit column\n\n| Key | Type | Meaning |\n|---|---|---|\n| `field` | alias, required | The column\'s field |\n| `edit` | `true`, required | Lets a person change the value on the line: true, its own control, written in place |\n\n#### Expect\n\n| Key | Type | Meaning |\n|---|---|---|\n| `field` | alias, required | The child\'s title, one row per value: a single select or a one-row link to a catalog |\n| `of` | alias | Lets each record choose its lines: with a select, the record\'s own multi-select naming the options it expects, in place of every option |\n| `only` | list of alias (at least one) | Holds lines for some options alone: with a select, those options; never with `of` |\n\n#### Compare\n\n| Key | Type | Meaning |\n|---|---|---|\n| `before` | alias, required | The rows\' field holding what stood before: files, text, a number, a date or a single select |\n| `after` | alias, required | A field of the same type holding what stands after |\n| `edit` | `true` | The after is written on the line |\n\n#### Tiered filter\n\n| Key | Type | Meaning |\n|---|---|---|\n| `field` | alias, required | A number \u2014 stored, or a formula or rollup reading one \u2014 in one unit for every row |\n| `tiers` | list of number (at least one), required | The breakpoints between its bands, ascending, in the field\'s stored unit: under the first, from each to the next, from the last up \u2014 each band worded in the field\'s notation; a filter picks several at once |\n\n#### Listed filter\n\n| Key | Type | Meaning |\n|---|---|---|\n| `field` | alias, required | A select, member or link field |\n| `values` | `"all"` \\| `"held"`, required | The values its menu lists: all, every option, person or linked row, those no row holds at 0; held, only those the rows hold. A bare field lists a select\'s every option, a member\'s or link\'s held |\n\n#### Sort key\n\n| Key | Type | Meaning |\n|---|---|---|\n| `field` | alias, required | The field rows are ordered by |\n| `desc` | boolean | Latest or largest first; absent or false, soonest or smallest first |\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `list.scope` | With the App\'s `scope`, a List over a table holding one one-row link to the folder\'s table is filed in the open folder by it, and one holding several names it in `scope`; that link is required. A List over the folder\'s own table states no `scope`. |\n| `list.unscoped` | *Noted, never refused:* In an App that states `scope`, a List over a table holding no one-row link to the folder\'s table lists every row, in every folder; so does a Tab\'s totals over a child holding no single link to it. |\n\n<!-- generated:end node-list -->\n\nA List takes only the props its place lists:\n\n<!-- generated:start list-places -->\n\n| A List standing in | Takes |\n|---|---|\n| every List | `key`, `entity` |\n| every List on a record | `via`, `label`, `when`, `filters`, `search`, `group`, `sort`, `chips`, `checks`, `opens`, `period`, `attention`, `readings` |\n| a root List (the first is the register) | `label`, `columns`, `filters`, `search`, `group`, `sort`, `chips`, `checks`, `opens`, `period`, `attention`, `layout`, `beside`, `create`, `add_label`, `remove`, `readings`, `where`, `edit`, `sources`, `source_column`, `scope` |\n| a record\'s child rows, as cards, a table, a checklist, a desk or a gantt (cards refuse `under`, `compare`, `current`, `expect`, an `edit: true` column and rows that nest as an outline; a table refuses a `compare` of photos; a gantt refuses `under`, `pick`, `compare`, `current`, `expect` and an `edit: true` column) | `columns`, `create`, `add_label`, `where`, `under`, `remove`, `pick`, `layout`, `compare`, `current`, `expect` |\n| a record\'s child rows with `layout` an agenda | `columns`, `create`, `add_label`, `remove`, `layout`, `edit` |\n| a record\'s child rows with `layout` `"timeline"` | `create`, `add_label`, `remove`, `layout`, `edit` |\n| a record\'s related rows, read only (`same`, or a Record that is `edit: false`) | `where`, `columns`, `same`, `edit` |\n| the documents a child List\'s lines stand under (`under`), a List inside it | `create`, `remove` |\n| the cells of a roster, a List inside it | `expect`, `covers`, `create`, `remove` |\n| a Sheet\'s list, read only | `label`, `where`, `columns`, `sort` |\n\n<!-- generated:end list-places -->\n\n- **The page a child List\'s rows open** is the entity\'s page in `pages`: its Fields in stated order, those the rows\' saves write editable, and the List\'s `columns` are the line. A row opens in place under itself: its fields or Sections, then each List of its own children, at any depth; one row is open at a time. Every row of a List that adds rows offers "Duplicate" in its \u22EF: the add opens with the row\'s values of the List\'s `create` fields, filed under the row\'s own parent (in an outline, the row above it), never carrying a status, a computed value or files. With `edit: false` the List reads as a related-rows List does.\n- **Documents:** in a child List with `under`, a List over the document\'s table (`key`, `entity`, `create`, `remove`,\n Acts and Checks; the document\'s Fields and Lists stand in its page) is the one place the documents are added or deleted;\n `create` states `true`, and `remove` needs `create: true` beside it.\n- **Writes:** a layout move (a gantt bar, a lane\'s block, a plan\'s item) writes only fields the app already writes on the row\'s page.\n- **`create` asks:** `true` asks the title, the natural key and every required field a person writes, never a computed\n or stamped field or the link the place sets. An `expect` list also asks the key it makes its lines by, and their picture.\n- **`filters`:** a threshold the business names ("large orders") is a formula yes/no, and bands it names (new, warm, cold) a formula with options, never a range.\n- **`opens`** absent, the register opens on the open work (rows not at a `closed` stage).\n- **`expect`:** an empty line adds its row (a checklist of papers per case).\n\n## List source\n\nSources are further tables a root List reads beside its entity as one List: the same job kept in tables of their own (a legacy ledger, a second branch\'s register). Each is projected onto the List\'s fields \u2014 by alias, else by its `fields` (the List\'s field \u2192 the source\'s) \u2014 and options line up by alias; its `where` narrows its own rows. Each row opens its own table\'s page in `pages`, stated or refused (`list.source-page`), and runs the Acts and Checks that page states: nothing the List offers its own rows reaches a source\'s. The add offers each table, asking the List\'s `create` in that table\'s fields; a source lacking one adds no row. A column naming each row\'s table, and a filter by it, draw by default; `source_column: false` hides both. Every source holds the title and the scope, and may hold no stage (its rows wear none and stand in no stage chip); its `columns` name value fields of its own table (not links or files) drawn on its rows alone, on a lanes board only; a table, cards, lanes or a plan reads sources, and an Export\'s `sources` makes a report of some of them.\n\n<!-- generated:start node-list-source -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `entity` | alias, required | A further table this List reads beside its own entity: the same job over its rows |\n| `fields` | map of alias \u2192 alias | A field of the List\'s entity \u2192 this table\'s field holding the same fact, where their aliases differ |\n| `where` | [narrowing](#app-tree) | Which of this table\'s rows the List reads |\n| `columns` | list of alias (at least one) | Fields of this table with no counterpart in the List\'s entity, drawn on this table\'s rows alone |\n| `row` | [List source row](#list-source-row) | How the List reads this table\'s rows, where it differs from the table\'s `records` |\n\n#### List source row\n\n| Key | Type | Meaning |\n|---|---|---|\n| `status` | `{ "edit": true }` | Lets a person move this table\'s stage by hand in the List: `{ edit: true }` |\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `list.sources` | A List\'s `sources` each name another entity once (`entity`) \u2014 never the List\'s own \u2014 whose fields line up with the List\'s by alias, else by `fields` (a field the List reads, or one an Export prints \u2192 one of the source\'s): read as one column type (a day apart from a moment), one value or several alike, a link to the same entity. Each source holds the title, the List\'s folder link and what `where` keeps; it may hold no status \u2014 its rows wear none and stand in no status chip, only the total\'s. Its `columns` name fields of its own table that no List field stands for, drawn on its rows alone and only on a lanes board \u2014 a text, number, date, select or yes/no field, or a lookup of those, never a link or files; an alias a List field or another source\'s column holds is refused; its own `records` status stays its page\'s; the List is a table, cards, lanes or a plan, whose `at`, `across` and `up`, or lanes\' `by` and loads, line up like any field. Two sources holding a field of their own under one alias hold it as one kind of value. An Export\'s `sources` each name the List\'s entity or one of its sources, once, and one of them holds each field its `where` and `per` narrow by. A List with `sources` draws a column naming each row\'s table, and a filter by it; `source_column: false` draws neither. A source\'s rows open the page of its own entity, which states the Acts and Checks they run: each Act\'s `key` its own among the App\'s Acts. |\n| `list.source-lacks` | *Noted, never refused:* A source lacking a field its List\'s `create` asks adds no row; one lacking the select its List\'s plan marks or sizes by never marks or sizes its rows. A field only an Export prints, held by a source as another kind of value, prints blank on its rows. A Tab\'s `totals` over a child linking to no row of a source total nothing on its rows. |\n| `list.source-option-kin` | *Noted, never refused:* A source\'s option labelled as one of the List\'s, under another alias, reads apart from it: the List lists both and counts each on its own. |\n\n<!-- generated:end node-list-source -->\n\n## List over a Query\n\nA root List that states `query` reads the rows of a root Query of the App in place of a table\'s. The Query states `ast` and no `params`, and its rows each come from one record of a table it scans: a Query that groups has no such record, and its rows are counted in a Reading. A row opens that record\'s page, so each table its rows are records of is named by the App and has a page (a Record in `pages`, or a List over it). The rows are read-only and in no folder. The List may hold Acts that act on no row: an Act states `key`, `label`, `on: "view"`, `workflow`, `asks` (inputs only, no field), `confirm` (`true` or a question, never `"warnings"`) and `danger`, runs its workflow with only what it asks (adding a row to the table the reader names, say), and is run by people inside the organization alone.\n\nEvery name the List states \u2014 `title`, `subtitle`, `columns`, `where`, `filters`, `search`, `group`, `sort`, `opens`, a Tab\'s, a Reading\'s and an Export\'s fields \u2014 is an output column of the Query, an alias holding one value. A select column passes a select field through, or writes an option key in the arm: `{ "source": { "literal": "ha" }, "type": "select" }`, worded by `words.<list key>.options.<column>.<key>`. A select read from several tables holds each table\'s option under its alias, and a chip, filter, `opens` and `where` on the alias match every one of them. A union under a `project` or a `limit` keeps the List\'s filters above it, so a column a filter or search narrows belongs in each arm\'s own projection. A number column reads the currency or unit its arms\' fields share, an arm\'s `{ "expression": \u2026 }` that only adds, subtracts or coalesces fields (`coalesce(input.a, 0) + input.b`) reading those it names; any other arm, or fields of different formats, leaves it a plain number.\n\n<!-- generated:start node-list-query -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `key` | alias, required | Names the List among the App\'s Views, and its rows in a report and in the App\'s `words` |\n| `query` | alias, required | The key of a root Query of the App stating `ast`, that is no group: each row it returns is a record of one of its tables and opens that record\'s page; its output columns are what this List names |\n| `label` | text, required | The register\'s name in the app\'s lists and tab strip |\n| `title` | alias, required | The column naming each row |\n| `subtitle` | list of alias (1\u20132) | Up to two columns read under the title |\n| `columns` | list of alias | Columns read after the row\'s title; absent, the title and subtitle alone |\n| `where` | [narrowing](#app-tree) | A fixed narrowing on the server, for every reader, over the Query\'s columns |\n| `filters` | list of (alias \\| [Tiered filter](#tiered-filter) \\| [Listed filter](#listed-filter)) (at most 3) | Columns the reader narrows by every day: a select, member, link, date, yes/no or number range of a column its rows draw, never one drawn nowhere; a Reading\'s narrowing names the same; `tiers` bands a number or date; `values` states which values a pick lists |\n| `search` | list of alias (at least one) \\| `false` | Columns the search box reads; absent, every text and link column the List draws; false, no search box |\n| `group` | alias \\| `false` | A column the rows stand grouped by; absent, the reader may group by a filter\'s column; false, no grouping |\n| `sort` | [Sort key](#sort-key) \\| list of [Sort key](#sort-key) (at least one) | The rows\' order; absent, the Query\'s own |\n| `opens` | [narrowing](#app-tree) | The view the rows open on, a chip the reader may take away: `where`\'s entries but a record bound, and `{ "me": true }` on a member field |\n| `period` | `"today"` \\| `"tomorrow"` \\| `"week"` \\| `"month"` \\| `"quarter"` \\| `"year"` \\| [Period days](#period-days) | The window its dated Tabs read; absent, this month |\n| `readings` | `false` | false, no band; absent, the band is the Readings it holds, none when it holds none. Never with Readings stated |\n| `children` | list of ([Tab](#tab-node) \\| [Reading](#reading-node) \\| [Export](#export-node) \\| [Act](#act-node)) (at least one) | Its Tabs, band Readings, Exports and Acts that act on no row |\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `list.query` | A List\'s `query` names a root Query of the App stating `ast` and no `params`, reading only tables the App names; the List\'s `key` names no table. |\n| `list.query-rows` | A List over a Query lists records: its Query\'s rows each carry the record they come from \u2014 no `group` on their way out. |\n| `list.query-opens` | Each table a List over a Query lists records of is an entity the App draws, whose page its rows open. |\n| `list.query-columns` | A List over a Query names its Query\'s output columns: each an alias holding one value; a select column passes a select field through or writes an option key (a select literal) in every arm, and a link column links one table. |\n| `list.query-scope` | A List over a Query stands in an App with no `scope`: the Query reads no folder. |\n\n<!-- generated:end node-list-query -->\n\n## List over a Query in a Record\n\nA child List of a Record, a Section or a Side that states `query` draws the rows of a root Query of the App that link to the record. The Query is held to what a root List over a Query holds it to, and returns a column linking to the record\'s table (`via` names it where several do); it cuts no rows (`limit`, `window`), which the record\'s narrowing would then miss. A row opens its own table\'s page. The List is read-only: it holds no Tab, Reading, Export, Act or filter, and no table child of the record has the same key as another List over a Query.\n\n<!-- generated:start node-list-query-record -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `key` | alias, required | Names the List among the record\'s parts; unique among the App\'s Lists over a Query |\n| `query` | alias, required | The key of a root Query of the App stating `ast`, that is no group and cuts no rows above its tables: the rows of it that link to this record are drawn, and each opens its table\'s page |\n| `label` | text, required | The block\'s name in the record |\n| `title` | alias, required | The column naming each row |\n| `subtitle` | list of alias (1\u20132) | Up to two columns read under the title |\n| `columns` | list of alias | Columns read after the row\'s title; absent, the title and subtitle alone |\n| `where` | [narrowing](#app-tree) | A fixed narrowing on the server, for every reader, over the Query\'s columns |\n| `sort` | [Sort key](#sort-key) \\| list of [Sort key](#sort-key) (at least one) | The rows\' order; absent, the Query\'s own |\n| `via` | alias | The Query\'s column linking each row to this record, where several link to it |\n| `when` | [condition](#app-tree) | Drawn only while this holds |\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `list.read-scope` | A child read under a record whose rows a `read_scope` narrows states its own \u2014 a row rule is not inherited, save the status history\'s, which takes its record\'s. |\n\n<!-- generated:end node-list-query-record -->\n\n## Layouts\n\nA List\'s `layout` is how it draws its rows: a word (`"table"`, `"cards"`, `"calendar"`, `"roster"`, `"timeline"`) or an\nobject stating one layout and the data it reads (`{ "gantt": \u2026 }`, `{ "lanes": \u2026 }`, `{ "plan": \u2026 }`, `{ "agenda": \u2026 }`,\n`{ "checklist": \u2026 }`, `{ "desk": \u2026 }`). Absent, the register draws a table; a child List states `"cards"` (the register\'s card grid, whatever\nits rows hold), `"table"` (always a table, even over pictures or long text), a checklist, a desk, a gantt, an agenda or\n`"timeline"`, else leaves `layout` out and draws rows holding pictures, long text or a pair of photos as cards and the rest as a table. Each layout reads what the rows already state \u2014 their\n`records` line, stage and dates \u2014 and the keys a layout adds stand on its section: here for an agenda and a checklist, `reference/time-layouts` for lanes and a gantt, `reference/plan-layout` for a plan, `reference/publish-desk` for a desk. Which one a job needs: the\n`design` reference. The register lays out as a table, cards, a calendar, a roster, a gantt, lanes or a plan; a record\'s\nchild rows as cards, a table, a checklist, a desk, a gantt, an agenda or a timeline.\n\n### Table\n\n<!-- generated:start layout-doc-table -->\n\nAbsent `layout`, each row is one line: the table\'s `records` entry \u2014 its picture or mark, title and the line under it \u2014\nthen the stage, the `columns`, and the figure at the right; the title, the stage and a column of days or amounts sort\nthe rows by their header. A table groups its rows by `group`; a table or cards reads `Tab`s and the `sources` of its List.\n\n<!-- generated:end layout-doc-table -->\n\n### Cards\n\n<!-- generated:start layout-doc-cards -->\n\n`"cards"` draws each row as a card led by its picture \u2014 the `records` `image`, or the List\'s `row.image`: its title and\nthe line under it, its stage and what needs the reader (a deadline, a warning), then its figure and the `columns` at its\nfoot. Cards are for rows found by their picture (a product, a vehicle, a damage photo); rows with no picture read better\nas a table.\n\n<!-- generated:end layout-doc-cards -->\n\n### Calendar\n\n<!-- generated:start layout-doc-calendar -->\n\n`"calendar"` or `{ "calendar": { "date": "starts_at", "end": "ends_at" } }` places each row on its day \u2014 a month, a week,\na day or a list (a phone reads the list or a day): at its hour where `date` holds one, over its span where `end` names\nthe date it runs to, with its line\'s other words and the `columns` after its title. `date` and `end` are two dates of\nthe row, both days or both moments; a span of moments gives a phone its day view, and a day\'s `end` is the last day held\n(unless `records` names it the day the row `frees`). The bare word takes them from the rows\' facts: two dates a person\nstates, the second ordered after the first by a `min` or a table check, both required or the second the row\'s `due`; else the one required date a person states that no Act stamps and a new row does not start at today \u2014 and is refused, naming `date`, where the rows hold neither. A `due` is a deadline, never the day a row is held on. The calendar reads the window in view, and its count and the stage chips count that window, opening on every row.\n\n<!-- generated:end layout-doc-calendar -->\n\n<!-- generated:start layout-calendar -->\n\n#### Calendar keys\n\n| Key | Type | Meaning |\n|---|---|---|\n| `date` | alias, required | The date or moment of this entity each row stands on: a viewing\'s start, a hire\'s first day, a visit\'s day |\n| `end` | alias | The date or moment each row\'s span ends on, read as `date` is \u2014 two days or two moments (a moment\'s end gives a phone its day view); absent, a row stands on `date` alone |\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `list.calendar` | `layout: "calendar"` or `{ calendar: { date, end } }`: two dates of the row, both days or both moments; bare, it takes the rows\' span or appointment, else is refused, naming `date`. |\n\n<!-- generated:end layout-calendar -->\n\n### Roster\n\n<!-- generated:start layout-doc-roster -->\n\n`"roster"` draws the List\'s rows down the side and the days of a week or a month across; the roster\'s cells are a List\ninside it over the table whose rows fill the days \u2014 each stands on one row by its single link to it, and on the first\ndate of its line (a shift on a person\'s day, a run on a vehicle\'s), on every day through the second date where its line\nholds one. A cell reads its row\'s stage, else the first single select on its line (a shift\'s kind), several rows their\ncount. A day holding none stays empty: nothing was due, which is never an absence. A filled cell opens its row; an empty\none adds a row there, the register row and the day set. With `expect` on the cells (a single select of those rows) the\ncolumns are its options in place of days \u2014 a checklist of papers \u2014 and `of` names the ones each row expects: a gap among\nthem reads as one and adds its row, the others stand blank, and each row reads what it holds of them, `2/3`. Over days, a\nroster reads the `cadence` its table\'s `records` states (a site\'s diary page, Monday to Saturday from breaking ground to\nhandover): a past day owed with none is marked missing and counted, and each row reads the days it holds of those owed. A\nroster states no `columns` and needs no readings: its legend counts each state in view. `covers: 2` on the cells List says each day\nneeds two rows across every lane: a day holding fewer is marked "Uncovered" in its head, counted in the legend, and the\nExport\'s `columns` carry `covered` (false on such a day) for every day of the window.\n\n<!-- generated:end layout-doc-roster -->\n\n```json\n{ "type": "List", "entity": "operator", "layout": "roster", "filters": ["depot"], "children": [{ "type": "List", "entity": "run" }] }\n```\n\n### Timeline\n\n`"timeline"` reads a record\'s child rows as a log of dated entries, newest first, with a composer where the app adds\nentries, each corrected and removed where it stands. It is never the record\'s status history: the rail shows each\nmove. A timeline\'s moment is its child\'s first date, and who its member field. Rows each what happened on a day and who \u2014\na date on their line, a member, no stage and no figure \u2014 read best as a timeline.\n\n### Agenda\n\n`{ "agenda": { \u2026 } }` reads a record\'s child rows as planned entries on a time axis: by day, soonest first, each with its\npicture and the day that is today marked. The day is the first date on the child\'s row line (its `records` title or\nsubtitle); within a day entries follow a datetime there, else the first single select after the date. An entry with no day\nyet is a plan, listed first and dated in place. `start` is the record\'s date that is the first day: each day\'s heading\ncounts from it (Day 1, Day 2).\n\n<!-- generated:start layout-agenda -->\n\n#### Agenda keys\n\n| Key | Type | Meaning |\n|---|---|---|\n| `start` | alias | The record\'s date that is the first day: each day\'s heading counts from it; absent, the weekday and the date alone |\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `list.agenda` | An agenda List\'s child names a date on its row line (`records` title or subtitle); the layout\'s `start` is a date of the record. |\n| `list.agenda-note` | *Noted, never refused:* Rows each on a day and within it (at an hour, in a part of the day) listed as a table: a List with `layout: { agenda }` draws them by day. |\n| `list.timeline` | A timeline List\'s child holds a date to place its entries by. |\n| `list.timeline-note` | *Noted, never refused:* Rows each what happened on a day and who \u2014 a date on their line, a member, no status and no figure \u2014 listed as a table: a List with `layout: "timeline"` draws them as a timeline, newest first. |\n\n<!-- generated:end layout-agenda -->\n\n### Checklist\n\n`{ "checklist": { \u2026 } }` reads a record\'s child rows, which are tasks, as a checklist of checks: each one\'s mark \u2014 passed\nat a `closed` option, failed at a `failed` one, else still to check \u2014 its title, its columns as its words (a text column\nits note, on its own line), and on a line under its title its photo and its clause. Never grouped nor written in place.\n`passed` alone sets the mark, so rows with no `task` and no status are checks: a measured yes/no is the verdict. With\n`expect` on the standard\'s items, each item is a line marked the same way (a missing one still to check), filled in\nplace by the block\'s `columns` (a measured value, a note, a photo), so `photo` and `clause` are not named.\n\n<!-- generated:start layout-checklist -->\n\n#### Checklist keys\n\n| Key | Type | Meaning |\n|---|---|---|\n| `photo` | alias | The child\'s files field holding the photo each row is checked by; absent, the child\'s `records.image` |\n| `clause` | alias | The child\'s one-row link to what each row is checked against \u2014 a standard\'s clause, a rule |\n| `failed` | list of alias (at least one) | Options of the child\'s status a row stands failed at \u2014 none of them closed |\n| `passed` | alias | The child\'s yes/no field (stored or a formula) setting each row\'s mark: yes passed, no failed, empty still to check |\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `list.checklist` | A child List with `layout: { checklist }` reads a task entity\'s rows as checks \u2014 never under documents, grouped, edited in place or picked together by an Act over several, its columns no files; `photo` names a files field of the child, `clause` a one-row link of it, `failed` options of its status, none `closed`; `passed` a yes/no of it, stored or a formula, setting each mark (yes passed, no failed, empty still to check) and standing without `task` or a status. With `expect` the lines of a standard are the checks, each marked and filled by the block\'s columns (a measured value, a note, a photo), so `photo` and `clause` are not named. |\n\n<!-- generated:end layout-checklist -->\n\n## Time layouts\n\nThe layouts that place a List\'s rows in time. Each is a `layout` object stating the data it reads.\n\n### Lanes\n\n<!-- generated:start layout-doc-lanes -->\n\n`{ "lanes": { "by": \u2026 } }` draws each row of the linked table as a lane (a chair, a machine, a room), empty ones too,\nand each row of the List as a block from the first date on its line (or `date`) to the second (`end`): over the hours of one day, where the\nfirst holds its hour (a week of them draws each day\'s cells, a block\'s time range its first fact), else over the days of one day, a week or a month. A press on a free stretch adds a row there, its lane and start set, its end where the next block bounds it. Rows naming no lane stand first, in a lane of their own; where the app writes the link, a block moves to another lane from its menu. Inside a `scope`, the lanes are those whose own one-link names that scope\'s row. A span\'s\nend holds its day unless `records` names it the day the row `frees`.\n\nRows with no hour read at one day as cards in lanes: the rows no lane holds first, in a tray that\nalso holds the rows with no day, then each lane with its count and its status where its table states one; a lane its link no longer admits says so on its head and takes no new card. A card\'s lead is its\ntick; ticked cards, or one dragged, go to a lane together in one write, every row judged before any is written. The List\'s first\n`sort`, where a stored number the app writes, is a card\'s place in its lane. A week of such rows, or rows with an hour, keep the blocks.\n\n`by` may instead name a member field holding one person, with `of` a group of the workspace, by id, whose every member is a\nlane \u2014 `{ "lanes": { "by": "engineer", "of": "grp_\u2026" } }`; a `no_overlap` by that member keeps one row per person at a time.\nOr a field holding one option (a single select, a formula stating options, a lookup of either through one-row links): each option is a\nlane in its order, the rows holding none in the tray, no add from a lane, a card given to an option where the app writes a stored select.\n`loads` read a lane\'s row, which neither is.\n\n`down` stands bands down the board of days: a card stands in the cell of its lane and band, the rows holding none in a last band drawn\nwhen a card in view holds none; where the app writes the `down` field, a card dropped in a cell is given both in one write.\nA List\'s `group` stands its cards in each lane (and cell)\nunder the group\'s sub-headings, a group holding no card there not drawn.\n\n`loads` names what a lane carries: `{ "weight": "payload", "volume": "box" }` sums each block\'s number against the lane row\'s own; each block then reads that number after its first column. A lane reads the most its\nblocks add up to at one time (hours add up within each day, across days the fullest day is read), named past its bound, by how much and when. `"per": "week"` holds the bound over the calendar week of the day in view instead, on a day, a week or a day of hours, the\nhead saying "6 h of 40 h this week". A bound a single row must keep (no parcel heavier than its van) is a `max` on the field through the link, which refuses the move.\n\n<!-- generated:end layout-doc-lanes -->\n\n<!-- generated:start layout-lanes -->\n\n#### Lanes keys\n\n| Key | Type | Meaning |\n|---|---|---|\n| `by` | alias \\| [Lanes axis](#lanes-axis), required | The field the rows stand in lanes by: a one-link, a member (with `of`) or a one-option field |\n| `of` | text | A group of the workspace, by id, whose every member is a lane |\n| `down` | alias \\| [Lanes axis](#lanes-axis) | The field the rows stand in bands by: a one-option field or a one-link |\n| `date` | alias | The day a row stands on: a date of the row, or a lookup of its parent\'s through one-row links |\n| `end` | alias | With `date`: the day it ends |\n| `loads` | map of alias \u2192 alias | A number of this entity each block adds \u2192 a number of the lane\'s row it bounds |\n| `per` | `"day"` \\| `"week"` | With `loads`: `day` (default) or `week` |\n\n#### Lanes axis\n\n| Key | Type | Meaning |\n|---|---|---|\n| `field` | alias, required | The board\'s field |\n| `values` | `"all"` \\| `"held"`, required | `all` draws every one, `held` only those a row in view stands in |\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `list.lanes` | `layout: { lanes }`: `by` and `down` (never one field) each name a one-row link to a table stating `records` or a one-option field, `by` also a member with `of`; the rows name a date on their line or in `date`, `end` read alike (two days or two moments); `loads` and `per` stand with a link `by` only, `values: "held"` never beside `of`, and a board by options, with `down` or `group` reads one day from a date, never a moment. |\n| `list.loads` | A lanes layout\'s `loads` names one to 2 numbers a lane block adds \u2014 never a percent \u2014 each against a number of the lane\'s row, in one unit or two of one dimension; `per` (day or week) stands only beside `loads`. |\n\n<!-- generated:end layout-lanes -->\n\n### Gantt\n\n<!-- generated:start layout-doc-gantt -->\n\n`{ "gantt": { \u2026 } }` draws each row as one bar on one axis of time: `{ "start": "etd", "end": "eta", "milestones":\n["cut_off"], "planned": { "end": "booked_eta" }, "progress": "done", "after": "waits_on" }`. `end` defaults to the table\'s\nfirst `due`, and a table with neither is refused. The bars\nstand in the lanes of the List\'s `group`. Where the app writes the row and a person writes a bar\'s date, the bar is\ndragged through the row\'s save; a computed date, one an Act sets, or a row the app does not write drags nothing. Over a\ntable that holds rows under rows, each bar stands under the row above it, indented and folded as the register\'s outline\nis, `group` still the outer section. A child List of a record may lay out as a gantt too: the bars of the rows the\nrecord\'s link names.\n\n<!-- generated:end layout-doc-gantt -->\n\n<!-- generated:start layout-gantt -->\n\n#### Gantt bar\n\n| Key | Type | Meaning |\n|---|---|---|\n| `start` | alias, required | A date of this entity each row\'s bar starts at (a sailing, a hire\'s start, a task\'s start) |\n| `end` | alias | The date each row\'s bar ends at, read as `start` is \u2014 two days or two moments; absent, the entity\'s first `due` |\n| `milestones` | list of alias (at least one) | Dates of the row marked on its bar\'s line as diamonds, each named by its label (a cut-off, a delivery, the end of free time) \u2014 never `start` or `end` |\n| `planned` | [Gantt plan](#gantt-plan) | The plan each row is read against, drawn as a thin bar under its own \u2014 each date read as `start` is; a missing one is the bar\'s own |\n| `progress` | alias | A percent of this entity (0\u2013100) filling each row\'s bar as far as the work is done; absent, how many of the row\'s tasks are done fills it where its record lists them, else the bar wears its status\'s tone |\n| `after` | alias | A link of this entity to its own rows each row waits on \u2014 it starts once they end (finish-to-start), an arrow from each; a row starting before one ends is drawn in the danger tone |\n\n#### Gantt plan\n\n| Key | Type | Meaning |\n|---|---|---|\n| `start` | alias | The date the row was planned to start at |\n| `end` | alias | The date the row was planned to end at (a booked arrival) |\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `list.gantt` | `layout: { gantt }`: `start` and `end` (absent, the entity\'s first `due`) are two different dates of the row, both days or both moments; each diamond (`milestones`) another date of it, each planned date read as `start` is, `progress` a percent and `after` a link to rows of the same entity. |\n\n<!-- generated:end layout-gantt -->\n\n## Plan layout\n\nThe layout that places a List\'s rows on a plan of the places they stand at: a `layout` object stating the data it reads.\n\n### Plan\n\n<!-- generated:start layout-doc-plan -->\n\n`{ "plan": { \u2026 } }` draws things that stand at a place \u2014 pallets in a warehouse \u2014 on a plan of the places. The places are\nthe rows of a table whose `records` states a `plan_place` (a bay, an open area or a landmark, each at its spot on a sheet\nof the plan); `at` names the one-link of the List\'s rows to a place and, for an item in a bay, the row (`across`) and the\ntier (`up`) it stands in, counted from 1. A bay is drawn as its rows and tiers, an area with a count, a landmark as a\nlabelled frame; the reader sees a plan, one bay enlarged, and the same plan in 3D. The List may read other tables as\n`sources`: one plan of every table\'s items. Each item carries `__reach` \u2014 how many items stand in the way of taking it out\n(those above it where the place is `stacked`, and those in the rows between it and the side `reach_from` says the bay is\ntaken from) \u2014 and `__floating` and `__crowded` (yes/no: nothing under it in a place that stacks; two in one cell) \u2014 so the list, its export and an agent\'s read all carry them; `<table>_plan_load` counts the rows each place\nholds. A move through the app is refused unless it clears the place, row and tier all three, or places the item at\na free cell of a bay \u2014 resting on a present item where the place is `stacked`, and no larger across or along than the bay\'s cell where the plan and the place both state a size \u2014 or at an area. Every other write (a grid edit, an import, a tool) holds one item to a cell only where the item\'s table states `unique: [<at>, <across>, <up>]`; a plan over a table stating none is noted. A plan opens on every row\nits `where` keeps, with no stage chip narrowing it. Rows with no place wait in a tray beside the plan. An Act that asks exactly a place (a link to the plan\'s places) and two numbers (the row and the tier) is answered by a pick on the plan, never by a form. On a desk a press opens a row\'s record in the panel beside the plan.\n\n<!-- generated:end layout-doc-plan -->\n\n```jsonc\n// table "bay"\n"title": "code",\n"records": { "plan_place": { "kind": "kind", "x": "x", "y": "y", "across": "rows", "up": "tiers", "reach_from": "taken_from", "stacked": "is_stack" } }\n```\n\n```json\n{ "type": "List", "entity": "pallet", "filters": ["line"], "layout": { "plan": { "at": "bay", "across": "row", "up": "tier" } } }\n```\n\n```jsonc\n// table "pallet": one item to a cell on every write, not only through the app\n"unique": [["bay", "row", "tier"]]\n```\n\n<!-- generated:start layout-plan -->\n\n#### Plan keys\n\n| Key | Type | Meaning |\n|---|---|---|\n| `at` | alias, required | A one-link of this entity to an entity whose `records` states a `plan_place`: where each row stands |\n| `across` | alias, required | A number field: the row of a bay a row stands in, counted from 1; empty at an area |\n| `up` | alias, required | A number field: the tier of a bay a row stands at, counted from 1 at the ground; empty at an area |\n| `fill` | alias | A single select the items are coloured by; absent, the first single select among the register\'s filters |\n| `mark` | [Plan mark](#plan-mark) | A row holding the option says the option\'s label on its box and is hatched in the option\'s own colour, and the legend names it by the label; over `sources`, the select is matched by option alias, and a source lacking the select never marks its rows |\n| `size` | [Plan size](#plan-size) | Each row\'s box as it stands in the world, in the one length unit its places\' `size` states: the option the row holds of the select names its box\'s width across, depth along and height; over `sources`, matched by option alias, as `mark` is; a row holding an option it does not name is drawn at its place\'s cell |\n\n#### Plan mark\n\n| Key | Type | Meaning |\n|---|---|---|\n| `field` | alias, required | A single select of this entity, or a lookup of one through a one-row link |\n| `option` | alias, required | An option alias of that select |\n\n#### Plan size\n\n| Key | Type | Meaning |\n|---|---|---|\n| `field` | alias, required | A single select of this entity, or a lookup of one through a one-row link |\n| `options` | map of alias \u2192 [Plan size box](#plan-size-box), required | The box of each option alias of that select |\n\n#### Plan size box\n\n| Key | Type | Meaning |\n|---|---|---|\n| `across` | number, required | The box\'s width across the bay\'s rows |\n| `along` | number, required | The box\'s depth along them |\n| `up` | number, required | The box\'s height |\n\n#### Plan place\n\n| Key | Type | Meaning |\n|---|---|---|\n| `kind` | alias, required | A single select, options aliased `bay` and, where the places have them, `area` and `landmark`: a bay holds rows and tiers, an area neither, a landmark nothing |\n| `sheet` | alias | The plan sheet it is on: a single select, or a one-row link to an entity whose `records` states its `image` \u2014 the sheet\'s drawing, which the places are drawn over (with `scale`) |\n| `scale` | alias | A number field of the sheet entity `sheet` links to: how many cells wide its drawing is, the plan\'s scale. Required where that entity states an `image`, and only then |\n| `x` | alias, required | A number field: left edge, in cells |\n| `y` | alias, required | A number field: top edge, in cells |\n| `width` | alias | A number field: an area\'s frame width, in cells |\n| `depth` | alias | A number field: an area\'s frame depth, in cells |\n| `across` | alias, required | A number field: a bay\'s rows |\n| `up` | alias, required | A number field: a bay\'s most tiers |\n| `reach_from` | alias | A single select, options aliased exactly `first`, `last`, `both`: the side boxes leave a bay from; a bay that names none has no reach and no arrow |\n| `stacked` | alias | A boolean field: true where items at this place rest on the one below (a stack), so a tier above the first needs a present item under it, shows floating without one, and an item\'s reach counts the items above it; false or empty, items sit at any tier and only the rows between a bay\'s reach side and the item are in the way |\n| `size` | [Plan place size](#plan-place-size) | The real size of ONE cell of the place, for 3D: three number fields stating one length `unit` alike. Absent, a cell is drawn at the size most of the sheet\'s places state, a unit cube where none states one |\n\n#### Plan place size\n\n| Key | Type | Meaning |\n|---|---|---|\n| `across` | alias, required | A number field: the width of one cell across the rows |\n| `along` | alias, required | A number field: the depth of one cell along the place |\n| `up` | alias, required | A number field: the height of one cell, one level |\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `list.plan` | `layout: { plan }`: `at` is a one-row link to an entity whose `records` states a `plan_place`, `across` and `up` two different numbers of the row, `fill` a single select; a plan List has no Tabs, `group` or `attention`. A write that sets `at`, `across` or `up` is refused unless it clears all three, or places the row at a free cell of a bay (a row from 1 to the bay\'s `across`, a tier from 1 to its `up`, resting on a present item), or at an area with neither. |\n| `list.plan-unique` | *Noted, never refused:* A plan\'s items (the List\'s table and each source) state `unique` on their place link, `across` and `up`: the app\'s moves refuse a taken cell, and the unique makes every other write hold it \u2014 the note names a table that states none. |\n| `list.plan-mark` | A plan\'s `mark` names a single select of the row, or a lookup of one through a one-row link, and an option of it by alias: a row holding that option is hatched on its box in the option\'s colour. A source that holds the select must hold it as a single select with that option; a source lacking it never marks its rows (`list.source-lacks`). |\n| `list.plan-size` | A plan\'s `size` names a single select of the row, or a lookup of one through a one-row link, and, by option alias, the box (`across`, `along`, `up` \u2014 positive, in the one length unit the places\' `size` states) of each option: a row holding one is drawn as that box. A source that holds the select must hold it as a single select; a source lacking it draws its rows at their places\' cells (`list.source-lacks`). |\n| `list.plan-box-size` | *Noted, never refused:* A plan whose places state a `size` and whose rows\' select options are ISO 6346 container size-type codes (`20DC`, `40HC`) states the box of each in `size`, from the ISO 668 dimensions, else every box is drawn at its place\'s cell. |\n\n<!-- generated:end layout-plan -->\n\n## Publish desk\n\nRows that are each a place the record is sent \u2014 a notice\'s boards, a listing\'s portals \u2014 are a record\'s child List with\n`expect` on the child\'s one-row link to the catalog of those places and `layout: { "desk": \u2026 }`:\n\n```json\n{\n "type": "List",\n "entity": "posting",\n "expect": "board",\n "columns": ["posted_link", "refusal"],\n "layout": { "desk": { "bodies": ["wording", "wording_abroad"], "text": "goes_out_as", "media": "pictures", "link": "page", "group": "reach", "network": "kind", "networks": { "company_page": "linkedin" } } }\n}\n```\n\nThe desk is where the post is written. `bodies` are the record\'s plain text fields it is written in (one per language,\nsay), each its editor between the list and the preview, saved as any field of the record is and drawn nowhere else on it.\nThe preview is `text` read over what is on screen: where `text` is a formula of the child, the desk computes that same\nformula over what is typed, so the post moves as it is written, and a place not ticked previews the words its row would\nhold. For that the formula reads only what a screen holds whole: stored values of its row, the record through lookups over\nthe link back to it, the place through lookups over `expect`, and formulas of the row over those \u2014 a rollup, a lookup\nthrough another link or the clock is refused, naming the field.\n\nEvery place the link admits is a line with a tick and that place\'s face: its picture, else the mark of the network it is on\nwhere `networks` names one. `group`, another single select of the place, stands the lines under its options in their\norder: a kind holding a ticked line is open, one holding none folded to its heading and its count. A tick makes the line\'s\nrow from its key alone \u2014 so nothing else the child requires is left without a default \u2014 and an untick deletes it until the\nrow\'s stage is `closed`: what went out is not taken back. It asks first only where a person wrote on the row. One line is\nworked beside the list and read as the post that place\'s feed shows: `text` is the child\'s words for that place, `media`\nand `link` the record\'s, and `network` the place\'s single select whose options `networks` names to a feed; an option not\nnamed reads on a plain card. Under the bodies stand the List\'s `columns` a person writes of the line\'s row; under the post,\nthe press copying its words beside the Acts of the child, then what the line and the `columns` hold that nobody writes\nthere (the link it went out at, why it was refused). A value an Act or a workflow fills is stated as that Act\'s, so the\ndesk never offers it as an empty box. Sending is an ordinary Act of the record.\n\n<!-- generated:start layout-desk -->\n\n#### Desk keys\n\n| Key | Type | Meaning |\n|---|---|---|\n| `bodies` | list of alias (1\u20133) | The record\'s plain text fields the post is written in, in order \u2014 one per language, say \u2014 at most 3: each its editor on the desk, between the list and the preview, and drawn nowhere else on the record |\n| `text` | alias, required | A text of the block\'s rows \u2014 stored, or a formula yielding text \u2014 holding the words that go out on that row\'s destination. A formula is computed on the desk too, over what is typed: it reads stored values of its row, the record through lookups over the link back to it, the destination through lookups over `expect`, and formulas of the row over those \u2014 never a rollup, another link or the clock |\n| `media` | alias, required | A files field of the record: the pictures or the video the post carries |\n| `link` | alias | A text field of the record holding a link (`format: "link"`), carried as the post\'s card |\n| `network` | alias, required | A single select of the entity `expect` links to, saying which network each destination is on |\n| `group` | alias | Another single select of the entity `expect` links to \u2014 the destination\'s kind \u2014 the lines stand grouped by: each option a heading in the select\'s order, a group holding no ticked line folded to its heading and its count, destinations holding no option last |\n| `networks` | map of alias \u2192 `"facebook"` \\| `"instagram"` \\| `"threads"` \\| `"x"` \\| `"linkedin"`, required | That select\'s options, each by its alias, to the network whose feed the post is previewed in \u2014 facebook, instagram, threads, x, linkedin. An option not named has no feed to imitate: its words read as a plain card |\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `list.post` | A child List with `layout: { desk }` needs `expect` on a one-row link \u2014 never a select, nor with `under`, `pick`, a checklist layout, `compare` or a `create` list, its line made by a tick from its key alone: its `bodies` are plain text fields of the record a person writes, drawn nowhere else on it; its `text` is a text of the child, stored or a formula yielding text \u2014 a formula reading only stored values of its row, lookups through the link back to the record or through `expect`, and formulas of the row over those, never the clock; its `media` a files field of the record and its `link` a text field of the record; its `network` a single select of the entity the link names, and `networks` holds options of that select, by alias, each to one of facebook, instagram, threads, x, linkedin; its `group` is another single select of that entity. |\n\n<!-- generated:end layout-desk -->\n\n## Record node\n\nA Record draws what a row opens: the head, then the parts.\n\n- **The head:** title, subtitle, picture, mark, party, figure and meter, deadlines, description \u2014 the\n table\'s `records` facts, overridden by the Record\'s `row`. `row` changes how the App\'s rows read wherever it lists them, and has nothing to do with arranging a page. The status stands in the head, or the Side where the Side states it, never in a Section.\n- **Where it stands:** a Record stands only in the App\'s `pages`, one per entity, stating its `entity`; every List over\n the entity opens it. With no page for an entity, the platform designs the record\'s Sections from the rows: the fields\n the head does not draw, child Lists, papers and Acts. A stated page stands exactly as written, so it replaces them.\n Under a child List, an absent page is every field of the child except the link back.\n- **Children:** either parts \u2014 `Section`, `Side`, and one `Steps` holding the Sections that are the record\'s path \u2014 or, for a one-part record, `Field`, `List`, `Reading`,\n `Statement`, `Comments` and `Act` directly. The two are never mixed. The page of an entity no root List and no Sheet\'s List (one stating no `app`) is over \u2014 a\n child List\'s, a document\'s or a roster cell\'s \u2014 holds `edit`, Fields, Sections of them with the Acts and the Lists of\n their rows\' own children, and the Lists of its rows\' own children; a row opened in place draws each Section under its\n title, an Act no Section holds at the last Section\'s foot, and a page with no Section its one section. Such a page\n holds what any page holds \u2014 a Reading, a Side \u2014 and one stating a Side opens its rows\n by its `door` instead of in place; any other `door` there is not drawn and stays stated.\n\n<!-- generated:start node-record -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `entity` | alias, required | The table whose rows open on this page: a page stands once per entity, in the App\'s `pages`, and every List over the entity opens it |\n| `row` | [Record row](#record-row) | How the App reads this entity\'s rows wherever it lists them \u2014 their line, figure, picture, deadlines and stage \u2014 where it differs from the table\'s `records` |\n| `add` | `false` \\| list of alias (at least one) | What a new row asks where a picker of this entity offers one, anywhere in the App: these fields; `false`: a picker only picks. Absent, the table\'s required fields, its natural key and its title, where the table states a `singular` |\n| `remove` | `true` | Lets a person delete a row reached through a link: true, it offers a Delete; rows a List lists are deleted as that List\'s `remove` says |\n| `door` | `"page"` \\| `"drawer"` | How a row opens, on a page or in a drawer: absent, a page where a part is a step or a Side or there are more than 3 parts, else a drawer |\n| `edit` | `false` | Shows a record nobody changes here: false, nothing it draws is written, a link\'s row of it included |\n| `children` | list of ([List over a Query in a Record](#list-over-a-query-in-a-record) \\| alias \\| [Field](#field-node) \\| [Fieldset](#fieldset-node) \\| [Section](#section-node) \\| [Steps](#steps-node) \\| [Side](#side-node) \\| [Outside](#outside-node) \\| [List](#list-node) \\| [Reading](#reading-node) \\| [Statement](#statement-node) \\| [Comments](#comments-node) \\| [Act](#act-node) \\| [Check](#check-node)) (at least one) | Parts (Section, Side, and one Steps holding the Sections that are its path), or for a one-part record its Fields, Fieldsets, Lists, Readings, Statements and Comments directly \u2014 never both. Beside either stand Outsides, Checks (guarding this entity\'s Acts and saves) and Acts on one row, each placed at the foot of the part whose step it moves into, a correction in the head\'s \u22EF. Holding only Acts, Checks and Outsides, or absent, the record\'s Sections are the platform\'s: the fields the head does not draw, child Lists, papers and Acts. Otherwise it stands exactly as written |\n\n#### Record row\n\n| Key | Type | Meaning |\n|---|---|---|\n| `title` | [Record row title](#record-row-title) | The row\'s title field, stated for its `edit` alone |\n| `subtitle` | list of (alias \\| [Record row line field](#record-row-line-field)) (1\u20132) | Up to two fields read under the title, in place of the table\'s |\n| `figure` | alias \\| [Record row line field](#record-row-line-field) \\| `false` | The one number a row stands for, in place of the table\'s; false, none. `{ field, edit: false }` reads it without writing it |\n| `image` | alias \\| [Record row line field](#record-row-line-field) \\| `false` | A files field, or a one-row link to a table with a picture, that pictures a row, in place of the table\'s; false, none. `{ field, edit: false }` reads it without writing it |\n| `due` | list of alias (at least one) \\| `false` | Dates that count down, in place of the table\'s; false, none |\n| `status` | `false` \\| `{ "edit": true \\| false }` | Whether this app shows and moves the stage: false, it is not shown. `{ edit: true }`: the stage is also moved by hand. `{ edit: false }`: nobody moves it in this app, another app does. Absent, the stage stands in the record\'s head, or in the Side where the Side states it: choosing a move runs its Act, asking and refusing as its button does |\n\n#### Record row title\n\n| Key | Type | Meaning |\n|---|---|---|\n| `edit` | `false` | Keeps a row\'s name as it stands: false, the title is read; absent, it is written where the table lets a person write it |\n\n#### Record row line field\n\n| Key | Type | Meaning |\n|---|---|---|\n| `field` | alias, required | The field\'s alias |\n| `edit` | boolean | Shows a value nobody changes here: false, the field is drawn and read; absent or true, it is written where the table and the part holding it let a person write it. A field an Act\'s body writes is the Act\'s, read-only elsewhere and drawn once filled, unless the Field states `edit: true`, which keeps it a person\'s to edit |\n\n<!-- generated:end node-record -->\n\nThe door is a page where a part is a step or a Side, or where there are more than 3 parts; else a drawer. `door`\nis a judged choice of how a job is worked (one after another over a long record), so it is kept. A Section is one area of the record\'s data a person comes to for its own job, like the tabs of a settings page (a company\'s General,\nMembers, Billing): the related lists and field groups of that area sit inside it under their headings. A status\'s stages are not areas:\ntheir acts stand at the foot of the rows they move. From three parts on, the\nrecord shows one at a time: a press on a page\'s rail (a strip of the same names on a phone and in a drawer) flips to a part and returns\nto the top. It opens on the part the address names, else the step that is now, else the first. A part\'s rows and drafts are kept\nacross flips. With fewer parts they stack.\n\nA record shows no activity and no audit log: a history an app shows is table-backed \u2014 `records.status.dates`, `records.status.history`, an event table an act\nmakes \u2014 stated where the app shows it.\n\nA field may be stated in any number of parts, and each part draws what it states. Where parts stack it stands once: in the\nstep that is now if that step states it, else the first part stating it. A Section or a List with `when` is\ndrawn only while each named select of the record holds one of its options.\n\n## Section node\n\nA titled part of a record. A Section draws its plain Fields first, then its\nLists, Readings, Statements and Comments in the order stated; its Acts stand at its foot.\n\n<!-- generated:start node-section -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `key` | alias | Unique among its siblings; part of the node\'s address. Absent, the title\'s words as a slug, written once and kept |\n| `title` | text | The part\'s heading. Absent, the part draws none where it is the record\'s only part; beside others it is named by what the record is. A step states it |\n| `description` | text | A line under the heading |\n| `when` | [condition](#app-tree) | Drawn only while this holds |\n| `edit` | `false` | Shows a part nobody changes here: false, nothing in it is written |\n| `at` | list of alias (at least one) | The status options this part is the work of; a step is stated as a Section inside `Steps` (`reference/steps-node`) |\n| `children` | list of ([List over a Query in a Record](#list-over-a-query-in-a-record) \\| alias \\| [Field](#field-node) \\| [Fieldset](#fieldset-node) \\| [List](#list-node) \\| [Reading](#reading-node) \\| [Statement](#statement-node) \\| [Comments](#comments-node) \\| [Act](#act-node) \\| [Check](#check-node)) (at least one) | What the part draws, in reading order; its Acts stand at its foot. A Fieldset holds Fields under a heading of their own. A Check stated here guards the entity as one beside the parts does |\n\n<!-- generated:end node-section -->\n\n#### Kinds of block\n\nWhat a Section draws beside its Fields is a block, of the kind its item states: a List a rows block, an outline where its table holds rows under rows, an agenda or a timeline by its layout, or a list that only reads; a Field a gallery of files or a prose block; a Statement, Comments and a Reading each its own.\n\n<!-- generated:start block-kinds -->\n\n| Kind | What it is |\n|---|---|\n| `rows` | Rows list a record\'s child rows under it, each a line in the register\'s row anatomy: a List standing in a Section, its rows linked to the record, narrowed by its `where`, opened in place, their Acts in each row\'s \u22EF; rows that hold pictures are cards, each led by its picture. A child List draws as rows unless its layout says otherwise; `cards` draws them as the register\'s card grid and `table` always as a table, whatever they hold; a `checklist` reads the rows as checks, a `desk` as the places the record is sent and a `gantt` as bars on an axis of time (the register\'s, over the rows the record\'s link names). |\n| `outline` | An outline draws a record\'s child rows as a tree where their table holds rows under rows (a task under a task, a part of a part): the top rows first, each row\'s sub-rows read when it is opened, with the count of them, closed of all, beside its name; a row adds a row under itself from its \u22EF. A List the reader narrows, orders by a header, groups or searches draws as plain rows. |\n| `agenda` | An agenda reads a record\'s child rows as planned entries on a time axis: by day, soonest first, each with its picture and the day that is today marked. The day is the first date on the child\'s row line; within a day entries follow a datetime there, else the first single select after the date. An entry with no day yet is a plan, listed first and dated in place. `start` is the record\'s date that is the first day: each day\'s heading counts from it (Day 1, Day 2). |\n| `timeline` | A timeline reads a record\'s child rows as a log of dated entries, newest first, with a composer where the app adds entries, each corrected and removed where it stands. It is never the record\'s status history: the rail shows each move. A timeline\'s moment is its child\'s first date, and who its member field. |\n| `files` | Files draw a run of the record\'s files fields as one gallery under a heading, each field\'s files as thumbnails with a drop zone to add to them. A files field, or a lookup of one, draws as a gallery unless its Field states `block: false`. |\n| `text` | Text draws one of the record\'s markdown fields as prose under a heading, edited in place where the app writes it. A markdown field draws as prose unless its Field states `block: false`; plain text is a control among the part\'s fields unless it states `block: true`. |\n| `choices` | Choices draws one of the record\'s multi-selects as a checklist under a heading: every option on a line of its own, ticked where the record holds it, ticked and unticked in place where the app writes it. A multi-select is a control among the part\'s fields unless its Field states `block: true`. |\n| `linked` | Linked draws the row a link of the record to one row names, whole and in place, as its page draws it \u2014 its fields, parts, Lists and Acts, read and written as that row\'s own \u2014 under a heading. A link draws as its row\'s chip unless its Field states `block: true`. |\n| `figures` | Figures draw numbers of the record (1 to 8) as tiles, each under its field\'s label. A tile holding nothing reads as not measured, never 0. |\n| `statement` | A statement builds one figure from figures of the record: each line a number of it with its operator and its label, the figures on one right edge, the last an `equals` drawn heaviest (a claim\'s payable, an invoice\'s total, a payslip\'s net). A line may carry the rows its figure adds up (`parts`), each listed under it. |\n| `comments` | Comments draws the record\'s comment thread: the platform\'s built-in comments, the same thread the table\'s record panel and a custom-code app show, with a box to write one. Reach for it where people discuss the record (a Section or the Side of a Record; once per Record). Members only: a viewer outside the workspace sees none. It reads the record\'s own thread, so a Record over a query has none to show. |\n| `reading` | A reading block draws a Reading over the child rows under the record, through their link to it: a number, a split into parts, a trend, a grid, a shortfall against stock, or the work against its plan. It stands in the record\'s strip beside the record\'s own figures. |\n| `list` | A list shows rows of another entity beside the record, read only: those linked to it, a path through a row of their own, or \u2014 with `same` \u2014 the siblings sharing a link of the record, the record itself left out. Each row reads in its `records` anatomy with the `columns` after its title, and opens on its page. |\n| `funnel` | A funnel counts steps people drop out of between, a column of each child row a step (2 to 8): one funnel over the rows under the record \u2014 each step its column summed, its bar over the first step, the share kept between two steps and from the first to the last. |\n\n<!-- generated:end block-kinds -->\n\n- **`at`** names the stage options during which the section is the work now. A step\'s `at` is stated on a Section inside `Steps`\n (`reference/steps-node`), which is where a stage\'s content stands. A step never hides a\n field, locks it or gates an act: fields stay writable as the write rules and checks allow, at any stage.\n- **Acts:** every Act on a record stands in the Section whose work it is. An Act moving the stage and offered at ONE step\n stands at that step\'s foot when it moves the work forward, to an exit later in the stage\'s options, or back to a step the\n work passes; one offered at several steps, or moving back into a step the work never passes, stands in the Section it\n enters, as its way in. One stated elsewhere stands there, and the answer says so. A correction (`danger`, and not one of\n its step\'s outcomes) waits in the Section heading\'s \u22EF.\n- **An exit** stands only once the record is in it, its reason there and its step apart from the path; until then the\n Act waits in the header\'s \u22EF.\n- **A document:** a Section that is no step and holds nothing but one `text` block over a markdown field reads as a document: the field is written in place with no box, saved when the writer leaves it, and the record reads in an article column while that part is in view.\n- **Writes:** its Fields and its Acts.\n\n## Steps node\n\nA record\'s path down the page. Steps holds the Sections that are the record\'s steps, in the order they stand: a stage that holds something of its own \u2014 fields, blocks, acts or a note \u2014 is a Section stating `at`, the status options during which it is the work now. The Sections stand where the Steps node stands among the record\'s parts.\n\n<!-- generated:start node-steps -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `children` | list of [Step](#step) (at least one), required | The record\'s steps in the order they stand, each a Section stating `at`: what it holds is drawn under its step, and the step stands as the work now while the status is one of its `at` |\n\n#### Step\n\n| Key | Type | Meaning |\n|---|---|---|\n| `type` | `"Section"`, required | Always `Section` |\n| `key` | alias | Unique among its siblings; part of the node\'s address. Absent, the title\'s words as a slug, written once and kept |\n| `title` | text | The step\'s heading. Absent where `at` names one option, the option\'s name; a step naming several options states it |\n| `description` | text | A line under the heading |\n| `when` | [condition](#app-tree) | Drawn only while this holds |\n| `edit` | `false` | Shows a part nobody changes here: false, nothing in it is written |\n| `at` | list of alias (at least one), required | Options of the record\'s status during which this step is the work now |\n| `children` | list of ([List over a Query in a Record](#list-over-a-query-in-a-record) \\| alias \\| [Field](#field-node) \\| [Fieldset](#fieldset-node) \\| [List](#list-node) \\| [Reading](#reading-node) \\| [Statement](#statement-node) \\| [Comments](#comments-node) \\| [Act](#act-node) \\| [Check](#check-node)) (at least one) | What the part draws, in reading order; its Acts stand at its foot. A Fieldset holds Fields under a heading of their own. A Check stated here guards the entity as one beside the parts does |\n\n<!-- generated:end node-steps -->\n\n- **Where:** a direct child of a Record, at most one, with every Section that states `at`; a Section, Side or Outside holds none. It states no `key`: its address is `steps`, and a Section inside it is `pages/<entity>/steps/<key>` or its key alone, which the page shares with the record\'s other parts.\n- **A step\'s title** is the name of its option where `at` names one and it states none; a step naming several options states its title.\n- **Over a status that closes an option** (`records.status.closed`). A status that closes none is a condition a person sets, and has no path; the record draws its select alone.\n- Two Sections may name one option, and their options may overlap. A status option no Section names is a step of its own, holding nothing.\n\n## Side node\n\nThe one part drawn beside the rest \u2014 the photos looked at, the pool picked from, the facts kept in view. It stands on the\nright, beside the rail and the parts; on a phone it is one pinned line that opens in place. At most one Side to a record, on a page\ndoor.\n\n<!-- generated:start node-side -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `key` | alias | Unique among its siblings; part of the node\'s address. Absent, the title\'s words as a slug, written once and kept |\n| `title` | text, required | The part\'s heading |\n| `description` | text | A line under the heading |\n| `when` | [condition](#app-tree) | Drawn only while this holds |\n| `edit` | `false` | Shows a part nobody changes here: false, nothing in it is written |\n| `children` | list of ([List over a Query in a Record](#list-over-a-query-in-a-record) \\| alias \\| [Field](#field-node) \\| [Fieldset](#fieldset-node) \\| [List](#list-node) \\| [Reading](#reading-node) \\| [Statement](#statement-node) \\| [Comments](#comments-node) \\| [Act](#act-node) \\| [Check](#check-node)) (at least one) | What the part draws, in reading order; its Acts stand at its foot. A Fieldset holds Fields under a heading of their own. A Check stated here guards the entity as one beside the parts does |\n\n<!-- generated:end node-side -->\n\nIt holds what a Section holds. A field it states, the status included, leaves the head and stays on list rows; the title stays in the head. Writes: its Fields and its Acts.\n\n## Outside node\n\nWhat one record shows, and which acts it allows, to a person with no seat who opens a link a member made of it. A member\npresses Create link on a record while its status stands in `at`; the link opens that one record until it expires, is\nrevoked, or its act moves the status out of `at`. The person sees the stated Fields and Lists and presses the stated Acts\nand nothing else. It stands directly in the Record of a table with a stored status select, whichever List over it opens the page.\n\n<!-- generated:start node-outside -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `key` | alias | Unique in the app: a link to the record names it. Absent, the title\'s words as a slug, written once and kept |\n| `title` | text, required | The heading of the page the person without a seat opens |\n| `description` | text | A line under the heading |\n| `at` | list of alias (at least one), required | Options of the record\'s status during which a link to it opens; none is owned by a stage, and each Act moves the status out of them |\n| `children` | list of (alias \\| [Field](#field-node) \\| [List](#list-node) \\| [Act](#act-node)) (at least one), required | Exactly what the link shows and allows: Fields read as values, Lists of child rows read as they are, and the Acts the person may press, each moving the status out of `at` |\n\n<!-- generated:end node-outside -->\n\n- **Fields** are read as values, in order; a lookup, a rollup or a formula is computed for the link only if stated here.\n A Field states nothing but its alias.\n- **Lists** read the child rows under the record as they are: `columns`, `label` and `where`.\n- **Acts** are the link\'s alone: no member, visitor or agent presses them. Each states `key`, `label`, `confirm`, `when`,\n `requires`, `asks`, `set`, `template` with `into`, or `sign`. `when` absent is the status held in `at`; `set` moves the\n status to an option outside `at`, so each press ends the visit. `asks` are text, numbers, dates or listed options. A\n `sign` is by a text field the signer types, with no witness: the link is the attestation.\n- `at` names options no stage owns, and no two Outsides of a table open during the same option.\n- **Writes:** its Acts, and nothing else.\n\n## Tab node\n\nA Tab is one view of a List\'s rows over a period: a register reporting a period \u2014 what stands at its end beside what came and went during it (the stock,\n the hires out, the tickets open) \u2014 reads its rows as Tabs over one `period` the reader picks above them. A Tab holds\n the rows `dated` within the period, those `open` at its end, or lists every row and draws what a child\'s rows came to\n in the period (`totals`). A Tab narrows its rows and holds no nodes; Readings stand beside it in the List and read the\n open Tab, or the one their `tab` names. Never date chips set by hand, and never a Tab per stage, which the chips split.\n Readings and Lists read apart from a List\'s rows stand on a Sheet, a View of the App\'s own.\n\n<!-- generated:start node-tab -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `key` | alias, required | Unique among its siblings; part of the node\'s address |\n| `label` | text, required | What the tab holds, in the reader\'s words |\n| `dated` | alias | A date: the tab holds the rows dated within the List\'s period |\n| `open` | [Tab open](#tab-open) | The tab holds the rows open at the period\'s end: begun, and not yet ended |\n| `totals` | [Tab totals](#tab-totals) | Each row\'s figures over a child\'s rows in the period |\n| `where` | [narrowing](#app-tree) | Only the rows whose select holds one of these options, whose yes/no is this value, or whose member field holds the reader (`{ "me": true }`) \u2014 every entry ANDed |\n| `sort` | [Sort key](#sort-key) \\| list of [Sort key](#sort-key) (at least one) | The order this tab\'s rows read in; absent, the List\'s |\n\n#### Tab open\n\n| Key | Type | Meaning |\n|---|---|---|\n| `from` | alias, required | The date a row begins on |\n| `to` | alias, required | The date a row ends on, empty while it is open |\n\n#### Tab totals\n\n| Key | Type | Meaning |\n|---|---|---|\n| `rows` | alias, required | An entity of this app whose rows each belong to one row of the register\'s entity: the rows the columns add |\n| `on` | alias, required | A date of the child placing each row in time: stored, a formula yielding a date, or a lookup of a date through a one-row link \u2014 never a moment or a span of days |\n| `columns` | list of [Totals column](#totals-column) (1\u20136), required | The figures drawn in place of the register\'s columns after each row\'s name, each under its own alias and label |\n\n#### Totals column\n\n| Key | Type | Meaning |\n|---|---|---|\n| `alias` | alias, required | The column\'s name: its address in the totals read |\n| `label` | text, required | What the column holds, in the reader\'s words |\n| `value` | alias \\| `{ "avg": alias }` | A number of the child (stored, a formula or a rollup) summed over the rows, or `{ avg }` averaged over the rows holding one, a window holding none drawing blank; absent, the rows are counted. A figure read in each row\'s own unit or currency stands only where the child\'s select is a lookup, through `via`, of a single select of the register\'s entity |\n| `where` | map of alias \u2192 (list of alias (at least one) \\| boolean) | Only the child\'s rows whose select holds one of these options, or whose yes/no is this value \u2014 every entry ANDed |\n| `window` | `"before"` \\| `"in"` \\| `"through"`, required | Which of the child\'s rows, by `on`, the column adds: `before` those dated before the period\'s first day, `in` those from its first day through its last, `through` those on or before its last day |\n\n#### Period days\n\n| Key | Type | Meaning |\n|---|---|---|\n| `days` | integer, required | How many days through today, at most 366 |\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `list.tabs` | A List\'s Tabs each have a `key` of their own, none the entity\'s alias or one a report template holds (`title`, `lines`, `readings`, `at`, `dates`, `period`, `per`); a Tab states one of `dated` and `open` (dates of its rows, `open`\'s two different) or `totals` (a child\'s rows windowed by the period); its `where` and `sort` hold as the List\'s do, and never narrow by the status, which its chips split. Only a table or cards List has Tabs, and a Reading\'s `tab` names one of them. A `period` opens a List on a window: over a table or cards a Tab that states `dated`, `open` or `totals` reads it; a calendar or a lanes board opens on `"today"`, `"week"` or `"month"` (a lanes board of hours, on `"today"` or `"week"`); no other layout draws one. Wrong: `period: "year"` over a table with no dated Tab. Right: a Tab stating `dated`, or no `period`. |\n| `list.tab-totals` | A Tab\'s `totals` name a child linked to the List\'s entity by a one-row link (a child linking the List\'s entity twice cannot be totalled), a date of the child, never a moment or a span, and 1 to 6 columns each under its own alias and label; a column\'s `value` is a number of the child, its `where` holds over the child\'s selects and yes/nos, and a value read in each row\'s own unit or currency stands only where that select of the child looks up, through its link, a single select of the List\'s entity, and the child links to no source\'s rows. A source\'s rows are totalled by the child\'s one link to them, by one field to one row; a source the child links to not at all totals nothing on its rows (`list.source-lacks`). Only a table List has them, and no Tab states `totals` beside `dated` or `open`. A column sums a number or counts rows, never `{ avg }`. |\n\n<!-- generated:end node-tab -->\n\nA `totals` Tab adds, per column, the child\'s rows `before` the period\'s first day, `in` the period, or `through` its last\nday, so `before` plus `in` of one value is its `through`:\n\n```json\n{\n "type": "Tab",\n "key": "items",\n "label": "Items",\n "totals": {\n "rows": "ledger_line",\n "on": "moved_on",\n "columns": [\n { "alias": "opening", "label": "Opening", "value": "quantity", "window": "before" },\n { "alias": "received", "label": "Received", "value": "quantity", "where": { "kind": ["receipt"] }, "window": "in" },\n { "alias": "issued", "label": "Issued", "value": "quantity", "where": { "kind": ["issue"] }, "window": "in" },\n { "alias": "closing", "label": "Closing", "value": "quantity", "window": "through" }\n ]\n }\n}\n```\n\n## Sheet node\n\nA Sheet is a grid of Readings and Lists over the App\'s rows in its `period`: each Reading a figure, each List the rows it lists. An App of one Sheet opens on it; an App of several draws a strip that picks one.\n\n<!-- generated:start node-sheet -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `key` | alias, required | Unique among the App\'s Views: the sheet\'s address, `/<key>` |\n| `label` | text, required | What the sheet holds, in the reader\'s words: its name among the App\'s Views |\n| `children` | list of ([Reading](#reading-node) \\| [List](#list-node)) (at least one), required | The Readings and Lists the sheet draws as a grid, in reading order: each Reading a figure over the App\'s rows in the App\'s `period`, each List the rows it lists |\n\n<!-- generated:end node-sheet -->\n\n## Field node\n\nA Field draws one field of the record it stands in. How it is drawn follows from the field\'s type and the table\'s facts:\n\n- a control or a value, with its notation, money, units and deadline countdown;\n- a files field as pictures and documents, a long or markdown text as prose written in place \u2014 a gallery or a prose block,\n with a heading (`label`) and a condition (`when`) of its own; a run of files Fields is one gallery;\n- a link as its row\'s chip, with a picker narrowed by `options_where`, offering a new row where the linked table\'s page\n states `add`;\n- the back side of a child\'s link as the rows filed under the record;\n- the fields an Act\'s `sign` writes as one signature.\n\n<!-- generated:start node-field -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `field` | alias, required | The field\'s alias |\n| `edit` | boolean | Shows a value nobody changes here: false, the field is drawn and read; absent or true, it is written where the table and the part holding it let a person write it. A field an Act\'s body writes is the Act\'s, read-only elsewhere and drawn once filled, unless the Field states `edit: true`, which keeps it a person\'s to edit |\n| `label` | text | The heading of the field\'s gallery or prose block, where it draws as one; absent, the field\'s label. A run of files fields takes the first one\'s |\n| `block` | boolean | Gives a field room of its own: true, a files, text or multi-select field draws as its own gallery, prose or checklist block, and a link to one row as that row drawn whole in place, as its page draws it; false: as a control among the part\'s fields. Absent, files and markdown fields draw as blocks, plain text, a multi-select and a link as a control |\n| `when` | [condition](#app-tree) | A gallery or prose block is shown only while the record\'s selects hold these options, its yes/nos these values, its numbers and dates meet their bounds and its `{ "empty": true \\| false }` fields are blank or filled |\n\n<!-- generated:end node-field -->\n\nA field drawn in the head (title, subtitle, picture, figure, stage) is never also a Field node. A Field is drawn once per\npage. **Writes:** the field, under `reference/app-tree`; a picker\'s add is the linked table\'s page\'s `add`.\n\n## Fieldset node\n\nA Fieldset heads a run of a part\'s Fields with a few words of its own: the facts of one kind among a part\'s many (a\nvehicle\'s plate, make and seats under "Vehicle"). It stands among a Section\'s or Side\'s children, or a one-part\nRecord\'s, and holds two or more Fields, each drawn as a control, each in one Fieldset. A Field in it reads and is\nwritten as it would be in the part. A gallery or prose Field stands beside it, never in it.\n\nWhere the arrangement itself is the need, it holds [Lines](#line-node) in place of Fields: each a line of cells stated\nleft to right. With `heads` its Lines read as the rows of a table under those headings. A Fieldset holds Fields or\nLines, never both, and its Lines hold at least one Field between them.\n\n<!-- generated:start node-fieldset -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `key` | alias | Unique among its siblings; part of the node\'s address. Absent, the label\'s words as a slug, written once and kept |\n| `label` | text, required | The heading over the facts it holds, in the reader\'s words |\n| `heads` | list of text (1\u20137) | One heading per column of its Lines \u2014 a line\'s label in the first, then its Fields and Values; the Fieldset then reads as a table, each Line a row whose one Act, stated last, is the row\'s action under no heading. A head may be empty |\n| `children` | list of (alias \\| [Field](#field-node) \\| [Act](#act-node) \\| [Line](#line-node)), required | Fields drawn under the label, in the order stated, each reading as it would in the part, or Lines of cells; the Acts it holds stand at its foot, taking every prop an Act in a part takes |\n\n<!-- generated:end node-fieldset -->\n\n## Line node\n\nA Line is one line of a Fieldset: up to six cells after its own optional `label`. A cell is a Field, an Act drawn in\nits cell (what it asks opens in its dialog), or a [Value](#value-node). A Field in a Line stays in its cell: an Act of\nthe part that asks it asks in its dialog too.\n\n- Without `heads` on its Fieldset, a Line of up to three cells stands on one line on a record\'s page and in the\n drawer a list opens it in; a longer Line stands two cells to a line, and a narrower screen two to a line, then one.\n A Field and a Value read under their own labels.\n- With `heads`, the Line is a row of a table: its `label` names the row under the first heading, each Field and Value\n stands under the next, and its one Act, stated last, is the row\'s action. Every Line of the Fieldset states a `label`\n or none does.\n\n```json\n{ "type": "Fieldset", "label": "Count", "children": [\n { "type": "Line", "children": [{ "field": "on_book", "edit": false }, "counted",\n { "type": "Value", "label": "Difference", "formula": "{counted} - {on_book}" }] } ] }\n```\n\n<!-- generated:start node-line -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `key` | alias | Unique among its siblings; part of the node\'s address. Absent, the label\'s words as a slug, written once and kept |\n| `label` | text | The words the line stands after, and its row header under `heads` |\n| `children` | list of (alias \\| [Field](#field-node) \\| [Act](#act-node) \\| [Value](#value-node)) (1\u20136), required | The cells, left to right, at most 6: a Field as it reads in a Fieldset, an Act drawn in its cell, or a Value |\n\n<!-- generated:end node-line -->\n\n## Value node\n\nA Value is a figure the screen works out from fields of the record and stores nowhere. A figure a List, a report or an\nExport reads is a formula field of the table (`set_tables`); a Value is for one a single screen shows. It follows a\nfield when that field is saved.\n\nIts `formula` reads `{alias}` fields of the record that hold text, a number, a date, a yes/no or one option \u2014 or a\ncomputed field yielding one \u2014 and names an option as `{field:option}`. It is refused where it reads the clock, a field\nof another kind, or a lookup through a link of several rows.\n\n<!-- generated:start node-value -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `key` | alias | Unique among its siblings; part of the node\'s address. Absent, the label\'s words as a slug, written once and kept |\n| `label` | text, required | What the figure is called, in the reader\'s words |\n| `formula` | text, required | The formula language over `{alias}` of the record\'s fields: text, numbers, dates, yes/no and single selects, or the result of a computed field of those; a function that reads the clock is refused |\n| `notation` | [notation](#number) | How a number figure reads: decimal, currency or a unit; only where the formula yields a number |\n\n<!-- generated:end node-value -->\n\n## Act node\n\nAn Act is a verb, stated whole where it stands. Its place decides what it works on:\n\n- in a Section or Side, or in a one-part Record: one record, at that part\'s foot;\n- in a List, with `on`: the ticked rows or every row in view, each checked before any is written;\n- directly in a Record that holds parts: refused.\n\n<!-- generated:start node-act -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `key` | alias, required | The act\'s name; its workflow is `act_<key>`, or the `workflow` it names |\n| `label` | text, required | The verb, as the reader says it |\n| `when` | [condition](#app-tree) | The act works only while this holds |\n| `requires` | list of alias (at least one) | Fields filled first, each drawn where the act stands |\n| `recommends` | list of alias (at least one) | Fields it runs without and reads when filled |\n| `asks` | list of (alias \\| `{ "field": alias, "starts": "today" \\| "me" }` \\| [Asked input](#asked-input)) (at least one) | What the reader states on pressing: fields of the row (written by the act) or inputs; a `link` input\'s picker adds as its entity\'s page `add` says |\n| `set` | map of alias \u2192 [value](#app-tree) | What the act writes; each field is read-only elsewhere in the app. With `over`, fields of the List\'s entity |\n| `over` | [Rows written](#rows-written) | The act writes the rows of a List of the record instead of the record: `set` states fields of that List\'s entity, a status moved as each row\'s own move; rows the presser cannot read are left out, and the press is refused while any row it writes is refused or it reaches more rows than one write takes |\n| `owner` | `"field"` \\| `"link.field"` \\| `{ "group": id }` | Who presses it: a member field of the row, `link.field` read through a one-row link, or `{ group }` by id. Absent, the owner of the stage it is offered at, or anyone the app is shared with where it stands at none |\n| `workflow` | alias | The workflow it runs for what `set` cannot say: one made under this name, its body set by `set_workflow`, or the app\'s Workflow node, taking the row as `record_id`; the act\'s guards head its body and hold the row it is pressed on; a row the body writes beyond it is the body\'s to check |\n| `template` | alias | A document template it makes a file from: html a PDF, excel a workbook, word a .docx; over several rows, one file of them all, an html paper hands each row its own lists under the names the record\'s paper uses |\n| `templates` | list of [Act template](#act-template) (at least 2) | Several papers made into `into`, instead of `template`: the reader ticks which |\n| `into` | alias | The record\'s files field keeping the document; remade, it replaces its own last paper, never a person\'s file |\n| `paper` | text | Its paper, `<child>.<kind>`: the line of the record\'s papers it stands on |\n| `intake` | alias | A child the record lists whose rows are its papers: the press takes papers, an agent reads them, each filed as a row of it. With `on: "view"`, they make a new record of the List\'s entity, and the save opens it |\n| `fills` | list of text (at least one) | With `intake`, what the papers may fill: a field of the record, `<link>.<field>` on the row a required one-row link names, or a child they add rows to; on a new record that row is found on its entity\'s `natural_key` or added. With `record`, fields of the new row an agent fills from the transcript |\n| `record` | [Recording](#recording) | The press records a call, visit or meeting, filed as a new row of a child the record lists |\n| `sign` | [Signature](#signature) | The press opens a pad; the act keeps the signature as a picture with who signed, when and the witness |\n| `review` | `true` | Lets a person approve what a workflow would write: with `workflow`, it only proposes a changeset of the act\'s table, and the reader ticks the rows to write |\n| `makes` | alias | The rows a record\'s `cadence` still owes of this child: the press lists them, each with what would stop it, and writes the ones ticked. Pressed again it lists only what is missing |\n| `confirm` | `true` \\| `"warnings"` \\| text | The press asks first: the question, or `true` for the act\'s label over the row; `"warnings"` asks only while a row it acts on holds a standing warning (an issue its entity declares in `records.issues`), listing it, and runs at once otherwise |\n| `danger` | `true` | The act destroys or cannot be undone |\n| `on` | `"ticked"` \\| `"view"` \\| `"none"` \\| `"period"` | Which rows an Act over a List works on: `ticked`, those ticked in the List holding it; `view`, every row in view; `none`, in a root List of a table: no row, the Act is handed only what it asks and stands at the List\'s title whatever rows are in view; `period`, in a root List drawn over days: no row, the Act is handed the first and last day of the period the List\'s window stands on (its day, week or month) as its workflow\'s inputs `from` and `to`, beside what it asks. Every Act a List holds states it, and no other |\n\n#### Rows written\n\n| Key | Type | Meaning |\n|---|---|---|\n| `list` | alias, required | The key of a List the record\'s page draws: its rows under each record the act is pressed on, as that List reads them |\n| `when` | [condition](#app-tree) | Which of those rows are written: a row outside it is left as it is; each written row is checked as a save of it is |\n\n#### Asked input\n\n| Key | Type | Meaning |\n|---|---|---|\n| `input` | alias, required | A value the act asks for that is not a field of the record |\n| `label` | text, required | What the reader is asked, in their words |\n| `type` | `"text"` \\| `"long_text"` \\| `"number"` \\| `"date"` \\| `"select"` \\| `"link"` \\| `"member"` \\| `"file"`, required | What the reader states. A `file` is one uploaded file, handed to the act\'s authored `workflow` as its file id and read by nothing else |\n| `options` | list of [Select option](#select-option) (at least one) | The choices a `select` input offers, one picked \u2014 written into a select holding the same option aliases |\n| `entity` | alias | The entity a `link` input picks one row of |\n| `accepts` | list of `"sheet"` \\| `"pdf"` \\| `"document"` \\| `"photo"` (at least one) | The kinds of file a `file` input takes; absent, a sheet, a PDF or a document \u2014 a phone offers its camera only where `photo` is among them |\n| `required` | `true` | The act is refused without it |\n| `default` | alias | A field of the row whose value the input starts from, still changed at will |\n| `starts` | `"today"` \\| `"me"` | Where the input starts, still changed at will: `today` a date, `me` a member, the reader; never beside `default` |\n\n#### Set formula\n\n| Key | Type | Meaning |\n|---|---|---|\n| `formula` | text, required | A formula over the acted row\'s fields, `{alias}` each, read as the entity\'s own formulas read them |\n\n#### Act template\n\n| Key | Type | Meaning |\n|---|---|---|\n| `template` | alias, required | A document template made into `into` |\n| `when` | map of alias \u2192 (list of alias (at least one) \\| boolean) | The paper starts ticked while each named select of the record holds one of these options and each named yes/no (stored, or a formula \u2014 how a multi-select is tested: `includes({needs}, {needs:x})`) is this value \u2014 a suggestion the reader changes, never a refusal; absent, it starts ticked |\n\n#### Recording\n\n| Key | Type | Meaning |\n|---|---|---|\n| `into` | alias, required | A child the record lists in a timeline or rows block, linking back by a single link: each recording is a new row |\n| `audio` | alias, required | The child\'s files field the recording\'s audio is kept in |\n| `transcript` | alias, required | The child\'s text field the transcript is kept in, a speaker\'s turn per line |\n| `video` | alias | The child\'s files field the screen is kept in, where the recording captured it |\n| `at` | alias | The child\'s date field stamped with the moment the recording started |\n| `by` | alias | The child\'s member field set to the person who recorded |\n\n#### Signature\n\n| Key | Type | Meaning |\n|---|---|---|\n| `into` | alias, required | The record\'s files field the signature is kept in, as a picture \u2014 each signing replaces the one before |\n| `by` | alias, required | Who signed: a text field the signer types into (someone with no seat), or a member field set to the person pressing |\n| `at` | alias, required | The record\'s date field stamped with the server\'s time as the act runs |\n| `witness` | alias | Beside a text `by`, the member field set to the person pressing, who saw the signer sign |\n\n<!-- generated:end node-act -->\n\nAn Act whose `when` does not hold is not offered. One whose `requires` are empty is offered disabled, naming each; one whose\n`recommends` are empty names what it will leave blank and still presses; one a standing Check blocks is offered disabled in\nits words. The `act_<key>` workflow re-checks all three on the server, writes `set` and what was asked,\nand appends the status history. A field an act both `requires` and `asks` never disables the press. A field an Act `requires` draws in its part with no statement. An Act in a child List may `sign` the row pressed.\n\n- **Writes:** every field it sets, asks, files into, signs or records is the act\'s.\n- **Papers.** A button that makes a paper is `template` (or `templates`) with `into` and no workflow, made from the row as the act left it. `templates` keeps a paper not made yet as a placeholder, and the set downloads as one archive (`archive_<key>`). `into` files the paper in the row\'s own files field, a write of the row its table\'s lock refuses; a `paper` line is a row of its own, made on a locked record. `intake`: what the papers state of each field `fills` names is shown beside what the row holds, and the save writes only what differs. `sign`: the record reads `into` as one signature, and the act\'s paper is handed the picture under `into`\'s name (`{{#each signature}}<img src="{{url}}">{{/each}}` in an html template).\n- **`review: true`:** the workflow (`workflows`) reads and returns a changeset of the act\'s table in `data.review`; the rows the reader ticks are written each checked first, all or none. Over every row in view the act is handed no rows.\n- **A `when` that compares** splits one stage by an amount or a date with no formula field behind it; the server refuses a press the row does not meet, and a blank number or date meets no bound:\n\n```json\n{ "type": "Act", "key": "approve", "label": "Approve", "when": { "status": ["submitted"], "amount": { "lte": 5000000 } }, "set": { "status": "approved" } }\n```\n\n```json\n{ "type": "Act", "key": "gate_in", "label": "Make the gate-in EIR", "template": "eir_in", "into": "eir", "sign": { "into": "driver_signature", "by": "driver_name", "at": "signed_at", "witness": "signed_before" } }\n```\n\n## Check node\n\nA Check is a yes/no or text formula of the row of the Record page it stands in (`pages/<entity>`): it stands while true or non-empty, and a text\nformula\'s words are what the reader sees. With `on` it refuses the saves and acts it names, on the server, in every write it names, and\nmay name any yes/no or text formula of its entity. With no `on` it names an issue the entity declares in `records.issues`, warns, and may\nstate the Act that `resolve`s it; a Check with neither is refused. A Check on a count never names `update` or `all`: the edits of its rows are what clear it.\n\n<!-- generated:start node-check -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `field` | alias, required | A yes/no or text formula of the page\'s entity \u2014 an issue it declares in `records.issues` where the Check states no `on` \u2014 or the count of rows a link lists that hold one |\n| `on` | `"all"` \\| list of (`"update"` \\| alias) (at least one) | What the standing issue refuses: `update` is the rows\' saves, an Act key is that Act \u2014 on one row, or over a List\'s rows of this entity \u2014 and `all` is every Act and save. A record\'s Acts are refused by a Check on the count its issues roll up from the rows it lists |\n| `resolve` | alias | An Act on one row of this entity that clears it. A Check states an `on` or a `resolve`: the declared issue stands without one |\n\n<!-- generated:end node-check -->\n\n`update` is the rows\' saves; an Act key is that Act, on the same rows; `all` is every act and save.\nA rule that refuses a Delete is a check of the table, not a Check: state it in the table\'s `checks` with `on: ["delete"]`\n(`reference/write-rules`), where it holds for every way a row is deleted and a removal that cascades to child rows is refused whole.\nA Check is stated once, on the entity it is true of. Absent `on`, the Check warns where its rows are listed; `on` names the acts it refuses. A record\'s Act is refused by the record\'s own Check on the count its rows\' issue rolls up (`records.issues` with `{ rows }`), never by `update` or `all`: it is judged on the stored count, with the record held while the Act runs. A List over rows of an entity with Checks offers one filter of the Checks some of its rows hold, but one that stops their edits or deletes, each with how many; picking one narrows the List to exactly those rows, through the address\'s filter on the check\'s field. `checks: false` offers none.\nA Check stands on each row of its page\'s entity wherever the App lists or opens it \u2014 a root List\'s, a child List\'s, a\nsource\'s \u2014 and refuses the acts and saves it names, an Act over a List\'s rows of the entity included. A warning reading the figure of a meter that `gates` marks against its\nbound or its pass mark is refused: the meter already draws it.\n\nThe check field\'s `label` is its short name \u2014 "Over budget", "Release expired": a row\'s line says it in the check\'s tone\n(the most severe of several, and how many more), while its words whole are the row\'s tooltip. Label it as the reader names\nthe problem, in a few words, and let a text formula say the sentence: the callout over the record says the label, then the sentence after it where it says more. A check with `resolve` carries the first of those Acts the row offers as a button at the end of its line, pressing as the Act itself; one with none links to the first field its formula reads that the record draws.\nA yes/no formula whose yes needs attention (papers the customer still owes) is a Check: its yes reads in the warning tone\nwherever it is drawn, every other yes in the success tone \u2014 and the row\'s line says it, so it is no column of the List too.\n\nA Check that every app over a table states the same way restates the table\'s contract and belongs in the table\'s `checks`\n(`reference/write-rules`).\n\nA Check refusing `update` (or `edit: false` on a record, part or field) makes the rows read-only in this app alone, drawn\nunder the read-only mark, never as a lock. A lock is the table\'s: a table workflow, a person, or an Act whose workflow sets `locked: true` on `update_records` locks a row, and every door refuses its writes until a table manager unlocks it \u2014 `update_records` with\n`locked: false` in an app\'s run is judged as the member who pressed. A locked row reads locked in every app: its lock mark, its fields as values\nunder one line naming who can change it, its saves, Delete and each Act writing it refused \u2014 an Act that writes\nelsewhere, makes a paper it hands back, or unlocks it stays its workflow\'s to answer.\n\n## Reading node\n\nA Reading is a number over rows: one figure, its parts, a grid, a figure per period, steps; or a record\'s own figure. The\npicture is the runtime\'s, chosen from what the reading means \u2014 no prop picks a chart. The question is stated by which\nsplit it names:\n\n| Names | Answers |\n|---|---|\n| nothing | one figure: the rows counted, or `value` summed, `{ "avg": \u2026 }` averaged |\n| `by` | the figure per value of a select, one-row link, member or yes/no, or per band of a number\'s `tiers` |\n| `by` a date field | the figure per period (a trend); `ahead: true` reads forward over the rows still to come |\n| `by` a date field and `across` | the figure per period, each period\'s bar stacked by the values of `across` (a select\'s options in their order, a number\'s bands lowest first) \u2014 counted or summed, never averaged |\n| `by` and `across` | a grid, `by` down the side and `across` along the top |\n| `steps` | a funnel: 2 to 8 number fields summed, each kept as a share of the one before; in a record only |\n| `planned` and `done` | the work against its plan, day by day: a List\'s band over a folder, or a record\'s block, never a Sheet |\n| no `entity`, in a Record | the record\'s own `value`, a tile under its field\'s label; up to eight consecutive tiles draw as one strip |\n\n<!-- generated:start node-reading -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `key` | alias | The reading\'s query name, unique in the app. Absent, the label\'s words as a slug, else its kind and field, written once and kept |\n| `label` | text | What the figure is called: absent, a split\'s `by` field\'s label, a trend\'s summed `value`\'s (else the rows\'), a grid\'s two fields\'; one figure states its label; with `planned`, always stated |\n| `entity` | alias | The List\'s rows; in a Record, the child\'s rows under it; absent in a Record with no `by`: the record\'s own `value`; with `planned`, the rows that are the parts of the work, always stated |\n| `via` | alias \\| text | The child\'s link to the record, where it has several; in a Record, a figure may state `<link>.<link>`, reaching the record through a row of their own |\n| `value` | alias \\| `{ "avg": alias }` | A number field summed over the rows, or `{ avg }` averaged over the rows holding one \u2014 a row with no number is no part of it, and a part or period where no row holds one reads blank, never 0. An average stands as a figure, per period (`by` a date) or per part (`by` a select, one-row link, member, yes/no or tiered number), never across a grid or beside `on_hand`; its parts add up to nothing: it states no total, and its rest reads the average of all the rows the rest holds. Absent, the rows are counted |\n| `where` | [narrowing](#app-tree) | Only the rows whose select holds one of these options, whose yes/no is this value, whose number or date meets its bounds (`gt`, `gte`, `lt`, `lte`; a date\'s `{ "now": true }` is read when the rows are), whose field is `{ "empty": true \\| false }`, or whose member field holds the reader (`{ "me": true }`) \u2014 every entry ANDed |\n| `by` | alias \\| [Tiered filter](#tiered-filter) | Splits the rows into parts; a date field splits them per period |\n| `across` | alias \\| [Tiered filter](#tiered-filter) | Reads a split against a second field: with `by` a field, the columns of a grid; with `by` a date, what each period is made of, its bar stacked by this field\'s values (counted or summed, never averaged) |\n| `over` | alias | The date that places a row in time |\n| `ahead` | `true` | Shows what is coming, not what has been: with a date `by`, the current period and those after it |\n| `steps` | list of alias (2\u20138) | Number fields summed, each a step of a funnel |\n| `on_hand` | [Reading on hand](#reading-on-hand) | With `by` (and `across`): the Reading\'s rows are what is owed, per value of those fields; drawn beside what is on hand per the same values, and the shortfall |\n| `target` | number | The number the figure is read against; absent, its bound, where the table states one |\n| `better` | `"up"` \\| `"down"` | Which way is good, for the figure\'s tone; absent, read from the figure\'s shape |\n| `planned` | [Reading planned](#reading-planned) | The days each row\'s work is planned over, its share planned spread evenly across them \u2014 a row missing either is no part of the plan, and neither line counts it |\n| `done` | alias | With `planned`, the work against its plan: a percent field of the row the server computes, its share done today (0\u2013100) |\n| `finished` | alias | A date of the row: the day its work was finished, from which it stands at its `done` |\n| `tab` | alias | The Tab it reads, else the open one |\n| `when` | [condition](#app-tree) | Drawn only while this holds |\n\n#### Reading on hand\n\n| Key | Type | Meaning |\n|---|---|---|\n| `entity` | alias, required | The entity whose rows are what is on hand, all of them |\n| `value` | alias | A number field summed over those rows; absent, the rows are counted |\n| `by` | alias | The field of this entity matching the Reading\'s `by`; absent, the same alias |\n| `across` | alias | The field of this entity matching the Reading\'s `across`; absent, the same alias |\n| `where` | [narrowing](#app-tree) | Only the rows whose select holds one of these options, whose yes/no is this value, whose number or date meets its bounds (`gt`, `gte`, `lt`, `lte`; a date\'s `{ "now": true }` is read when the rows are), whose field is `{ "empty": true \\| false }`, or whose member field holds the reader (`{ "me": true }`) \u2014 every entry ANDed |\n\n#### Reading planned\n\n| Key | Type | Meaning |\n|---|---|---|\n| `start` | alias, required | A date of the row: the first day of its planned work |\n| `end` | alias, required | A date of the row: the last day of its planned work |\n\n<!-- generated:end node-reading -->\n\n#### Kinds of reading\n\n<!-- generated:start reading-kinds -->\n\n| Kind | What it is |\n|---|---|\n| `metric` | A metric is one number over an entity\'s rows: how many, or the sum or average of a number field. It is read against a target, or against the bound its `limits` states; placed in time by `over`, it shows its change over the recent periods and which way is good (`better`). |\n| `breakdown` | A breakdown splits an entity\'s rows into parts: each row is counted, or its number summed or averaged, under the one value of the field it is split by \u2014 a select\'s option, a linked row, a person, yes or no \u2014 or under the band of a number cut by `tiers`. |\n| `trend` | A trend counts an entity\'s rows, or sums or averages a number of them, per period of the date that places each row in time (`over`) \u2014 the periods up to today, or with `ahead` the current one and those after it, over the rows dated today or later; with `split`, each period\'s count or sum stacked by the values of one field. |\n| `pivot` | A pivot crosses two splits in a grid: each row of the entity is counted, or its number summed, under the pair of values it holds \u2014 one down the side (`rows`), one across the top (`columns`). |\n| `shortfall` | A shortfall sets what is still owed against what is on hand: the owed rows are counted, or a number of them summed, per value of the fields they are for (`by`, and `across`), beside every row of the stock (`on_hand`) matching those fields, with what falls short. |\n| `progress` | A progress reads the work against its plan: each row is a part of the work, planned over the days between two of its dates and done by a share the server computes, set against the plan day by day. Each row weighs its planned days. |\n| `list` | A list shows an entity\'s rows, each in its `records` anatomy \u2014 its title, its line, its status \u2014 with the fields read after the title (`columns`). |\n\n<!-- generated:end reading-kinds -->\n\nWhere a Reading stands decides which rows: a Sheet\'s every row, a List\'s rows in its open tab and folder (the search,\nthe status and the filters narrow the rows and leave the figures as they stand), a Record\'s the child\'s rows under the record. A Reading counts its rows, or sums the number\n`value` names \u2014 never a percent. `over` is a date, the row\'s own or its parent\'s through a lookup: a trend\'s periods, a\nfigure\'s recent periods, and what a Sheet\'s period windows. `where` keeps rows whose select holds one of the options, or\nwhose yes/no is the value, every entry ANDed \u2014 a band leads with the job\'s exception as a formula\'s yes/no (what is\nshort), never a stage the chips already count nor the overdue rows the register\'s summary line counts from `records.due`.\n\n- **A figure\'s change** is green where it moves the good way: a sum\'s rise, a count kept by `where` falling; `better` states\n the other way where that reads wrong (money going out). A value `limits` bounds reads against the sum of its bound\n (`10 / 14`); `target` reads one against a number nothing bounds.\n- **An average** is its sum over the rows that hold a value, divided by how many hold one; a row holding none is no part\n of it, and where none holds one the figure reads a dash, never 0. Under a Sheet\'s period it is the average over the\n period so far, never a sum of averages. A share is an average too: a number formula that is `100` on the rows that count\n and `0` on the others, in percent notation, averaged. Only a single figure averages.\n- **Bands.** `by` and `across` each take, in place of a field, a number by its `tiers` \u2014 `{ "field", "tiers" }` \u2014\n splitting the rows by the bands those breakpoints cut: `[1, 31, 61]` over days late reads not due, 1\u201330, 31\u201360 and over\n 60, the aged report. Every band is drawn in the bands\' own order, one holding no row at zero; rows holding no number\n stand apart. On a List a band is a door: a press narrows the rows to it. In a List\'s band, a split by one or two\n breakpoints stands in it, and one by three or more stands whole under it.\n- **In a List,** Readings stand under the title in one compact band: the job\'s headline number first, then at most the mix\n and the movement. A picture stands only where it splits the rows in view into two parts or more, one holding two rows or\n more. The summary line already totals the figure and the chips count the rows, so a figure summing the figure, or counting\n the rows of a table with a stage, is refused unless its `where` narrows it.\n- **Name.** A Reading\'s `key` is the query it is read by (`run_app_query`).\n- **The work against its plan** (`planned` and `done`, `label` and `entity` stated) takes none of a figure\'s props: the\n share of the work planned and the share done, cumulative day by day, today\'s two at its foot. Each row is a part of the\n work, its plan spread evenly over its planned days and weighing its planned days. Its share done today is `done`, a\n percent the server computes; on an earlier day, its `done` from its `finished` day on and nothing before it.\n\n## Statement node\n\nA Statement draws a figure the record works out from its own figures \u2014 a claim\'s payable, an invoice\'s total, a payslip\'s\nnet \u2014 line by line in the order the arithmetic runs: each line a number of the record, the first stating no `op`, the last\nan `equals`. Every figure is a field the server computes or a person writes; the screen adds nothing up. A line\'s `parts`\nlists the rows its figure carries, each read from its own row, and that figure is what they add up to \u2014 a formula, rollup\nor lookup, or the server\'s copy when the record is made (`default_from`), which nothing writes after.\n\n<!-- generated:start node-statement -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `key` | alias | The statement\'s name, unique among its siblings. Absent, the label\'s words as a slug, written once and kept |\n| `label` | text | What the statement is called: absent, the label of what it comes to |\n| `lines` | list of [Statement line](#statement-line) (at least 3), required | The figures it is built from, top to bottom, ending in the one it comes to |\n| `when` | [condition](#app-tree) | Drawn only while this holds |\n\n#### Statement line\n\n| Key | Type | Meaning |\n|---|---|---|\n| `field` | alias, required | A number of the record \u2014 stored, a formula, a rollup or a lookup \u2014 read on the line after its label |\n| `op` | `"plus"` \\| `"minus"` \\| `"times"` \\| `"equals"` | How the line works on the lines above it \u2014 `plus`, `minus`, `times`, or `equals` for what they come to, a formula, rollup or lookup the server computes; absent on the first line, which the rest work from |\n| `rate` | alias | A percent of the record read after the line\'s label: the rate its figure is taken at (retention at 5 %) |\n| `parts` | [Statement parts](#statement-parts) | The rows the line\'s figure carries, each listed under it with its words and its own figure \u2014 read from those rows, never a copy of them. The line\'s figure is what they add up to, drawn read: a formula, rollup or lookup, or a value the server copies when the record is made (`default_from`) that nothing writes after |\n\n#### Statement parts\n\n| Key | Type | Meaning |\n|---|---|---|\n| `rows` | alias, required | The entity whose rows the line\'s figure carries \u2014 the record\'s own for the earlier rows of the same thing |\n| `same` | alias, required | A one-link the record and those rows both hold: the rows naming what the record names in it |\n| `at` | alias | A moment (a datetime) of those rows no person keys \u2014 when each was certified: with `before`, only the rows whose moment stands before the record\'s, earliest first; absent with it, every row so named, in their own order |\n| `before` | alias | A moment (a datetime) of the record no person keys \u2014 when it was made: the moment the rows\' `at` stands before; stated with `at` |\n| `where` | map of alias \u2192 (list of alias (at least one) \\| boolean \\| `{ "empty": true \\| false }` \\| [comparison](#values)) | Only the rows whose single select holds one of these options, whose yes/no (stored, or a formula) is this value, whose number or date meets its bounds, or whose field is empty or filled \u2014 read so on the server |\n| `columns` | list of alias (1\u20132), required | The rows\' fields read as each one\'s words, in order (its date, its percent) |\n| `figure` | alias, required | The rows\' number each one reads at the figures\' edge, frozen when the row was certified: a stored number an act fills (`{ "formula": \u2026 }` as it runs) or the server copies when the row is made (`default_from`) \u2014 never one a person keys, nor a formula, rollup or lookup the server recomputes |\n\n<!-- generated:end node-statement -->\n\n```json\n{\n "type": "Statement",\n "key": "claim",\n "lines": [\n { "field": "contract_value" },\n { "field": "done_to_date", "op": "times" },\n { "field": "value_to_date", "op": "equals" },\n { "field": "certified_before", "op": "minus", "parts": { "rows": "claim", "same": "contract", "at": "certified_at", "before": "made_at", "where": { "kind": ["work"] }, "columns": ["claimed_on", "done_to_date"], "figure": "certified_value" } },\n { "field": "claim_value", "op": "equals" },\n { "field": "retention", "op": "minus", "rate": "retention_rate" },\n { "field": "payable", "op": "equals" }\n ],\n "when": { "kind": ["work"] }\n}\n```\n\n## Comments node\n\nComments draws the record\'s comment thread: the platform\'s built-in comments, the same thread the table\'s record panel and a custom-code app show, so threads already written appear. It stands in a Section or the Side of a Record (or among a one-part Record\'s children), once per Record: two that differ are refused (`record.placed-once`). Presence is the opt-in: a Record with no Comments serves none, and the app\'s `comments` capability follows the node, never a tool. The thread is oldest first with a box under the last to write one; edit and delete are the author\'s alone; files already attached are shown, none are added here. Members only: a person outside the workspace sees none. A person reads the comments of any record of the table the app\'s record read reaches, narrowed by the App\'s `rows` where it states one \u2014 a List\'s `where` or a "me" chip is no row rule. A Record over a Query has no table, so no thread.\n\n<!-- generated:start node-comments -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `key` | alias | The thread\'s name, unique among its siblings. Absent, `comments`, written once and kept |\n| `title` | text | The thread\'s heading; absent, the word for comments in the app\'s language ("Comments", "B\xECnh lu\u1EADn") |\n| `when` | [condition](#app-tree) | Drawn only while this holds |\n\n<!-- generated:end node-comments -->\n\n```json\n{ "type": "Comments", "title": "Discussion" }\n```\n\n## Export node\n\nAn Export is a report file of the rows in view: the title, a line per chip, the search and the moment it was exported, the\nReadings, and every row, at most 20,000. With no props, the one Export is the workbook of the List\'s columns, the Readings\non a sheet before the rows. A List states the reports the business sends \u2014 one a button, several one menu \u2014 each a `label`,\na `description`, and a `template` filled with `title`, `lines`, `readings`, `at` (the moment it was made), `dates` (each\ndate filter\'s `from` and `to` by field) and the rows under the table\'s alias (an html one made a PDF, an excel one a\nworkbook). A report\'s `filename` names its file in the template grammar over the same keys but the rows. Where `per` is a\none-row link, `per_row.<field>` reads a text, number, date or yes/no field of the picked row, and `| add_days:<n>` shifts a\ndate by whole days (`n` a number or such a field, empty for none): `Stock {{per}} {{period.to | add_days:per_row.day_offset | format:"dd.MM.yyyy"}}`. A report of some\nrows (`where`), or of one value the reader picks (`per`: one file per value), is made of the List as those chips would\nnarrow it; the screen keeps the chips and rows it shows. A report sent outside the business \u2014 a partner\'s stock, a\nfiling \u2014 is `fixed`: the same file from every screen and device, of what the reader narrowed only the period and the\ndate chips reaching it, never their status, other chips or search.\n\nProve an Export with `run_app_query` and `export` (`agent_surface/exporting-a-file`): the answer is the file it makes.\n\n<!-- generated:start node-export -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `key` | alias | The report\'s name, unique in the app. Absent, the label\'s words as a slug, written once and kept |\n| `label` | text | The report\'s name; absent on the one Export that stands for the register\'s workbook |\n| `description` | text | What the report is for, in a sentence |\n| `template` | alias | An html or excel document template the report fills, with `title`, `lines`, `readings`, `at`, `dates`, `period`, `per` and `per_row` (a one-row `per`\'s picked row, the fields `filename` reads); absent, the workbook of the List\'s columns |\n| `filename` | text | The file\'s name, at most 500 characters, in the template grammar, over one value each: `title`, `at`, `dates.<field>.from` or `.to`, `period.from` or `.to`, `per`, `per_row.<field>` (a text, number, date or yes/no field of the row a one-row `per` picks), `lines \\| lookup:<n>`; `\\| add_days:<n>` shifts a date by whole days, `n` a number or `per_row.<field>`. Absent, the report\'s label |\n| `where` | [narrowing](#app-tree) | Only the rows whose select holds one of these options, whose yes/no is this value, or whose member field holds the reader (`{ "me": true }`) \u2014 every entry ANDed |\n| `per` | alias | A select, member or one-row link the reader picks one value of: one file of that value |\n| `sources` | list of alias (at least one) | Of the List\'s entity and its sources, the tables the report reads; absent, all |\n| `fixed` | `true` | The same file from every screen: only its `where`, its `per`, the period and the date chips narrow it, never the reader\'s status, other chips or search; absent, the rows in view |\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `list.export-report` | A List\'s Exports each have their own `label`; `per` picks one option, person or one-link row \u2014 never of the status, the folder or a field its `where` fixes. |\n| `list.export-key` | An Export is named by its key alone: no two Exports of an app share one. |\n| `list.export-filename` | An Export\'s `filename` is words and `{{value}}` placeholders, each value one of `title`, `at`, `dates.<field>.from` or `.to` (a date filter of the List), `period.from` or `.to` (a List with Tabs), `per`, `per_row.<field>` (a field of the row a one-link `per` picks) and `lines \\| lookup:<n>`, through helpers that exist and take the arguments given. |\n| `list.export-template` | A template an Export fills is an html or an Excel one (a Word register stays a workflow body) and reads at its root only `title`, `lines`, `readings`, `at`, `dates`, `period`, `per`, `per_row` (and `columns`, on a roster) and its rows under the List\'s entity alias \u2014 an entity named none of those \u2014 and is the document of no Act. |\n\n<!-- generated:end node-export -->\n\n## Query node\n\nA Query is a read for agents, never drawn. An app generates a query for everything its screen reads (`agent_surface` lists them); a Query declares one the screen never asks, called through `run_app_query` or the app\'s API: the\ntable whose rows it reads, the fields each row returns, and what narrows them.\n\n<!-- generated:start node-query -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `description` | text, required | What the query answers, read by whoever calls it by its alias \u2014 at most 300 characters |\n| `params` | map of alias \u2192 ([Workflow value](#workflow-value) \\| a typed input (`app_bindings`)) | What a call states, by name: with `rows` or `list`, values a `where` entry reads; with `ast`, typed inputs the ast reads as `{{params.<name>}} |\n| `fields` | list of alias (at least one) | The fields each row returns, by alias: with `rows` or `list`. `ast` states its own |\n| `sort` | [Sort key](#sort-key) \\| list of [Sort key](#sort-key) (at least one) | The order the rows return in; absent, the order the entity\'s list reads in |\n| `limit` | integer | The most rows returned |\n| `key` | alias, required | The query\'s name, what `run_app_query` calls; unique in the app |\n| `rows` | alias | The table whose rows it reads, under the app\'s row rule of it and, where the table holds one one-row link to the App\'s `scope`, inside the folder the call states. A Query states `rows`, `list` or `ast`, one of the three |\n| `list` | alias | The key of a root List of the App: the rows read as that List reads them \u2014 its `where`, its folder and its order. A Query states `rows`, `list` or `ast`, one of the three |\n| `ast` | a query tree (`app_bindings`) | The whole read, where `rows` or `list` cannot state it: a join, a union, a group, a window or a computed column. Fields and tables by alias |\n| `templates` | map of text \u2192 a document template (`app_bindings`) | Document templates an export of this query\'s rows may fill, by the name the export asks for. An export names one of these or none; a template it does not declare is refused. |\n| `where` | map of alias \u2192 [condition](#query-node) | What narrows the rows, as a List\'s `where` does: a select\'s options, a yes/no\'s value, a number or date meeting its bounds (`gt`, `gte`, `lt`, `lte`), a field `{ "empty": true \\| false }`, `{ "me": true }` on a member field \u2014 or a value the call states (`{ "param": name }`), or a date or number range of params (`{ "from": \u2026, "to": \u2026 }`) |\n\n#### Query param\n\n| Key | Type | Meaning |\n|---|---|---|\n| `param` | text, required | A param of this query: the condition holds what the call states for it, and is left out where the call states none |\n\n#### Query range\n\n| Key | Type | Meaning |\n|---|---|---|\n| `from` | [Query param](#query-param) | The param the field is on or after \u2014 a date\'s first day, a number\'s least |\n| `to` | [Query param](#query-param) | The param the field is on or before \u2014 a date\'s last day, a number\'s most |\n\n<!-- generated:end node-query -->\n\n```json\n{\n "type": "Query",\n "key": "fees_unbilled",\n "description": "A customer\'s fees no invoice covers yet, oldest first.",\n "params": {\n "customer": { "type": "record_link", "entity": "customer", "description": "The customer whose fees are read." },\n "since": { "type": "date", "required": false, "description": "Only fees charged on or after this day." }\n },\n "rows": "fee",\n "fields": ["visit", "service", "amount", "charged_on"],\n "where": { "billed": false, "customer": { "param": "customer" }, "charged_on": { "from": { "param": "since" } } },\n "sort": { "field": "charged_on" },\n "limit": 200\n}\n```\n\nAn entry of `where` holds what a Reading\'s `where` holds, or a value the call states: `{ "param": "<name>" }`. A required\nparam is always stated; one stating `required: false` may be left out, and the condition reading it then narrows nothing.\nA query reads under its table\'s read scope, as every read of the app does. A caller counts, sums or averages its rows\nwith `run_app_query`\'s `aggregate`. `set_app` compiles a Query with the rest of the app: no code is set.\n\nEvery Reading of the app is a query too, returning its groups, called by its key. A Tab\'s `totals` read is called by\n`<table>_totals_<tab>` with the period\'s two days, `from` and `to`, both required.\n\nA query reads one table: on an app whose List reads `sources`, it names a source\'s own table, never the\nList\'s. A param compares a field holding one value \u2014 or, as a range, a date or a number \u2014 and never a number read in each\nrow\'s own unit or currency, nor a date holding a span.\n\n## Workflow node\n\nA Workflow is a verb for agents, never drawn: a job no press of the screen starts \u2014 an agent or a service handing the app a\nfile, or a list of rows to reconcile a table against. It states what it takes and what it hands back; a table is named by\nits alias in `tables` and a select by `<table>.<field>`. It is called through the app, by `run_app_workflow` or the app\'s\nAPI. On an app shared by a public link it runs only for someone who holds the app, and a visitor\'s call is refused as an\nalias the app does not have.\n\n<!-- generated:start node-workflow -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `description` | text, required | What the workflow does, read by whoever calls it by its alias \u2014 at most 300 characters |\n| `inputs` | map of text \u2192 [Workflow value](#workflow-value) | What a call hands it, by name \u2014 checked before its body runs |\n| `outputs` | map of text \u2192 [Workflow value](#workflow-value) | What its body returns as `data`, by name \u2014 checked as it returns; absent, read off the body |\n| `key` | alias, required | The workflow\'s name, what `run_app_workflow` calls; unique in the app |\n\n#### Workflow value\n\n| Key | Type | Meaning |\n|---|---|---|\n| `type` | `"text"` \\| `"number"` \\| `"boolean"` \\| `"date"` \\| `"datetime"` \\| `"email"` \\| `"json"` \\| `"record_link"` \\| `"select"` \\| `"member"` \\| `"file"` \\| `"object"` \\| `"array"`, required | What the value is |\n| `description` | text | What the value is for, read by whoever calls the workflow |\n| `required` | boolean | Lets a caller leave the value out: false; absent or true, it is always there |\n| `multi` | `true` | A `record_link`, `select`, `member` or `file` holding several |\n| `entity` | alias | The entity a `record_link` names a row of |\n| `field` | text | `<entity>.<field>`: the select field whose options a `select` takes, as the field holds them when the workflow runs |\n| `options` | list of (alias \\| [Select option](#select-option)) (at least one) | The values a `select` takes, where no field holds them: aliases, or the objects a field\'s `options` take |\n| `fields` | map of text \u2192 [Workflow value](#workflow-value) | An `object`\'s values, by name |\n| `items` | [Workflow value](#workflow-value) | What each item of an `array` is |\n\n<!-- generated:end node-workflow -->\n\n```json\n{\n "type": "Workflow",\n "key": "reconcile_fees",\n "description": "Reconciles a visit\'s fees against the lines of the carrier\'s statement.",\n "inputs": {\n "visit": { "type": "record_link", "entity": "visit" },\n "statement": { "type": "file", "required": false },\n "lines": { "type": "array", "items": { "type": "object", "fields": { "service": { "type": "select", "field": "fee.service" }, "amount": { "type": "number" } } } }\n },\n "outputs": { "added": { "type": "number" }, "changed": { "type": "number" } }\n}\n```\n\nIts code is set on the app, never stated in the tree: `set_workflow` with a `source` whose `on({ type: "app", app_id, alias })` header names the app and the key, leaving\n`inputs` and `outputs` out \u2014 the code is checked against what the node declares. Every `set_app` keeps that code and holds\nwhat it takes, what it hands back and its description to the node. `set_app` keeps the code where it still meets a change\nof what the workflow takes or hands back; a change it does not meet is refused unless the same `set_app` carries the new\ncode in `workflows`, each as `set_workflow` takes it. With no code yet it refuses every call, and each `set_app` says so. A\nWorkflow the tree stops declaring is archived with its key.\n\n## Tasks\n\nA table whose `records` states `"task": true` \u2014 its status a stored select with `closed` \u2014 is work someone finishes.\nEvery List of its rows draws it alike, each row led by a ring. Ticking the ring moves the row to a closed option by the\none write the app already has for that move: the Act of that table setting a closed option, offered on an open row and\nasking nothing, else its own save where people write the status \u2014 stamping what that act stamps and appending the\nstatus history. Unticking runs the Act moving a closed row back, else the save back to the status\'s default. A move no\nwrite reaches leaves the ring disabled and the check notes it. An Act with `on: "ticked"` completes several at once.\n\nA record listing task rows filed under it by a link holding one row says how much of that work is done \u2014 those at a\nclosed option of all \u2014 wherever its row is drawn: a meter on its head, a column of its register\'s rows, a card\'s foot, a\ncalendar entry, a gantt\'s or a lane\'s bar. No rollup is stated for it.\n\n```json\n{\n "tables": [\n {\n "ref": "project",\n "label": "Projects",\n "singular": "Project",\n "fields": {\n "name": { "label": "Name", "required": true, "type": "text" },\n "lead": { "label": "Lead", "type": "member" }\n },\n "title": "name",\n "records": {}\n },\n {\n "ref": "task",\n "label": "Tasks",\n "singular": "Task",\n "fields": {\n "title": { "label": "Title", "required": true, "type": "text" },\n "project": { "label": "Project", "required": true, "type": "link", "table": "project", "multi": false },\n "assignee": { "label": "Assignee", "type": "member" },\n "status": {\n "label": "Status",\n "required": true,\n "default": ["todo"],\n "type": "select",\n "options": [\n { "alias": "todo", "label": "To do", "color": "slate" },\n { "alias": "done", "label": "Done", "color": "green" }\n ]\n },\n "due": { "label": "Due", "type": "date", "format": "date" },\n "done_on": { "label": "Done on", "type": "date", "format": "date" }\n },\n "title": "title",\n "records": {\n "subtitle": ["assignee"],\n "due": ["due"],\n "task": true,\n "starts": { "assignee": "me" },\n "status": { "field": "status", "closed": ["done"] }\n }\n }\n ]\n}\n```\n\n```json\n{\n "body": {\n "type": "App",\n "key": "projects",\n "name": "Projects",\n "color": "blue",\n "tables": { "project": "<id of the project table>", "task": "<id of the task table>" },\n "templates": {},\n "children": [\n {\n "type": "List",\n "entity": "project"\n }\n ],\n "pages": [\n {\n "type": "Record",\n "entity": "project",\n "children": [\n {\n "type": "Section",\n "key": "work",\n "title": "Work",\n "children": [\n "lead",\n {\n "type": "List",\n "entity": "task",\n "columns": ["due"],\n "children": [\n { "type": "Act", "key": "complete_all", "label": "Complete", "on": "ticked", "when": { "status": ["todo"] }, "set": { "status": "done", "done_on": { "now": true } } }\n ]\n }\n ]\n }\n ]\n },\n {\n "type": "Record",\n "entity": "task",\n "children": [\n { "type": "Act", "key": "complete", "label": "Complete", "when": { "status": ["todo"] }, "set": { "status": "done", "done_on": { "now": true } } },\n { "type": "Act", "key": "reopen", "label": "Reopen", "when": { "status": ["done"] }, "set": { "status": "todo", "done_on": null } }\n ]\n }\n ]\n }\n}\n```\n\nThe tasks as a register of their own, for one person: a one-part Record holds its Fields and Acts directly.\n\n```json\n{\n "body": {\n "type": "App",\n "key": "my_tasks",\n "name": "My tasks",\n "color": "teal",\n "tables": { "project": "<id of the project table>", "task": "<id of the task table>" },\n "templates": {},\n "children": [\n {\n "type": "List",\n "entity": "task",\n "opens": { "assignee": { "me": true } },\n "children": [\n { "type": "Reading", "label": "Open", "where": { "status": ["todo"] } }\n ]\n }\n ],\n "pages": [\n {\n "type": "Record",\n "entity": "task",\n "door": "drawer",\n "children": [\n "project",\n "due",\n { "type": "Act", "key": "finish", "label": "Finish", "when": { "status": ["todo"] }, "set": { "status": "done", "done_on": { "now": true } } },\n { "type": "Act", "key": "undo", "label": "Undo", "when": { "status": ["done"] }, "set": { "status": "todo", "done_on": null } }\n ]\n }\n ]\n }\n}\n```\n\n## App rules\n\nEvery rule the check enforces over an app, one sentence each under an id; a finding names its rule\'s id\n(`[list.filter]`), and `reference/<rule id>` is that one rule\'s page. A sentence names the node and the prop an author writes (`List.create`, a `Section`);\neach area stands in the tree where this table says:\n\n| Area | Stands at |\n|---|---|\n| `app` | what every write meets (the tree\'s keys, the names it declares, the tables and rows it carries), the App, and the register List\'s props that belong to the app: `words` (labels), `color`, `scope`, sources, the root Views |\n| `template` | the document templates an Act makes and an Export fills |\n| `list` | a List: its columns, filters, search, group, sort, layout, tabs, period, export, and what a child List holds |\n| `reading` | a Reading |\n| `record` | a Record and its parts: Section, Side, Act placement |\n| `statement` | a Statement |\n| `act` | an Act |\n| `check` | a Check |\n\n<!-- generated:start rules-app -->\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `app.schema` | Every key is one its table lists, holding the type its row gives, and every required key is stated. |\n| `app.names-declared` | Every alias a key names is declared: a table of the App\'s `tables`, a field of the table the node reads, an option of the select it names, an Act `key` of the App, a template of its `templates`, or an app. |\n| `app.record-home` | A Record stands in the App\'s `pages`, never inside a List: one page per entity, opened from the Lists over it. |\n| `app.spec-claims` | Every workflow a tree\'s screens run is one the app binds, taking each input the screens send. |\n| `app.spec-sound` | The app a tree compiles to reads every column its screens draw and carries what each needs: a tree refused for it meets a fault of the platform\'s, which is reported, and no change to the tree is owed. |\n| `app.compile-lowers` | Every screen, read and write a tree states lowers to the app\'s spec: a tree the compiler cannot lower is refused at the App. |\n| `app.tables` | A call declares at least one table and at most 50; send the rest in a second call. |\n| `app.rows-cap` | Rows are a sample: at most 200 per entity, 2000 per call and 2000 documents attached \u2014 a real data set goes in with `create_records` once the tables exist. |\n| `app.alias-scope` | An alias is unique where it is named: tables and fields in their table, options in their select. |\n| `app.label-unique` | A label is unique where it is found by its label: fields in their table, options in their select. |\n| `app.filter` | A filter \u2014 a view\'s, a rollup\'s \u2014 tests fields of the entity it reads, through links as `entity.field` hops each standing on the entity the last lands on, by options its select declares. |\n| `app.input-once` | The fields the App\'s saves, adds and Acts of a table send are each sent under one input name: a files or many-link field is sent as `<alias>_added` (and `<alias>_removed` by a save or an Act), so no other field of the write is so named, and none takes an input the workflow names itself, such as `record_id`, the input naming the row. |\n| `app.alias-unique` | An App\'s `key` is unique among apps, and an Act\'s among the Acts of its App, every List\'s included. |\n| `app.icon` | An App\'s `icon` is a Lucide icon name in kebab-case, as `receipt` or `trending-up` are. |\n| `app.add-label` | A List\'s `add_label` stands only where it adds rows (`create`), in words that are not empty and hold no `{` or `}`. |\n| `app.labels` | An App\'s `words` name a table it reads and a field or option of it, in words that are not empty and hold no `{` or `}`; no two fields of a table, nor two options of a field, show the same words. |\n| `app.records-entry` | Every table an App draws a List over, opens or picks from \u2014 a root List\'s, a child List\'s, a linked row\'s, a documents List\'s \u2014 has a `records` entry. |\n| `app.scope` | The App\'s `scope` names the table whose one row the app works inside (the folder), a table whose row rule can bind; every List over a table linking to it is filed in the open folder (`list.scope`). Stated again on such a List as a `columns`, `filters` or `search` entry, `group`, `where`, `opens`, a Field of a part, a `create` question or a report\'s `where` or `per`, its folder link is left out and said: the App already narrows every read to it and files every add under it. |\n| `app.folders` | The App\'s `folders` names a root List over the table its `scope` names: that List draws the folders the app opens on, and a row pressed is the folder entered. |\n| `app.when` | A node\'s `when` holds single selects to options, yes/nos to `true` or `false` (stored, a formula of one \u2014 a formula with `options` is a select \u2014 or, offering a node, a lookup through a link to one row), numbers and dates to bounds (`gt`, `gte`, `lt`, `lte`; a date\'s bound is a day, a moment on a datetime, or `{ "now": true }`) and any field but a yes/no to `{ "empty": true \\| false }` \u2014 a number read in each row\'s own unit or currency takes only the bound 0, and a lookup takes none. |\n| `app.asked-written` | What a List\'s `create` asks, what an Act\'s `asks` asks and what `starts` fills is a field a person writes \u2014 never a formula, rollup, lookup, autonumber or a date the workspace stamps. |\n| `app.own-rows` | A many-link to rows that each belong to one row of this entity is never a `create` question or an Act\'s `asks`: those rows are the record\'s own, each written by its own write. |\n| `app.create-asks` | A List\'s `create` asks fields a person writes \u2014 never the link or the folder it files the row under, which the add sets itself. |\n| `app.create-required` | A List\'s `create` asks every field its entity requires that nothing else fills \u2014 a `default`, `starts`, the record or folder it files the row under, or a `default_from` over a link it fills \u2014 or the server refuses every add. |\n| `app.row` | A Record\'s `row` states only what differs from `records`: a `subtitle` that is not the title, a number for its `figure`, dates for its `due`, an `image` that is a files picture no Act makes documents into, or `false` for a figure, deadlines or picture the entity states and the App draws none of. `row` changes what the head draws, never what the App writes (`record.edit-declared`). |\n| `app.restates` | *Noted, never refused:* A key the tree states that the platform sets the same without it \u2014 a `label` the table\'s or field\'s own, a `row.subtitle` the table\'s, a `door`, an add or a layout end the default gives, a row rule a status history inherits \u2014 changes nothing: the write keeps it and says so. |\n| `app.tasks` | *Noted, never refused:* A task entity an App lists whose rows no write of the App moves to a closed option (its ring stands disabled), or that an Act ticks done and none moves back. |\n| `app.same-list` | *Noted, never refused:* A root List over a table another App of the workspace lists at its root. Unnarrowed, every reader sees the same list, and a row\'s rail shows only that app\'s parts, so no one sees the whole path. A different job narrows with `where` and `columns`; a shared job stays one app, `owner` on its Acts and stages deciding who presses. |\n| `app.views-jobs` | *Noted, never refused:* An App of more than two Views, or a Sheet of more than six Readings, asks whether each is a job someone does on its own: Views of one job read better as one List\'s filters, tabs or Readings, and a Sheet reads at a glance with few. |\n| `app.tile` | *Noted, never refused:* An App that draws a List or a Sheet and states no `icon`, no `color` or neither: its launcher tile draws the glyph, or the colour, every App stating none shares, so the workspace\'s apps read alike. |\n| `app.workflow-value` | A value a Workflow takes or hands back states what its type needs and nothing another type does: a `"record_link"` its `entity`, a `"select"` its `options` or the `field` holding them \u2014 never both \u2014 an `"object"` its `fields`, an `"array"` its `items`; `multi` stands on a `"record_link"`, `"select"`, `"member"` or `"file"`; an output is never a `"member"` or a `"file"`; and a value nests at most 8 deep. |\n| `app.query` | A Query reads `rows` of one table \u2014 under the App\'s row rule of it and inside the open folder where the table holds one one-row link to the App\'s `scope` (one holding several is read through `list`) \u2014 or a root List\'s rows as that List reads them (`list`: its `where`, folder and order; never a List reading `sources`), one of the two; it returns them as `fields`, ordered by `sort` and bounded by `limit`; each param is a number, a yes/no, a date, a select, a one-row link or a member holding one, read by an entry of `where` on a field of its type \u2014 a date by a range, a number by either, and never a number read in each row\'s own unit or currency or a date holding a span. |\n| `app.generated-name` | A name the App makes is taken by nothing the App states: no Query, Workflow, Reading or List `key` is the name of a read or a workflow the App makes, an Act\'s own `workflow` among them; where the App makes two reads spelled alike, the later takes the next free ordinal (`_2`, `_3`). |\n| `app.surface-described` | *Noted, never refused:* A value a Workflow takes, and a param a Query takes, that states no `description`: the one line a caller reads to fill it. |\n| `app.keys-unique` | No two children of one node share a key: an address names one node. |\n| `app.states-list` | An App states a List whose rows it lists, only Sheets of Readings, or only Queries and Workflows for a server to call. |\n| `app.period` | An App\'s `period` is the window every Sheet opens on, so it stands in an App that holds a Sheet: a List states its own `period`. |\n| `app.dashboard-words` | An App that holds Sheets and no List reads every table\'s rows whole and states no `words` or `scope`: those are an App with a List\'s. |\n| `app.entity-once` | The App\'s Lists and their sources work a table one way: its rows ticked as tasks by the same moves, and their work counted by the same kinds of task rows. |\n| `app.add-filed` | The Lists adding rows of one table file them by one link: where two Lists add them by different links, each is refused naming the other\'s \u2014 state `create: false` on every List but the one whose link files them. Wrong: a List adding `booking` rows filed by `freelancer` beside one filed by `production`. Right: one states `create: false`. |\n| `app.adds-disagree` | Adds of one entity\'s rows hold a status that Acts move at the same stage. |\n| `app.check-field-unwritten` | *Noted, never refused:* A table the App updates or adds rows to, with an enabled check on that write naming a `field` the App writes nowhere in it (no Act asks, requires or sets it, no Record or add writes it), refuses every such write a person here makes: ask the field in the Act that moves the row, or draw it editable. A workflow may fill it, so it is said, never refused. |\n| `app.adds-field` | A picker\'s `add` names fields of its table a person writes, each once. |\n| `app.edits` | *Noted by the designer on a write, never refused:* The fields an app\'s saves may change are the fields its surfaces write \u2014 a record\'s save, a child row\'s, an in-place column, a lane, gantt or plan move \u2014 less what its own Acts change; the designer notes an app whose saves change none. |\n\n<!-- generated:end rules-app -->\n\n## Reading rules\n\n<!-- generated:start rules-reading -->\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `reading.value` | A Reading sums a number, never a percent \u2014 percents do not add up; a value of `{ avg }` reads one. |\n| `reading.average` | `{ avg }` averages a Reading\'s `value` over the rows holding one, read against a plain `target` \u2014 never a value `limits` bounds, whose bound is a sum. |\n| `reading.split` | `by` and `across` split by one value each row holds \u2014 a single select, a one-row link, one member or a yes/no, stored or a formula, a lookup through one-row links as the field it reads \u2014 or by the bands `tiers` cut a number read in one unit on every row; a date `by` splits them per period, as a trend, each period stacked by `across` where it states one; a grid crosses two different fields. Never by the select that sets the unit or currency of the number summed: its figure already reads once per unit. |\n| `reading.over` | `over` is a date: the row\'s own, stored or a formula, or its parent\'s through a lookup over a one-row link. |\n| `reading.where` | A reading\'s and a Query\'s `where` keep rows by a select\'s options, a yes/no\'s `true` or `false`, a number or date\'s bounds (`gt`, `gte`, `lt`, `lte`; a date\'s `{ "now": true }`), `{ "empty": true \\| false }`, or a member field, a lookup of one, or a member of the row a one-row link names (`<link>.<member>`), holding the reader (`{ "me": true }`); a List\'s `where` also keeps rows by `<link>.<field>`, a select or yes/no of the row a one-row link names; a Query\'s `where` also holds a field to what the call states (`param`, `from`, `to`). |\n| `reading.target` | `target` reads a value nothing bounds \u2014 a value `limits` bounds reads against the sum of its bound. |\n| `reading.better` | `better` needs `over`: a change is read over the periods its date places the rows in. |\n| `reading.progress` | A Reading stating `planned` and `done` (the work against its plan) reads dates of its rows for `planned` and `finished`, and a number for `done`. |\n| `reading.progress-alone` | A Reading stating `planned` or `done` is the work against its plan: it names its `entity` and states `planned` and `done`, with `finished`, `where`, `via`, `tab`, `when` and `label` beside them, and none of a figure\'s props (`value`, `by`, `across`, `over`, `ahead`, `steps`, `on_hand`, `target`, `better`). It stands in a List\'s band or a record, never on a Sheet. |\n| `reading.key` | A Reading\'s `key` is its query\'s name, and a List that only reads is called by its `key`, else its entity\'s alias: each its own among the App\'s Readings, Lists that only read and Queries. |\n| `reading.tabs` | A Sheet holds Readings and Lists, one at least; a Reading stands in a Sheet or in a List\'s band. |\n| `reading.restate` | *Noted, never refused:* A Sheet\'s count tile counting the rows a List beside it lists under the same `where` and tab, and a List\'s band counting its rows past a deadline, say what the List already draws: its head counts the first, its overdue chip the second. |\n| `reading.period` | An App\'s `period` stands only over a Reading placed in time by `over`. |\n| `reading.funnel-place` | A Reading with `steps` (a funnel) stands in a part of a Record: a band and a Sheet draw none. |\n| `reading.on-hand-split` | A Reading with `on_hand` compares what is owed with what is on hand per value of one field, or two: its `by` and `across` name fields, never bands. |\n| `reading.average-kind` | An average (`value: { avg }`) is a figure\'s, a trend\'s (`by` a date) or a breakdown\'s (`by` a select, one-row link, member, yes/no or tiered number): its Reading states no `on_hand` or `across`. |\n| `reading.via-path` | A Reading\'s `via` is a path (`<link>.<link>`, reaching the record through a row of the child\'s own) only on a Record\'s page, over a number, a split, a trend, a grid or a shortfall of the child\'s rows \u2014 never in a List\'s band or on a Sheet, nor on the record\'s own figure, a funnel or the work against its plan. |\n| `reading.grid-rows` | `across` splits a grid\'s columns, and stands only beside the `by` splitting its rows. |\n| `reading.band-off` | `readings: false` turns off the band a register leads with by default: a List stating it states no Readings, which are the band. |\n\n<!-- generated:end rules-reading -->\n\n## Statement rules\n\n<!-- generated:start rules-statement -->\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `statement.lines` | A Statement\'s `lines` are numbers of the record, each once \u2014 the first stating no `op`, every other one, the last an `"equals"` \u2014 each `"equals"` a formula, rollup or lookup, and a `rate` a number of the record. |\n| `statement.rows` | A line\'s `parts` read rows of an entity holding `same`, a one-link of the record\'s to the same entity; `at`, a moment of those rows, and `before`, a moment of the record (datetimes, never days), stated together; their `columns` and `figure` are those rows\' fields, the figure a number. |\n| `statement.parts-keyed` | A line\'s `parts` add up to its figure, so no person keys it: a formula, rollup or lookup, a value the server copies when the record is made (`default_from`) that no `create` asks and no save or Act writes, or a stored number the App\'s saves leave out \u2014 the line draws it read; each part\'s `figure` is frozen when its row was certified \u2014 a stored number an Act fills, the server copies or the App\'s saves leave out, never one a person keys or the server recomputes \u2014 and no person keys the moments `at` and `before` either. |\n\n<!-- generated:end rules-statement -->\n\n## Check rules\n\n<!-- generated:start rules-check -->\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `check.field` | A Check\'s `field` is an issue its entity\'s table declares in `records.issues` \u2014 a yes/no or text formula of the row, or the count of rows a link lists that hold one (`<link>_<issue>`). |\n| `check.of` | A Check stands in `pages/<entity>` and names an issue of that entity. |\n| `check.states-nothing` | A Check names an `on` or a `resolve`: a declared issue already stands wherever the row is drawn, so one that refuses and clears nothing adds nothing. |\n| `check.not-placed` | A Check\'s field is never also placed on the record as a Field \u2014 the line under the head says it. |\n| `check.on` | A Check\'s `on` names what it refuses: `"update"` (the saves), the `key` of an Act over the Check\'s entity \u2014 on one row or over a List\'s rows \u2014 or `"all"`. A record\'s Acts are refused by a Check of that record on the count its issues roll up from the rows it lists. It binds this App alone; a Delete is the table\'s checks\' to refuse. |\n| `check.resolve` | A Check\'s `resolve` names an Act of this App on one row of the Check\'s entity, not refused by the Check, and drawn as a button \u2014 never a correction. |\n| `check.restates-meter` | A warning reading a gated meter\'s figure against its bound or pass mark is refused \u2014 the meter draws it. |\n\n<!-- generated:end rules-check -->\n\n## List rules\n\nThe rules of a List\'s props and of what a child List holds. A layout\'s, a Tab\'s, an Export\'s and a desk\'s rules stand with their keys.\n\n<!-- generated:start rules-list -->\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `list.key-shape` | A List\'s key is not a record id\'s shape. |\n| `list.peers-read` | Root Lists over one table may state different `where`, unless one holds a `where` through a link, `sources` or a `plan` layout. |\n| `list.column-drawn` | A List\'s `columns` stand beside what the row draws itself: a column of its title, subtitle, picture, status, figure or meter\'s bound, of a child List\'s link back, or one named twice, stands once where the row seats it. |\n| `list.columns-budget` | *Noted, never refused:* A List\'s `columns`, each at the width of its kind, are told against the room a desk leaves beside its name and the row\'s own status, deadline and figure; what does not fit folds onto the name\'s line. |\n| `list.chips` | `chips: false` stops a register opening on status options. |\n| `list.filter` | A List\'s `filters` name a select, a member, a link, a date, a yes/no or a number of the List\'s own rows \u2014 a lookup through one-row links as the field it reads \u2014 never the status its chips draw, nor one `where` fixes; `values` only on a select, member or link. A List states at most 3; one drawn whole, as a plan is, up to 8. |\n| `list.filter-split` | *Noted, never refused:* A `filters` entry on a field a Reading of the List with `by` or `across` splits the rows by \u2014 a press on its part narrows by it too; a member\'s filter, which narrows to the reader\'s own rows, is never noted. |\n| `list.filter-unshown` | A `filters` entry of a List, a child List included, names a field its rows show: a `columns` entry, the row\'s title, line, picture, status, figure, deadline or meter\'s bound, the unit or currency a drawn figure is read in, a warning its line says, the group or lane it stands under, or a formula drawn where every field it reads is. A filter on a field no row shows is refused: make it a column or part of the row\'s line, or drop it. |\n| `list.narrow-unshown` | A narrowing the List `opens` on and a press in a Reading\'s band (a part, a grid cell, a figure\'s `where`) name a field its rows show, as a `filters` entry does (`list.filter-unshown`). A narrowing to the reader needs none. |\n| `list.tiers` | `tiers` band a number read in one unit on every row; a figure read in each row\'s own unit or currency is named bare. |\n| `list.search-undrawn` | *Noted, never refused:* A List\'s `search` matches all of a row\'s text, drawn or not: where a lookup, rollup, copy or link of its rows reads another entity under a row rule the List\'s readers are not all inside, it finds rows by text the List draws none of. |\n| `list.search` | A List\'s `search` names text, a code, or a link \u2014 matched by its row\'s title. |\n| `list.sort` | Each `sort` key of a List or a Tab names a field of the List\'s rows that holds an order \u2014 never files \u2014 and no field twice. |\n| `list.group` | A List\'s `group` names one value per row \u2014 a single select, a one-row link, one member, a date, a yes/no or a text, a lookup through one-row links as the field it reads \u2014 the status too, but never on a task list\'s block, whose chips narrow it; only a table or cards List groups, a gantt into its lanes, and a lanes board of days at one day; grouping by the title needs a `row.subtitle` to lead each row. |\n| `list.readings-own` | A Reading in a List reads the List\'s own entity; another entity\'s stands on a Sheet. |\n| `list.readings-bands` | A Reading in a List that bands a number by `tiers` has that field with the same tiers among the List\'s `filters`, which a press on a band narrows by. |\n| `list.readings-restate` | A Reading with no `by` in a List never sums the row\'s figure, counts the rows, or counts one stage\'s rows, unless it is placed in time (`over`): the summary line and the status chips already do, but draw no change against the last period. Instead, for the summed figure: a mix `by` a field or a sum under a `where`; for the rows counted: a sum of the figure under a `where`, a mix `by` a field or a yes/no in `where`. |\n| `list.where-opens` | A List\'s `where` and `opens` hold a select\'s options, a yes/no\'s value, a number or date\'s bounds (`lte`, `gte`; a date\'s `{ "now": true }`; a number read in each row\'s own unit or currency takes only 0) and `{ "empty": true \\| false }`; `opens` alone names the reader \u2014 a member field or a lookup of one holding `{ "me": true }`, or, on a status whose `stages` have owners, the rows waiting on the reader \u2014 and takes fields only, on the status only options. A field `where` fixes to options is never a filter nor opened otherwise, and `opens` stays among the options `where` keeps. A List laid out as a `plan` keeps its items by options and yes/nos alone. |\n| `list.roster` | A `layout: "roster"` List holds the List of its cells: the cells\' entity has one single link to this one and a date on its line (its own field, or a lookup of its parent\'s date); a roster draws no `columns`, and an `expect` stands only on the cells List. |\n| `list.roster-covers` | `covers` is a whole number from 1, only on a roster\'s cells List over days, never beside an `expect`. |\n| `list.roster-expect` | A roster cells List\'s `expect` is a single select of its rows, and its `of` this entity\'s multi-select whose every option is one of `expect`\'s. |\n| `list.source-page` | A source\'s entity states a Record page in the App\'s `pages`. |\n| `list.band-pivot` | *Noted, never refused:* A Reading with `across` (a grid) among a List\'s Readings: its grid reads on a Sheet, and the band leads with a figure (a Reading with no `by`). |\n| `list.headline` | *Noted by the designer on a write, never refused:* A List over rows that fall due or carry money and have no status whose steps the chips count, laid out as a table, cards or a gantt, has Readings \u2014 they split the rows by a field they show. |\n| `list.figures-lead` | *Noted, never refused:* A root List over a table holding a status, or a money field beside a date, to count or total states a Reading, or a Tab with totals, above its rows: what a person watches, as a figure or a chart. |\n| `list.title-only` | *Noted, never refused:* A root List whose rows draw their title alone: a subtitle, a figure, a status, a deadline, a picture, a face or `columns` says what each row is. |\n| `list.people-undrawn` | *Noted, never refused:* A root List drawn in columns, stating fewer than two besides the figure, where a table whose rows are people links to its table: the paired link holding several of them is not a column of it, or the link is not paired. |\n| `list.layout-call` | *Noted, never refused:* A root List that states no layout, over rows a board layout\'s own resolver resolves (a calendar, a gantt, lanes, or a roster of rows a `cadence` owes), draws a table; the note names each layout and its key. A deadline or a stamped date is never a day rows stand on. |\n| `list.lanes-overlap` | *Noted, never refused:* Lanes of dated rows by a link with no `no_overlap`. |\n| `list.lanes-order` | *Noted, never refused:* Lanes giving rows at a day, whose first ascending `sort` is no stored number the app writes. |\n| `list.where-bound` | A bound read from the record (`{ "record": \u2026 }`) in `where` narrows only a List that reads its rows \u2014 `same`, or `edit: false`. |\n| `list.where-reader` | A root List\'s `opens` names the reader (`{ "me": true }`), never its `where`. Wrong: `where: { crew_lead: { me: true } }` on a child List. Right: a row rule bounds access, or a root List over the entity states `opens: { crew_lead: { me: true } }`. |\n| `list.where-reader-path` | A path reader `<link>.<field>` names a one-row link and a member field of the row it links. |\n| `list.props` | A node states only its place\'s props: a List those of a root List, a roster\'s cells, a rows, agenda, timeline or read-only List of a record (which take every prop of a View but `sources`), a document or a Sheet; the Record of a List that opens no row in place and a source\'s entity page `entity`, `edit` and its children; a Sheet its `key`, `label` and children. |\n| `list.holds` | A List holds what its place draws: a root List its Tabs, Readings, Exports, Acts over ticked rows or every row in view, sources and, under a roster, the List of its cells; a child List its Tabs, Readings, Exports, Acts over ticked rows and, with `under`, the List of its documents; a Sheet its Readings and Lists. An Act on one row and every Check stand in `pages/<entity>`. |\n| `list.layout-place` | The register lays out as a table, cards, a calendar, a roster, a gantt, lanes or a plan; a child List writing its rows as cards (never nested as an outline), a table, checklist, desk or gantt; any child List as an agenda or timeline. |\n| `list.edit-column` | An edit column (`{ "field": \u2026, "edit": true }`) stands in a child List only: the register\'s rows are written where they open. |\n| `list.child-link` | A child List reads a child linked to the record; `via` names the link where the child links more than once. |\n| `list.row-blocks` | A List drawn as lines (`expect`, `under` or a desk) opens no row in place, so no List stands below its rows; a plain list of rows holds one. |\n| `list.title-back` | Where a child\'s title is its link back to the record, its first other `row.subtitle` names it there \u2014 a text, a code, a select, a link or a member, never a number or a date. |\n| `list.where` | A child List\'s `where` names single selects of the child by the options they hold (a row holding none stands in no such List; one held at a single option is never also a column), yes/nos by value, numbers and dates by bounds, and fields by `{ "empty": true \\| false }`. A yes/no, a bound or a blank is never held: a child List adds rows only at a stored yes/no\'s start, none under a bound or a blank, and never picks, expects or stands lines under documents. |\n| `list.under` | `under` names the child\'s one-row link to a document entity that pairs a many-link back and is read under this record by its one link; the lines\' columns never read the document (its heading does) nor hold long text. |\n| `list.under-once` | Documents drawn over their lines (`under`) are never listed again as a List of their own. |\n| `list.edits` | A child List\'s editable columns (`{ "field", "edit": true }`) name at most two of the child\'s columns or its figure that the App\'s saves write \u2014 a number, a date, a few words, one option or a one-row link, never a files or long-text field, the List\'s `via` nor a link it must name alike (a link\'s `same`) \u2014 never on an `expect` List. |\n| `list.remove-roster` | A roster cells List\'s `remove: true` offers the Delete of its rows, so it stands only over rows the App writes. |\n| `list.attention` | `attention: false` keeps a table\'s or cards\' rows in the List\'s own order; a calendar, lanes, a gantt and a roster stand their rows in time and lift none. |\n| `list.remove-documents` | The documents List inside a child List with `under` states `remove: true` only over documents the App writes. |\n| `list.compare` | A child List\'s `compare` names two different fields of the child, `before` and `after`: two files fields, or two values of one type (text but long text, a number, a date, a single select), never with `expect`. Over files on a checklist layout, `before` is the check\'s `photo`. Over values neither side is a column or something the row draws already, two numbers share a notation, no column is long text, and the layout is no checklist. |\n| `list.current` | A child List\'s `current` names a date or number of the child (stored, or a formula) that orders revisions: the latest row is current, the rest fold as superseded. Never with `group`, `under`, `expect`, `checklist`, `compare`, `desk` or `pick`, nor beside a column of long text. |\n| `list.pick` | A child List\'s `pick` links rows of the child through `via` \u2014 an optional one-row link a person writes, no Act writes, no other rule compares rows by and no `under` List stands lines under \u2014 paired with a many-link of the record its own save writes; the child\'s `read_scope` reads a row naming no record through `via`; never with `expect` or `under`, nor where the App\'s saves leave out the child or the many-link. |\n| `list.narrow` | A child List\'s `filters`, `search`, `group` and `sort` follow the register\'s rules over the child\'s rows, its status among them but on a task list (its chips); never on the link back or a select its `where` holds at one option, nor on an `expect` List; an `under` List is grouped by its documents. |\n| `list.expect` | `expect` names the child\'s title \u2014 a single select or a one-row link a person writes, never the link back \u2014 on a child added in the List; its `columns` name a field filled in place (not on a desk, whose lines are ticked) and its `create` takes the file where the child is pictured by one. |\n| `list.expect-fills` | An expected line is made from its key and its first filled column \u2014 a desk\'s from its key alone \u2014 so every other field the child requires has a default, a start or a `default_from`, or is read first. |\n| `list.expect-of` | An `expect` object\'s `of` or `only` needs a select: `of` names the record\'s multi-select of the title\'s options; `only` names options of a single select, never with `of` or a `where` on it, one List per option; an Act\'s `paper` is drawn in one. |\n| `list.post-option` | A desk\'s `text` formula names, as `{field:option}`, only options that select states. |\n| `list.funnel` | A Reading\'s `steps` (a funnel) are 2 to 8 numbers of its child, each named once \u2014 stored, a formula or a rollup \u2014 all in one notation, never a percent nor a unit read on each row. |\n| `list.list` | A read-only child List (`same`, or a Record that is `edit: false`) lists the rows of an entity that link to the record by its one link (`via` where it has several); with `same`, a one-row link of the record, it lists the rows sharing that link\'s row \u2014 the record left out \u2014 by the listed entity\'s one link to that row\'s entity (likewise `via`). `same` stands in a Record, never on a Sheet. Its Record\'s Fields \u2014 at least one, each a field of the listed entity named once, never its title nor a `columns` entry \u2014 are what an opened row shows, read-only. |\n| `list.figures` | A Record\'s own figures (Readings with no `entity` or `by`, whose `value` names the field) are 1 to 8 numbers of the record, each a tile. |\n| `list.create-boolean` | A document\'s and a roster\'s cells\' `create` is `true` or `false`: their add asks the table\'s defaults. |\n| `list.via-path` | A `<link>.<link>` `via` only reads rows, through a row of their own: a List writing its rows lists a child linked to the row it stands under. |\n| `list.beside` | `beside` opens a row beside a table: a root List drawn as a table states it, never a board, cards, a calendar or a List of a record. |\n| `list.create-empty` | A child List stating `create: true` asks the fields of its add (where the table\'s defaults ask none, state `create: false` or those fields); one stating no `create` adds none. |\n| `list.unworked-stage` | *Noted, never refused:* A register lists rows (every open one, else those its `where` keeps) at a stage no Act of the App is offered at and no Section stands at, though the App states the stages it works: keep them out with `where`, or leave them to the App working them. |\n| `list.under-note` | *Noted, never refused:* Rows holding a paper that cover another List\'s lines, listed apart with no add of their own stated: `under` draws them over the lines they cover. |\n| `list.expect-note` | *Noted, never refused:* Rows each a kind of paper, listed with no `expect` and no `where` on the kind, that no Act files a call into or `fills`: the missing lines read as what a record needs. |\n\n<!-- generated:end rules-list -->\n\n## Record rules\n\n<!-- generated:start rules-record -->\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `record.placed-once` | A child List, a Reading, a Statement, Comments and an Act each stand once in a Record; the same block stated in several Sections is that one placement, drawn in the first and said where repeated, and a repeat that differs from the first is refused; a set of papers stands where its Act does. A Field may be stated in several parts: parts that stack draw it once, parts a reader navigates each draw it. The head draws the title, line, picture, status, figure and the nearest open deadline, and a Field of a part standing there stands aside unless a person writes it in the part; what a Side states stands only in the Side. |\n| `record.check-lifted` | *Noted, never refused:* A Check stated inside a part guards the whole record, as one beside the parts does: it stands at the page, and is said. |\n| `record.foot-total` | A child List\'s foot totals the child\'s figure and each summed column over the rows it lists; the record\'s rollup summing that field over those rows (the same `where`) is that foot, never also a Field of a part. |\n| `record.section-holds` | A part without `at` (Section, Side) holds Fields, Fieldsets, child Lists, Readings, Statements, Comments or Acts; a Record\'s one Section stating only a `key` and a `title` is the platform\'s part, which draws the fields, papers and buttons no other part of it draws and is always shown. |\n| `record.platform-part` | *Noted, never refused:* A Section stating no children and no `at` beside a part that states a Field is the platform\'s part of its Record: it draws the fields, papers and buttons no other part of the record draws, and follows the table. |\n| `record.linked` | A link drawn as a block (`block: true`) is a link to one row of a table the App states a Record page of: the row stands in place as that page draws it. |\n| `record.fieldset` | A Fieldset stands in a part, or in a one-part Record, and holds two or more Fields drawn as controls, or Lines of cells \u2014 never a gallery or prose Field (`block`) \u2014 each Field in one Fieldset; an Act in a Fieldset or one of its Lines stands where it is stated, and is refused where its stage puts it at another part: it is stated at that part. |\n| `record.value` | A Value is a formula over fields of the record, computed on the screen and never stored: it names fields the entity holds that are text, numbers, days, yes/nos or single selects, or the one such value a computed field yields, and options its selects hold; it never reads the clock, and states a `notation` only where it yields a number, its currency or unit stated rather than read from a row. |\n| `record.value-held` | *Noted, never refused:* A Value whose formula is that of a formula field of the table computes on one screen what the table already holds for every list, report and export: said, and the field stated in the Line reads the same figure. |\n| `record.parts` | *Noted by the designer on a write, never refused:* A List laid out as a table, cards or a gantt opens a Record whose Sections hold the fields people write, a files Field per paper and the Acts no stage places, a Section per stage the status states (in option order) with the moves offered there at its foot, and a child List per child, a table\'s own rows that belong to a row of it included. |\n| `record.steps` | *Noted by the designer on a write, never refused:* A stage an Act is offered at alone that asks a field or files a paper holds something of its own: on a path (`closed`), its Section stands inside `Steps`. |\n| `record.lists` | *Noted by the designer on a write, never refused:* A table some App records, whose rows other rows each belong to (a one-row link to it, never its status history), draws some of them under its row \u2014 a child List in its Record, a List with `layout` roster or lanes by that link, or an App over them working inside one of its rows at a time (`scope`). |\n| `record.at` | A Section\'s `at` names options of the record\'s status; a record with no status has no steps. |\n| `record.steps-hold` | A Record that states `Steps` states every Section with `at` inside it, never beside it. |\n| `record.steps-path` | `Steps` stands on an entity whose status closes an option (`closed` on `records.status`): a status that closes none is a condition a person sets, and has no path. |\n| `record.edit-declared` | What an App writes of a row is what its Record declares: each Field its Sections state, the table\'s face (`records`: title, line, picture, figure, description) and, where the Record states no part, every field a person writes \u2014 each unless `edit: false` reads it \u2014 beside what an Act requires and a list of child rows its block writes. The head as `row` restates it (each part takes `edit: false`, read and never written), a column, an expected line, a `compare` and a layout\'s move draw a declared field with its control and never declare one: one naming a field no Section declares is refused. A tree stored before the rule rebuilds as it was. |\n| `record.edit-unseated` | *Noted, never refused:* A field of the table\'s face the `row` leaves out of the head, that no Section, column, layout or Act of the App writes, is written nowhere in this App: said, and a Section stating it makes it the App\'s to write. |\n| `record.beside-door` | A Record whose entity a root List opens `beside` its table states no `door`: the rows open beside the table. |\n| `record.key-clash` | A Record\'s List blocks, filed rows and links share one namespace of `key`s: none repeats but the same block stated again (`record.placed-once`), a List\'s default being its table, and a link\'s or a filed field\'s being its alias; a List and a link at one key, or one alias leading to two tables, is refused. Where unkeyed Lists over one entity stand in different Sections of a page, each takes its Section\'s key as its own, unless they are stated alike (one block stated again) or two stand in one Section, which nothing tells apart: those stay unkeyed. |\n| `record.side` | At most one Side stands in a Record, on a page `door`. |\n| `record.history` | No part of a Record reads the entity\'s status history (`status.history`): the rail reads each move. |\n| `record.section-acts` | An Act in a part works on the record itself; an Act over ticked rows or every row in view stands in a List. |\n| `record.move-home` | *Noted, never refused:* A status move offered at one step stands at that step\'s foot when it moves the work forward, to an exit, or back to a step the work passes \u2014 one a row starts at, or one an Act moves the work forward into or on from; one offered at several steps, or moving back into a step the work never passes, stands in the Section whose `at` holds the status it enters, as its way in. A move written in another Section, or in none, stands there and is said. |\n| `record.act-staged` | An Act at a staged Section\'s foot is offered only during that Section\'s steps: its `when` holds the status to options the Section\'s `at` names. A tree\'s Act with no `when` at the foot of a Section staged at one step is offered at that step and said; a correction stays offered at every step, and an exit is refused. |\n| `record.act-hidden` | An Act is never offered only while its part\'s `when` hides the part. |\n| `record.outside-place` | An Outside stands directly in a Record whose table states a stored status select, and its `key` is unique in the App: a link to a record names it. |\n| `record.outside-at` | An Outside\'s `at` names options of the record\'s status that no stage owns, and no two Outsides of a record open during the same option. |\n| `record.outside-field` | An Outside\'s Fields are read as values, each a field of the record shown once, never `edit`, `when` or a label of its own. |\n| `record.outside-list` | An Outside\'s Lists read the child rows under the record as they are: their `columns`, `label` and `where` only, never an add, a Delete, a pick, a filter, a search, a link that opens, or a bound read from the record. |\n| `record.outside-where` | An Outside List\'s `where` keeps the child rows by single selects held at options, yes/nos at values, numbers and dates between bounds, and fields by `{ "empty": \u2026 }`. |\n| `record.outside-act` | An Outside\'s Acts are its alone and each ends the visit: `when` holds the status to `at`, `set` moves it to an option outside `at`, `asks` are text, numbers, dates or listed options, `requires` names fields the Outside shows or the act asks, a `sign` is by a text field with no witness, and none states `on`, `workflow`, `templates`, `paper`, `intake`, `record`, `review`, `danger`, `recommends`, `me` or `confirm: "warnings"`, since a link reads no warnings. |\n| `record.holds` | A Record stands in the App\'s `pages`, once per entity some List of the app or of a Sheet is over, or whose rows a link the app draws names. Every Record holds the same: parts (Section, Side) or the Fields, Fieldsets, Lists, Readings and Statements of its one part, never both; beside either stand Outsides, Checks and Acts on one row; holding only those, the record\'s Sections are the platform\'s. The page of an entity whose rows a child List opens no row of in place (an agenda, a timeline, a read-only List) holds Fields alone. |\n| `record.remove` | A Record\'s `remove` deletes a row opened from a link; an entity a List lists is deleted as that List\'s `remove` says. |\n| `record.field-heading` | A Field drawn as a control states no `label` or `when`: only a gallery or prose Field (`block`) has a heading and a condition. |\n| `record.section-owners` | *Noted, never refused:* A Section holding acts offered at stages that different owners work \u2014 a role apiece, or a member field apiece \u2014 is two jobs in one: each owner\'s part is a Section of its own. |\n| `record.stage-field` | *Noted, never refused:* A field of a record with a status that only Acts offered at some of its stages write \u2014 no `create` asks it, no Field of the page draws it written \u2014 and that a Side or a Section shown at every stage draws, stands empty before those stages: it is stated in a Section `at` them, where it is the work then. |\n| `record.rows-repeated` | *Noted, never refused:* A Record that lists the same rows (a List of one table through one link) in two or more Sections lists them once, in the Section they belong to: a Section is one area of the record\'s data. |\n\n<!-- generated:end rules-record -->\n\n## Act rules\n\n<!-- generated:start rules-act -->\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `act.paper-note` | *Noted, never refused:* A made paper kept in a field of a record that lists its papers by kind: it is one of those lines. |\n| `act.moves` | *Noted by the designer on a write, never refused:* The rows of a root List of the App that a stored status stages towards `closed` options are moved by an Act of the App (on a page, a List or an Outside), or by its authored `workflow` \u2014 each open option moves to the next, the last to the first closed one. |\n| `act.set-not-asked` | A field an Act `set`s (an option, a value, `{ "now": true }`, `{ "me": true }`, an input) or `sign`s is the Act\'s outcome: the App\'s `create` never asks it, and a required one takes a `default`. A `formula` only starts a value, which a person may change after. |\n| `act.owner` | An Act\'s `owner` is a single member field of its row, a one-row link\'s member field (`link.field`), or `{ "group": <id> }` of a group the workspace holds: the press is that owner\'s, or the one standing in for them. An Act handed no row (`review`, `intake`, or over the list asking a person something) has no row to read a member field from, so its owner is a group. |\n| `act.owner-stage` | *Noted, never refused:* An Act that moves no status and is offered while the status holds a stage another member owns is pressed by that stage\'s owner: state its `owner` for someone else to press it. |\n| `act.owner-moves` | An Act stating `owner` moves no row off a stage another owner owns: the server refuses that move to anyone else, so the press would be refused. A move from an option no one owns is fine. |\n| `act.asks-set` | A field an Act `asks`, `set`s or `sign`s is stated by one of them: what the Act writes is its outcome, never also asked, and no field is written by two clauses of one Act. |\n| `act.starts` | `starts` (an ask `{ field, starts }`, or an input\'s own) starts what the Act asks for the reader pressing it, who changes it at will: `"today"` a date or a moment (never a span), `me` a member. |\n| `act.period` | An Act with `on: "period"` stands in a root List whose layout steps a window of days (a calendar or lanes board, not a table or a roster): it is handed the first and last day of the period that window stands on (its day, week or month) as its workflow\'s inputs `from` and `to`, so it asks no input of those names. |\n| `act.set-formula` | `set: { <field>: { formula } }` reads fields of the acted row and computes what the field holds \u2014 a number, a date, text, a yes/no or a single select\'s option (`{field:option}`), typed as the entity\'s own formulas are \u2014 never the status; a bound a write rule holds the field to is checked on the computed value as the Act runs. |\n| `act.set-formula-option` | A `{field:option}` token of a `set` formula names an option that select states. |\n| `act.of` | An Act in a child List works on that child: the one row pressed \u2014 or, with `on: "ticked"`, the rows ticked together where the record lists them as tasks \u2014 never the rows in view, nor none (`on: "none"` and `"period"` stand in a root List of a table). |\n| `act.writes-line-key` | An Act never writes the link or the key naming an expected line under its record \u2014 a line\'s key is stated by filling it. |\n| `act.makes-or-runs` | An Act makes a document (`template`, `templates`) or runs an authored `workflow`, never both \u2014 the workflow makes what it needs. |\n| `act.does-nothing` | An Act does something: it `set`s a value, `asks` a field, runs a `workflow`, makes a document, takes an `intake`, a `record` or a `sign`, or `makes` the rows a cadence owes. |\n| `act.view` | An Act over every row in view (`on: "view"`) writes (`set`), makes a document, runs a workflow or reads papers into a new record, and states no `requires` and no `confirm: "warnings"`, which holds no row in hand to warn. |\n| `act.requires-written` | A field an Act requires that only an Act writes is written by an Act offered together with it, or asked by the Act itself. |\n| `act.recommends` | A field an Act `recommends` is not also in its `requires`. |\n| `act.set` | `set` writes each field a value it holds \u2014 an option alias, a number, a yes/no, a text, `{ "now": true }` on a date, `{ "me": true }` on a member, `{ "input": "<name>" }` of an input the Act asks of the same kind \u2014 or clears an optional one with `null`. |\n| `act.into` | `into` is a files field of the one record the Act is pressed on, beside its `template` or `templates`. |\n| `act.paper-list` | A List a made paper names is one it can list: none keeps its rows by the reader, and no name is reached by a child List that writes its rows and one that only reads them, or by two of either, at once. |\n| `act.paper-list-field` | A List a made paper names is not also a field of the record, other than the link to those rows; an outline\'s rows are handed their depth as `level`, so they hold no field of that name. |\n| `act.paper-loop` | A loop of an html or Word paper that prints a field of each item runs over a link of the record or a table linking to it once (their rows are read under the app\'s row rules), or a List\'s rows \u2014 never over a link inside a child row, or one to rows the app cannot read, which a paper is handed as titles; over several rows an html paper holds the same one level inside `{{#each <alias>}}`, where each row is handed its own lists; a List\'s rows are looped for their fields, never printed whole; a loop runs over a name the paper is handed, never one it is not, which prints an empty table. |\n| `act.paper-cells` | A paper does not draw a cell for each title of a link inside the row of a List it loops over: the titles of a link line up with no column, so a cell packs left under the wrong date. Lay the rows out on a roster and export it, or draw a List. |\n| `act.paper` | `paper` is a kind the record lists its papers by, on one record \u2014 never beside `into` or `templates`; one maker per kind. |\n| `act.templates` | `templates` names each template once, kept in `into`, on one record pressed alone \u2014 never beside `template` or `asks`, in a child List, or with an `on` over several rows. |\n| `act.intake` | `intake` names a child the record lists in a child List with `expect` on its title \u2014 a single select, the paper\'s kind \u2014 and is narrowed by no `where`, holding exactly one files field and needing nothing an added line does not fill; the Act runs on one record (rows it finds by natural key need the link filing them under the record paired), or over the view (`on: "view"`) where the papers make a new record, states `fills`, and states nothing but its `label`, `when` and `requires` beside them \u2014 over the view no `when` or `requires`, the record has no row yet. |\n| `act.record` | `record` names a child the record draws in a timeline List or a child List with no `expect`, `under` or `where`, linking back by one single link, its row needing nothing the recording does not write: `audio` and `video` files fields, `transcript` text, `at` a date, `by` a member, each its own field; on one record, stating only `label`, `when`, `requires` and `fills` beside it. |\n| `act.sign` | `sign` runs on one record: `into` a files field, `by` a text field the signer types or a member field set to the person pressing, `at` a date, `witness` a member field \u2014 stated exactly beside a text `by` \u2014 each a field of its own that the Act does not also ask or set, and no other Act signs into `into`. |\n| `act.fills` | `fills` names each once, only beside `intake` or `record`. Beside `record`: a field of the recording\'s row the recording does not write, never a link. Beside `intake`: a field of the record, `<link>.<field>` on the row a required one-row link names (never beside that link), or a child the record adds rows of in a child List with no `expect`, `under` or `where`, filled in the fields its `create` asks \u2014 every one a new row needs among them. Each field filled is one a person writes \u2014 text, a number, a date, a yes/no, options or a single link\'s row \u2014 never a status, a field an Act writes or a link `same` narrows; a link\'s row is one the App reads of its entity. Over the view the papers make a new record, so `fills` names every field the record requires that nothing fills itself \u2014 the review asks the ones no paper states \u2014 and the row a required one-row link names is found on its entity\'s `natural_key` once `<link>.<field>` fills every field of it, left as it is, else added with the fields filled, so `fills` names each field that row requires too. |\n| `act.fills-drawn` | *Noted, never refused:* A field `fills` writes that the record draws nowhere: the review shows the change, the record does not. |\n| `act.fills-new` | *Noted, never refused:* A child `fills` adds rows of, whose natural key the papers cannot state: every row read is added, so the same papers read twice list them twice. Over the view, so is the row a required link names where the papers fill no natural key of it. |\n| `act.input` | An input has a name of its own \u2014 never another ask\'s, a field the act sends under that name (one it asks, one a `set` takes from an input, a typed `sign.by`, a `requires`), `sign.into`, or the record input its workflow takes (nor `approved` beside `review`) \u2014 `options` exactly when it is a select, `entity` exactly when it is a link, and a `default` field holding what it states, or `starts`, never both. An input starts empty, from its `default` or its `starts`, and never reads, shadows or overwrites a field of the row: an act that adds a subtask may ask `name`, though the row has a `name`. A `"file"` input is read by the Act\'s authored `workflow` alone, starts empty, and is never written into a field by `set`. |\n| `act.review` | `review: true` stands beside an authored `workflow` on an Act over the record, the ticked rows or every row in view (never on a List reading `sources`), never beside `set`, `template`, `templates`, `intake`, `record`, `sign` or `confirm`, nor in a child List, and it asks inputs only, none named `approved`. Its workflow is that Act\'s alone, run by no other Act. The workflow calls only steps that read \u2014 no agent \u2014 and returns a changeset of the entity\'s table in `data.review`, the same for the same inputs and rows; the platform writes the rows `approved` names, each only while the run proposes it as the caller read it. Over every row in view (`on: "view"`) it is handed no rows and states no `when`: its workflow reads the rows it may change, whatever the view is narrowed to, and no bound on a run\'s rows applies. |\n| `act.over` | `over` names a List the record\'s page draws \u2014 in a Record\'s Act or a List\'s `on: "ticked"` Act, never `on: "view"` nor in a child List \u2014 whose entity links to the Act\'s, read through that List\'s one link, `same` and `where` (never one that keeps rows by the reader, nor an outline) and narrowed by `over.when`; the Act states `set` and nothing but `label`, `when`, `requires`, `owner`, `confirm`, `danger` beside it. `set` states fields of the List\'s entity a person writes, each a fixed value, `now`, `me` or an option \u2014 no formula or input \u2014 and every row written is checked as a save of it is \u2014 a `set` of its status as that move on its own row, from-stages and stage owner \u2014 before any is written. Rows the presser\'s row rule hides are not read, and a press reaching more rows than one write takes is refused. |\n| `act.makes` | `makes` names a child that the Act\'s entity states a `cadence` for, in a Record or in a List with `on: "view"` or `"ticked"` that is not a child List; never beside `set`, `workflow`, `template`, `templates`, `intake`, `record`, `sign`, `review` or `of`. The app lists the child\'s rows in a List, and every field of the child that the cadence does not fill and that a row requires has a `default_from`, a `default` or an autonumber, since the app writes the child. The child states a `unique` of its link to the parent and the `planned` date (the day its cadence fills, where the cadence states no `planned`), so two presses at once make a day once, and the cadence states `start` where the child\'s first date holds a moment. |\n| `act.workflow` | An Act\'s authored `workflow` body parses once the guards the Act states are placed above it: the code is the author\'s, the guards above it the platform\'s. A declared Workflow an Act runs takes the row pressed as `record_id` (a required record_link to the act\'s rows), is run by that one Act, over one row, which asks only its inputs and states no `set`, papers, `intake`, `record` or `review`. An authored `workflow` is one Act\'s. Where a Check on the count its issues roll up refuses the Act, the workflow holds the record as one transaction and so cannot mail, notify, run an agent or wait. |\n| `act.set-tagged` | An Act\'s `set` states the moment as `{ "now": true }`, the person pressing as `{ "me": true }` and an input as `{ "input": \u2026 }` \u2014 never the strings `"now"`, `"me"` or `"input:\u2026"`. |\n\n<!-- generated:end rules-act -->\n\n## Template rules\n\nThe rules of the document templates an Act makes and an Export fills.\n\n<!-- generated:start rules-template -->\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `template.kind` | An Act\'s `template` is an html, excel or word document template and an Export\'s `template` an html or excel one, never an email or pdf-form one. |\n| `template.marker` | Every marker of a Word template an Act makes is filled by that Act: a field of its entity, or a list of the child rows its record lists (the entity\'s own alias over several rows). |\n| `template.act` | *Noted, never refused:* In an App none of whose Acts runs an authored `workflow`, every html, excel or word template is made by an Act (`template`, `templates`) or filled by an Export \u2014 the note names the app over the table whose fields it prints most, where the Act belongs. |\n\n<!-- generated:end rules-template -->\n\n## What the workspace remembers\n\nThe workspace holds every table, field and select option under an id that never changes, whatever its\nlabel or alias becomes. `set_tables` answers each table\'s id, and an\napp\'s body names tables and templates by those ids, so a relabel on either side is a rename and no body\npoints at another table by accident.\n\nA table `set_tables` refuses to write, or an id the workspace no longer holds, is a refusal by name. `set_tables` with `{ table_id, restore: true }` puts a deleted table back.\n\n## A complete workspace\n\nTwo main entities, so two apps: a sales desk over the orders, where an order is taken and shipped, and an account review\nover the customers, where an account manager reads each customer by tier. What belongs to a row is a child List on that\nrow\'s page, never another app or a Tab: a customer\'s orders are on the customer\'s page, and each order is also a row of\nthe sales desk, one record with one page (`app_architecture`).\n\nOne `set_tables` call makes both tables: each item carries a `ref`, and a link names the table it points\nat by the `ref` of the other item. Its answer carries each table\'s id. One `set_app` call then makes each\napp, `{ "body": \u2026 }`: the tree\'s root names the app by its `key` and `name`, and the tables it uses in `tables` by those ids,\nshown here as placeholders to replace.\n\n```json\n{\n "tables": [\n {\n "ref": "customer",\n "label": "Customers",\n "singular": "Customer",\n "fields": {\n "name": {"label": "Name", "required": true, "type": "text"},\n "logo": {"label": "Logo", "type": "files"},\n "tier": {\n "label": "Tier",\n "default": ["standard"],\n "type": "select",\n "options": [\n {"alias": "standard", "label": "Standard", "color": "slate"},\n {"alias": "gold", "label": "Gold", "color": "amber"}\n ]\n },\n "orders": {"label": "Orders", "type": "link", "pair": "customer", "table": "order", "multi": true},\n "total_ordered": {"label": "Total ordered", "type": "rollup", "via": "orders", "op": "sum", "field": "amount"}\n },\n "title": "name",\n "records": {"image": "logo", "party": "organization", "figure": "total_ordered"}\n },\n {\n "ref": "order",\n "label": "Orders",\n "singular": "Order",\n "fields": {\n "code": {"label": "Order no.", "type": "text", "unique": true},\n "placed_on": {"label": "Placed on", "type": "date", "format": "date"},\n "amount": {"label": "Amount", "type": "number", "notation": {"style": "currency", "currency": "VND"}},\n "total": {\n "label": "Total with VAT",\n "type": "formula",\n "expression": "{amount} * 1.1",\n "notation": {"style": "currency", "currency": "VND"}\n },\n "customer": {"label": "Customer", "type": "link", "pair": "orders", "table": "customer", "multi": false},\n "note": {"label": "Note", "type": "text"},\n "stage": {\n "label": "Stage",\n "default": ["draft"],\n "type": "select",\n "options": [\n {"alias": "draft", "label": "Draft", "color": "slate"},\n {"alias": "confirmed", "label": "Confirmed", "color": "blue"},\n {"alias": "shipped", "label": "Shipped", "color": "green"}\n ]\n }\n },\n "title": "customer",\n "records": {\n "subtitle": ["code", "placed_on"],\n "figure": "amount",\n "status": {"field": "stage", "closed": ["shipped"]},\n "starts": {"placed_on": "today"}\n }\n }\n ]\n}\n```\n\n```json\n{\n "body": {\n "type": "App",\n "key": "account_review",\n "name": "Account review",\n "color": "blue",\n "tables": {"customer": "<id of the customer table>", "order": "<id of the order table>"},\n "templates": {},\n "children": [\n {\n "type": "List",\n "entity": "customer",\n "columns": ["tier"],\n "children": [\n {"type": "Reading", "key": "ordered_by_tier", "by": "tier", "value": "total_ordered"}\n ]\n }\n ],\n "pages": [\n {\n "type": "Record",\n "entity": "customer",\n "children": [\n {"type": "Section", "key": "account", "title": "Account", "children": ["tier"]},\n {\n "type": "Section",\n "key": "orders",\n "title": "Orders",\n "children": [{"type": "List", "entity": "order", "columns": ["total"], "create": ["code", "amount"]}]\n }\n ]\n }\n ]\n }\n}\n```\n\n```json\n{\n "body": {\n "type": "App",\n "key": "sales_desk",\n "name": "Sales desk",\n "color": "violet",\n "tables": {"customer": "<id of the customer table>", "order": "<id of the order table>"},\n "templates": {},\n "children": [\n {\n "type": "List",\n "entity": "order",\n "filters": ["customer"],\n "create": ["code", "customer", "placed_on"],\n "children": [\n {"type": "Reading", "by": "placed_on", "value": "amount"}\n ]\n }\n ],\n "pages": [\n {\n "type": "Record",\n "entity": "order",\n "door": "drawer",\n "children": [\n {\n "type": "Section",\n "key": "order",\n "title": "Order",\n "children": [\n "note",\n {\n "type": "Act",\n "key": "confirm",\n "label": "Confirm",\n "when": {"stage": ["draft"]},\n "set": {"stage": "confirmed"}\n },\n {\n "type": "Act",\n "key": "ship",\n "label": "Ship",\n "when": {"stage": ["confirmed"]},\n "set": {"stage": "shipped"}\n }\n ]\n }\n ]\n }\n ]\n }\n}\n```\n\nThe account review leaves the door a record opens through and the rows it opens in to the system, each the default the\ntable\'s facts give; the sales desk states a drawer. Each List names what its add asks (`create`). The customer\'s orders are a block in its "Orders" section, never its own `Orders`\nlink as a field as well: one fact, one place. An order is titled by its customer and read by its number under it; the\nList names what its add asks, since a subtitle or a figure is never asked by default. `Total ordered` is a rollup, so it\nis read and never asked; the sales desk\'s record opens in a drawer, because its rows are worked one after another. An\norder\'s `stage` is its status (`records.status`), moved only by the app\'s acts: they set it, so the app\'s saves leave it\nout, each act names the stage it is offered at (`when`) and the one it sets, and the register opens on the orders not yet\nshipped (`closed`).\n';
|
|
1886
|
+
var reference_default = '# Tables and apps\n\nThe tables of a workspace and the apps over them, each a JSON document. A table is a document, an item of\nthe tool `set_tables`: its fields, options, how a row is recognised, and the rules its writes\nfollow. An app is a tree of components, the `body` of the tool `set_app`: its Views \u2014 Lists of rows and Sheets of\nreadings \u2014 and the page each table\'s rows open. Each section is its own page, `reference/<section>`.\nWhich treatment each job\'s screen needs: the `design` reference. Each treatment worked through in an\napp: the `examples` reference.\n\n**What the documents compose with**\n\n- **Tables and fields** (`reference/tables`, `reference/read-scope`, `reference/field`) \u2014 a table\'s columns, options and links. A table document sits\n in the `tables` list of a `set_tables` call; a field sits under its alias in the table\'s `fields`.\n- **Records** (`reference/records`, then `reference/status`) \u2014 how a row of each table is RECOGNISED: its title, the line\n under it, its picture, its status, the one number it stands for. Stated once per table\n and read by every surface that draws one of its rows.\n- **Write rules** (`reference/write-rules`) \u2014 what a write finds, bounds and picks among.\n- **Apps** (`reference/app-tree`, then a page each) \u2014 the Lists and Sheets at the app\'s root, each a View of its own, and the\n page each table\'s rows open: which fields go where, the acts, and the checks that guard them.\n How each thing LOOKS is the runtime\'s, one treatment per concept; no prop here changes it.\n A screen the job needs and no component states is told to the person \u2014 the job, what the app\n drew, the word wanted \u2014 never props bent to approximate it.\n\n**The working order**\n\n1. The tables and fields the jobs touch, and a `records` entry for every table an\n app lists, opens or picks. Which apps a business needs is `app_architecture`.\n2. One `set_tables` call with the tables: a link names the table it points at by the `ref` of another\n item of the call, and the answer carries every table id and the aliases of the fields it added. A\n call carries at most 50 tables, 200 first rows a table, and 2000 rows and 2000 documents in all; more\n tables go in a further call, which names the earlier tables by alias. A call is checked whole and writes\n nothing when refused, listing everything wrong; `dry_run` is for reading the grants a write would make or\n deciding `force`.\n3. One `set_app` call per app. The tree names its tables and document templates by alias wherever it points at one;\n the App node\'s `tables` and `templates` maps are filled by `set_app`, never written.\n `set_app` with the tree as `body` creates the app, named by its `name`; a refused tree writes nothing and is listed whole, and `dry_run` is for reading the permissions the write\n would grant and remove (on the CLI, `lotics app apply <file>`, with `--check` for `dry_run`).\n4. Change an app afterwards one node at a time: `get_app` prints the `tree:`, each node\'s address under `node addresses:`\n and the `version` line, which is the `base_version_id` to send (the tree and addresses go to the app\'s author alone);\n `set_app` with `app_id`, `base_version_id` and `nodes`, a map from a node\'s address to a\n patch, changes it (`reference/changing-an-app`), and its answer states the permissions the change grants and removes. A table\n is changed by `set_tables` with its `table_id`, a merge patch over the document `get_table` answers. To go back,\n send the tree you saved before the change as `body` with `app_id`: it replaces `children` but keeps every App prop it\n omits (`words`, `scope`, `period`, `icon`), so null those. (On the CLI, `lotics app pull <app_id>` writes the tree as JSON and `lotics app apply\n <file>` sends an edited file, refused when the app has moved past the version the file was pulled at.) An app\n saved before apps were trees has no tree: `get_app` says so beside what it lets a person write, and `set_app` with\n `app_id` changes it by its whole tree as `body`, which replaces it, or by its name, description, icon and color alone.\n\n## The rules\n\n- **A `set_tables` call is all or nothing.** Every item is checked before any is written; an item\n without `table_id` makes a table, one with it patches that table.\n- **An app\'s labels decide its language.** A body names no locale \u2014 the words an\n app draws itself (its buttons, empty states, refusals) are in the language its\n own labels are written in, so a Vietnamese desk beside English ones answers in\n Vietnamese. The generated screens read the kit\'s\n pack, and a generated WRITE cannot: its refusals run on the server, so they are\n worded in that same language. Mix the two within one app and it answers in two. The app\'s own `words`\n (its words for a table, a field or an option) count as its labels: Vietnamese words over an English table\n make the app answer in Vietnamese.\n- **`set_tables` and `set_app` check all of it before anything is written**, and\n report every problem in one run rather than the first. The tables half of this\n page ends its keys with the rules the check enforces there, and `reference/app-rules` and the pages after it hold the app\'s, one sentence each\n under an id; a finding names its rule\'s id (`[list.filter]`), and\n `reference/<rule id>` is that one rule\'s page.\n\n## Top level\n\nEvery table of keys on this page is generated from the grammar a table document and an app tree are written in, so it is the whole of what a key may hold.\n\n<!-- generated:start top-level -->\n\n#### set_tables call\n\n| Key | Type | Meaning |\n|---|---|---|\n| `tables` | list of [Table item](#table-item), required | One or more, all or nothing; each item is a table document with these keys added. It creates a table (a `label` and `fields` at least) or, with `table_id`, patches one: the document it states merges into the table\'s own |\n| `rows` | map of alias \u2192 list of [Row](#row) | First records of the tables the call creates, keyed by each one\'s `ref` |\n| `force` | boolean | Consent to losing what rows hold: a field deleted, an option removed |\n| `dry_run` | boolean | Answer what the call would change, writing nothing: for reading the grants a write would make or deciding `force`. A refused call writes nothing too and lists every reason, so a dry run checks no more than the call does |\n\n#### Table item\n\n| Key | Type | Meaning |\n|---|---|---|\n| `ref` | alias | A created table\'s handle in this call: other items link to it, and `rows` are keyed by it |\n| `table_id` | text | The table to patch; absent, the item creates one. A patch states only what changes: `null` removes a key, a list replaces whole |\n\n<!-- generated:end top-level -->\n\n**A `set_tables` item is a table document** (`reference/tables`) with `ref` and `table_id` added, and the call\ntakes no other key. **A `set_app` body is an app tree** (`reference/app-tree`), whose root is an App node: its `tables` and\n`templates` each map a local alias the tree names to the id of the table or document template it means, from the\n`set_tables` answer or `get_table`. The tree is the only home of the app\'s `name`, `description`, `icon` and `color`;\n`set_app` takes it whole to create, or as a merge patch over the App node with `app_id`, or `nodes` with `app_id` to change one, and with `base_version_id` (the\nversion you read) it refuses a write over a newer one. Nothing is built code. An unknown key is an error, never ignored.\n\nA smallest call, two tables of plain fields, a select and a two-way link \u2014 nothing else is needed to write it:\n\n```json\n{\n "tables": [\n {\n "ref": "customer",\n "label": "Customers",\n "singular": "Customer",\n "fields": {\n "name": {"type": "text", "label": "Name", "required": true},\n "tier": {"type": "select", "label": "Tier", "options": [{"alias": "gold", "label": "Gold", "color": "yellow"}, {"alias": "standard", "label": "Standard", "color": "gray"}]},\n "orders": {"type": "link", "label": "Orders", "table": "order", "multi": true, "pair": "customer"}\n }\n },\n {\n "ref": "order",\n "label": "Orders",\n "singular": "Order",\n "fields": {\n "code": {"type": "text", "label": "Code", "required": true},\n "customer": {"type": "link", "label": "Customer", "table": "customer", "multi": false, "pair": "orders"},\n "amount": {"type": "number", "label": "Amount"}\n }\n }\n ]\n}\n```\n\n### Aliases\n\nEvery `alias` is a lowercase slug \u2014 a letter, then letters, digits and\nunderscores (`unit_price`, `so_1001`). Aliases are how a document and an app tree\nname a field, an option or a table; they are never shown to anyone. `label` is\nwhat a person sees.\n\nLabels must be unique within their namespace \u2014 two fields on one table, two options\non one field cannot share a label.\n\n## Tables\n\n<!-- generated:start table -->\n\n#### Table document\n\n| Key | Type | Meaning |\n|---|---|---|\n| `label` | text, required | The table\'s name in the workspace |\n| `singular` | text | One row of this table, in the business\'s own words \u2014 what a create\'s button and panel name |\n| `description` | text | The table\'s description, written onto the table in the workspace, where a caller of an app\'s queries and workflows reads it beside them |\n| `fields` | map of alias \u2192 [Field](#field), required | The table\'s columns, each under its alias, which is its key here and so is never stated inside it |\n| `read_scope` | [Read scope rule](#read-scope-rule) | Which rows a member reads. Absent, every member with access to the table reads every row. |\n| `unique` | list (at least one) of list of alias (at least one) | Sets of fields whose values no two live rows share \u2014 each a list of field aliases (text, number, date, a single select, a single member, or a link holding one row \u2014 `multi: false`); a single text field states `unique: true` on itself instead of a one-field set. A create or update landing a second row with the same values is refused. |\n| `locked_change` | `"tell"` | `tell`: a change stated with a reason to a locked row is written at once and the people who manage the table are told. Absent, it waits for one of them to approve it. |\n| `title` | alias | The alias of the field that names a row wherever a link or a record shows one; absent, the first text field |\n| `colors` | any value | Row colors: a list of { filters, color }, the filter reading fields of this table by alias and a select\'s options by alias; one condition on its own is a group of one |\n| `records` | any value | How a row is recognised: the keys of the Record, Status and Cadence tables below but `title`, which sits above; a table they name is an id or a `ref`. A status `history` that names a `ref` no item of the call declares is made by the call as a table, `dates` add each date field they name, and a status with stages each stage and each open option they name none for its `<option>_at`, unless the document declares it; each is listed in the result\'s notes |\n| `natural_key` | list of alias (at least one) | The field aliases a row of this table is RECOGNISED by: an app\'s add and find-or-create reuse the row they find by these values, minting one only where nothing matches. A record tool or the API creates the row it is handed. |\n| `no_overlap` | [No overlap](#no-overlap) \\| list of [No overlap](#no-overlap) (at least 2) | No two rows hold overlapping spans (one rule, or a list of rules a row must each meet) \u2014 a create or update that would is refused, and so is a change to the dates or states of the row a span is read through that would make two rows overlap |\n| `checks` | map of alias \u2192 table check (`workflows/table-checks`) | The conditions a write of the table\'s rows may not meet, each under its alias: a merge patch edits one, and `null` removes it. Expressions name fields by alias |\n\n<!-- generated:end table -->\n\n<!-- generated:start rules-entity -->\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `entity.singular` | A table a List\'s `create` is mounted over \u2014 a root List\'s or a child List\'s that adds rows \u2014 states its `singular`: one row of it, in the business\'s words. |\n| `entity.link-format` | A text field of `format: "link"` holds web addresses; one whose rows hold a phone or a mail address states no format. |\n| `entity.read-scope` | A `read_scope` clause names a group (`member_of`) or a field of its table reached through one-row links: `"self"` a member field, options a single select declares; an `any` or an `all` groups clauses, and groups nest. |\n| `entity.unique` | A `unique` set names fields of its table once each, each holding one value to compare \u2014 text, a number, a date, a single select, a one-row link \u2014 and is stated once; a lone text field is `unique: true` on it. |\n\n<!-- generated:end rules-entity -->\n\n**`unique` is a set of values no two live rows share.** Each entry names fields\nof this table holding ONE value \u2014 text, number, date, a single select, a link\nwith `multi: false` \u2014 and a create or update landing a second row with the\nsame values is refused. A set of one text field is that field\'s own `unique:\ntrue`, so it is refused here. A create carries each set in the names its panel\nsends, so the panel can name the duplicate before the write does.\n\n**`singular` is what a create says** \u2014 `New Order`, `Add Claim line`, `H\u1ED3 s\u01A1\nm\u1EDBi` \u2014 while `label` names the table, so without it the button reads `New\nOrders`. Nothing derives it: English plurals are irregular, and no language is\nexempt. In a language without plural forms it is usually the label itself,\nless any word for the collection. A List that leaves `create` to its default adds nothing over a table that states\nnone (nor does the app\'s `words` state one); a `create` list stated over such a table is refused (`entity.singular`).\n\n**An app that only reads a table\'s rows draws them with `edit: false`** and states `create: false` and `remove: false` \u2014 a log of what the system sent, a copy of\nwhat another system holds. The app keeps the section and opens each row at rest, with no Add and no Delete; a party\nof it is picked, never found or minted; and the app writes no create, update or remove for it. It shapes that app, not who may write: a direct write \u2014 the records\nAPI, the chat agent, an import \u2014 follows the table\'s access, as on any table, and another app over the same rows\nstates its own tree.\n\n**`read_scope`** \u2014 which rows a member reads \u2014 is its own page, `reference/read-scope`.\n\n## Read scope\n\n<!-- generated:start read-scope -->\n\n#### Read scope rule\n\n| Key | Type | Meaning |\n|---|---|---|\n| `any` | list of ([Read scope by role](#read-scope-by-role) \\| [Read scope by member](#read-scope-by-member) \\| [Read scope by option](#read-scope-by-option) \\| [Read scope rule](#read-scope-rule)) (at least one) | A row is readable when ANY of these holds |\n| `all` | list of ([Read scope by role](#read-scope-by-role) \\| [Read scope by member](#read-scope-by-member) \\| [Read scope by option](#read-scope-by-option) \\| [Read scope rule](#read-scope-rule)) (at least one) | A row is readable when ALL of these hold |\n\n#### Read scope by role\n\n| Key | Type | Meaning |\n|---|---|---|\n| `member_of` | text, required | The id of a group (from Settings, or chat): whoever is in it reads the row |\n\n#### Read scope by member\n\n| Key | Type | Meaning |\n|---|---|---|\n| `through` | list of alias (1\u20133) | link aliases from this entity outward, each holding one row (`multi: false`) \u2014 the clause\'s field is on the entity the last hop lands on |\n| `field` | alias, required | A member field alias on this entity, or on the entity `through` lands on |\n| `is` | `"self"`, required | The members this column names on a row read that row |\n\n#### Read scope by option\n\n| Key | Type | Meaning |\n|---|---|---|\n| `through` | list of alias (1\u20133) | link aliases from this entity outward, each holding one row (`multi: false`) \u2014 the clause\'s field is on the entity the last hop lands on |\n| `field` | alias, required | A single-select field alias on this entity, or on the entity `through` lands on |\n| `is` | list of alias (at least one), required | Its option aliases whose rows are readable \u2014 naming none would hide every row |\n\n<!-- generated:end read-scope -->\n\n**A row rule is enforced by the platform.** A table\'s `read_scope` is resolved into its own row filters, so\nthe table tools, the data view and the API answer the same rows, and it caps what an app\'s owner can hand out: an\napp never reads beyond its owner\'s reach. An app states its own rule of each table it reads in `rows` on the App\nnode (`reference/app-tree`), in the grammar above. A `"self"` clause reads a column of one member or several, and every group\nand option a clause names must exist.\n\n**A rule holds through a link.** A filter through a link and a List\'s linked column read the linked row under the\nreader\'s own rule of it, and a link to a row the writer cannot read is refused. A lookup, rollup or copy is stored, so\nit reads one value for everyone who reads its table: one over a table with a rule takes `manage` on that table, and\n`get_table` of that table lists them as `crossings`.\n\n**An app runs under its owner\'s authority**, so the people it is shared with need the app and no access to its\ntables. Where they differ in what they may read, `rows` states it: one rule per table, evaluated against the caller,\nnarrowing the app\'s screens, its queries (the AI and MCP path), its writes and acts, and its workflow bodies and app\nagents, every row they read or write. A table `rows` states no rule of is read whole by everyone the app is shared\nwith, so a desk whose audience its sharing already decides states nothing. The rule holds for admins too: an app with people who see every row names them, as a group.\n\n**A row rule is never inherited.** A child read under a ruled record states\nits own in `rows`: the record\'s `member_of` clauses as they are, and its column clauses\n`through` the one-row link the child hangs by \u2014 over one hop or several, each a\nlink with `"multi": false`, since over several rows the rule would admit a\nreader any one of them admits while the editor\'s guard reads the first. Only the\nstatus history takes its record\'s rule.\n\n## Field\n\nEvery field carries the keys below, and its `type`\'s section adds the rest; a\ntype whose section names no `default` takes none. `label` may not contain `{` or\n`}` (formulas reference fields by label at the platform level). Every row in `rows` states each\n`required` field it carries (neither a default nor a `default_from` copy is applied to them), and a required\nLINK is written with its row: the table it names is created first, and tables\nwhose required links name each other are refused, since none of their rows could\never be created.\n\n**A table states who keys nothing.** Whether a person may change a field in an app is that app\'s statement\n(what its tree draws, and `edit: false`, `reference/app-tree`): a post\'s id a publishing workflow brings back, a count a sync fills, a status an act moves\nare left out of the apps that do not save them, and written by a workflow, the records API, the chat agent and an\nimport as the table\'s access allows. A formula, a rollup, a lookup and an autonumber are no one\'s to key already.\n\n<!-- generated:start field -->\n\n#### Field\n\n| Key | Type | Meaning |\n|---|---|---|\n| `type` | `"text"` \\| `"number"` \\| `"date"` \\| `"boolean"` \\| `"select"` \\| `"member"` \\| `"link"` \\| `"files"` \\| `"formula"` \\| `"rollup"` \\| `"lookup"` \\| `"autonumber"`, required | What the field holds \u2014 each type takes the further keys its own section lists |\n| `label` | text, required | The field\'s name in the workspace |\n| `description` | text | The field\'s description, written onto the field in the workspace |\n| `required` | boolean | Refuse a record whose cell for this field is empty. Every write path \u2014 create, update, an agent\'s tool call, a workflow\'s set \u2014 refuses the row by field name. A stored field is flagged only once every row holds a value. |\n\n<!-- generated:end field -->\n\n### `text`\n\n<!-- generated:start field-text -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `default` | text | Value pre-filled into a new record when none is supplied for this field; the write that makes the field required also fills it into every row holding it empty. |\n| `unique` | boolean | Unique values required |\n| `format` | `"text"` \\| `"link"` \\| `"markdown"` \\| `"time"` | How the words are drawn \u2014 plain, as a link that opens, or as markdown |\n| `default_from` | text | Copied when a record is made off the row a one-row link of this entity names \u2014 `<link alias>.<field alias>` \u2014 or, reading on through one-row links, off the row the last of them names \u2014 `<link alias>.<link alias>.<field alias>` \u2014 and never re-read, so the source changing later leaves the row alone. A value the add states wins; a select copies each option as this field\'s option of the same alias. |\n| `suggest` | [Suggest](#suggest) | A text field whose control offers, as the reader types, the distinct values a text field of a catalog table holds (a damage position\'s code among the codes on file); any text is still written |\n| `min` | number \\| text | Refuse a create or update whose value is below this: a constant for a number, or a field \u2014 `<field alias>` of the same row, or `<link alias>.<field alias>` of the one row a link names \u2014 of the same type (a return date after the departure, a line\'s day inside its trip). On a figure whose unit or currency is per row (its notation\'s `per_row`) a constant bound is only 0; bound it by a field of the row |\n| `max` | number \\| text | Refuse a create or update whose value is above this: a constant for a number, or a field of the same row or of the one row a link names |\n\n<!-- generated:end field-text -->\n\n### `number`\n\n<!-- generated:start field-number -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `default` | number | Value pre-filled into a new record when none is supplied for this field; the write that makes the field required also fills it into every row holding it empty. |\n| `notation` | [notation](#number) | How the figure reads: { "style": "decimal" }; money, { "style": "currency", "currency": an ISO 4217 code (USD, VND) }; or a quantity, { "style": "unit", "unit": "percent" (10 reads "10%"), or a measured code (g, kg, t, l, m3, cbm, mm, cm, m, km, m2, min, h, day), which converts and scales within its dimension, or any other noun of at most 12 characters (ki\u1EC7n, pallet, TEU), which never does }. A currency or unit read on each row from a single select of that row is { "per_row": that select }. Omitted, a decimal. |\n| `rating` | [Rating](#rating) | The figure is a grade: whole numbers 1 to `max` (3 to 10), empty or one of them, drawn as stars. Only on a plain decimal figure. |\n| `default_from` | text | Copied when a record is made off the row a one-row link of this entity names \u2014 `<link alias>.<field alias>` \u2014 or, reading on through one-row links, off the row the last of them names \u2014 `<link alias>.<link alias>.<field alias>` \u2014 and never re-read, so the source changing later leaves the row alone. A value the add states wins; a select copies each option as this field\'s option of the same alias. |\n| `min` | number \\| text | Refuse a create or update whose value is below this: a constant for a number, or a field \u2014 `<field alias>` of the same row, or `<link alias>.<field alias>` of the one row a link names \u2014 of the same type (a return date after the departure, a line\'s day inside its trip). On a figure whose unit or currency is per row (its notation\'s `per_row`) a constant bound is only 0; bound it by a field of the row |\n| `max` | number \\| text | Refuse a create or update whose value is above this: a constant for a number, or a field of the same row or of the one row a link names |\n\n#### Rating\n\n| Key | Type | Meaning |\n|---|---|---|\n| `max` | integer, required | The scale\'s top: the most stars a grade holds |\n\n<!-- generated:end field-number -->\n\n`notation` is how the number reads, and every surface reads it:\n`{ "style": "currency", "currency": "USD" }` prints as money in its code,\n`{ "style": "unit", "unit": "kg" }` as a quantity with its unit after it,\n`{ "style": "unit", "unit": "percent" }` as a percent \u2014 10 is "10%", never\nmultiplied \u2014 and `{ "style": "decimal" }`, or no notation, as a plain number. One\nkey, so a figure reads one way.\n\nAn absent number is drawn blank, except a `sum` or count rollup read as a meter\'s measure: nothing accumulated yet reads 0.\n\nA unit \u2014 `{ "style": "unit", "unit": "kg" }` \u2014 is what a figure counts or\nmeasures; `percent` aside, it is measured or counted. A **measured** unit is a code of one catalog \u2014 mass `g`\n`kg` `t`, volume `l` `m3` `cbm` (a cubic metre under freight\'s name), length\n`mm` `cm` `m` `km`, area `m2`, duration `min` `h` `day` \u2014 so a figure typed in\nanother unit of its dimension converts (`12,5 t` into a `kg` field is 12 500),\nand a tile or a chart reads it in the largest unit it reaches (12 500 kg as\n12,5 t\u1EA5n; CBM never scales) while a cell, a fact and a column always read in the\nfield\'s own. Any other noun of at most 12 characters (`ki\u1EC7n`, `pallet`, `TEU`) is a\n**counted** unit: a word after the figure that never converts. A measured unit is\nwritten as its code \u2014 `t\u1EA5n`, `KG` or `m\xB3` is refused, naming the code. A formula\nstates its own as its `notation`; a rollup that keeps the value (`sum`, `avg`,\n`median`, `min`, `max`, `range`) and a lookup carry the unit of the figure they\nread, exactly as they carry a currency, and a count carries none. A quantity is a\nnumber with its unit, never words (`3 cartons` in a text field): only a number\nsums, converts and reads down a column.\n\nA field\'s cells always hold figures in its own unit, so moving it between two\nunits of one dimension (`kg` to `t`) converts every stored figure \u2014 a change made\nin the workspace, in the field\'s settings (which say how many first) or through\n`set_tables`. Any other change of unit\nrelabels.\n\nA figure whose unit or currency varies by row names a single select of its own\nrow as `per_row` \u2014 `{ "style": "unit", "unit": { "per_row": "uom" } }`,\n`{ "style": "currency", "currency": { "per_row": "currency" } }` \u2014 or a lookup of\none through a one-link, a line reading its shipment\'s currency. That select\'s\noptions are the vocabulary: each label a unit (`chi\u1EBFc`, `kg`), or an ISO 4217 code\n(`USD`). A label outside it is refused when the figure is written and when the\nselect is \u2014 its options, its type or its deletion while a figure names it. A row\nwhose select is empty reads its figure bare. Every app reads each row\'s figure in\nits own row\'s unit, and a sum never mixes units: totals are one per unit, most rows first and units tied on rows in their select\'s option order (past three units a total the runtime draws over a set of rows \u2014\nsummary line, group totals and feet, a Sheet\'s table foot \u2014\nstates the count alone; a reading an author states draws every unit), a chart draws one at a time. A rollup that keeps the value (`sum`, `avg`, `min`\u2026)\nover such a figure stands only where the child\'s select is a lookup, through\nthe rollup\'s own link, of a select on this table \u2014 the rollup reads that\nselect\'s unit; otherwise it is refused. A lookup of such a figure stands only\nwhere its table also looks up the figure\'s select (stored, or itself looked up\nthrough one-row links) through the same one-link, and reads in that lookup; otherwise it is refused. A count is unaffected. Moving a field between a\nfixed and a per-row unit relabels.\n\n### `date`\n\n<!-- generated:start field-date -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `default` | text | Value pre-filled into a new record when none is supplied for this field; the write that makes the field required also fills it into every row holding it empty. A date string in the field\'s format. |\n| `format` | `"date"` \\| `"datetime"` \\| `"month"` \\| `"date_range"` \\| `"datetime_range"` | Whether the field holds a day or a moment, alone or as a span; `month` (stored YYYY-MM) holds a calendar month, a payroll or billing period: a full date written to it keeps its month. |\n| `timezone` | text | IANA timezone |\n| `derive_from` | `"created_at"` \\| `"updated_at"` | Auto-populate from the row\'s system timestamp; the field becomes read-only. |\n| `default_from` | text | Copied when a record is made off the row a one-row link of this entity names \u2014 `<link alias>.<field alias>` \u2014 or, reading on through one-row links, off the row the last of them names \u2014 `<link alias>.<link alias>.<field alias>` \u2014 and never re-read, so the source changing later leaves the row alone. A value the add states wins; a select copies each option as this field\'s option of the same alias. |\n| `min` | number \\| text | Refuse a create or update whose value is below this: a constant for a number, or a field \u2014 `<field alias>` of the same row, or `<link alias>.<field alias>` of the one row a link names \u2014 of the same type (a return date after the departure, a line\'s day inside its trip). On a figure whose unit or currency is per row (its notation\'s `per_row`) a constant bound is only 0; bound it by a field of the row |\n| `max` | number \\| text | Refuse a create or update whose value is above this: a constant for a number, or a field of the same row or of the one row a link names |\n\n<!-- generated:end field-date -->\n\nA `default` is refused beside `derive_from`: the platform stamps that date.\n\n### `boolean`\n\n<!-- generated:start field-boolean -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `default` | boolean | Value pre-filled into a new record when none is supplied for this field; the write that makes the field required also fills it into every row holding it empty. |\n| `default_from` | text | Copied when a record is made off the row a one-row link of this entity names \u2014 `<link alias>.<field alias>` \u2014 or, reading on through one-row links, off the row the last of them names \u2014 `<link alias>.<link alias>.<field alias>` \u2014 and never re-read, so the source changing later leaves the row alone. A value the add states wins; a select copies each option as this field\'s option of the same alias. |\n\n<!-- generated:end field-boolean -->\n\n### `select`\n\n<!-- generated:start field-select -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `default` | list of alias | Value pre-filled into a new record when none is supplied for this field; the write that makes the field required also fills it into every row holding it empty. Option alias(es) this field declares \u2014 one for single-select. |\n| `options` | list of [Select option](#select-option) (at least one), required | The choices, in the order every picker and every ladder lists them |\n| `multi` | boolean | Allow multiple selections |\n| `default_from` | text | Copied when a record is made off the row a one-row link of this entity names \u2014 `<link alias>.<field alias>` \u2014 or, reading on through one-row links, off the row the last of them names \u2014 `<link alias>.<link alias>.<field alias>` \u2014 and never re-read, so the source changing later leaves the row alone. A value the add states wins; a select copies each option as this field\'s option of the same alias. |\n\n#### Select option\n\n| Key | Type | Meaning |\n|---|---|---|\n| `alias` | alias, required | Stable local alias, unique within the field |\n| `label` | text, required | Display label for the option |\n| `color` | [colour](#select) \\| `null` | The colour the option\'s badge is drawn in; omitted, the option holds none and reads as its word wherever its select is drawn (a status\'s option takes a distinct colour), and an existing one keeps its own; null clears it |\n| `mark` | [mark](#select) | The option\'s own mark, drawn in place of its colour dot wherever the option is shown: the brand it is ({kind: "brand", name: one of facebook, instagram, threads, meta, tiktok, google-ads, zalo, linkedin, x, google-meet, youtube, telegram, whatsapp, gmail, google-drive, outlook, excel, kiotviet, misa, lark, payos, easyinvoice, google, reddit, quora, grok, claude}) a kit glyph ({kind: "icon", name: "wrench"}) or the face of who it is, drawn from its label ({kind: "avatar", name: "person" or "organization"}). Every option of a field has one, or none does. A mark a reader does not draw falls back to the dot |\n| `short` | text | A few letters the option reads as where room is short \u2014 a table\'s column ("K5" for a long legal category) \u2014 its label shown on hover |\n\n<!-- generated:end field-select -->\n\nA patch of a select states its whole `options` list: a list replaces whole, so an option it leaves out is deleted. To\nrename or recolour one option, restate every option kept, each with its alias. Rows still holding a deleted option refuse\nthe patch unless `force`.\n\n```json\n{\n "options": [\n { "alias": "draft", "label": "Draft" },\n { "alias": "confirmed", "label": "Confirmed" },\n { "alias": "shipped", "label": "Shipped", "color": "green" }\n ]\n}\n```\n\n`color` is one of: `red`, `orange`, `amber`, `yellow`, `lime`, `green`,\n`emerald`, `teal`, `cyan`, `sky`, `blue`, `indigo`, `violet`, `purple`,\n`fuchsia`, `pink`, `rose`, `slate`, `gray`, `zinc`, `neutral`, `stone`.\nEvery option is drawn in its colour wherever it shows \u2014 a cell, a row\'s line,\na record, a picker, the bar a reading splits the rows by.\n\nAn option may carry its own `mark`, drawn in place of its colour dot wherever\nthe option is shown \u2014 a stage, a chip, a filter, a fact, an entry of a log, a\nreading\'s part, a lookup of the select on another table. Where the select is its\nrows\' `records` `mark`, a brand or glyph stands on the row\'s lead tile in the option\'s\ncolour, and an option with none leads with its colour dot there. A select a reader scans\ndown a column \u2014 how a payment was made, the channel, the mode \u2014 states one on every\noption, since a glyph reads before its word: the brand it IS\n(`{"kind": "brand", "name": "tiktok"}` \u2014 one of `facebook`, `instagram`,\n`threads`, `meta`, `tiktok`, `google-ads`, `zalo`, `linkedin`, `x`,\n`google-meet`, `youtube`, `telegram`, `whatsapp`, `gmail`, `google-drive`,\n`outlook`, `excel`, `kiotviet`, `misa`, `lark`, `payos`), a glyph the kit draws\n(`{"kind": "icon", "name": "wrench"}`; any other name is refused), or \u2014 where the\noptions name people or organisations who are no member and no row \u2014 the face of who\nit is, drawn from its label (`{"kind": "avatar", "name": "person"}` or\n`"organization"`). Every option of a select has one, or none does: a run of chips\nwhere one carries no mark reads as the one missing something. `set_tables` writes the\nmarks onto the table. The glyph names are `reference/field/option-glyphs`.\n\n```jsonc\n"options": [\n { "alias": "short_video", "label": "Short video", "color": "zinc", "mark": { "kind": "brand", "name": "tiktok" } },\n { "alias": "print", "label": "Print", "color": "amber", "mark": { "kind": "icon", "name": "newspaper" } }\n]\n```\n\n### Option glyphs\n\nThe kit\'s glyph names an option\'s `mark` takes:\n\n<!-- generated:start field-select-glyphs -->\n\nactivity, align-center, align-left, align-right, align-vertical-justify-center, align-vertical-justify-end, align-vertical-justify-start, arrow-down, arrow-down-a-z, arrow-down-up, arrow-down-wide-narrow, arrow-left, arrow-left-from-line, arrow-right, arrow-right-from-line, arrow-right-left, arrow-up, arrow-up-down, arrow-up-wide-narrow, arrow-up-z-a, ban, banknote, bed, bell, between-horizontal-start, between-vertical-start, bold, bolt, book-marked, book-open, book-text, bot, box, brackets, brain, briefcase, building-2, calculator, calendar, calendar-clock, calendar-off, camera, car, chart-column, check, chevron-down, chevron-left, chevron-right, chevron-up, chevrons-down-up, chevrons-up-down, circle-alert, circle-check, circle-x, clipboard-list, clipboard-paste, clock, code, code-xml, columns-3, columns-3-cog, combine, construction, container, copy, credit-card, database, decimals-arrow-left, decimals-arrow-right, dollar-sign, download, ellipsis, eraser, expand, external-link, eye, eye-off, file, file-csv, file-down, file-question, file-spreadsheet, file-stack, file-text, file-up, folder, folder-closed, folder-open, folder-pen, form, funnel-plus, funnel-x, gauge, globe, gpu, grid-2x2, grip-vertical, group, hand-coins, hash, heading, heading-1, heading-2, heading-3, history, house, image, inbox, info, italic, keyboard, languages, layout-dashboard, layout-grid, library-big, link-2, link-2-off, list, list-checks, list-collapse, list-filter, list-filter-plus, list-ordered, list-tree, loader, lock, lock-keyhole, lock-keyhole-open, lock-open, log-in, log-out, mail, map-pin, maximize-2, megaphone, menu, message-circle, message-circle-question-mark, message-square, messages-square, mic, minimize-2, minus, monitor, mouse, mouse-pointer-click, music, newspaper, notepad-text-dashed, package, paint-bucket, paintbrush-vertical, palette, panel-left, panel-left-close, panel-left-open, panel-right, panel-right-close, panel-right-open, paperclip, pause, pencil, percent, phone, pin, pin-off, plane, play, plug, plus, receipt, rectangle-ellipsis, redo, refresh-cw, repeat, rotate-ccw, rotate-cw, rows-3, scan, scan-line, scissors, search, send, settings, share, share-2, shield, shield-alert, shield-check, shopping-cart, sigma, sliders-horizontal, smile, smile-plus, snowflake, sparkles, split, square, square-check, square-pen, square-sigma, star, stethoscope, sticky-note, strikethrough, table, table-2, tag, target, text-quote, text-wrap, thumbs-down, thumbs-up, ticket, trash, trending-down, trending-up, triangle-alert, truck, tv-minimal, type, underline, undo, upload, user, user-check, user-pen, users, utensils, waypoints, workflow, wrench, x, zap, zoom-in, zoom-out\n\n<!-- generated:end field-select-glyphs -->\n\n### `member`\n\nA person picker over the workspace\'s members. No default. With no role it is still drawn \u2014\nface and name, ranked as a `party` \u2014 in a screen\'s `columns` and in the register\na record draws of these rows.\n\n<!-- generated:start field-member -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `multi` | boolean | Allow multiple selections |\n| `default_from` | text | Copied when a record is made off the row a one-row link of this entity names \u2014 `<link alias>.<field alias>` \u2014 or, reading on through one-row links, off the row the last of them names \u2014 `<link alias>.<link alias>.<field alias>` \u2014 and never re-read, so the source changing later leaves the row alone. A value the add states wins; a select copies each option as this field\'s option of the same alias. |\n\n<!-- generated:end field-member -->\n\n### `link`\n\n<!-- generated:start field-link -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `default_from` | text | Copied when a record is made off the row a one-row link of this entity names \u2014 `<link alias>.<field alias>` \u2014 or, reading on through one-row links, off the row the last of them names \u2014 `<link alias>.<link alias>.<field alias>` \u2014 and never re-read, so the source changing later leaves the row alone. A value the add states wins; a select copies each option as this field\'s option of the same alias. |\n| `options_where` | [filter](#filters) | Which rows of the target this link may point at \u2014 an `and` group of plain conditions over the TARGET table\'s own fields, each `field_key` a field alias. It narrows every picker of the link, and a save naming a row outside it is refused on every path \u2014 an app, the grid, an import, a workflow, the API. |\n| `same` | list of alias (at least one) | One-row links this row and each row this link points at must name alike \u2014 a fee\'s invoice is one of its own visit\'s, a box\'s seal one of its own shipping line\'s: each a one-row link of both tables to the same table, or a lookup of one (a line\'s shipping line looked up from its visit, never stored beside it). It narrows the picker\'s read to the rows naming what this row names, a row made from the picker names it too (set, never asked), and a write is refused wherever it lands \u2014 on the link, or on what the two rows compare. |\n| `table` | text, required | The table the link points at: its alias, or the `ref` of another item of the call |\n| `multi` | boolean, required | Whether a row links to one row or many: true, many; false, one. Where the link is paired, at most one of the two sides holds one |\n| `pair` | `true` \\| alias | Makes the link two-way: the alias of its partner field on the other table, which names this one back, or `true` to have the alias derived. Stated on one table, the partner is made on the other with the inverse cardinality; a many-to-many link states both sides |\n\n<!-- generated:end field-link -->\n\n**`multi` is stated on every link:** `true` holds several rows, `false` one \u2014 one customer on an\ninvoice, one project on a device. There is no default.\n\nA two-way link states `pair` on one table, as `true` or a free alias, and the partner is made on the\nother table with the inverse cardinality; a many-to-many link states both sides, since the inverse of\nmany is not decided. A pair stated on both sides is made once. Both tables are written in the one\ncall (`table` names the other item\'s `ref`). A link with no `pair` is one-way, and nothing is created on the target. Pair a link when\nthe target\'s own record should list what points at it, and leave it unpaired when it should not: either\nway the record plan draws the relation as a section on the side it points at, so an unpaired link costs\nthe target nothing. Of two paired links at most one holds one row.\nA link to its own table is paired with itself (a spouse) when `pair` is `true`, and with a second field of that table when `pair`\nnames its alias (a parent and its children, each stating the other); paired with itself it cannot hold one row.\n\n```jsonc\n// a field of table "order"\n"customer": { "type": "link", "label": "Customer", "table": "customer", "multi": false, "pair": "orders" }\n```\n\n```jsonc\n// a field of table "customer"\n"orders": { "type": "link", "label": "Orders", "table": "order", "multi": true, "pair": "customer" }\n```\n\n### `files`\n\nA row attaches documents to it (`reference/rows`). Each file\nis drawn by its kind, with no key to choose: a picture (an image, a video) as its\nthumbnail, a document (a PDF, a sheet) as its type\'s badge and its filename.\n\n<!-- generated:start field-files -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `photo_places` | `true` | Each photo shot through a phone\'s camera into this field keeps where the device stood, as the device reported it and never proof of where the photo was taken: for photos whose place matters (inspections, deliveries, proof of a visit). Formulas on the table read it through `distance`; apps holding the capability draw it to members of the organization only, never to a visitor or another organization |\n\n<!-- generated:end field-files -->\n\n### `formula`\n\nA formula states its keys on the field itself, beside `type` and `label`:\n`{ "type": "formula", "label": "Total", "expression": "{quantity} * {unit_price}", "notation": { "style": "currency", "currency": "USD" } }`.\n\n<!-- generated:start field-formula -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `expression` | text, required | The expression, over fields of THIS entity by alias in braces \u2014 `{quantity} * {unit_price}` |\n| `output_type` | `"number"` \\| `"text"` \\| `"date"` \\| `"datetime"` \\| `"boolean"` \\| `"select"` | Holds a formula to the type its readers need: absent, it is what the expression yields. Stated, it is checked against that and refused where they differ (a datetime is never stated date) |\n| `notation` | [notation](#number) | How the figure reads: { "style": "decimal" }; money, { "style": "currency", "currency": an ISO 4217 code (USD, VND) }; or a quantity, { "style": "unit", "unit": "percent" (10 reads "10%"), or a measured code (g, kg, t, l, m3, cbm, mm, cm, m, km, m2, min, h, day), which converts and scales within its dimension, or any other noun of at most 12 characters (ki\u1EC7n, pallet, TEU), which never does }. A currency or unit read on each row from a single select of that row is { "per_row": that select }. For a formula yielding a number. |\n| `link` | `true` | The formula yields a URL as text, drawn as a link that opens. |\n| `options` | list of [Select option](#select-option) (at least one) | The categories the formula yields, drawn as a single select\'s options are (read-only). The expression yields one of them as `{this_field:option}`, or null \u2014 `{days_idle} > 30 ? {warmth:cold} : {warmth:hot}`. Omit for a formula yielding a plain value. |\n\n<!-- generated:end field-formula -->\n\n`output_type` is what lets a role or a screen clause accept a computed value: a\ncaption over a derived name (`output_type: "text"`), a period over a settled date\n(`"date"`). A formula declaring no `output_type`, `notation` or `link` says nothing\nabout its result, and every rule that needs one refuses it by name. A formula stating\n`options` is a computed category: read-only, and read as a single select\nwherever it is drawn \u2014 a column, a filter, a reading\'s `by` or `where`.\n\n**A select reaches a formula as the KEYS of its chosen options**, a list \u2014\nnever their labels, and never their aliases \u2014 and a document has no keys: the\nworkspace mints them when the table is made. So an option is named in a formula\nas `{field:option}`, both aliases, and the write puts that option\'s key in its\nplace: `includes({kind}, {kind:crate})` for a select holding one or several,\n`{kind}[0] == {kind:crate}` for a single one. A select compared to its own words\n(`{kind} != "Crate"`) matches no row and computes the other branch everywhere,\nso the check refuses it and names the token. A select looked up through a link\nof one row (`multi: false`, or a chain of them) is named the same way:\n`{parent_stage} == {parent_stage:won}`. A lookup through a link holding several\nrows has no single option; it is tested on the table it lives on, in a formula of\nits own, and that result looked up.\n\n**The language.** The check refuses a call or a name the platform cannot run, naming what to write:\n\n<!-- generated:start field-formula-language -->\n\n- Operators: `+ - * / %`, `== != > < >= <=`, `&& || !`; `+` also joins text\n- Numbers: arithmetic is exact decimal (`0.1 * 3` is `0.3`), a division that does not end the nearest double; a comparison between two numbers reads both at 15 significant digits; `round` rounds a half away from zero (`round(-2.5)` is `-3`)\n- Conditionals: a ternary only \u2014 `{amount} > 100 ? "High" : "Low"`\n- Not supported: optional chaining (`?.`), nullish coalescing (`??`), template literals, arrow functions \u2014 use `get(obj, "path", default)`, `coalesce(v1, v2)`\n- Helpers are these names, spelled exactly; a spreadsheet function (`IF`, `SUM`, `LEN`, `DATEDIF`) is none of them, and a formula calling one is refused\n- Math: round(n,decimals?), ceil(n), floor(n), abs(n), min(a,b), max(a,b), sum(arr), mean(arr), clamp(n,min,max), percentage(part,total,decimals?), pow(base,exp), sqrt(n), mod(n,divisor), distance(lat1,lon1,lat2,lon2) (metres along the earth between two places in degrees; null when an argument is empty)\n- Photo places: distance(photos,lat,lon) over a files field stating `photo_places` is a list, one entry per file in order \u2014 the metres from where its photo was taken to (lat,lon), null for a file with no kept place; judge a cell with a list helper: `max(distance({photos},{site_lat},{site_lon})) > 150`\n- A select reads as its option keys: compare it with `{field:option}`; read its name as text with `label({field})`\n- Strings: label(select) (the option\'s name; a multi-select\'s names joined ", "), upper(s), lower(s), trim(s), capitalize(s), length(s), contains(s,search), join(arr,sep), split(s,sep), replace(s,search,rep), replaceAll(s,search,rep), removeChars(s,chars) (s without any character that occurs in chars), removeSpaces(s) (s without any whitespace), startsWith(s,prefix), endsWith(s,suffix), substring(s,start,end?), padStart(s,len,char), padEnd(s,len,char), numberToWords(n, lang?) (lang \'vi\' default, or \'en\'), uuidFrom(s) (the same UUID for the same text)\n- Lists: includes(list,value), first(list), last(list), unique(list), compact(list) \u2014 length(list) counts one; join, sum, mean, first, last, unique and compact read a single value as a list of it\n- Dates: now(), formatDate(d,fmt), addDays(d,n), subDays(d,n), addHours(d,n), subHours(d,n), addMinutes(d,n), subMinutes(d,n), startOfDay(d), endOfDay(d), startOfMonth(d), endOfMonth(d), addMonths(d,n), differenceInCalendarDays(later,earlier) (days between two dates, whatever it is searched as: `daysBetween`, `diffDays`, `dateDiff`), differenceInHours(later,earlier), differenceInMinutes(later,earlier), isBefore(d1,d2), isAfter(d1,d2), isSameDay(d1,d2), isToday(d), isWithinRange(d,start,end), datesOn(from,until,days) (the days from..until falling on weekdays named `mon` to `sun`, as a list of dates), meetsBounds(value,kind,{gt,gte,lt,lte},tz?), parseDate(d)\n- Null/type: isNull(v), isEmpty(v) (also true for "" and []), coalesce(v1,v2,...), isString(v), isNumber(v), isBoolean(v), isArray(v), toNumber(v), toFigure(v), toString(v)\n- Other: formatCurrency(amount,locale,currency), formatDecimal(value,decimals,locale) (grouped quantity, no symbol; without decimals, `formatDecimal(value,locale)`, the decimals it holds, at most two, as the app draws a figure), get(obj,"path",default?)\n- Empty cells: a cell nobody filled is null inside a formula, whatever its type; one holding 0, false or "0" is not empty. Test it with `isEmpty({note})` \u2014 `{note} == ""` and `{done} == false` are false on an unset cell\n- Arithmetic over an empty cell: `+` and `-` read it as 0 beside a value (`{fee} + {surcharge}` is `{fee}` when the surcharge is empty, null when both are); `*`, `/`, `%` and a unary `-` yield null (`{price} * {qty}` is null, not 0, when the quantity is empty)\n- No helper throws on an empty cell: the math helpers and toNumber return null, the string helpers "". A value of the wrong type still errors. When EVERY field a formula reads is empty it is null \u2014 unless it reads each only as the argument of isEmpty, isNull or isNotNull (`!isEmpty({file})` is false there, not null)\n\n<!-- generated:end field-formula-language -->\n\n### `rollup`\n\nAggregates the records reached through a link on this table.\n\n<!-- generated:start field-rollup -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `filter` | [filter](#filters) group | Only linked records matching this filter are aggregated; one condition on its own is a group of one. Every `field_key` in it names a field alias on the linked entity, and a select condition\'s value names an option alias there. A traversal node reaches past that entity, so its `path` hops and inner `field_key` are fully-qualified `entity.field` aliases. |\n| `via` | alias, required | The alias of a link of this table to roll up from |\n| `op` | [operation](#rollup), required | The operation over the linked rows |\n| `field` | alias | The alias of the field on the linked table the operation reads; absent for `count` |\n\n<!-- generated:end field-rollup -->\n\nA rollup states `via` (a link of this table), `op` and \u2014 except for `count` \u2014 `field`, an alias on the\nlinked table; `op` is one of `count`,\n`sum`, `avg`, `median`, `min`, `max`, `range`, `empty`, `filled`,\n`percent_empty`, `percent_filled`, `unique`, `percent_unique`, `earliest`,\n`latest`, `date_range`, `checked`, `unchecked`, `percent_checked`,\n`percent_unchecked`. The operation must be one the aggregated field\'s type\nallows \u2014 `sum` over a number, `earliest` over a date, `filled` over any stored or\nformula field. A lookup is never rolled up: roll up the child\'s own field, or a formula\nover it. A rollup states no `notation`: `sum`, `avg`, `median`, `min`, `max` and `range`\nread in the aggregated figure\'s, a count as a plain number, and a `percent_*` as a\npercent (0\u2013100), in the app as in the table.\n\n### `lookup`\n\nDisplays a field from the linked records: `via` names a link of this table, `field` a field of the table it\npoints at. Through a link holding several rows it holds every linked row\'s value, which an app reads whole: a sort by\nits first value, a filter matching any value, a grouping counting the row under each; `order_by` (`field`, `direction`)\npicks the one row whose value shows instead.\n\n<!-- generated:start field-lookup -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `via` | alias, required | The alias of a link of this table to look up through |\n| `field` | alias, required | The alias of the field on the linked table to show |\n| `order_by` | [Lookup order](#lookup-order) | Show ONE linked row\'s value \u2014 the first in this order \u2014 rather than every linked row\'s |\n\n#### Lookup order\n\n| Key | Type | Meaning |\n|---|---|---|\n| `field` | alias, required | A field alias on the linked table the rows are ordered by |\n| `direction` | `"asc"` \\| `"desc"`, required | Which end of that order the one row is taken from |\n\n<!-- generated:end field-lookup -->\n\nInside a formula, a lookup holding one value is that value (`{due_soon}` is\n`true`, not `[true]`); several values are a list.\n\n### `autonumber`\n\n<!-- generated:start field-autonumber -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `prefix` | text | Literal prefix prepended to every display value (e.g. \'KH-\' \u2192 \'KH-001\'). Ignored when `template` is set. |\n| `padding` | integer | Zero-pad the integer to this width. Default 1 (no padding). 3 \u2192 \'001\', \'012\', \'123\', \'1234\' (overflow uses the actual width). Ignored when `template` is set. |\n| `template` | text | Format template with placeholder tokens evaluated at insert time. Tokens: {N} (raw integer), {N:W} (zero-padded to width W, e.g. {N:3} \u2192 001), {YEAR} (4-digit year), {YEAR:2} (2-digit year), {MONTH} (2-digit month), {DAY} (2-digit day). Date tokens use the workspace timezone. Example: \'HM-{YEAR}-{N:3}\' yields \'HM-2026-001\'. Stored as the composed string; subsequent template edits do NOT re-format existing rows (date tokens would lose the original creation date). |\n| `next` | integer | Sets the number the next row takes, once, as the patch is written; never below one past the highest number issued. On a field added to a table with rows, those rows are numbered from it in creation order. It is no setting of the field: a read of the table shows none |\n\n<!-- generated:end field-autonumber -->\n\nA refused write and a dry run take no number, so a table\'s numbers run without a gap; a removed row\'s number is not\nissued again.\n\n<!-- generated:start rules-field -->\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `field.default` | A default names options its select declares \u2014 one on a single select \u2014 and a date stamped by `derive_from` states none. |\n| `field.default-from` | A field\'s `default_from` reads `<link>.<field>` off the row a one-row link of its table names \u2014 a link no copy fills \u2014 or, through further one-row links, `<link>.<link>.<field>` off the row the last names, into a field of the same type, date format and notation that `derive_from` does not stamp (a figure read per row, into one whose select is copied from or looked up off the source\'s select by the same links): a lookup only through a one-row link, a link only into one to the same table, a select\'s option as this field\'s of the same alias (one it lacks is not copied), several values only into a field holding several. The server copies it on every add that fills the link and leaves the field empty, so a List\'s `create` sure to fill the link \u2014 a required one, or the record it files the row under \u2014 does not ask it by default. |\n| `field.option-mark` | An option\'s `mark` is one the kit draws, and a select\'s options mark every one or none. |\n| `field.unit-select` | A notation\'s `per_row` names a single select of the same row, or a lookup of one through a one-link, whose every option label is a unit, or an ISO 4217 code. |\n| `field.link` | A link targets a table of the call or the workspace: its `pair` a link on that table naming this one back \u2014 and of two paired links at most one reads one row (`multi: false`). |\n| `field.formula` | A formula parses, reads fields of its own table by alias, names an option as `{field:option}` of a select it holds, or looks up through a link of one row, and compares a select to its options\' keys, never their words. |\n| `field.formula-type` | A formula yields what it states \u2014 its `output_type` (the type the platform stores: a `"datetime"` is never stated `date`), else a figure where it states a `notation` and text where it states `link` \u2014 as the platform infers it from the expression when the field is created. |\n| `field.rollup` | A rollup aggregates, through a link of its table (`via`), a field of the linked table (`field`) by an operation (`op`) that field\'s type takes \u2014 a figure read in each row\'s own unit or currency only by an `op` that keeps its values whose child select is a lookup, through the rollup\'s own link, of a select on this table \u2014 filtered on fields of the linked table. |\n| `field.lookup` | A lookup reads (`field`), through a link of its table (`via`), a field of the linked table \u2014 a figure read in each row\'s own unit or currency only where this table looks up that row\'s select through the same one-row link \u2014 ordered by a field of it (`order_by`). |\n| `field.computed-cycle` | Computed fields never wait on each other in a loop: each is computed after what it reads. |\n\n<!-- generated:end rules-field -->\n\n## Filters\n\nA table\'s saved views are not part of its document: `set_table_views` writes them and `get_table` lists them. A view\'s\nfilter, a color rule\'s filter, `options_where` and a rollup\'s `filter` share one grammar. Every field reference is a\nfield ALIAS on that table.\n\nA filter is a group \u2014 `{ "node_type": "group", "logic": "and" | "or",\n"children": [ \u2026 ] }` \u2014 or one condition on its own, `{ "node_type":\n"condition", "field_key": "tier", "operator": "has_any_of", "value": ["gold"] }`. A sort is a list of `{ "field_key": \u2026, "order": "asc" |\n"desc" | null }`. A condition states no `type`: its field\'s type decides which `operator` it admits: `has_any_of` / `has_none_of` / `has_all_of` / `is_empty` /\n`is_not_empty` for a select, `equals` / `greater_than` / `less_than` for a\nnumber, `on` / `before` / `after` / `between` for a date, `contains` /\n`is_any_of` for text. A select condition\'s `value` names option ALIASES.\n\n<!-- generated:start rules-color -->\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `color.fields` | A color rule\'s filters name fields of its table. |\n\n<!-- generated:end rules-color -->\n\n## Groups and templates\n\nA member group and a document template are made on their own, outside a table document and an app tree. A tree names a\ntemplate by its alias. A table document names a group by its id, where a `read_scope` clause (`member_of`),\na stage owner (`group`) or a check\'s `member_of("<id>")` takes one. `get_workspace` kind `group` lists the workspace\'s groups with their ids and members; `set_members` creates,\nchanges or deletes one in its `groups` (an admin\'s of the workspace). A group belongs to one workspace and holds only its people.\n\n`{{name}}` in an `html` or `email` template is filled from the workflow\'s data. Inline content is refused where it holds a\nscript, a frame, a `<link>`, an inline event handler or a `javascript:` URL; an `html` one may be a fragment, kept as\nwritten and printed as a whole document.\n\nA template\'s markup is the `template` of `set_template`, as one JSON string. A paper shaped like a counterparty\'s \u2014 a letterhead, a reference line, a seal, a signature block \u2014 is an `html` template with a shell around the body; `document_templates` covers the types.\n\n**What an act\'s template is handed** is its record\'s own fields by alias: a\nselect, a member and a link as their words (a link as the linked row\'s title), a\nnumber, a date and a computed value that declares its kind raw (`2800000`,\n`2026-09-14`) and a files field as its file cells (`{id, name, mime, url}`, the photos in the order held; a child row\'s\nfiles likewise) \u2014 never a computed select. On one record it is\nhanded, too, the rows of each child List the record draws, listed under that child\'s\nlink\'s name for `{{#each <link>}}` (and under the child entity\'s alias too): every row filed under the record, oldest first, each\nby its own fields as the record\'s are, less its link back to the record. A List that only reads is listed under its `key`, its rows reached by its link\nor, for a `<link>.<link>` path, by both. Over\nseveral rows (at most 200) the rows are listed under the table\'s alias, for\n`{{#each <alias>}}`, an html paper hands each row its own child rows under the same names, with `<name>_totals`.\n\n**Photos in a paper.** A file cell is drawn only if whoever makes the paper may read that file, by the rule the file\nproxy applies; a file they may not read is never drawn. html: `{{#each photos}}<img src="{{url}}">{{/each}}`, each\nphoto inline, only those the data\'s file cells carry (a url typed into a text field stays a link). Word:\n`{{IMAGE picture(cover, 8)}}` for one file cell, and `{{FOR p IN photos}}{{IMAGE picture($p, 8)}}{{END-FOR p}}` for\nmany. Excel: `{{cover | picture:6}}` as the whole cell, and `{{#each photos}}` with `{{this | picture}}` for many, each\nrow growing to its picture. The number is the width in centimetres (8 by default, 6 in Excel); the height follows the\npicture. `picture` takes one image file cell: a list, a file that is no image and a file that cannot be read are\nrefused by name. Photos are embedded at most 1600 pixels across.\n\nHelpers print a raw value in the template\'s `locale` \u2014 `vi` or `en`, the organization\'s language where it states\nnone; each prints `""` for an empty value:\n\n| Helper | Prints (`vi` / `en`) |\n|---|---|\n| `{{money total "USD"}}` | `1.250,50 US$` / `$1,250.50`, in the currency\'s minor units; no code, a number |\n| `{{number qty}}`, `{{number qty unit}}` | `1.234,5` / `1,234.5`: grouped, up to 2 decimals; a unit as the second argument follows it (`{{number qty item_unit}}` prints `6 kg`, `2 l\xEDt` / `2 L`: a measured unit in the language\'s label, a counted noun such as `th\xF9ng` as written) |\n| `{{date issued_on}}` | `14/09/2026`, `14 Sep 2026` in an English template; a date-fns pattern as the second argument, `{{date at "dd/MM/yyyy HH:mm"}}`, literal text quoted (`"\'Ng\xE0y\' dd"`). A moment prints on the workspace\'s timezone |\n| `{{words total "USD"}}` | `M\u1ED9t ngh\xECn hai tr\u0103m n\u0103m m\u01B0\u01A1i \u0111\xF4 la M\u1EF9 n\u0103m m\u01B0\u01A1i xu` / `One thousand two hundred fifty US dollars and fifty cents`; no code, VND (`\u0111\u1ED3ng`) |\n| `{{qr link}}`, `{{code128 position 6}}` | the value as a QR code, or as a Code 128 barcode (ASCII text only), a picture the width of the optional second argument in centimetres, by default sized to the value (a module prints 0.5 mm in a QR code, 0.33 mm in a barcode); a width too narrow to scan is refused, naming the least that does; not in an email template |\n| `{{date (add_days issued_on -1)}}` | `13/09/2026`: the date shifted by whole days (`-1`: the day before), for `date` to print; a number field as the days, empty shifting none |\n\nA value it cannot read (`{{money "abc"}}`, `{{date "14/09/2026"}}`) fails the render. A field named like a\nhelper and written alone (`{{number}}`) prints its own value.\n\nA field printed as a code in the other types: Excel `{{position | qr}}` or `{{position | code128:6}}` as the whole\ncell and the last helper \u2014 the picture is anchored on the cell and its row grows to hold it; Word `{{IMAGE qr(position)}}` or `{{IMAGE code128(position, 6)}}`. An empty field draws no picture.\n\n## Rows\n\n`rows` of a `set_tables` call are the first records of the tables the call creates, keyed by each one\'s `ref`;\na patch of an existing table seeds none, so write its rows into the table. A sample, not a data set: rows past it go in with `create_records` once the tables exist, in the batches its description bounds.\n\n```jsonc\n"rows": {\n "customer": [\n { "ref": "acme", "fields": { "name": "Acme Trading", "tier": "gold" } }\n ]\n}\n```\n\n`rows` sits beside `tables` in the call, not inside a table.\n\n<!-- generated:start rows -->\n\n#### Row\n\n| Key | Type | Meaning |\n|---|---|---|\n| `ref` | text, required | Local handle for this row, referenced by other rows\' link fields |\n| `fields` | map of text \u2192 any value, required | Field alias \u2192 the value, read against the field\'s declared type |\n\n<!-- generated:end rows -->\n\n<!-- generated:start rules-rows -->\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `rows.ref` | A row\'s `ref` is unique within its table. |\n| `rows.required` | A row states every field its table requires: it is created with what it states, its fields\' defaults and copies unapplied. |\n| `rows.value` | A row\'s value fits its field: an option alias for a select, `"<table ref>:<row ref>"` of a row of the linked table in this call or a stored record\'s id for a link, `"self"` for a member, a `fil_` id for files, a date in the date grammar (an hour only on a datetime), a text, number, yes/no or null otherwise \u2014 and none on a computed field. |\n\n<!-- generated:end rules-rows -->\n\nA `ref` is lowercase letters, digits and underscores, and is never persisted.\n\n`fields` is keyed by field alias, and every value is read against the field\'s\nDECLARED type:\n\n| Field type | Value |\n|---|---|\n| `text` / `number` / `boolean` | the value itself |\n| `date` | `"2026-03-14"`, or a relative expression (below) |\n| `select` | the option ALIAS \u2014 `"gold"`, or `["gold","vip"]` for a multi-select |\n| `link` | `"<table ref>:<row ref>"` naming another row of this call \u2014 `"customer:acme"` \u2014 or the id of a record the linked table already holds, or an array for several; a paired link is stated on ONE side (the child\'s link to its parent) and its partner fills itself |\n| `member` | `"self"` only \u2014 the member making the call |\n| `files` | the `fil_` id of a file already in this workspace, or a list of them |\n| `formula`, `rollup`, `lookup`, `autonumber` | not allowed \u2014 the platform writes these |\n\n### Relative dates\n\nA date cell holds a literal `YYYY-MM-DD`, or an expression relative to the day\nthe call is made, so a screen that opens on "this month" is not empty a month\nlater:\n\n- `@today` \u2014 the day of the run, in the workspace\'s timezone\n- `@month-start` \u2014 the 1st of that month\n- either with a whole-day offset: `@today-14`, `@month-start+9`\n- on a date that holds its hour (`format: "datetime"`), that hour after the day, and always stated:\n `@today 14:30`, `@today+1 06:00`\n\n`@month-start` exists because `@today-N` cannot promise a month: applied on the\n2nd, `@today-3` lands in the previous one.\n\n## Records\n\n`records` says how a row of a table is RECOGNISED \u2014 stated once in the table\'s document, beside its\n`title` \u2014 and every surface that draws one of its rows reads the same\nstatement: the register\'s row, a picker\'s option, a link\'s chip, a child table\'s\nrow and the record\'s header. Every table an app lists, opens or picks has one. The rarer keys \u2014 `scan`, `cadence`, `place`, `pin` and `plan_place` \u2014 are stated on `reference/record-places-pins-and-cadence`.\n\n```jsonc\n// table "visit"\n"title": "container_no",\n"records": {\n "subtitle": ["customer", "arrived_on"],\n "image": "photos",\n "status": { "field": "stage", "closed": ["gone"], "history": "visit_history" },\n "figure": "total_fees",\n "due": ["free_until"]\n}\n```\n\n```jsonc\n// table "release": a release order read against what it allows \u2014 a meter wherever it shows\n"title": "release_no",\n"records": { "figure": "issued", "limits": { "issued": "units" } }\n```\n\n```jsonc\n// table "dossier": a straight-line process \u2014 the stage a select, each step\'s day the date it stamps\n"title": "applicant",\n"records": { "status": { "field": "stage", "closed": ["signed"], "dates": { "received": "received_on", "appraised": "appraised_on", "signed": "signed_on" } } }\n```\n\n<!-- generated:start records -->\n\n#### Record\n\n| Key | Type | Meaning |\n|---|---|---|\n| `subtitle` | list of alias (1\u20132) | Up to two fields read under the title wherever a row is drawn (a code, a date, a party): the first at the body ink and the rest muted, one line at a desk, a second on a phone; a card shows one line per column |\n| `image` | alias \\| list of alias (at least one) | A files field that pictures the row, or a one-row link to a table with a picture (or a lookup of one through a one-row link: a delivery led by its order\'s customer), whose picture the row leads with \u2014 never a files field an act keeps the document it makes in. A list of them, each a different field, is read in order: the first that holds a picture pictures the row (a line linking either a product or a bundle). Absent, a table with exactly one files field is pictured by the first image in it \u2014 never a paper or other file \u2014 unless the entry states a `mark` or puts that field in the title or subtitle; an app turns it off with `row.image: false`. |\n| `image_shape` | `"portrait"` \\| `"square"` \\| `"landscape"` | The shape the register\'s cards and tiles, and a child List stating `layout: "cards"`, draw the row\'s picture at: portrait (4:5), square or landscape (16:9), whatever the pictures themselves measure; only where the rows lead with a picture (`image`, or the default lone files field \u2014 not where a `mark` leads or that field is in the title or subtitle). Absent, a card\'s banner is landscape and a tile square; a small lead keeps its size |\n| `mark` | alias | A single select (or a lookup of one through a one-row link) whose option leads the row wherever a mark leads it \u2014 a list\'s row, the record\'s head, a link naming the row: the option\'s brand or glyph, else its colour dot, on a tile. The field stays a field: a subtitle run, a column, a section\'s control. A write setting a formula mark is refused (a derived flag is an issue) and a stored one keeps drawing; never beside `image` or `party`, and never the status field |\n| `description` | alias | A text field saying what the row is about \u2014 a plan\'s brief, a customer\'s note: read in its record\'s head under the title\'s line, its first lines at rest and whole on a press, and written from the head\'s \u270E. Never on a row\'s line |\n| `party` | `"person"` \\| `"organization"` \\| `"organisation"` | What each row is where the rows are people (a contact, a patient) or organisations (a customer, a supplier, a carrier); absent, the rows are things (an order, an item, a paper) |\n| `status` | [Status](#status) | The stage a row moves through, a single select, drawn in the record\'s head, or its Side where the Side states it |\n| `figure` | alias | The one number the row stands for, read at its right (a total, a quantity left) |\n| `limits` | map of alias \u2192 (alias \\| number) | A number read against a bound \u2014 a field of the same row or a constant \u2014 drawn as a meter wherever it shows |\n| `gates` | map of alias \u2192 (alias \\| number) | A pass mark on a meter `limits` bounds \u2014 a field of the same row or a constant; a percent field is its share of the bound, any other number an amount. The meter marks it and fills complete once past it |\n| `due` | list of alias (at least one) | Dates that are deadlines (stored, or computed as a date): each counts down and turns overdue until the row is at a `closed` option or `settled` holds, whatever stage it has moved to. A deadline is never an appointment date or the day a stage starts |\n| `frees` | alias | A date ending the row\'s span of days on which what the row holds is free again (a check-out, a hire\'s return): a stay from the 3rd to the 5th holds the 3rd and the 4th, and another may start on the 5th \u2014 on a lanes board, a calendar, a roster and in `no_overlap` alike. Absent, a span of days holds its last day; a span of moments always frees its end |\n| `settled` | alias | A yes/no of the row (stored, a formula: an invoice paid in full, or looked up through a one-row link: a line settled with its parent) that ends its deadlines: while it is true, no `due` of the row counts down or turns overdue \u2014 in a cell, on its line, in its head, on a calendar or gantt, or in the overdue count. A Sheet\'s or reading\'s `where` reads it as any other yes/no |\n| `task` | `true` | A row is work someone finishes: wherever rows of it stand in a table \u2014 a register, a record\'s rows, the rows filed under one \u2014 each is led by a ring ticking it done and unticking it by the one write of the app making that move. Its status is a stored select with `closed` |\n| `applies` | map of alias \u2192 map of alias \u2192 (list of alias (at least one) \\| boolean) | Fields that apply only while their conditions hold (a length only on a line whose tariff charges by the metre): where one does not apply no add asks it and no surface shows it. Never the title; a required one starts at its `default` |\n| `starts` | map of alias \u2192 `"today"` \\| `"me"` | What a field of a row being added starts at, where that start is certain: `today` a date (a moment starts now), `me` a member, the reader adding it; every other field starts empty unless the reader narrowed the register to a value or the field declares a `default` |\n| `issues` | list of (alias \\| [Rolled issues](#rolled-issues)) (at least one) | What is wrong with a row, in priority order, standing in every app that draws it: a formula of the row stating `output_type` boolean (true stands) or text (non-empty stands, its words the sentence), named by alias \u2014 its label is the issue\'s name; or `{ rows: <link> }`, a many-link paired to a one-row link, which rolls up the issues the linked table declares itself, each kept as a count on this table (`<link>_<issue>`), at that position. A derived flag is an issue: state a yes/no formula for each case |\n\n#### Rolled issues\n\n| Key | Type | Meaning |\n|---|---|---|\n| `rows` | alias, required | A many-link of this table, paired to a one-row link on the linked table, which declares issues of its own: each is counted here as `<link>_<issue>`, a roll-up of the linked rows holding it |\n\n<!-- generated:end records -->\n\n<!-- generated:start rules-records -->\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `records.title` | A title is the one field naming the row \u2014 any field but a button or a yes/no \u2014 and the subtitle never names the title\'s own field. |\n| `records.image` | `image` is a files field, never one an Act keeps the documents it makes in (`into`), or a single link to a table with a picture \u2014 its own, or a lookup of one through a single link (never beside a `party`) \u2014 or several of them in order, each stated once. |\n| `records.image_shape` | `image_shape` is portrait, square or landscape, the shape of the register\'s cards and tiles and of a child List stating `layout: "cards"`, stated only where the rows lead with a picture (`image`, or the default lone files field \u2014 not where a `mark` leads or that field is in the title or subtitle). |\n| `records.mark` | `mark` is a single select or a lookup of one through a one-row link, never a formula (a write setting one is refused: a derived flag is an issue), never the status field, nor on the folder an App works inside (`scope`), which its switcher names by a picture or its initials. |\n| `records.description` | `description` is a text field, read in the record\'s head \u2014 never a Field of a part too. |\n| `records.issues` | An issue is a formula of the row stating `output_type` "boolean" or "text" (a derived flag is an issue, never a select), listed once among the table\'s issues, or `{ rows }` naming a many-link paired to a one-row link, listed once, to a table that declares issues of its own \u2014 each rolled issue held as the count `<link>_<issue>` on the table. |\n| `records.figure` | A figure is a number. |\n| `records.applies` | `applies` holds a field of the row other than its title to conditions of the same row \u2014 a yes/no (stored or a formula) by `true` or `false`, a single select by its options, its own or looked up through a one-row link \u2014 never to itself; a required field it holds starts at a `default`. |\n| `records.limits` | `limits` bounds a number by a number field of the row, in its unit or one of the same dimension \u2014 or by a constant, where every row reads the figure in one unit. |\n| `records.gates` | `gates` marks a pass on a meter `limits` bounds: a percent field (its share of the bound), another number in the bound\'s unit, or a constant. |\n| `records.starts` | `starts` starts a field a person writes \u2014 `"today"` a date or a moment (never a span), `me` a member \u2014 and a `create` that does not ask a field it starts writes that start. |\n| `records.due` | A deadline (`due`) is a date. |\n| `records.frees` | `frees` names a stored day, never a moment: a span of moments already frees its end. |\n| `records.settled` | `settled` names a yes/no of the row (stored, a formula, or looked up through a one-row link) beside a `due`: while it holds, the row\'s deadlines neither count down nor turn overdue. |\n| `records.task` | A task entity (`task`) states a `status` of a stored single select with `closed` options \u2014 its ring ticks a row done by moving it to one. |\n| `records.cadence-makes` | *Noted, never refused:* An entity with a multi-select of weekdays that no `cadence` reads, whose rows a one-row child holding a date stands under, states a `cadence` naming the child, and an Act `makes` its rows. |\n| `records.picture` | *Noted by the designer on a write, never refused:* Rows an App draws that each hold one files field no Act makes documents into, no call is filed into, no files gallery keeps and no List compares as a pair (`compare`) \u2014 and no figure \u2014 are pictured by it (`image`); where the workspace\'s files are known, the field holding images is the picture, a figure or not. |\n| `records.mark-derived` | *Noted, never refused:* A table whose `records.mark` is a formula keeps drawing it; a derived flag is an issue, so a write setting `mark` to a formula is refused (`records.mark`) and a stored one keeps drawing. |\n| `records.mark-lead` | *Noted by the designer on a write, never refused:* Rows an App draws of an entity that states a single select besides its status whose options state a mark, and states no `mark`, `image` or `party`, can lead with that field\'s option as their mark (`records.mark`). |\n| `records.stage-holder` | *Noted, never refused:* A stage owned by a member field of the row itself, where the table does not require that field and no `create` or Act of the App states it (asks, sets, requires or writes it), lets a row reach the stage with the field empty: require the field, or state it in a `create` or an Act. |\n\n<!-- generated:end rules-records -->\n\n- **The title names the row** by who or what it is \u2014 a link by the linked row (a job\n read by its customer). Any field but a button or a yes/no may title it, yet a code\n titles a row only where people name the row by it, else it is a `subtitle`; it is the table\'s own setting, which every link shows.\n- **One lead per row.** A row leads with its picture (`image`), a face (`party`) or the\n option of a single select it holds (`mark`) \u2014 never two. A `mark` draws that option\n on a tile: its brand or glyph, else its colour dot; a row holding none, a ring saying\n none is picked. The same tile heads the row\'s record and leads it where a link\n names it; the select stays a field \u2014 a subtitle run, a column, a section\'s control.\n- **A limit** reads a number against a bound \u2014 another field of the row, or a constant.\n A `gates` entry marks a pass on that meter: a percent field is its share of the\n bound, any other number an amount.\n- **A deadline** (`due`) counts down wherever it is drawn and is overdue once past while\n the work is open. A register over the table says how many rows in view are overdue on\n its summary line, and pressing that count narrows to them \u2014 no reading to state.\n- **A span\'s free day** (`frees`) is the end date on which what the row held is free\n again \u2014 a check-out, a hire\'s return. A stay from the 3rd to the 5th holds two nights:\n a lanes board, a calendar and a roster draw it through the 4th, and `no_overlap` lets\n the next stay start on the 5th. Without it a span of days holds its last day; a span of\n moments always ends as the next may begin.\n- **`starts`** is where an add\'s field begins, stated only where that is certain \u2014 a\n log\'s own day at `today`, a request\'s requester at `me`. Nothing else starts a field\n but its declared `default` and what the reader narrowed the register to.\n\n## Record places, pins and cadence\n\nThe rarer keys of `records`, stated beside the ones on `reference/records`: a title read off a photo (`scan`), the rows a child owes each day (`cadence`), where a row stands on a map (`place`) or on a picture (`pin`, `plan_place`).\n\n```jsonc\n// table "site": it owes a diary page each day it works, from breaking ground through handover\n"title": "name",\n"records": { "cadence": [{ "entity": "diary_page", "on": ["mon", "tue", "wed", "thu", "fri", "sat"], "from": "started", "until": "handed_over" }] }\n```\n\n<!-- generated:start records-places -->\n\n#### Record places\n\n| Key | Type | Meaning |\n|---|---|---|\n| `cadence` | list of [Cadence](#cadence) (at least one) | The rows of a child each row owes one of a day, on the days of the week listed or its own multi-select names (a site\'s diary page, Monday to Saturday; a class\'s Tuesdays and Thursdays at 16:00) \u2014 one entry a child, never owed on a day still to come; an Act\'s `makes` makes them. A roster of these rows over days marks a past day owed with none missing in the danger tone, counted in the legend; today\'s is due, offered to add and never marked; each row\'s total reads the days it holds of those owed |\n| `scan` | `"text"` \\| `"iso6346"` \\| `"code"` | Its title, a text field, is painted or printed on the thing a row is (a container\'s number, a seal\'s) and read off one photo on a phone, beside each search matching it and each field holding or picking it: `iso6346` a container number, refused unless its check digit holds; `text` as it stands; `code` a barcode or QR code on the thing, decoded on the device from the photo with no agent |\n| `place` | [Place](#place) | Where a row stands, as plain fields of it, drawn as one place where its record draws the address: how sure it is, a press opening it in the device\'s maps, and one taking it from where the device stands |\n| `plan_place` | [Plan place](#plan-place) | Each row is a place on the plan a `plan` register draws: its title the place\'s code, its subtitle a note. A flat list, no tree |\n| `pin` | [Pin](#pin) | Each row is a place on a picture (a snag on a flat\'s plan, a spot on a container\'s drawing): a List of these rows draws the picture its `on` row holds with a numbered pin at each row\'s own place, each row led by its number, the row opened lit on it and a pin pressed opening its row; where the List writes rows, a press on the bare picture adds one there, and a pin dragged moves its row. A List of rows that link to these by a single link draws their places the same way |\n\n#### Cadence\n\n| Key | Type | Meaning |\n|---|---|---|\n| `entity` | text, required | The table owed: each of its rows stands on one row of this table by its single link to it, and on the first date of its line (`records` title or subtitle) |\n| `on` | list of `"mon"` \\| `"tue"` \\| `"wed"` \\| `"thu"` \\| `"fri"` \\| `"sat"` \\| `"sun"` (at least one) \\| alias, required | The days of the week one is owed on: listed (`mon` to `sun`, each once), or a multi-select of this row whose option aliases are `mon` to `sun` |\n| `from` | alias | A date of this row: the first day one is owed (a site breaking ground, a contract\'s start); absent, no first day |\n| `until` | alias | A date of this row: the last day one is owed (a site\'s handover, a contract\'s end); empty or absent, through today |\n| `start` | alias | A `format: "time"` field of this row (a lookup too): the time of day the child\'s first date starts at, where that date holds a moment |\n| `end` | alias | A `format: "time"` field of this row, where the child\'s second date holds a moment: the same day, or the next where it is earlier; or a number field of this row, the days each runs, where the child\'s dates are days (its last day is the first plus the days less one; an empty length leaves the row unplaced) |\n| `planned` | alias | A stored date of the child, by its alias on that table: the day it was made for, kept when it moves. Set by what makes it, and read for what is still owed; state it with the child\'s link in `unique` |\n| `except` | text | A table of closed days: each of its rows closes the days from the first date on its line to the second. Nothing is owed on them |\n\n#### Place\n\n| Key | Type | Meaning |\n|---|---|---|\n| `address` | alias, required | A text field: the address, as people write it |\n| `latitude` | alias, required | A number field: degrees north, negative south |\n| `longitude` | alias, required | A number field: degrees east, negative west |\n| `accuracy` | alias | A number field: how many metres off the device that gave the place said it may be |\n\n#### Pin\n\n| Key | Type | Meaning |\n|---|---|---|\n| `on` | alias, required | A single link of this row to the row whose picture (its `records` `image`) the place is on \u2014 a container\'s drawing, a floor\'s plan |\n| `x` | alias, required | A number field of this row: how far across that picture the place stands, in percent from its left edge |\n| `y` | alias, required | A number field of this row: how far down that picture the place stands, in percent from its top edge |\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `records.scan` | A title read off a photo or a code (`scan`) is a text field the row stores. |\n| `records.cadence` | A `cadence` names each child once \u2014 its rows standing on one row of this entity by their single link and on the first date of their line \u2014 and its `on` lists each day of the week once, or names a multi-select of this entity whose options are all aliased mon to sun. `from` and `until` are two different days of this entity. `start` and `end` are `format: "time"` fields of this entity (a lookup too): `start` where the child\'s first date holds a moment, `end` where its second does, or `end` a number of days where its dates are days. `planned` is a stored date of the child, never its first or second. `except` is an entity whose line holds a date. |\n| `records.place` | A `place` names four different fields of the row: its address a text field, its latitude, longitude and accuracy number fields it stores. |\n| `records.plan_place` | A `plan_place` names `kind` and `reach_from` as single selects, `sheet` as a single select or a one-row link, `stacked` as a boolean and the rest as numbers, each a different field; `kind`, `x`, `y` required. `size` names three numbers (`across`, `along`, `up`) stating one cell in one length `unit` alike. A `sheet` linking to an entity that states an `image` draws that drawing under the places, `scale` (a number field of that entity) its width in cells; `scale` goes with such a `sheet` alone. |\n| `records.pin` | A `pin` names a single link of the row (`on`) to an entity whose `records` states its `image` (a PDF is drawn as its first page), and two different number fields of the row, how far across (`x`) and down (`y`) that picture in percent. A List of rows whose own entity states a `pin` is drawn over that picture; `on`, `x` and `y` are set by the press that adds a row, never asked. |\n\n<!-- generated:end records-places -->\n\n## Status\n\nA record\'s `status` is the stage a row moves through \u2014 a stored single select, each\noption\'s moment the date `dates` names. A record draws it as its dot and word where Act buttons on the page offer its moves, and as a control for the moves no drawn Act offers: choosing one runs its Act, asking and refusing as its button does.\n\n<!-- generated:start status -->\n\n#### Status\n\n| Key | Type | Meaning |\n|---|---|---|\n| `field` | alias, required | The single select that is the row\'s state, its options in the order the work goes through them, drawn as a line of steps on a record page where no Section states `at` |\n| `closed` | list of alias (at least one) | Options that end the work: a register opens on the rows not at them, and the badge reads muted |\n| `dropped` | list of alias (at least one) | Options of `closed` that leave the work undone (cancelled, rejected): whoever holds the row moves it to one from any stage, where every other move forward passes each owned stage between that binds the row (its `when`) and needs each one\'s owner, and a row leaving one enters a stage as a row made there does |\n| `history` | text | A table every write that sets or moves the status appends one row to (its link to this table, the new status, the moment and who) \u2014 by the record write path, whoever writes: for reporting on every move |\n| `dates` | map of alias \u2192 alias | Option alias \u2192 a date field of this entity the record write path stamps with the moment a row moves into that option, or is made at it \u2014 whoever writes. A value the same write states for that field wins, so past data loads as it happened \u2014 and the `history` records the move at that day, a row made at a later option recording each earlier one whose date the write states, in order; the platform never clears a stamp, so each is when the row last entered the option. A stage\'s date is made where none is named |\n| `stages` | map of alias \u2192 [Stage](#stage) | Option alias \u2192 who owns that stage and how long it should take: the owner alone takes a row out of it, by any write, and presses the acts offered there; every move forward past it of a row it binds (its `when`), and every such row made past it, is its owner\'s too. Its days run from the moment its `dates` field holds. In an app the status then moves only by acts that `set` one of its options \u2014 no save writes it and no act asks it |\n\n#### Stage\n\n| Key | Type | Meaning |\n|---|---|---|\n| `owner` | `"field"` \\| `"link.field"` \\| `{ "group": id }`, required | Who owns the stage: a member field of the row, `link.field` read through a one-row link (not at the stage a row opens at, whose owner made the row: a member field of the row itself), or `{ group }`. A member moves a row off only one stage that groups own, one at a time: the next waits on a different member, or on a stage stating no owner; a row made past a stage signs nothing there |\n| `within` | integer | Whole days the stage should take from the moment the row entered it |\n| `when` | map of alias \u2192 (list of alias (at least one) \\| boolean \\| [comparison](#values) \\| `{ "empty": true \\| false }`) | The rows that must pass this stage: a row meeting every entry on its own fields, as it stood before a write or as the write leaves it \u2014 a single select holding one of these options, a yes/no this value, a number or date meeting its bounds, a field empty or filled; a yes/no or a number may be one a formula yields, a number one a rollup counts or sums. Absent, every row must. A row at the stage leaves it by its owner either way |\n\n#### Stage group\n\n| Key | Type | Meaning |\n|---|---|---|\n| `group` | text, required | A group of the workspace, by id: its members press the act. One person moves a row off only one of the stages different groups own |\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `records.status` | A status is one single select, its options in the order the work goes through them, `closed` naming the ones that end it and `dropped` those of them reached from any stage. |\n| `records.history` | A declared status `history` has exactly one link to the row it records, one single select holding every option of the status (or a text), exactly one date and at most one member. |\n| `records.stages` | A stage\'s owner (`status.stages`) is a single member field of the row, one read through a one-row link (never at the stage a row opens at: its owner made the row, so it is a member field of the row itself), or a group, on an option that does not end the work; a group\'s stage needs the status `history` with who moved the row. Every write takes a row off a stage as its owner alone, and moves a row past it or makes a row past it as its owner alone where the stage binds the row (its `when`) \u2014 a move to a `dropped` option excepted, which whoever holds the row makes from any stage; a row leaving a dropped option, or holding none, enters a stage as one made there. Each stage\'s moment, and each open option\'s, is the date its `dates` names, made where none is named, which every write that opens or moves the status stamps; `within` runs from it. In an App a status with stages moves only by Acts that `set` one of its options \u2014 no save writes it or a date it stamps, and no Act asks either, sets it otherwise or writes either from a workflow; an Act moving a row forward past a stage another owner owns, into an option not `dropped`, keeps its `when` off every row that stage binds. |\n| `records.stage-when` | A stage\'s `when` names the rows that must pass it, as an Act\'s `when` holds them \u2014 single selects to their options, yes/nos to `true` or `false`, numbers and dates to bounds, any field to `{ "empty": true \\| false }` \u2014 on fields of the row itself, stored or computed of it \u2014 a yes/no or a number a formula yields, the number a rollup counts or sums: never the status, a lookup or a computed date or select, and never on the stage a row opens at. It binds a row meeting it as it stood before a write or as the write leaves it; absent, it binds every row. |\n\n<!-- generated:end status -->\n\n- **The status** is one single select. `closed` options end the work: a register opens\n on the rows not in them, a row holding no status among them. A `history` table gets one row per move \u2014 its link to this\n table, the new status (a select holding the same option aliases, or text), the\n moment (the stage\'s `dates` value where the write states a past one, so loaded rows keep\n the day they reached it) and who \u2014 appended by the record write path in every write that opens a row at a\n stage or moves it, whoever writes (the member behind the write is its `by`; an automation\n leaves it empty). A `history` the tables do not declare is derived, and needs no\n `records` of its own.\n- **When each step happened** is the date `dates` names for its option, stamped as the row\n enters it, whoever moves it. One way times a status: a straight-line process is a select\n whose options are its steps in order, each with its date \u2014 never a run of dates the stage\n is read off. An Act that moves the stage and `asks` the step\'s date with `starts: "today"`\n lets the reader record a day already past in the same press.\n\n## Write rules\n\nWhat a WRITE of a table\'s rows meets is stated in the table\'s document, where it applies: `min` and\n`max` on a number or date field, `options_where` and `same` on a link, `suggest` on a text field,\nand `no_overlap` and `natural_key` on the table. A key a field\'s type does not take is refused at\nits path, and a document has no `write_rules` key.\nEvery one but `natural_key` and `suggest` holds on every path a record is written by \u2014 the grid, a record\'s form, an import, a workflow, an\nagent, the API, an app \u2014 judged in the write\'s own transaction, every broken rule listed at once; the\nscreen and a picker only mirror them. A row that already breaks one stays editable until a write\ntouches what the rule reads. `natural_key` names the fields an app recognises a row by, to reuse it where an\nadd or a find-or-create meets it; a record tool or the API creates the row it is handed. `suggest` offers\nvalues in a text control and refuses none. An `options_where` link is refused where a write names a row the\nnarrowing does not admit, and every picker of the link offers only the rows it admits.\n\n```json\n{\n "tables": [\n {\n "ref": "customer",\n "label": "Customer",\n "fields": { "email": { "type": "text", "label": "Email", "unique": true } },\n "natural_key": ["email"]\n }\n ]\n}\n```\n\nA customer above is RECOGNISED by their address. An add that names one \u2014 from the customers\nregister or from a picker\'s "new" \u2014 reuses the row it matches and opens one only where nothing does,\nso the book never grows a second Acme.\n\n```json\n{\n "tables": [\n { "ref": "product", "label": "Product", "fields": { "name": { "type": "text", "label": "Name" }, "in_stock": { "type": "number", "label": "In stock" } } },\n {\n "ref": "order",\n "label": "Order",\n "fields": {\n "name": { "type": "text", "label": "Name" },\n "placed_on": { "type": "date", "label": "Placed on" },\n "due_on": { "type": "date", "label": "Due on" },\n "lines": { "type": "link", "label": "Lines", "table": "order_line", "multi": true, "pair": "order" }\n }\n },\n {\n "ref": "order_line",\n "label": "Order line",\n "fields": {\n "name": { "type": "text", "label": "Name" },\n "order": { "type": "link", "label": "Order", "table": "order", "multi": false, "pair": "lines" },\n "quantity": { "type": "number", "label": "Quantity", "min": 1, "max": 9999 },\n "ships_on": { "type": "date", "label": "Ships on", "min": "order.placed_on", "max": "order.due_on" },\n "product": {\n "type": "link",\n "label": "Product",\n "table": "product",\n "multi": false,\n "options_where": {\n "node_type": "group",\n "logic": "and",\n "children": [{ "node_type": "condition", "type": "number", "field_key": "in_stock", "operator": "greater_than", "value": 0 }]\n }\n }\n }\n }\n ]\n}\n```\n\nA line of nothing is not a line: `quantity` is refused on create and on update. A line ships inside\nits order\'s window \u2014 a bound read off the row a link names is judged when the line is written. Nothing is sold off an empty shelf: every picker of `product`\nreads only the rows that answer its `options_where`, and every save refuses the same rows again.\n\n```json\n{\n "tables": [\n {\n "ref": "booking",\n "label": "Booking",\n "fields": {\n "room": { "type": "text", "label": "Room" },\n "state": { "type": "select", "label": "State", "options": [{ "alias": "held", "label": "Held", "color": "blue" }, { "alias": "released", "label": "Released", "color": "gray" }] },\n "starts_on": { "type": "date", "label": "Starts on" },\n "ends_on": { "type": "date", "label": "Ends on", "min": "starts_on" }\n },\n "no_overlap": { "from": "starts_on", "to": "ends_on", "by": ["room"], "while": { "state": ["held"] } }\n }\n ]\n}\n```\n\nOne booking per room at a time, while it is held \u2014 a create or a save whose span overlaps another\nheld booking of the same room is refused.\n\nA table\'s `checks` (the conditions no write of its rows may meet) are stated in its document and hold on every path a record is written by; their keys, what they read and an example are on `workflows/table-checks`. What follows every committed write of its rows is a workflow, written with `set_workflow` (`workflows/table-workflows`).\n\n<!-- generated:start write-rules -->\n\n#### Suggest\n\n| Key | Type | Meaning |\n|---|---|---|\n| `table` | text, required | The table whose text field is offered from: its id, or its `ref` in this call |\n| `field` | alias, required | The alias of that table\'s stored text field; the field\'s control offers, as the reader types, the distinct values it holds, and any text is still written |\n\n#### No overlap\n\n| Key | Type | Meaning |\n|---|---|---|\n| `from` | text, required | The stored date (or datetime), or time of day (a `format: "time"` text field), a row\'s span starts on: `<field alias>` of the row, or `<link alias>.<field alias>` of the one row a one-row link names (a booking line\'s piece held for its booking\'s dates) |\n| `to` | text, required | The stored date (or datetime) a row\'s span ends on, named like `from` and through the same link \u2014 a day it holds, unless `records` names it the day the row `frees`; a moment another row may start at |\n| `by` | list of text (at least one) | Fields two rows share to compete for a span (the same employee, the same room): `<field alias>`, or `<link alias>.<field alias>` of the one row the span is read through. A field holding many values (a multi-select, a link to several rows, several members) competes where two rows share any one; absent, every row |\n| `while` | map of text \u2192 list of alias (at least one) | Only rows at these options of these selects hold their span (running, not closed), the select named like `from` \u2014 `<field alias>` or `<link alias>.<field alias>`; absent, every row |\n\n<!-- generated:end write-rules -->\n\n<!-- generated:start rules-write -->\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `write.natural-key` | A `natural_key` is text or a number a person types back, or a one-row link; a text key is unique \u2014 `unique: true`, or the key\'s fields as a set in the table\'s `unique`. |\n| `write.bounds` | `min` and `max` bound a number, a date or a time of day \u2014 by a constant a number, by a field of this row or of the one row a one-row link names either, of the same type and unit, never by itself \u2014 and `min` is never above `max`. |\n| `write.bound-per-row-unit` | On a figure whose unit or currency is the row\'s own (its notation\'s `per_row`) a constant bound is only 0 \u2014 bound it by a field of the row. |\n| `write.suggest` | `suggest` stands on a stored text field and names a `table` and a `field`, a stored text field of that table; the app reads that table, so it has a `records` entry. |\n| `write.same` | `same` stands on a link and names one-row links, or lookups of one, this table and the link\'s target both hold to one table. |\n| `write.options-where` | `options_where` narrows a link by an `"and"` group of plain conditions over the target\'s own fields \u2014 a number compared in one unit on every row, a select by options it declares. |\n| `write.no-overlap-night` | *Noted, never refused:* `no_overlap` between two times of day reads a span ending at or before its start within its own day: to midnight, then from midnight. |\n| `write.no-overlap-pair` | *Noted, never refused:* A dated table with a link to a person and a link to a resource, and a `no_overlap` by only one of them, lets the other be held twice: name each in a rule, in a list. |\n| `write.no-overlap` | `no_overlap` is a rule, or a list of rules a row must each meet, spanning two date fields or two `format: "time"` fields, the row\'s own or the one row a one-row link names (`booking.start_on`); `by` names values rows share \u2014 a link, a person, a text or a number, an option, a field of the one row the span is read through (`booking.room`), or a field of many values, which competes where two rows share any one; `while` names single selects by their options, the row\'s own or that linked row\'s. |\n\n<!-- generated:end rules-write -->\n\n- A `natural_key` is `text` or `number`, because a person types it back, or a\n one-row link, because a row is also recognised by the one row it belongs with (a\n fee by its visit and its kind). A key holding a `text` field is unique: `unique:\n true` on that field, or the key\'s fields as a set in the table\'s `unique` (a\n site by its customer and its name) \u2014 two rows sharing it would make\n find-or-create pick whichever the read answered first. An add asks the key by\n default.\n- A `same` link names only rows that name what this row names \u2014 a fee\'s invoice\n is one of its own visit\'s \u2014 through a one-row link both tables hold to one\n table; its picker offers nothing until the row names one. A row added under a\n record names what it copies off it (`default_from`) from the start, so a block\n expecting one line per row of the link lists that record\'s rows alone. A save\n of this row moving what the two compare is refused while they would name apart.\n- An `options_where` link may be left empty; a row it names is refused on every\n save that writes the link unless it holds the narrowing, and the refusal names\n the link and the row. A save that leaves the link alone is not judged, so a row\n still naming a row the narrowing no longer admits stays editable. A link naming\n one kind of a book\'s rows (a "Shipping line" among the parties) narrows to that\n kind, or its picker offers every row.\n\nA field\'s own `required` is not here: the field carries it, and every write\npath refuses the row by field name from it. `unique` is the text field\'s own\nclause (`reference/text`) \u2014 an add says so at the control before the column does. A\nfield the workspace writes (a formula, a rollup, a lookup, an autonumber, a date\nwith `derive_from`) is never asked, written or edited.\n\n## App tree\n\nAn app is a tree of components, assembled the way a page is written in JSX: pick a component, bind it to a table by\nname, and it draws well with no props, because its defaults come from the table\'s facts (`reference/records`, `reference/status`,\n`reference/write-rules`, `reference/field`). A prop overrides a default at its own node. No prop says how anything looks: the runtime\ndraws each concept one way, and a screen the job needs that no component states is told to the person \u2014 the job,\nwhat the app drew, the word wanted \u2014 never props bent to approximate it.\n\n**The smallest tree is one root List.** `{ "type": "App", "key": "orders", "name": "Orders", "children": [{ "type": "List", "entity": "order" }] }`\nis a whole app: the platform composes the rest from the tables and stores it \u2014 the page every row opens, a Section per stage with its moves\nat the foot, a child List per child, the add and the Delete \u2014 and draws the band of readings. What the platform composed beyond what you stated, the answer of `set_app` names (`scaffolded`) and says what it placed or folded in what you stated, so you state only\nthe difference. Lists at the root stand beside one another, two over one entity opening its one page.\n\nEach component is a page of its own: `reference/app-node`, `reference/list-node`, `reference/list-source`, `reference/list-over-a-query`, `reference/list-over-a-query-in-a-record`, `reference/record-node`, `reference/section-node`,\n`reference/steps-node`, `reference/side-node`, `reference/outside-node`, `reference/tab-node`, `reference/sheet-node`, `reference/field-node`, `reference/fieldset-node`, `reference/line-node`, `reference/value-node`, `reference/act-node`, `reference/check-node`,\n`reference/reading-node`, `reference/statement-node`, `reference/comments-node`, `reference/export-node`,\n`reference/query-node` and `reference/workflow-node`. Beside them: `reference/changing-an-app` and `reference/what-an-app-may-write`, `reference/layouts`, `reference/time-layouts`, `reference/plan-layout` and\n`reference/publish-desk` for a List\'s `layout`, `reference/tasks`, and the rules, `reference/app-rules`,\n`reference/reading-rules`, `reference/statement-rules`, `reference/check-rules`, `reference/list-rules`, `reference/record-rules`, `reference/act-rules` and `reference/template-rules`.\n\n<!-- generated:start app-components -->\n\n| Component | Draws | Holds |\n|---|---|---|\n| [App](#app-node) | the launcher tile, the app\'s words, its Views (Lists and Sheets), and its API | List, Sheet, Query, Workflow, Record |\n| [List](#list-node) | rows of an entity: the register, a record\'s child rows, a roster\'s cells, related rows | Tab, Reading, Export, Act, List |\n| [Record](#record-node) | what a row opens: the head and the parts | List, Field, Fieldset, Section, Steps, Side, Outside, Reading, Statement, Comments, Act, Check |\n| [Section](#section-node) | a titled part of a record | List, Field, Fieldset, Reading, Statement, Comments, Act, Check |\n| [Steps](#steps-node) | a record\'s path down the page: one step per Section, the fields, blocks and acts of a stage under its step | Section |\n| [Side](#side-node) | the part the rest is worked from, beside them | List, Field, Fieldset, Reading, Statement, Comments, Act, Check |\n| [Outside](#outside-node) | what one record shows, and which acts it allows, to a person with no seat who opens a link a member made of it | Field, List, Act |\n| [Tab](#tab-node) | one view of a List\'s rows over a period | \u2014 |\n| [Sheet](#sheet-node) | a grid of Readings and Lists over the App\'s rows in its period | Reading, List |\n| [Field](#field-node) | one field: a control, a gallery, prose, a link and its picker, the rows filed under a back-link | \u2014 |\n| [Fieldset](#fieldset-node) | fields of a part read together under a heading of their own, or as Lines of cells the author arranges | Field, Act, Line |\n| [Line](#line-node) | one line of a Fieldset: Fields, Acts and Values in the order stated, after its own label | Field, Act, Value |\n| [Value](#value-node) | a figure worked out on the screen from fields of the record, never stored | \u2014 |\n| [Act](#act-node) | a verb: what pressing it does | \u2014 |\n| [Check](#check-node) | an issue the table declares that refuses the writes and acts it names, or names the act that clears it | \u2014 |\n| [Reading](#reading-node) | a number over rows: one figure, its parts, a grid, per period, steps; or a record\'s own figure; with `planned` and `done`, the work against its plan, day by day | \u2014 |\n| [Statement](#statement-node) | a figure built from figures of the record | \u2014 |\n| [Comments](#comments-node) | the record\'s comment thread, with a box to write one | \u2014 |\n| [Export](#export-node) | a report file of the rows in view | \u2014 |\n| [Query](#query-node) | nothing: a read for agents | \u2014 |\n| [Workflow](#workflow-node) | nothing: a verb for agents | \u2014 |\n\n<!-- generated:end app-components -->\n\n### A node\n\nA node is `{ "type": <Component>, "key"?, ...props, "children"?: [...] }`. `type` names the component, `key` its\nname among its siblings, the other keys its props, `children` the nodes it holds. An unknown prop is refused.\n\n- **Two shorthands, both for Field.** A bare string child is a Field (`"due_date"`); an object with `field` and no\n `type` is a Field with props (`{ "field": "price", "edit": false }`). Both work in every prop that lists fields:\n `create`, a Record\'s `row.subtitle` and `add`, and the `children` of a Record or a part. A column is a field\'s alias, or\n `{ "field", "edit": true }` for the line\'s own control, and takes no other prop.\n- **Fields and options are named by alias**, never by label. A tagged value is an object, never a magic string.\n- **`false` turns a default off at its node:** `"edit": false` makes a field read-only, `"create": false` and\n `"remove": false` take a List\'s add and Delete away, `"readings": false` its band; on a Record, `"row": { "figure": false }`\n drops the row\'s figure, `"row": { "status": { "edit": false } }` the status buttons (another app moves the stage) and\n `"row": { "image": false }` the picture.\n\n### Keys and addresses\n\nA key is unique among its siblings, the way a React key is. A node that binds data takes its key from what it binds:\n\n| Node | Key when none is stated |\n|---|---|\n| Field, Check | its field alias |\n| List | its entity alias |\n| Record | its `entity` alias |\n\nEvery other node states its key. Three kinds of key are unique across the whole app, because each is an API name:\nan Act\'s (its workflow is `act_<key>`, or the one it names), a Reading\'s (its query name for `run_app_query`), and a Query\'s or\nWorkflow\'s.\n\nA node\'s **address** is the path of keys from the app, such as `pages/customer/orders`; the app itself is `/` (the `in` of a node at the root), and its own key is part of no address. A patch may use any ending\nof that path that names exactly one node (`orders`). The exact path wins where one exists; an ending naming two\nnodes is refused, and the refusal lists both paths. `get_app` prints the tree with each node\'s address.\n\n### Values\n\n| Value | Written |\n|---|---|\n| now, the reader, an asked input | `{ "now": true }`, `{ "me": true }`, `{ "input": "name" }` |\n| a computed value | `{ "formula": "{cost} * 1.2" }` over the acted row\'s fields |\n| a call\'s own value, in a Query | `{ "param": "name" }` |\n| cleared | `null` in an Act\'s `set` |\n| an option | its alias |\n\nA **condition** (`when`) maps a select to a list of its option aliases and a yes/no to `true` or `false`; every entry\nholds. A number (a number, currency or percent field, or a formula or rollup yielding one) takes a comparison with any\nof `gt`, `gte`, `lt`, `lte` (at least one, never both `gt` and `gte` or both `lt` and `lte`), each a number; a date\ntakes the same keys with a day (`"2026-03-01"`), a moment on a datetime (`"2026-03-01T09:30"`) or `{ "now": true }`\n\u2014 today, or the current minute on a datetime, read when the rows are, so overdue is `{ "due_on": { "lt": { "now": true } } }`;\nand any field but a yes/no takes `{ "empty": true }` or `{ "empty": false }`. A comparison on a field it does not fit is\nrefused, naming the field, its type and what it takes. A `when` on an Act, a Section or other block, and a List\'s `where`\n(the register\'s or a child List\'s) take these; a child List that adds, picks or expects rows refuses a comparison in its\n`where`, since a row it holds could stand outside it. A **narrowing** (`opens`, a Reading\'s, a Tab\'s or an Export\'s `where`) takes these and also `{ "me": true }` on a member\nfield or a lookup of one, the reader; `where` on a root List or a record\'s child rows fixes the rows on the server for every reader, so it refuses\n`{ "me": true }` \u2014 open on it with `opens`; on a record\'s related rows (`same`, `app`) and on a Sheet\'s List it\nnarrows by the reader and takes it, and those two take no comparison.\n\n## Changing an app\n\n1. `get_workspace` with `kind: "app"` names the app. `get_app` prints the `tree:`, the `node addresses:` (the address of\n each node the app draws, `(default)` on those the tree leaves to the platform) and the `version` line, whose id is the `base_version_id` to send. A member who is not the\n app\'s author is shown no tree. Keep the tree: no tool reads an earlier one.\n2. `set_app` with `app_id`, `base_version_id` (that version: a newer write is refused, not overwritten) and `nodes`,\n (a refused change writes nothing, so `dry_run` is for reading the permissions it would grant and remove). Every answer\n states the permissions the change grants and removes.\n3. `screenshot_app` shows the result.\n\n`nodes` maps an address to a patch of that node. Read against the customers List and page of the account review (`reference/a-complete-workspace`), the call below makes `tier` read-only, moves the Orders Section ahead of Account, adds an Act to\nAccount and removes the Reading:\n\n```json\n{\n "type": "App",\n "key": "account_review",\n "name": "Account review",\n "children": [{ "type": "List", "entity": "customer", "children": [{ "type": "Reading", "key": "ordered_by_tier", "by": "tier", "value": "total_ordered" }] }],\n "pages": [\n {\n "type": "Record",\n "entity": "customer",\n "children": [\n { "type": "Section", "key": "account", "title": "Account", "children": ["tier"] },\n { "type": "Section", "key": "orders", "title": "Orders", "children": [{ "type": "List", "entity": "order" }] }\n ]\n }\n ]\n}\n```\n\n```json\n{\n "app_id": "<id of the app>",\n "base_version_id": "<current_version_id>",\n "nodes": {\n "tier": { "edit": false },\n "orders": { "before": "account" },\n "mark_gold": { "type": "Act", "in": "account", "label": "Make gold", "when": { "tier": ["standard"] }, "set": { "tier": "gold" } },\n "ordered_by_tier": null\n }\n}\n```\n\nEach entry applies in order:\n\n- **An existing node:** a JSON merge patch (RFC 7396) of its props; `null` drops a prop, and a list (`children`,\n `columns`) replaces the node\'s whole, as `layout` does: a patch states the whole layout.\n- **`null`:** removes the node and everything under it.\n- **An address naming no node, with `type`:** adds a node into the node its path names (`"pages/<entity>": { "type":\n "Record", \u2026 }` adds a Record page), or, for a bare key, into the node `in` names (`/` the app); its key is the\n address\'s last word, and a Field states `field` in place of `type`.\n- **`in`, `before`, `after`:** move a node into another, or ahead of or behind a sibling.\n\nThe app\'s own props (`name`, `description`, `icon`, `color`, `words`, `scope`, `period`) change\nthrough `body`, a merge patch over the App node. `dry_run` checks a change and writes nothing.\n\n| To change | State |\n|---|---|\n| a field read-only | `"edit": false` on its Field, or on the Section, Side or Record that draws it |\n| a column added or dropped | `columns` of the List, every column kept: a List that never stated `columns` draws none beyond the row\'s title and its `records` line |\n| a button | an Act node (`reference/act-node`); `confirm` makes its press ask first |\n| a label | the table\'s field `label` in `set_tables`, for every app; for this app alone, `body: { "words": { "<table>": { "fields": { "fee": "Consultation" }, "options": { "urgency": { "rush": "Same day" } } } } }`; a List\'s `label`, a Section\'s `title`, an Act\'s `label`, `add_label` on the add. A Field\'s `label` heads only a gallery or prose block |\n| the order of nodes and rows | `before` or `after` a sibling, or `in` another parent, in the node\'s entry (a Section ahead of another, a Field ahead of another in its Section); a List\'s `columns` read in the order stated; its rows read in its `sort`: `{ "sort": { "field": "collected_on", "desc": true } }` |\n| the row\'s second line | `row: { "subtitle": ["mechanic"] }` on the List: up to two fields under the title, in place of the table\'s `records` line, which stays as it is |\n| a picker\'s add | `add` on the linked table\'s page: `{ "type": "Record", "entity": "pet", "add": ["species", "microchip"] }` asks those fields of the new row; absent, the picker only picks. It holds in every picker of that table in the app |\n| a linked row fixed or deleted where its link stands | the linked table\'s page in `pages`: the link\'s card opens the row in the drawer as that page draws it, saving what it writes, with a Delete where it states `remove: true`. A table a List of the app draws is worked in that List |\n| a headline figure | a Reading in the List: `{ "type": "Reading", "in": "orders", "label": "Prepaid owed", "value": "prepaid", "where": { "stage": ["awaiting_payment"] } }` sums the rows in view; without a `value` it counts them |\n| a calendar and its date | `layout: { "calendar": { "date": "pickup_on" } }` on the List, with `end` for the date a row runs to (both days or both moments); the bare `"calendar"` takes them from the rows\' facts and is refused, naming `date`, where those name none |\n| a record\'s child lines | a List inside the Record\'s Section over the child table: `{ "type": "List", "in": "details", "entity": "repair_line" }`; the child table (one link back to the record) and the record\'s rollup over its rows come from `set_tables` first. Lines priced off a book: `docs path="design/treatments/moves-and-numbers/priced-lines"` |\n\n**What a write stores.** A write stores the pages, platform parts, steps and child Lists the platform composed, and its answer\'s `scaffolded` names each by its path from the root; they are ordinary nodes: edit one, or remove a part, a step or a child List and it stays removed. A page is composed again while a List still opens it; a patch removing the List that alone opened a page takes the page with it where the platform composed all of it (the answer\'s notes say so), and is refused where the page holds what you stated. A Section stating no `children` and no `at` is the platform\'s part of its Record and follows the table: a field the table gains appears in it, while a new child table or stage is yours to add. A Record stating no `children` is composed again. `get_app` marks `(default)` the nodes still left to the platform (the status buttons, the band of readings); patch one by its address and the call states it first: the nearest node the tree does state gains the default child that leads to it, as drawn (every status button of the app, every reading of the band, since stating one stands the others down), then the patch applies. Removing every reading, or every status button, is refused: only `readings: false` on the List or `row.status: { "edit": false }` on the Record draws none. **A stated subtree stays as it is**: a field or option the tables gain later is not added to it, so name it in the tree. An address that ends several drawn nodes is refused, as for stated ones.\n\n**A write places what has one fix, and says so.** The stored tree is the placed one, `get_app` shows it, and the answer lists\neach placement at its address, so you read the difference instead of meeting a refusal:\n\n- `where: { "<field>": { "me": true } }` on a root List moves to `opens`, the chip that names the reader. A child List\n keeps the refusal: bound access with a row rule, or list the rows in a root List.\n- A read-only repeat of a field across a record\'s steps, or a Field beside the files or text block that draws it, is left\n out and said; the statement stays in the tree.\n- `door` on the page of an entity no root List and no Sheet\'s List is over, where the page states no Side, is\n not drawn and is said: its rows open in place. It stays stated, and applies once one of those or a root List does.\n\n## What an app may write\n\nAn app states no list of what it writes: the tree derives it, and the generated workflows accept exactly that, so it is\nalso what an agent can do through the app\'s API. `get_app` prints it beside the tree.\n\n1. **A save of field `f` of table `E`** exists when a node draws `f` on a page of `E`\'s rows (a Field in a Record,\n Section or Side, or a part of the head), the table lets a person write it (stored; not computed, stamped or the\n back side of a child\'s link), no Act of the app on `E`\'s rows writes it, and neither the node nor a container above it\n says `edit: false`. A row\'s stage is moved by an Act or the one button per move a status no Act moves gets, by hand only where its Record\'s `row.status` says `{ "edit": true }`, and by none where it says `{ "edit": false }`.\n2. **An add of `E`** exists for a List over `E` that writes its rows unless it says `create: false` (asking what it lists, and\n setting the link back to the record itself), and for every picker of `E` where `E`\'s page states `add`. An absent `create`\n stands down where the table states no `singular` (nor the app\'s `words`), or where `where` keeps a select at an option an\n Act sets other than the one a new row starts at; a stated `create` list over such a table is refused. A roster\'s cells and\n a document are added only where `create: true`.\n3. **A Delete of `E`** exists for a List over `E` unless it says `remove: false`, and for the table of each of that\n List\'s `sources` (a source has no `remove` of its own). A roster\'s cells, a document and a desk\'s rows are deleted only where `remove: true`.\n A Delete comes with `restore_<entity>`, which brings the row back with the rows its delete took, all or none.\n `remove: false` takes this app\'s Delete away and no more: the record tools, the API and other apps still delete. A row no\n surface may delete is a table check with `on: ["delete"]`.\n4. **An act** exists for each Act node. Every field it sets, asks, files into, signs or records is the act\'s, and read-only\n everywhere else in the app.\n5. **The table\'s contract holds on every path** and is not restated here: required, unique, no overlap, field rules, table\n checks, stage owners, history and the read scope. (`natural_key` is read by an app\'s add and find-or-create alone.)\n\nDrawing is reading or saving; a List that writes its rows also adds and deletes them, until it says `create: false` or `remove: false`, and a List below a part or a Record that says `edit: false` writes, adds and deletes none.\n\n### What a table gives a component\n\n| Table fact | Feeds |\n|---|---|\n| The title | every row\'s name: Lists, a Record\'s head, link chips, pickers, an add |\n| The row\'s line (`records` subtitle, figure, image, mark, party, description) | the row\'s line and head, cards, a checklist\'s photo |\n| The stage (`records` status) | the stage chips, a List\'s `opens`, the badge, an Act\'s moves, stage owners gating acts, a step\'s `at` |\n| Deadlines (`records` due, settled, frees) | countdowns and overdue marks, the default sort, attention order, spans on lanes, calendars and rosters |\n| Bounds (`records` limits, gates, tolerance) | the figure\'s meter, wherever it stands |\n| Tasks and cadence (`records` task, cadence) | the ring on task rows, a roster\'s owed days |\n| Applicability and starts (`records` applies, starts) | a field shown and asked only where it applies; an add\'s starting values |\n| A field\'s `required`, `default`, `default_from`, `natural_key`, `unique` | what an add asks, and what it starts at |\n| A field\'s `notation`, `format`, options, `options_where` | money, units, chips, and what a picker offers |\n| The table\'s `read_scope` | which rows each reader reads, in every List |\n\n### Where the rules stand\n\n`reference/app-rules` and the rule pages after it are every rule the check holds over an app, by id, whichever component it concerns. A\n**language** is decided by the app\'s own words: a tree names no locale, so what an app draws itself (its buttons, empty\nstates, refusals) is in the language its labels are written in, and `words` count as labels. Mix two languages in one\napp and it answers in two.\n\n## App node\n\nAn app draws its launcher tile, its words, its Views and its API. It binds the tables it names: `set_app` fills\n`tables` with the id of every table alias the tree uses, and `templates` with that of every document template alias.\nA relabel on either side is a rename and no tree points at another table by accident.\n\n<!-- generated:start node-app -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `key` | alias, required | The app\'s alias, its name among apps; the App node is addressed `/`, and no address in it starts with this key |\n| `name` | text, required | The job, in the words of the people who do it |\n| `description` | text | What the job is for, in a sentence |\n| `icon` | text | A Lucide icon name in kebab-case the launcher tile draws; absent, the tile draws the one glyph every app without an icon shares |\n| `color` | [colour](#select) | The launcher tile\'s colour |\n| `words` | map of alias \u2192 [Table labels](#table-labels) | A table \u2192 the words this app draws for it |\n| `scope` | alias | The table whose one row the app works inside \u2014 the folder: every List over a table holding a one-row link to it lists the open folder\'s rows and files each add under it; absent, the app reads every row |\n| `folders` | alias | The key of a root List over the table `scope` names: it draws the folders the app opens on \u2014 its columns, filters, grouping, order and summary \u2014 and a row pressed is the folder entered; absent, the folders are listed by their anatomy |\n| `rows` | map of alias \u2192 [Read scope rule](#read-scope-rule) | Each table\'s row rule in this app, by its alias (a table the app only reaches, by the table\'s own alias): who of the people the app is shared with reads which rows, on its screens, its queries, its writes and its workflows. A table the app states none of is read whole by everyone it is shared with |\n| `uses` | list of alias (at least one) | Tables the app\'s Query and Workflow nodes read without drawing them, by alias: they join the tables the app reaches, so a workflow may name them |\n| `period` | `"today"` \\| `"tomorrow"` \\| `"week"` \\| `"month"` \\| `"quarter"` \\| `"year"` \\| [Period days](#period-days) | The window every Sheet opens on: "today", "tomorrow", "week", "month", "quarter", "year" or { "days": n }; absent, the calendar month |\n| `tables` | map of alias \u2192 text | The id of each table the tree names, by its alias: filled by set_app, never written |\n| `templates` | map of alias \u2192 text | The id of each document template the tree names, by its alias: filled by set_app, never written |\n| `children` | list of ([List over a Query](#list-over-a-query) \\| [List](#list-node) \\| [Sheet](#sheet-node) \\| [Query](#query-node) \\| [Workflow](#workflow-node)) (at least one) | The App\'s Views in order \u2014 Lists and Sheets, the first where the App opens \u2014 and its Queries and Workflows. Queries and Workflows alone: an API app, which a server calls with an app key |\n| `pages` | list of [Record](#record-node) (at least one) | The page the rows of an entity open, one per entity, each a Record stating its `entity`; every List over the entity, anywhere in the App, opens it, and a link\'s row no List lists. Absent, the platform draws the page |\n\n#### Table labels\n\n| Key | Type | Meaning |\n|---|---|---|\n| `label` | text | The table\'s name in the plural (a register\'s heading, a block\'s, a link\'s picker) |\n| `singular` | text | One row of the table, as the add and empty sentences name it |\n| `fields` | map of alias \u2192 text | A field alias \u2192 the words this app draws wherever it names the field; the table\'s field keeps its own label |\n| `options` | map of alias \u2192 map of alias \u2192 text | A select field alias \u2192 option alias \u2192 its words |\n\n<!-- generated:end node-app -->\n\n- **Every View at the root is a peer**: a List or a Sheet, in the order stated, the first where the App opens and the\n others each one entry of the App\'s lists, picked under its title, each at its own address: the first at the app\'s root (`/`), any other at `/<key>`, inside the folder where the App is scoped. A List states\n its `label`, any layout, its own Tabs, Readings and Exports, and may read `sources`; two may stand over one entity, and\n both open its one page. Whoever the app is shared with is shown every View, each table narrowed by the App\'s `rows`.\n A list people work every day as a desk of their own is another app.\n- **A Sheet** draws Readings and read-only Lists over the App\'s rows. The App\'s one `period` windows every reading of\n its Sheets placed in time: the calendar month by default, or `today`, `tomorrow`, `week`, `quarter`, `year` or `{ "days": n }`. An App of Sheets alone\n draws the pages its Sheets\' Lists open (a List naming no `app`), each from `pages` as any page is. A Sheet\'s List\n naming no `app` opens its row\'s page in this app, in the drawer over the Sheet, at `/<sheet key>/<row>`.\n- **Query and Workflow** nodes stand at the root and are never drawn.\n- **Writes:** nothing itself.\n\n## List node\n\nA List draws rows of one table. What its rows are depends on where it stands:\n\n- at the App root: a register, a View of its own among the App\'s;\n- under a Record, Section or Side: the record\'s child rows, filed through the child\'s one link to the record\n (`via` where it has several);\n- under a roster List: the rows that fill the roster\'s cells;\n- with `same` or `app`, or on a Sheet: related rows, read only.\n\nA List below a row\'s page is a View too: it takes Tabs, Readings and Exports as a root List does, and its rows open at\n`/<view>/<row>/<key>`, drawn alone with its band, its way back the row\'s page. An Export of it is the file of that one\nrow\'s rows.\n\n<!-- generated:start node-list -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `key` | alias | Names the List among its siblings and in a Query\'s `list`; absent, the entity alias |\n| `entity` | alias, required | The table whose rows the List draws |\n| `sources` | list of [List source](#list-source) (at least one) | Further tables read as one List with this entity |\n| `source_column` | `false` | Reads a List\'s tables as one: false, no column naming each row\'s table and no filter by it; absent, a List with `sources` draws both |\n| `scope` | alias | Says which folder a row files in: with the App\'s `scope`, the one-row link, where the table holds several |\n| `via` | alias \\| text | The link that files the child\'s rows under the record; absent, the child\'s one link to it; a List that only reads may state `<link>.<link>`, reaching the record through a row of their own |\n| `same` | alias | A one-row link of the record: the rows sharing its row, the record left out, read only |\n| `where` | [narrowing](#app-tree) | A fixed narrowing on the server, for every reader: a condition (`reference/values`), and `<link>.<field>`, the rows whose one-row link names a row holding a select or yes/no so. A List that only reads (`same`, a Record with `edit: false`) also bounds a date or number by a field of the record, `{ "record": "<field>" }`: blank, it keeps no row; an Act\'s paper naming the List is handed the same rows; it is never an access bound, which the table\'s row rules are. An add holds only a select\'s option and a yes/no\'s value |\n| `expect` | alias \\| [Expect](#expect) | What a record should hold, shown before it does: one line per option of this select, or per row of this catalog link |\n| `under` | alias | Groups lines by the document covering them: a one-row link to it |\n| `covers` | integer | With a roster\'s cells over days: how many rows each day needs across every lane; a day holding fewer is marked Uncovered. Absent, no day is expected to hold any |\n| `edit` | `false` | Shows rows nobody changes here: false, this List only reads them |\n| `label` | text | The register\'s name in the app\'s lists and tab strip; absent, the entity\'s label. Never the noun of its rows, which is the table\'s label and singular (this app\'s `words`) |\n| `columns` | list of (alias \\| [Edit column](#edit-column)) | Fields read after the row\'s title, each drawn though no row holds it; `{ field, edit: true }` is the line\'s own control, at most 2. Absent: the title and the `records` line alone |\n| `filters` | list of (alias \\| [Tiered filter](#tiered-filter) \\| [Listed filter](#listed-filter)) (at most 3) | Fields the reader narrows by every day, beside the stage chips, at most 3 \u2014 on a plan each is also a choice of what colours its boxes: a select, member, link, date, yes/no or number range of a field its rows draw (a column, the title, the line), never one drawn nowhere; a Reading\'s narrowing names the same; `tiers` bands a number or date; `values` states which values a pick lists |\n| `search` | list of alias (at least one) \\| `false` | Fields the search box reads; absent, every word of the row; false, no search box |\n| `group` | alias \\| `false` | A field the rows stand grouped by, a gantt drawing the groups as its lanes, a lanes board of days its cards\' sub-headings inside each lane; absent, the reader may group by a filter\'s field, a lanes board\'s reader none; false, no grouping |\n| `sort` | [Sort key](#sort-key) \\| list of [Sort key](#sort-key) (at least one) | The rows\' order; absent, a register reads newest made first, a record\'s rows as added |\n| `opens` | [narrowing](#app-tree) | The view the register opens on, a chip the reader may take away: `where`\'s entries but a record bound, and `{ "me": true }` on a member field or a lookup of one |\n| `period` | `"today"` \\| `"tomorrow"` \\| `"week"` \\| `"month"` \\| `"quarter"` \\| `"year"` \\| [Period days](#period-days) | The window a table\'s or cards\' dated Tabs read, or the day, week or month a calendar or lanes board opens on: "today", "tomorrow", "week", "month", "quarter", "year" or { "days": n }; absent, this month |\n| `chips` | `false` | The line\'s one chip row, the stage chips: false, none \u2014 the List then holds every row at every stage, and a filter on the status picks among its options. A root List without `sources` whose `where` keeps the status at one option draws none, unless its `opens` names the status |\n| `checks` | `false` | The filter picking among the Checks its rows hold, each with how many hold it: false, none |\n| `attention` | `false` | Keeps a list in its own order: false, the sort menu offers no attention-first order |\n| `readings` | `false` | Leaves a list without figures above it: false, no band; absent, rows that move, fall due or carry money lead with one. Never with Readings stated |\n| `layout` | [layout](#layouts) | A word, or an object stating one layout with its data; absent, a table |\n| `beside` | `true` | Keeps the list in view while a row is worked: true, a row pressed opens beside this table; a root List drawn as a table. Absent, the page\'s `door` |\n| `compare` | [Compare](#compare) | Each row\'s before against its after: two files fields as a pair of photos, or two values of one type as one column |\n| `current` | alias | A child List of revisions: the child\'s date or number field ordering them. The latest reads as current, the others fold under "superseded \xB7 N"; the record shows the current file through a lookup of the child ordered by it |\n| `create` | boolean \\| list of alias (at least one) | The fields an add asks; `false`: rows are not added here. Absent: where this List writes its rows, the table\'s required fields, natural key and title; nothing where the table states no `singular` (nor the app\'s `words`), or `where` keeps a select at an option an Act sets other than the one a new row starts at. A roster\'s cells and a document add only where `true` |\n| `add_label` | text | The add button\'s words; absent, the platform\'s word and the singular |\n| `remove` | boolean | Rows offer a Delete. Absent: where this List writes its rows; `false`: this app\'s Delete alone is gone, and a row no surface may delete is a table check with `on: ["delete"]`. A roster\'s cells, a document and a desk\'s rows delete only where `true` |\n| `pick` | `true` | Also picks rows of the child that no record holds yet |\n| `when` | [condition](#app-tree) | Drawn only while this holds |\n| `children` | list of ([Tab](#tab-node) \\| [Reading](#reading-node) \\| [Export](#export-node) \\| [Act](#act-node) \\| [List](#list-node)) (at least one) | Its Tabs, band Readings, Exports and Acts over ticked rows or every row in view; under a roster the List of its cells, with `under` the List of its documents. An Act on one row and every Check stand in `pages/<entity>` |\n\n#### Edit column\n\n| Key | Type | Meaning |\n|---|---|---|\n| `field` | alias, required | The column\'s field |\n| `edit` | `true`, required | Lets a person change the value on the line: true, its own control, written in place |\n\n#### Expect\n\n| Key | Type | Meaning |\n|---|---|---|\n| `field` | alias, required | The child\'s title, one row per value: a single select or a one-row link to a catalog |\n| `of` | alias | Lets each record choose its lines: with a select, the record\'s own multi-select naming the options it expects, in place of every option |\n| `only` | list of alias (at least one) | Holds lines for some options alone: with a select, those options; never with `of` |\n\n#### Compare\n\n| Key | Type | Meaning |\n|---|---|---|\n| `before` | alias, required | The rows\' field holding what stood before: files, text, a number, a date or a single select |\n| `after` | alias, required | A field of the same type holding what stands after |\n| `edit` | `true` | The after is written on the line |\n\n#### Tiered filter\n\n| Key | Type | Meaning |\n|---|---|---|\n| `field` | alias, required | A number \u2014 stored, or a formula or rollup reading one \u2014 in one unit for every row |\n| `tiers` | list of number (at least one), required | The breakpoints between its bands, ascending, in the field\'s stored unit: under the first, from each to the next, from the last up \u2014 each band worded in the field\'s notation; a filter picks several at once |\n\n#### Listed filter\n\n| Key | Type | Meaning |\n|---|---|---|\n| `field` | alias, required | A select, member or link field |\n| `values` | `"all"` \\| `"held"`, required | The values its menu lists: all, every option, person or linked row, those no row holds at 0; held, only those the rows hold. A bare field lists a select\'s every option, a member\'s or link\'s held |\n\n#### Sort key\n\n| Key | Type | Meaning |\n|---|---|---|\n| `field` | alias, required | The field rows are ordered by |\n| `desc` | boolean | Latest or largest first; absent or false, soonest or smallest first |\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `list.scope` | With the App\'s `scope`, a List over a table holding one one-row link to the folder\'s table is filed in the open folder by it, and one holding several names it in `scope`; that link is required. A List over the folder\'s own table states no `scope`. |\n| `list.unscoped` | *Noted, never refused:* In an App that states `scope`, a List over a table holding no one-row link to the folder\'s table lists every row, in every folder; so does a Tab\'s totals over a child holding no single link to it. |\n\n<!-- generated:end node-list -->\n\nA List takes only the props its place lists:\n\n<!-- generated:start list-places -->\n\n| A List standing in | Takes |\n|---|---|\n| every List | `key`, `entity` |\n| every List on a record | `via`, `label`, `when`, `filters`, `search`, `group`, `sort`, `chips`, `checks`, `opens`, `period`, `attention`, `readings` |\n| a root List (the first is the register) | `label`, `columns`, `filters`, `search`, `group`, `sort`, `chips`, `checks`, `opens`, `period`, `attention`, `layout`, `beside`, `create`, `add_label`, `remove`, `readings`, `where`, `edit`, `sources`, `source_column`, `scope` |\n| a record\'s child rows, as cards, a table, a checklist, a desk or a gantt (cards refuse `under`, `compare`, `current`, `expect`, an `edit: true` column and rows that nest as an outline; a table refuses a `compare` of photos; a gantt refuses `under`, `pick`, `compare`, `current`, `expect` and an `edit: true` column) | `columns`, `create`, `add_label`, `where`, `under`, `remove`, `pick`, `layout`, `compare`, `current`, `expect` |\n| a record\'s child rows with `layout` an agenda | `columns`, `create`, `add_label`, `remove`, `layout`, `edit` |\n| a record\'s child rows with `layout` `"timeline"` | `create`, `add_label`, `remove`, `layout`, `edit` |\n| a record\'s related rows, read only (`same`, or a Record that is `edit: false`) | `where`, `columns`, `same`, `edit` |\n| the documents a child List\'s lines stand under (`under`), a List inside it | `create`, `remove` |\n| the cells of a roster, a List inside it | `expect`, `covers`, `create`, `remove` |\n| a Sheet\'s list, read only | `label`, `where`, `columns`, `sort` |\n\n<!-- generated:end list-places -->\n\n- **The page a child List\'s rows open** is the entity\'s page in `pages`: its Fields in stated order, those the rows\' saves write editable, and the List\'s `columns` are the line. A row opens in place under itself: its fields or Sections, then each List of its own children, at any depth; one row is open at a time. Every row of a List that adds rows offers "Duplicate" in its \u22EF: the add opens with the row\'s values of the List\'s `create` fields, filed under the row\'s own parent (in an outline, the row above it), never carrying a status, a computed value or files. With `edit: false` the List reads as a related-rows List does.\n- **Documents:** in a child List with `under`, a List over the document\'s table (`key`, `entity`, `create`, `remove`,\n Acts and Checks; the document\'s Fields and Lists stand in its page) is the one place the documents are added or deleted;\n `create` states `true`, and `remove` needs `create: true` beside it.\n- **Writes:** a layout move (a gantt bar, a lane\'s block, a plan\'s item) writes only fields the app already writes on the row\'s page.\n- **`create` asks:** `true` asks the title, the natural key and every required field a person writes, never a computed\n or stamped field or the link the place sets. An `expect` list also asks the key it makes its lines by, and their picture.\n- **`filters`:** a threshold the business names ("large orders") is a formula yes/no, and bands it names (new, warm, cold) a formula with options, never a range.\n- **`opens`** absent, the register opens on the open work (rows not at a `closed` stage).\n- **`expect`:** an empty line adds its row (a checklist of papers per case).\n\n## List source\n\nSources are further tables a root List reads beside its entity as one List: the same job kept in tables of their own (a legacy ledger, a second branch\'s register). Each is projected onto the List\'s fields \u2014 by alias, else by its `fields` (the List\'s field \u2192 the source\'s) \u2014 and options line up by alias; its `where` narrows its own rows. Each row opens its own table\'s page in `pages`, stated or refused (`list.source-page`), and runs the Acts and Checks that page states: nothing the List offers its own rows reaches a source\'s. The add offers each table, asking the List\'s `create` in that table\'s fields; a source lacking one adds no row. A column naming each row\'s table, and a filter by it, draw by default; `source_column: false` hides both. Every source holds the title and the scope, and may hold no stage (its rows wear none and stand in no stage chip); its `columns` name value fields of its own table (not links or files) drawn on its rows alone, on a lanes board only; a table, cards, lanes or a plan reads sources, and an Export\'s `sources` makes a report of some of them.\n\n<!-- generated:start node-list-source -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `entity` | alias, required | A further table this List reads beside its own entity: the same job over its rows |\n| `fields` | map of alias \u2192 alias | A field of the List\'s entity \u2192 this table\'s field holding the same fact, where their aliases differ |\n| `where` | [narrowing](#app-tree) | Which of this table\'s rows the List reads |\n| `columns` | list of alias (at least one) | Fields of this table with no counterpart in the List\'s entity, drawn on this table\'s rows alone |\n| `row` | [List source row](#list-source-row) | How the List reads this table\'s rows, where it differs from the table\'s `records` |\n\n#### List source row\n\n| Key | Type | Meaning |\n|---|---|---|\n| `status` | `{ "edit": true }` | Lets a person move this table\'s stage by hand in the List: `{ edit: true }` |\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `list.sources` | A List\'s `sources` each name another entity once (`entity`) \u2014 never the List\'s own \u2014 whose fields line up with the List\'s by alias, else by `fields` (a field the List reads, or one an Export prints \u2192 one of the source\'s): read as one column type (a day apart from a moment), one value or several alike, a link to the same entity. Each source holds the title, the List\'s folder link and what `where` keeps; it may hold no status \u2014 its rows wear none and stand in no status chip, only the total\'s. Its `columns` name fields of its own table that no List field stands for, drawn on its rows alone and only on a lanes board \u2014 a text, number, date, select or yes/no field, or a lookup of those, never a link or files; an alias a List field or another source\'s column holds is refused; its own `records` status stays its page\'s; the List is a table, cards, lanes or a plan, whose `at`, `across` and `up`, or lanes\' `by` and loads, line up like any field. Two sources holding a field of their own under one alias hold it as one kind of value. An Export\'s `sources` each name the List\'s entity or one of its sources, once, and one of them holds each field its `where` and `per` narrow by. A List with `sources` draws a column naming each row\'s table, and a filter by it; `source_column: false` draws neither. A source\'s rows open the page of its own entity, which states the Acts and Checks they run: each Act\'s `key` its own among the App\'s Acts. |\n| `list.source-lacks` | *Noted, never refused:* A source lacking a field its List\'s `create` asks adds no row; one lacking the select its List\'s plan marks or sizes by never marks or sizes its rows. A field only an Export prints, held by a source as another kind of value, prints blank on its rows. A Tab\'s `totals` over a child linking to no row of a source total nothing on its rows. |\n| `list.source-option-kin` | *Noted, never refused:* A source\'s option labelled as one of the List\'s, under another alias, reads apart from it: the List lists both and counts each on its own. |\n\n<!-- generated:end node-list-source -->\n\n## List over a Query\n\nA root List that states `query` reads the rows of a root Query of the App in place of a table\'s. The Query states `ast` and no `params`, and its rows each come from one record of a table it scans: a Query that groups has no such record, and its rows are counted in a Reading. A row opens that record\'s page, so each table its rows are records of is named by the App and has a page (a Record in `pages`, or a List over it). The rows are read-only and in no folder. The List may hold Acts that act on no row: an Act states `key`, `label`, `on: "view"`, `workflow`, `asks` (inputs only, no field), `confirm` (`true` or a question, never `"warnings"`) and `danger`, runs its workflow with only what it asks (adding a row to the table the reader names, say), and is run by people inside the organization alone.\n\nEvery name the List states \u2014 `title`, `subtitle`, `columns`, `where`, `filters`, `search`, `group`, `sort`, `opens`, a Tab\'s, a Reading\'s and an Export\'s fields \u2014 is an output column of the Query, an alias holding one value. A select column passes a select field through, or writes an option key in the arm: `{ "source": { "literal": "ha" }, "type": "select" }`, worded by `words.<list key>.options.<column>.<key>`. A select read from several tables holds each table\'s option under its alias, and a chip, filter, `opens` and `where` on the alias match every one of them. A union under a `project` or a `limit` keeps the List\'s filters above it, so a column a filter or search narrows belongs in each arm\'s own projection. A number column reads the currency or unit its arms\' fields share, an arm\'s `{ "expression": \u2026 }` that only adds, subtracts or coalesces fields (`coalesce(input.a, 0) + input.b`) reading those it names; any other arm, or fields of different formats, leaves it a plain number.\n\n<!-- generated:start node-list-query -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `key` | alias, required | Names the List among the App\'s Views, and its rows in a report and in the App\'s `words` |\n| `query` | alias, required | The key of a root Query of the App stating `ast`, that is no group: each row it returns is a record of one of its tables and opens that record\'s page; its output columns are what this List names |\n| `label` | text, required | The register\'s name in the app\'s lists and tab strip |\n| `title` | alias, required | The column naming each row |\n| `subtitle` | list of alias (1\u20132) | Up to two columns read under the title |\n| `columns` | list of alias | Columns read after the row\'s title; absent, the title and subtitle alone |\n| `where` | [narrowing](#app-tree) | A fixed narrowing on the server, for every reader, over the Query\'s columns |\n| `filters` | list of (alias \\| [Tiered filter](#tiered-filter) \\| [Listed filter](#listed-filter)) (at most 3) | Columns the reader narrows by every day: a select, member, link, date, yes/no or number range of a column its rows draw, never one drawn nowhere; a Reading\'s narrowing names the same; `tiers` bands a number or date; `values` states which values a pick lists |\n| `search` | list of alias (at least one) \\| `false` | Columns the search box reads; absent, every text and link column the List draws; false, no search box |\n| `group` | alias \\| `false` | A column the rows stand grouped by; absent, the reader may group by a filter\'s column; false, no grouping |\n| `sort` | [Sort key](#sort-key) \\| list of [Sort key](#sort-key) (at least one) | The rows\' order; absent, the Query\'s own |\n| `opens` | [narrowing](#app-tree) | The view the rows open on, a chip the reader may take away: `where`\'s entries but a record bound, and `{ "me": true }` on a member field |\n| `period` | `"today"` \\| `"tomorrow"` \\| `"week"` \\| `"month"` \\| `"quarter"` \\| `"year"` \\| [Period days](#period-days) | The window its dated Tabs read; absent, this month |\n| `readings` | `false` | false, no band; absent, the band is the Readings it holds, none when it holds none. Never with Readings stated |\n| `children` | list of ([Tab](#tab-node) \\| [Reading](#reading-node) \\| [Export](#export-node) \\| [Act](#act-node)) (at least one) | Its Tabs, band Readings, Exports and Acts that act on no row |\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `list.query` | A List\'s `query` names a root Query of the App stating `ast` and no `params`, reading only tables the App names; the List\'s `key` names no table. |\n| `list.query-rows` | A List over a Query lists records: its Query\'s rows each carry the record they come from \u2014 no `group` on their way out. |\n| `list.query-opens` | Each table a List over a Query lists records of is an entity the App draws, whose page its rows open. |\n| `list.query-columns` | A List over a Query names its Query\'s output columns: each an alias holding one value; a select column passes a select field through or writes an option key (a select literal) in every arm, and a link column links one table. |\n| `list.query-scope` | A List over a Query stands in an App with no `scope`: the Query reads no folder. |\n\n<!-- generated:end node-list-query -->\n\n## List over a Query in a Record\n\nA child List of a Record, a Section or a Side that states `query` draws the rows of a root Query of the App that link to the record. The Query is held to what a root List over a Query holds it to, and returns a column linking to the record\'s table (`via` names it where several do); it cuts no rows (`limit`, `window`), which the record\'s narrowing would then miss. A row opens its own table\'s page. The List is read-only: it holds no Tab, Reading, Export, Act or filter, and no table child of the record has the same key as another List over a Query.\n\n<!-- generated:start node-list-query-record -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `key` | alias, required | Names the List among the record\'s parts; unique among the App\'s Lists over a Query |\n| `query` | alias, required | The key of a root Query of the App stating `ast`, that is no group and cuts no rows above its tables: the rows of it that link to this record are drawn, and each opens its table\'s page |\n| `label` | text, required | The block\'s name in the record |\n| `title` | alias, required | The column naming each row |\n| `subtitle` | list of alias (1\u20132) | Up to two columns read under the title |\n| `columns` | list of alias | Columns read after the row\'s title; absent, the title and subtitle alone |\n| `where` | [narrowing](#app-tree) | A fixed narrowing on the server, for every reader, over the Query\'s columns |\n| `sort` | [Sort key](#sort-key) \\| list of [Sort key](#sort-key) (at least one) | The rows\' order; absent, the Query\'s own |\n| `via` | alias | The Query\'s column linking each row to this record, where several link to it |\n| `when` | [condition](#app-tree) | Drawn only while this holds |\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `list.read-scope` | A child read under a record whose rows a `read_scope` narrows states its own \u2014 a row rule is not inherited, save the status history\'s, which takes its record\'s. |\n\n<!-- generated:end node-list-query-record -->\n\n## Layouts\n\nA List\'s `layout` is how it draws its rows: a word (`"table"`, `"cards"`, `"calendar"`, `"roster"`, `"timeline"`) or an\nobject stating one layout and the data it reads (`{ "gantt": \u2026 }`, `{ "lanes": \u2026 }`, `{ "plan": \u2026 }`, `{ "agenda": \u2026 }`,\n`{ "checklist": \u2026 }`, `{ "desk": \u2026 }`). Absent, the register draws a table; a child List states `"cards"` (the register\'s card grid, whatever\nits rows hold), `"table"` (always a table, even over pictures or long text), a checklist, a desk, a gantt, an agenda or\n`"timeline"`, else leaves `layout` out and draws rows holding pictures, long text or a pair of photos as cards and the rest as a table. Each layout reads what the rows already state \u2014 their\n`records` line, stage and dates \u2014 and the keys a layout adds stand on its section: here for an agenda and a checklist, `reference/time-layouts` for lanes and a gantt, `reference/plan-layout` for a plan, `reference/publish-desk` for a desk. Which one a job needs: the\n`design` reference. The register lays out as a table, cards, a calendar, a roster, a gantt, lanes or a plan; a record\'s\nchild rows as cards, a table, a checklist, a desk, a gantt, an agenda or a timeline.\n\n### Table\n\n<!-- generated:start layout-doc-table -->\n\nAbsent `layout`, each row is one line: the table\'s `records` entry \u2014 its picture or mark, title and the line under it \u2014\nthen the stage, the `columns`, and the figure at the right; the title, the stage and a column of days or amounts sort\nthe rows by their header. A table groups its rows by `group`; a table or cards reads `Tab`s and the `sources` of its List.\n\n<!-- generated:end layout-doc-table -->\n\n### Cards\n\n<!-- generated:start layout-doc-cards -->\n\n`"cards"` draws each row as a card led by its picture \u2014 the `records` `image`, or the List\'s `row.image`: its title and\nthe line under it, its stage and what needs the reader (a deadline, a warning), then its figure and the `columns` at its\nfoot. Cards are for rows found by their picture (a product, a vehicle, a damage photo); rows with no picture read better\nas a table.\n\n<!-- generated:end layout-doc-cards -->\n\n### Calendar\n\n<!-- generated:start layout-doc-calendar -->\n\n`"calendar"` or `{ "calendar": { "date": "starts_at", "end": "ends_at" } }` places each row on its day \u2014 a month, a week,\na day or a list (a phone reads the list or a day): at its hour where `date` holds one, over its span where `end` names\nthe date it runs to, with its line\'s other words and the `columns` after its title. `date` and `end` are two dates of\nthe row, both days or both moments; a span of moments gives a phone its day view, and a day\'s `end` is the last day held\n(unless `records` names it the day the row `frees`). The bare word takes them from the rows\' facts: two dates a person\nstates, the second ordered after the first by a `min` or a table check, both required or the second the row\'s `due`; else the one required date a person states that no Act stamps and a new row does not start at today \u2014 and is refused, naming `date`, where the rows hold neither. A `due` is a deadline, never the day a row is held on. The calendar reads the window in view, and its count and the stage chips count that window, opening on every row.\n\n<!-- generated:end layout-doc-calendar -->\n\n<!-- generated:start layout-calendar -->\n\n#### Calendar keys\n\n| Key | Type | Meaning |\n|---|---|---|\n| `date` | alias, required | The date or moment of this entity each row stands on: a viewing\'s start, a hire\'s first day, a visit\'s day |\n| `end` | alias | The date or moment each row\'s span ends on, read as `date` is \u2014 two days or two moments (a moment\'s end gives a phone its day view); absent, a row stands on `date` alone |\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `list.calendar` | `layout: "calendar"` or `{ calendar: { date, end } }`: two dates of the row, both days or both moments; bare, it takes the rows\' span or appointment, else is refused, naming `date`. |\n\n<!-- generated:end layout-calendar -->\n\n### Roster\n\n<!-- generated:start layout-doc-roster -->\n\n`"roster"` draws the List\'s rows down the side and the days of a week or a month across; the roster\'s cells are a List\ninside it over the table whose rows fill the days \u2014 each stands on one row by its single link to it, and on the first\ndate of its line (a shift on a person\'s day, a run on a vehicle\'s), on every day through the second date where its line\nholds one. A cell reads its row\'s stage, else the first single select on its line (a shift\'s kind), several rows their\ncount. A day holding none stays empty: nothing was due, which is never an absence. A filled cell opens its row; an empty\none adds a row there, the register row and the day set. With `expect` on the cells (a single select of those rows) the\ncolumns are its options in place of days \u2014 a checklist of papers \u2014 and `of` names the ones each row expects: a gap among\nthem reads as one and adds its row, the others stand blank, and each row reads what it holds of them, `2/3`. Over days, a\nroster reads the `cadence` its table\'s `records` states (a site\'s diary page, Monday to Saturday from breaking ground to\nhandover): a past day owed with none is marked missing and counted, and each row reads the days it holds of those owed. A\nroster states no `columns` and needs no readings: its legend counts each state in view. `covers: 2` on the cells List says each day\nneeds two rows across every lane: a day holding fewer is marked "Uncovered" in its head, counted in the legend, and the\nExport\'s `columns` carry `covered` (false on such a day) for every day of the window.\n\n<!-- generated:end layout-doc-roster -->\n\n```json\n{ "type": "List", "entity": "operator", "layout": "roster", "filters": ["depot"], "children": [{ "type": "List", "entity": "run" }] }\n```\n\n### Timeline\n\n`"timeline"` reads a record\'s child rows as a log of dated entries, newest first, with a composer where the app adds\nentries, each corrected and removed where it stands. It is never the record\'s status history: the rail shows each\nmove. A timeline\'s moment is its child\'s first date, and who its member field. Rows each what happened on a day and who \u2014\na date on their line, a member, no stage and no figure \u2014 read best as a timeline.\n\n### Agenda\n\n`{ "agenda": { \u2026 } }` reads a record\'s child rows as planned entries on a time axis: by day, soonest first, each with its\npicture and the day that is today marked. The day is the first date on the child\'s row line (its `records` title or\nsubtitle); within a day entries follow a datetime there, else the first single select after the date. An entry with no day\nyet is a plan, listed first and dated in place. `start` is the record\'s date that is the first day: each day\'s heading\ncounts from it (Day 1, Day 2).\n\n<!-- generated:start layout-agenda -->\n\n#### Agenda keys\n\n| Key | Type | Meaning |\n|---|---|---|\n| `start` | alias | The record\'s date that is the first day: each day\'s heading counts from it; absent, the weekday and the date alone |\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `list.agenda` | An agenda List\'s child names a date on its row line (`records` title or subtitle); the layout\'s `start` is a date of the record. |\n| `list.agenda-note` | *Noted, never refused:* Rows each on a day and within it (at an hour, in a part of the day) listed as a table: a List with `layout: { agenda }` draws them by day. |\n| `list.timeline` | A timeline List\'s child holds a date to place its entries by. |\n| `list.timeline-note` | *Noted, never refused:* Rows each what happened on a day and who \u2014 a date on their line, a member, no status and no figure \u2014 listed as a table: a List with `layout: "timeline"` draws them as a timeline, newest first. |\n\n<!-- generated:end layout-agenda -->\n\n### Checklist\n\n`{ "checklist": { \u2026 } }` reads a record\'s child rows, which are tasks, as a checklist of checks: each one\'s mark \u2014 passed\nat a `closed` option, failed at a `failed` one, else still to check \u2014 its title, its columns as its words (a text column\nits note, on its own line), and on a line under its title its photo and its clause. Never grouped nor written in place.\n`passed` alone sets the mark, so rows with no `task` and no status are checks: a measured yes/no is the verdict. With\n`expect` on the standard\'s items, each item is a line marked the same way (a missing one still to check), filled in\nplace by the block\'s `columns` (a measured value, a note, a photo), so `photo` and `clause` are not named.\n\n<!-- generated:start layout-checklist -->\n\n#### Checklist keys\n\n| Key | Type | Meaning |\n|---|---|---|\n| `photo` | alias | The child\'s files field holding the photo each row is checked by; absent, the child\'s `records.image` |\n| `clause` | alias | The child\'s one-row link to what each row is checked against \u2014 a standard\'s clause, a rule |\n| `failed` | list of alias (at least one) | Options of the child\'s status a row stands failed at \u2014 none of them closed |\n| `passed` | alias | The child\'s yes/no field (stored or a formula) setting each row\'s mark: yes passed, no failed, empty still to check |\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `list.checklist` | A child List with `layout: { checklist }` reads a task entity\'s rows as checks \u2014 never under documents, grouped, edited in place or picked together by an Act over several, its columns no files; `photo` names a files field of the child, `clause` a one-row link of it, `failed` options of its status, none `closed`; `passed` a yes/no of it, stored or a formula, setting each mark (yes passed, no failed, empty still to check) and standing without `task` or a status. With `expect` the lines of a standard are the checks, each marked and filled by the block\'s columns (a measured value, a note, a photo), so `photo` and `clause` are not named. |\n\n<!-- generated:end layout-checklist -->\n\n## Time layouts\n\nThe layouts that place a List\'s rows in time. Each is a `layout` object stating the data it reads.\n\n### Lanes\n\n<!-- generated:start layout-doc-lanes -->\n\n`{ "lanes": { "by": \u2026 } }` draws each row of the linked table as a lane (a chair, a machine, a room), empty ones too,\nand each row of the List as a block from the first date on its line (or `date`) to the second (`end`): over the hours of one day, where the\nfirst holds its hour (a week of them draws each day\'s cells, a block\'s time range its first fact), else over the days of one day, a week or a month. A press on a free stretch adds a row there, its lane and start set, its end where the next block bounds it. Rows naming no lane stand first, in a lane of their own; where the app writes the link, a block moves to another lane from its menu. Inside a `scope`, the lanes are those whose own one-link names that scope\'s row. A span\'s\nend holds its day unless `records` names it the day the row `frees`.\n\nRows with no hour read at one day as cards in lanes: the rows no lane holds first, in a tray that\nalso holds the rows with no day, then each lane with its count and its status where its table states one; a lane its link no longer admits says so on its head and takes no new card. A card\'s lead is its\ntick; ticked cards, or one dragged, go to a lane together in one write, every row judged before any is written. The List\'s first\n`sort`, where a stored number the app writes, is a card\'s place in its lane. A week of such rows, or rows with an hour, keep the blocks.\n\n`by` may instead name a member field holding one person, with `of` a group of the workspace, by id, whose every member is a\nlane \u2014 `{ "lanes": { "by": "engineer", "of": "grp_\u2026" } }`; a `no_overlap` by that member keeps one row per person at a time.\nOr a field holding one option (a single select, a formula stating options, a lookup of either through one-row links): each option is a\nlane in its order, the rows holding none in the tray, no add from a lane, a card given to an option where the app writes a stored select.\n`loads` read a lane\'s row, which neither is.\n\n`down` stands bands down the board of days: a card stands in the cell of its lane and band, the rows holding none in a last band drawn\nwhen a card in view holds none; where the app writes the `down` field, a card dropped in a cell is given both in one write.\nA List\'s `group` stands its cards in each lane (and cell)\nunder the group\'s sub-headings, a group holding no card there not drawn.\n\n`loads` names what a lane carries: `{ "weight": "payload", "volume": "box" }` sums each block\'s number against the lane row\'s own; each block then reads that number after its first column. A lane reads the most its\nblocks add up to at one time (hours add up within each day, across days the fullest day is read), named past its bound, by how much and when. `"per": "week"` holds the bound over the calendar week of the day in view instead, on a day, a week or a day of hours, the\nhead saying "6 h of 40 h this week". A bound a single row must keep (no parcel heavier than its van) is a `max` on the field through the link, which refuses the move.\n\n<!-- generated:end layout-doc-lanes -->\n\n<!-- generated:start layout-lanes -->\n\n#### Lanes keys\n\n| Key | Type | Meaning |\n|---|---|---|\n| `by` | alias \\| [Lanes axis](#lanes-axis), required | The field the rows stand in lanes by: a one-link, a member (with `of`) or a one-option field |\n| `of` | text | A group of the workspace, by id, whose every member is a lane |\n| `down` | alias \\| [Lanes axis](#lanes-axis) | The field the rows stand in bands by: a one-option field or a one-link |\n| `date` | alias | The day a row stands on: a date of the row, or a lookup of its parent\'s through one-row links |\n| `end` | alias | With `date`: the day it ends |\n| `loads` | map of alias \u2192 alias | A number of this entity each block adds \u2192 a number of the lane\'s row it bounds |\n| `per` | `"day"` \\| `"week"` | With `loads`: `day` (default) or `week` |\n\n#### Lanes axis\n\n| Key | Type | Meaning |\n|---|---|---|\n| `field` | alias, required | The board\'s field |\n| `values` | `"all"` \\| `"held"`, required | `all` draws every one, `held` only those a row in view stands in |\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `list.lanes` | `layout: { lanes }`: `by` and `down` (never one field) each name a one-row link to a table stating `records` or a one-option field, `by` also a member with `of`; the rows name a date on their line or in `date`, `end` read alike (two days or two moments); `loads` and `per` stand with a link `by` only, `values: "held"` never beside `of`, and a board by options, with `down` or `group` reads one day from a date, never a moment. |\n| `list.loads` | A lanes layout\'s `loads` names one to 2 numbers a lane block adds \u2014 never a percent \u2014 each against a number of the lane\'s row, in one unit or two of one dimension; `per` (day or week) stands only beside `loads`. |\n\n<!-- generated:end layout-lanes -->\n\n### Gantt\n\n<!-- generated:start layout-doc-gantt -->\n\n`{ "gantt": { \u2026 } }` draws each row as one bar on one axis of time: `{ "start": "etd", "end": "eta", "milestones":\n["cut_off"], "planned": { "end": "booked_eta" }, "progress": "done", "after": "waits_on" }`. `end` defaults to the table\'s\nfirst `due`, and a table with neither is refused. The bars\nstand in the lanes of the List\'s `group`. Where the app writes the row and a person writes a bar\'s date, the bar is\ndragged through the row\'s save; a computed date, one an Act sets, or a row the app does not write drags nothing. Over a\ntable that holds rows under rows, each bar stands under the row above it, indented and folded as the register\'s outline\nis, `group` still the outer section. A child List of a record may lay out as a gantt too: the bars of the rows the\nrecord\'s link names.\n\n<!-- generated:end layout-doc-gantt -->\n\n<!-- generated:start layout-gantt -->\n\n#### Gantt bar\n\n| Key | Type | Meaning |\n|---|---|---|\n| `start` | alias, required | A date of this entity each row\'s bar starts at (a sailing, a hire\'s start, a task\'s start) |\n| `end` | alias | The date each row\'s bar ends at, read as `start` is \u2014 two days or two moments; absent, the entity\'s first `due` |\n| `milestones` | list of alias (at least one) | Dates of the row marked on its bar\'s line as diamonds, each named by its label (a cut-off, a delivery, the end of free time) \u2014 never `start` or `end` |\n| `planned` | [Gantt plan](#gantt-plan) | The plan each row is read against, drawn as a thin bar under its own \u2014 each date read as `start` is; a missing one is the bar\'s own |\n| `progress` | alias | A percent of this entity (0\u2013100) filling each row\'s bar as far as the work is done; absent, how many of the row\'s tasks are done fills it where its record lists them, else the bar wears its status\'s tone |\n| `after` | alias | A link of this entity to its own rows each row waits on \u2014 it starts once they end (finish-to-start), an arrow from each; a row starting before one ends is drawn in the danger tone |\n\n#### Gantt plan\n\n| Key | Type | Meaning |\n|---|---|---|\n| `start` | alias | The date the row was planned to start at |\n| `end` | alias | The date the row was planned to end at (a booked arrival) |\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `list.gantt` | `layout: { gantt }`: `start` and `end` (absent, the entity\'s first `due`) are two different dates of the row, both days or both moments; each diamond (`milestones`) another date of it, each planned date read as `start` is, `progress` a percent and `after` a link to rows of the same entity. |\n\n<!-- generated:end layout-gantt -->\n\n## Plan layout\n\nThe layout that places a List\'s rows on a plan of the places they stand at: a `layout` object stating the data it reads.\n\n### Plan\n\n<!-- generated:start layout-doc-plan -->\n\n`{ "plan": { \u2026 } }` draws things that stand at a place \u2014 pallets in a warehouse \u2014 on a plan of the places. The places are\nthe rows of a table whose `records` states a `plan_place` (a bay, an open area or a landmark, each at its spot on a sheet\nof the plan); `at` names the one-link of the List\'s rows to a place and, for an item in a bay, the row (`across`) and the\ntier (`up`) it stands in, counted from 1. A bay is drawn as its rows and tiers, an area with a count, a landmark as a\nlabelled frame; the reader sees a plan, one bay enlarged, and the same plan in 3D. The List may read other tables as\n`sources`: one plan of every table\'s items. Each item carries `__reach` \u2014 how many items stand in the way of taking it out\n(those above it where the place is `stacked`, and those in the rows between it and the side `reach_from` says the bay is\ntaken from) \u2014 and `__floating` and `__crowded` (yes/no: nothing under it in a place that stacks; two in one cell) \u2014 so the list, its export and an agent\'s read all carry them; `<table>_plan_load` counts the rows each place\nholds. A move through the app is refused unless it clears the place, row and tier all three, or places the item at\na free cell of a bay \u2014 resting on a present item where the place is `stacked`, and no larger across or along than the bay\'s cell where the plan and the place both state a size \u2014 or at an area. Every other write (a grid edit, an import, a tool) holds one item to a cell only where the item\'s table states `unique: [<at>, <across>, <up>]`; a plan over a table stating none is noted. A plan opens on every row\nits `where` keeps, with no stage chip narrowing it. Rows with no place wait in a tray beside the plan. An Act that asks exactly a place (a link to the plan\'s places) and two numbers (the row and the tier) is answered by a pick on the plan, never by a form. On a desk a press opens a row\'s record in the panel beside the plan.\n\n<!-- generated:end layout-doc-plan -->\n\n```jsonc\n// table "bay"\n"title": "code",\n"records": { "plan_place": { "kind": "kind", "x": "x", "y": "y", "across": "rows", "up": "tiers", "reach_from": "taken_from", "stacked": "is_stack" } }\n```\n\n```json\n{ "type": "List", "entity": "pallet", "filters": ["line"], "layout": { "plan": { "at": "bay", "across": "row", "up": "tier" } } }\n```\n\n```jsonc\n// table "pallet": one item to a cell on every write, not only through the app\n"unique": [["bay", "row", "tier"]]\n```\n\n<!-- generated:start layout-plan -->\n\n#### Plan keys\n\n| Key | Type | Meaning |\n|---|---|---|\n| `at` | alias, required | A one-link of this entity to an entity whose `records` states a `plan_place`: where each row stands |\n| `across` | alias, required | A number field: the row of a bay a row stands in, counted from 1; empty at an area |\n| `up` | alias, required | A number field: the tier of a bay a row stands at, counted from 1 at the ground; empty at an area |\n| `fill` | alias | A single select the items are coloured by; absent, the first single select among the register\'s filters |\n| `mark` | [Plan mark](#plan-mark) | A row holding the option says the option\'s label on its box and is hatched in the option\'s own colour, and the legend names it by the label; over `sources`, the select is matched by option alias, and a source lacking the select never marks its rows |\n| `size` | [Plan size](#plan-size) | Each row\'s box as it stands in the world, in the one length unit its places\' `size` states: the option the row holds of the select names its box\'s width across, depth along and height; over `sources`, matched by option alias, as `mark` is; a row holding an option it does not name is drawn at its place\'s cell |\n\n#### Plan mark\n\n| Key | Type | Meaning |\n|---|---|---|\n| `field` | alias, required | A single select of this entity, or a lookup of one through a one-row link |\n| `option` | alias, required | An option alias of that select |\n\n#### Plan size\n\n| Key | Type | Meaning |\n|---|---|---|\n| `field` | alias, required | A single select of this entity, or a lookup of one through a one-row link |\n| `options` | map of alias \u2192 [Plan size box](#plan-size-box), required | The box of each option alias of that select |\n\n#### Plan size box\n\n| Key | Type | Meaning |\n|---|---|---|\n| `across` | number, required | The box\'s width across the bay\'s rows |\n| `along` | number, required | The box\'s depth along them |\n| `up` | number, required | The box\'s height |\n\n#### Plan place\n\n| Key | Type | Meaning |\n|---|---|---|\n| `kind` | alias, required | A single select, options aliased `bay` and, where the places have them, `area` and `landmark`: a bay holds rows and tiers, an area neither, a landmark nothing |\n| `sheet` | alias | The plan sheet it is on: a single select, or a one-row link to an entity whose `records` states its `image` \u2014 the sheet\'s drawing, which the places are drawn over (with `scale`) |\n| `scale` | alias | A number field of the sheet entity `sheet` links to: how many cells wide its drawing is, the plan\'s scale. Required where that entity states an `image`, and only then |\n| `x` | alias, required | A number field: left edge, in cells |\n| `y` | alias, required | A number field: top edge, in cells |\n| `width` | alias | A number field: an area\'s frame width, in cells |\n| `depth` | alias | A number field: an area\'s frame depth, in cells |\n| `across` | alias, required | A number field: a bay\'s rows |\n| `up` | alias, required | A number field: a bay\'s most tiers |\n| `reach_from` | alias | A single select, options aliased exactly `first`, `last`, `both`: the side boxes leave a bay from; a bay that names none has no reach and no arrow |\n| `stacked` | alias | A boolean field: true where items at this place rest on the one below (a stack), so a tier above the first needs a present item under it, shows floating without one, and an item\'s reach counts the items above it; false or empty, items sit at any tier and only the rows between a bay\'s reach side and the item are in the way |\n| `size` | [Plan place size](#plan-place-size) | The real size of ONE cell of the place, for 3D: three number fields stating one length `unit` alike. Absent, a cell is drawn at the size most of the sheet\'s places state, a unit cube where none states one |\n\n#### Plan place size\n\n| Key | Type | Meaning |\n|---|---|---|\n| `across` | alias, required | A number field: the width of one cell across the rows |\n| `along` | alias, required | A number field: the depth of one cell along the place |\n| `up` | alias, required | A number field: the height of one cell, one level |\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `list.plan` | `layout: { plan }`: `at` is a one-row link to an entity whose `records` states a `plan_place`, `across` and `up` two different numbers of the row, `fill` a single select; a plan List has no Tabs, `group` or `attention`. A write that sets `at`, `across` or `up` is refused unless it clears all three, or places the row at a free cell of a bay (a row from 1 to the bay\'s `across`, a tier from 1 to its `up`, resting on a present item), or at an area with neither. |\n| `list.plan-unique` | *Noted, never refused:* A plan\'s items (the List\'s table and each source) state `unique` on their place link, `across` and `up`: the app\'s moves refuse a taken cell, and the unique makes every other write hold it \u2014 the note names a table that states none. |\n| `list.plan-mark` | A plan\'s `mark` names a single select of the row, or a lookup of one through a one-row link, and an option of it by alias: a row holding that option is hatched on its box in the option\'s colour. A source that holds the select must hold it as a single select with that option; a source lacking it never marks its rows (`list.source-lacks`). |\n| `list.plan-size` | A plan\'s `size` names a single select of the row, or a lookup of one through a one-row link, and, by option alias, the box (`across`, `along`, `up` \u2014 positive, in the one length unit the places\' `size` states) of each option: a row holding one is drawn as that box. A source that holds the select must hold it as a single select; a source lacking it draws its rows at their places\' cells (`list.source-lacks`). |\n| `list.plan-box-size` | *Noted, never refused:* A plan whose places state a `size` and whose rows\' select options are ISO 6346 container size-type codes (`20DC`, `40HC`) states the box of each in `size`, from the ISO 668 dimensions, else every box is drawn at its place\'s cell. |\n\n<!-- generated:end layout-plan -->\n\n## Publish desk\n\nRows that are each a place the record is sent \u2014 a notice\'s boards, a listing\'s portals \u2014 are a record\'s child List with\n`expect` on the child\'s one-row link to the catalog of those places and `layout: { "desk": \u2026 }`:\n\n```json\n{\n "type": "List",\n "entity": "posting",\n "expect": "board",\n "columns": ["posted_link", "refusal"],\n "layout": { "desk": { "bodies": ["wording", "wording_abroad"], "text": "goes_out_as", "media": "pictures", "link": "page", "group": "reach", "network": "kind", "networks": { "company_page": "linkedin" } } }\n}\n```\n\nThe desk is where the post is written. `bodies` are the record\'s plain text fields it is written in (one per language,\nsay), each its editor between the list and the preview, saved as any field of the record is and drawn nowhere else on it.\nThe preview is `text` read over what is on screen: where `text` is a formula of the child, the desk computes that same\nformula over what is typed, so the post moves as it is written, and a place not ticked previews the words its row would\nhold. For that the formula reads only what a screen holds whole: stored values of its row, the record through lookups over\nthe link back to it, the place through lookups over `expect`, and formulas of the row over those \u2014 a rollup, a lookup\nthrough another link or the clock is refused, naming the field.\n\nEvery place the link admits is a line with a tick and that place\'s face: its picture, else the mark of the network it is on\nwhere `networks` names one. `group`, another single select of the place, stands the lines under its options in their\norder: a kind holding a ticked line is open, one holding none folded to its heading and its count. A tick makes the line\'s\nrow from its key alone \u2014 so nothing else the child requires is left without a default \u2014 and an untick deletes it until the\nrow\'s stage is `closed`: what went out is not taken back. It asks first only where a person wrote on the row. One line is\nworked beside the list and read as the post that place\'s feed shows: `text` is the child\'s words for that place, `media`\nand `link` the record\'s, and `network` the place\'s single select whose options `networks` names to a feed; an option not\nnamed reads on a plain card. Under the bodies stand the List\'s `columns` a person writes of the line\'s row; under the post,\nthe press copying its words beside the Acts of the child, then what the line and the `columns` hold that nobody writes\nthere (the link it went out at, why it was refused). A value an Act or a workflow fills is stated as that Act\'s, so the\ndesk never offers it as an empty box. Sending is an ordinary Act of the record.\n\n<!-- generated:start layout-desk -->\n\n#### Desk keys\n\n| Key | Type | Meaning |\n|---|---|---|\n| `bodies` | list of alias (1\u20133) | The record\'s plain text fields the post is written in, in order \u2014 one per language, say \u2014 at most 3: each its editor on the desk, between the list and the preview, and drawn nowhere else on the record |\n| `text` | alias, required | A text of the block\'s rows \u2014 stored, or a formula yielding text \u2014 holding the words that go out on that row\'s destination. A formula is computed on the desk too, over what is typed: it reads stored values of its row, the record through lookups over the link back to it, the destination through lookups over `expect`, and formulas of the row over those \u2014 never a rollup, another link or the clock |\n| `media` | alias, required | A files field of the record: the pictures or the video the post carries |\n| `link` | alias | A text field of the record holding a link (`format: "link"`), carried as the post\'s card |\n| `network` | alias, required | A single select of the entity `expect` links to, saying which network each destination is on |\n| `group` | alias | Another single select of the entity `expect` links to \u2014 the destination\'s kind \u2014 the lines stand grouped by: each option a heading in the select\'s order, a group holding no ticked line folded to its heading and its count, destinations holding no option last |\n| `networks` | map of alias \u2192 `"facebook"` \\| `"instagram"` \\| `"threads"` \\| `"x"` \\| `"linkedin"`, required | That select\'s options, each by its alias, to the network whose feed the post is previewed in \u2014 facebook, instagram, threads, x, linkedin. An option not named has no feed to imitate: its words read as a plain card |\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `list.post` | A child List with `layout: { desk }` needs `expect` on a one-row link \u2014 never a select, nor with `under`, `pick`, a checklist layout, `compare` or a `create` list, its line made by a tick from its key alone: its `bodies` are plain text fields of the record a person writes, drawn nowhere else on it; its `text` is a text of the child, stored or a formula yielding text \u2014 a formula reading only stored values of its row, lookups through the link back to the record or through `expect`, and formulas of the row over those, never the clock; its `media` a files field of the record and its `link` a text field of the record; its `network` a single select of the entity the link names, and `networks` holds options of that select, by alias, each to one of facebook, instagram, threads, x, linkedin; its `group` is another single select of that entity. |\n\n<!-- generated:end layout-desk -->\n\n## Record node\n\nA Record draws what a row opens: the head, then the parts.\n\n- **The head:** title, subtitle, picture, mark, party, figure and meter, deadlines, description \u2014 the\n table\'s `records` facts, overridden by the Record\'s `row`. `row` changes how the App\'s rows read wherever it lists them, and has nothing to do with arranging a page. The status stands in the head, or the Side where the Side states it, never in a Section.\n- **Where it stands:** a Record stands only in the App\'s `pages`, one per entity, stating its `entity`; every List over\n the entity opens it. With no page for an entity, the platform designs the record\'s Sections from the rows: the fields\n the head does not draw, child Lists, papers and Acts. A stated page stands exactly as written, so it replaces them.\n Under a child List, an absent page is every field of the child except the link back.\n- **Children:** either parts \u2014 `Section`, `Side`, and one `Steps` holding the Sections that are the record\'s path \u2014 or, for a one-part record, `Field`, `List`, `Reading`,\n `Statement`, `Comments` and `Act` directly. The two are never mixed. The page of an entity no root List and no Sheet\'s List (one stating no `app`) is over \u2014 a\n child List\'s, a document\'s or a roster cell\'s \u2014 holds `edit`, Fields, Sections of them with the Acts and the Lists of\n their rows\' own children, and the Lists of its rows\' own children; a row opened in place draws each Section under its\n title, an Act no Section holds at the last Section\'s foot, and a page with no Section its one section. Such a page\n holds what any page holds \u2014 a Reading, a Side \u2014 and one stating a Side opens its rows\n by its `door` instead of in place; any other `door` there is not drawn and stays stated.\n\n<!-- generated:start node-record -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `entity` | alias, required | The table whose rows open on this page: a page stands once per entity, in the App\'s `pages`, and every List over the entity opens it |\n| `row` | [Record row](#record-row) | How the App reads this entity\'s rows wherever it lists them \u2014 their line, figure, picture, deadlines and stage \u2014 where it differs from the table\'s `records` |\n| `add` | `false` \\| list of alias (at least one) | What a new row asks where a picker of this entity offers one, anywhere in the App: these fields; `false`: a picker only picks. Absent, the table\'s required fields, its natural key and its title, where the table states a `singular` |\n| `remove` | `true` | Lets a person delete a row reached through a link: true, it offers a Delete; rows a List lists are deleted as that List\'s `remove` says |\n| `door` | `"page"` \\| `"drawer"` | How a row opens, on a page or in a drawer: absent, a page where a part is a step or a Side or there are more than 3 parts, else a drawer |\n| `edit` | `false` | Shows a record nobody changes here: false, nothing it draws is written, a link\'s row of it included |\n| `children` | list of ([List over a Query in a Record](#list-over-a-query-in-a-record) \\| alias \\| [Field](#field-node) \\| [Fieldset](#fieldset-node) \\| [Section](#section-node) \\| [Steps](#steps-node) \\| [Side](#side-node) \\| [Outside](#outside-node) \\| [List](#list-node) \\| [Reading](#reading-node) \\| [Statement](#statement-node) \\| [Comments](#comments-node) \\| [Act](#act-node) \\| [Check](#check-node)) (at least one) | Parts (Section, Side, and one Steps holding the Sections that are its path), or for a one-part record its Fields, Fieldsets, Lists, Readings, Statements and Comments directly \u2014 never both. Beside either stand Outsides, Checks (guarding this entity\'s Acts and saves) and Acts on one row, each placed at the foot of the part whose step it moves into, a correction in the head\'s \u22EF. Holding only Acts, Checks and Outsides, or absent, the record\'s Sections are the platform\'s: the fields the head does not draw, child Lists, papers and Acts. Otherwise it stands exactly as written |\n\n#### Record row\n\n| Key | Type | Meaning |\n|---|---|---|\n| `title` | [Record row title](#record-row-title) | The row\'s title field, stated for its `edit` alone |\n| `subtitle` | list of (alias \\| [Record row line field](#record-row-line-field)) (1\u20132) | Up to two fields read under the title, in place of the table\'s |\n| `figure` | alias \\| [Record row line field](#record-row-line-field) \\| `false` | The one number a row stands for, in place of the table\'s; false, none. `{ field, edit: false }` reads it without writing it |\n| `image` | alias \\| [Record row line field](#record-row-line-field) \\| `false` | A files field, or a one-row link to a table with a picture, that pictures a row, in place of the table\'s; false, none. `{ field, edit: false }` reads it without writing it |\n| `due` | list of alias (at least one) \\| `false` | Dates that count down, in place of the table\'s; false, none |\n| `status` | `false` \\| `{ "edit": true \\| false }` | Whether this app shows and moves the stage: false, it is not shown. `{ edit: true }`: the stage is also moved by hand. `{ edit: false }`: nobody moves it in this app, another app does. Absent, the stage stands in the record\'s head, or in the Side where the Side states it: choosing a move runs its Act, asking and refusing as its button does |\n\n#### Record row title\n\n| Key | Type | Meaning |\n|---|---|---|\n| `edit` | `false` | Keeps a row\'s name as it stands: false, the title is read; absent, it is written where the table lets a person write it |\n\n#### Record row line field\n\n| Key | Type | Meaning |\n|---|---|---|\n| `field` | alias, required | The field\'s alias |\n| `edit` | boolean | Shows a value nobody changes here: false, the field is drawn and read; absent or true, it is written where the table and the part holding it let a person write it. A field an Act\'s body writes is the Act\'s, read-only elsewhere and drawn once filled, unless the Field states `edit: true`, which keeps it a person\'s to edit |\n\n<!-- generated:end node-record -->\n\nThe door is a page where a part is a step or a Side, or where there are more than 3 parts; else a drawer. `door`\nis a judged choice of how a job is worked (one after another over a long record), so it is kept. A Section is one area of the record\'s data a person comes to for its own job, like the tabs of a settings page (a company\'s General,\nMembers, Billing): the related lists and field groups of that area sit inside it under their headings. A status\'s stages are not areas:\ntheir acts stand at the foot of the rows they move. From three parts on, the\nrecord shows one at a time: a press on a page\'s rail (a strip of the same names on a phone and in a drawer) flips to a part and returns\nto the top. It opens on the part the address names, else the step that is now, else the first. A part\'s rows and drafts are kept\nacross flips. With fewer parts they stack.\n\nA record shows no activity and no audit log: a history an app shows is table-backed \u2014 `records.status.dates`, `records.status.history`, an event table an act\nmakes \u2014 stated where the app shows it.\n\nA field may be stated in any number of parts, and each part draws what it states. Where parts stack it stands once: in the\nstep that is now if that step states it, else the first part stating it. A Section or a List with `when` is\ndrawn only while each named select of the record holds one of its options.\n\n## Section node\n\nA titled part of a record. A Section draws its plain Fields first, then its\nLists, Readings, Statements and Comments in the order stated; its Acts stand at its foot.\n\n<!-- generated:start node-section -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `key` | alias | Unique among its siblings; part of the node\'s address. Absent, the title\'s words as a slug, written once and kept |\n| `title` | text | The part\'s heading. Absent, the part draws none where it is the record\'s only part; beside others it is named by what the record is. A step states it |\n| `description` | text | A line under the heading |\n| `when` | [condition](#app-tree) | Drawn only while this holds |\n| `edit` | `false` | Shows a part nobody changes here: false, nothing in it is written |\n| `at` | list of alias (at least one) | The status options this part is the work of; a step is stated as a Section inside `Steps` (`reference/steps-node`) |\n| `children` | list of ([List over a Query in a Record](#list-over-a-query-in-a-record) \\| alias \\| [Field](#field-node) \\| [Fieldset](#fieldset-node) \\| [List](#list-node) \\| [Reading](#reading-node) \\| [Statement](#statement-node) \\| [Comments](#comments-node) \\| [Act](#act-node) \\| [Check](#check-node)) (at least one) | What the part draws, in reading order; its Acts stand at its foot. A Fieldset holds Fields under a heading of their own. A Check stated here guards the entity as one beside the parts does |\n\n<!-- generated:end node-section -->\n\n#### Kinds of block\n\nWhat a Section draws beside its Fields is a block, of the kind its item states: a List a rows block, an outline where its table holds rows under rows, an agenda or a timeline by its layout, or a list that only reads; a Field a gallery of files or a prose block; a Statement, Comments and a Reading each its own.\n\n<!-- generated:start block-kinds -->\n\n| Kind | What it is |\n|---|---|\n| `rows` | Rows list a record\'s child rows under it, each a line in the register\'s row anatomy: a List standing in a Section, its rows linked to the record, narrowed by its `where`, opened in place, their Acts in each row\'s \u22EF; rows that hold pictures are cards, each led by its picture. A child List draws as rows unless its layout says otherwise; `cards` draws them as the register\'s card grid and `table` always as a table, whatever they hold; a `checklist` reads the rows as checks, a `desk` as the places the record is sent and a `gantt` as bars on an axis of time (the register\'s, over the rows the record\'s link names). |\n| `outline` | An outline draws a record\'s child rows as a tree where their table holds rows under rows (a task under a task, a part of a part): the top rows first, each row\'s sub-rows read when it is opened, with the count of them, closed of all, beside its name; a row adds a row under itself from its \u22EF. A List the reader narrows, orders by a header, groups or searches draws as plain rows. |\n| `agenda` | An agenda reads a record\'s child rows as planned entries on a time axis: by day, soonest first, each with its picture and the day that is today marked. The day is the first date on the child\'s row line; within a day entries follow a datetime there, else the first single select after the date. An entry with no day yet is a plan, listed first and dated in place. `start` is the record\'s date that is the first day: each day\'s heading counts from it (Day 1, Day 2). |\n| `timeline` | A timeline reads a record\'s child rows as a log of dated entries, newest first, with a composer where the app adds entries, each corrected and removed where it stands. It is never the record\'s status history: the rail shows each move. A timeline\'s moment is its child\'s first date, and who its member field. |\n| `files` | Files draw a run of the record\'s files fields as one gallery under a heading, each field\'s files as thumbnails with a drop zone to add to them. A files field, or a lookup of one, draws as a gallery unless its Field states `block: false`. |\n| `text` | Text draws one of the record\'s markdown fields as prose under a heading, edited in place where the app writes it. A markdown field draws as prose unless its Field states `block: false`; plain text is a control among the part\'s fields unless it states `block: true`. |\n| `choices` | Choices draws one of the record\'s multi-selects as a checklist under a heading: every option on a line of its own, ticked where the record holds it, ticked and unticked in place where the app writes it. A multi-select is a control among the part\'s fields unless its Field states `block: true`. |\n| `linked` | Linked draws the row a link of the record to one row names, whole and in place, as its page draws it \u2014 its fields, parts, Lists and Acts, read and written as that row\'s own \u2014 under a heading. A link draws as its row\'s chip unless its Field states `block: true`. |\n| `figures` | Figures draw numbers of the record (1 to 8) as tiles, each under its field\'s label. A tile holding nothing reads as not measured, never 0. |\n| `statement` | A statement builds one figure from figures of the record: each line a number of it with its operator and its label, the figures on one right edge, the last an `equals` drawn heaviest (a claim\'s payable, an invoice\'s total, a payslip\'s net). A line may carry the rows its figure adds up (`parts`), each listed under it. |\n| `comments` | Comments draws the record\'s comment thread: the platform\'s built-in comments, the same thread the table\'s record panel and a custom-code app show, with a box to write one. Reach for it where people discuss the record (a Section or the Side of a Record; once per Record). Members only: a viewer outside the workspace sees none. It reads the record\'s own thread, so a Record over a query has none to show. |\n| `reading` | A reading block draws a Reading over the child rows under the record, through their link to it: a number, a split into parts, a trend, a grid, a shortfall against stock, or the work against its plan. It stands in the record\'s strip beside the record\'s own figures. |\n| `list` | A list shows rows of another entity beside the record, read only: those linked to it, a path through a row of their own, or \u2014 with `same` \u2014 the siblings sharing a link of the record, the record itself left out. Each row reads in its `records` anatomy with the `columns` after its title, and opens on its page. |\n| `funnel` | A funnel counts steps people drop out of between, a column of each child row a step (2 to 8): one funnel over the rows under the record \u2014 each step its column summed, its bar over the first step, the share kept between two steps and from the first to the last. |\n\n<!-- generated:end block-kinds -->\n\n- **`at`** names the stage options during which the section is the work now. A step\'s `at` is stated on a Section inside `Steps`\n (`reference/steps-node`), which is where a stage\'s content stands. A step never hides a\n field, locks it or gates an act: fields stay writable as the write rules and checks allow, at any stage.\n- **Acts:** every Act on a record stands in the Section whose work it is. An Act moving the stage and offered at ONE step\n stands at that step\'s foot when it moves the work forward, to an exit later in the stage\'s options, or back to a step the\n work passes; one offered at several steps, or moving back into a step the work never passes, stands in the Section it\n enters, as its way in. One stated elsewhere stands there, and the answer says so. A correction (`danger`, and not one of\n its step\'s outcomes) waits in the Section heading\'s \u22EF.\n- **An exit** stands only once the record is in it, its reason there and its step apart from the path; until then the\n Act waits in the header\'s \u22EF.\n- **A document:** a Section that is no step and holds nothing but one `text` block over a markdown field reads as a document: the field is written in place with no box, saved when the writer leaves it, and the record reads in an article column while that part is in view.\n- **Writes:** its Fields and its Acts.\n\n## Steps node\n\nA record\'s path down the page. Steps holds the Sections that are the record\'s steps, in the order they stand: a stage that holds something of its own \u2014 fields, blocks, acts or a note \u2014 is a Section stating `at`, the status options during which it is the work now. The Sections stand where the Steps node stands among the record\'s parts.\n\n<!-- generated:start node-steps -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `children` | list of [Step](#step) (at least one), required | The record\'s steps in the order they stand, each a Section stating `at`: what it holds is drawn under its step, and the step stands as the work now while the status is one of its `at` |\n\n#### Step\n\n| Key | Type | Meaning |\n|---|---|---|\n| `type` | `"Section"`, required | Always `Section` |\n| `key` | alias | Unique among its siblings; part of the node\'s address. Absent, the title\'s words as a slug, written once and kept |\n| `title` | text | The step\'s heading. Absent where `at` names one option, the option\'s name; a step naming several options states it |\n| `description` | text | A line under the heading |\n| `when` | [condition](#app-tree) | Drawn only while this holds |\n| `edit` | `false` | Shows a part nobody changes here: false, nothing in it is written |\n| `at` | list of alias (at least one), required | Options of the record\'s status during which this step is the work now |\n| `children` | list of ([List over a Query in a Record](#list-over-a-query-in-a-record) \\| alias \\| [Field](#field-node) \\| [Fieldset](#fieldset-node) \\| [List](#list-node) \\| [Reading](#reading-node) \\| [Statement](#statement-node) \\| [Comments](#comments-node) \\| [Act](#act-node) \\| [Check](#check-node)) (at least one) | What the part draws, in reading order; its Acts stand at its foot. A Fieldset holds Fields under a heading of their own. A Check stated here guards the entity as one beside the parts does |\n\n<!-- generated:end node-steps -->\n\n- **Where:** a direct child of a Record, at most one, with every Section that states `at`; a Section, Side or Outside holds none. It states no `key`: its address is `steps`, and a Section inside it is `pages/<entity>/steps/<key>` or its key alone, which the page shares with the record\'s other parts.\n- **A step\'s title** is the name of its option where `at` names one and it states none; a step naming several options states its title.\n- **Over a status that closes an option** (`records.status.closed`). A status that closes none is a condition a person sets, and has no path; the record draws its select alone.\n- Two Sections may name one option, and their options may overlap. A status option no Section names is a step of its own, holding nothing.\n\n## Side node\n\nThe one part drawn beside the rest \u2014 the photos looked at, the pool picked from, the facts kept in view. It stands on the\nright, beside the rail and the parts; on a phone it is one pinned line that opens in place. At most one Side to a record, on a page\ndoor.\n\n<!-- generated:start node-side -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `key` | alias | Unique among its siblings; part of the node\'s address. Absent, the title\'s words as a slug, written once and kept |\n| `title` | text, required | The part\'s heading |\n| `description` | text | A line under the heading |\n| `when` | [condition](#app-tree) | Drawn only while this holds |\n| `edit` | `false` | Shows a part nobody changes here: false, nothing in it is written |\n| `children` | list of ([List over a Query in a Record](#list-over-a-query-in-a-record) \\| alias \\| [Field](#field-node) \\| [Fieldset](#fieldset-node) \\| [List](#list-node) \\| [Reading](#reading-node) \\| [Statement](#statement-node) \\| [Comments](#comments-node) \\| [Act](#act-node) \\| [Check](#check-node)) (at least one) | What the part draws, in reading order; its Acts stand at its foot. A Fieldset holds Fields under a heading of their own. A Check stated here guards the entity as one beside the parts does |\n\n<!-- generated:end node-side -->\n\nIt holds what a Section holds. A field it states, the status included, leaves the head and stays on list rows; the title stays in the head. Writes: its Fields and its Acts.\n\n## Outside node\n\nWhat one record shows, and which acts it allows, to a person with no seat who opens a link a member made of it. A member\npresses Create link on a record while its status stands in `at`; the link opens that one record until it expires, is\nrevoked, or its act moves the status out of `at`. The person sees the stated Fields and Lists and presses the stated Acts\nand nothing else. It stands directly in the Record of a table with a stored status select, whichever List over it opens the page.\n\n<!-- generated:start node-outside -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `key` | alias | Unique in the app: a link to the record names it. Absent, the title\'s words as a slug, written once and kept |\n| `title` | text, required | The heading of the page the person without a seat opens |\n| `description` | text | A line under the heading |\n| `at` | list of alias (at least one), required | Options of the record\'s status during which a link to it opens; none is owned by a stage, and each Act moves the status out of them |\n| `children` | list of (alias \\| [Field](#field-node) \\| [List](#list-node) \\| [Act](#act-node)) (at least one), required | Exactly what the link shows and allows: Fields read as values, Lists of child rows read as they are, and the Acts the person may press, each moving the status out of `at` |\n\n<!-- generated:end node-outside -->\n\n- **Fields** are read as values, in order; a lookup, a rollup or a formula is computed for the link only if stated here.\n A Field states nothing but its alias.\n- **Lists** read the child rows under the record as they are: `columns`, `label` and `where`.\n- **Acts** are the link\'s alone: no member, visitor or agent presses them. Each states `key`, `label`, `confirm`, `when`,\n `requires`, `asks`, `set`, `template` with `into`, or `sign`. `when` absent is the status held in `at`; `set` moves the\n status to an option outside `at`, so each press ends the visit. `asks` are text, numbers, dates or listed options. A\n `sign` is by a text field the signer types, with no witness: the link is the attestation.\n- `at` names options no stage owns, and no two Outsides of a table open during the same option.\n- **Writes:** its Acts, and nothing else.\n\n## Tab node\n\nA Tab is one view of a List\'s rows over a period: a register reporting a period \u2014 what stands at its end beside what came and went during it (the stock,\n the hires out, the tickets open) \u2014 reads its rows as Tabs over one `period` the reader picks above them. A Tab holds\n the rows `dated` within the period, those `open` at its end, or lists every row and draws what a child\'s rows came to\n in the period (`totals`). A Tab narrows its rows and holds no nodes; Readings stand beside it in the List and read the\n open Tab, or the one their `tab` names. Never date chips set by hand, and never a Tab per stage, which the chips split.\n Readings and Lists read apart from a List\'s rows stand on a Sheet, a View of the App\'s own.\n\n<!-- generated:start node-tab -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `key` | alias, required | Unique among its siblings; part of the node\'s address |\n| `label` | text, required | What the tab holds, in the reader\'s words |\n| `dated` | alias | A date: the tab holds the rows dated within the List\'s period |\n| `open` | [Tab open](#tab-open) | The tab holds the rows open at the period\'s end: begun, and not yet ended |\n| `totals` | [Tab totals](#tab-totals) | Each row\'s figures over a child\'s rows in the period |\n| `where` | [narrowing](#app-tree) | Only the rows whose select holds one of these options, whose yes/no is this value, or whose member field holds the reader (`{ "me": true }`) \u2014 every entry ANDed |\n| `sort` | [Sort key](#sort-key) \\| list of [Sort key](#sort-key) (at least one) | The order this tab\'s rows read in; absent, the List\'s |\n\n#### Tab open\n\n| Key | Type | Meaning |\n|---|---|---|\n| `from` | alias, required | The date a row begins on |\n| `to` | alias, required | The date a row ends on, empty while it is open |\n\n#### Tab totals\n\n| Key | Type | Meaning |\n|---|---|---|\n| `rows` | alias, required | An entity of this app whose rows each belong to one row of the register\'s entity: the rows the columns add |\n| `on` | alias, required | A date of the child placing each row in time: stored, a formula yielding a date, or a lookup of a date through a one-row link \u2014 never a moment or a span of days |\n| `columns` | list of [Totals column](#totals-column) (1\u20136), required | The figures drawn in place of the register\'s columns after each row\'s name, each under its own alias and label |\n\n#### Totals column\n\n| Key | Type | Meaning |\n|---|---|---|\n| `alias` | alias, required | The column\'s name: its address in the totals read |\n| `label` | text, required | What the column holds, in the reader\'s words |\n| `value` | alias \\| `{ "avg": alias }` | A number of the child (stored, a formula or a rollup) summed over the rows, or `{ avg }` averaged over the rows holding one, a window holding none drawing blank; absent, the rows are counted. A figure read in each row\'s own unit or currency stands only where the child\'s select is a lookup, through `via`, of a single select of the register\'s entity |\n| `where` | map of alias \u2192 (list of alias (at least one) \\| boolean) | Only the child\'s rows whose select holds one of these options, or whose yes/no is this value \u2014 every entry ANDed |\n| `window` | `"before"` \\| `"in"` \\| `"through"`, required | Which of the child\'s rows, by `on`, the column adds: `before` those dated before the period\'s first day, `in` those from its first day through its last, `through` those on or before its last day |\n\n#### Period days\n\n| Key | Type | Meaning |\n|---|---|---|\n| `days` | integer, required | How many days through today, at most 366 |\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `list.tabs` | A List\'s Tabs each have a `key` of their own, none the entity\'s alias or one a report template holds (`title`, `lines`, `readings`, `at`, `dates`, `period`, `per`); a Tab states one of `dated` and `open` (dates of its rows, `open`\'s two different) or `totals` (a child\'s rows windowed by the period); its `where` and `sort` hold as the List\'s do, and never narrow by the status, which its chips split. Only a table or cards List has Tabs, and a Reading\'s `tab` names one of them. A `period` opens a List on a window: over a table or cards a Tab that states `dated`, `open` or `totals` reads it; a calendar or a lanes board opens on `"today"`, `"week"` or `"month"` (a lanes board of hours, on `"today"` or `"week"`); no other layout draws one. Wrong: `period: "year"` over a table with no dated Tab. Right: a Tab stating `dated`, or no `period`. |\n| `list.tab-totals` | A Tab\'s `totals` name a child linked to the List\'s entity by a one-row link (a child linking the List\'s entity twice cannot be totalled), a date of the child, never a moment or a span, and 1 to 6 columns each under its own alias and label; a column\'s `value` is a number of the child, its `where` holds over the child\'s selects and yes/nos, and a value read in each row\'s own unit or currency stands only where that select of the child looks up, through its link, a single select of the List\'s entity, and the child links to no source\'s rows. A source\'s rows are totalled by the child\'s one link to them, by one field to one row; a source the child links to not at all totals nothing on its rows (`list.source-lacks`). Only a table List has them, and no Tab states `totals` beside `dated` or `open`. A column sums a number or counts rows, never `{ avg }`. |\n\n<!-- generated:end node-tab -->\n\nA `totals` Tab adds, per column, the child\'s rows `before` the period\'s first day, `in` the period, or `through` its last\nday, so `before` plus `in` of one value is its `through`:\n\n```json\n{\n "type": "Tab",\n "key": "items",\n "label": "Items",\n "totals": {\n "rows": "ledger_line",\n "on": "moved_on",\n "columns": [\n { "alias": "opening", "label": "Opening", "value": "quantity", "window": "before" },\n { "alias": "received", "label": "Received", "value": "quantity", "where": { "kind": ["receipt"] }, "window": "in" },\n { "alias": "issued", "label": "Issued", "value": "quantity", "where": { "kind": ["issue"] }, "window": "in" },\n { "alias": "closing", "label": "Closing", "value": "quantity", "window": "through" }\n ]\n }\n}\n```\n\n## Sheet node\n\nA Sheet is a grid of Readings and Lists over the App\'s rows in its `period`: each Reading a figure, each List the rows it lists. An App of one Sheet opens on it; an App of several draws a strip that picks one.\n\n<!-- generated:start node-sheet -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `key` | alias, required | Unique among the App\'s Views: the sheet\'s address, `/<key>` |\n| `label` | text, required | What the sheet holds, in the reader\'s words: its name among the App\'s Views |\n| `children` | list of ([Reading](#reading-node) \\| [List](#list-node)) (at least one), required | The Readings and Lists the sheet draws as a grid, in reading order: each Reading a figure over the App\'s rows in the App\'s `period`, each List the rows it lists |\n\n<!-- generated:end node-sheet -->\n\n## Field node\n\nA Field draws one field of the record it stands in. How it is drawn follows from the field\'s type and the table\'s facts:\n\n- a control or a value, with its notation, money, units and deadline countdown;\n- a files field as pictures and documents, a long or markdown text as prose written in place \u2014 a gallery or a prose block,\n with a heading (`label`) and a condition (`when`) of its own; a run of files Fields is one gallery;\n- a link as its row\'s chip, with a picker narrowed by `options_where`, offering a new row where the linked table\'s page\n states `add`;\n- the back side of a child\'s link as the rows filed under the record;\n- the fields an Act\'s `sign` writes as one signature.\n\n<!-- generated:start node-field -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `field` | alias, required | The field\'s alias |\n| `edit` | boolean | Shows a value nobody changes here: false, the field is drawn and read; absent or true, it is written where the table and the part holding it let a person write it. A field an Act\'s body writes is the Act\'s, read-only elsewhere and drawn once filled, unless the Field states `edit: true`, which keeps it a person\'s to edit |\n| `label` | text | The heading of the field\'s gallery or prose block, where it draws as one; absent, the field\'s label. A run of files fields takes the first one\'s |\n| `block` | boolean | Gives a field room of its own: true, a files, text or multi-select field draws as its own gallery, prose or checklist block, and a link to one row as that row drawn whole in place, as its page draws it; false: as a control among the part\'s fields. Absent, files and markdown fields draw as blocks, plain text, a multi-select and a link as a control |\n| `when` | [condition](#app-tree) | A gallery or prose block is shown only while the record\'s selects hold these options, its yes/nos these values, its numbers and dates meet their bounds and its `{ "empty": true \\| false }` fields are blank or filled |\n\n<!-- generated:end node-field -->\n\nA field drawn in the head (title, subtitle, picture, figure, stage) is never also a Field node. A Field is drawn once per\npage. **Writes:** the field, under `reference/app-tree`; a picker\'s add is the linked table\'s page\'s `add`.\n\n## Fieldset node\n\nA Fieldset heads a run of a part\'s Fields with a few words of its own: the facts of one kind among a part\'s many (a\nvehicle\'s plate, make and seats under "Vehicle"). It stands among a Section\'s or Side\'s children, or a one-part\nRecord\'s, and holds two or more Fields, each drawn as a control, each in one Fieldset. A Field in it reads and is\nwritten as it would be in the part. A gallery or prose Field stands beside it, never in it.\n\nWhere the arrangement itself is the need, it holds [Lines](#line-node) in place of Fields: each a line of cells stated\nleft to right. With `heads` its Lines read as the rows of a table under those headings. A Fieldset holds Fields or\nLines, never both, and its Lines hold at least one Field between them.\n\n<!-- generated:start node-fieldset -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `key` | alias | Unique among its siblings; part of the node\'s address. Absent, the label\'s words as a slug, written once and kept |\n| `label` | text, required | The heading over the facts it holds, in the reader\'s words |\n| `heads` | list of text (1\u20137) | One heading per column of its Lines \u2014 a line\'s label in the first, then its Fields and Values; the Fieldset then reads as a table, each Line a row whose one Act, stated last, is the row\'s action under no heading. A head may be empty |\n| `children` | list of (alias \\| [Field](#field-node) \\| [Act](#act-node) \\| [Line](#line-node)), required | Fields drawn under the label, in the order stated, each reading as it would in the part, or Lines of cells; the Acts it holds stand at its foot, taking every prop an Act in a part takes |\n\n<!-- generated:end node-fieldset -->\n\n## Line node\n\nA Line is one line of a Fieldset: up to six cells after its own optional `label`. A cell is a Field, an Act drawn in\nits cell (what it asks opens in its dialog), or a [Value](#value-node). A Field in a Line stays in its cell: an Act of\nthe part that asks it asks in its dialog too.\n\n- Without `heads` on its Fieldset, a Line of up to three cells stands on one line on a record\'s page and in the\n drawer a list opens it in; a longer Line stands two cells to a line, and a narrower screen two to a line, then one.\n A Field and a Value read under their own labels.\n- With `heads`, the Line is a row of a table: its `label` names the row under the first heading, each Field and Value\n stands under the next, and its one Act, stated last, is the row\'s action. Every Line of the Fieldset states a `label`\n or none does.\n\n```json\n{ "type": "Fieldset", "label": "Count", "children": [\n { "type": "Line", "children": [{ "field": "on_book", "edit": false }, "counted",\n { "type": "Value", "label": "Difference", "formula": "{counted} - {on_book}" }] } ] }\n```\n\n<!-- generated:start node-line -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `key` | alias | Unique among its siblings; part of the node\'s address. Absent, the label\'s words as a slug, written once and kept |\n| `label` | text | The words the line stands after, and its row header under `heads` |\n| `children` | list of (alias \\| [Field](#field-node) \\| [Act](#act-node) \\| [Value](#value-node)) (1\u20136), required | The cells, left to right, at most 6: a Field as it reads in a Fieldset, an Act drawn in its cell, or a Value |\n\n<!-- generated:end node-line -->\n\n## Value node\n\nA Value is a figure the screen works out from fields of the record and stores nowhere. A figure a List, a report or an\nExport reads is a formula field of the table (`set_tables`); a Value is for one a single screen shows. It follows a\nfield when that field is saved.\n\nIts `formula` reads `{alias}` fields of the record that hold text, a number, a date, a yes/no or one option \u2014 or a\ncomputed field yielding one \u2014 and names an option as `{field:option}`. It is refused where it reads the clock, a field\nof another kind, or a lookup through a link of several rows.\n\n<!-- generated:start node-value -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `key` | alias | Unique among its siblings; part of the node\'s address. Absent, the label\'s words as a slug, written once and kept |\n| `label` | text, required | What the figure is called, in the reader\'s words |\n| `formula` | text, required | The formula language over `{alias}` of the record\'s fields: text, numbers, dates, yes/no and single selects, or the result of a computed field of those; a function that reads the clock is refused |\n| `notation` | [notation](#number) | How a number figure reads: decimal, currency or a unit; only where the formula yields a number |\n\n<!-- generated:end node-value -->\n\n## Act node\n\nAn Act is a verb, stated whole where it stands. Its place decides what it works on:\n\n- in a Section or Side, or in a one-part Record: one record, at that part\'s foot;\n- in a List, with `on`: the ticked rows or every row in view, each checked before any is written;\n- directly in a Record that holds parts: refused.\n\n<!-- generated:start node-act -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `key` | alias, required | The act\'s name; its workflow is `act_<key>`, or the `workflow` it names |\n| `label` | text, required | The verb, as the reader says it |\n| `when` | [condition](#app-tree) | The act works only while this holds |\n| `requires` | list of alias (at least one) | Fields filled first, each drawn where the act stands |\n| `recommends` | list of alias (at least one) | Fields it runs without and reads when filled |\n| `asks` | list of (alias \\| `{ "field": alias, "starts": "today" \\| "me" }` \\| [Asked input](#asked-input)) (at least one) | What the reader states on pressing: fields of the row (written by the act) or inputs; a `link` input\'s picker adds as its entity\'s page `add` says |\n| `set` | map of alias \u2192 [value](#app-tree) | What the act writes; each field is read-only elsewhere in the app. With `over`, fields of the List\'s entity |\n| `over` | [Rows written](#rows-written) | The act writes the rows of a List of the record instead of the record: `set` states fields of that List\'s entity, a status moved as each row\'s own move; rows the presser cannot read are left out, and the press is refused while any row it writes is refused or it reaches more rows than one write takes |\n| `owner` | `"field"` \\| `"link.field"` \\| `{ "group": id }` | Who presses it: a member field of the row, `link.field` read through a one-row link, or `{ group }` by id. Absent, the owner of the stage it is offered at, or anyone the app is shared with where it stands at none |\n| `workflow` | alias | The workflow it runs for what `set` cannot say: one made under this name, its body set by `set_workflow`, or the app\'s Workflow node, taking the row as `record_id`; the act\'s guards head its body and hold the row it is pressed on; a row the body writes beyond it is the body\'s to check |\n| `template` | alias | A document template it makes a file from: html a PDF, excel a workbook, word a .docx; over several rows, one file of them all, an html paper hands each row its own lists under the names the record\'s paper uses |\n| `templates` | list of [Act template](#act-template) (at least 2) | Several papers made into `into`, instead of `template`: the reader ticks which |\n| `into` | alias | The record\'s files field keeping the document; remade, it replaces its own last paper, never a person\'s file |\n| `paper` | text | Its paper, `<child>.<kind>`: the line of the record\'s papers it stands on |\n| `intake` | alias | A child the record lists whose rows are its papers: the press takes papers, an agent reads them, each filed as a row of it. With `on: "view"`, they make a new record of the List\'s entity, and the save opens it |\n| `fills` | list of text (at least one) | With `intake`, what the papers may fill: a field of the record, `<link>.<field>` on the row a required one-row link names, or a child they add rows to; on a new record that row is found on its entity\'s `natural_key` or added. With `record`, fields of the new row an agent fills from the transcript |\n| `record` | [Recording](#recording) | The press records a call, visit or meeting, filed as a new row of a child the record lists |\n| `sign` | [Signature](#signature) | The press opens a pad; the act keeps the signature as a picture with who signed, when and the witness |\n| `review` | `true` | Lets a person approve what a workflow would write: with `workflow`, it only proposes a changeset of the act\'s table, and the reader ticks the rows to write |\n| `makes` | alias | The rows a record\'s `cadence` still owes of this child: the press lists them, each with what would stop it, and writes the ones ticked. Pressed again it lists only what is missing |\n| `confirm` | `true` \\| `"warnings"` \\| text | The press asks first: the question, or `true` for the act\'s label over the row; `"warnings"` asks only while a row it acts on holds a standing warning (an issue its entity declares in `records.issues`), listing it, and runs at once otherwise |\n| `danger` | `true` | The act destroys or cannot be undone |\n| `on` | `"ticked"` \\| `"view"` \\| `"none"` \\| `"period"` | Which rows an Act over a List works on: `ticked`, those ticked in the List holding it; `view`, every row in view; `none`, in a root List of a table: no row, the Act is handed only what it asks and stands at the List\'s title whatever rows are in view; `period`, in a root List drawn over days: no row, the Act is handed the first and last day of the period the List\'s window stands on (its day, week or month) as its workflow\'s inputs `from` and `to`, beside what it asks. Every Act a List holds states it, and no other |\n\n#### Rows written\n\n| Key | Type | Meaning |\n|---|---|---|\n| `list` | alias, required | The key of a List the record\'s page draws: its rows under each record the act is pressed on, as that List reads them |\n| `when` | [condition](#app-tree) | Which of those rows are written: a row outside it is left as it is; each written row is checked as a save of it is |\n\n#### Asked input\n\n| Key | Type | Meaning |\n|---|---|---|\n| `input` | alias, required | A value the act asks for that is not a field of the record |\n| `label` | text, required | What the reader is asked, in their words |\n| `type` | `"text"` \\| `"long_text"` \\| `"number"` \\| `"date"` \\| `"select"` \\| `"link"` \\| `"member"` \\| `"file"`, required | What the reader states. A `file` is one uploaded file, handed to the act\'s authored `workflow` as its file id and read by nothing else |\n| `options` | list of [Select option](#select-option) (at least one) | The choices a `select` input offers, one picked \u2014 written into a select holding the same option aliases |\n| `entity` | alias | The entity a `link` input picks one row of |\n| `accepts` | list of `"sheet"` \\| `"pdf"` \\| `"document"` \\| `"photo"` (at least one) | The kinds of file a `file` input takes; absent, a sheet, a PDF or a document \u2014 a phone offers its camera only where `photo` is among them |\n| `required` | `true` | The act is refused without it |\n| `default` | alias | A field of the row whose value the input starts from, still changed at will |\n| `starts` | `"today"` \\| `"me"` | Where the input starts, still changed at will: `today` a date, `me` a member, the reader; never beside `default` |\n\n#### Set formula\n\n| Key | Type | Meaning |\n|---|---|---|\n| `formula` | text, required | A formula over the acted row\'s fields, `{alias}` each, read as the entity\'s own formulas read them |\n\n#### Act template\n\n| Key | Type | Meaning |\n|---|---|---|\n| `template` | alias, required | A document template made into `into` |\n| `when` | map of alias \u2192 (list of alias (at least one) \\| boolean) | The paper starts ticked while each named select of the record holds one of these options and each named yes/no (stored, or a formula \u2014 how a multi-select is tested: `includes({needs}, {needs:x})`) is this value \u2014 a suggestion the reader changes, never a refusal; absent, it starts ticked |\n\n#### Recording\n\n| Key | Type | Meaning |\n|---|---|---|\n| `into` | alias, required | A child the record lists in a timeline or rows block, linking back by a single link: each recording is a new row |\n| `audio` | alias, required | The child\'s files field the recording\'s audio is kept in |\n| `transcript` | alias, required | The child\'s text field the transcript is kept in, a speaker\'s turn per line |\n| `video` | alias | The child\'s files field the screen is kept in, where the recording captured it |\n| `at` | alias | The child\'s date field stamped with the moment the recording started |\n| `by` | alias | The child\'s member field set to the person who recorded |\n\n#### Signature\n\n| Key | Type | Meaning |\n|---|---|---|\n| `into` | alias, required | The record\'s files field the signature is kept in, as a picture \u2014 each signing replaces the one before |\n| `by` | alias, required | Who signed: a text field the signer types into (someone with no seat), or a member field set to the person pressing |\n| `at` | alias, required | The record\'s date field stamped with the server\'s time as the act runs |\n| `witness` | alias | Beside a text `by`, the member field set to the person pressing, who saw the signer sign |\n\n<!-- generated:end node-act -->\n\nAn Act whose `when` does not hold is not offered. One whose `requires` are empty is offered disabled, naming each; one whose\n`recommends` are empty names what it will leave blank and still presses; one a standing Check blocks is offered disabled in\nits words. The `act_<key>` workflow re-checks all three on the server, writes `set` and what was asked,\nand appends the status history. A field an act both `requires` and `asks` never disables the press. A field an Act `requires` draws in its part with no statement. An Act in a child List may `sign` the row pressed.\n\n- **Writes:** every field it sets, asks, files into, signs or records is the act\'s.\n- **Papers.** A button that makes a paper is `template` (or `templates`) with `into` and no workflow, made from the row as the act left it. `templates` keeps a paper not made yet as a placeholder, and the set downloads as one archive (`archive_<key>`). `into` files the paper in the row\'s own files field, a write of the row its table\'s lock refuses; a `paper` line is a row of its own, made on a locked record. `intake`: what the papers state of each field `fills` names is shown beside what the row holds, and the save writes only what differs. `sign`: the record reads `into` as one signature, and the act\'s paper is handed the picture under `into`\'s name (`{{#each signature}}<img src="{{url}}">{{/each}}` in an html template).\n- **`review: true`:** the workflow (`workflows`) reads and returns a changeset of the act\'s table in `data.review`; the rows the reader ticks are written each checked first, all or none. Over every row in view the act is handed no rows.\n- **A `when` that compares** splits one stage by an amount or a date with no formula field behind it; the server refuses a press the row does not meet, and a blank number or date meets no bound:\n\n```json\n{ "type": "Act", "key": "approve", "label": "Approve", "when": { "status": ["submitted"], "amount": { "lte": 5000000 } }, "set": { "status": "approved" } }\n```\n\n```json\n{ "type": "Act", "key": "gate_in", "label": "Make the gate-in EIR", "template": "eir_in", "into": "eir", "sign": { "into": "driver_signature", "by": "driver_name", "at": "signed_at", "witness": "signed_before" } }\n```\n\n## Check node\n\nA Check is a yes/no or text formula of the row of the Record page it stands in (`pages/<entity>`): it stands while true or non-empty, and a text\nformula\'s words are what the reader sees. With `on` it refuses the saves and acts it names, on the server, in every write it names, and\nmay name any yes/no or text formula of its entity. With no `on` it names an issue the entity declares in `records.issues`, warns, and may\nstate the Act that `resolve`s it; a Check with neither is refused. A Check on a count never names `update` or `all`: the edits of its rows are what clear it.\n\n<!-- generated:start node-check -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `field` | alias, required | A yes/no or text formula of the page\'s entity \u2014 an issue it declares in `records.issues` where the Check states no `on` \u2014 or the count of rows a link lists that hold one |\n| `on` | `"all"` \\| list of (`"update"` \\| alias) (at least one) | What the standing issue refuses: `update` is the rows\' saves, an Act key is that Act \u2014 on one row, or over a List\'s rows of this entity \u2014 and `all` is every Act and save. A record\'s Acts are refused by a Check on the count its issues roll up from the rows it lists |\n| `resolve` | alias | An Act on one row of this entity that clears it. A Check states an `on` or a `resolve`: the declared issue stands without one |\n\n<!-- generated:end node-check -->\n\n`update` is the rows\' saves; an Act key is that Act, on the same rows; `all` is every act and save.\nA rule that refuses a Delete is a check of the table, not a Check: state it in the table\'s `checks` with `on: ["delete"]`\n(`reference/write-rules`), where it holds for every way a row is deleted and a removal that cascades to child rows is refused whole.\nA Check is stated once, on the entity it is true of. Absent `on`, the Check warns where its rows are listed; `on` names the acts it refuses. A record\'s Act is refused by the record\'s own Check on the count its rows\' issue rolls up (`records.issues` with `{ rows }`), never by `update` or `all`: it is judged on the stored count, with the record held while the Act runs. A List over rows of an entity with Checks offers one filter of the Checks some of its rows hold, but one that stops their edits or deletes, each with how many; picking one narrows the List to exactly those rows, through the address\'s filter on the check\'s field. `checks: false` offers none.\nA Check stands on each row of its page\'s entity wherever the App lists or opens it \u2014 a root List\'s, a child List\'s, a\nsource\'s \u2014 and refuses the acts and saves it names, an Act over a List\'s rows of the entity included. A warning reading the figure of a meter that `gates` marks against its\nbound or its pass mark is refused: the meter already draws it.\n\nThe check field\'s `label` is its short name \u2014 "Over budget", "Release expired": a row\'s line says it in the check\'s tone\n(the most severe of several, and how many more), while its words whole are the row\'s tooltip. Label it as the reader names\nthe problem, in a few words, and let a text formula say the sentence: the callout over the record says the label, then the sentence after it where it says more. A check with `resolve` carries the first of those Acts the row offers as a button at the end of its line, pressing as the Act itself; one with none links to the first field its formula reads that the record draws.\nA yes/no formula whose yes needs attention (papers the customer still owes) is a Check: its yes reads in the warning tone\nwherever it is drawn, every other yes in the success tone \u2014 and the row\'s line says it, so it is no column of the List too.\n\nA Check that every app over a table states the same way restates the table\'s contract and belongs in the table\'s `checks`\n(`reference/write-rules`).\n\nA Check refusing `update` (or `edit: false` on a record, part or field) makes the rows read-only in this app alone, drawn\nunder the read-only mark, never as a lock. A lock is the table\'s: a table workflow, a person, or an Act whose workflow sets `locked: true` on `update_records` locks a row, and every door refuses its writes until a table manager unlocks it \u2014 `update_records` with\n`locked: false` in an app\'s run is judged as the member who pressed. A locked row reads locked in every app: its lock mark, its fields as values\nunder one line naming who can change it, its saves, Delete and each Act writing it refused \u2014 an Act that writes\nelsewhere, makes a paper it hands back, or unlocks it stays its workflow\'s to answer.\n\n## Reading node\n\nA Reading is a number over rows: one figure, its parts, a grid, a figure per period, steps; or a record\'s own figure. The\npicture is the runtime\'s, chosen from what the reading means \u2014 no prop picks a chart. The question is stated by which\nsplit it names:\n\n| Names | Answers |\n|---|---|\n| nothing | one figure: the rows counted, or `value` summed, `{ "avg": \u2026 }` averaged |\n| `by` | the figure per value of a select, one-row link, member or yes/no, or per band of a number\'s `tiers` |\n| `by` a date field | the figure per period (a trend); `ahead: true` reads forward over the rows still to come |\n| `by` a date field and `across` | the figure per period, each period\'s bar stacked by the values of `across` (a select\'s options in their order, a number\'s bands lowest first) \u2014 counted or summed, never averaged |\n| `by` and `across` | a grid, `by` down the side and `across` along the top |\n| `steps` | a funnel: 2 to 8 number fields summed, each kept as a share of the one before; in a record only |\n| `planned` and `done` | the work against its plan, day by day: a List\'s band over a folder, or a record\'s block, never a Sheet |\n| no `entity`, in a Record | the record\'s own `value`, a tile under its field\'s label; up to eight consecutive tiles draw as one strip |\n\n<!-- generated:start node-reading -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `key` | alias | The reading\'s query name, unique in the app. Absent, the label\'s words as a slug, else its kind and field, written once and kept |\n| `label` | text | What the figure is called: absent, a split\'s `by` field\'s label, a trend\'s summed `value`\'s (else the rows\'), a grid\'s two fields\'; one figure states its label; with `planned`, always stated |\n| `entity` | alias | The List\'s rows; in a Record, the child\'s rows under it; absent in a Record with no `by`: the record\'s own `value`; with `planned`, the rows that are the parts of the work, always stated |\n| `via` | alias \\| text | The child\'s link to the record, where it has several; in a Record, a figure may state `<link>.<link>`, reaching the record through a row of their own |\n| `value` | alias \\| `{ "avg": alias }` | A number field summed over the rows, or `{ avg }` averaged over the rows holding one \u2014 a row with no number is no part of it, and a part or period where no row holds one reads blank, never 0. An average stands as a figure, per period (`by` a date) or per part (`by` a select, one-row link, member, yes/no or tiered number), never across a grid or beside `on_hand`; its parts add up to nothing: it states no total, and its rest reads the average of all the rows the rest holds. Absent, the rows are counted |\n| `where` | [narrowing](#app-tree) | Only the rows whose select holds one of these options, whose yes/no is this value, whose number or date meets its bounds (`gt`, `gte`, `lt`, `lte`; a date\'s `{ "now": true }` is read when the rows are), whose field is `{ "empty": true \\| false }`, or whose member field holds the reader (`{ "me": true }`) \u2014 every entry ANDed |\n| `by` | alias \\| [Tiered filter](#tiered-filter) | Splits the rows into parts; a date field splits them per period |\n| `across` | alias \\| [Tiered filter](#tiered-filter) | Reads a split against a second field: with `by` a field, the columns of a grid; with `by` a date, what each period is made of, its bar stacked by this field\'s values (counted or summed, never averaged) |\n| `over` | alias | The date that places a row in time |\n| `ahead` | `true` | Shows what is coming, not what has been: with a date `by`, the current period and those after it |\n| `steps` | list of alias (2\u20138) | Number fields summed, each a step of a funnel |\n| `on_hand` | [Reading on hand](#reading-on-hand) | With `by` (and `across`): the Reading\'s rows are what is owed, per value of those fields; drawn beside what is on hand per the same values, and the shortfall |\n| `target` | number | The number the figure is read against; absent, its bound, where the table states one |\n| `better` | `"up"` \\| `"down"` | Which way is good, for the figure\'s tone; absent, read from the figure\'s shape |\n| `planned` | [Reading planned](#reading-planned) | The days each row\'s work is planned over, its share planned spread evenly across them \u2014 a row missing either is no part of the plan, and neither line counts it |\n| `done` | alias | With `planned`, the work against its plan: a percent field of the row the server computes, its share done today (0\u2013100) |\n| `finished` | alias | A date of the row: the day its work was finished, from which it stands at its `done` |\n| `tab` | alias | The Tab it reads, else the open one |\n| `when` | [condition](#app-tree) | Drawn only while this holds |\n\n#### Reading on hand\n\n| Key | Type | Meaning |\n|---|---|---|\n| `entity` | alias, required | The entity whose rows are what is on hand, all of them |\n| `value` | alias | A number field summed over those rows; absent, the rows are counted |\n| `by` | alias | The field of this entity matching the Reading\'s `by`; absent, the same alias |\n| `across` | alias | The field of this entity matching the Reading\'s `across`; absent, the same alias |\n| `where` | [narrowing](#app-tree) | Only the rows whose select holds one of these options, whose yes/no is this value, whose number or date meets its bounds (`gt`, `gte`, `lt`, `lte`; a date\'s `{ "now": true }` is read when the rows are), whose field is `{ "empty": true \\| false }`, or whose member field holds the reader (`{ "me": true }`) \u2014 every entry ANDed |\n\n#### Reading planned\n\n| Key | Type | Meaning |\n|---|---|---|\n| `start` | alias, required | A date of the row: the first day of its planned work |\n| `end` | alias, required | A date of the row: the last day of its planned work |\n\n<!-- generated:end node-reading -->\n\n#### Kinds of reading\n\n<!-- generated:start reading-kinds -->\n\n| Kind | What it is |\n|---|---|\n| `metric` | A metric is one number over an entity\'s rows: how many, or the sum or average of a number field. It is read against a target, or against the bound its `limits` states; placed in time by `over`, it shows its change over the recent periods and which way is good (`better`). |\n| `breakdown` | A breakdown splits an entity\'s rows into parts: each row is counted, or its number summed or averaged, under the one value of the field it is split by \u2014 a select\'s option, a linked row, a person, yes or no \u2014 or under the band of a number cut by `tiers`. |\n| `trend` | A trend counts an entity\'s rows, or sums or averages a number of them, per period of the date that places each row in time (`over`) \u2014 the periods up to today, or with `ahead` the current one and those after it, over the rows dated today or later; with `split`, each period\'s count or sum stacked by the values of one field. |\n| `pivot` | A pivot crosses two splits in a grid: each row of the entity is counted, or its number summed, under the pair of values it holds \u2014 one down the side (`rows`), one across the top (`columns`). |\n| `shortfall` | A shortfall sets what is still owed against what is on hand: the owed rows are counted, or a number of them summed, per value of the fields they are for (`by`, and `across`), beside every row of the stock (`on_hand`) matching those fields, with what falls short. |\n| `progress` | A progress reads the work against its plan: each row is a part of the work, planned over the days between two of its dates and done by a share the server computes, set against the plan day by day. Each row weighs its planned days. |\n| `list` | A list shows an entity\'s rows, each in its `records` anatomy \u2014 its title, its line, its status \u2014 with the fields read after the title (`columns`). |\n\n<!-- generated:end reading-kinds -->\n\nWhere a Reading stands decides which rows: a Sheet\'s every row, a List\'s rows in its open tab and folder (the search,\nthe status and the filters narrow the rows and leave the figures as they stand), a Record\'s the child\'s rows under the record. A Reading counts its rows, or sums the number\n`value` names \u2014 never a percent. `over` is a date, the row\'s own or its parent\'s through a lookup: a trend\'s periods, a\nfigure\'s recent periods, and what a Sheet\'s period windows. `where` keeps rows whose select holds one of the options, or\nwhose yes/no is the value, every entry ANDed \u2014 a band leads with the job\'s exception as a formula\'s yes/no (what is\nshort), never a stage the chips already count nor the overdue rows the register\'s summary line counts from `records.due`.\n\n- **A figure\'s change** is green where it moves the good way: a sum\'s rise, a count kept by `where` falling; `better` states\n the other way where that reads wrong (money going out). A value `limits` bounds reads against the sum of its bound\n (`10 / 14`); `target` reads one against a number nothing bounds.\n- **An average** is its sum over the rows that hold a value, divided by how many hold one; a row holding none is no part\n of it, and where none holds one the figure reads a dash, never 0. Under a Sheet\'s period it is the average over the\n period so far, never a sum of averages. A share is an average too: a number formula that is `100` on the rows that count\n and `0` on the others, in percent notation, averaged. Only a single figure averages.\n- **Bands.** `by` and `across` each take, in place of a field, a number by its `tiers` \u2014 `{ "field", "tiers" }` \u2014\n splitting the rows by the bands those breakpoints cut: `[1, 31, 61]` over days late reads not due, 1\u201330, 31\u201360 and over\n 60, the aged report. Every band is drawn in the bands\' own order, one holding no row at zero; rows holding no number\n stand apart. On a List a band is a door: a press narrows the rows to it. In a List\'s band, a split by one or two\n breakpoints stands in it, and one by three or more stands whole under it.\n- **In a List,** Readings stand under the title in one compact band: the job\'s headline number first, then at most the mix\n and the movement. A picture stands only where it splits the rows in view into two parts or more, one holding two rows or\n more. The summary line already totals the figure and the chips count the rows, so a figure summing the figure, or counting\n the rows of a table with a stage, is refused unless its `where` narrows it.\n- **Name.** A Reading\'s `key` is the query it is read by (`run_app_query`).\n- **The work against its plan** (`planned` and `done`, `label` and `entity` stated) takes none of a figure\'s props: the\n share of the work planned and the share done, cumulative day by day, today\'s two at its foot. Each row is a part of the\n work, its plan spread evenly over its planned days and weighing its planned days. Its share done today is `done`, a\n percent the server computes; on an earlier day, its `done` from its `finished` day on and nothing before it.\n\n## Statement node\n\nA Statement draws a figure the record works out from its own figures \u2014 a claim\'s payable, an invoice\'s total, a payslip\'s\nnet \u2014 line by line in the order the arithmetic runs: each line a number of the record, the first stating no `op`, the last\nan `equals`. Every figure is a field the server computes or a person writes; the screen adds nothing up. A line\'s `parts`\nlists the rows its figure carries, each read from its own row, and that figure is what they add up to \u2014 a formula, rollup\nor lookup, or the server\'s copy when the record is made (`default_from`), which nothing writes after.\n\n<!-- generated:start node-statement -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `key` | alias | The statement\'s name, unique among its siblings. Absent, the label\'s words as a slug, written once and kept |\n| `label` | text | What the statement is called: absent, the label of what it comes to |\n| `lines` | list of [Statement line](#statement-line) (at least 3), required | The figures it is built from, top to bottom, ending in the one it comes to |\n| `when` | [condition](#app-tree) | Drawn only while this holds |\n\n#### Statement line\n\n| Key | Type | Meaning |\n|---|---|---|\n| `field` | alias, required | A number of the record \u2014 stored, a formula, a rollup or a lookup \u2014 read on the line after its label |\n| `op` | `"plus"` \\| `"minus"` \\| `"times"` \\| `"equals"` | How the line works on the lines above it \u2014 `plus`, `minus`, `times`, or `equals` for what they come to, a formula, rollup or lookup the server computes; absent on the first line, which the rest work from |\n| `rate` | alias | A percent of the record read after the line\'s label: the rate its figure is taken at (retention at 5 %) |\n| `parts` | [Statement parts](#statement-parts) | The rows the line\'s figure carries, each listed under it with its words and its own figure \u2014 read from those rows, never a copy of them. The line\'s figure is what they add up to, drawn read: a formula, rollup or lookup, or a value the server copies when the record is made (`default_from`) that nothing writes after |\n\n#### Statement parts\n\n| Key | Type | Meaning |\n|---|---|---|\n| `rows` | alias, required | The entity whose rows the line\'s figure carries \u2014 the record\'s own for the earlier rows of the same thing |\n| `same` | alias, required | A one-link the record and those rows both hold: the rows naming what the record names in it |\n| `at` | alias | A moment (a datetime) of those rows no person keys \u2014 when each was certified: with `before`, only the rows whose moment stands before the record\'s, earliest first; absent with it, every row so named, in their own order |\n| `before` | alias | A moment (a datetime) of the record no person keys \u2014 when it was made: the moment the rows\' `at` stands before; stated with `at` |\n| `where` | map of alias \u2192 (list of alias (at least one) \\| boolean \\| `{ "empty": true \\| false }` \\| [comparison](#values)) | Only the rows whose single select holds one of these options, whose yes/no (stored, or a formula) is this value, whose number or date meets its bounds, or whose field is empty or filled \u2014 read so on the server |\n| `columns` | list of alias (1\u20132), required | The rows\' fields read as each one\'s words, in order (its date, its percent) |\n| `figure` | alias, required | The rows\' number each one reads at the figures\' edge, frozen when the row was certified: a stored number an act fills (`{ "formula": \u2026 }` as it runs) or the server copies when the row is made (`default_from`) \u2014 never one a person keys, nor a formula, rollup or lookup the server recomputes |\n\n<!-- generated:end node-statement -->\n\n```json\n{\n "type": "Statement",\n "key": "claim",\n "lines": [\n { "field": "contract_value" },\n { "field": "done_to_date", "op": "times" },\n { "field": "value_to_date", "op": "equals" },\n { "field": "certified_before", "op": "minus", "parts": { "rows": "claim", "same": "contract", "at": "certified_at", "before": "made_at", "where": { "kind": ["work"] }, "columns": ["claimed_on", "done_to_date"], "figure": "certified_value" } },\n { "field": "claim_value", "op": "equals" },\n { "field": "retention", "op": "minus", "rate": "retention_rate" },\n { "field": "payable", "op": "equals" }\n ],\n "when": { "kind": ["work"] }\n}\n```\n\n## Comments node\n\nComments draws the record\'s comment thread: the platform\'s built-in comments, the same thread the table\'s record panel and a custom-code app show, so threads already written appear. It stands in a Section or the Side of a Record (or among a one-part Record\'s children), once per Record: two that differ are refused (`record.placed-once`). Presence is the opt-in: a Record with no Comments serves none, and the app\'s `comments` capability follows the node, never a tool. The thread is oldest first with a box under the last to write one; edit and delete are the author\'s alone; files already attached are shown, none are added here. Members only: a person outside the workspace sees none. A person reads the comments of any record of the table the app\'s record read reaches, narrowed by the App\'s `rows` where it states one \u2014 a List\'s `where` or a "me" chip is no row rule. A Record over a Query has no table, so no thread.\n\n<!-- generated:start node-comments -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `key` | alias | The thread\'s name, unique among its siblings. Absent, `comments`, written once and kept |\n| `title` | text | The thread\'s heading; absent, the word for comments in the app\'s language ("Comments", "B\xECnh lu\u1EADn") |\n| `when` | [condition](#app-tree) | Drawn only while this holds |\n\n<!-- generated:end node-comments -->\n\n```json\n{ "type": "Comments", "title": "Discussion" }\n```\n\n## Export node\n\nAn Export is a report file of the rows in view: the title, a line per chip, the search and the moment it was exported, the\nReadings, and every row, at most 20,000. With no props, the one Export is the workbook of the List\'s columns, the Readings\non a sheet before the rows. A List states the reports the business sends \u2014 one a button, several one menu \u2014 each a `label`,\na `description`, and a `template` filled with `title`, `lines`, `readings`, `at` (the moment it was made), `dates` (each\ndate filter\'s `from` and `to` by field) and the rows under the table\'s alias (an html one made a PDF, an excel one a\nworkbook). A report\'s `filename` names its file in the template grammar over the same keys but the rows. Where `per` is a\none-row link, `per_row.<field>` reads a text, number, date or yes/no field of the picked row, and `| add_days:<n>` shifts a\ndate by whole days (`n` a number or such a field, empty for none): `Stock {{per}} {{period.to | add_days:per_row.day_offset | format:"dd.MM.yyyy"}}`. A report of some\nrows (`where`), or of one value the reader picks (`per`: one file per value), is made of the List as those chips would\nnarrow it; the screen keeps the chips and rows it shows. A report sent outside the business \u2014 a partner\'s stock, a\nfiling \u2014 is `fixed`: the same file from every screen and device, of what the reader narrowed only the period and the\ndate chips reaching it, never their status, other chips or search.\n\nProve an Export with `run_app_query` and `export` (`agent_surface/exporting-a-file`): the answer is the file it makes.\n\n<!-- generated:start node-export -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `key` | alias | The report\'s name, unique in the app. Absent, the label\'s words as a slug, written once and kept |\n| `label` | text | The report\'s name; absent on the one Export that stands for the register\'s workbook |\n| `description` | text | What the report is for, in a sentence |\n| `template` | alias | An html or excel document template the report fills, with `title`, `lines`, `readings`, `at`, `dates`, `period`, `per` and `per_row` (a one-row `per`\'s picked row, the fields `filename` reads); absent, the workbook of the List\'s columns |\n| `filename` | text | The file\'s name, at most 500 characters, in the template grammar, over one value each: `title`, `at`, `dates.<field>.from` or `.to`, `period.from` or `.to`, `per`, `per_row.<field>` (a text, number, date or yes/no field of the row a one-row `per` picks), `lines \\| lookup:<n>`; `\\| add_days:<n>` shifts a date by whole days, `n` a number or `per_row.<field>`. Absent, the report\'s label |\n| `where` | [narrowing](#app-tree) | Only the rows whose select holds one of these options, whose yes/no is this value, or whose member field holds the reader (`{ "me": true }`) \u2014 every entry ANDed |\n| `per` | alias | A select, member or one-row link the reader picks one value of: one file of that value |\n| `sources` | list of alias (at least one) | Of the List\'s entity and its sources, the tables the report reads; absent, all |\n| `fixed` | `true` | The same file from every screen: only its `where`, its `per`, the period and the date chips narrow it, never the reader\'s status, other chips or search; absent, the rows in view |\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `list.export-report` | A List\'s Exports each have their own `label`; `per` picks one option, person or one-link row \u2014 never of the status, the folder or a field its `where` fixes. |\n| `list.export-key` | An Export is named by its key alone: no two Exports of an app share one. |\n| `list.export-filename` | An Export\'s `filename` is words and `{{value}}` placeholders, each value one of `title`, `at`, `dates.<field>.from` or `.to` (a date filter of the List), `period.from` or `.to` (a List with Tabs), `per`, `per_row.<field>` (a field of the row a one-link `per` picks) and `lines \\| lookup:<n>`, through helpers that exist and take the arguments given. |\n| `list.export-template` | A template an Export fills is an html or an Excel one (a Word register stays a workflow body) and reads at its root only `title`, `lines`, `readings`, `at`, `dates`, `period`, `per`, `per_row` (and `columns`, on a roster) and its rows under the List\'s entity alias \u2014 an entity named none of those \u2014 and is the document of no Act. |\n\n<!-- generated:end node-export -->\n\n## Query node\n\nA Query is a read for agents, never drawn. An app generates a query for everything its screen reads (`agent_surface` lists them); a Query declares one the screen never asks, called through `run_app_query` or the app\'s API: the\ntable whose rows it reads, the fields each row returns, and what narrows them.\n\n<!-- generated:start node-query -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `description` | text, required | What the query answers, read by whoever calls it by its alias \u2014 at most 300 characters |\n| `params` | map of alias \u2192 ([Workflow value](#workflow-value) \\| a typed input (`app_bindings`)) | What a call states, by name: with `rows` or `list`, values a `where` entry reads; with `ast`, typed inputs the ast reads as `{{params.<name>}} |\n| `fields` | list of alias (at least one) | The fields each row returns, by alias: with `rows` or `list`. `ast` states its own |\n| `sort` | [Sort key](#sort-key) \\| list of [Sort key](#sort-key) (at least one) | The order the rows return in; absent, the order the entity\'s list reads in |\n| `limit` | integer | The most rows returned |\n| `key` | alias, required | The query\'s name, what `run_app_query` calls; unique in the app |\n| `rows` | alias | The table whose rows it reads, under the app\'s row rule of it and, where the table holds one one-row link to the App\'s `scope`, inside the folder the call states. A Query states `rows`, `list` or `ast`, one of the three |\n| `list` | alias | The key of a root List of the App: the rows read as that List reads them \u2014 its `where`, its folder and its order. A Query states `rows`, `list` or `ast`, one of the three |\n| `ast` | a query tree (`app_bindings`) | The whole read, where `rows` or `list` cannot state it: a join, a union, a group, a window or a computed column. Fields and tables by alias |\n| `templates` | map of text \u2192 a document template (`app_bindings`) | Document templates an export of this query\'s rows may fill, by the name the export asks for. An export names one of these or none; a template it does not declare is refused. |\n| `where` | map of alias \u2192 [condition](#query-node) | What narrows the rows, as a List\'s `where` does: a select\'s options, a yes/no\'s value, a number or date meeting its bounds (`gt`, `gte`, `lt`, `lte`), a field `{ "empty": true \\| false }`, `{ "me": true }` on a member field \u2014 or a value the call states (`{ "param": name }`), or a date or number range of params (`{ "from": \u2026, "to": \u2026 }`) |\n\n#### Query param\n\n| Key | Type | Meaning |\n|---|---|---|\n| `param` | text, required | A param of this query: the condition holds what the call states for it, and is left out where the call states none |\n\n#### Query range\n\n| Key | Type | Meaning |\n|---|---|---|\n| `from` | [Query param](#query-param) | The param the field is on or after \u2014 a date\'s first day, a number\'s least |\n| `to` | [Query param](#query-param) | The param the field is on or before \u2014 a date\'s last day, a number\'s most |\n\n<!-- generated:end node-query -->\n\n```json\n{\n "type": "Query",\n "key": "fees_unbilled",\n "description": "A customer\'s fees no invoice covers yet, oldest first.",\n "params": {\n "customer": { "type": "record_link", "entity": "customer", "description": "The customer whose fees are read." },\n "since": { "type": "date", "required": false, "description": "Only fees charged on or after this day." }\n },\n "rows": "fee",\n "fields": ["visit", "service", "amount", "charged_on"],\n "where": { "billed": false, "customer": { "param": "customer" }, "charged_on": { "from": { "param": "since" } } },\n "sort": { "field": "charged_on" },\n "limit": 200\n}\n```\n\nAn entry of `where` holds what a Reading\'s `where` holds, or a value the call states: `{ "param": "<name>" }`. A required\nparam is always stated; one stating `required: false` may be left out, and the condition reading it then narrows nothing.\nA query reads under its table\'s read scope, as every read of the app does. A caller counts, sums or averages its rows\nwith `run_app_query`\'s `aggregate`. `set_app` compiles a Query with the rest of the app: no code is set.\n\nEvery Reading of the app is a query too, returning its groups, called by its key. A Tab\'s `totals` read is called by\n`<table>_totals_<tab>` with the period\'s two days, `from` and `to`, both required.\n\nA query reads one table: on an app whose List reads `sources`, it names a source\'s own table, never the\nList\'s. A param compares a field holding one value \u2014 or, as a range, a date or a number \u2014 and never a number read in each\nrow\'s own unit or currency, nor a date holding a span.\n\n## Workflow node\n\nA Workflow is a verb for agents, never drawn: a job no press of the screen starts \u2014 an agent or a service handing the app a\nfile, or a list of rows to reconcile a table against. It states what it takes and what it hands back; a table is named by\nits alias in `tables` and a select by `<table>.<field>`. It is called through the app, by `run_app_workflow` or the app\'s\nAPI. On an app shared by a public link it runs only for someone who holds the app, and a visitor\'s call is refused as an\nalias the app does not have.\n\n<!-- generated:start node-workflow -->\n\n| Key | Type | Meaning |\n|---|---|---|\n| `description` | text, required | What the workflow does, read by whoever calls it by its alias \u2014 at most 300 characters |\n| `inputs` | map of text \u2192 [Workflow value](#workflow-value) | What a call hands it, by name \u2014 checked before its body runs |\n| `outputs` | map of text \u2192 [Workflow value](#workflow-value) | What its body returns as `data`, by name \u2014 checked as it returns; absent, read off the body |\n| `key` | alias, required | The workflow\'s name, what `run_app_workflow` calls; unique in the app |\n\n#### Workflow value\n\n| Key | Type | Meaning |\n|---|---|---|\n| `type` | `"text"` \\| `"number"` \\| `"boolean"` \\| `"date"` \\| `"datetime"` \\| `"email"` \\| `"json"` \\| `"record_link"` \\| `"select"` \\| `"member"` \\| `"file"` \\| `"object"` \\| `"array"`, required | What the value is |\n| `description` | text | What the value is for, read by whoever calls the workflow |\n| `required` | boolean | Lets a caller leave the value out: false; absent or true, it is always there |\n| `multi` | `true` | A `record_link`, `select`, `member` or `file` holding several |\n| `entity` | alias | The entity a `record_link` names a row of |\n| `field` | text | `<entity>.<field>`: the select field whose options a `select` takes, as the field holds them when the workflow runs |\n| `options` | list of (alias \\| [Select option](#select-option)) (at least one) | The values a `select` takes, where no field holds them: aliases, or the objects a field\'s `options` take |\n| `fields` | map of text \u2192 [Workflow value](#workflow-value) | An `object`\'s values, by name |\n| `items` | [Workflow value](#workflow-value) | What each item of an `array` is |\n\n<!-- generated:end node-workflow -->\n\n```json\n{\n "type": "Workflow",\n "key": "reconcile_fees",\n "description": "Reconciles a visit\'s fees against the lines of the carrier\'s statement.",\n "inputs": {\n "visit": { "type": "record_link", "entity": "visit" },\n "statement": { "type": "file", "required": false },\n "lines": { "type": "array", "items": { "type": "object", "fields": { "service": { "type": "select", "field": "fee.service" }, "amount": { "type": "number" } } } }\n },\n "outputs": { "added": { "type": "number" }, "changed": { "type": "number" } }\n}\n```\n\nIts code is set on the app, never stated in the tree: `set_workflow` with a `source` whose `on({ type: "app", app_id, alias })` header names the app and the key, leaving\n`inputs` and `outputs` out \u2014 the code is checked against what the node declares. Every `set_app` keeps that code and holds\nwhat it takes, what it hands back and its description to the node. `set_app` keeps the code where it still meets a change\nof what the workflow takes or hands back; a change it does not meet is refused unless the same `set_app` carries the new\ncode in `workflows`, each as `set_workflow` takes it. With no code yet it refuses every call, and each `set_app` says so. A\nWorkflow the tree stops declaring is archived with its key.\n\n## Tasks\n\nA table whose `records` states `"task": true` \u2014 its status a stored select with `closed` \u2014 is work someone finishes.\nEvery List of its rows draws it alike, each row led by a ring. Ticking the ring moves the row to a closed option by the\none write the app already has for that move: the Act of that table setting a closed option, offered on an open row and\nasking nothing, else its own save where people write the status \u2014 stamping what that act stamps and appending the\nstatus history. Unticking runs the Act moving a closed row back, else the save back to the status\'s default. A move no\nwrite reaches leaves the ring disabled and the check notes it. An Act with `on: "ticked"` completes several at once.\n\nA record listing task rows filed under it by a link holding one row says how much of that work is done \u2014 those at a\nclosed option of all \u2014 wherever its row is drawn: a meter on its head, a column of its register\'s rows, a card\'s foot, a\ncalendar entry, a gantt\'s or a lane\'s bar. No rollup is stated for it.\n\n```json\n{\n "tables": [\n {\n "ref": "project",\n "label": "Projects",\n "singular": "Project",\n "fields": {\n "name": { "label": "Name", "required": true, "type": "text" },\n "lead": { "label": "Lead", "type": "member" }\n },\n "title": "name",\n "records": {}\n },\n {\n "ref": "task",\n "label": "Tasks",\n "singular": "Task",\n "fields": {\n "title": { "label": "Title", "required": true, "type": "text" },\n "project": { "label": "Project", "required": true, "type": "link", "table": "project", "multi": false },\n "assignee": { "label": "Assignee", "type": "member" },\n "status": {\n "label": "Status",\n "required": true,\n "default": ["todo"],\n "type": "select",\n "options": [\n { "alias": "todo", "label": "To do", "color": "slate" },\n { "alias": "done", "label": "Done", "color": "green" }\n ]\n },\n "due": { "label": "Due", "type": "date", "format": "date" },\n "done_on": { "label": "Done on", "type": "date", "format": "date" }\n },\n "title": "title",\n "records": {\n "subtitle": ["assignee"],\n "due": ["due"],\n "task": true,\n "starts": { "assignee": "me" },\n "status": { "field": "status", "closed": ["done"] }\n }\n }\n ]\n}\n```\n\n```json\n{\n "body": {\n "type": "App",\n "key": "projects",\n "name": "Projects",\n "color": "blue",\n "tables": { "project": "<id of the project table>", "task": "<id of the task table>" },\n "templates": {},\n "children": [\n {\n "type": "List",\n "entity": "project"\n }\n ],\n "pages": [\n {\n "type": "Record",\n "entity": "project",\n "children": [\n {\n "type": "Section",\n "key": "work",\n "title": "Work",\n "children": [\n "lead",\n {\n "type": "List",\n "entity": "task",\n "columns": ["due"],\n "children": [\n { "type": "Act", "key": "complete_all", "label": "Complete", "on": "ticked", "when": { "status": ["todo"] }, "set": { "status": "done", "done_on": { "now": true } } }\n ]\n }\n ]\n }\n ]\n },\n {\n "type": "Record",\n "entity": "task",\n "children": [\n { "type": "Act", "key": "complete", "label": "Complete", "when": { "status": ["todo"] }, "set": { "status": "done", "done_on": { "now": true } } },\n { "type": "Act", "key": "reopen", "label": "Reopen", "when": { "status": ["done"] }, "set": { "status": "todo", "done_on": null } }\n ]\n }\n ]\n }\n}\n```\n\nThe tasks as a register of their own, for one person: a one-part Record holds its Fields and Acts directly.\n\n```json\n{\n "body": {\n "type": "App",\n "key": "my_tasks",\n "name": "My tasks",\n "color": "teal",\n "tables": { "project": "<id of the project table>", "task": "<id of the task table>" },\n "templates": {},\n "children": [\n {\n "type": "List",\n "entity": "task",\n "opens": { "assignee": { "me": true } },\n "children": [\n { "type": "Reading", "label": "Open", "where": { "status": ["todo"] } }\n ]\n }\n ],\n "pages": [\n {\n "type": "Record",\n "entity": "task",\n "door": "drawer",\n "children": [\n "project",\n "due",\n { "type": "Act", "key": "finish", "label": "Finish", "when": { "status": ["todo"] }, "set": { "status": "done", "done_on": { "now": true } } },\n { "type": "Act", "key": "undo", "label": "Undo", "when": { "status": ["done"] }, "set": { "status": "todo", "done_on": null } }\n ]\n }\n ]\n }\n}\n```\n\n## App rules\n\nEvery rule the check enforces over an app, one sentence each under an id; a finding names its rule\'s id\n(`[list.filter]`), and `reference/<rule id>` is that one rule\'s page. A sentence names the node and the prop an author writes (`List.create`, a `Section`);\neach area stands in the tree where this table says:\n\n| Area | Stands at |\n|---|---|\n| `app` | what every write meets (the tree\'s keys, the names it declares, the tables and rows it carries), the App, and the register List\'s props that belong to the app: `words` (labels), `color`, `scope`, sources, the root Views |\n| `template` | the document templates an Act makes and an Export fills |\n| `list` | a List: its columns, filters, search, group, sort, layout, tabs, period, export, and what a child List holds |\n| `reading` | a Reading |\n| `record` | a Record and its parts: Section, Side, Act placement |\n| `statement` | a Statement |\n| `act` | an Act |\n| `check` | a Check |\n\n<!-- generated:start rules-app -->\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `app.schema` | Every key is one its table lists, holding the type its row gives, and every required key is stated. |\n| `app.names-declared` | Every alias a key names is declared: a table of the App\'s `tables`, a field of the table the node reads, an option of the select it names, an Act `key` of the App, a template of its `templates`, or an app. |\n| `app.record-home` | A Record stands in the App\'s `pages`, never inside a List: one page per entity, opened from the Lists over it. |\n| `app.spec-claims` | Every workflow a tree\'s screens run is one the app binds, taking each input the screens send. |\n| `app.spec-sound` | The app a tree compiles to reads every column its screens draw and carries what each needs: a tree refused for it meets a fault of the platform\'s, which is reported, and no change to the tree is owed. |\n| `app.compile-lowers` | Every screen, read and write a tree states lowers to the app\'s spec: a tree the compiler cannot lower is refused at the App. |\n| `app.tables` | A call declares at least one table and at most 50; send the rest in a second call. |\n| `app.rows-cap` | Rows are a sample: at most 200 per entity, 2000 per call and 2000 documents attached \u2014 a real data set goes in with `create_records` once the tables exist. |\n| `app.alias-scope` | An alias is unique where it is named: tables and fields in their table, options in their select. |\n| `app.label-unique` | A label is unique where it is found by its label: fields in their table, options in their select. |\n| `app.filter` | A filter \u2014 a view\'s, a rollup\'s \u2014 tests fields of the entity it reads, through links as `entity.field` hops each standing on the entity the last lands on, by options its select declares. |\n| `app.input-once` | The fields the App\'s saves, adds and Acts of a table send are each sent under one input name: a files or many-link field is sent as `<alias>_added` (and `<alias>_removed` by a save or an Act), so no other field of the write is so named, and none takes an input the workflow names itself, such as `record_id`, the input naming the row. |\n| `app.alias-unique` | An App\'s `key` is unique among apps, and an Act\'s among the Acts of its App, every List\'s included. |\n| `app.icon` | An App\'s `icon` is a Lucide icon name in kebab-case, as `receipt` or `trending-up` are. |\n| `app.add-label` | A List\'s `add_label` stands only where it adds rows (`create`), in words that are not empty and hold no `{` or `}`. |\n| `app.labels` | An App\'s `words` name a table it reads and a field or option of it, in words that are not empty and hold no `{` or `}`; no two fields of a table, nor two options of a field, show the same words. |\n| `app.records-entry` | Every table an App draws a List over, opens or picks from \u2014 a root List\'s, a child List\'s, a linked row\'s, a documents List\'s \u2014 has a `records` entry. |\n| `app.scope` | The App\'s `scope` names the table whose one row the app works inside (the folder), a table whose row rule can bind; every List over a table linking to it is filed in the open folder (`list.scope`). Stated again on such a List as a `columns`, `filters` or `search` entry, `group`, `where`, `opens`, a Field of a part, a `create` question or a report\'s `where` or `per`, its folder link is left out and said: the App already narrows every read to it and files every add under it. |\n| `app.folders` | The App\'s `folders` names a root List over the table its `scope` names: that List draws the folders the app opens on, and a row pressed is the folder entered. |\n| `app.when` | A node\'s `when` holds single selects to options, yes/nos to `true` or `false` (stored, a formula of one \u2014 a formula with `options` is a select \u2014 or, offering a node, a lookup through a link to one row), numbers and dates to bounds (`gt`, `gte`, `lt`, `lte`; a date\'s bound is a day, a moment on a datetime, or `{ "now": true }`) and any field but a yes/no to `{ "empty": true \\| false }` \u2014 a number read in each row\'s own unit or currency takes only the bound 0, and a lookup takes none. |\n| `app.asked-written` | What a List\'s `create` asks, what an Act\'s `asks` asks and what `starts` fills is a field a person writes \u2014 never a formula, rollup, lookup, autonumber or a date the workspace stamps. |\n| `app.own-rows` | A many-link to rows that each belong to one row of this entity is never a `create` question or an Act\'s `asks`: those rows are the record\'s own, each written by its own write. |\n| `app.create-asks` | A List\'s `create` asks fields a person writes \u2014 never the link or the folder it files the row under, which the add sets itself. |\n| `app.create-required` | A List\'s `create` asks every field its entity requires that nothing else fills \u2014 a `default`, `starts`, the record or folder it files the row under, or a `default_from` over a link it fills \u2014 or the server refuses every add. |\n| `app.row` | A Record\'s `row` states only what differs from `records`: a `subtitle` that is not the title, a number for its `figure`, dates for its `due`, an `image` that is a files picture no Act makes documents into, or `false` for a figure, deadlines or picture the entity states and the App draws none of. `row` changes what the head draws, never what the App writes (`record.edit-declared`). |\n| `app.restates` | *Noted, never refused:* A key the tree states that the platform sets the same without it \u2014 a `label` the table\'s or field\'s own, a `row.subtitle` the table\'s, a `door`, an add or a layout end the default gives, a row rule a status history inherits \u2014 changes nothing: the write keeps it and says so. |\n| `app.tasks` | *Noted, never refused:* A task entity an App lists whose rows no write of the App moves to a closed option (its ring stands disabled), or that an Act ticks done and none moves back. |\n| `app.same-list` | *Noted, never refused:* A root List over a table another App of the workspace lists at its root. Unnarrowed, every reader sees the same list, and a row\'s rail shows only that app\'s parts, so no one sees the whole path. A different job narrows with `where` and `columns`; a shared job stays one app, `owner` on its Acts and stages deciding who presses. |\n| `app.views-jobs` | *Noted, never refused:* An App of more than two Views, or a Sheet of more than six Readings, asks whether each is a job someone does on its own: Views of one job read better as one List\'s filters, tabs or Readings, and a Sheet reads at a glance with few. |\n| `app.tile` | *Noted, never refused:* An App that draws a List or a Sheet and states no `icon`, no `color` or neither: its launcher tile draws the glyph, or the colour, every App stating none shares, so the workspace\'s apps read alike. |\n| `app.workflow-value` | A value a Workflow takes or hands back states what its type needs and nothing another type does: a `"record_link"` its `entity`, a `"select"` its `options` or the `field` holding them \u2014 never both \u2014 an `"object"` its `fields`, an `"array"` its `items`; `multi` stands on a `"record_link"`, `"select"`, `"member"` or `"file"`; an output is never a `"member"` or a `"file"`; and a value nests at most 8 deep. |\n| `app.query` | A Query reads `rows` of one table \u2014 under the App\'s row rule of it and inside the open folder where the table holds one one-row link to the App\'s `scope` (one holding several is read through `list`) \u2014 or a root List\'s rows as that List reads them (`list`: its `where`, folder and order; never a List reading `sources`), one of the two; it returns them as `fields`, ordered by `sort` and bounded by `limit`; each param is a number, a yes/no, a date, a select, a one-row link or a member holding one, read by an entry of `where` on a field of its type \u2014 a date by a range, a number by either, and never a number read in each row\'s own unit or currency or a date holding a span. |\n| `app.generated-name` | A name the App makes is taken by nothing the App states: no Query, Workflow, Reading or List `key` is the name of a read or a workflow the App makes, an Act\'s own `workflow` among them; where the App makes two reads spelled alike, the later takes the next free ordinal (`_2`, `_3`). |\n| `app.surface-described` | *Noted, never refused:* A value a Workflow takes, and a param a Query takes, that states no `description`: the one line a caller reads to fill it. |\n| `app.keys-unique` | No two children of one node share a key: an address names one node. |\n| `app.states-list` | An App states a List whose rows it lists, only Sheets of Readings, or only Queries and Workflows for a server to call. |\n| `app.period` | An App\'s `period` is the window every Sheet opens on, so it stands in an App that holds a Sheet: a List states its own `period`. |\n| `app.dashboard-words` | An App that holds Sheets and no List reads every table\'s rows whole and states no `words` or `scope`: those are an App with a List\'s. |\n| `app.entity-once` | The App\'s Lists and their sources work a table one way: its rows ticked as tasks by the same moves, and their work counted by the same kinds of task rows. |\n| `app.add-filed` | The Lists adding rows of one table file them by one link: where two Lists add them by different links, each is refused naming the other\'s \u2014 state `create: false` on every List but the one whose link files them. Wrong: a List adding `booking` rows filed by `freelancer` beside one filed by `production`. Right: one states `create: false`. |\n| `app.adds-disagree` | Adds of one entity\'s rows hold a status that Acts move at the same stage. |\n| `app.check-field-unwritten` | *Noted, never refused:* A table the App updates or adds rows to, with an enabled check on that write naming a `field` the App writes nowhere in it (no Act asks, requires or sets it, no Record or add writes it), refuses every such write a person here makes: ask the field in the Act that moves the row, or draw it editable. A workflow may fill it, so it is said, never refused. |\n| `app.adds-field` | A picker\'s `add` names fields of its table a person writes, each once. |\n| `app.edits` | *Noted by the designer on a write, never refused:* The fields an app\'s saves may change are the fields its surfaces write \u2014 a record\'s save, a child row\'s, an in-place column, a lane, gantt or plan move \u2014 less what its own Acts change; the designer notes an app whose saves change none. |\n\n<!-- generated:end rules-app -->\n\n## Reading rules\n\n<!-- generated:start rules-reading -->\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `reading.value` | A Reading sums a number, never a percent \u2014 percents do not add up; a value of `{ avg }` reads one. |\n| `reading.average` | `{ avg }` averages a Reading\'s `value` over the rows holding one, read against a plain `target` \u2014 never a value `limits` bounds, whose bound is a sum. |\n| `reading.split` | `by` and `across` split by one value each row holds \u2014 a single select, a one-row link, one member or a yes/no, stored or a formula, a lookup through one-row links as the field it reads \u2014 or by the bands `tiers` cut a number read in one unit on every row; a date `by` splits them per period, as a trend, each period stacked by `across` where it states one; a grid crosses two different fields. Never by the select that sets the unit or currency of the number summed: its figure already reads once per unit. |\n| `reading.over` | `over` is a date: the row\'s own, stored or a formula, or its parent\'s through a lookup over a one-row link. |\n| `reading.where` | A reading\'s and a Query\'s `where` keep rows by a select\'s options, a yes/no\'s `true` or `false`, a number or date\'s bounds (`gt`, `gte`, `lt`, `lte`; a date\'s `{ "now": true }`), `{ "empty": true \\| false }`, or a member field, a lookup of one, or a member of the row a one-row link names (`<link>.<member>`), holding the reader (`{ "me": true }`); a List\'s `where` also keeps rows by `<link>.<field>`, a select or yes/no of the row a one-row link names; a Query\'s `where` also holds a field to what the call states (`param`, `from`, `to`). |\n| `reading.target` | `target` reads a value nothing bounds \u2014 a value `limits` bounds reads against the sum of its bound. |\n| `reading.better` | `better` needs `over`: a change is read over the periods its date places the rows in. |\n| `reading.progress` | A Reading stating `planned` and `done` (the work against its plan) reads dates of its rows for `planned` and `finished`, and a number for `done`. |\n| `reading.progress-alone` | A Reading stating `planned` or `done` is the work against its plan: it names its `entity` and states `planned` and `done`, with `finished`, `where`, `via`, `tab`, `when` and `label` beside them, and none of a figure\'s props (`value`, `by`, `across`, `over`, `ahead`, `steps`, `on_hand`, `target`, `better`). It stands in a List\'s band or a record, never on a Sheet. |\n| `reading.key` | A Reading\'s `key` is its query\'s name, and a List that only reads is called by its `key`, else its entity\'s alias: each its own among the App\'s Readings, Lists that only read and Queries. |\n| `reading.tabs` | A Sheet holds Readings and Lists, one at least; a Reading stands in a Sheet or in a List\'s band. |\n| `reading.restate` | *Noted, never refused:* A Sheet\'s count tile counting the rows a List beside it lists under the same `where` and tab, and a List\'s band counting its rows past a deadline, say what the List already draws: its head counts the first, its overdue chip the second. |\n| `reading.period` | An App\'s `period` stands only over a Reading placed in time by `over`. |\n| `reading.funnel-place` | A Reading with `steps` (a funnel) stands in a part of a Record: a band and a Sheet draw none. |\n| `reading.on-hand-split` | A Reading with `on_hand` compares what is owed with what is on hand per value of one field, or two: its `by` and `across` name fields, never bands. |\n| `reading.average-kind` | An average (`value: { avg }`) is a figure\'s, a trend\'s (`by` a date) or a breakdown\'s (`by` a select, one-row link, member, yes/no or tiered number): its Reading states no `on_hand` or `across`. |\n| `reading.via-path` | A Reading\'s `via` is a path (`<link>.<link>`, reaching the record through a row of the child\'s own) only on a Record\'s page, over a number, a split, a trend, a grid or a shortfall of the child\'s rows \u2014 never in a List\'s band or on a Sheet, nor on the record\'s own figure, a funnel or the work against its plan. |\n| `reading.grid-rows` | `across` splits a grid\'s columns, and stands only beside the `by` splitting its rows. |\n| `reading.band-off` | `readings: false` turns off the band a register leads with by default: a List stating it states no Readings, which are the band. |\n\n<!-- generated:end rules-reading -->\n\n## Statement rules\n\n<!-- generated:start rules-statement -->\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `statement.lines` | A Statement\'s `lines` are numbers of the record, each once \u2014 the first stating no `op`, every other one, the last an `"equals"` \u2014 each `"equals"` a formula, rollup or lookup, and a `rate` a number of the record. |\n| `statement.rows` | A line\'s `parts` read rows of an entity holding `same`, a one-link of the record\'s to the same entity; `at`, a moment of those rows, and `before`, a moment of the record (datetimes, never days), stated together; their `columns` and `figure` are those rows\' fields, the figure a number. |\n| `statement.parts-keyed` | A line\'s `parts` add up to its figure, so no person keys it: a formula, rollup or lookup, a value the server copies when the record is made (`default_from`) that no `create` asks and no save or Act writes, or a stored number the App\'s saves leave out \u2014 the line draws it read; each part\'s `figure` is frozen when its row was certified \u2014 a stored number an Act fills, the server copies or the App\'s saves leave out, never one a person keys or the server recomputes \u2014 and no person keys the moments `at` and `before` either. |\n\n<!-- generated:end rules-statement -->\n\n## Check rules\n\n<!-- generated:start rules-check -->\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `check.field` | A Check\'s `field` is an issue its entity\'s table declares in `records.issues` \u2014 a yes/no or text formula of the row, or the count of rows a link lists that hold one (`<link>_<issue>`). |\n| `check.of` | A Check stands in `pages/<entity>` and names an issue of that entity. |\n| `check.states-nothing` | A Check names an `on` or a `resolve`: a declared issue already stands wherever the row is drawn, so one that refuses and clears nothing adds nothing. |\n| `check.not-placed` | A Check\'s field is never also placed on the record as a Field \u2014 the line under the head says it. |\n| `check.on` | A Check\'s `on` names what it refuses: `"update"` (the saves), the `key` of an Act over the Check\'s entity \u2014 on one row or over a List\'s rows \u2014 or `"all"`. A record\'s Acts are refused by a Check of that record on the count its issues roll up from the rows it lists. It binds this App alone; a Delete is the table\'s checks\' to refuse. |\n| `check.resolve` | A Check\'s `resolve` names an Act of this App on one row of the Check\'s entity, not refused by the Check, and drawn as a button \u2014 never a correction. |\n| `check.restates-meter` | A warning reading a gated meter\'s figure against its bound or pass mark is refused \u2014 the meter draws it. |\n\n<!-- generated:end rules-check -->\n\n## List rules\n\nThe rules of a List\'s props and of what a child List holds. A layout\'s, a Tab\'s, an Export\'s and a desk\'s rules stand with their keys.\n\n<!-- generated:start rules-list -->\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `list.key-shape` | A List\'s key is not a record id\'s shape. |\n| `list.peers-read` | Root Lists over one table may state different `where`, unless one holds a `where` through a link, `sources` or a `plan` layout. |\n| `list.column-drawn` | A List\'s `columns` stand beside what the row draws itself: a column of its title, subtitle, picture, status, figure or meter\'s bound, of a child List\'s link back, or one named twice, stands once where the row seats it. |\n| `list.columns-budget` | *Noted, never refused:* A List\'s `columns`, each at the width of its kind, are told against the room a desk leaves beside its name and the row\'s own status, deadline and figure; what does not fit folds onto the name\'s line. |\n| `list.chips` | `chips: false` stops a register opening on status options. |\n| `list.filter` | A List\'s `filters` name a select, a member, a link, a date, a yes/no or a number of the List\'s own rows \u2014 a lookup through one-row links as the field it reads \u2014 never the status its chips draw, nor one `where` fixes; `values` only on a select, member or link. A List states at most 3, whatever draws its rows. |\n| `list.filter-split` | *Noted, never refused:* A `filters` entry on a field a Reading of the List with `by` or `across` splits the rows by \u2014 a press on its part narrows by it too; a member\'s filter, which narrows to the reader\'s own rows, is never noted. |\n| `list.filter-unshown` | A `filters` entry of a List, a child List included, names a field its rows show: a `columns` entry, the row\'s title, line, picture, status, figure, deadline or meter\'s bound, the unit or currency a drawn figure is read in, a warning its line says, the group or lane it stands under, or a formula drawn where every field it reads is. A filter on a field no row shows is refused: make it a column or part of the row\'s line, or drop it. |\n| `list.narrow-unshown` | A narrowing the List `opens` on and a press in a Reading\'s band (a part, a grid cell, a figure\'s `where`) name a field its rows show, as a `filters` entry does (`list.filter-unshown`). A narrowing to the reader needs none. |\n| `list.tiers` | `tiers` band a number read in one unit on every row; a figure read in each row\'s own unit or currency is named bare. |\n| `list.search-undrawn` | *Noted, never refused:* A List\'s `search` matches all of a row\'s text, drawn or not: where a lookup, rollup, copy or link of its rows reads another entity under a row rule the List\'s readers are not all inside, it finds rows by text the List draws none of. |\n| `list.search` | A List\'s `search` names text, a code, or a link \u2014 matched by its row\'s title. |\n| `list.sort` | Each `sort` key of a List or a Tab names a field of the List\'s rows that holds an order \u2014 never files \u2014 and no field twice. |\n| `list.group` | A List\'s `group` names one value per row \u2014 a single select, a one-row link, one member, a date, a yes/no or a text, a lookup through one-row links as the field it reads \u2014 the status too, but never on a task list\'s block, whose chips narrow it; only a table or cards List groups, a gantt into its lanes, and a lanes board of days at one day; grouping by the title needs a `row.subtitle` to lead each row. |\n| `list.readings-own` | A Reading in a List reads the List\'s own entity; another entity\'s stands on a Sheet. |\n| `list.readings-bands` | A Reading in a List that bands a number by `tiers` has that field with the same tiers among the List\'s `filters`, which a press on a band narrows by. |\n| `list.readings-restate` | A Reading with no `by` in a List never sums the row\'s figure, counts the rows, or counts one stage\'s rows, unless it is placed in time (`over`): the summary line and the status chips already do, but draw no change against the last period. Instead, for the summed figure: a mix `by` a field or a sum under a `where`; for the rows counted: a sum of the figure under a `where`, a mix `by` a field or a yes/no in `where`. |\n| `list.where-opens` | A List\'s `where` and `opens` hold a select\'s options, a yes/no\'s value, a number or date\'s bounds (`lte`, `gte`; a date\'s `{ "now": true }`; a number read in each row\'s own unit or currency takes only 0) and `{ "empty": true \\| false }`; `opens` alone names the reader \u2014 a member field or a lookup of one holding `{ "me": true }`, or, on a status whose `stages` have owners, the rows waiting on the reader \u2014 and takes fields only, on the status only options. A field `where` fixes to options is never a filter nor opened otherwise, and `opens` stays among the options `where` keeps. A List laid out as a `plan` keeps its items by options and yes/nos alone. |\n| `list.roster` | A `layout: "roster"` List holds the List of its cells: the cells\' entity has one single link to this one and a date on its line (its own field, or a lookup of its parent\'s date); a roster draws no `columns`, and an `expect` stands only on the cells List. |\n| `list.roster-covers` | `covers` is a whole number from 1, only on a roster\'s cells List over days, never beside an `expect`. |\n| `list.roster-expect` | A roster cells List\'s `expect` is a single select of its rows, and its `of` this entity\'s multi-select whose every option is one of `expect`\'s. |\n| `list.source-page` | A source\'s entity states a Record page in the App\'s `pages`. |\n| `list.band-pivot` | *Noted, never refused:* A Reading with `across` (a grid) among a List\'s Readings: its grid reads on a Sheet, and the band leads with a figure (a Reading with no `by`). |\n| `list.headline` | *Noted by the designer on a write, never refused:* A List over rows that fall due or carry money and have no status whose steps the chips count, laid out as a table, cards or a gantt, has Readings \u2014 they split the rows by a field they show. |\n| `list.figures-lead` | *Noted, never refused:* A root List over a table holding a status, or a money field beside a date, to count or total states a Reading, or a Tab with totals, above its rows: what a person watches, as a figure or a chart. |\n| `list.title-only` | *Noted, never refused:* A root List whose rows draw their title alone: a subtitle, a figure, a status, a deadline, a picture, a face or `columns` says what each row is. |\n| `list.people-undrawn` | *Noted, never refused:* A root List drawn in columns, stating fewer than two besides the figure, where a table whose rows are people links to its table: the paired link holding several of them is not a column of it, or the link is not paired. |\n| `list.layout-call` | *Noted, never refused:* A root List that states no layout, over rows a board layout\'s own resolver resolves (a calendar, a gantt, lanes, or a roster of rows a `cadence` owes), draws a table; the note names each layout and its key. A deadline or a stamped date is never a day rows stand on. |\n| `list.lanes-overlap` | *Noted, never refused:* Lanes of dated rows by a link with no `no_overlap`. |\n| `list.lanes-order` | *Noted, never refused:* Lanes giving rows at a day, whose first ascending `sort` is no stored number the app writes. |\n| `list.where-bound` | A bound read from the record (`{ "record": \u2026 }`) in `where` narrows only a List that reads its rows \u2014 `same`, or `edit: false`. |\n| `list.where-reader` | A root List\'s `opens` names the reader (`{ "me": true }`), never its `where`. Wrong: `where: { crew_lead: { me: true } }` on a child List. Right: a row rule bounds access, or a root List over the entity states `opens: { crew_lead: { me: true } }`. |\n| `list.where-reader-path` | A path reader `<link>.<field>` names a one-row link and a member field of the row it links. |\n| `list.props` | A node states only its place\'s props: a List those of a root List, a roster\'s cells, a rows, agenda, timeline or read-only List of a record (which take every prop of a View but `sources`), a document or a Sheet; the Record of a List that opens no row in place and a source\'s entity page `entity`, `edit` and its children; a Sheet its `key`, `label` and children. |\n| `list.holds` | A List holds what its place draws: a root List its Tabs, Readings, Exports, Acts over ticked rows or every row in view, sources and, under a roster, the List of its cells; a child List its Tabs, Readings, Exports, Acts over ticked rows and, with `under`, the List of its documents; a Sheet its Readings and Lists. An Act on one row and every Check stand in `pages/<entity>`. |\n| `list.layout-place` | The register lays out as a table, cards, a calendar, a roster, a gantt, lanes or a plan; a child List writing its rows as cards (never nested as an outline), a table, checklist, desk or gantt; any child List as an agenda or timeline. |\n| `list.edit-column` | An edit column (`{ "field": \u2026, "edit": true }`) stands in a child List only: the register\'s rows are written where they open. |\n| `list.child-link` | A child List reads a child linked to the record; `via` names the link where the child links more than once. |\n| `list.row-blocks` | A List drawn as lines (`expect`, `under` or a desk) opens no row in place, so no List stands below its rows; a plain list of rows holds one. |\n| `list.title-back` | Where a child\'s title is its link back to the record, its first other `row.subtitle` names it there \u2014 a text, a code, a select, a link or a member, never a number or a date. |\n| `list.where` | A child List\'s `where` names single selects of the child by the options they hold (a row holding none stands in no such List; one held at a single option is never also a column), yes/nos by value, numbers and dates by bounds, and fields by `{ "empty": true \\| false }`. A yes/no, a bound or a blank is never held: a child List adds rows only at a stored yes/no\'s start, none under a bound or a blank, and never picks, expects or stands lines under documents. |\n| `list.under` | `under` names the child\'s one-row link to a document entity that pairs a many-link back and is read under this record by its one link; the lines\' columns never read the document (its heading does) nor hold long text. |\n| `list.under-once` | Documents drawn over their lines (`under`) are never listed again as a List of their own. |\n| `list.edits` | A child List\'s editable columns (`{ "field", "edit": true }`) name at most two of the child\'s columns or its figure that the App\'s saves write \u2014 a number, a date, a few words, one option or a one-row link, never a files or long-text field, the List\'s `via` nor a link it must name alike (a link\'s `same`) \u2014 never on an `expect` List. |\n| `list.remove-roster` | A roster cells List\'s `remove: true` offers the Delete of its rows, so it stands only over rows the App writes. |\n| `list.attention` | `attention: false` keeps a table\'s or cards\' rows in the List\'s own order; a calendar, lanes, a gantt and a roster stand their rows in time and lift none. |\n| `list.remove-documents` | The documents List inside a child List with `under` states `remove: true` only over documents the App writes. |\n| `list.compare` | A child List\'s `compare` names two different fields of the child, `before` and `after`: two files fields, or two values of one type (text but long text, a number, a date, a single select), never with `expect`. Over files on a checklist layout, `before` is the check\'s `photo`. Over values neither side is a column or something the row draws already, two numbers share a notation, no column is long text, and the layout is no checklist. |\n| `list.current` | A child List\'s `current` names a date or number of the child (stored, or a formula) that orders revisions: the latest row is current, the rest fold as superseded. Never with `group`, `under`, `expect`, `checklist`, `compare`, `desk` or `pick`, nor beside a column of long text. |\n| `list.pick` | A child List\'s `pick` links rows of the child through `via` \u2014 an optional one-row link a person writes, no Act writes, no other rule compares rows by and no `under` List stands lines under \u2014 paired with a many-link of the record its own save writes; the child\'s `read_scope` reads a row naming no record through `via`; never with `expect` or `under`, nor where the App\'s saves leave out the child or the many-link. |\n| `list.narrow` | A child List\'s `filters`, `search`, `group` and `sort` follow the register\'s rules over the child\'s rows, its status among them but on a task list (its chips); never on the link back or a select its `where` holds at one option, nor on an `expect` List; an `under` List is grouped by its documents. |\n| `list.expect` | `expect` names the child\'s title \u2014 a single select or a one-row link a person writes, never the link back \u2014 on a child added in the List; its `columns` name a field filled in place (not on a desk, whose lines are ticked) and its `create` takes the file where the child is pictured by one. |\n| `list.expect-fills` | An expected line is made from its key and its first filled column \u2014 a desk\'s from its key alone \u2014 so every other field the child requires has a default, a start or a `default_from`, or is read first. |\n| `list.expect-of` | An `expect` object\'s `of` or `only` needs a select: `of` names the record\'s multi-select of the title\'s options; `only` names options of a single select, never with `of` or a `where` on it, one List per option; an Act\'s `paper` is drawn in one. |\n| `list.post-option` | A desk\'s `text` formula names, as `{field:option}`, only options that select states. |\n| `list.funnel` | A Reading\'s `steps` (a funnel) are 2 to 8 numbers of its child, each named once \u2014 stored, a formula or a rollup \u2014 all in one notation, never a percent nor a unit read on each row. |\n| `list.list` | A read-only child List (`same`, or a Record that is `edit: false`) lists the rows of an entity that link to the record by its one link (`via` where it has several); with `same`, a one-row link of the record, it lists the rows sharing that link\'s row \u2014 the record left out \u2014 by the listed entity\'s one link to that row\'s entity (likewise `via`). `same` stands in a Record, never on a Sheet. Its Record\'s Fields \u2014 at least one, each a field of the listed entity named once, never its title nor a `columns` entry \u2014 are what an opened row shows, read-only. |\n| `list.figures` | A Record\'s own figures (Readings with no `entity` or `by`, whose `value` names the field) are 1 to 8 numbers of the record, each a tile. |\n| `list.create-boolean` | A document\'s and a roster\'s cells\' `create` is `true` or `false`: their add asks the table\'s defaults. |\n| `list.via-path` | A `<link>.<link>` `via` only reads rows, through a row of their own: a List writing its rows lists a child linked to the row it stands under. |\n| `list.beside` | `beside` opens a row beside a table: a root List drawn as a table states it, never a board, cards, a calendar or a List of a record. |\n| `list.create-empty` | A child List stating `create: true` asks the fields of its add (where the table\'s defaults ask none, state `create: false` or those fields); one stating no `create` adds none. |\n| `list.unworked-stage` | *Noted, never refused:* A register lists rows (every open one, else those its `where` keeps) at a stage no Act of the App is offered at and no Section stands at, though the App states the stages it works: keep them out with `where`, or leave them to the App working them. |\n| `list.under-note` | *Noted, never refused:* Rows holding a paper that cover another List\'s lines, listed apart with no add of their own stated: `under` draws them over the lines they cover. |\n| `list.expect-note` | *Noted, never refused:* Rows each a kind of paper, listed with no `expect` and no `where` on the kind, that no Act files a call into or `fills`: the missing lines read as what a record needs. |\n\n<!-- generated:end rules-list -->\n\n## Record rules\n\n<!-- generated:start rules-record -->\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `record.placed-once` | A child List, a Reading, a Statement, Comments and an Act each stand once in a Record; the same block stated in several Sections is that one placement, drawn in the first and said where repeated, and a repeat that differs from the first is refused; a set of papers stands where its Act does. A Field may be stated in several parts: parts that stack draw it once, parts a reader navigates each draw it. The head draws the title, line, picture, status, figure and the nearest open deadline, and a Field of a part standing there stands aside unless a person writes it in the part; what a Side states stands only in the Side. |\n| `record.check-lifted` | *Noted, never refused:* A Check stated inside a part guards the whole record, as one beside the parts does: it stands at the page, and is said. |\n| `record.foot-total` | A child List\'s foot totals the child\'s figure and each summed column over the rows it lists; the record\'s rollup summing that field over those rows (the same `where`) is that foot, never also a Field of a part. |\n| `record.section-holds` | A part without `at` (Section, Side) holds Fields, Fieldsets, child Lists, Readings, Statements, Comments or Acts; a Record\'s one Section stating only a `key` and a `title` is the platform\'s part, which draws the fields, papers and buttons no other part of it draws and is always shown. |\n| `record.platform-part` | *Noted, never refused:* A Section stating no children and no `at` beside a part that states a Field is the platform\'s part of its Record: it draws the fields, papers and buttons no other part of the record draws, and follows the table. |\n| `record.linked` | A link drawn as a block (`block: true`) is a link to one row of a table the App states a Record page of: the row stands in place as that page draws it. |\n| `record.fieldset` | A Fieldset stands in a part, or in a one-part Record, and holds two or more Fields drawn as controls, or Lines of cells \u2014 never a gallery or prose Field (`block`) \u2014 each Field in one Fieldset; an Act in a Fieldset or one of its Lines stands where it is stated, and is refused where its stage puts it at another part: it is stated at that part. |\n| `record.value` | A Value is a formula over fields of the record, computed on the screen and never stored: it names fields the entity holds that are text, numbers, days, yes/nos or single selects, or the one such value a computed field yields, and options its selects hold; it never reads the clock, and states a `notation` only where it yields a number, its currency or unit stated rather than read from a row. |\n| `record.value-held` | *Noted, never refused:* A Value whose formula is that of a formula field of the table computes on one screen what the table already holds for every list, report and export: said, and the field stated in the Line reads the same figure. |\n| `record.parts` | *Noted by the designer on a write, never refused:* A List laid out as a table, cards or a gantt opens a Record whose Sections hold the fields people write, a files Field per paper and the Acts no stage places, a Section per stage the status states (in option order) with the moves offered there at its foot, and a child List per child, a table\'s own rows that belong to a row of it included. |\n| `record.steps` | *Noted by the designer on a write, never refused:* A stage an Act is offered at alone that asks a field or files a paper holds something of its own: on a path (`closed`), its Section stands inside `Steps`. |\n| `record.lists` | *Noted by the designer on a write, never refused:* A table some App records, whose rows other rows each belong to (a one-row link to it, never its status history), draws some of them under its row \u2014 a child List in its Record, a List with `layout` roster or lanes by that link, or an App over them working inside one of its rows at a time (`scope`). |\n| `record.at` | A Section\'s `at` names options of the record\'s status; a record with no status has no steps. |\n| `record.steps-hold` | A Record that states `Steps` states every Section with `at` inside it, never beside it. |\n| `record.steps-path` | `Steps` stands on an entity whose status closes an option (`closed` on `records.status`): a status that closes none is a condition a person sets, and has no path. |\n| `record.edit-declared` | What an App writes of a row is what its Record declares: each Field its Sections state, the table\'s face (`records`: title, line, picture, figure, description) and, where the Record states no part, every field a person writes \u2014 each unless `edit: false` reads it \u2014 beside what an Act requires and a list of child rows its block writes. The head as `row` restates it (each part takes `edit: false`, read and never written), a column, an expected line, a `compare` and a layout\'s move draw a declared field with its control and never declare one: one naming a field no Section declares is refused. A tree stored before the rule rebuilds as it was. |\n| `record.edit-unseated` | *Noted, never refused:* A field of the table\'s face the `row` leaves out of the head, that no Section, column, layout or Act of the App writes, is written nowhere in this App: said, and a Section stating it makes it the App\'s to write. |\n| `record.beside-door` | A Record whose entity a root List opens `beside` its table states no `door`: the rows open beside the table. |\n| `record.key-clash` | A Record\'s List blocks, filed rows and links share one namespace of `key`s: none repeats but the same block stated again (`record.placed-once`), a List\'s default being its table, and a link\'s or a filed field\'s being its alias; a List and a link at one key, or one alias leading to two tables, is refused. Where unkeyed Lists over one entity stand in different Sections of a page, each takes its Section\'s key as its own, unless they are stated alike (one block stated again) or two stand in one Section, which nothing tells apart: those stay unkeyed. |\n| `record.side` | At most one Side stands in a Record, on a page `door`. |\n| `record.history` | No part of a Record reads the entity\'s status history (`status.history`): the rail reads each move. |\n| `record.section-acts` | An Act in a part works on the record itself; an Act over ticked rows or every row in view stands in a List. |\n| `record.move-home` | *Noted, never refused:* A status move offered at one step stands at that step\'s foot when it moves the work forward, to an exit, or back to a step the work passes \u2014 one a row starts at, or one an Act moves the work forward into or on from; one offered at several steps, or moving back into a step the work never passes, stands in the Section whose `at` holds the status it enters, as its way in. A move written in another Section, or in none, stands there and is said. |\n| `record.act-staged` | An Act at a staged Section\'s foot is offered only during that Section\'s steps: its `when` holds the status to options the Section\'s `at` names. A tree\'s Act with no `when` at the foot of a Section staged at one step is offered at that step and said; a correction stays offered at every step, and an exit is refused. |\n| `record.act-hidden` | An Act is never offered only while its part\'s `when` hides the part. |\n| `record.outside-place` | An Outside stands directly in a Record whose table states a stored status select, and its `key` is unique in the App: a link to a record names it. |\n| `record.outside-at` | An Outside\'s `at` names options of the record\'s status that no stage owns, and no two Outsides of a record open during the same option. |\n| `record.outside-field` | An Outside\'s Fields are read as values, each a field of the record shown once, never `edit`, `when` or a label of its own. |\n| `record.outside-list` | An Outside\'s Lists read the child rows under the record as they are: their `columns`, `label` and `where` only, never an add, a Delete, a pick, a filter, a search, a link that opens, or a bound read from the record. |\n| `record.outside-where` | An Outside List\'s `where` keeps the child rows by single selects held at options, yes/nos at values, numbers and dates between bounds, and fields by `{ "empty": \u2026 }`. |\n| `record.outside-act` | An Outside\'s Acts are its alone and each ends the visit: `when` holds the status to `at`, `set` moves it to an option outside `at`, `asks` are text, numbers, dates or listed options, `requires` names fields the Outside shows or the act asks, a `sign` is by a text field with no witness, and none states `on`, `workflow`, `templates`, `paper`, `intake`, `record`, `review`, `danger`, `recommends`, `me` or `confirm: "warnings"`, since a link reads no warnings. |\n| `record.holds` | A Record stands in the App\'s `pages`, once per entity some List of the app or of a Sheet is over, or whose rows a link the app draws names. Every Record holds the same: parts (Section, Side) or the Fields, Fieldsets, Lists, Readings and Statements of its one part, never both; beside either stand Outsides, Checks and Acts on one row; holding only those, the record\'s Sections are the platform\'s. The page of an entity whose rows a child List opens no row of in place (an agenda, a timeline, a read-only List) holds Fields alone. |\n| `record.remove` | A Record\'s `remove` deletes a row opened from a link; an entity a List lists is deleted as that List\'s `remove` says. |\n| `record.field-heading` | A Field drawn as a control states no `label` or `when`: only a gallery or prose Field (`block`) has a heading and a condition. |\n| `record.section-owners` | *Noted, never refused:* A Section holding acts offered at stages that different owners work \u2014 a role apiece, or a member field apiece \u2014 is two jobs in one: each owner\'s part is a Section of its own. |\n| `record.stage-field` | *Noted, never refused:* A field of a record with a status that only Acts offered at some of its stages write \u2014 no `create` asks it, no Field of the page draws it written \u2014 and that a Side or a Section shown at every stage draws, stands empty before those stages: it is stated in a Section `at` them, where it is the work then. |\n| `record.rows-repeated` | *Noted, never refused:* A Record that lists the same rows (a List of one table through one link) in two or more Sections lists them once, in the Section they belong to: a Section is one area of the record\'s data. |\n\n<!-- generated:end rules-record -->\n\n## Act rules\n\n<!-- generated:start rules-act -->\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `act.paper-note` | *Noted, never refused:* A made paper kept in a field of a record that lists its papers by kind: it is one of those lines. |\n| `act.moves` | *Noted by the designer on a write, never refused:* The rows of a root List of the App that a stored status stages towards `closed` options are moved by an Act of the App (on a page, a List or an Outside), or by its authored `workflow` \u2014 each open option moves to the next, the last to the first closed one. |\n| `act.set-not-asked` | A field an Act `set`s (an option, a value, `{ "now": true }`, `{ "me": true }`, an input) or `sign`s is the Act\'s outcome: the App\'s `create` never asks it, and a required one takes a `default`. A `formula` only starts a value, which a person may change after. |\n| `act.owner` | An Act\'s `owner` is a single member field of its row, a one-row link\'s member field (`link.field`), or `{ "group": <id> }` of a group the workspace holds: the press is that owner\'s, or the one standing in for them. An Act handed no row (`review`, `intake`, or over the list asking a person something) has no row to read a member field from, so its owner is a group. |\n| `act.owner-stage` | *Noted, never refused:* An Act that moves no status and is offered while the status holds a stage another member owns is pressed by that stage\'s owner: state its `owner` for someone else to press it. |\n| `act.owner-moves` | An Act stating `owner` moves no row off a stage another owner owns: the server refuses that move to anyone else, so the press would be refused. A move from an option no one owns is fine. |\n| `act.asks-set` | A field an Act `asks`, `set`s or `sign`s is stated by one of them: what the Act writes is its outcome, never also asked, and no field is written by two clauses of one Act. |\n| `act.starts` | `starts` (an ask `{ field, starts }`, or an input\'s own) starts what the Act asks for the reader pressing it, who changes it at will: `"today"` a date or a moment (never a span), `me` a member. |\n| `act.period` | An Act with `on: "period"` stands in a root List whose layout steps a window of days (a calendar or lanes board, not a table or a roster): it is handed the first and last day of the period that window stands on (its day, week or month) as its workflow\'s inputs `from` and `to`, so it asks no input of those names. |\n| `act.set-formula` | `set: { <field>: { formula } }` reads fields of the acted row and computes what the field holds \u2014 a number, a date, text, a yes/no or a single select\'s option (`{field:option}`), typed as the entity\'s own formulas are \u2014 never the status; a bound a write rule holds the field to is checked on the computed value as the Act runs. |\n| `act.set-formula-option` | A `{field:option}` token of a `set` formula names an option that select states. |\n| `act.of` | An Act in a child List works on that child: the one row pressed \u2014 or, with `on: "ticked"`, the rows ticked together where the record lists them as tasks \u2014 never the rows in view, nor none (`on: "none"` and `"period"` stand in a root List of a table). |\n| `act.writes-line-key` | An Act never writes the link or the key naming an expected line under its record \u2014 a line\'s key is stated by filling it. |\n| `act.makes-or-runs` | An Act makes a document (`template`, `templates`) or runs an authored `workflow`, never both \u2014 the workflow makes what it needs. |\n| `act.does-nothing` | An Act does something: it `set`s a value, `asks` a field, runs a `workflow`, makes a document, takes an `intake`, a `record` or a `sign`, or `makes` the rows a cadence owes. |\n| `act.view` | An Act over every row in view (`on: "view"`) writes (`set`), makes a document, runs a workflow or reads papers into a new record, and states no `requires` and no `confirm: "warnings"`, which holds no row in hand to warn. |\n| `act.requires-written` | A field an Act requires that only an Act writes is written by an Act offered together with it, or asked by the Act itself. |\n| `act.recommends` | A field an Act `recommends` is not also in its `requires`. |\n| `act.set` | `set` writes each field a value it holds \u2014 an option alias, a number, a yes/no, a text, `{ "now": true }` on a date, `{ "me": true }` on a member, `{ "input": "<name>" }` of an input the Act asks of the same kind \u2014 or clears an optional one with `null`. |\n| `act.into` | `into` is a files field of the one record the Act is pressed on, beside its `template` or `templates`. |\n| `act.paper-list` | A List a made paper names is one it can list: none keeps its rows by the reader, and no name is reached by a child List that writes its rows and one that only reads them, or by two of either, at once. |\n| `act.paper-list-field` | A List a made paper names is not also a field of the record, other than the link to those rows; an outline\'s rows are handed their depth as `level`, so they hold no field of that name. |\n| `act.paper-loop` | A loop of an html or Word paper that prints a field of each item runs over a link of the record or a table linking to it once (their rows are read under the app\'s row rules), or a List\'s rows \u2014 never over a link inside a child row, or one to rows the app cannot read, which a paper is handed as titles; over several rows an html paper holds the same one level inside `{{#each <alias>}}`, where each row is handed its own lists; a List\'s rows are looped for their fields, never printed whole; a loop runs over a name the paper is handed, never one it is not, which prints an empty table. |\n| `act.paper-cells` | A paper does not draw a cell for each title of a link inside the row of a List it loops over: the titles of a link line up with no column, so a cell packs left under the wrong date. Lay the rows out on a roster and export it, or draw a List. |\n| `act.paper` | `paper` is a kind the record lists its papers by, on one record \u2014 never beside `into` or `templates`; one maker per kind. |\n| `act.templates` | `templates` names each template once, kept in `into`, on one record pressed alone \u2014 never beside `template` or `asks`, in a child List, or with an `on` over several rows. |\n| `act.intake` | `intake` names a child the record lists in a child List with `expect` on its title \u2014 a single select, the paper\'s kind \u2014 and is narrowed by no `where`, holding exactly one files field and needing nothing an added line does not fill; the Act runs on one record (rows it finds by natural key need the link filing them under the record paired), or over the view (`on: "view"`) where the papers make a new record, states `fills`, and states nothing but its `label`, `when` and `requires` beside them \u2014 over the view no `when` or `requires`, the record has no row yet. |\n| `act.record` | `record` names a child the record draws in a timeline List or a child List with no `expect`, `under` or `where`, linking back by one single link, its row needing nothing the recording does not write: `audio` and `video` files fields, `transcript` text, `at` a date, `by` a member, each its own field; on one record, stating only `label`, `when`, `requires` and `fills` beside it. |\n| `act.sign` | `sign` runs on one record: `into` a files field, `by` a text field the signer types or a member field set to the person pressing, `at` a date, `witness` a member field \u2014 stated exactly beside a text `by` \u2014 each a field of its own that the Act does not also ask or set, and no other Act signs into `into`. |\n| `act.fills` | `fills` names each once, only beside `intake` or `record`. Beside `record`: a field of the recording\'s row the recording does not write, never a link. Beside `intake`: a field of the record, `<link>.<field>` on the row a required one-row link names (never beside that link), or a child the record adds rows of in a child List with no `expect`, `under` or `where`, filled in the fields its `create` asks \u2014 every one a new row needs among them. Each field filled is one a person writes \u2014 text, a number, a date, a yes/no, options or a single link\'s row \u2014 never a status, a field an Act writes or a link `same` narrows; a link\'s row is one the App reads of its entity. Over the view the papers make a new record, so `fills` names every field the record requires that nothing fills itself \u2014 the review asks the ones no paper states \u2014 and the row a required one-row link names is found on its entity\'s `natural_key` once `<link>.<field>` fills every field of it, left as it is, else added with the fields filled, so `fills` names each field that row requires too. |\n| `act.fills-drawn` | *Noted, never refused:* A field `fills` writes that the record draws nowhere: the review shows the change, the record does not. |\n| `act.fills-new` | *Noted, never refused:* A child `fills` adds rows of, whose natural key the papers cannot state: every row read is added, so the same papers read twice list them twice. Over the view, so is the row a required link names where the papers fill no natural key of it. |\n| `act.input` | An input has a name of its own \u2014 never another ask\'s, a field the act sends under that name (one it asks, one a `set` takes from an input, a typed `sign.by`, a `requires`), `sign.into`, or the record input its workflow takes (nor `approved` beside `review`) \u2014 `options` exactly when it is a select, `entity` exactly when it is a link, and a `default` field holding what it states, or `starts`, never both. An input starts empty, from its `default` or its `starts`, and never reads, shadows or overwrites a field of the row: an act that adds a subtask may ask `name`, though the row has a `name`. A `"file"` input is read by the Act\'s authored `workflow` alone, starts empty, and is never written into a field by `set`. |\n| `act.review` | `review: true` stands beside an authored `workflow` on an Act over the record, the ticked rows or every row in view (never on a List reading `sources`), never beside `set`, `template`, `templates`, `intake`, `record`, `sign` or `confirm`, nor in a child List, and it asks inputs only, none named `approved`. Its workflow is that Act\'s alone, run by no other Act. The workflow calls only steps that read \u2014 no agent \u2014 and returns a changeset of the entity\'s table in `data.review`, the same for the same inputs and rows; the platform writes the rows `approved` names, each only while the run proposes it as the caller read it. Over every row in view (`on: "view"`) it is handed no rows and states no `when`: its workflow reads the rows it may change, whatever the view is narrowed to, and no bound on a run\'s rows applies. |\n| `act.over` | `over` names a List the record\'s page draws \u2014 in a Record\'s Act or a List\'s `on: "ticked"` Act, never `on: "view"` nor in a child List \u2014 whose entity links to the Act\'s, read through that List\'s one link, `same` and `where` (never one that keeps rows by the reader, nor an outline) and narrowed by `over.when`; the Act states `set` and nothing but `label`, `when`, `requires`, `owner`, `confirm`, `danger` beside it. `set` states fields of the List\'s entity a person writes, each a fixed value, `now`, `me` or an option \u2014 no formula or input \u2014 and every row written is checked as a save of it is \u2014 a `set` of its status as that move on its own row, from-stages and stage owner \u2014 before any is written. Rows the presser\'s row rule hides are not read, and a press reaching more rows than one write takes is refused. |\n| `act.makes` | `makes` names a child that the Act\'s entity states a `cadence` for, in a Record or in a List with `on: "view"` or `"ticked"` that is not a child List; never beside `set`, `workflow`, `template`, `templates`, `intake`, `record`, `sign`, `review` or `of`. The app lists the child\'s rows in a List, and every field of the child that the cadence does not fill and that a row requires has a `default_from`, a `default` or an autonumber, since the app writes the child. The child states a `unique` of its link to the parent and the `planned` date (the day its cadence fills, where the cadence states no `planned`), so two presses at once make a day once, and the cadence states `start` where the child\'s first date holds a moment. |\n| `act.workflow` | An Act\'s authored `workflow` body parses once the guards the Act states are placed above it: the code is the author\'s, the guards above it the platform\'s. A declared Workflow an Act runs takes the row pressed as `record_id` (a required record_link to the act\'s rows), is run by that one Act, over one row, which asks only its inputs and states no `set`, papers, `intake`, `record` or `review`. An authored `workflow` is one Act\'s. Where a Check on the count its issues roll up refuses the Act, the workflow holds the record as one transaction and so cannot mail, notify, run an agent or wait. |\n| `act.set-tagged` | An Act\'s `set` states the moment as `{ "now": true }`, the person pressing as `{ "me": true }` and an input as `{ "input": \u2026 }` \u2014 never the strings `"now"`, `"me"` or `"input:\u2026"`. |\n\n<!-- generated:end rules-act -->\n\n## Template rules\n\nThe rules of the document templates an Act makes and an Export fills.\n\n<!-- generated:start rules-template -->\n\n#### Rules the check enforces\n\n| Rule | |\n|---|---|\n| `template.kind` | An Act\'s `template` is an html, excel or word document template and an Export\'s `template` an html or excel one, never an email or pdf-form one. |\n| `template.marker` | Every marker of a Word template an Act makes is filled by that Act: a field of its entity, or a list of the child rows its record lists (the entity\'s own alias over several rows). |\n| `template.act` | *Noted, never refused:* In an App none of whose Acts runs an authored `workflow`, every html, excel or word template is made by an Act (`template`, `templates`) or filled by an Export \u2014 the note names the app over the table whose fields it prints most, where the Act belongs. |\n\n<!-- generated:end rules-template -->\n\n## What the workspace remembers\n\nThe workspace holds every table, field and select option under an id that never changes, whatever its\nlabel or alias becomes. `set_tables` answers each table\'s id, and an\napp\'s body names tables and templates by those ids, so a relabel on either side is a rename and no body\npoints at another table by accident.\n\nA table `set_tables` refuses to write, or an id the workspace no longer holds, is a refusal by name. `set_tables` with `{ table_id, restore: true }` puts a deleted table back.\n\n## A complete workspace\n\nTwo main entities, so two apps: a sales desk over the orders, where an order is taken and shipped, and an account review\nover the customers, where an account manager reads each customer by tier. What belongs to a row is a child List on that\nrow\'s page, never another app or a Tab: a customer\'s orders are on the customer\'s page, and each order is also a row of\nthe sales desk, one record with one page (`app_architecture`).\n\nOne `set_tables` call makes both tables: each item carries a `ref`, and a link names the table it points\nat by the `ref` of the other item. Its answer carries each table\'s id. One `set_app` call then makes each\napp, `{ "body": \u2026 }`: the tree\'s root names the app by its `key` and `name`, and the tables it uses in `tables` by those ids,\nshown here as placeholders to replace.\n\n```json\n{\n "tables": [\n {\n "ref": "customer",\n "label": "Customers",\n "singular": "Customer",\n "fields": {\n "name": {"label": "Name", "required": true, "type": "text"},\n "logo": {"label": "Logo", "type": "files"},\n "tier": {\n "label": "Tier",\n "default": ["standard"],\n "type": "select",\n "options": [\n {"alias": "standard", "label": "Standard", "color": "slate"},\n {"alias": "gold", "label": "Gold", "color": "amber"}\n ]\n },\n "orders": {"label": "Orders", "type": "link", "pair": "customer", "table": "order", "multi": true},\n "total_ordered": {"label": "Total ordered", "type": "rollup", "via": "orders", "op": "sum", "field": "amount"}\n },\n "title": "name",\n "records": {"image": "logo", "party": "organization", "figure": "total_ordered"}\n },\n {\n "ref": "order",\n "label": "Orders",\n "singular": "Order",\n "fields": {\n "code": {"label": "Order no.", "type": "text", "unique": true},\n "placed_on": {"label": "Placed on", "type": "date", "format": "date"},\n "amount": {"label": "Amount", "type": "number", "notation": {"style": "currency", "currency": "VND"}},\n "total": {\n "label": "Total with VAT",\n "type": "formula",\n "expression": "{amount} * 1.1",\n "notation": {"style": "currency", "currency": "VND"}\n },\n "customer": {"label": "Customer", "type": "link", "pair": "orders", "table": "customer", "multi": false},\n "note": {"label": "Note", "type": "text"},\n "stage": {\n "label": "Stage",\n "default": ["draft"],\n "type": "select",\n "options": [\n {"alias": "draft", "label": "Draft", "color": "slate"},\n {"alias": "confirmed", "label": "Confirmed", "color": "blue"},\n {"alias": "shipped", "label": "Shipped", "color": "green"}\n ]\n }\n },\n "title": "customer",\n "records": {\n "subtitle": ["code", "placed_on"],\n "figure": "amount",\n "status": {"field": "stage", "closed": ["shipped"]},\n "starts": {"placed_on": "today"}\n }\n }\n ]\n}\n```\n\n```json\n{\n "body": {\n "type": "App",\n "key": "account_review",\n "name": "Account review",\n "color": "blue",\n "tables": {"customer": "<id of the customer table>", "order": "<id of the order table>"},\n "templates": {},\n "children": [\n {\n "type": "List",\n "entity": "customer",\n "columns": ["tier"],\n "children": [\n {"type": "Reading", "key": "ordered_by_tier", "by": "tier", "value": "total_ordered"}\n ]\n }\n ],\n "pages": [\n {\n "type": "Record",\n "entity": "customer",\n "children": [\n {"type": "Section", "key": "account", "title": "Account", "children": ["tier"]},\n {\n "type": "Section",\n "key": "orders",\n "title": "Orders",\n "children": [{"type": "List", "entity": "order", "columns": ["total"], "create": ["code", "amount"]}]\n }\n ]\n }\n ]\n }\n}\n```\n\n```json\n{\n "body": {\n "type": "App",\n "key": "sales_desk",\n "name": "Sales desk",\n "color": "violet",\n "tables": {"customer": "<id of the customer table>", "order": "<id of the order table>"},\n "templates": {},\n "children": [\n {\n "type": "List",\n "entity": "order",\n "filters": ["customer"],\n "create": ["code", "customer", "placed_on"],\n "children": [\n {"type": "Reading", "by": "placed_on", "value": "amount"}\n ]\n }\n ],\n "pages": [\n {\n "type": "Record",\n "entity": "order",\n "door": "drawer",\n "children": [\n {\n "type": "Section",\n "key": "order",\n "title": "Order",\n "children": [\n "note",\n {\n "type": "Act",\n "key": "confirm",\n "label": "Confirm",\n "when": {"stage": ["draft"]},\n "set": {"stage": "confirmed"}\n },\n {\n "type": "Act",\n "key": "ship",\n "label": "Ship",\n "when": {"stage": ["confirmed"]},\n "set": {"stage": "shipped"}\n }\n ]\n }\n ]\n }\n ]\n }\n}\n```\n\nThe account review leaves the door a record opens through and the rows it opens in to the system, each the default the\ntable\'s facts give; the sales desk states a drawer. Each List names what its add asks (`create`). The customer\'s orders are a block in its "Orders" section, never its own `Orders`\nlink as a field as well: one fact, one place. An order is titled by its customer and read by its number under it; the\nList names what its add asks, since a subtitle or a figure is never asked by default. `Total ordered` is a rollup, so it\nis read and never asked; the sales desk\'s record opens in a drawer, because its rows are worked one after another. An\norder\'s `stage` is its status (`records.status`), moved only by the app\'s acts: they set it, so the app\'s saves leave it\nout, each act names the stage it is offered at (`when`) and the one it sets, and the register opens on the orders not yet\nshipped (`closed`).\n';
|
|
1887
1887
|
|
|
1888
1888
|
// docs/examples.md
|
|
1889
1889
|
var examples_default = '# Worked examples\n\nEach section is one treatment, cut from a complete workspace of an invented business: the job, the keys to\nread, where the treatment is wrong, and the excerpt \u2014 the app\'s tree, the App node `set_app` takes as `body`,\nwhich the check passes with no finding; the tables it draws as the items of a `set_tables` call, each with its\n`title` and `records`; those tables\' fields it names, by what each holds and how it is drawn; and the templates it makes.\nLeft out, for the page\'s size: a Section or page that carries nothing of the treatment, every `label` and `description` of a table or field, `required`, `min`, `unique`, `default` (a section keeps the ones its **Read** rests on), a link\'s\n`pair`, how a computed field computes, the `tables` and `templates` maps an App adds (ids from the\n`set_tables` answer), and template contents \u2014 a call states each table\'s and field\'s `label`. Choosing\namong them: the `design` reference. Every key: `reference`, at the pages each section names under\n**Keys**. How a record\'s status draws is a choice of its own, made by what the work is (`design`, Stages):\neach section says which its record takes under **Its stages**, so the form is copied with its reason.\n\n## Calendar\n\n**The job.** Book visits on the days they happen, and see a week\'s work at a glance.\n\n**Read.** `layout: "calendar"` on the List; each visit stands from `scheduled_for` over its span to `ends_at`, the two `required` moments of its facts (`ends_at` is ordered after `scheduled_for` by its `min`); a keyed calendar names the date and the end itself.\n\n**Keys.** `reference/calendar`\n\n**Not when.** Rows booked on a resource that two may not share at once \u2014 that is `lanes`. Rows with a date nobody plans by (an invoice\'s date) stay a table.\n\n**Its stages.** `service_visit` states Sections at its stages: its path reads down the page, each stage\'s Section under its step.\n\n```json\n{\n "tables": [\n {\n "ref": "service_visit",\n "title": "customer",\n "fields": {\n "customer": {"required": true, "type": "link", "table": "customer", "multi": false},\n "scheduled_for": {"required": true, "type": "date", "format": "datetime"},\n "ends_at": {"required": true, "type": "date", "format": "datetime", "min": "scheduled_for"},\n "engineer": {"type": "link", "table": "engineer", "multi": false},\n "job": {\n "required": true,\n "type": "select",\n "options": [{"alias": "inspection", "color": "sky"}, {"alias": "repair", "color": "orange"}]\n },\n "stage": {\n "type": "select",\n "options": [\n {"alias": "booked_on", "color": "blue"},\n {"alias": "parts_ready_on", "color": "blue"},\n {"alias": "arrived_on", "color": "blue"},\n {"alias": "completed_on", "color": "green"}\n ]\n },\n "booked_on": {"type": "date"},\n "parts_ready_on": {"type": "date"},\n "arrived_on": {"type": "date"},\n "hours": {"type": "number", "notation": {"style": "unit", "unit": "h"}},\n "report": {"type": "text", "format": "markdown"},\n "completed_on": {"type": "date"}\n },\n "records": {\n "subtitle": ["scheduled_for", "ends_at"],\n "figure": "hours",\n "due": ["scheduled_for"],\n "status": {\n "field": "stage",\n "closed": ["completed_on"],\n "dates": {\n "booked_on": "booked_on",\n "parts_ready_on": "parts_ready_on",\n "arrived_on": "arrived_on",\n "completed_on": "completed_on"\n }\n }\n }\n }\n ],\n "body": {\n "type": "App",\n "key": "visits",\n "name": "Service visits",\n "icon": "calendar",\n "color": "emerald",\n "rows": {\n "customer": {"any": [{"member_of": "sales"}]},\n "order": {"any": [{"member_of": "sales"}, {"member_of": "stores"}]},\n "order_line": {"any": [{"member_of": "sales"}, {"member_of": "stores"}]},\n "payment": {"any": [{"member_of": "sales"}, {"member_of": "stores"}]},\n "service_visit": {"any": [{"member_of": "sales"}, {"member_of": "stores"}, {"member_of": "field"}]}\n },\n "children": [\n {\n "type": "List",\n "entity": "service_visit",\n "columns": ["engineer", "job"],\n "filters": ["customer"],\n "sort": {"field": "scheduled_for"},\n "layout": "calendar",\n "create": ["customer", "job", "scheduled_for", "ends_at", "engineer"],\n "children": [\n {"type": "Reading", "key": "register_reading_0", "label": "Repairs", "where": {"job": ["repair"]}},\n {"type": "Reading", "key": "register_reading_1", "value": "hours", "by": "engineer"}\n ]\n }\n ],\n "pages": [\n {\n "type": "Record",\n "entity": "service_visit",\n "children": [\n {\n "type": "Steps",\n "children": [\n {\n "type": "Section",\n "key": "visit",\n "title": "Visit",\n "at": ["booked_on", "parts_ready_on"],\n "children": [\n "job",\n "booked_on",\n "parts_ready_on",\n {\n "type": "Act",\n "key": "reschedule",\n "label": "Reschedule",\n "asks": ["scheduled_for", "ends_at"],\n "when": {"stage": ["booked_on", "parts_ready_on"]}\n },\n {\n "type": "Act",\n "key": "to_booked_on",\n "label": "Booked",\n "when": {"stage": {"empty": true}},\n "asks": [{"field": "booked_on", "starts": "today"}],\n "set": {"stage": "booked_on"}\n },\n {\n "type": "Act",\n "key": "to_parts_ready_on",\n "label": "Parts ready",\n "when": {"stage": ["booked_on"], "job": ["repair"]},\n "asks": [{"field": "parts_ready_on", "starts": "today"}],\n "set": {"stage": "parts_ready_on"}\n },\n {\n "type": "Act",\n "key": "to_arrived_on",\n "label": "On site",\n "when": {"stage": ["booked_on"], "job": ["inspection"]},\n "asks": [{"field": "arrived_on", "starts": "today"}],\n "set": {"stage": "arrived_on"}\n },\n {\n "type": "Act",\n "key": "to_arrived_on_2",\n "label": "On site",\n "when": {"stage": ["parts_ready_on"]},\n "asks": [{"field": "arrived_on", "starts": "today"}],\n "set": {"stage": "arrived_on"}\n }\n ]\n },\n {\n "type": "Section",\n "key": "report",\n "title": "Report",\n "at": ["arrived_on"],\n "children": [\n "engineer",\n "arrived_on",\n {"field": "report", "block": false},\n {\n "type": "Act",\n "key": "complete",\n "label": "Complete visit",\n "requires": ["engineer"],\n "asks": [\n "hours",\n {"input": "summary", "label": "What was done", "type": "long_text", "required": true}\n ],\n "set": {"report": {"input": "summary"}, "stage": "completed_on"},\n "when": {"stage": ["arrived_on"]}\n },\n {\n "type": "Act",\n "key": "clear_visit_hours",\n "label": "Clear hours",\n "set": {"hours": null},\n "confirm": true\n }\n ]\n }\n ]\n }\n ]\n },\n {"type": "Record", "entity": "warehouse", "add": ["name", "city"]},\n {"type": "Record", "entity": "engineer", "add": ["name", "base"]},\n {"type": "Record", "entity": "customer", "add": ["name", "credit_limit"]}\n ]\n }\n}\n```\n\n## Lanes\n\n**The job.** Put each service visit on an engineer\'s day by the hour, and see at once who is free between visits.\n\n**Read.** `layout` `lanes` with `by` naming the one-row link to the resource (the engineer); every engineer stands as a lane, empty or not.\n\n**Keys.** `reference/lanes`\n\n**Not when.** The resource is not a row of the model (a free-text room name), or rows never compete for one \u2014 a `calendar` reads them by day.\n\n**Its stages.** `service_visit` states no Section at a stage and its Acts move it: its path draws as a line of steps across the page.\n\n```json\n{\n "tables": [\n {\n "ref": "service_visit",\n "title": "customer",\n "fields": {\n "customer": {"type": "link", "table": "customer", "multi": false},\n "scheduled_for": {"type": "date", "format": "datetime"},\n "ends_at": {"type": "date", "format": "datetime"},\n "engineer": {"type": "link", "table": "engineer", "multi": false},\n "job": {\n "type": "select",\n "options": [{"alias": "inspection", "color": "sky"}, {"alias": "repair", "color": "orange"}]\n },\n "stage": {\n "type": "select",\n "options": [\n {"alias": "booked_on", "color": "blue"},\n {"alias": "parts_ready_on", "color": "blue"},\n {"alias": "arrived_on", "color": "blue"},\n {"alias": "completed_on", "color": "green"}\n ]\n },\n "booked_on": {"type": "date"},\n "parts_ready_on": {"type": "date"},\n "arrived_on": {"type": "date"},\n "hours": {"type": "number", "notation": {"style": "unit", "unit": "h"}},\n "completed_on": {"type": "date"},\n "length": {"type": "formula", "notation": {"style": "unit", "unit": "h"}}\n },\n "records": {\n "subtitle": ["scheduled_for", "ends_at"],\n "figure": "hours",\n "due": ["scheduled_for"],\n "status": {\n "field": "stage",\n "closed": ["completed_on"],\n "dates": {\n "booked_on": "booked_on",\n "parts_ready_on": "parts_ready_on",\n "arrived_on": "arrived_on",\n "completed_on": "completed_on"\n }\n }\n }\n },\n {\n "ref": "engineer",\n "title": "name",\n "fields": {\n "name": {"type": "text"},\n "base": {"type": "link", "table": "warehouse", "multi": false},\n "day_hours": {"type": "number", "notation": {"style": "unit", "unit": "h"}}\n },\n "records": {"subtitle": ["base"], "party": "person"}\n }\n ],\n "body": {\n "type": "App",\n "key": "dispatch",\n "name": "Dispatch",\n "icon": "wrench",\n "color": "sky",\n "rows": {\n "customer": {"any": [{"member_of": "sales"}]},\n "order": {"any": [{"member_of": "sales"}, {"member_of": "stores"}]},\n "order_line": {"any": [{"member_of": "sales"}, {"member_of": "stores"}]},\n "payment": {"any": [{"member_of": "sales"}, {"member_of": "stores"}]},\n "service_visit": {"any": [{"member_of": "sales"}, {"member_of": "stores"}, {"member_of": "field"}]}\n },\n "children": [\n {\n "type": "List",\n "entity": "service_visit",\n "columns": ["job"],\n "search": ["customer"],\n "layout": {"lanes": {"by": "engineer", "loads": {"length": "day_hours"}}},\n "create": ["engineer", "scheduled_for", "ends_at", "customer", "job"]\n }\n ],\n "pages": [\n {\n "type": "Record",\n "entity": "service_visit",\n "children": [\n {\n "type": "Section",\n "key": "booking",\n "title": "Booking",\n "children": [\n "engineer",\n "job",\n "hours",\n {\n "type": "Act",\n "key": "to_booked_on",\n "label": "Booked",\n "when": {"stage": {"empty": true}},\n "asks": [{"field": "booked_on", "starts": "today"}],\n "set": {"stage": "booked_on"}\n },\n {\n "type": "Act",\n "key": "to_parts_ready_on",\n "label": "Parts ready",\n "when": {"stage": ["booked_on"], "job": ["repair"]},\n "asks": [{"field": "parts_ready_on", "starts": "today"}],\n "set": {"stage": "parts_ready_on"}\n },\n {\n "type": "Act",\n "key": "to_arrived_on",\n "label": "On site",\n "when": {"stage": ["booked_on"], "job": ["inspection"]},\n "asks": [{"field": "arrived_on", "starts": "today"}],\n "set": {"stage": "arrived_on"}\n },\n {\n "type": "Act",\n "key": "to_arrived_on_2",\n "label": "On site",\n "when": {"stage": ["parts_ready_on"]},\n "asks": [{"field": "arrived_on", "starts": "today"}],\n "set": {"stage": "arrived_on"}\n },\n {\n "type": "Act",\n "key": "to_completed_on",\n "label": "Completed",\n "when": {"stage": ["arrived_on"]},\n "asks": [{"field": "completed_on", "starts": "today"}],\n "set": {"stage": "completed_on"}\n }\n ]\n }\n ],\n "row": {\n "subtitle": [{"field": "scheduled_for", "edit": false}, {"field": "ends_at", "edit": false}],\n "figure": false\n }\n },\n {"type": "Record", "entity": "warehouse", "add": ["name", "city"]},\n {"type": "Record", "entity": "engineer", "add": ["name", "base"]},\n {"type": "Record", "entity": "customer", "add": ["name", "credit_limit"]}\n ]\n }\n}\n```\n\n## Gantt\n\n**The job.** Read every hire as a bar from the day the machine goes out to the day it is due back, against today.\n\n**Read.** `layout` `gantt` with its `start`; with no end stated, the bar ends at the entity\'s first `due`. The day a hire comes back (`ngay_tra`) is stamped by the status\'s `dates`, so no act sets it.\n\n**Keys.** `reference/gantt`\n\n**Not when.** Rows that last a day or less (a visit, a shift) \u2014 `calendar` or `lanes`; a plan with no dates set yet.\n\n**Its stages.** `phieu_thue` states Sections at its stages: its path reads down the page, each stage\'s Section under its step.\n\n```json\n{\n "tables": [\n {\n "ref": "phieu_thue",\n "title": "khach_hang",\n "fields": {\n "khach_hang": {"type": "link", "table": "khach_hang", "multi": false},\n "so_phieu": {"type": "text"},\n "trang_thai": {\n "type": "select",\n "options": [\n {"alias": "moi", "color": "slate"},\n {"alias": "dang_thue", "color": "blue"},\n {"alias": "da_tra", "color": "green"},\n {"alias": "huy", "color": "gray"}\n ]\n },\n "phu_trach": {"type": "member"},\n "ngay_giao": {"type": "date"},\n "han_tra": {"type": "date"},\n "ngay_tra": {"type": "date"},\n "tinh_trang_tra": {\n "type": "select",\n "options": [\n {"alias": "tot", "color": "green"},\n {"alias": "tray_xuoc", "color": "amber"},\n {"alias": "hu_hong", "color": "red"}\n ]\n },\n "so_ngay": {"type": "formula"},\n "tong_tien": {"type": "rollup"}\n },\n "records": {\n "subtitle": ["so_phieu"],\n "figure": "tong_tien",\n "due": ["han_tra"],\n "status": {"field": "trang_thai", "closed": ["da_tra", "huy"], "dates": {"da_tra": "ngay_tra"}}\n }\n }\n ],\n "body": {\n "type": "App",\n "key": "tien_do_thue",\n "name": "Ti\u1EBFn \u0111\u1ED9 cho thu\xEA",\n "icon": "calendar-range",\n "color": "teal",\n "children": [\n {\n "type": "List",\n "entity": "phieu_thue",\n "columns": ["phu_trach"],\n "filters": ["phu_trach", "khach_hang"],\n "layout": {"gantt": {"start": "ngay_giao"}},\n "create": false,\n "remove": false\n }\n ],\n "pages": [\n {\n "type": "Record",\n "entity": "phieu_thue",\n "children": [\n {\n "type": "Section",\n "key": "phieu_thue",\n "title": "Phi\u1EBFu thu\xEA",\n "children": ["ngay_giao", "han_tra"]\n },\n {\n "type": "Steps",\n "children": [\n {\n "type": "Section",\n "key": "dang_thue",\n "title": "\u0110ang thu\xEA",\n "at": ["dang_thue"],\n "children": [\n "so_ngay",\n {"field": "ngay_tra", "edit": false},\n {\n "type": "Act",\n "key": "nhan_tra",\n "label": "Nh\u1EADn m\xE1y tr\u1EA3",\n "when": {"trang_thai": ["dang_thue"]},\n "asks": ["tinh_trang_tra"],\n "set": {"trang_thai": "da_tra"},\n "confirm": true\n },\n {\n "type": "Act",\n "key": "mo_lai",\n "label": "M\u1EDF l\u1EA1i",\n "when": {"trang_thai": ["da_tra"]},\n "set": {"trang_thai": "dang_thue"},\n "confirm": true\n }\n ]\n }\n ]\n }\n ]\n }\n ]\n }\n}\n```\n\n## Roster\n\n**The job.** See who works which shift on each day of the week or the month.\n\n**Read.** `layout: "roster"` over the people; the child List (`lich_truc`) is the rows that fill the days \u2014 one link back and a date on its line.\n\n**Keys.** `reference/roster`\n\n**Not when.** Rows that are themselves the bookings (a stay over several days) \u2014 a `calendar` or `lanes` draws them; a roster\'s row is what the days are filled for.\n\n```json\n{\n "tables": [\n {\n "ref": "nha_si",\n "title": "ho_ten",\n "fields": {\n "ho_ten": {"type": "text"},\n "chuyen_mon": {\n "type": "select",\n "options": [\n {"alias": "tong_quat", "color": "blue"},\n {"alias": "chinh_nha", "color": "purple"},\n {"alias": "nha_chu", "color": "green"},\n {"alias": "phuc_hinh", "color": "orange"}\n ]\n },\n "dien_thoai": {"type": "text"},\n "ngay_lam": {\n "type": "select",\n "options": [\n {"alias": "mon", "color": "blue"},\n {"alias": "tue", "color": "blue"},\n {"alias": "wed", "color": "blue"},\n {"alias": "thu", "color": "blue"},\n {"alias": "fri", "color": "blue"},\n {"alias": "sat", "color": "blue"},\n {"alias": "sun", "color": "blue"}\n ],\n "multi": true\n },\n "tu_ngay": {"type": "date"}\n },\n "records": {\n "subtitle": ["chuyen_mon"],\n "party": "person",\n "cadence": [{"entity": "lich_truc", "on": "ngay_lam", "from": "tu_ngay", "planned": "ke_hoach"}]\n }\n },\n {\n "ref": "lich_truc",\n "title": "ca",\n "fields": {\n "nha_si": {"type": "link", "table": "nha_si", "multi": false},\n "ca": {\n "type": "select",\n "options": [\n {"alias": "sang", "color": "blue"},\n {"alias": "chieu", "color": "purple"},\n {"alias": "ca_ngay", "color": "green"},\n {"alias": "nghi", "color": "gray"}\n ]\n },\n "ngay": {"type": "date"},\n "ghe": {"type": "link", "table": "ghe", "multi": false},\n "ke_hoach": {"type": "date"}\n },\n "records": {"subtitle": ["ngay", "ghe"], "mark": "ca"}\n }\n ],\n "body": {\n "type": "App",\n "key": "lich_truc",\n "name": "L\u1ECBch tr\u1EF1c",\n "icon": "users",\n "color": "indigo",\n "children": [\n {\n "type": "List",\n "entity": "nha_si",\n "filters": ["chuyen_mon"],\n "layout": "roster",\n "create": ["ho_ten", "chuyen_mon", "dien_thoai"],\n "children": [\n {"type": "List", "entity": "lich_truc", "create": true, "remove": true},\n {"type": "Act", "key": "tao_ca_truc_ds", "label": "T\u1EA1o ca tr\u1EF1c", "on": "view", "makes": "lich_truc"},\n {\n "type": "Export",\n "key": "lich_truc_thang",\n "label": "L\u1ECBch tr\u1EF1c th\xE1ng",\n "template": "lich_truc_thang"\n }\n ]\n }\n ],\n "pages": [\n {\n "type": "Record",\n "entity": "nha_si",\n "children": [\n {\n "type": "Section",\n "key": "lich_tuan",\n "title": "L\u1ECBch tr\u1EF1c m\u1ED7i tu\u1EA7n",\n "children": [\n "ngay_lam",\n "tu_ngay",\n {"type": "Act", "key": "tao_ca_truc", "label": "T\u1EA1o ca tr\u1EF1c", "makes": "lich_truc"}\n ]\n }\n ]\n },\n {"type": "Record", "entity": "lich_truc"},\n {"type": "Record", "entity": "ghe", "add": ["ten", "phong"]}\n ]\n }\n}\n```\n\n## Cards\n\n**The job.** Find an item by its picture, and count what the shelf holds.\n\n**Read.** `layout: "cards"` over rows whose `records.image` is a photo; `scope` keeps the app inside one warehouse at a time.\n\n**Keys.** `reference/cards`, `reference/records`, `reference/app-node`\n\n**Not when.** Rows with no picture \u2014 cards of words are a table drawn worse.\n\n```json\n{\n "tables": [\n {\n "ref": "stock_item",\n "title": "name",\n "fields": {\n "name": {"type": "text"},\n "warehouse": {"type": "link", "table": "warehouse", "multi": false},\n "photo": {"type": "files"},\n "sku": {"type": "text"},\n "category": {\n "type": "select",\n "options": [\n {"alias": "pumps", "color": "blue"},\n {"alias": "valves", "color": "teal"},\n {"alias": "seals", "color": "amber"},\n {"alias": "motors", "color": "violet"}\n ]\n },\n "on_hand": {"type": "number"},\n "minimum": {"type": "number"},\n "price": {"type": "number", "notation": {"style": "currency", "currency": "USD"}},\n "supplier_page": {"type": "text", "format": "link"},\n "last_counted": {"type": "date"},\n "counted_by": {"type": "member"},\n "count_note": {"type": "text"}\n },\n "records": {\n "subtitle": ["sku", "category"],\n "image": "photo",\n "figure": "on_hand",\n "limits": {"on_hand": 400},\n "gates": {"on_hand": "minimum"}\n }\n },\n {\n "ref": "order_line",\n "title": "item",\n "fields": {\n "item": {"type": "link", "table": "stock_item", "multi": false},\n "order": {"type": "link", "table": "order", "multi": false},\n "quantity": {"type": "number"},\n "shipped": {"type": "number"},\n "picked": {"type": "number"},\n "unit_price": {"type": "number", "notation": {"style": "currency", "currency": "USD"}},\n "amount": {"type": "formula", "notation": {"style": "currency", "currency": "USD"}},\n "settled": {"type": "formula"},\n "category": {"type": "lookup"}\n },\n "records": {\n "subtitle": ["order", "unit_price"],\n "figure": "amount",\n "limits": {"shipped": "quantity", "picked": "quantity"}\n }\n }\n ],\n "body": {\n "type": "App",\n "key": "stock",\n "name": "Stock",\n "icon": "boxes",\n "color": "teal",\n "rows": {\n "customer": {"any": [{"member_of": "sales"}]},\n "order": {"any": [{"member_of": "sales"}, {"member_of": "stores"}]},\n "order_line": {"any": [{"member_of": "sales"}, {"member_of": "stores"}]},\n "payment": {"any": [{"member_of": "sales"}, {"member_of": "stores"}]}\n },\n "scope": "warehouse",\n "children": [\n {\n "type": "List",\n "entity": "stock_item",\n "filters": ["on_hand"],\n "search": ["name", "sku"],\n "layout": "cards",\n "children": [\n {"type": "Reading", "key": "register_reading_0", "value": "on_hand", "by": "category"},\n {"type": "Export", "key": "export"}\n ]\n }\n ],\n "pages": [\n {\n "type": "Record",\n "entity": "stock_item",\n "children": [\n {\n "type": "Section",\n "key": "item",\n "title": "Item",\n "children": ["price", "minimum", "supplier_page"]\n },\n {\n "type": "Section",\n "key": "last_count",\n "title": "Last count",\n "children": [\n "last_counted",\n "counted_by",\n "count_note",\n {\n "type": "Act",\n "key": "count",\n "label": "Count stock",\n "asks": [\n {"input": "counted", "label": "Units on the shelf", "type": "number", "required": true},\n {"input": "remark", "label": "Remark", "type": "long_text"}\n ],\n "set": {\n "on_hand": {"input": "counted"},\n "last_counted": {"now": true},\n "counted_by": {"me": true},\n "count_note": {"input": "remark"}\n }\n }\n ]\n },\n {\n "type": "Section",\n "key": "on_order",\n "title": "On order",\n "children": [{"type": "List", "entity": "order_line"}]\n }\n ]\n },\n {\n "type": "Record",\n "entity": "order_line",\n "children": ["quantity", "shipped", {"type": "Check", "field": "settled", "on": ["update"]}]\n },\n {"type": "Record", "entity": "customer", "add": ["name", "credit_limit"]}\n ]\n }\n}\n```\n\n## Party\n\n**The job.** Keep each customer account \u2014 who they are, what they ordered, what was said to them.\n\n**Read.** `records.customer.party: "organization"` and its `image` (the logo); a List with `layout: "timeline"` for the touches, a Reading `by` the day placed for its orders, and its papers `expect`ed by kind.\n\n**Keys.** `reference/records`, `reference/layouts`, `reference/list-node`, `reference/reading-node`\n\n**Not when.** A list of customers is not a job by itself: the customer is a link on the desk whose rows name it, unless the job is the account itself.\n\n**Its stages.** `order` states no Section at a stage and its Acts move it: its path draws as a line of steps across the page.\n\n```json\n{\n "tables": [\n {\n "ref": "customer",\n "title": "name",\n "fields": {\n "name": {"type": "text"},\n "logo": {"type": "files"},\n "code": {"type": "text"},\n "tier": {\n "type": "select",\n "options": [\n {"alias": "key", "color": "violet"},\n {"alias": "standard", "color": "sky"},\n {"alias": "lapsed", "color": "gray"}\n ]\n },\n "phone": {"type": "text"},\n "website": {"type": "text", "format": "link"},\n "account_manager": {"type": "member"},\n "credit_limit": {"type": "number", "notation": {"style": "currency", "currency": "USD"}},\n "orders": {"type": "link", "table": "order", "multi": true},\n "outstanding": {"type": "rollup"},\n "papers_needed": {\n "type": "select",\n "options": [\n {"alias": "credit_application", "color": "blue"},\n {"alias": "trade_reference", "color": "violet"},\n {"alias": "vat_certificate", "color": "teal"}\n ],\n "multi": true\n },\n "notes": {"type": "text", "format": "markdown"}\n },\n "records": {\n "subtitle": ["tier"],\n "image": "logo",\n "party": "organization",\n "figure": "outstanding",\n "limits": {"outstanding": "credit_limit"}\n }\n },\n {\n "ref": "order",\n "title": "reference",\n "fields": {\n "customer": {"type": "link", "table": "customer", "multi": false},\n "reference": {"type": "text"},\n "stage": {\n "type": "select",\n "options": [\n {"alias": "draft", "color": "slate"},\n {"alias": "confirmed", "color": "blue"},\n {"alias": "picking", "color": "amber"},\n {"alias": "shipped", "color": "indigo"},\n {"alias": "received", "color": "green"},\n {"alias": "cancelled", "color": "rose"}\n ]\n },\n "placed": {"type": "date"},\n "due_date": {"type": "date"},\n "handler": {"type": "member"},\n "priority": {"type": "boolean"},\n "lines": {"type": "link", "table": "order_line", "multi": true},\n "payments": {"type": "link", "table": "payment", "multi": true},\n "total": {"type": "rollup"},\n "balance": {"type": "formula", "notation": {"style": "currency", "currency": "USD"}},\n "units_ordered": {"type": "rollup"},\n "units_shipped": {"type": "rollup"},\n "units_picked": {"type": "rollup"},\n "carrier": {"type": "text"},\n "tracking_no": {"type": "text"},\n "shipped_on": {"type": "date"},\n "cancellation_reason": {"type": "text"},\n "cancelled_by": {"type": "member"},\n "replaced_by": {"type": "link", "table": "order", "multi": false},\n "attachments": {"type": "files"},\n "delivery_note": {"type": "files"},\n "notes": {"type": "text", "format": "markdown"},\n "paid_in_full": {"type": "formula"},\n "reminder_ref": {"type": "text"}\n },\n "records": {\n "subtitle": ["customer", "placed"],\n "figure": "total",\n "limits": {"units_shipped": "units_ordered", "units_picked": "units_ordered"},\n "due": ["due_date"],\n "status": {\n "field": "stage",\n "closed": ["received", "cancelled"],\n "dates": {"shipped": "shipped_on"},\n "history": "order_stage"\n }\n }\n },\n {\n "ref": "customer_paper",\n "title": "kind",\n "fields": {\n "kind": {\n "type": "select",\n "options": [\n {"alias": "credit_application", "color": "blue"},\n {"alias": "trade_reference", "color": "violet"},\n {"alias": "vat_certificate", "color": "teal"}\n ]\n },\n "customer": {"type": "link", "table": "customer", "multi": false},\n "received_on": {"type": "date"},\n "file": {"type": "files"}\n },\n "records": {"image": "file"}\n },\n {\n "ref": "touch",\n "title": "said",\n "fields": {\n "said": {"type": "text"},\n "customer": {"type": "link", "table": "customer", "multi": false},\n "on": {"type": "date"},\n "by": {"type": "member"}\n }\n }\n ],\n "body": {\n "type": "App",\n "key": "customers",\n "name": "Customers",\n "icon": "users",\n "color": "violet",\n "rows": {\n "customer": {"any": [{"member_of": "sales"}]},\n "order": {"any": [{"member_of": "sales"}, {"member_of": "stores"}]},\n "order_line": {"any": [{"member_of": "sales"}, {"member_of": "stores"}]},\n "payment": {"any": [{"member_of": "sales"}, {"member_of": "stores"}]},\n "touch": {"any": [{"member_of": "sales"}]},\n "customer_paper": {"any": [{"member_of": "sales"}]},\n "service_visit": {"any": [{"member_of": "sales"}, {"member_of": "stores"}, {"member_of": "field"}]}\n },\n "children": [\n {\n "type": "List",\n "entity": "customer",\n "columns": ["phone", "account_manager"],\n "filters": ["account_manager"],\n "sort": {"field": "name"},\n "opens": {"tier": ["key", "standard"]},\n "create": ["name", "code", "credit_limit"],\n "children": [{"type": "Reading", "key": "register_reading_1", "value": "outstanding", "by": "account_manager"}]\n }\n ],\n "pages": [\n {\n "type": "Record",\n "entity": "customer",\n "door": "drawer",\n "children": [\n {"type": "Section", "key": "contact", "title": "Contact", "children": ["phone", "website"]},\n {\n "type": "Section",\n "key": "account",\n "title": "Account",\n "children": [\n "code",\n "account_manager",\n "credit_limit",\n {\n "type": "Act",\n "key": "reassign",\n "label": "Reassign",\n "asks": [{"input": "to", "label": "Account manager", "type": "member", "required": true}],\n "set": {"account_manager": {"input": "to"}}\n },\n {\n "type": "Act",\n "key": "lapse",\n "label": "Mark lapsed",\n "when": {"tier": ["key", "standard"]},\n "set": {"tier": "lapsed"},\n "confirm": true\n },\n {\n "type": "Act",\n "key": "reinstate",\n "label": "Reinstate",\n "when": {"tier": ["lapsed"]},\n "asks": [\n {\n "input": "back_to",\n "label": "Back to",\n "type": "select",\n "options": [\n {\n "alias": "key",\n "label": "Key account",\n "color": "violet",\n "mark": {"kind": "icon", "name": "building-2"}\n },\n {"alias": "standard", "label": "Standard", "color": "sky"}\n ],\n "required": true\n }\n ],\n "set": {"tier": {"input": "back_to"}}\n }\n ]\n },\n {\n "type": "Section",\n "key": "orders",\n "title": "Orders",\n "children": [\n {\n "type": "Reading",\n "key": "block_reading_0",\n "label": "Order value",\n "entity": "order",\n "value": "total",\n "where": {"stage": ["confirmed", "picking", "shipped", "received"]},\n "by": "placed"\n },\n {\n "type": "List",\n "entity": "order",\n "where": {"stage": ["draft", "confirmed", "picking", "shipped"]},\n "label": "Open orders",\n "columns": ["due_date"],\n "create": false\n },\n {\n "type": "List",\n "key": "order_2",\n "entity": "order",\n "where": {"stage": ["shipped", "received"], "paid_in_full": false},\n "label": "Shipped, still owed",\n "columns": ["balance"],\n "create": false\n },\n {\n "type": "List",\n "key": "block_reading_3",\n "entity": "service_visit",\n "columns": ["engineer", "job"],\n "edit": false\n }\n ]\n },\n {\n "type": "Section",\n "key": "account_papers",\n "title": "Account papers",\n "children": [\n {\n "type": "List",\n "entity": "customer_paper",\n "expect": {"field": "kind", "of": "papers_needed"},\n "columns": ["received_on"]\n }\n ]\n },\n {\n "type": "Section",\n "key": "contact_log",\n "title": "Contact log",\n "children": [{"type": "List", "entity": "touch", "layout": "timeline"}]\n },\n {"type": "Section", "key": "notes", "title": "Notes", "children": ["notes"]}\n ]\n },\n {\n "type": "Record",\n "entity": "order",\n "children": [\n "due_date",\n "handler",\n {"field": "priority", "edit": false},\n "lines",\n "payments",\n {"field": "carrier", "edit": false},\n {"field": "tracking_no", "edit": false},\n {"field": "shipped_on", "edit": false},\n {"field": "cancellation_reason", "edit": false},\n {"field": "cancelled_by", "edit": false},\n {"field": "replaced_by", "edit": false},\n {"field": "attachments", "edit": false},\n "delivery_note",\n "notes",\n {"field": "reminder_ref", "edit": false},\n {"type": "Check", "field": "paid_in_full", "on": ["update"]}\n ]\n },\n {"type": "Record", "entity": "warehouse", "add": ["name", "city"]},\n {"type": "Record", "entity": "stock_item", "add": ["name", "warehouse", "sku", "category"]},\n {"type": "Record", "entity": "order_line", "add": ["item", "quantity"]}\n ]\n }\n}\n```\n\n## Case\n\n**The job.** Gather an applicant\'s papers into one case, make the forms it needs, and file it on time.\n\n**Read.** Lists with `expect` for the papers brought (one line per kind, the missing ones empty), an Act\'s `templates` for the forms made (ticked and made at once, kept in `into`), and `intake` reading the papers brought.\n\n**Keys.** `reference/list-node`, `reference/act-node`\n\n**Not when.** A record that needs no papers, or one paper made once \u2014 a single `template` act.\n\n**Its stages.** `ho_so` states Sections at its stages: its path reads down the page, each stage\'s Section under its step.\n\n```json\n{\n "tables": [\n {\n "ref": "ho_so",\n "title": "khach_hang",\n "fields": {\n "khach_hang": {"type": "link", "table": "khach_hang", "multi": false},\n "du_an": {"type": "link", "table": "du_an", "multi": false},\n "ma_ho_so": {"type": "autonumber"},\n "dich_vu": {\n "type": "select",\n "options": [{"alias": "tron_goi", "color": "blue"}, {"alias": "lam_ho_so", "color": "violet"}]\n },\n "doi_tuong": {\n "type": "select",\n "options": [\n {"alias": "thu_nhap_thap", "color": "sky"},\n {"alias": "cong_nhan", "color": "teal"},\n {"alias": "can_bo", "color": "indigo"},\n {"alias": "luc_luong", "color": "green"},\n {"alias": "ho_ngheo", "color": "amber"},\n {"alias": "nguoi_co_cong", "color": "rose"}\n ]\n },\n "tinh_trang_nha_o": {\n "type": "select",\n "options": [{"alias": "chua_co_nha", "color": "gray"}, {"alias": "nha_chat", "color": "orange"}]\n },\n "giay_chung_nhan_so": {"type": "text"},\n "dien_tich_nha": {"type": "number"},\n "sale": {"type": "member"},\n "xu_ly": {"type": "member"},\n "can_bo_sung": {"type": "boolean"},\n "phi_dich_vu": {"type": "number", "notation": {"style": "currency", "currency": "VND"}},\n "loai_can": {\n "type": "select",\n "options": [\n {"alias": "studio", "color": "sky"},\n {"alias": "mot_pn", "color": "blue"},\n {"alias": "hai_pn", "color": "indigo"},\n {"alias": "ba_pn", "color": "violet"}\n ]\n },\n "giai_doan": {\n "type": "select",\n "options": [\n {"alias": "ngay_thu_phi", "color": "blue"},\n {"alias": "ngay_nhan_giay_to", "color": "blue"},\n {"alias": "ngay_lap_ho_so", "color": "blue"},\n {"alias": "ngay_nop_cdt", "color": "blue"},\n {"alias": "ngay_cdt_duyet", "color": "blue"},\n {"alias": "ngay_so_xd_duyet", "color": "blue"},\n {"alias": "ngay_boc_tham", "color": "blue"},\n {"alias": "ngay_ky_hdmb", "color": "green"},\n {"alias": "ngay_ban_giao", "color": "green"}\n ]\n },\n "ngay_thu_phi": {"type": "date"},\n "ngay_nhan_giay_to": {"type": "date"},\n "ngay_lap_ho_so": {"type": "date"},\n "ngay_nop_cdt": {"type": "date"},\n "ngay_cdt_duyet": {"type": "date"},\n "ngay_so_xd_duyet": {"type": "date"},\n "ngay_boc_tham": {"type": "date"},\n "ngay_ky_hdmb": {"type": "date"},\n "ngay_ban_giao": {"type": "date"},\n "bo_ho_so": {"type": "files"},\n "giay_to": {"type": "link", "table": "giay_to", "multi": true},\n "thanh_vien": {"type": "link", "table": "thanh_vien", "multi": true},\n "phieu_thu": {"type": "link", "table": "phieu_thu", "multi": true},\n "dien_thoai": {"type": "lookup"},\n "cccd": {"type": "lookup"},\n "ngay_sinh": {"type": "lookup"},\n "da_thu": {"type": "rollup"},\n "chua_thu_phi": {"type": "formula"},\n "da_hoan_tat": {"type": "formula"}\n },\n "records": {\n "subtitle": ["dich_vu"],\n "figure": "phi_dich_vu",\n "status": {\n "field": "giai_doan",\n "closed": ["ngay_ky_hdmb", "ngay_ban_giao"],\n "dates": {\n "ngay_thu_phi": "ngay_thu_phi",\n "ngay_nhan_giay_to": "ngay_nhan_giay_to",\n "ngay_lap_ho_so": "ngay_lap_ho_so",\n "ngay_nop_cdt": "ngay_nop_cdt",\n "ngay_cdt_duyet": "ngay_cdt_duyet",\n "ngay_so_xd_duyet": "ngay_so_xd_duyet",\n "ngay_boc_tham": "ngay_boc_tham",\n "ngay_ky_hdmb": "ngay_ky_hdmb",\n "ngay_ban_giao": "ngay_ban_giao"\n }\n }\n }\n },\n {\n "ref": "thanh_vien",\n "title": "ho_ten",\n "fields": {\n "ho_ten": {"type": "text"},\n "ho_so": {"type": "link", "table": "ho_so", "multi": false},\n "quan_he": {\n "type": "select",\n "options": [\n {"alias": "nguoi_dung_don", "color": "blue"},\n {"alias": "vo_chong", "color": "violet"},\n {"alias": "con", "color": "teal"},\n {"alias": "bo_me", "color": "amber"},\n {"alias": "khac", "color": "gray"}\n ]\n },\n "ngay_sinh": {"type": "date"},\n "cccd": {"type": "text"},\n "thu_nhap": {"type": "number", "notation": {"style": "currency", "currency": "VND"}}\n },\n "records": {"subtitle": ["quan_he", "cccd"], "party": "person", "figure": "thu_nhap"}\n },\n {\n "ref": "giay_to",\n "title": "loai",\n "fields": {\n "loai": {\n "type": "select",\n "options": [\n {"alias": "don_dang_ky", "color": "blue"},\n {"alias": "can_cuoc", "color": "sky"},\n {"alias": "giay_doi_tuong", "color": "violet"},\n {"alias": "xac_nhan_nha_o", "color": "teal"},\n {"alias": "xac_nhan_thu_nhap", "color": "amber"},\n {"alias": "hon_nhan", "color": "indigo"}\n ]\n },\n "ho_so": {"type": "link", "table": "ho_so", "multi": false},\n "ngay_nhan": {"type": "date"},\n "tep": {"type": "files"}\n },\n "records": {"image": "tep", "starts": {"ngay_nhan": "today"}}\n },\n {\n "ref": "phieu_thu",\n "title": "khoan",\n "fields": {\n "khoan": {\n "type": "select",\n "options": [\n {"alias": "dat_coc", "color": "blue"},\n {"alias": "tat_toan", "color": "indigo"},\n {"alias": "phi_ho_so", "color": "violet"}\n ]\n },\n "ho_so": {"type": "link", "table": "ho_so", "multi": false},\n "so_tien": {"type": "number", "notation": {"style": "currency", "currency": "VND"}},\n "hinh_thuc": {\n "type": "select",\n "options": [\n {"alias": "tien_mat", "color": "green", "mark": {"kind": "icon", "name": "banknote"}},\n {"alias": "chuyen_khoan", "color": "blue", "mark": {"kind": "icon", "name": "arrow-right-left"}}\n ]\n },\n "trang_thai": {\n "type": "select",\n "options": [\n {"alias": "cho_thu", "color": "amber"},\n {"alias": "da_thu", "color": "green"},\n {"alias": "huy", "color": "gray"}\n ]\n },\n "ngay_thu": {"type": "date"}\n },\n "records": {\n "subtitle": ["hinh_thuc", "ngay_thu"],\n "figure": "so_tien",\n "status": {"field": "trang_thai", "closed": ["da_thu", "huy"]}\n }\n }\n ],\n "templates": [\n {"alias": "don_dang_ky", "type": "html", "label": "\u0110\u01A1n \u0111\u0103ng k\xFD mua nh\xE0 \u1EDF x\xE3 h\u1ED9i"},\n {"alias": "mau_02_chua_co_nha", "type": "html", "label": "M\u1EABu 02 \u2014 X\xE1c nh\u1EADn ch\u01B0a c\xF3 nh\xE0 \u1EDF"},\n {"alias": "mau_03_nha_chat", "type": "html", "label": "M\u1EABu 03 \u2014 X\xE1c nh\u1EADn nh\xE0 \u1EDF d\u01B0\u1EDBi 15 m\xB2/ng\u01B0\u1EDDi"},\n {"alias": "mau_05_thu_nhap", "type": "html", "label": "M\u1EABu 05 \u2014 X\xE1c nh\u1EADn thu nh\u1EADp"},\n {"alias": "danh_sach_nop", "type": "html", "label": "Danh s\xE1ch h\u1ED3 s\u01A1 n\u1ED9p ch\u1EE7 \u0111\u1EA7u t\u01B0"}\n ],\n "body": {\n "type": "App",\n "key": "ho_so",\n "name": "H\u1ED3 s\u01A1 nh\xE0 \u1EDF x\xE3 h\u1ED9i",\n "icon": "folder-open",\n "color": "blue",\n "scope": "du_an",\n "folders": "cac_du_an",\n "children": [\n {\n "type": "List",\n "entity": "ho_so",\n "columns": ["can_bo_sung", "doi_tuong", "xu_ly"],\n "filters": ["xu_ly", "can_bo_sung"],\n "search": ["khach_hang", "ma_ho_so", "dien_thoai"],\n "create": ["khach_hang", "dich_vu", "doi_tuong", "tinh_trang_nha_o", "loai_can", "phi_dich_vu", "sale"],\n "children": [\n {\n "type": "Reading",\n "key": "register_reading_0",\n "label": "Ch\u1EDD kh\xE1ch b\u1ED5 sung",\n "where": {"can_bo_sung": true}\n },\n {\n "type": "Reading",\n "key": "register_reading_1",\n "label": "Ph\xED \u0111\xE3 thu",\n "value": "da_thu",\n "over": "ngay_nhan_giay_to"\n },\n {"type": "Reading", "key": "register_reading_2", "by": "doi_tuong"},\n {"type": "Export", "key": "export"},\n {\n "type": "Act",\n "key": "in_danh_sach",\n "label": "In danh s\xE1ch n\u1ED9p ch\u1EE7 \u0111\u1EA7u t\u01B0",\n "on": "view",\n "template": "danh_sach_nop"\n }\n ]\n },\n {\n "type": "List",\n "entity": "du_an",\n "key": "cac_du_an",\n "columns": ["han_nop"],\n "create": false,\n "sort": {"field": "han_nop"},\n "children": [{"type": "Reading", "key": "du_an_theo_trang_thai", "by": "trang_thai"}]\n }\n ],\n "pages": [\n {\n "type": "Record",\n "entity": "ho_so",\n "children": [\n {\n "type": "Section",\n "key": "nguoi_dung_don",\n "title": "Ng\u01B0\u1EDDi \u0111\u1EE9ng \u0111\u01A1n",\n "children": [\n "ma_ho_so",\n {"field": "khach_hang", "block": true, "label": "Th\xF4ng tin c\xE1 nh\xE2n"},\n {\n "type": "Fieldset",\n "key": "dieu_kien",\n "label": "\u0110i\u1EC1u ki\u1EC7n mua",\n "children": ["doi_tuong", "tinh_trang_nha_o"]\n },\n {\n "type": "Fieldset",\n "key": "phu_trach",\n "label": "Ph\u1EE5 tr\xE1ch",\n "children": ["sale", "xu_ly", "can_bo_sung", "phi_dich_vu"]\n },\n {\n "type": "List",\n "entity": "thanh_vien",\n "label": "H\u1ED9 gia \u0111\xECnh",\n "columns": ["ngay_sinh"],\n "create": ["ho_ten", "quan_he", "ngay_sinh", "cccd", "thu_nhap"]\n },\n {\n "type": "List",\n "entity": "giay_to",\n "expect": {"field": "loai", "only": ["can_cuoc", "hon_nhan"]},\n "label": "Gi\u1EA5y t\u1EDD c\xE1 nh\xE2n",\n "columns": ["ngay_nhan"]\n },\n {\n "type": "Act",\n "key": "doc_giay_to",\n "label": "\u0110\u1ECDc gi\u1EA5y t\u1EDD",\n "intake": "giay_to",\n "fills": [\n "doi_tuong",\n "tinh_trang_nha_o",\n "giay_chung_nhan_so",\n "dien_tich_nha",\n "khach_hang.ho_ten",\n "khach_hang.cccd",\n "khach_hang.ngay_sinh",\n "khach_hang.dia_chi",\n "thanh_vien"\n ]\n },\n {\n "type": "Act",\n "key": "giao_xu_ly",\n "label": "Giao ng\u01B0\u1EDDi x\u1EED l\xFD",\n "asks": [{"input": "nguoi", "label": "Ng\u01B0\u1EDDi x\u1EED l\xFD", "type": "member", "required": true}],\n "set": {"xu_ly": {"input": "nguoi"}}\n },\n {\n "type": "Act",\n "key": "chuyen_du_an",\n "label": "Chuy\u1EC3n d\u1EF1 \xE1n",\n "asks": [\n {\n "input": "du_an_moi",\n "label": "Sang d\u1EF1 \xE1n",\n "type": "link",\n "entity": "du_an",\n "required": true\n }\n ],\n "set": {"du_an": {"input": "du_an_moi"}},\n "confirm": true\n }\n ]\n },\n {\n "type": "Steps",\n "children": [\n {\n "type": "Section",\n "key": "bo_ho_so",\n "title": "B\u1ED9 h\u1ED3 s\u01A1",\n "at": ["ngay_nhan_giay_to", "ngay_lap_ho_so"],\n "children": [\n "ngay_nhan_giay_to",\n "ngay_lap_ho_so",\n {\n "type": "Act",\n "key": "tao_giay_to",\n "label": "T\u1EA1o gi\u1EA5y t\u1EDD",\n "templates": [\n {"template": "don_dang_ky"},\n {"template": "mau_02_chua_co_nha", "when": {"tinh_trang_nha_o": ["chua_co_nha"]}},\n {"template": "mau_03_nha_chat", "when": {"tinh_trang_nha_o": ["nha_chat"]}}\n ],\n "into": "bo_ho_so",\n "when": {"giai_doan": ["ngay_nhan_giay_to", "ngay_lap_ho_so"]}\n },\n {\n "type": "Act",\n "key": "nop_cdt",\n "label": "N\u1ED9p ch\u1EE7 \u0111\u1EA7u t\u01B0",\n "when": {"dich_vu": ["tron_goi"], "giai_doan": ["ngay_lap_ho_so"]},\n "requires": ["bo_ho_so", "loai_can"],\n "asks": ["loai_can"],\n "set": {"giai_doan": "ngay_nop_cdt"},\n "confirm": true\n },\n {\n "type": "Act",\n "key": "to_ngay_nhan_giay_to",\n "label": "\u0110\xE3 nh\u1EADn gi\u1EA5y t\u1EDD",\n "when": {"giai_doan": {"empty": true}, "dich_vu": ["tron_goi"]},\n "asks": [{"field": "ngay_nhan_giay_to", "starts": "today"}],\n "set": {"giai_doan": "ngay_nhan_giay_to"}\n },\n {\n "type": "Act",\n "key": "to_ngay_lap_ho_so",\n "label": "\u0110\xE3 l\u1EADp h\u1ED3 s\u01A1",\n "when": {"giai_doan": ["ngay_nhan_giay_to"], "dich_vu": ["tron_goi"]},\n "asks": [{"field": "ngay_lap_ho_so", "starts": "today"}],\n "set": {"giai_doan": "ngay_lap_ho_so"}\n },\n {\n "type": "Act",\n "key": "to_ngay_ban_giao",\n "label": "\u0110\xE3 b\xE0n giao h\u1ED3 s\u01A1",\n "when": {"giai_doan": ["ngay_nhan_giay_to"], "dich_vu": ["lam_ho_so"]},\n "asks": [{"field": "ngay_ban_giao", "starts": "today"}],\n "set": {"giai_doan": "ngay_ban_giao"}\n }\n ]\n }\n ]\n },\n {\n "type": "Act",\n "key": "lap_mau_05",\n "label": "L\u1EADp m\u1EABu 05",\n "when": {"doi_tuong": ["thu_nhap_thap"]},\n "template": "mau_05_thu_nhap",\n "paper": "giay_to.xac_nhan_thu_nhap"\n },\n {"type": "Check", "field": "chua_thu_phi", "on": ["nop_cdt"]},\n {"type": "Check", "field": "da_hoan_tat", "on": ["doc_giay_to"]}\n ],\n "row": {"figure": false}\n },\n {"type": "Record", "entity": "du_an", "add": ["ten_du_an", "chu_dau_tu", "so_can"]}\n ]\n }\n}\n```\n\n## Calls\n\n**The job.** Call a lead from their record, and keep what was said as a touch on its timeline.\n\n**Read.** An Act\'s `record` (into the `timeline` child: audio, transcript, when and who) and `fills` (the touch\'s fields an agent fills from the transcript).\n\n**Keys.** `reference/act-node`, `reference/layouts`\n\n**Not when.** Calls made and logged elsewhere \u2014 a `timeline` with its own add keeps the note.\n\n**Its stages.** `khach_tiem_nang` states Sections at its stages: its path reads down the page, each stage\'s Section under its step. `buoc_tiep` states no Section at a stage and its Acts move it: its path draws as a line of steps across the page.\n\n```json\n{\n "tables": [\n {\n "ref": "khach_tiem_nang",\n "title": "ho_ten",\n "fields": {\n "ho_ten": {"type": "text"},\n "ten_cong_ty": {"type": "text"},\n "vai_tro": {\n "type": "select",\n "options": [\n {"alias": "chu_doanh_nghiep", "color": "emerald"},\n {"alias": "ke_toan_truong", "color": "blue"},\n {"alias": "quan_ly", "color": "teal"},\n {"alias": "nhan_vien", "color": "sky"},\n {"alias": "chua_ro", "color": "zinc"}\n ]\n },\n "loai_hinh": {\n "type": "select",\n "options": [\n {"alias": "thuong_mai", "color": "blue"},\n {"alias": "san_xuat", "color": "amber"},\n {"alias": "dich_vu", "color": "violet"},\n {"alias": "xay_dung", "color": "orange"},\n {"alias": "ho_kinh_doanh", "color": "teal"},\n {"alias": "chua_ro", "color": "zinc"}\n ]\n },\n "quy_mo": {\n "type": "select",\n "options": [\n {"alias": "q_1_10", "color": "sky"},\n {"alias": "q_11_50", "color": "blue"},\n {"alias": "q_51_200", "color": "indigo"},\n {"alias": "q_200", "color": "violet"},\n {"alias": "chua_ro", "color": "zinc"}\n ]\n },\n "so_dien_thoai": {"type": "text"},\n "zalo": {"type": "text"},\n "email": {"type": "text"},\n "trang_ca_nhan": {"type": "text", "format": "link"},\n "anh": {"type": "files"},\n "trang_thai": {\n "type": "select",\n "options": [\n {"alias": "moi", "color": "gray"},\n {"alias": "du_dieu_kien", "color": "blue"},\n {"alias": "da_lien_he", "color": "amber"},\n {"alias": "da_chuyen_doi", "color": "emerald"},\n {"alias": "loai", "color": "red"}\n ]\n },\n "ly_do_loai": {\n "type": "select",\n "options": [\n {"alias": "khong_phu_hop", "color": "orange"},\n {"alias": "qua_nho", "color": "amber"},\n {"alias": "chua_co_ngan_sach", "color": "yellow"},\n {"alias": "sai_nguoi", "color": "blue"},\n {"alias": "yeu_cau_dung", "color": "red"},\n {"alias": "trung", "color": "zinc"}\n ]\n },\n "vi_sao_du_dieu_kien": {"type": "text"},\n "phu_trach": {"type": "member"},\n "nguon": {"type": "link", "table": "kenh", "multi": false},\n "lien_he": {"type": "link", "table": "lien_he", "multi": false},\n "cong_ty": {"type": "link", "table": "cong_ty", "multi": false},\n "ngay_chuyen_doi": {"type": "date", "format": "datetime", "timezone": "Asia/Ho_Chi_Minh"},\n "ghi_chu": {"type": "text", "format": "markdown"},\n "tin_hieu": {"type": "link", "table": "tin_hieu", "multi": true},\n "buoc_tiep": {"type": "link", "table": "buoc_tiep", "multi": true},\n "tuong_tac": {"type": "link", "table": "tuong_tac", "multi": true},\n "do_nong": {\n "type": "formula",\n "options": [\n {"alias": "nong", "label": "N\xF3ng", "color": "orange"},\n {"alias": "nguoi", "label": "Ngu\u1ED9i", "color": "sky"}\n ]\n },\n "han_buoc_tiep": {"type": "rollup"},\n "khong_lien_he": {"type": "formula"}\n },\n "records": {\n "subtitle": ["ten_cong_ty"],\n "image": "anh",\n "party": "person",\n "due": ["han_buoc_tiep"],\n "status": {\n "field": "trang_thai",\n "closed": ["da_chuyen_doi", "loai"],\n "dates": {"da_chuyen_doi": "ngay_chuyen_doi"}\n }\n }\n },\n {\n "ref": "tin_hieu",\n "title": "tom_tat",\n "fields": {\n "tom_tat": {"type": "text"},\n "noi_dung": {"type": "text", "format": "markdown"},\n "anh_chup": {"type": "files"},\n "lien_ket": {"type": "text", "format": "link"},\n "kenh": {"type": "link", "table": "kenh", "multi": false},\n "loai": {\n "type": "select",\n "options": [\n {"alias": "hoi_dich_vu", "color": "emerald"},\n {"alias": "than_phien", "color": "blue"},\n {"alias": "tuyen_ke_toan", "color": "amber"},\n {"alias": "moi_thanh_lap", "color": "violet"},\n {"alias": "gioi_thieu", "color": "teal"},\n {"alias": "danh_ba", "color": "zinc"},\n {"alias": "nhieu", "color": "stone"}\n ]\n },\n "ngay_dang": {"type": "date", "timezone": "Asia/Ho_Chi_Minh"},\n "ngay_xay_ra": {"type": "formula"}\n },\n "records": {"subtitle": ["kenh", "ngay_xay_ra"], "image": "anh_chup"}\n },\n {\n "ref": "buoc_tiep",\n "title": "vi_sao_luc_nay",\n "fields": {\n "vi_sao_luc_nay": {"type": "text"},\n "viec": {\n "type": "select",\n "options": [\n {"alias": "binh_luan", "color": "blue", "mark": {"kind": "icon", "name": "message-square"}},\n {"alias": "nhan_facebook", "color": "violet", "mark": {"kind": "brand", "name": "facebook"}},\n {"alias": "nhan_zalo", "color": "sky", "mark": {"kind": "brand", "name": "zalo"}},\n {"alias": "goi_dien", "color": "teal", "mark": {"kind": "icon", "name": "phone"}},\n {"alias": "gui_email", "color": "indigo", "mark": {"kind": "icon", "name": "mail"}},\n {"alias": "gui_bang_gia", "color": "amber", "mark": {"kind": "icon", "name": "receipt"}}\n ]\n },\n "ban_nhap": {"type": "text", "format": "markdown"},\n "han": {"type": "date", "format": "datetime", "timezone": "Asia/Ho_Chi_Minh"},\n "tinh_trang": {\n "type": "select",\n "options": [\n {"alias": "cho", "color": "blue"},\n {"alias": "xong", "color": "emerald"},\n {"alias": "bo_qua", "color": "zinc"}\n ]\n }\n },\n "records": {\n "subtitle": ["viec"],\n "mark": "viec",\n "due": ["han"],\n "status": {"field": "tinh_trang", "closed": ["xong", "bo_qua"]}\n }\n },\n {\n "ref": "tuong_tac",\n "title": "tom_tat",\n "fields": {\n "tom_tat": {"type": "text"},\n "thoi_diem": {"type": "date", "format": "datetime", "timezone": "Asia/Ho_Chi_Minh"},\n "qua": {\n "type": "select",\n "options": [\n {"alias": "goi_dien", "color": "teal", "mark": {"kind": "icon", "name": "phone"}},\n {"alias": "zalo", "color": "sky", "mark": {"kind": "brand", "name": "zalo"}},\n {"alias": "facebook", "color": "blue", "mark": {"kind": "brand", "name": "facebook"}},\n {"alias": "email", "color": "indigo", "mark": {"kind": "icon", "name": "mail"}},\n {"alias": "gap_truc_tiep", "color": "emerald", "mark": {"kind": "icon", "name": "users"}},\n {"alias": "khac", "color": "zinc", "mark": {"kind": "icon", "name": "ellipsis"}}\n ]\n },\n "phan_hoi": {\n "type": "select",\n "options": [\n {"alias": "dang_cho", "color": "blue"},\n {"alias": "da_tra_loi", "color": "green"},\n {"alias": "quan_tam", "color": "amber"},\n {"alias": "khong_phu_hop", "color": "red"},\n {"alias": "khong_phan_hoi", "color": "zinc"},\n {"alias": "sai_so", "color": "stone"}\n ]\n },\n "ghi_am": {"type": "files"},\n "man_hinh": {"type": "files"},\n "nguyen_van": {"type": "text", "format": "markdown"},\n "hen_lai": {"type": "date", "timezone": "Asia/Ho_Chi_Minh"},\n "nguoi_thuc_hien": {"type": "member"}\n },\n "records": {"subtitle": ["qua", "phan_hoi"]}\n }\n ],\n "body": {\n "type": "App",\n "key": "khach_tiem_nang",\n "name": "Kh\xE1ch ti\u1EC1m n\u0103ng",\n "icon": "radar",\n "color": "violet",\n "children": [\n {\n "type": "List",\n "entity": "khach_tiem_nang",\n "columns": ["phu_trach", "han_buoc_tiep"],\n "filters": ["phu_trach"],\n "create": ["ho_ten", "trang_ca_nhan", "so_dien_thoai", "ten_cong_ty", "nguon"],\n "children": [\n {"type": "Reading", "key": "register_reading_0", "by": "phu_trach"},\n {\n "type": "Reading",\n "key": "register_reading_1",\n "label": "Kh\xE1ch chuy\u1EC3n \u0111\u1ED5i",\n "by": "ngay_chuyen_doi"\n }\n ]\n }\n ],\n "pages": [\n {\n "type": "Record",\n "entity": "khach_tiem_nang",\n "children": [\n {\n "type": "Steps",\n "children": [\n {\n "type": "Section",\n "key": "danh_gia",\n "title": "\u0110\xE1nh gi\xE1",\n "at": ["moi"],\n "children": [\n "vai_tro",\n "loai_hinh",\n "quy_mo",\n "vi_sao_du_dieu_kien",\n "do_nong",\n {\n "type": "List",\n "entity": "tin_hieu",\n "columns": ["loai", "noi_dung"],\n "create": ["tom_tat", "anh_chup", "loai", "noi_dung", "kenh", "lien_ket", "ngay_dang"]\n },\n {\n "type": "Act",\n "key": "danh_gia_dat",\n "label": "\u0110\u1EE7 \u0111i\u1EC1u ki\u1EC7n",\n "when": {"trang_thai": ["moi"]},\n "requires": ["vi_sao_du_dieu_kien"],\n "set": {"trang_thai": "du_dieu_kien"}\n }\n ]\n },\n {\n "type": "Section",\n "key": "lien_he",\n "title": "Li\xEAn h\u1EC7",\n "at": ["du_dieu_kien"],\n "children": [\n "so_dien_thoai",\n "phu_trach",\n "trang_ca_nhan",\n "zalo",\n "email",\n {"field": "ghi_chu", "block": false},\n {\n "type": "List",\n "entity": "buoc_tiep",\n "columns": ["ban_nhap"],\n "create": ["vi_sao_luc_nay", "viec", "han", "ban_nhap"]\n },\n {\n "type": "List",\n "entity": "tuong_tac",\n "layout": "timeline",\n "create": ["tom_tat", "qua", "phan_hoi", "thoi_diem", "hen_lai"]\n },\n {\n "type": "Act",\n "key": "ghi_cuoc_goi",\n "label": "Ghi \xE2m cu\u1ED9c g\u1ECDi",\n "when": {"trang_thai": ["du_dieu_kien"]},\n "fills": ["tom_tat", "phan_hoi"],\n "record": {\n "into": "tuong_tac",\n "audio": "ghi_am",\n "transcript": "nguyen_van",\n "at": "thoi_diem",\n "by": "nguoi_thuc_hien",\n "video": "man_hinh"\n }\n },\n {\n "type": "Act",\n "key": "da_lien_he",\n "label": "\u0110\xE1nh d\u1EA5u \u0111\xE3 li\xEAn h\u1EC7",\n "when": {"trang_thai": ["du_dieu_kien"]},\n "set": {"trang_thai": "da_lien_he"}\n }\n ]\n },\n {\n "type": "Section",\n "key": "chuyen_doi",\n "title": "Chuy\u1EC3n \u0111\u1ED5i",\n "at": ["da_lien_he"],\n "children": [\n "nguon",\n {"field": "lien_he", "edit": false},\n {"field": "cong_ty", "edit": false},\n {\n "type": "Act",\n "key": "chuyen_doi",\n "label": "Chuy\u1EC3n \u0111\u1ED5i",\n "when": {"trang_thai": ["da_lien_he"]},\n "workflow": "chuyen_doi_khach",\n "confirm": true\n }\n ]\n },\n {\n "type": "Section",\n "key": "loai",\n "title": "Lo\u1EA1i",\n "at": ["loai"],\n "children": [\n "ly_do_loai",\n {\n "type": "Act",\n "key": "loai",\n "label": "Lo\u1EA1i",\n "when": {"trang_thai": ["moi", "du_dieu_kien", "da_lien_he"]},\n "asks": ["ly_do_loai"],\n "set": {"trang_thai": "loai"},\n "danger": true\n },\n {\n "type": "Act",\n "key": "mo_lai",\n "label": "M\u1EDF l\u1EA1i",\n "when": {"trang_thai": ["loai"]},\n "set": {"trang_thai": "moi"}\n }\n ]\n }\n ]\n },\n {"type": "Check", "field": "khong_lien_he", "resolve": "da_lien_he"}\n ]\n },\n {"type": "Record", "entity": "kenh", "add": ["ten", "loai"]},\n {\n "type": "Record",\n "entity": "buoc_tiep",\n "children": [\n {\n "type": "Act",\n "key": "lam_xong",\n "label": "\u0110\xE3 l\xE0m",\n "when": {"tinh_trang": ["cho"]},\n "set": {"tinh_trang": "xong"}\n }\n ]\n }\n ]\n }\n}\n```\n\n## Approval\n\n**The job.** Raise a payment request, see it through approval, and read what is waiting at the top of the list.\n\n**Read.** `records.de_nghi.status` with its `history` (each move: when and who), Sections staged by `at`, and the List\'s Readings leading with the headline number. The history stays because the business reads who signed each move; where only the day a stage was reached matters, the status stamps a date on the row instead (the Gantt above).\n\n**Keys.** `reference/status`, `reference/section-node`, `reference/reading-node`\n\n**Not when.** Rows that never move \u2014 a reference list (a price list, a catalog) has no status and no headline number.\n\n**Its stages.** `de_nghi` states Sections at its stages: its path reads down the page, each stage\'s Section under its step.\n\n```json\n{\n "tables": [\n {\n "ref": "de_nghi",\n "title": "noi_dung",\n "fields": {\n "noi_dung": {"type": "text"},\n "so_de_nghi": {"type": "text"},\n "loai": {\n "type": "select",\n "options": [\n {"alias": "thanh_toan_ncc", "color": "violet"},\n {"alias": "nhan_cong", "color": "indigo"},\n {"alias": "chi_phi_cong_truong", "color": "sky"},\n {"alias": "tam_ung", "color": "amber"},\n {"alias": "hoan_ung", "color": "teal"}\n ]\n },\n "du_an": {"type": "link", "table": "du_an", "multi": false},\n "nha_cung_cap": {"type": "link", "table": "nha_cung_cap", "multi": false},\n "so_tien": {"type": "number", "notation": {"style": "currency", "currency": "VND"}},\n "han_thanh_toan": {"type": "date"},\n "trang_thai": {\n "type": "select",\n "options": [\n {"alias": "nhap", "color": "slate"},\n {"alias": "cho_duyet", "color": "amber"},\n {"alias": "cho_chu_tich", "color": "violet"},\n {"alias": "da_duyet", "color": "blue"},\n {"alias": "da_chi", "color": "green"},\n {"alias": "tu_choi", "color": "rose"}\n ]\n },\n "nguoi_de_nghi": {"type": "member"},\n "chung_tu": {"type": "files"},\n "nguoi_duyet": {"type": "member"},\n "duyet_luc": {"type": "date", "format": "datetime"},\n "ly_do_tu_choi": {"type": "text"},\n "phieu_chi": {"type": "files"},\n "ngan_sach_du_an": {"type": "lookup"},\n "da_duyet_du_an": {"type": "lookup"},\n "da_gui": {"type": "formula"},\n "nhap_at": {"type": "date", "format": "datetime"},\n "cho_duyet_at": {"type": "date", "format": "datetime"},\n "cho_chu_tich_at": {"type": "date", "format": "datetime"},\n "da_duyet_at": {"type": "date", "format": "datetime"}\n },\n "records": {\n "subtitle": ["du_an"],\n "figure": "so_tien",\n "limits": {"da_duyet_du_an": "ngan_sach_du_an"},\n "due": ["han_thanh_toan"],\n "starts": {"nguoi_de_nghi": "me"},\n "status": {\n "field": "trang_thai",\n "closed": ["da_chi", "tu_choi"],\n "dropped": ["tu_choi"],\n "dates": {\n "nhap": "nhap_at",\n "cho_duyet": "cho_duyet_at",\n "cho_chu_tich": "cho_chu_tich_at",\n "da_duyet": "da_duyet_at"\n },\n "history": "lich_su_duyet",\n "stages": {\n "nhap": {"owner": "nguoi_de_nghi"},\n "cho_duyet": {"owner": {"group": "<id of the giam_doc group>"}, "within": 1},\n "cho_chu_tich": {\n "owner": {"group": "<id of the chu_tich group>"},\n "within": 2,\n "when": {"so_tien": {"gt": 200000000}}\n },\n "da_duyet": {"owner": {"group": "<id of the ke_toan group>"}, "within": 2}\n }\n }\n }\n }\n ],\n "body": {\n "type": "App",\n "key": "de_nghi_chi",\n "name": "\u0110\u1EC1 ngh\u1ECB thanh to\xE1n",\n "icon": "hand-coins",\n "color": "amber",\n "children": [\n {\n "type": "List",\n "entity": "de_nghi",\n "filters": ["du_an"],\n "group": "du_an",\n "create": ["noi_dung", "loai", "du_an", "nha_cung_cap", "so_tien", "han_thanh_toan", "nguoi_de_nghi"],\n "children": [\n {\n "type": "Reading",\n "key": "register_reading_0",\n "label": "\u0110\xE3 duy\u1EC7t, ch\u1EDD chi",\n "value": "so_tien",\n "where": {"trang_thai": ["da_duyet"]}\n },\n {"type": "Reading", "key": "register_reading_1", "value": "so_tien", "by": "han_thanh_toan"}\n ]\n }\n ],\n "pages": [\n {\n "type": "Record",\n "entity": "de_nghi",\n "door": "drawer",\n "children": [\n {\n "type": "Steps",\n "children": [\n {\n "type": "Section",\n "key": "de_nghi",\n "title": "\u0110\u1EC1 ngh\u1ECB",\n "at": ["nhap"],\n "children": [\n "so_de_nghi",\n "loai",\n "nha_cung_cap",\n "han_thanh_toan",\n "nguoi_de_nghi",\n {"field": "chung_tu"},\n {\n "type": "Act",\n "key": "gui_duyet",\n "label": "G\u1EEDi duy\u1EC7t",\n "when": {"trang_thai": ["nhap"]},\n "requires": ["chung_tu", "nguoi_de_nghi"],\n "set": {"trang_thai": "cho_duyet"}\n }\n ]\n },\n {\n "type": "Section",\n "key": "duyet",\n "title": "Duy\u1EC7t",\n "at": ["cho_duyet", "cho_chu_tich"],\n "children": [\n {"field": "nguoi_duyet", "edit": false},\n {"field": "duyet_luc", "edit": false},\n {"field": "ly_do_tu_choi", "edit": false},\n {\n "type": "Act",\n "key": "rut_lai",\n "label": "R\xFAt l\u1EA1i",\n "when": {"trang_thai": ["cho_duyet", "cho_chu_tich"]},\n "set": {"trang_thai": "nhap"},\n "confirm": true\n }\n ]\n },\n {\n "type": "Section",\n "key": "da_chi",\n "title": "\u0110\xE3 chi",\n "at": ["da_chi"],\n "children": [{"field": "phieu_chi", "edit": false}]\n }\n ]\n },\n {"type": "Check", "field": "da_gui", "on": ["update"]}\n ]\n },\n {"type": "Record", "entity": "du_an", "add": ["ten", "ma_du_an", "chu_dau_tu", "ngan_sach"]}\n ]\n }\n}\n```\n\n## Dashboard\n\n**The job.** The owner\'s question \u2014 what came in, what went out, where it went, and what is still unmatched \u2014 answered over one period.\n\n**Read.** An App of Readings and no List: Readings with `over` (the period windows them), a Reading `by` the day, Readings `by` a field, and a List of rows to act on.\n\n**Keys.** `reference/app-node`, `reference/reading-node`\n\n**Not when.** One job\'s headline numbers \u2014 those lead that job\'s List as its Readings.\n\n```json\n{\n "tables": [\n {\n "ref": "giao_dich",\n "title": "noi_dung",\n "fields": {\n "noi_dung": {"type": "text"},\n "ngay": {"type": "date"},\n "loai": {"type": "select", "options": [{"alias": "thu", "color": "green"}, {"alias": "chi", "color": "rose"}]},\n "so_tien": {"type": "number", "notation": {"style": "currency", "currency": "VND"}},\n "bien_dong": {"type": "formula", "notation": {"style": "currency", "currency": "VND"}},\n "doi_tuong": {"type": "link", "table": "doi_tuong", "multi": false},\n "danh_muc": {\n "type": "select",\n "options": [\n {"alias": "doanh_thu", "color": "green"},\n {"alias": "hang_hoa", "color": "blue"},\n {"alias": "van_chuyen", "color": "indigo"},\n {"alias": "nhan_su", "color": "violet"},\n {"alias": "van_phong", "color": "sky"},\n {"alias": "thue_phi", "color": "slate"},\n {"alias": "ngan_hang", "color": "teal"},\n {"alias": "khac", "color": "gray"}\n ]\n },\n "sao_ke": {"type": "link", "table": "sao_ke", "multi": false},\n "hoa_don": {"type": "link", "table": "hoa_don", "multi": true},\n "trang_thai": {\n "type": "select",\n "options": [\n {"alias": "chua_khop", "color": "amber"},\n {"alias": "da_khop", "color": "green"},\n {"alias": "khong_can_hd", "color": "slate"}\n ]\n },\n "khop_luc": {"type": "date", "format": "datetime"}\n },\n "records": {\n "subtitle": ["ngay"],\n "figure": "bien_dong",\n "status": {"field": "trang_thai", "closed": ["da_khop", "khong_can_hd"], "dates": {"da_khop": "khop_luc"}}\n }\n },\n {\n "ref": "hoa_don",\n "title": "doi_tuong",\n "fields": {\n "doi_tuong": {"type": "link", "table": "doi_tuong", "multi": false},\n "so_hoa_don": {"type": "text"},\n "ngay_hoa_don": {"type": "date"},\n "so_ngay_qua_han": {"type": "formula", "notation": {"style": "unit", "unit": "day"}},\n "chieu": {\n "type": "select",\n "options": [{"alias": "ban_ra", "color": "green"}, {"alias": "mua_vao", "color": "violet"}]\n },\n "tong_cong": {"type": "formula", "notation": {"style": "currency", "currency": "VND"}},\n "tep": {"type": "files"},\n "giao_dich": {"type": "link", "table": "giao_dich", "multi": true}\n },\n "records": {"subtitle": ["so_hoa_don", "ngay_hoa_don"], "image": "tep", "figure": "tong_cong"}\n }\n ],\n "body": {\n "type": "App",\n "key": "dong_tien",\n "name": "D\xF2ng ti\u1EC1n",\n "icon": "chart-line",\n "color": "emerald",\n "children": [\n {\n "type": "Sheet",\n "key": "dong_tien",\n "label": "D\xF2ng ti\u1EC1n",\n "children": [\n {\n "type": "Reading",\n "key": "dashboard_reading_0",\n "label": "Ti\u1EC1n v\xE0o",\n "entity": "giao_dich",\n "value": "so_tien",\n "where": {"loai": ["thu"]},\n "over": "ngay"\n },\n {\n "type": "Reading",\n "key": "dashboard_reading_1",\n "label": "Ti\u1EC1n ra",\n "entity": "giao_dich",\n "value": "so_tien",\n "where": {"loai": ["chi"]},\n "over": "ngay",\n "better": "down"\n },\n {\n "type": "Reading",\n "key": "dashboard_reading_2",\n "label": "D\xF2ng ti\u1EC1n r\xF2ng",\n "entity": "giao_dich",\n "value": "bien_dong",\n "by": "ngay"\n },\n {\n "type": "Reading",\n "key": "dashboard_reading_3",\n "label": "Chi theo danh m\u1EE5c",\n "entity": "giao_dich",\n "value": "so_tien",\n "where": {"loai": ["chi"]},\n "by": "danh_muc",\n "over": "ngay"\n },\n {\n "type": "Reading",\n "key": "dashboard_reading_4",\n "label": "Thu theo kh\xE1ch h\xE0ng",\n "entity": "giao_dich",\n "value": "so_tien",\n "where": {"loai": ["thu"]},\n "by": "doi_tuong",\n "over": "ngay"\n },\n {\n "type": "Reading",\n "key": "dashboard_reading_5",\n "label": "C\xF4ng n\u1EE3 b\xE1n ra theo tu\u1ED5i n\u1EE3",\n "entity": "hoa_don",\n "value": "tong_cong",\n "where": {"chieu": ["ban_ra"]},\n "by": "doi_tuong",\n "across": {"field": "so_ngay_qua_han", "tiers": [1, 8, 16, 31]}\n },\n {\n "type": "List",\n "key": "dashboard_reading_8",\n "entity": "giao_dich",\n "where": {"trang_thai": ["chua_khop"]},\n "label": "D\xF2ng ch\u01B0a kh\u1EDBp",\n "columns": ["sao_ke"]\n }\n ]\n }\n ]\n }\n}\n```\n';
|
|
1890
1890
|
|
|
1891
1891
|
// docs/agent_surface.md
|
|
1892
|
-
var agent_surface_default = '# An app\'s agent surface\n\nEverything a person reads or does in an app, an agent reads or does through that app\'s **queries** and\n**workflows** \u2014 the same ones its screen runs, under the same permissions and the same rules. Three tools\nreach them, over MCP and as `lotics run <tool>`:\n\n| Tool | Answers |\n|---|---|\n| `get_app` | The app\'s `catalog`: its queries and workflows by alias, each one\'s description, its params or inputs with their types and legal values, and under a query\'s line its output columns (`returns`) \u2014 beside what each table they name holds, in its owner\'s words \u2014 and, for the app\'s author, `notes`: what its stored tree compiles with, each at its address under its rule id (`list.layout-call`, a root List drawing a table over rows a board layout would draw, with the layouts to state; `list.filter-unshown`, a filter no row draws, which the app leaves out) |\n| `run_app_query` | The rows, a count or the groups of one query \u2014 or of several in one call |\n| `run_app_workflow` | One write \u2014 or several in order \u2014 or a dry run of it that writes nothing |\n\nAn app generates this surface from its tree; Query and Workflow nodes declare what the screen never\nasks (`agent_surface/declaring-more`). Every root List of an app (a change may add one at any time) is part of it: each List\'s list, its rows by id, its page\'s\nLists and its Acts are queries and workflows of the same app, named by that List\'s table \u2014 `get_app` lists them in the\none roster, and nothing of a root List is another app\'s. Every caller the app is shared with is answered them, its rows narrowed by the app\'s row rules. A custom-code app\'s surface is the queries and workflows bound on it\n(`app_bindings`).\n\n## Finding what an app offers\n\n`get_workspace` maps the workspace. Its `search` matches the keys and descriptions of the Query and Workflow nodes an app declares, and the app\'s line names the matching keys; it never matches the generated `act_`, `create_` or `update_` aliases. `get_app` then gives the contracts. An agent runs a declared node before it falls back to `query_records`.\n\n## What every app generates\n\nA name in angle brackets is the app\'s alias for that thing; an `<entity>` is the alias of a table the app reads. `get_app` lists the ones a given\napp has.\n\n### Queries\n\n<!-- generated:start queries -->\n\n| Called | What it says of itself | Takes | Generated for |\n|---|---|---|---|\n| `<entity>_list` | Every row of <entity> the reader may see. | `search`?; `<scope entity>_id` where the app states `scope`; `<filter>_is`? per List `filters` field holding one value \u2014 a select, a one-row link, a member, a yes/no; `<filter>_from`? / `<filter>_to`? per date filter \u2014 none for a date holding a span; `<filter>_min`? / `<filter>_max`? per number filter \u2014 none over sources, none for a looked-up link or member, none for a number read in each row\'s own unit or currency | every entity the app draws; the filter params on the app\'s own entity alone; a root List after the first over an entity, whose chips differ from the first\'s, adds one of its own, called by its key |\n| `<entity>_list_<tab>` | The <entity> rows of the tab "<tab>". | the list\'s; `from`? / `to`? on a tab dated `in` a period; `to` on a tab of rows `open` on a day | each Tab of the register, and of each later root List over an entity, called by its key; none over sources, none for a Tab whose period reads a date holding a span |\n| `<entity>_totals_<tab>` | The <child> rows added per <entity> row, by "<link>", over the period from `from` to `to`, dated by "<date>": . | `from`; `to` | each Tab of the register stating `totals`, and of each later root List over an entity, called by its key |\n| `<entity>_record` | One row of <entity> by its id. | `<entity>_id` | every entity the app draws |\n| `<child>_by_<link>` | The <child> rows under one <entity>, through "<link>". | `<entity>_id` | each List of child rows on the record; one narrowed by `where` or ordered by `sort` adds `_<field>_<option>` and `_sorted_<field>` to its name |\n| `outside_<key>_one` | One row of <entity> by its id. | `record` | each Outside: the record a link opens, projected to the fields the Outside states |\n| `outside_<key>_<child>` | The <child> rows under one <entity>, through "<link>". | `record` | each List of an Outside: the rows under the record a link opens, projected to the List\'s columns |\n| `<child>_by_<link>_days` | The <child> rows of the <entity> rows handed in whose "<day>" falls from one day to another. | `<entity>_ids`; `from`; `to` | a roster List: the List of its cells |\n| `<entity>_<link>_pick` | The <target> rows "<link>" may point at, narrowed by what the reader typed. | `search`?; `same_<link>` per `same` link | a written link a write rule narrows (`options_where`, `same`) |\n| `<child>_by_<link>_picks` | The <child> rows no <entity> holds through "<link>" yet, that one <entity> may pick, narrowed by what the reader typed. | `search`?; `same_<link>` per `same` link | a List with `pick`: it picks existing rows into the record |\n| `<key>` | <label>: how many <entity> rows there are. Each row carries `__count`. | the list\'s; `from`? / `to`? where the reading states `over`, or its `tab` is dated `in` a period; `to` where its `tab` is of rows `open` on a day | each Reading of a List\'s band, called by its `key` \u2014 but the work against its plan (a Reading stating `planned` and `done`), which reads the List\'s own rows; none over sources |\n| `<key>` | <label>: how many <entity> rows there are. Each row carries `__count`. | `from`? / `to`? where the reading states `over` | each Reading and List of a Sheet, called by its `key` |\n| `<key>` | <label>: how many <child> rows there are. Each row carries `__count`. | `<entity>_id`; `same_<field>` where it is a List stating `same`; `record_<field>` per `where` bound to a field of the record | each Reading of a Record page, each List that only reads on it (its `key`, else its entity\'s alias) and each funnel, called by its `key` |\n| `<reading>_bound` | <label> / <bound>: the sum of "<bound>" over the <entity> rows. Each row carries `__count`, `__sum`. | its reading\'s | a Reading whose value `records.limits` bounds: the bound\'s sum, beside the Reading\'s own |\n| `<reading>_on_hand` | <label> / <on-hand entity>: how many <on-hand entity> rows there are, per "<field>". Each row carries `<field>`, `__count`. | none: every row of its entity its `where` keeps, whatever the place | a Reading with `on_hand` (a shortfall): the on-hand rows\' groups, beside the Reading\'s own |\n| `<entity>_export_rows` | Every row of <entity> the reader may see, with every field "<template>" may print. | the list\'s | an Export of the register that fills a template |\n| `<entity>_export_rows_of_<source>` | Every row of <entity> the reader may see, with every field "<template>" may print. | the list\'s | an Export over some of a List\'s sources: their rows alone, each source named in turn |\n| `<entity>_moves` | Each move in <history> of the <entity> rows handed in: the status it went to, when and by whom, earliest first. | `<entity>_ids` | an entity whose status keeps a history (`records.status.history`) |\n| `<entity>_plan_load` | How many <entity> rows each <place> holds, over every table the register reads \u2014 the rows with no <place> counted apart. | | a register laid out as a `plan`: its places\' counts of present rows |\n\n<!-- generated:end queries -->\n\nA reading\'s query returns groups, never the rows it read: one row for all of them, or one per value it\nsplits by, or per day. Each row carries the alias of each field it splits by, `__day` where it splits by\nday, `__count`, and `__sum` where it sums a number; its description states which. An average is `__sum`\nover `__count`, both over the rows holding a value.\n\nA Reading is called by its `key` (`reference/reading-node`), and a List that only reads by its `key`, else its entity\'s alias \u2014 wherever its List stands in the app, so a move in the tree changes no name. Each is its own among the app\'s Readings, Lists that only read and Queries.\n\nA register reading\'s query reads the rows it names, whatever a screen has open: the rows of its `tab` where\nit states one, every tab\'s where it states none \u2014 its description says which. One placed in time (`over`)\nreads every day unless the call states `from` or `to`.\n\n### Queries the screen runs for itself\n\nThey run like any other, and `get_app` leaves them out: each feeds one control, and takes ids\nthe screen already holds.\n\n<!-- generated:start screen-queries -->\n\n| Called | What it says of itself | Takes | Generated for |\n|---|---|---|---|\n| `<child>_<link>_target` | One <entity> row by its id, where a <child> row\'s "<link>" may point at it. | `<entity>_id` | a List with `pick` whose link a write rule narrows |\n| `<entity>_<field>_values` | Each "<field>" the <entity> rows hold, once, most held first, narrowed by what the reader typed. | `search`? | a text field a write rule offers values to (`suggest`) |\n| `<entity>_pictures` | The picture and name of each <entity> row among the ids handed in. | `<entity>_ids` | a link to several pictured rows |\n| `<entity>_count_by_<scope>` | How many <entity> rows each <scope entity> holds. | | an app stating `scope` |\n| `<task>_progress_by_<link>` | How many <task> rows each <entity> row handed in holds, at each status. | `<entity>_ids` | rows whose task rows are counted done |\n| `<entity>_sub_counts_by_<link>` | How many <entity> rows stand under each <entity> row handed in, through <link>, at each status. | `<entity>_ids` | a record\'s rows block over a hierarchy (`nests`), for the rows it draws |\n| `<entity>_plan_places` | Every <place> the <entity> rows stand at, with what the plan draws of each. | | a register laid out as a `plan`: the places its rows stand at |\n| `<lane>_lanes` | The <lane> rows of one <scope entity>, each a lane of the board. | `<scope entity>_id` | a lanes board inside an app stating `scope` |\n| `<entity>_same_<link>` | The <entity> rows naming one "<link>". | `same`; `before` where its line reads rows before a moment | a statement line that carries rows (`parts`) |\n\n<!-- generated:end screen-queries -->\n\n### Workflows\n\n<!-- generated:start workflows -->\n\n| Called | What it says of itself | Takes | Generated for |\n|---|---|---|---|\n| `create_<entity>` | Opens one row of <entity>. | every field the add asks, and the link it files the row under; a field the Lists adding the entity hold may be left out | an entity the app adds rows of |\n| `update_<entity>` | Changes one row of <entity>; every input but the row is optional, and one left out is left as it is. | `record_id`, and each field a person edits \u2014 a files field or a link to several rows as `<field>_added` / `<field>_removed` | an entity the app edits |\n| `move_<list>` | Gives rows of <entity> to a <lane> together: every row is judged before any is written, so a refusal leaves them all as they were. `lane` left out leaves the <lane> as it is, `lane` empty clears it; `day` dates only the rows holding none; `order` places each by its number. | `record_ids`, `lane` (left out, the lane stays; empty, none), `day` for the rows holding none, and `order`: each row\'s id and number | a lanes board of days with no hour whose app writes its lane |\n| `remove_<entity>` | Removes one row of <entity>. | `record_id` | an entity the app removes rows of |\n| `restore_<entity>` | Brings back one deleted row of <entity>. | `record_id` | an entity the app removes rows of |\n| `act_<act>` | <label> \u2014 on one row of <entity>, refused where its conditions do not hold. | `record_id` \u2014 `record_ids` on an act over several rows \u2014 and what the act asks | each Act that names no workflow of its own |\n| `archive_<act>` | Hands back every file of <label> on one row of <entity> as one archive. | `record_id` | an Act making a set of papers (`templates`) |\n\n<!-- generated:end workflows -->\n\nA Workflow node is called by its `key`, and every Act by `act_<key>`; an Act that names its own `workflow` is also called by that workflow\'s alias.\n\n## Calling a query\n\n```\nget_app {"app_id":"app_\u2026"}\nrun_app_query {"app_id":"app_\u2026","alias":"order_list","params":{"status_is":"open","due_on_to":"2031-03-14"}}\n```\n\n| Argument | Does |\n|---|---|\n| `params` | The query\'s declared params. A required one is always sent; an optional one left out narrows nothing. A select takes the option\'s alias as `get_app` lists it in `select(label=alias|\u2026)` \u2014 a link a record id, a member a member id, a date `yyyy-mm-dd` |\n| `filters` | Narrows the result further, by the query\'s output columns (`filters`) |\n| `fields` | The output columns to return, in place of all of them; each row then holds them and the id of the record it is |\n| `sort` | An order in place of the query\'s own: `[{ "field_key": "<column>", "order": "asc" }]`, `asc` or `desc`, each `field_key` an output column\'s name |\n| `count` | `true`: `total`, the number of rows, in place of the rows; with `count_by`, `counts` per value of one column, keyed by an option\'s label, a member\'s name or a linked row\'s display; with `count_where` \u2014 a map of name \u2192 filter, never beside `count_by` \u2014 `counts` per name. Never with `fields`, `sort`, `limit` or `cursor` |\n| `aggregate` | Groups of the result in place of its rows, one row per group: `by` (up to 3 columns), `bands` (a number column of `by` grouped by its breakpoints), or `day` (a date column, answered as `__day`), `sum` (a number column, answered as `__sum`) and `avg` (a number column averaged over the group\'s rows that hold one, answered as `__avg`), each group with its `__count`. Sent with `params` and `filters` alone. Buckets are by day only: a period\'s total is one call per period, with `from` and `to` or a date filter |\n| `limit`, `cursor` | A page \u2014 200 rows at most, 50 where no `limit` is stated \u2014 and the `next_cursor` of the page before it; `truncated` says more rows matched than `rows` holds |\n| `runs` | Several reads in one call, 20 at most, each with its own `alias` and arguments, answered in order under `runs`. Never beside an `alias` of the call\'s own |\n\nA query that states its own `limit` lists at most that many rows: `truncated` is `true` where more match, and `total` is\nthe rows the filtered query matches without it. A `count`, `count_by`, `count_where` and an `aggregate` are over every row\nthe query matches, never over the rows its `limit` lists.\n\nThe rows of one call, across its reads, total at most 262,144 bytes: a read past that is refused, naming\n`fields` and `limit` as what narrows it. The names `filters`, `fields`, `sort`, `count_by` and `aggregate`\ntake are the ones on the query\'s `returns` line.\n\nA list\'s params are how a person narrows that register: `search`, the row\'s id on an app that works inside\none row (`scope`), and a param for each filter the register states that one value or a range narrows. A\nfilter with no param \u2014 on a looked-up link or member, on a number read in each row\'s own unit or currency,\non a date holding a span, or on a List of several tables (`sources`) \u2014 is narrowed by `filters`, where a\nnumber condition names the unit its value is in as `unit_option`, an option of the figure\'s select by label\nor key. Each tab of a register is a query of its own, taking the list\'s params and the period its rows are\nread over; a tab\'s totals take the folder\'s id too, in an app that works inside one row.\n\n## Exporting a file\n\n```\nrun_app_query {"app_id":"app_\u2026","export":{"key":"by_carrier","per":"\u2026","tab":"in_yard","status":["\u2026"]}}\n```\n\n`export` makes the file the register\'s Export button makes, from what the caller reads, and answers it under `files` as a workspace\nfile like any other a tool makes: `file_id`, `url`, `filename`, `mime_type`. `key` is the\nkey of an Export of a List in `get_app`\'s tree, at the root or below a row\'s page; it is sent without `alias` or any other argument of a\nread. An option is named by its name or its id, as a read\'s filters name it; a member by its id or its name, for a member\nof the app\'s organization; a row, by its id. The other keys\nnarrow the file as the register\'s own controls do, each absent one leaving the register\'s opening view:\n\n| Key | Takes |\n|---|---|\n| `per` | The option, row id or member id the report is made for \u2014 required by an Export that states `per`, refused by one that does not; a member, here and in a member chip, is an id or a name, found as a filter on a member column finds one |\n| `tab`, `period`, `window` | A Tab\'s key (the first when absent); `{ "from", "to" }` days `yyyy-MM-dd` (`yyyy-MM-ddTHH:mm` on a date-and-time field) the tabs read over; a calendar\'s or board\'s days |\n| `status` | Options of the register\'s status that are kept |\n| `filters` | `{ "<field>": <value> }` by the field\'s alias, a value `null` clearing the register\'s opening chip; a value is one of the shapes below |\n| `search`, `overdue`, `waiting` | Words searched, one line each of a pasted list; `true`: only the rows past a deadline; `true`: only the rows waiting on the caller |\n| `sort`, `group`, `folder` | `{ "field", "dir" }`; a field alias; a folder id |\n| `row` | The id of the row whose rows a List below a row\'s page exports: required there and refused on a root View, and the reader must be able to open that row |\n\n| A `filters` value | For a field that is |\n|---|---|\n| `{ "kind": "ids", "ids": [...], "unset"?: true }` | a select (options) or a link to rows (row ids); `unset` also keeps rows holding none |\n| `{ "kind": "members", "mine": false, "ids": [...], "unset"?: true }` | a member; `mine` is the caller |\n| `{ "kind": "dates", "from": "yyyy-MM-dd" \\| null, "to": \u2026 \\| null, "unset"?: true }` | a date; `null` leaves an end open; `unset` also keeps rows holding none |\n| `{ "kind": "yes_no", "value": true }` | a yes/no |\n| `{ "kind": "number", "min": 1 \\| null, "max": \u2026 \\| null, "unit"?: "\u2026" }` | a number; `unit` the option of a unit or currency field |\n| `{ "kind": "bands", "bands": [{ "min", "max" }] }` | a number the register cuts into tiers |\n\nA key the register lacks, a tab it does not hold or a value its field cannot take is refused, naming it.\n\n## Calling a workflow\n\n```\nrun_app_workflow {"app_id":"app_\u2026","alias":"act_hand_over","inputs":{"record_id":"rec_\u2026"},"dry_run":true}\nrun_app_workflow {"app_id":"app_\u2026","alias":"act_hand_over","inputs":{"record_id":"rec_\u2026"}}\n```\n\n| Argument | Does |\n|---|---|\n| `inputs` | The workflow\'s declared inputs. An update takes the record and only the fields that change |\n| `dry_run` | `true`: the run is made and taken back, so nothing is kept, and the answer is what the run would return, with the calls it would make \u2014 or `status: "not_previewed"` where the workflow cannot be dry-run (`agent_surface/a-dry-run`) |\n| `as_member` | For an organization owner: the run is a dry run, judged as that member would press it \u2014 their stage owners, row rules and app access \u2014 and writes nothing. Anyone else is refused; a record tool takes it the same way, and so do `query_records` and `run_app_query`, which answer what that member would read, and `screenshot_app`, which draws the app as that member sees it |\n| `runs` | Several runs in one call, 50 at most, in order, each its own write, answered under `runs`. The first one refused, failed or not dry-run ends the call. An input `{"from_run": 0, "path": "data.record_id"}` is an earlier run\'s answer at that path. A run states its own `dry_run`, or takes the call\'s. Dry runs one after another share their rows, taken back together, so a run reads what the one before it made; a run reads a dry run\'s answer only from a run dry-run in that stretch |\n\n```\nrun_app_workflow {"app_id":"app_\u2026","runs":[\n {"alias":"create_order","inputs":{"customer":"rec_\u2026","item":"rec_\u2026","due_on":"2031-03-14"}},\n {"alias":"act_hand_over","inputs":{"record_id":{"from_run":0,"path":"data.record_id"}}}\n]}\n```\n\nAn act that reads papers (`intake`) is read by the caller: no platform agent reads for it. Its save `act_<alias>` takes `fields` (what the papers state), `rows` (the child rows listed) and `papers` (`[{"file":"fil_\u2026","kind":"<option>"}]`), and `dry_run` shows the record and rows it would make.\n\n## A dry run\n\nA dry run is the run itself on the real inputs, taken back: it is made in a transaction that is rolled back, so a read after a write reads that write, a branch or a loop walks the values the run would hold, and a call fed by an earlier call\'s answer gets it. No row, number, event, audit entry or table workflow outlives it. A write of the workspace\'s rows is made by its table \u2014 checks, write rules, stage owners \u2014 and the first refusal is the dry run\'s answer. A connected service\'s read-only call is made; a service write, a send, a notification or a button that runs another workflow is not, and is answered as a "would" with its payload. A guard (`when`, `requires`, a check, a lock) refuses it with the press\'s own sentence. A paper it makes is rendered for the answer and its file is removed with the dry run; an act that makes a paper is dry-run like any other, never refused for it. A body that sets the record\'s status also answers `moves`. Its answer carries `status`,\n`message`, `field_errors` and `data` as the run would return them, and under `dry_run`:\n\n| Key | Holds |\n|---|---|\n| `available` | `true` |\n| `writes` | The calls the run would make that are not reads, in order. The app\'s owner and an admin, who may read the workflow\'s body, read each call\'s `step_id`, `tool_name` and `input`. Another member reads each step that would write once: its `step_id` and `tool_name`, and where the step states them outright, the `table_id` it names and how many `records` it lists |\n| `reads` | The reads made for real, in order, each with its `input` and what it `returned` (cut at 2,000 characters, `truncated`), for the app\'s owner and an admin |\n| `papers` | Each paper rendered: its `step_id` and `filename`. The file is not kept |\n| `unpredicted` | The parts of the answer left out \u2014 `message`, `field_errors`, `data` \u2014 because each reads what a call the dry run did not make would answer |\n\nWhat a write sets off once it commits \u2014 a table\'s own workflows, its events \u2014 does not happen in a dry run.\n\nA workflow is not dry-run where its body reads the answer of a call that leaves the workspace, to branch,\nloop, check or feed another call, where it reads or writes rows after such a call (the run would find them as\nthat call left them), where it runs an agent, where it waits, where a step cannot be evaluated, fails\nfor a reason that is no table\'s refusal, or sends its call an input the call refuses, and where the run is past\nwhat one dry run walks \u2014 its steps, the passes of a loop, 50 reads, 50 writes or 20 seconds, which the runs of\none call share and the database holds it to: a lock wait that outlasts them ends the dry run. The\nanswer is then `status: "not_previewed"` with\n`dry_run: { "available": false, "reason" }`, and nothing ran \u2014 within `runs`, it ends the call. The same\nanswers a caller outside the app\'s organization.\n\n## A reviewed act\n\nAn act that states `review` runs a workflow that only proposes: call it with the inputs the act asks and it answers,\nwriting nothing, the changeset its body proposes in `data.review` \u2014 `table_id`, `creates` (each with its `key`) and\n`updates` (each with its `record_id`), each row\'s `data` holding only the fields that change, by field alias, with an\noptional `note` and `ticked` (`false` where the body leaves it for a person to choose), and `unplaced`, what was read\nand matched nothing; the platform adds a `sha` to every row. Call it again with the same inputs and `approved`,\n`{ "updates": [{ "record_id", "sha" }], "creates": [{ "key", "sha" }] }`, listing the rows to write with the `sha` each\ncarries in the proposal, copied as it came \u2014 never computed \u2014 and the platform writes those rows as that second call\nproposes them, each only where it proposes the values read:\n\n```\nrun_app_workflow {"app_id":"app_\u2026","alias":"match_statement","inputs":{"record_ids":["rec_\u2026"],"statement":"fil_\u2026"}}\nrun_app_workflow {"app_id":"app_\u2026","alias":"match_statement","inputs":{"record_ids":["rec_\u2026"],"statement":"fil_\u2026","approved":{"updates":[{"record_id":"rec_\u2026","sha":"9f2c\u2026"}],"creates":[{"key":"line-4","sha":"41d0\u2026"}]}}}\n```\n\nThe answer\'s `data.applied` names the run (`execution_id`), the records `updated`, what each held before (`previous`), each `created` record by its key,\nand each approved row `left` with its `reason`: `not_proposed` (the second call no longer proposes it), `not_acted`\n(an update of a record the act was not run on), `changed` (the second call proposes other values than were read \u2014 read\nthe proposal again), `empty` (an update changing no field), `missing`, `locked` or `conflict`. Every approved row is\nchecked before any is written, and all are written in one transaction or none; the status history of each row written\nthat moved is recorded by the same run. `applied.previous` holds, for each record in `updated`, what the fields the call wrote held before (null for an empty one): `update_records` with it as `set` puts them back, and `delete_records` of a `created` record takes that row away. An act over every\nrow in view takes no `record_ids`. A `file` input takes the id of a file uploaded to the workspace.\n\nAn Act that `makes` a cadence\'s rows proposes the same way with no body: `creates` are the child rows still owed, each\n`key` `<parent id>|<day>`, a row its write would refuse unticked with the refusal as its `note`, and `unplaced` says what\nstays off the pattern and how many closed days were skipped.\n\n## A refusal\n\nA workflow re-checks on the server what the screen shows of its own act or save: what an act requires, a\nduplicate, whose step it is, a row the caller may not see. Each write it makes also meets the table\'s own\nrules (a bound, a span, a stage\'s owner, its lock), which hold on every path a record is written by. A row its table\nlocked is refused in every app\'s act and save, naming who can change it; an app\'s own Check only makes a row read-only\nin that app. An unlock in an app\'s run is judged as the member it runs for, never the app\'s owner. A run refused\nbefore it writes writes nothing; one whose later write a table\'s rule refuses keeps the writes before it.\nEither answers `status: "error"` with the sentence a person would read as `message`, and under `field_errors`\nthe sentence for each input it was refused over. A value of the wrong type, a missing required input and an unknown\nalias are refused before the body runs: the call itself fails with the sentence, and `field_errors` where\nan input is at fault \u2014 within `runs`, a run refused for its inputs answers `status: "error"` in its place,\nand the runs before it stand. A refused read fails the same way, naming the param or the column; within\n`runs`, it answers its `error` and the other reads are still answered.\n\n## Declaring more\n\nWhat the business asks an agent in the app again and again, and no screen draws, is stated in the app\'s tree as Query and Workflow nodes, beside its\nActs: every figure or list whose definition is the business\'s own (open orders, what a customer owes, low stock) and every recurring operation (close the month, send to the accounting service, chase overdue invoices), each with a `description` written for an agent. A question asked once stays on `query_records` with `aggregate`. A Workflow gets an Act only where a person presses it; work only an agent does has no button. Both are checked and compiled when the tree is written (`set_app`; `reference/query-node`, `reference/workflow-node`).\n\n**What the data decides, the system decides.** Whatever follows from the rows and the rules is stated where it holds for every writer, never left to a caller: a fact of one row in its table (`required`, `unique`, `min` and `max`, `options_where`, a check); a value that follows from others as a formula, a lookup or `default_from`; a step of the work in the status\'s `stages` and its Acts (`when`, `requires`); who reads which rows in the table\'s `read_scope` and the app\'s `rows`; what a write sets off in a table\'s workflow; and a decision over many rows or papers (which papers a household\'s facts call for) in a Workflow that computes it and refuses what breaks it, every call the same. A caller\'s inputs are what only it knows: the facts it read, a judgement it made. An override of what the system computes is an optional input, never the way the work is done. A Workflow refuses only what would leave a row invalid or put a false statement on a paper, naming the fact that fixes it; what leaves room for error but is not wrong (a blank printed for handwriting, an unusual choice) it does and reports as a warning in what it returns.\n\n**A query** \u2014 the rows of one table, or one figure of them, in the app\'s own aliases:\n\n```jsonc\n{\n "type": "Query",\n "key": "orders_overdue",\n "description": "A customer\'s orders still open past the day they were due, longest overdue first.",\n "params": {\n "customer": { "type": "record_link", "entity": "customer", "required": false, "description": "Only this customer\'s orders." },\n "as_of": { "type": "date", "description": "The day an order is overdue on: due before it." }\n },\n "rows": "order",\n "fields": ["customer", "item", "due_on", "price"],\n "where": { "status": ["baking"], "customer": { "param": "customer" }, "due_on": { "to": { "param": "as_of" } } },\n "sort": { "field": "due_on" }\n}\n```\n\nIt reads under the app\'s `rows` (every row, where the app states none of the table) and, on the app\'s own table, exactly the rows its list reads \u2014\nso never the table of an app whose List reads `sources`, several tables. A condition reading an\noptional param narrows nothing when the call leaves it out; no param compares a number read in each row\'s\nown unit or currency, or a date holding a span. A Query returns its `fields`; a caller counts, sums or\naverages them with `run_app_query`\'s `aggregate`. A Query, a Workflow and\na Reading\'s `key` take no name the app generates (`reference/app.generated-name`).\n\n**A workflow** \u2014 a write no Act of the record makes, typed in the app\'s tree and its code set on the app:\n\n```jsonc\n{\n "type": "Workflow",\n "key": "import_bookings",\n "description": "Books every order a sheet lists, reusing an order the sheet already booked.",\n "inputs": {\n "sheet": { "type": "file", "description": "The order sheet, one order per row." },\n "booked_by": { "type": "member", "required": false, "description": "Who the orders are taken by; absent, the caller." }\n },\n "outputs": { "added": { "type": "number" }, "reused": { "type": "number" } }\n}\n```\n\n`set_workflow` sets its code (`workflows`). A query the app holds that\nthe tree does not declare is listed by `get_app` as `unstated_queries` and removed by the next write,\nwhose answer notes it; declared as a Query node, it is the tree\'s. A caller sees the description and\neach input\'s `description` and nothing else, so each says what the value is and what leaving it out means;\nthe check notes one that says nothing.\n\n**Shape each for a caller that is not looking at a screen.** One job a person hands an agent \u2014 a paper read,\na message answered, a sheet brought in \u2014 is one declared workflow named for the job, never a chain of the\ngenerated per-row workflows. Take a list where the job covers many rows, a record\'s lines among them. A workflow\'s code\nthat writes more than one row makes them in one `save_record` workflow step, all or nothing, and recognises\nwhat exists by the identity the input itself carries, declared unique on its table, so the same input sent\ntwice updates instead of adding. Return the ids under `outputs`, so the next run can read them. Gate what\ncannot be undone behind an approval step.\n\n## Prove an app as an agent\n\nRun on one of the owner\'s own rows, moved only as far as its stage; a record made for the run takes a number and a stage move nobody asked for.\n\n1. `get_app` \u2014 every job the app\'s `description` names has an alias that does it or reads it.\n2. `run_app_query` the list with no param, then with each param a person would narrow by; `count: true`\n answers how many without the rows.\n3. `run_app_query` `<entity>_record` with one row\'s id, and each `<child>_by_<link>` under it.\n4. `run_app_workflow` an act with `dry_run: true`, then without.\n5. `run_app_workflow` an act its record is not ready for: the answer is `status: "error"` with the sentence\n the screen would show.\n6. `run_app_workflow` the app\'s job workflow with the input a person would hand it \u2014 the paper read, the row:\n it completes in one call. Call it again with the same input: nothing is added.\n';
|
|
1892
|
+
var agent_surface_default = '# An app\'s agent surface\n\nEverything a person reads or does in an app, an agent reads or does through that app\'s **queries** and\n**workflows** \u2014 the same ones its screen runs, under the same permissions and the same rules. Three tools\nreach them, over MCP and as `lotics run <tool>`:\n\n| Tool | Answers |\n|---|---|\n| `get_app` | The app\'s `catalog`: its queries and workflows by alias, each one\'s description, its params or inputs with their types and legal values, and under a query\'s line its output columns (`returns`) \u2014 beside what each table they name holds, in its owner\'s words \u2014 and, for the app\'s author, `notes`: what its stored tree compiles with, each at its address under its rule id (`list.layout-call`, a root List drawing a table over rows a board layout would draw, with the layouts to state; `list.filter-unshown`, a filter no row draws, which the app leaves out) |\n| `run_app_query` | The rows, a count or the groups of one query \u2014 or of several in one call |\n| `run_app_workflow` | One write \u2014 or several in order \u2014 or a dry run of it that writes nothing |\n\nAn app generates this surface from its tree; Query and Workflow nodes declare what the screen never\nasks (`agent_surface/declaring-more`). Every root List of an app (a change may add one at any time) is part of it: each List\'s list, its rows by id, its page\'s\nLists and its Acts are queries and workflows of the same app, named by that List\'s table \u2014 `get_app` lists them in the\none roster, and nothing of a root List is another app\'s. Every caller the app is shared with is answered them, its rows narrowed by the app\'s row rules. A custom-code app\'s surface is the queries and workflows bound on it\n(`app_bindings`).\n\n## Finding what an app offers\n\n`get_workspace` maps the workspace. Its `search` matches the keys and descriptions of the Query and Workflow nodes an app declares, and the app\'s line names the matching keys; it never matches the generated `act_`, `create_` or `update_` aliases. `get_app` then gives the contracts. An agent runs a declared node before it falls back to `query_records`.\n\n## What every app generates\n\nA name in angle brackets is the app\'s alias for that thing; an `<entity>` is the alias of a table the app reads. `get_app` lists the ones a given\napp has.\n\n### Queries\n\n<!-- generated:start queries -->\n\n| Called | What it says of itself | Takes | Generated for |\n|---|---|---|---|\n| `<entity>_list` | Every row of <entity> the reader may see. | `search`?; `<scope entity>_id` where the app states `scope`; `<filter>_is`? per List `filters` field holding one value \u2014 a select, a one-row link, a member, a yes/no; `<filter>_from`? / `<filter>_to`? per date filter \u2014 none for a date holding a span; `<filter>_min`? / `<filter>_max`? per number filter \u2014 none over sources, none for a looked-up link or member, none for a number read in each row\'s own unit or currency | every entity the app draws; the filter params on the app\'s own entity alone; a root List after the first over an entity, whose chips differ from the first\'s, adds one of its own, called by its key |\n| `<entity>_list_<tab>` | The <entity> rows of the tab "<tab>". | the list\'s; `from`? / `to`? on a tab dated `in` a period; `to` on a tab of rows `open` on a day | each Tab of the register, and of each later root List over an entity, called by its key; none over sources, none for a Tab whose period reads a date holding a span |\n| `<entity>_totals_<tab>` | The <child> rows added per <entity> row, by "<link>", over the period from `from` to `to`, dated by "<date>": . | `from`; `to` | each Tab of the register stating `totals`, and of each later root List over an entity, called by its key |\n| `<entity>_record` | One row of <entity> by its id. | `<entity>_id` | every entity the app draws |\n| `<child>_by_<link>` | The <child> rows under one <entity>, through "<link>". | `<entity>_id` | each List of child rows on the record; one narrowed by `where` or ordered by `sort` adds `_<field>_<option>` and `_sorted_<field>` to its name |\n| `outside_<key>_one` | One row of <entity> by its id. | `record` | each Outside: the record a link opens, projected to the fields the Outside states |\n| `outside_<key>_<child>` | The <child> rows under one <entity>, through "<link>". | `record` | each List of an Outside: the rows under the record a link opens, projected to the List\'s columns |\n| `<child>_by_<link>_days` | The <child> rows of the <entity> rows handed in whose "<day>" falls from one day to another. | `<entity>_ids`; `from`; `to` | a roster List: the List of its cells |\n| `<entity>_<link>_pick` | The <target> rows "<link>" may point at, narrowed by what the reader typed. | `search`?; `same_<link>` per `same` link | a written link a write rule narrows (`options_where`, `same`) |\n| `<child>_by_<link>_picks` | The <child> rows no <entity> holds through "<link>" yet, that one <entity> may pick, narrowed by what the reader typed. | `search`?; `same_<link>` per `same` link | a List with `pick`: it picks existing rows into the record |\n| `<key>` | <label>: how many <entity> rows there are. Each row carries `__count`. | the list\'s; `from`? / `to`? where the reading states `over`, or its `tab` is dated `in` a period; `to` where its `tab` is of rows `open` on a day | each Reading of a List\'s band, called by its `key` \u2014 but the work against its plan (a Reading stating `planned` and `done`), which reads the List\'s own rows; none over sources |\n| `<key>` | <label>: how many <entity> rows there are. Each row carries `__count`. | `from`? / `to`? where the reading states `over` | each Reading and List of a Sheet, called by its `key` |\n| `<key>` | <label>: how many <child> rows there are. Each row carries `__count`. | `<entity>_id`; `same_<field>` where it is a List stating `same`; `record_<field>` per `where` bound to a field of the record | each Reading of a Record page, each List that only reads on it (its `key`, else its entity\'s alias) and each funnel, called by its `key` |\n| `<reading>_bound` | <label> / <bound>: the sum of "<bound>" over the <entity> rows. Each row carries `__count`, `__sum`. | its reading\'s | a Reading whose value `records.limits` bounds: the bound\'s sum, beside the Reading\'s own |\n| `<reading>_on_hand` | <label> / <on-hand entity>: how many <on-hand entity> rows there are, per "<field>". Each row carries `<field>`, `__count`. | none: every row of its entity its `where` keeps, whatever the place | a Reading with `on_hand` (a shortfall): the on-hand rows\' groups, beside the Reading\'s own |\n| `<entity>_export_rows` | Every row of <entity> the reader may see, with every field "<template>" may print. | the list\'s | an Export of the register that fills a template |\n| `<entity>_export_rows_of_<source>` | Every row of <entity> the reader may see, with every field "<template>" may print. | the list\'s | an Export over some of a List\'s sources: their rows alone, each source named in turn |\n| `<entity>_moves` | Each move in <history> of the <entity> rows handed in: the status it went to, when and by whom, earliest first. | `<entity>_ids` | an entity whose status keeps a history (`records.status.history`) |\n| `<entity>_plan_load` | How many <entity> rows each <place> holds, over every table the register reads \u2014 the rows with no <place> counted apart. | | a register laid out as a `plan`: its places\' counts of present rows |\n\n<!-- generated:end queries -->\n\nA reading\'s query returns groups, never the rows it read: one row for all of them, or one per value it\nsplits by, or per day. Each row carries the alias of each field it splits by, `__day` where it splits by\nday, `__count`, and `__sum` where it sums a number; its description states which. An average is `__sum`\nover `__count`, both over the rows holding a value.\n\nA Reading is called by its `key` (`reference/reading-node`), and a List that only reads by its `key`, else its entity\'s alias \u2014 wherever its List stands in the app, so a move in the tree changes no name. Each is its own among the app\'s Readings, Lists that only read and Queries.\n\nA register reading\'s query reads the rows it names, whatever a screen has open: the rows of its `tab` where\nit states one, every tab\'s where it states none \u2014 its description says which. One placed in time (`over`)\nreads every day unless the call states `from` or `to`.\n\n### Queries the screen runs for itself\n\nThey run like any other, and `get_app` leaves them out: each feeds one control, and takes ids\nthe screen already holds.\n\n<!-- generated:start screen-queries -->\n\n| Called | What it says of itself | Takes | Generated for |\n|---|---|---|---|\n| `<child>_<link>_target` | One <entity> row by its id, where a <child> row\'s "<link>" may point at it. | `<entity>_id` | a List with `pick` whose link a write rule narrows |\n| `<entity>_<field>_values` | Each "<field>" the <entity> rows hold, once, most held first, narrowed by what the reader typed. | `search`? | a text field a write rule offers values to (`suggest`) |\n| `<entity>_pictures` | The picture and name of each <entity> row among the ids handed in. | `<entity>_ids` | a link to several pictured rows |\n| `<entity>_count_by_<scope>` | How many <entity> rows each <scope entity> holds. | | an app stating `scope` |\n| `<task>_progress_by_<link>` | How many <task> rows each <entity> row handed in holds, at each status. | `<entity>_ids` | rows whose task rows are counted done |\n| `<entity>_sub_counts_by_<link>` | How many <entity> rows stand under each <entity> row handed in, through <link>, at each status. | `<entity>_ids` | a record\'s rows block over a hierarchy (`nests`), for the rows it draws |\n| `<entity>_plan_places` | Every <place> the <entity> rows stand at, with what the plan draws of each. | | a register laid out as a `plan`: the places its rows stand at |\n| `<lane>_lanes` | The <lane> rows of one <scope entity>, each a lane of the board. | `<scope entity>_id` | a lanes board inside an app stating `scope` |\n| `<entity>_same_<link>` | The <entity> rows naming one "<link>". | `same`; `before` where its line reads rows before a moment | a statement line that carries rows (`parts`) |\n\n<!-- generated:end screen-queries -->\n\n### Workflows\n\n<!-- generated:start workflows -->\n\n| Called | What it says of itself | Takes | Generated for |\n|---|---|---|---|\n| `create_<entity>` | Opens one row of <entity>. | every field the add asks, and the link it files the row under; a field the Lists adding the entity hold may be left out | an entity the app adds rows of |\n| `update_<entity>` | Changes one row of <entity>; every input but the row is optional, and one left out is left as it is. | `record_id`, and each field a person edits \u2014 a files field or a link to several rows as `<field>_added` / `<field>_removed` | an entity the app edits |\n| `move_<list>` | Gives rows of <entity> to a <lane> together: every row is judged before any is written, so a refusal leaves them all as they were. `lane` left out leaves the <lane> as it is, `lane` empty clears it; `day` dates only the rows holding none; `order` places each by its number. | `record_ids`, `lane` (left out, the lane stays; empty, none), `day` for the rows holding none, and `order`: each row\'s id and number | a lanes board of days with no hour whose app writes its lane |\n| `remove_<entity>` | Removes one row of <entity>. | `record_id` | an entity the app removes rows of |\n| `restore_<entity>` | Brings back one deleted row of <entity>. | `record_id` | an entity the app removes rows of |\n| `act_<act>` | <label> \u2014 on one row of <entity>, refused where its conditions do not hold. | `record_id` \u2014 `record_ids` on an act over several rows \u2014 and what the act asks | each Act that names no workflow of its own |\n| `archive_<act>` | Hands back every file of <label> on one row of <entity> as one archive. | `record_id` | an Act making a set of papers (`templates`) |\n\n<!-- generated:end workflows -->\n\nA Workflow node is called by its `key`, and every Act by `act_<key>`; an Act that names its own `workflow` is also called by that workflow\'s alias.\n\n## Calling a query\n\n```\nget_app {"app_id":"app_\u2026"}\nrun_app_query {"app_id":"app_\u2026","alias":"order_list","params":{"status_is":"open","due_on_to":"2031-03-14"}}\n```\n\n| Argument | Does |\n|---|---|\n| `params` | The query\'s declared params. A required one is always sent; an optional one left out narrows nothing. A select takes the option\'s alias as `get_app` lists it in `select(label=alias|\u2026)` \u2014 a link a record id, a member a member id, a date `yyyy-mm-dd` |\n| `filters` | Narrows the result further, by the query\'s output columns (`filters`) |\n| `fields` | The output columns to return, in place of all of them; each row then holds them and the id of the record it is |\n| `sort` | An order in place of the query\'s own: `[{ "field_key": "<column>", "order": "asc" }]`, `asc` or `desc`, each `field_key` an output column\'s name |\n| `count` | `true`: `total`, the number of rows, in place of the rows; with `count_by`, `counts` per value of one column, keyed by an option\'s label, a member\'s name or a linked row\'s display; with `count_where` \u2014 a map of name \u2192 filter, never beside `count_by` \u2014 `counts` per name. Never with `fields`, `sort`, `limit` or `cursor` |\n| `aggregate` | Groups of the result in place of its rows, one row per group: `by` (up to 3 columns), `bands` (a number column of `by` grouped by its breakpoints), or `day` (a date column, answered as `__day`), `sum` (a number column, answered as `__sum`) and `avg` (a number column averaged over the group\'s rows that hold one, answered as `__avg`), each group with its `__count`. Sent with `params` and `filters` alone. Buckets are by day only: a period\'s total is one call per period, with `from` and `to` or a date filter |\n| `limit`, `cursor` | A page \u2014 200 rows at most, 50 where no `limit` is stated \u2014 and the `next_cursor` of the page before it; `truncated` says more rows matched than `rows` holds |\n| `runs` | Several reads in one call, 20 at most, each with its own `alias` and arguments, answered in order under `runs`. Never beside an `alias` of the call\'s own |\n\nA query that states its own `limit` lists at most that many rows: `truncated` is `true` where more match, and `total` is\nthe rows the filtered query matches without it. A `count`, `count_by`, `count_where` and an `aggregate` are over every row\nthe query matches, never over the rows its `limit` lists.\n\nThe rows of one call, across its reads, total at most 262,144 bytes: a read past that is refused, naming\n`fields` and `limit` as what narrows it. The names `filters`, `fields`, `sort`, `count_by` and `aggregate`\ntake are the ones on the query\'s `returns` line.\n\nA list\'s params are how a person narrows that register: `search`, the row\'s id on an app that works inside\none row (`scope`), and a param for each filter the register states that one value or a range narrows. A\nfilter with no param \u2014 on a looked-up link or member, on a number read in each row\'s own unit or currency,\non a date holding a span, or on a List of several tables (`sources`) \u2014 is narrowed by `filters`, where a\nnumber condition names the unit its value is in as `unit_option`, an option of the figure\'s select by label\nor key. Each tab of a register is a query of its own, taking the list\'s params and the period its rows are\nread over; a tab\'s totals take the folder\'s id too, in an app that works inside one row.\n\n## Exporting a file\n\n```\nrun_app_query {"app_id":"app_\u2026","export":{"key":"by_carrier","per":"\u2026","tab":"in_yard","status":["\u2026"]}}\n```\n\n`export` makes the file the register\'s Export button makes, from what the caller reads, and answers it under `files` as a workspace\nfile like any other a tool makes: `file_id`, `url`, `filename`, `mime_type`. `key` is the\nkey of an Export of a List in `get_app`\'s tree, at the root or below a row\'s page; it is sent without `alias` or any other argument of a\nread. An option is named by its name or its id, as a read\'s filters name it; a member by its id or its name, for a member\nof the app\'s organization; a row, by its id. The other keys\nnarrow the file as the register\'s own controls do, each absent one leaving the register\'s opening view:\n\n| Key | Takes |\n|---|---|\n| `per` | The option, row id or member id the report is made for \u2014 required by an Export that states `per`, refused by one that does not; a member, here and in a member chip, is an id or a name, found as a filter on a member column finds one |\n| `tab`, `period`, `window` | A Tab\'s key (the first when absent); `{ "from", "to" }` days `yyyy-MM-dd` (`yyyy-MM-ddTHH:mm` on a date-and-time field) the tabs read over; a calendar\'s or board\'s days |\n| `status` | Options of the register\'s status that are kept |\n| `filters` | `{ "<field>": <value> }` by the field\'s alias, a value `null` clearing the register\'s opening chip; a value is one of the shapes below |\n| `search`, `overdue`, `waiting` | Words searched, one line each of a pasted list; `true`: only the rows past a deadline; `true`: only the rows waiting on the caller |\n| `sort`, `group`, `folder` | `{ "field", "dir" }`; a field alias; a folder id |\n| `row` | The id of the row whose rows a List below a row\'s page exports: required there and refused on a root View, and the reader must be able to open that row |\n\n| A `filters` value | For a field that is |\n|---|---|\n| `{ "kind": "ids", "ids": [...], "unset"?: true }` | a select (options) or a link to rows (row ids); `unset` also keeps rows holding none |\n| `{ "kind": "members", "mine": false, "ids": [...], "unset"?: true }` | a member; `mine` is the caller |\n| `{ "kind": "dates", "from": "yyyy-MM-dd" \\| null, "to": \u2026 \\| null, "unset"?: true }` | a date; `null` leaves an end open; `unset` also keeps rows holding none |\n| `{ "kind": "yes_no", "value": true }` | a yes/no |\n| `{ "kind": "number", "min": 1 \\| null, "max": \u2026 \\| null, "unit"?: "\u2026" }` | a number; `unit` the option of a unit or currency field |\n| `{ "kind": "bands", "bands": [{ "min", "max" }] }` | a number the register cuts into tiers |\n\nA key the register lacks, a tab it does not hold or a value its field cannot take is refused, naming it.\n\n## Calling a workflow\n\n```\nrun_app_workflow {"app_id":"app_\u2026","alias":"act_hand_over","inputs":{"record_id":"rec_\u2026"},"dry_run":true}\nrun_app_workflow {"app_id":"app_\u2026","alias":"act_hand_over","inputs":{"record_id":"rec_\u2026"}}\n```\n\n| Argument | Does |\n|---|---|\n| `inputs` | The workflow\'s declared inputs. An update takes the record and only the fields that change |\n| `dry_run` | `true`: the run is made and taken back, so nothing is kept, and the answer is what the run would return, with the calls it would make \u2014 or `status: "not_previewed"` where the workflow cannot be dry-run (`agent_surface/a-dry-run`) |\n| `as_member` | For an organization owner: the run is a dry run, judged as that member would press it \u2014 their stage owners, row rules and app access \u2014 and writes nothing. Anyone else is refused; a record tool takes it the same way, and so do `query_records` and `run_app_query`, which answer what that member would read, and `screenshot_app`, which draws the app as that member sees it |\n| `runs` | Several runs in one call, 50 at most, in order, each its own write, answered under `runs`. The first one refused, failed or not dry-run ends the call. An input `{"from_run": 0, "path": "data.record_id"}` is an earlier run\'s answer at that path. A run states its own `dry_run`, or takes the call\'s. Dry runs one after another share their rows, taken back together, so a run reads what the one before it made; a run reads a dry run\'s answer only from a run dry-run in that stretch |\n\n```\nrun_app_workflow {"app_id":"app_\u2026","runs":[\n {"alias":"create_order","inputs":{"customer":"rec_\u2026","item":"rec_\u2026","due_on":"2031-03-14"}},\n {"alias":"act_hand_over","inputs":{"record_id":{"from_run":0,"path":"data.record_id"}}}\n]}\n```\n\nA run that makes a paper answers it under `files`, as an export does: `file_id`, `url`, `filename`, `mime_type`; a dry run keeps none.\n\nAn act that reads papers (`intake`) is read by the caller: no platform agent reads for it. Its save `act_<alias>` takes `fields` (what the papers state), `rows` (the child rows listed) and `papers` (`[{"file":"fil_\u2026","kind":"<option>"}]`), and `dry_run` shows the record and rows it would make.\n\n## A dry run\n\nA dry run is the run itself on the real inputs, taken back: it is made in a transaction that is rolled back, so a read after a write reads that write, a branch or a loop walks the values the run would hold, and a call fed by an earlier call\'s answer gets it. No row, number, event, audit entry or table workflow outlives it. A write of the workspace\'s rows is made by its table \u2014 checks, write rules, stage owners \u2014 and the first refusal is the dry run\'s answer. A connected service\'s read-only call is made; a service write, a send, a notification or a button that runs another workflow is not, and is answered as a "would" with its payload. A guard (`when`, `requires`, a check, a lock) refuses it with the press\'s own sentence. A paper it makes is rendered for the answer and its file is removed with the dry run; an act that makes a paper is dry-run like any other, never refused for it. A body that sets the record\'s status also answers `moves`. Its answer carries `status`,\n`message`, `field_errors` and `data` as the run would return them, and under `dry_run`:\n\n| Key | Holds |\n|---|---|\n| `available` | `true` |\n| `writes` | The calls the run would make that are not reads, in order. The app\'s owner and an admin, who may read the workflow\'s body, read each call\'s `step_id`, `tool_name` and `input`. Another member reads each step that would write once: its `step_id` and `tool_name`, and where the step states them outright, the `table_id` it names and how many `records` it lists |\n| `reads` | The reads made for real, in order, each with its `input` and what it `returned` (cut at 2,000 characters, `truncated`), for the app\'s owner and an admin |\n| `papers` | Each paper rendered: its `step_id` and `filename`. The file is not kept |\n| `unpredicted` | The parts of the answer left out \u2014 `message`, `field_errors`, `data` \u2014 because each reads what a call the dry run did not make would answer |\n\nWhat a write sets off once it commits \u2014 a table\'s own workflows, its events \u2014 does not happen in a dry run.\n\nA workflow is not dry-run where its body reads the answer of a call that leaves the workspace, to branch,\nloop, check or feed another call, where it reads or writes rows after such a call (the run would find them as\nthat call left them), where it runs an agent, where it waits, where a step cannot be evaluated, fails\nfor a reason that is no table\'s refusal, or sends its call an input the call refuses, and where the run is past\nwhat one dry run walks \u2014 its steps, the passes of a loop, 50 reads, 50 writes or 20 seconds, which the runs of\none call share and the database holds it to: a lock wait that outlasts them ends the dry run. The\nanswer is then `status: "not_previewed"` with\n`dry_run: { "available": false, "reason" }`, and nothing ran \u2014 within `runs`, it ends the call. The same\nanswers a caller outside the app\'s organization.\n\n## A reviewed act\n\nAn act that states `review` runs a workflow that only proposes: call it with the inputs the act asks and it answers,\nwriting nothing, the changeset its body proposes in `data.review` \u2014 `table_id`, `creates` (each with its `key`) and\n`updates` (each with its `record_id`), each row\'s `data` holding only the fields that change, by field alias, with an\noptional `note` and `ticked` (`false` where the body leaves it for a person to choose), and `unplaced`, what was read\nand matched nothing; the platform adds a `sha` to every row. Call it again with the same inputs and `approved`,\n`{ "updates": [{ "record_id", "sha" }], "creates": [{ "key", "sha" }] }`, listing the rows to write with the `sha` each\ncarries in the proposal, copied as it came \u2014 never computed \u2014 and the platform writes those rows as that second call\nproposes them, each only where it proposes the values read:\n\n```\nrun_app_workflow {"app_id":"app_\u2026","alias":"match_statement","inputs":{"record_ids":["rec_\u2026"],"statement":"fil_\u2026"}}\nrun_app_workflow {"app_id":"app_\u2026","alias":"match_statement","inputs":{"record_ids":["rec_\u2026"],"statement":"fil_\u2026","approved":{"updates":[{"record_id":"rec_\u2026","sha":"9f2c\u2026"}],"creates":[{"key":"line-4","sha":"41d0\u2026"}]}}}\n```\n\nThe answer\'s `data.applied` names the run (`execution_id`), the records `updated`, what each held before (`previous`), each `created` record by its key,\nand each approved row `left` with its `reason`: `not_proposed` (the second call no longer proposes it), `not_acted`\n(an update of a record the act was not run on), `changed` (the second call proposes other values than were read \u2014 read\nthe proposal again), `empty` (an update changing no field), `missing`, `locked` or `conflict`. Every approved row is\nchecked before any is written, and all are written in one transaction or none; the status history of each row written\nthat moved is recorded by the same run. `applied.previous` holds, for each record in `updated`, what the fields the call wrote held before (null for an empty one): `update_records` with it as `set` puts them back, and `delete_records` of a `created` record takes that row away. An act over every\nrow in view takes no `record_ids`. A `file` input takes the id of a file uploaded to the workspace.\n\nAn Act that `makes` a cadence\'s rows proposes the same way with no body: `creates` are the child rows still owed, each\n`key` `<parent id>|<day>`, a row its write would refuse unticked with the refusal as its `note`, and `unplaced` says what\nstays off the pattern and how many closed days were skipped.\n\n## A refusal\n\nA workflow re-checks on the server what the screen shows of its own act or save: what an act requires, a\nduplicate, whose step it is, a row the caller may not see. Each write it makes also meets the table\'s own\nrules (a bound, a span, a stage\'s owner, its lock), which hold on every path a record is written by. A row its table\nlocked is refused in every app\'s act and save, naming who can change it; an app\'s own Check only makes a row read-only\nin that app. An unlock in an app\'s run is judged as the member it runs for, never the app\'s owner. A run refused\nbefore it writes writes nothing; one whose later write a table\'s rule refuses keeps the writes before it.\nEither answers `status: "error"` with the sentence a person would read as `message`, and under `field_errors`\nthe sentence for each input it was refused over. A value of the wrong type, a missing required input and an unknown\nalias are refused before the body runs: the call itself fails with the sentence, and `field_errors` where\nan input is at fault \u2014 within `runs`, a run refused for its inputs answers `status: "error"` in its place,\nand the runs before it stand. A refused read fails the same way, naming the param or the column; within\n`runs`, it answers its `error` and the other reads are still answered.\n\n## Declaring more\n\nWhat the business asks an agent in the app again and again, and no screen draws, is stated in the app\'s tree as Query and Workflow nodes, beside its\nActs: every figure or list whose definition is the business\'s own (open orders, what a customer owes, low stock) and every recurring operation (close the month, send to the accounting service, chase overdue invoices), each with a `description` written for an agent. A question asked once stays on `query_records` with `aggregate`. A Workflow gets an Act only where a person presses it; work only an agent does has no button. Both are checked and compiled when the tree is written (`set_app`; `reference/query-node`, `reference/workflow-node`).\n\n**What the data decides, the system decides.** Whatever follows from the rows and the rules is stated where it holds for every writer, never left to a caller: a fact of one row in its table (`required`, `unique`, `min` and `max`, `options_where`, a check); a value that follows from others as a formula, a lookup or `default_from`; a step of the work in the status\'s `stages` and its Acts (`when`, `requires`); who reads which rows in the table\'s `read_scope` and the app\'s `rows`; what a write sets off in a table\'s workflow; and a decision over many rows or papers (which papers a household\'s facts call for) in a Workflow that computes it and refuses what breaks it, every call the same. A caller\'s inputs are what only it knows: the facts it read, a judgement it made. An override of what the system computes is an optional input, never the way the work is done. A Workflow refuses only what would leave a row invalid or put a false statement on a paper, naming the fact that fixes it; what leaves room for error but is not wrong (a blank printed for handwriting, an unusual choice) it does and reports as a warning in what it returns.\n\n**A query** \u2014 the rows of one table, or one figure of them, in the app\'s own aliases:\n\n```jsonc\n{\n "type": "Query",\n "key": "orders_overdue",\n "description": "A customer\'s orders still open past the day they were due, longest overdue first.",\n "params": {\n "customer": { "type": "record_link", "entity": "customer", "required": false, "description": "Only this customer\'s orders." },\n "as_of": { "type": "date", "description": "The day an order is overdue on: due before it." }\n },\n "rows": "order",\n "fields": ["customer", "item", "due_on", "price"],\n "where": { "status": ["baking"], "customer": { "param": "customer" }, "due_on": { "to": { "param": "as_of" } } },\n "sort": { "field": "due_on" }\n}\n```\n\nIt reads under the app\'s `rows` (every row, where the app states none of the table) and, on the app\'s own table, exactly the rows its list reads \u2014\nso never the table of an app whose List reads `sources`, several tables. A condition reading an\noptional param narrows nothing when the call leaves it out; no param compares a number read in each row\'s\nown unit or currency, or a date holding a span. A Query returns its `fields`; a caller counts, sums or\naverages them with `run_app_query`\'s `aggregate`. A Query, a Workflow and\na Reading\'s `key` take no name the app generates (`reference/app.generated-name`).\n\n**A workflow** \u2014 a write no Act of the record makes, typed in the app\'s tree and its code set on the app:\n\n```jsonc\n{\n "type": "Workflow",\n "key": "import_bookings",\n "description": "Books every order a sheet lists, reusing an order the sheet already booked.",\n "inputs": {\n "sheet": { "type": "file", "description": "The order sheet, one order per row." },\n "booked_by": { "type": "member", "required": false, "description": "Who the orders are taken by; absent, the caller." }\n },\n "outputs": { "added": { "type": "number" }, "reused": { "type": "number" } }\n}\n```\n\n`set_workflow` sets its code (`workflows`). A query the app holds that\nthe tree does not declare is listed by `get_app` as `unstated_queries` and removed by the next write,\nwhose answer notes it; declared as a Query node, it is the tree\'s. A caller sees the description and\neach input\'s `description` and nothing else, so each says what the value is and what leaving it out means;\nthe check notes one that says nothing.\n\n**Shape each for a caller that is not looking at a screen.** One job a person hands an agent \u2014 a paper read,\na message answered, a sheet brought in \u2014 is one declared workflow named for the job, never a chain of the\ngenerated per-row workflows. Take a list where the job covers many rows, a record\'s lines among them. A workflow\'s code\nthat writes more than one row makes them in one `save_record` workflow step, all or nothing, and recognises\nwhat exists by the identity the input itself carries, declared unique on its table, so the same input sent\ntwice updates instead of adding. Return the ids under `outputs`, so the next run can read them. Gate what\ncannot be undone behind an approval step.\n\n## Prove an app as an agent\n\nRun on one of the owner\'s own rows, moved only as far as its stage; a record made for the run takes a number and a stage move nobody asked for.\n\n1. `get_app` \u2014 every job the app\'s `description` names has an alias that does it or reads it.\n2. `run_app_query` the list with no param, then with each param a person would narrow by; `count: true`\n answers how many without the rows.\n3. `run_app_query` `<entity>_record` with one row\'s id, and each `<child>_by_<link>` under it.\n4. `run_app_workflow` an act with `dry_run: true`, then without.\n5. `run_app_workflow` an act its record is not ready for: the answer is `status: "error"` with the sentence\n the screen would show.\n6. `run_app_workflow` the app\'s job workflow with the input a person would hand it \u2014 the paper read, the row:\n it completes in one call. Call it again with the same input: nothing is added.\n';
|
|
1893
1893
|
|
|
1894
1894
|
// AGENTS.md
|
|
1895
1895
|
var AGENTS_default = "# @lotics/cli \u2014 agent index\n\nThe model an agent needs before driving this CLI: which surface answers which question, what the\nconventions are, and where the traps are.\n\n| Read | For |\n|---|---|\n| `lotics --help` | The verb inventory (\xA7 COMMANDS) and global flags. The verb LIST is generated and never stale; the prose beside each verb is hand-written, so where it disagrees with `docs/cli_reference.md`, the reference wins. |\n| `lotics tools` \xB7 `lotics tools <name>` | The agent tool registry and one tool's full JSON Schema. |\n| `lotics docs` \xB7 `lotics docs <area>[/<section>]` \xB7 `lotics docs [<area>] --grep <text>` | This CLI's references, carried inside it so each describes the binary answering. Capped at a page: a doc that does not fit hands back its opening and the addresses into it, so the next call is smaller than the last. A page the copy lacks \u2014 one the server added since this binary was built, which a refusal can cite \u2014 is read from the server's `docs` tool with this machine's credential, and so is every `--grep`, over the references the server serves. A custom-code app's SDK reference is `node_modules/@lotics/app-sdk/AGENTS.md` inside the app. |\n| `lotics docs reference` \xB7 `lotics docs reference/<section>` | The keys of a table document and the components of an app tree: a table's fields keyed by alias, how a row of each table is recognised (`records`), and the apps stated over them. Every key, every field type with the config it needs, the rules, and a worked example. |\n| `lotics docs design` \xB7 `lotics docs design/<section>` | Designing an app \u2014 the treatment each kind of row takes with the `reference` page stating its keys, the visual bar, looking at what a write built, and the rubric a build answers. Opens on the visual bar; a finding names its section. |\n| `lotics docs examples` \xB7 `lotics docs examples/<treatment>` | Each treatment worked through in an app of a complete workspace: the job, the props to read, where it is the wrong one, and the excerpt. |\n| [docs/getting_started.md](./docs/getting_started.md) | What a workspace holds, and the one page to open for each job: building a workspace, changing an app, a rule on a table, a document, data and questions, a connected service, sharing. The first page an agent outside the product reads. |\n| [docs/build.md](./docs/build.md) | A workspace or an app built call by call \u2014 tables with a check, the paper, the app, what the owner will ask an agent, the owner's rows, pressing it \u2014 in one worked example, at any time: an app added or changed weeks later starts there too. |\n| [docs/app_architecture.md](./docs/app_architecture.md) | Which apps a business needs, one per main entity, with a worked split; who gets each, and which rows each person reads. |\n| [docs/working_in_a_workspace.md](./docs/working_in_a_workspace.md) | The right means for each job once the apps exist: an app's act for a business operation, a record write for data entry, a query for a figure the business defines, a count for the rest. |\n| [docs/cli_reference.md](./docs/cli_reference.md) | Per-command contracts, flags, exit codes, and gotchas \u2014 the detail `--help` compresses. |\n| [docs/data_model.md](./docs/data_model.md) | Tables, their fields, and how they relate \u2014 one fact per column, one table per kind of thing and the NAME-OVERLAP probe that says when a split has broken, one vocabulary wherever values are copied, a copy boundary that accounts for every source field, provenance as a link, a declared natural key, history as rows, and why derived DEPTH costs more than row count; then the choices around a field's type, and how a field is changed (a list replaces whole, what refuses a deletion, what `force` consents to). Separate from build because every workspace starts with tables and many never get an app. |\n| [docs/filters.md](./docs/filters.md) | The one filter grammar every filter-taking tool, view and rollup reads \u2014 conditions, groups, and the operators per field type. |\n| [docs/field_values.md](./docs/field_values.md) | The value each field type takes in a write. |\n| [docs/workflows.md](./docs/workflows.md) | Writing a workflow body \u2014 triggers, steps, what an expression reads, the helpers, approvals and agent steps, and table checks. |\n| [docs/app_bindings.md](./docs/app_bindings.md) | The queries, workflows and agents an app binds \u2014 the query tree, typed inputs and outputs, and an agent's declaration. |\n| [docs/document_templates.md](./docs/document_templates.md) | Generating PDF/Excel/Word/email from reusable templates, and what a template an app's Act makes is handed. |\n| [docs/knowledge_docs.md](./docs/knowledge_docs.md) | Authoring the procedures, policies and glossary an agent can't guess with `set_knowledge`; who can read a doc; searching and reading it line by line. |\n| [docs/migration.md](./docs/migration.md) | What to DO when something an earlier CLI wrote to disk no longer matches what it does \u2014 local app projects are gone, and each verb that read one has a replacement. |\n| [README.md](./README.md) | Install, auth, and worked examples. |\n\n## Two surfaces, and the trap between them\n\n**`lotics tools` is not the CLI's capability list.** There are two disjoint surfaces:\n\n- **Tools** (`lotics tools`, `lotics run <tool>`) \u2014 the *agent tool registry*: what an agent, workflow,\n or automation may call. Workspace data, templates, knowledge, admin.\n- **Commands** (`lotics --help` \xA7 COMMANDS) \u2014 the CLI's *own verbs*: auth and org/workspace scoping,\n file upload and download, and those that touch a local file for an app \u2014 `app apply`,\n `app create --custom`, `app pull` and `app deploy`.\n\nSeveral capabilities exist **only** as commands and appear nowhere in `lotics tools` \u2014 downloading a\nfile is the one most often mistaken for missing. Concluding \"the platform can't do X\" from the tool\nlist alone is a mistake; check both.\n\n**`lotics <verb> --help` prints that verb's entries from \xA7 COMMANDS** (`lotics app --help`,\n`lotics file download --help`); `lotics report --help` prints the report frame. To find out whether\nsomething exists, read `lotics --help` \xA7 COMMANDS \u2014 the whole section, not a narrow grep.\n\n## Conventions that hold across every command\n\n- **Scope is resolved per invocation.** `LOTICS_ORG` / `LOTICS_WORKSPACE` (or `LOTICS_API_KEY`) scope a\n single call without changing the active org or a directory pin \u2014 the safe way to touch one tenant\n from a shell serving many. Every command that resolves a workspace echoes its target to **stderr**\n (`lotics \u2192 <org> / <workspace>`); read it back before trusting a write. Resolution precedence is\n in README \xA7 Organizations.\n- **A machine with no key can still sign in, and the sign-in never blocks you.** `lotics auth\n login` takes no argument and sends no mail: it prints the page a person opens and the code that page must show,\n records the request, and EXITS. They press Confirm whenever they get to it; the next command that\n NEEDS a credential collects the key before doing its own work, so \"sign in\" costs you one command\n and then re-running what you wanted. Never wrap it in a timeout waiting for a human \u2014 `--wait`\n exists if you really want one blocking command, and killing that one is safe too (the request\n survives and the next command claims it). A command run before Confirm exits 1 naming the page and\n code again; once the 15 minutes are up it says to ask again. `lotics auth signup <email>` for an email that\n already has an account creates nothing and names `auth login`.\n- **A credential is either a SIGN-IN or an API KEY, and `logout` treats them differently.** A profile\n from `auth login` / `auth signup` acts as the person who confirmed it and is theirs \u2014 `lotics auth\n logout` revokes it server-side, and it lapses on its own after 90 idle days (each use pushes that\n out). A profile from `auth api-key` holds a key an ADMIN issued. A key created in Settings carries\n its OWN access \u2014 every app and table, or only the ones chosen on the key, so a listing that comes\n back short is the key's reach, not a bug \u2014 while an older key created FOR a person carries that\n person's access and dies with their membership. Either is routinely also on a server and on\n other machines, so logout only forgets it locally and says so; only an admin revokes it. A profile that states no kind (saved before the field existed) is resolved against the SERVER\n and revoked only if the answer is a sign-in; a bare `--api-key` / `LOTICS_API_KEY` names no\n profile to remove at all. Nothing is ever revoked on a guess \u2014 between two, the destructive one is\n wrong. `lotics auth whoami` prints the kind, asking the server when the store cannot say.\n- **A key created in Settings never administers the organization, whatever its access.** The verbs\n `docs/cli_reference.md` reserves to an organization owner or a workspace admin split in two under a key: `workspace doctor`, which only\n reads inside a workspace the key reaches, runs as before, while managing people, sharing or\n ownership, creating or deleting a workspace, changing workspace settings, setting credit limits,\n reading the access log and publishing an app's API answer `403` and name the remedy: an admin signed in, so\n `lotics auth login` and run it again. A sign-in acts as that person and is refused none of\n them. Do not retry a `403` with the same credential and do not ask for a wider key \u2014 no answer on\n the key's own screen grants this.\n- **A 401 names its remedy \u2014 act on the hint, do not retry.** \"This credential expired / was\n revoked / belongs to a member who is no longer active\" carries the one remedy that ends this\n credential: run `lotics auth login` for a sign-in, or ask the admin who issued it for a\n new key. A credential minted before that was recorded carries BOTH, because nothing on the row\n tells them apart \u2014 so on a box with no browser, take the second. Only an UNRECOGNIZED key gets\n the generic \"Invalid or disabled API key\", and that one is generic on purpose, so re-sending it\n teaches nothing. A `reason` rides on the body for a script to branch on, since the code stays\n `unauthorized` for every 401.\n- **Large payloads bypass `ARG_MAX`** \u2014 `lotics run <tool> @args.json`, or piped stdin behind `-`. A leading `@` is\n unambiguously a file path (JSON args start with `{`).\n- **stdout is the payload, stderr is the narration.** Progress, status lines, and the target echo go to\n stderr; the result goes to stdout, so piping stays clean. `--json` switches stdout from the\n agent-readable summary to the full structured object.\n- **Every tool is invoked one way \u2014 `lotics run <tool>`.** Including the ones that RUN something\n (`run_app_workflow`, `run_app_query`) and every one that builds\n (`set_tables`, `set_app`, `set_workflow`). A command\n exists only for work that touches a local file.\n- **Building is two tools, each a writer that creates without an id and edits with one.** `set_tables`\n takes `{ \"tables\": [...] }` \u2014 always a list, one or many, all or nothing \u2014 each table a document keyed\n by alias (fields keyed by alias; a link names its table by id, or by the `ref` of another table of the\n same call, and states `multi`; a two-way link states `pair` on both tables), edited by an RFC 7396\n merge patch of that document, where `null` deletes. A call carries at most 50 tables, 200 first rows a table,\n and 2000 rows and 2000 documents in all. `set_app` takes ONE app: `{ \"body\": <the App tree> }` to create, the app's\n `name`, `description`, `icon` and `color` being props of the App node; `{ \"app_id\": \u2026, \"nodes\": { \"<address>\": <patch> } }`\n to change a node, refused with `base_version_id` when the app has moved past the version you read. `dry_run` checks\n without writing, a refusal lists everything wrong in the call, and every answer states the permissions the write\n granted and removed. The answer shows what the platform drew where the tree is silent (nothing is stored for it) and says what it placed or folded in what the tree states; a placement is stored. A new workspace: one `set_tables` call with\n the tables, then every `set_app` call, then fixes.\n- **Every change to an app mints a version of it, and applying the earlier tree again is the undo.** An apply, a\n deploy, a single `set_app_*`: each is a new version. Applying the earlier tree again restores the app \u2014 never a table change or a row a workflow wrote,\n so try a write on a throwaway record.\n- **Exit codes are assertable, and they report the WORK rather than the call.** `lotics run` exits\n non-zero when a `run_app_workflow` result's own envelope carries a failed\n `status` (`error`/`failed`/`cancelled`, or `not_previewed`: a dry run asked for and not given) \u2014 any other tool's top-level status is data and exits 0 \u2014\n so `lotics run \u2026 && next-step` cannot walk past a refused run; `workspace doctor` exits non-zero on\n findings. An unrecognized status exits 0 \u2014 the list is an allowlist of failure, so a status added\n later never turns a working script red \u2014 and a parked run (`awaiting_input`) is not a failure.\n- **An app that PUBLISHES an API turns every later binding write into a release.** Publishing\n snapshots what the app's queries, workflows and agents promise to callers outside it \u2014 a\n customer's own site or server, which nobody here can redeploy. From then on an additive change\n re-snapshots silently and a breaking one is REFUSED, naming each change; the tool's\n `acknowledge_breaking_api_change` carries it out and snapshots the break as a new contract version.\n- **Exposure is per app, all or nothing** \u2014 a public share or a key reaches every alias an app\n declares, so what outsiders may call is a second app over the same tables\n ([docs/app_architecture.md](./docs/app_architecture.md)).\n- **`--print-created` / `--cleanup` on any call that reports `side_effects`.** The first prints the\n records created plus a paste-ready cleanup plan and what cannot be auto-undone; the second runs\n those deletes (records only \u2014 never files, integrations or notifications). Neither is a rollback.\n- **Text output is the default and is built for reading**; reach for `--json` only when a field is\n needed programmatically.\n- **`lotics report '<json>'` is the channel for what nothing else records.** Reach for it\n when the platform is genuinely missing something (a capability that does not exist \u2014 no\n command ran), when a success was wrong (exited 0, wrong effect), or when an error did\n not name the remedy \u2014 not for your own mistakes, which the logs already show.\n **It is a frame, not a paragraph** \u2014 `{goal, actual, expected?, tried?, wanted?}`, because a log\n reconstructs what you RAN and never what you WANTED, and that gap is the report. `goal` and\n `actual` are required; there is no severity or category to pick. The\n session's commands attach themselves \u2014 do not retype them. Run it bare for the full prompt; a\n long one rides `@file.json` or an explicit `-` for stdin (bare NEVER reads stdin).\n- **`LOTICS_TELEMETRY=1` correlates a whole session** so the authoring loop's rough edges can be\n found and fixed. Off by default; set it in the shell profile, not per command (each invocation is\n its own process). It sends no arguments, no file contents, and no record data \u2014 see README\n \xA7 Diagnostics.\n\n## Where this CLI is not the answer\n\n- **Editing an app in a local directory.** An app stated as a tree is changed by applying the\n tree again; its bindings through their `set_app_*` tools; a custom-code app's code by deploying\n its directory again. Nothing reads a local copy of a live app back.\n- **OAuth connections.** Attaching a connected account is web-only; the CLI can list them.\n";
|
|
@@ -1916,7 +1916,7 @@ var workflow_steps_default = '<!-- Generated by backend/scripts/generate_workflo
|
|
|
1916
1916
|
var app_bindings_default = "# App bindings \u2014 the queries and workflows an app calls\n\nA custom-code app reaches workspace data through two kinds of binding, each declared on the app\nunder an alias \u2014 a JS identifier (`/^[a-zA-Z_$][a-zA-Z0-9_$]*$/`):\n\n| Binding | Declared with | The app calls it with | An agent calls it with |\n|---|---|---|---|\n| Query | `set_app`, a `Query` node | `useQuery(\"<alias>\", params?)` | `run_app_query` |\n| Workflow | `set_workflow` | `useWorkflow(\"<alias>\")({ ...inputs })` | `run_app_workflow` |\n\nEach runs under the app's authority (`{ type: \"app\", app_id }`), the app owner's reach \u2014 never the\ncalling member's. Declaring one needs the app's owner or an admin. A write is live: the app's next\ncall uses it. `get_app` lists an app's aliases with their params and inputs.\n\nEach reader returns a fingerprint of what it read, and a write built on that read passes it back:\n`get_workflow`'s `version` as `set_workflow`'s `expected_version`, and `get_app`'s version as `set_app`'s\n`base_version_id`. The write is refused, and writes nothing, when it changed since; omit it for an unconditional write.\n\n## API apps\n\nAn API app is one a customer's own server calls. It holds only `Query` and `Workflow` nodes, so no address serves it, and it cannot be shared publicly.\n\n1. `set_app` with a tree of those nodes, naming the tables they read in `uses`. The answer carries the link where an admin creates its key, and `get_app` states it again.\n2. `set_workflow` sets each workflow's code.\n3. An admin opens the link and creates an app key (`lak_\u2026`). It reaches this app alone and only calls it; no other route and no tool answers it, and that can never be widened. Its secret is shown once, so it goes straight into the server's secrets, and no tool creates or reads one.\n4. To promise the shape to that server, an admin's `set_app` states `{ \"app_id\": \"\u2026\", \"api_published\": true }`: a numbered contract and an OpenAPI document, and a later write that would break it is refused.\n\nThe server sends `Authorization: Bearer lak_\u2026` to `POST /v1/apps/{app_id}/queries/{alias}` and `POST /v1/apps/{app_id}/workflows/{alias}/execute`. The answer holds what the app declares, with each row's own id and timestamps: no member's email, no field id, and a failed run a generic message beside its `execution_id`. A browser cannot call them, and a key never goes in a page.\n\nA `Query` node reads one table or List with `rows` or `list`. A wider read states the whole query as `ast`, below.\n\n## Queries\n\nA query declaration is `{ ast, params?, description?, templates? }`:\n\n- `ast` \u2014 a query template (a QueryNode, below). It fixes the tables, filters and columns the alias\n reads, so a caller cannot widen it.\n- `params` \u2014 the typed value holes the caller fills, each an input declaration (see **Inputs**),\n named in the ast as `{{params.<name>}}`. A param fills a VALUE position only \u2014 a filter value, a\n `search` \u2014 never a `table_id` or a field key. Every token the ast names is declared. An optional\n param left unset drops the conditions that read it; a required param that arrives empty is\n refused where a filter reads it.\n- `description` \u2014 one line saying what the query returns, for an agent choosing between aliases.\n- `templates` \u2014 the document templates an export of its rows may fill, by name:\n `{ <name>: { template_id: \"dtl_\u2026\", rows: \"<key the template lists the rows under>\" } }`.\n\nA save checks what a deploy checks: every table is in this workspace and within the owner's reach,\nevery projected, filtered and sorted field resolves, every param token is declared, and a key a\nnode's kind does not take (a stray `sort`, `limit`, `filter`, `search`) is refused by name.\n\n`set_app` states one as a `Query` node: `{ \"type\": \"Query\", \"key\": \"<alias>\", \"ast\": { \u2026 } }`, beside `params`,\n`description` and `templates`. On an app made from a tree it stands among the tree's `children`, and a `nodes` patch\nreplaces its `ast`, `params` or `templates` whole. On an app that serves\ncode, `nodes` takes `{ \"<alias>\": { \u2026 } }` and merges each: send only the fields you change, `null` clears `params`,\n`description` or `templates` (never `ast`), a new alias needs an `ast`, and an alias set to `null` is unbound. Its\n`children` state the list whole, each query entire, and an alias they omit is unbound. Any other field is refused by\nname, and `get_app`'s `body` reads them back by alias.\n\n### The query tree\n\nEvery node has a `kind`; all but `from_table` read the node under `from` (`join`: `left`/`right`,\n`union`: `sources`).\n\n| `kind` | Keys |\n|---|---|\n| `from_table` | `table_id`, `filter?`, `search?`, `sort?`, `limit?` |\n| `project` | `columns` \u2014 the output columns |\n| `filter` | `predicate` \u2014 a filter tree over the input's columns |\n| `join` | `left`, `right`, `on: { left_column, right_column }`, `type: \"inner\" \\| \"left\"` |\n| `union` | `sources` (at least two, columns aligned by name and type) |\n| `group` | `by` (columns, `{ bucket: { source, granularity, output } }`, or `{ band: { source, tiers, output } }`), `aggregates` |\n| `window` | `partition_by`, `order_by`, `frame?`, `aggregates?`, `functions?` |\n| `sort` | `by: [{ field_key, order }]` |\n| `limit` | `n`, `offset?` or `keyset?` |\n| `unpivot` | `passthrough`, `row_columns`, `rows` \u2014 one source row into several |\n| `unnest` | `source`, `output`, `display_output?`, `keep_empty?` \u2014 one row per element of a multi-value cell |\n\nFilters (`from_table.filter`, `filter.predicate`, an aggregate's `filter`) are the filter grammar \u2014 the\n`filters` reference \u2014 over the input's columns, taking `{{params.x}}` as values. `search` matches\nevery text-bearing field of the row, accent- and case-insensitive.\n\nA query names a table's fields by the alias its document states, wherever a node reads the table directly (a\n`from_table`'s filter and sort, the `project`, `filter`, `group`, `window`, `unnest` or `unpivot` over it) and a select\ncondition's values by the option's alias. A column a `project` writes answers under the alias it was written with; every\nname past a `project` or an aggregate is that column's own. A `union` whose arms read one alias from different tables\nprojects each arm's columns under one name first. The query is stored by key and read back by alias.\n\nA `project` column is a field's alias as a bare string (output name and type come from the field), or\n`{ output?, type?, source, writable_target?, limit? }` to rename, compute or bound one. A computed\n`source` is a field's alias, `{ literal }`, `{ eq: [a, b] }`, `{ neq: [a, b] }`, `{ isEmpty }`,\n`{ isNotEmpty }`, `{ coalesce: [...] }`, `{ concat: [...] }`, `{ record_id: true }`,\n`{ link: { source, field } }` (a field of the first linked record),\n`{ link_agg: { source, field, operation } }` (`sum`, `avg`, `min`, `max`, `count`, `string_agg`\nover every linked record), or `{ expression }`. A computed column states its `type`: `text`,\n`number`, `boolean`, `date`, `datetime`, `select`, `select_record_link`, `select_member`, `files`\nor `json`. `limit` (1\u201310) bounds a `files` column's entries per cell.\n\nAn aggregate column is `{ output, type, operation, input_column?, filter? }` \u2014 `string_agg` also\ntakes `separator`, `distinct` and `max_values`. A `window` function is\n`{ output, fn }` for `row_number`, `rank`, `dense_rank`, `percent_rank`, `cume_dist`, plus\n`buckets` for `ntile` and `input_column`, `offset?`, `default?` for `lag` / `lead`; functions need\na non-empty `order_by`.\n\n## Inputs\n\nA query's `params`, a workflow's `inputs` and an agent's `inputs` are one vocabulary: a map of\nname \u2192 `{ type, required?, description?, field?, \u2026per type }`. An entry is required unless it states\n`required: false`. `field: \"<table id>.<alias>\"` names the table field the entry is a value of: the field's own\ndescription is read with the entry, as the table states it when read. The inputs an app's own adds, saves and acts\ndeclare name theirs.\n\n| `type` | Takes |\n|---|---|\n| `text`, `number`, `boolean`, `date`, `datetime`, `email` | \u2014 |\n| `record_link` | `table_id`; `multi?`; `max?` (with `multi`, the most ids one call carries) |\n| `select` | exactly one of `options: [{ label, value }]` or `field: \"<table id>.<alias>\"` (a select field whose CURRENT options back it); `multi?` |\n| `date_range` | `include_time?` |\n| `member` | `multi?`; `group?` (a member group the value must belong to) |\n| `file` | `multi?` \u2014 an uploaded `fil_\u2026` id, for a files field |\n| `json` | \u2014 any value |\n| `object` | `fields` \u2014 a nested map of entries |\n| `array` | `items` \u2014 one entry |\n\nA `record_link`'s `table_id`, in inputs and outputs, takes the table's id or alias and is stored as its id. Nesting stops at\ndepth 8. A `field`-form select tracks the field's options as they change, and `only: [\"<option key or alias>\", \u2026]` beside `field` keeps it to those options of the field (inputs and outputs of an app workflow, an app agent or a notification action, not a query's params); an\ninline `options` set is a fixed list. A query's select param takes an option by alias, label or key, each condition reading it by its own field's options, and a value that is none of them is refused naming the options.\n\n## Outputs\n\nA workflow's and an agent's `outputs` declare the structured data handed back: a map of\nname \u2192 `{ type, required?, description?, \u2026per type }`, every entry present unless it states\n`required: false`.\n\n| `type` | Takes |\n|---|---|\n| `text`, `number`, `boolean`, `date`, `datetime`, `email`, `json` | \u2014 |\n| `record_link` | `table_id`, `multi?` |\n| `select` | exactly one of `options: [{ label, value }]` or `field: \"<table id>.<alias>\"`; `multi?` |\n| `object` | `fields` |\n| `array` | `items` |\n\nThe returned value is checked against it, and the app reads it typed. An inline `options` set is\nalso enforced on the value returned, so the producer is told the legal keys; a `field`-form select\nkeeps the type tracking the live field.\n\n## Workflows\n\n`set_workflow` binds a workflow body to an alias: `{ workflow_id?, name?, description?, source }`, the `source`\nopening with `on({ type: \"app\", app_id, alias, inputs?, outputs? })`. Without a `workflow_id` it binds the alias; with\nthe one `get_app` lists for it, it replaces the body. On an app written as a tree the alias is one the tree names \u2014 a Workflow node's\n`key` or an Act's `workflow` \u2014 and the node states `inputs`, `outputs` and `description`\n(`reference/workflow-node`, whose value shapes differ from the **Inputs** below): a call stating any of\nthem for it is refused, and outputs the node leaves out are derived from the body. An alias the tree\nnames nowhere is archived by the next `set_app`. `set_app`'s `workflows` takes the same sources and saves them in the\nsame write as the tree: a change to what a workflow takes or hands back that its saved body no longer meets is refused\nunless the write carries the new body. A Workflow node runs only for someone who holds the\napp: on an app shared by a public link, a visitor's call of it is refused as an alias the app does\nnot have. This page's `inputs` and `outputs` are for a custom-code app.\n\n- `source` is the header, then the body; the app is the trigger. The body reads each declared\n input as `trigger.app_workflow.inputs.<name>`; no record is in scope, so it reads each one by id\n with `query_records` and `record_ids`.\n The body's steps are the `workflows` reference.\n- `inputs` in the header is the payload the call site passes (see **Inputs**). Omitted, an existing workflow keeps\n its inputs; on a first bind it takes an untyped payload. `{}` clears them.\n- `outputs` in the header is what `return({ data })` hands back (see **Outputs**). Usually omit it: the type is\n derived from the body's `return({ data })`, and the result echoes the bound `outputs`. Declared,\n the body does not save unless its return matches.\n- A save checks the body \u2014 parse, type-check against the declared inputs, names, lint, structure \u2014\n and answers with `[source/code] location: message` lines. `dry_run: true` makes every check\n and writes nothing. A call naming a live alias replaces its body in place, keeping its run history.\n- A call whose payload does not match `inputs` is refused before the body runs.\n\n`get_workflow` reads the source back; `set_workflow` with `dry_run` and `record_id` or `preview_inputs`\nrehearses a draft before binding; `set_workflow` with `delete: true` and the `workflow_id` unbinds it. An unbind is refused\nwhile the deployed version of the app calls the alias or an agent of the app declares it (`even_if_invoked` overrides it for a\nworkflow that has run, only when the caller that ran it is gone).\n";
|
|
1917
1917
|
|
|
1918
1918
|
// docs/document_templates.md
|
|
1919
|
-
var document_templates_default = '# Document Templates\n\nTurn workspace data into finished documents \u2014 invoices, contracts, reports, letters,\nlabels, emails \u2014 by filling a reusable template instead of writing a file from scratch.\nYou register a template once, then generate a filled file (or a rendered email) from it as\nmany times as you like, feeding it data from records, a workflow, or an agent run.\n\nThis is a **capability + usage** guide. A tool\'s exact input schema is in its own description.\n\n## The five template types\n\n`set_template` writes all five. Its `type` names which one a new template is.\n\n| Type | What it fills | Output | `type` |\n|---|---|---|---|\n| `pdf-form` | fields overlaid on an **uploaded PDF** at fixed positions | PDF | `"pdf-form"` |\n| `html` (a PDF) | an **HTML + Handlebars** layout you write from scratch | PDF | `"html"` |\n| `excel` | an **uploaded `.xlsx` or `.xlsm`** with `{{marker}}` cells | `.xlsx` | `"excel"` |\n| `word` | an **uploaded `.docx`** with `{{marker}}`s | `.docx` | `"word"` |\n| `email` | an **inline HTML + Handlebars** body, rendered when the email is sent | email | `"email"` |\n\nTwo shapes underneath: **file-backed** (`pdf-form`, `excel`, `word`) clone an uploaded\noffice file and mark it up; **inline** (`html`, `email`) store the markup you author directly.\n\n## The lifecycle: create \u2192 generate \u2192 chain\n\n1. **Create** a template \u2014 register the file (or inline markup) and declare a `variables`\n map (the named slots the template fills). This returns a template id (`dtl_\u2026`).\n2. **Generate** a filled file \u2014 call `generate_document` with the\n template id, a `filename` (no extension), and a `data` map keyed by your variable names.\n It substitutes the markers and returns a **generated file** (with a `file_id`).\n3. **Chain** the result \u2014 generation only *produces* the file. Attaching it to a record,\n sending it, or saving it is a separate step: `update_records` with `add_to` on a files field\n files the `file_id` on a record (`remove_made`, a template id, takes out the paper that template\n made earlier); over MCP and on the CLI, `download_file` fetches it; inside a workflow, pass the `file_id` to the next\n step. A paper an app makes is its Act\'s `template`, which files it on the record itself\n (below).\n\nEmail is the exception: `generate_document` refuses an email template. An email template is\nrendered to a subject + body **at send time** from the template and the data the send step\nsupplies \u2014 so you author it with `set_template` and a workflow/app send step (or the\nweb composer) does the rendering and delivery. External agents send their own email directly.\n\n## Creating and changing a template\n\nA paper prints the owner\'s own terms only: the clauses, wording and fields of the sample they sent, never a term the owner did not state.\n\n`set_template` creates a template when it is given no `template_id`, and changes the named one\nwhen it is given one. Creating takes `type` and `name`, and the fields of its type; changing takes\n`expected_version` \u2014 the `current_version` that `get_template` returned, so a concurrent edit is\nrefused rather than overwritten \u2014 and only the fields to change. A field the type does not take is\nrefused rather than dropped. `description` (one line on what the template produces) is on every type. A template\'s\nalias is made from its name when it is created and stays when the template is renamed. A change is\nbuilt into every app whose Acts make the template; one an app can no longer be built with is refused, naming the app and\nthe marker, and nothing is written.\n\n### Getting a file in\n\nA file-backed template starts from a file in the workspace: over MCP and on the CLI, `upload_file` takes a public URL,\nor bytes you hold, and returns a `file_id`. When the person has the file and your host shows you its content but not its\nbytes, `upload_file` with `person: true` returns a `drop_url` for them to open and a `ticket_id` per file; once they say\nthey dropped it, `upload_file` with that `ticket_id` returns the `file_id`.\n\nA new Word or Excel paper is a file you build yourself, in your own filesystem or sandbox, with its markers typed where\nthe values go, then, over MCP or on the CLI, send it with `upload_file` `files` and register with `set_template`. Where your sandbox cannot reach\nthis host, give the person the file and a `person` drop link.\n\n### By type\n\n- **`html`** \u2014 a full HTML document with inline CSS and `{{variable}}` placeholders, rendered to PDF; anything whose layout\n you control. `variables` are plain text, rich `html`, an auto-rendered `table` or a `list`; `format` (a named page size:\n A0\u2013A6, Letter, Legal, Tabloid, Ledger) and `orientation` are optional; any other size is the page\'s own CSS,\n `@page { size: 50mm 30mm }`. A change may send `patch_ops`, exact search-and-replace edits of the stored markup, in place\n of the whole `template`.\n- **`pdf-form`** \u2014 an existing PDF filled in place. `set_template` with the uploaded `template_file_id`\n answers `page_count` and `pages` (each page\'s `page_index`, unrotated MediaBox `width` and `height`, `origin_x`, `origin_y`\n and its `labels`, the text with its position and font size; `get_template` returns the same); `set_template` again with\n `expected_version` and the positioned `variables` (`text` / `checkbox` / `image`, each with a page and x/y/size). Data is one scalar per field. A field whose `page` is past `page_count`, or whose box lies outside that page\'s MediaBox,\n is refused. The answer holds at most 50 pages and 400 labels a page; `pages_omitted` and each page\'s `labels_omitted`\n count the rest, and `pages_unavailable` says why a template\'s pages could not be read.\n A positioned text field prints in Arimo, which covers Vietnamese; a PDF\'s own field keeps its font while its value is\n ASCII and switches to Arimo past it.\n- **`excel`** \u2014 a `.xlsx` or `.xlsm` with `{{marker}}`s in the cells to fill, and a `variables` map. `sheet` names the sheet\n that is the paper in a workbook holding others, and the template leaves the rest out; a formula reading a sheet left out\n is refused. A macro workbook is kept without its macros and the buttons that run them. Markers are validated at create\n time: a structural error blocks the save, and a declared variable with no marker comes back in `unmarked_variables`\n (skipped). `set_template` with `dry_run: true` runs every check and stores nothing; a refusal lists every error with its code and cell, and `warnings[]` (`severity`, `code`, `message`, `sheet_name?`, `cell?`) comes back with the answer. Pass\n raw numbers, ISO dates and booleans at generate time; the cell\'s number format shows them. A cell\'s format also decides\n what text becomes: text that reads as a number (`5%`) is written as one, unless the cell is formatted as text (`@`).\n- **`word`** \u2014 a `.docx` with `{{marker}}`s. `variables` is optional: every marker is derived (`{{name}}` string,\n `{{FOR \u2026 IN name}}` array, `{{IF name}}` boolean), and a marker you did not declare is still added\n (`derived_variables`). At generate time `data` needs a key for **every** marker, `""` for a blank one. A marker may run\n across formatting runs and is still read whole. In a table, the row holding `{{FOR line IN lines}}` and the row holding\n `{{END-FOR line}}` enclose the row that repeats. A newline in a value prints as a line break and a tab as a tab;\n a tab the paper prints only when a blank is empty is written `{{IF !name}}{{"\\t"}}\u2026\u2026{{END-IF}}`, since the\n form\'s own tab stays put inside an `{{IF}}` on the same line.\n- **`email`** \u2014 inline HTML + Handlebars, with `template` and `variables`; optionally a default `subject` (it takes\n `{{variable}}` too) and `default_to`, `default_cc`, `default_bcc`. Body and subject render from the data at send time.\n\n## Markers, at a usage level\n\nEvery type supports three shapes of substitution. The exact syntax differs per engine \u2014 read\nthe `set_template` description for the reference; here is the capability:\n\n- **Scalar** \u2014 a single value in one spot: `{{name}}`, `{{total}}`. Whole-cell scalars in\n Excel preserve their type via the cell\'s number format.\n- **Repeating rows / line items** \u2014 one template row rendered once per item in a list, for\n invoice lines, order rows, tables. Excel and the HTML/email engines use a Handlebars-style\n `{{#each items}}\u2026{{/each}}`; Word uses `{{FOR item IN items}}\u2026{{$item.field}}\u2026{{END-FOR item}}`. The HTML and email types\n also offer an auto-rendered `table` variable \u2014 declare its columns and pass an array, no\n hand-written loop. Excel marks the rows that repeat with `{{#each items}}` and `{{/each}}`, each alone in a row above and\n below them, or inline in the paper\'s own rows: `{{#each items}}` opens the first repeated row\'s first cell holding text\n and `{{/each}}` closes the last one\'s last (a formula cell is passed over), so a one-row body reads `{{#each lines}}{{@ordinal}}` \u2026 `{{amount}}{{/each}}`. A row repeats for one loop: two loops side by side in the same rows are refused, so put them in separate row bands or on separate sheets.\n (Excel has no auto-rendered `table` type; its variable types are string/number/date/boolean/array.) Inside a loop the row\'s number counted from 1\n is `{{@ordinal}}` (Excel, HTML, email) or `{{$ordinal}}` (Word), the innermost loop\'s: an STT column is a cell holding\n `{{@ordinal}}` beside the row\'s other markers. `{{@index}}` counts from 0.\n- **Columns across** \u2014 a column per item of a list, for a grid of rows by days or by kinds. HTML/email nest a\n `{{#each}}` inside a table row\'s; Excel repeats the columns between `{{#each-col columns}}` and `{{/each-col}}`, each\n marker alone in its column, and a row\'s cell under the column is `{{cells | lookup:@index}}`, its list\'s item at that\n column\'s place; Word repeats a table cell between a cell holding `{{FOR c IN columns}}` and one holding\n `{{END-FOR c}}`, and a row\'s cells the same way inside its loop, `{{FOR k IN $r.cells}}` `{{$k}}` `{{END-FOR k}}`.\n- **Conditional sections** \u2014 a block shown only when a condition holds (a "paid" stamp, an\n optional notes block). Excel/HTML/email use `{{#if}}\u2026{{else}}\u2026{{/if}}`; Word uses `{{IF name}}\u2026{{END-IF name}}`.\n\nThe `html` and `email` types print a raw value through a helper in the template\'s `locale` (`vi` or `en`; none prints in the organization\'s language): `{{money total "VND"}}`, `{{number qty item_unit}}` (the figure, then its unit), `{{date issued_on}}`, `{{words total "USD"}}` (`reference/groups-and-templates` lists what each prints). `{{date (add_days issued_on -1)}}` prints the day before, `add_days` shifting a date by whole days. A value a helper cannot read fails the render, and a template calling a helper the engine lacks (`{{eq a b}}`) is refused when saved, naming the ones it has.\n\nA field can also print as a **QR code** or a **Code 128 barcode** (a picture a phone\'s camera or a scanner reads back): `{{qr link}}` or `{{code128 position 6}}` in html (never email: mail clients do not show the picture, and a save refuses it), `{{position | qr}}` or `{{position | code128:6}}` as a whole Excel cell (its row grows to the picture), `{{IMAGE qr(position)}}` or `{{IMAGE code128(position, 6)}}` in Word. The optional number is the picture\'s width in centimetres. Without it the width follows the value\'s length \u2014 each module prints 0.5 mm in a QR code and 0.33 mm in a barcode, so a longer value prints wider; a width that would shrink a module below what a scanner reads (0.3 mm, 0.19 mm) is refused, naming the least width that scans. An empty field draws nothing.\n\nA cell merged in an Excel template over the rows of a loop covers the rows that loop becomes; inside an outer loop, each of its items its own rows (a group\'s name merged beside its lines). An Excel cell\'s text can stand in parts, some of them bold: `{{goods | rich}}` as the whole cell takes a list of `{ text, bold }` and writes the parts as one text, a bold part in the cell\'s own font made bold. Excel shows a row at most 409 points tall and cuts a cell\'s text past it, so a long text is laid over several rows.\n\nA record\'s **photos** (a files field, or a lookup of one through its links, an act\'s paper hands each as a file cell `{id, name, mime, url}`) print too, and only for a file whoever makes the paper may read \u2014 the same rule the file proxy applies; any other file is never drawn. html: `{{#each photos}}<img src="{{url}}">{{/each}}` (only the data\'s file cells are inlined; a url typed into a text field stays a link). Word: `{{IMAGE picture(cover, 8)}}`, and `{{FOR p IN photos}}{{IMAGE picture($p, 8)}}{{END-FOR p}}` for several. Excel: `{{cover | picture:6}}` as the whole cell, or `{{this | picture}}` inside `{{#each photos}}` (each row grows to its picture). The number is the width in centimetres (8, or 6 in Excel, by default). `picture` takes one image file: a list (loop over it), a file that is no image or one that cannot be read is refused by name. Photos are embedded at most 1600 pixels across, about 200 dpi at 20 cm.\n\nA Word command (`{{ \u2026 }}`) reads the data and calls, by name, a Word helper (`picture`, `qr`, `code128`) or one of these text\nand number functions: `trim`, `trimStart`, `trimEnd`, `lower`, `upper`, `capitalize`, `replace`, `replaceAll`, `removeChars`, `removeSpaces`,\n`startsWith`, `endsWith`, `contains`, `substring`, `padStart`, `padEnd`, `length`, `join`, `split`, `repeat`, `formatNumber`,\n`formatDecimal`, `numberToWords`. It holds no JavaScript method or regular-expression literal: `{{upper(name)}}`,\n`{{formatDecimal(total, 0, "vi-VN")}}`, and `{{removeSpaces(removeChars(cccd || "", ".\u2026"))}}` for the text without its dots,\nellipses and spaces. `removeChars(text, chars)` removes every character of `text` that occurs in `chars` (a set of characters,\nnever a pattern); `removeSpaces(text)` removes every whitespace character of `text`, anywhere in it, the set `trim` trims.\n\nA field named like a function is read as the field, and calling the function then fails.\n\n`set_template`\'s description holds each type\'s exact marker grammar and helper list.\n\n## Generating a filled file\n\n```\nget_template {"template_id": "dtl_\u2026"} # its declared variables\ngenerate_document {"document_template_id": "dtl_\u2026", "filename": "invoice-1042",\n "data": {"company_name": "Acme", "total": 1042, "items": [...]}}\n```\n\n- `data` is a map keyed by your variable names. Scalars for scalar/form fields; arrays for\n `table`/`list`/loop variables. `filename` excludes the extension (the type sets it). Pass a select, a\n member or a link as `query_records`\' `display` words, a number and a date raw.\n- `generate_document` renders the template\'s own type and returns a generated file object; take\n its `file_id` onward.\n- A PDF no template is wanted for takes `html`, a `filename` and its `data` in place of `document_template_id`: the markup is\n rendered as an `html` template is (the same markup rules, markers and helpers) and the PDF is stored as a workspace file. Name one of the two.\n- In a workflow, a **generate step** calls the same tool and hands the `file_id` to the next\n step (attach to a record, send as an attachment, etc.).\n\n## A template an app\'s Act makes\n\nAn Act with `template` (or `templates`) fills an `html`, `excel` or `word` template from its record and files the result\n(a PDF, an `.xlsx` or a `.docx`) in the record\'s files field `into`; `run_app_workflow` on `act_<key>` presses it. The Act hands the template the record\'s fields by their\nalias, so name each variable after one: `{{customer}}`, `{{total}}`. A select, a member and a link arrive as their words\n(a link as the linked row\'s title); a number and a date arrive raw, for `{{money total "VND"}}` and `{{date issued_on}}`.\nA loop over a link of the record whose partner the table pairs, or over the alias of a table that links to the record\nonce, receives those rows with their fields, read under the app\'s row rules:\n\n```html\n<h1>Quote {{code}}</h1>\n<p>{{customer}} \u2014 {{money total "VND"}}</p>\n{{#each lines}}<p>{{description}} \xD7 {{quantity}}</p>{{/each}}\n```\n\nHere `code`, `customer` and `total` are fields of the record and `lines` is its link to the child table, so\n`{{#each quote_line}}`, the child table\'s alias, fills as well; a Word template loops the same rows with `{{FOR line IN lines}}` \u2026\n`{{$line.description}}` \u2026 `{{END-FOR line}}`. A link whose partner is not paired reaches no rows from the record, and\na loop printing a field of each of its items is refused, naming `pair`.\n\nEvery List the record draws and the template names (an html template\'s variables, a Word template\'s markers) hands its\nrows, each List\'s `where` applied; a List the template does not name is not read. A List that only reads hands them under its\n`key` (the table\'s alias where it states none), and a List that sums a number hands the sums under `<name>_totals`, one\nentry per number the List draws as a column or as the table\'s figure. A `where` bound may be `{ "record": "<field>" }`,\na date or number the record itself holds, so a record can print a window of its own days. A service plan row (customer,\n`period_start`, `period_end`) draws the customer\'s visits within its period:\n\n```\n{ "type": "List", "key": "visits", "entity": "visit", "same": "customer", "label": "Visits", "columns": ["visited_on", "hours"],\n "where": { "visited_on": { "gte": { "record": "period_start" }, "lte": { "record": "period_end" } } } }\n```\n\n```html\n{{#each visits}}<p>{{visited_on}} \u2014 {{hours}} h</p>{{/each}}\n<p>Total {{visits_totals.hours}} h</p>\n```\n\nA bound the record leaves blank, or holds as anything but one whole day (`2026-05`) or one figure, keeps no row:\n`visits` is empty and `visits_totals.hours` is `0`. The sums add a number as the List\'s foot does: a cell holding a\nfigure adds it, any other cell (blank, an errored formula, a lookup\'s list) adds nothing. A Word template loops\n`{{FOR v IN visits}}` and prints `{{visits_totals.hours}}` the same way. A template that names a List narrowed to the\nreader (`"me"`) is refused, and so is a name a rows List and a `list` List both reach: give the `list` a `key`. A record\nbound narrows what is listed and is never an access bound; the table\'s row rules are.\n\nA List that reads by a path (`via: "<link>.<link>"`) hands its rows the same way. A List the screen draws as an outline (a record\'s own\nsub-rows, in a table whose rows nest, with no `where`, total, group, long-text column or other narrowing) hands every sub-row, depth first, each after the row it is filed under and its\nsiblings in the List\'s order, with its depth as `level` (1 for the rows filed under the record): `{{#each tasks}}{{level}} {{name}}{{/each}}`.\nA paper that lists an outline whose table has a field named `level` is refused. Inside a listed row a link arrives as the\ntitles of its rows (`{{#each marks}}{{this}}{{/each}}` prints them), so a loop there printing a field of each item is\nrefused, naming the key a List hands those rows under; so is one drawing a table cell per title, which lines up with no\ncolumn \u2014 a grid of rows by days is a roster\'s Export (below). A Word template is read for this when it is next saved.\n\nA paper made over several rows (`on: "ticked"` or `"view"`, at most 200) is one file of them all: the rows arrive under the entity\'s alias. An html paper hands each row the child rows the record\'s paper would be handed, under the same names, with their `_totals`; an Excel or Word paper is handed the rows alone. The page the rows open draws those Lists:\n\n```html\n{{#each supplier_order}}<h2>{{code}}</h2>{{#each sources}}<p>{{description}} \xD7 {{quantity}}</p>{{/each}}{{/each}}\n```\n\nA paper over many rows (a client\'s month, a statement) is that: a record of the period whose List is windowed by its dates, made by the Act\'s `template`; or a List `Export` with `template` and `per` (`reference/export-node`).\n`reference/groups-and-templates` has the rest.\n\nA roster\'s `Export` (an html or Excel `template`) is handed its grid over the window in view: `columns`, the days\nholding a row in the file (with `expect`, every option), each a `label`, its `date` and `weekday`; and on each row (under the List\'s entity alias, `student` here)\n`cells`, a word per column \u2014 each of its rows\' mark, the option\'s `short` else its label (a row with no state, its title), joined by `, ` \u2014\n`counts`, how many of its rows stand at each option by alias (`held`, at none), and `total`, as the roster reads it (its owed or expected ratio, else the sum of the row\'s figure, else the count of the cells it holds):\n\n```html\n<tr><th>Student</th>{{#each columns}}<th>{{label}}</th>{{/each}}<th>Absent</th></tr>\n{{#each student}}<tr><td>{{name}}</td>{{#each cells}}<td>{{this}}</td>{{/each}}<td>{{counts.absent}}</td></tr>{{/each}}\n```\n\n| | A | B | C | D | E |\n|---|---|---|---|---|---|\n| 1 | Student | `{{#each-col columns}}` | `{{label}}` | `{{/each-col}}` | Absent |\n| 2 | `{{#each student}}` | | | | |\n| 3 | `{{name}}` | | `{{cells \\| lookup:@index}}` | | `{{counts.absent}}` |\n| 4 | `{{/each}}` | | | | |\n\n## Discovering and managing templates\n\nThese tools work across all five types:\n\n| Tool | Does |\n|---|---|\n| `get_workspace` | list the workspace\'s templates (`kind: "template"`), each with its id, type and one line |\n| `get_template` | one template\'s full definition, incl. the `variables` it expects and the `current_version` a change needs |\n| `set_template` | create a template, change one, delete it (`delete: true` with `template_id`) or bring it back (`restore: true`); `dry_run: true` checks the call and stores nothing; a copy is `get_template` then `set_template` |\n\nCall `get_template` before generating when you don\'t already know a template\'s variable names.\n';
|
|
1919
|
+
var document_templates_default = '# Document Templates\n\nTurn workspace data into finished documents \u2014 invoices, contracts, reports, letters,\nlabels, emails \u2014 by filling a reusable template instead of writing a file from scratch.\nYou register a template once, then generate a filled file (or a rendered email) from it as\nmany times as you like, feeding it data from records, a workflow, or an agent run.\n\nThis is a **capability + usage** guide. A tool\'s exact input schema is in its own description.\n\n## The five template types\n\n`set_template` writes all five. Its `type` names which one a new template is.\n\n| Type | What it fills | Output | `type` |\n|---|---|---|---|\n| `pdf-form` | fields overlaid on an **uploaded PDF** at fixed positions | PDF | `"pdf-form"` |\n| `html` (a PDF) | an **HTML + Handlebars** layout you write from scratch | PDF | `"html"` |\n| `excel` | an **uploaded `.xlsx` or `.xlsm`** with `{{marker}}` cells | `.xlsx` | `"excel"` |\n| `word` | an **uploaded `.docx`** with `{{marker}}`s | `.docx` | `"word"` |\n| `email` | an **inline HTML + Handlebars** body, rendered when the email is sent | email | `"email"` |\n\nTwo shapes underneath: **file-backed** (`pdf-form`, `excel`, `word`) clone an uploaded\noffice file and mark it up; **inline** (`html`, `email`) store the markup you author directly.\n\n## The lifecycle: create \u2192 generate \u2192 chain\n\n1. **Create** a template \u2014 register the file (or inline markup) and declare a `variables`\n map (the named slots the template fills). This returns a template id (`dtl_\u2026`).\n2. **Generate** a filled file \u2014 call `generate_document` with the\n template id, a `filename` (no extension), and a `data` map keyed by your variable names.\n It substitutes the markers and returns a **generated file** (with a `file_id`).\n3. **Chain** the result \u2014 generation only *produces* the file. Attaching it to a record,\n sending it, or saving it is a separate step: `update_records` with `add_to` on a files field\n files the `file_id` on a record (`remove_made`, a template\'s id or alias, takes out the paper that template\n made earlier); over MCP and on the CLI, `download_file` fetches it; inside a workflow, pass the `file_id` to the next\n step. A paper an app makes is its Act\'s `template`, which files it on the record itself\n (below).\n\nEmail is the exception: `generate_document` refuses an email template. An email template is\nrendered to a subject + body **at send time** from the template and the data the send step\nsupplies \u2014 so you author it with `set_template` and a workflow/app send step (or the\nweb composer) does the rendering and delivery. External agents send their own email directly.\n\n## Creating and changing a template\n\nA paper prints the owner\'s own terms only: the clauses, wording and fields of the sample they sent, never a term the owner did not state.\n\n`set_template` creates a template when it is given no `template_id`, and changes the named one\nwhen it is given one. Creating takes `type` and `name`, and the fields of its type; changing takes\n`expected_version` \u2014 the `current_version` that `get_template` returned, so a concurrent edit is\nrefused rather than overwritten \u2014 and only the fields to change. A field the type does not take is\nrefused rather than dropped. `description` (one line on what the template produces) is on every type. A template\'s\nalias is made from its name when it is created and stays when the template is renamed. A change is\nbuilt into every app whose Acts make the template; one an app can no longer be built with is refused, naming the app and\nthe marker, and nothing is written.\n\n### Getting a file in\n\nA file-backed template starts from a file in the workspace: over MCP and on the CLI, `upload_file` takes a public URL,\nor bytes you hold, and returns a `file_id`. When the person has the file and your host shows you its content but not its\nbytes, `upload_file` with `person: true` returns a `drop_url` for them to open and a `ticket_id` per file; once they say\nthey dropped it, `upload_file` with that `ticket_id` returns the `file_id`.\n\nA new Word or Excel paper is a file you build yourself, in your own filesystem or sandbox, with its markers typed where\nthe values go, then, over MCP or on the CLI, send it with `upload_file` `files` and register with `set_template`. Where your sandbox cannot reach\nthis host, give the person the file and a `person` drop link.\n\n### By type\n\n- **`html`** \u2014 a full HTML document with inline CSS and `{{variable}}` placeholders, rendered to PDF; anything whose layout\n you control. `variables` are plain text, rich `html`, an auto-rendered `table` or a `list`; `format` (a named page size:\n A0\u2013A6, Letter, Legal, Tabloid, Ledger) and `orientation` are optional; any other size is the page\'s own CSS,\n `@page { size: 50mm 30mm }`. A change may send `patch_ops`, exact search-and-replace edits of the stored markup, in place\n of the whole `template`.\n- **`pdf-form`** \u2014 an existing PDF filled in place. `set_template` with the uploaded `template_file_id`\n answers `page_count` and `pages` (each page\'s `page_index`, unrotated MediaBox `width` and `height`, `origin_x`, `origin_y`\n and its `labels`, the text with its position and font size; `get_template` returns the same); `set_template` again with\n `expected_version` and the positioned `variables` (`text` / `checkbox` / `image`, each with a page and x/y/size). Data is one scalar per field. A field whose `page` is past `page_count`, or whose box lies outside that page\'s MediaBox,\n is refused. The answer holds at most 50 pages and 400 labels a page; `pages_omitted` and each page\'s `labels_omitted`\n count the rest, and `pages_unavailable` says why a template\'s pages could not be read.\n A positioned text field prints in Arimo, which covers Vietnamese; a PDF\'s own field keeps its font while its value is\n ASCII and switches to Arimo past it.\n- **`excel`** \u2014 a `.xlsx` or `.xlsm` with `{{marker}}`s in the cells to fill, and a `variables` map. `sheet` names the sheet\n that is the paper in a workbook holding others, and the template leaves the rest out; a formula reading a sheet left out\n is refused. A macro workbook is kept without its macros and the buttons that run them. Markers are validated at create\n time: a structural error blocks the save, and a declared variable with no marker comes back in `unmarked_variables`\n (skipped). `set_template` with `dry_run: true` runs every check and stores nothing; a refusal lists every error with its code and cell, and `warnings[]` (`severity`, `code`, `message`, `sheet_name?`, `cell?`) comes back with the answer. Pass\n raw numbers, ISO dates and booleans at generate time; the cell\'s number format shows them. A cell\'s format also decides\n what text becomes: text that reads as a number (`5%`) is written as one, unless the cell is formatted as text (`@`).\n- **`word`** \u2014 a `.docx` with `{{marker}}`s. `variables` is optional: every marker is derived (`{{name}}` string,\n `{{FOR \u2026 IN name}}` array, `{{IF name}}` boolean), and a marker you did not declare is still added\n (`derived_variables`). At generate time `data` needs a key for **every** marker, `""` for a blank one. A marker may run\n across formatting runs and is still read whole. In a table, the row holding `{{FOR line IN lines}}` and the row holding\n `{{END-FOR line}}` enclose the row that repeats. A newline in a value prints as a line break and a tab as a tab;\n a tab the paper prints only when a blank is empty is written `{{IF !name}}{{"\\t"}}\u2026\u2026{{END-IF}}`, since the\n form\'s own tab stays put inside an `{{IF}}` on the same line.\n- **`email`** \u2014 inline HTML + Handlebars, with `template` and `variables`; optionally a default `subject` (it takes\n `{{variable}}` too) and `default_to`, `default_cc`, `default_bcc`. Body and subject render from the data at send time.\n\n## Markers, at a usage level\n\nEvery type supports three shapes of substitution. The exact syntax differs per engine \u2014 read\nthe `set_template` description for the reference; here is the capability:\n\n- **Scalar** \u2014 a single value in one spot: `{{name}}`, `{{total}}`. Whole-cell scalars in\n Excel preserve their type via the cell\'s number format.\n- **Repeating rows / line items** \u2014 one template row rendered once per item in a list, for\n invoice lines, order rows, tables. Excel and the HTML/email engines use a Handlebars-style\n `{{#each items}}\u2026{{/each}}`; Word uses `{{FOR item IN items}}\u2026{{$item.field}}\u2026{{END-FOR item}}`. The HTML and email types\n also offer an auto-rendered `table` variable \u2014 declare its columns and pass an array, no\n hand-written loop. Excel marks the rows that repeat with `{{#each items}}` and `{{/each}}`, each alone in a row above and\n below them, or inline in the paper\'s own rows: `{{#each items}}` opens the first repeated row\'s first cell holding text\n and `{{/each}}` closes the last one\'s last (a formula cell is passed over), so a one-row body reads `{{#each lines}}{{@ordinal}}` \u2026 `{{amount}}{{/each}}`. A row repeats for one loop: two loops side by side in the same rows are refused, so put them in separate row bands or on separate sheets.\n (Excel has no auto-rendered `table` type; its variable types are string/number/date/boolean/array.) Inside a loop the row\'s number counted from 1\n is `{{@ordinal}}` (Excel, HTML, email) or `{{$ordinal}}` (Word), the innermost loop\'s: an STT column is a cell holding\n `{{@ordinal}}` beside the row\'s other markers. `{{@index}}` counts from 0.\n- **Columns across** \u2014 a column per item of a list, for a grid of rows by days or by kinds. HTML/email nest a\n `{{#each}}` inside a table row\'s; Excel repeats the columns between `{{#each-col columns}}` and `{{/each-col}}`, each\n marker alone in its column, and a row\'s cell under the column is `{{cells | lookup:@index}}`, its list\'s item at that\n column\'s place; Word repeats a table cell between a cell holding `{{FOR c IN columns}}` and one holding\n `{{END-FOR c}}`, and a row\'s cells the same way inside its loop, `{{FOR k IN $r.cells}}` `{{$k}}` `{{END-FOR k}}`.\n- **Conditional sections** \u2014 a block shown only when a condition holds (a "paid" stamp, an\n optional notes block). Excel/HTML/email use `{{#if}}\u2026{{else}}\u2026{{/if}}`; Word uses `{{IF name}}\u2026{{END-IF name}}`.\n\nThe `html` and `email` types print a raw value through a helper in the template\'s `locale` (`vi` or `en`; none prints in the organization\'s language): `{{money total "VND"}}`, `{{number qty item_unit}}` (the figure, then its unit), `{{date issued_on}}`, `{{words total "USD"}}` (`reference/groups-and-templates` lists what each prints). `{{date (add_days issued_on -1)}}` prints the day before, `add_days` shifting a date by whole days. A value a helper cannot read fails the render, and a template calling a helper the engine lacks (`{{eq a b}}`) is refused when saved, naming the ones it has.\n\nA field can also print as a **QR code** or a **Code 128 barcode** (a picture a phone\'s camera or a scanner reads back): `{{qr link}}` or `{{code128 position 6}}` in html (never email: mail clients do not show the picture, and a save refuses it), `{{position | qr}}` or `{{position | code128:6}}` as a whole Excel cell (its row grows to the picture), `{{IMAGE qr(position)}}` or `{{IMAGE code128(position, 6)}}` in Word. The optional number is the picture\'s width in centimetres. Without it the width follows the value\'s length \u2014 each module prints 0.5 mm in a QR code and 0.33 mm in a barcode, so a longer value prints wider; a width that would shrink a module below what a scanner reads (0.3 mm, 0.19 mm) is refused, naming the least width that scans. An empty field draws nothing.\n\nA cell merged in an Excel template over the rows of a loop covers the rows that loop becomes; inside an outer loop, each of its items its own rows (a group\'s name merged beside its lines). An Excel cell\'s text can stand in parts, some of them bold: `{{goods | rich}}` as the whole cell takes a list of `{ text, bold }` and writes the parts as one text, a bold part in the cell\'s own font made bold. Excel shows a row at most 409 points tall and cuts a cell\'s text past it, so a long text is laid over several rows.\n\nA record\'s **photos** (a files field, or a lookup of one through its links, an act\'s paper hands each as a file cell `{id, name, mime, url}`) print too, and only for a file whoever makes the paper may read \u2014 the same rule the file proxy applies; any other file is never drawn. html: `{{#each photos}}<img src="{{url}}">{{/each}}` (only the data\'s file cells are inlined; a url typed into a text field stays a link). Word: `{{IMAGE picture(cover, 8)}}`, and `{{FOR p IN photos}}{{IMAGE picture($p, 8)}}{{END-FOR p}}` for several. Excel: `{{cover | picture:6}}` as the whole cell, or `{{this | picture}}` inside `{{#each photos}}` (each row grows to its picture). The number is the width in centimetres (8, or 6 in Excel, by default). `picture` takes one image file: a list (loop over it), a file that is no image or one that cannot be read is refused by name. Photos are embedded at most 1600 pixels across, about 200 dpi at 20 cm.\n\nA Word command (`{{ \u2026 }}`) reads the data and calls, by name, a Word helper (`picture`, `qr`, `code128`) or one of these text\nand number functions: `trim`, `trimStart`, `trimEnd`, `lower`, `upper`, `capitalize`, `replace`, `replaceAll`, `removeChars`, `removeSpaces`,\n`startsWith`, `endsWith`, `contains`, `substring`, `padStart`, `padEnd`, `length`, `join`, `split`, `repeat`, `formatNumber`,\n`formatDecimal`, `numberToWords`. It holds no JavaScript method or regular-expression literal: `{{upper(name)}}`,\n`{{formatDecimal(total, 0, "vi-VN")}}`, and `{{removeSpaces(removeChars(cccd || "", ".\u2026"))}}` for the text without its dots,\nellipses and spaces. `removeChars(text, chars)` removes every character of `text` that occurs in `chars` (a set of characters,\nnever a pattern); `removeSpaces(text)` removes every whitespace character of `text`, anywhere in it, the set `trim` trims.\n\nA field named like a function is read as the field, and calling the function then fails.\n\n`set_template`\'s description holds each type\'s exact marker grammar and helper list.\n\n## Generating a filled file\n\n```\nget_template {"template_id": "dtl_\u2026"} # its declared variables\ngenerate_document {"document_template_id": "dtl_\u2026", "filename": "invoice-1042",\n "data": {"company_name": "Acme", "total": 1042, "items": [...]}}\n```\n\n- `data` is a map keyed by your variable names. Scalars for scalar/form fields; arrays for\n `table`/`list`/loop variables. `filename` excludes the extension (the type sets it). Pass a select, a\n member or a link as `query_records`\' `display` words, a number and a date raw.\n- `generate_document` renders the template\'s own type and returns a generated file object; take\n its `file_id` onward.\n- A PDF no template is wanted for takes `html`, a `filename` and its `data` in place of `document_template_id`: the markup is\n rendered as an `html` template is (the same markup rules, markers and helpers) and the PDF is stored as a workspace file. Name one of the two.\n- In a workflow, a **generate step** calls the same tool and hands the `file_id` to the next\n step (attach to a record, send as an attachment, etc.).\n\n## A template an app\'s Act makes\n\nAn Act with `template` (or `templates`) fills an `html`, `excel` or `word` template from its record and files the result\n(a PDF, an `.xlsx` or a `.docx`) in the record\'s files field `into`; `run_app_workflow` on `act_<key>` presses it. The Act hands the template the record\'s fields by their\nalias, so name each variable after one: `{{customer}}`, `{{total}}`. A select, a member and a link arrive as their words\n(a link as the linked row\'s title); a number and a date arrive raw, for `{{money total "VND"}}` and `{{date issued_on}}`.\nA loop over a link of the record whose partner the table pairs, or over the alias of a table that links to the record\nonce, receives those rows with their fields, read under the app\'s row rules:\n\n```html\n<h1>Quote {{code}}</h1>\n<p>{{customer}} \u2014 {{money total "VND"}}</p>\n{{#each lines}}<p>{{description}} \xD7 {{quantity}}</p>{{/each}}\n```\n\nHere `code`, `customer` and `total` are fields of the record and `lines` is its link to the child table, so\n`{{#each quote_line}}`, the child table\'s alias, fills as well; a Word template loops the same rows with `{{FOR line IN lines}}` \u2026\n`{{$line.description}}` \u2026 `{{END-FOR line}}`. A link whose partner is not paired reaches no rows from the record, and\na loop printing a field of each of its items is refused, naming `pair`.\n\nEvery List the record draws and the template names (an html template\'s variables, a Word template\'s markers) hands its\nrows, each List\'s `where` applied; a List the template does not name is not read. A List that only reads hands them under its\n`key` (the table\'s alias where it states none), and a List that sums a number hands the sums under `<name>_totals`, one\nentry per number the List draws as a column or as the table\'s figure. A `where` bound may be `{ "record": "<field>" }`,\na date or number the record itself holds, so a record can print a window of its own days. A service plan row (customer,\n`period_start`, `period_end`) draws the customer\'s visits within its period:\n\n```\n{ "type": "List", "key": "visits", "entity": "visit", "same": "customer", "label": "Visits", "columns": ["visited_on", "hours"],\n "where": { "visited_on": { "gte": { "record": "period_start" }, "lte": { "record": "period_end" } } } }\n```\n\n```html\n{{#each visits}}<p>{{visited_on}} \u2014 {{hours}} h</p>{{/each}}\n<p>Total {{visits_totals.hours}} h</p>\n```\n\nA bound the record leaves blank, or holds as anything but one whole day (`2026-05`) or one figure, keeps no row:\n`visits` is empty and `visits_totals.hours` is `0`. The sums add a number as the List\'s foot does: a cell holding a\nfigure adds it, any other cell (blank, an errored formula, a lookup\'s list) adds nothing. A Word template loops\n`{{FOR v IN visits}}` and prints `{{visits_totals.hours}}` the same way. A template that names a List narrowed to the\nreader (`"me"`) is refused, and so is a name a rows List and a `list` List both reach: give the `list` a `key`. A record\nbound narrows what is listed and is never an access bound; the table\'s row rules are.\n\nA List that reads by a path (`via: "<link>.<link>"`) hands its rows the same way. A List the screen draws as an outline (a record\'s own\nsub-rows, in a table whose rows nest, with no `where`, total, group, long-text column or other narrowing) hands every sub-row, depth first, each after the row it is filed under and its\nsiblings in the List\'s order, with its depth as `level` (1 for the rows filed under the record): `{{#each tasks}}{{level}} {{name}}{{/each}}`.\nA paper that lists an outline whose table has a field named `level` is refused. Inside a listed row a link arrives as the\ntitles of its rows (`{{#each marks}}{{this}}{{/each}}` prints them), so a loop there printing a field of each item is\nrefused, naming the key a List hands those rows under; so is one drawing a table cell per title, which lines up with no\ncolumn \u2014 a grid of rows by days is a roster\'s Export (below). A Word template is read for this when it is next saved.\n\nA paper made over several rows (`on: "ticked"` or `"view"`, at most 200) is one file of them all: the rows arrive under the entity\'s alias. An html paper hands each row the child rows the record\'s paper would be handed, under the same names, with their `_totals`; an Excel or Word paper is handed the rows alone. The page the rows open draws those Lists:\n\n```html\n{{#each supplier_order}}<h2>{{code}}</h2>{{#each sources}}<p>{{description}} \xD7 {{quantity}}</p>{{/each}}{{/each}}\n```\n\nA paper over many rows (a client\'s month, a statement) is that: a record of the period whose List is windowed by its dates, made by the Act\'s `template`; or a List `Export` with `template` and `per` (`reference/export-node`).\n`reference/groups-and-templates` has the rest.\n\nA roster\'s `Export` (an html or Excel `template`) is handed its grid over the window in view: `columns`, the days\nholding a row in the file (with `expect`, every option), each a `label`, its `date` and `weekday`; and on each row (under the List\'s entity alias, `student` here)\n`cells`, a word per column \u2014 each of its rows\' mark, the option\'s `short` else its label (a row with no state, its title), joined by `, ` \u2014\n`counts`, how many of its rows stand at each option by alias (`held`, at none), and `total`, as the roster reads it (its owed or expected ratio, else the sum of the row\'s figure, else the count of the cells it holds):\n\n```html\n<tr><th>Student</th>{{#each columns}}<th>{{label}}</th>{{/each}}<th>Absent</th></tr>\n{{#each student}}<tr><td>{{name}}</td>{{#each cells}}<td>{{this}}</td>{{/each}}<td>{{counts.absent}}</td></tr>{{/each}}\n```\n\n| | A | B | C | D | E |\n|---|---|---|---|---|---|\n| 1 | Student | `{{#each-col columns}}` | `{{label}}` | `{{/each-col}}` | Absent |\n| 2 | `{{#each student}}` | | | | |\n| 3 | `{{name}}` | | `{{cells \\| lookup:@index}}` | | `{{counts.absent}}` |\n| 4 | `{{/each}}` | | | | |\n\n## Discovering and managing templates\n\nThese tools work across all five types:\n\n| Tool | Does |\n|---|---|\n| `get_workspace` | list the workspace\'s templates (`kind: "template"`), each with its id, type and one line |\n| `get_template` | one template\'s full definition, incl. the `variables` it expects and the `current_version` a change needs |\n| `set_template` | create a template, change one, delete it (`delete: true` with `template_id`) or bring it back (`restore: true`); `dry_run: true` checks the call and stores nothing; a copy is `get_template` then `set_template` |\n\nCall `get_template` before generating when you don\'t already know a template\'s variable names.\n';
|
|
1920
1920
|
|
|
1921
1921
|
// docs/knowledge_docs.md
|
|
1922
1922
|
var knowledge_docs_default = '# Knowledge Docs\n\nKnowledge docs are the workspace\'s **rulebook layer** \u2014 the facts and rules an agent can\'t know on its own: a\nprocedure, a policy, a glossary of in-house terms, a tariff book. You write them once; the agent **searches and reads\nthem on demand** while it works, pulling in only the lines it needs. They are not injected wholesale, so a 10,000-line\ntariff costs nothing until a question touches it.\n\nA menu with its prices, the customer list and the open orders are not knowledge: they are rows of tables, so apps, queries and documents\ncan use them.\n\n## Rulebook, not methodology\n\nPut in a knowledge doc the things the model **cannot guess**: your specific numbers, codes, names, exceptions and\npolicies. Do **not** put in it general skills the model already has ("how to write a polite email"). If the agent would\nget it right without the doc, the doc is noise.\n\n## Writing a doc \u2014 `set_knowledge`\n\n`set_knowledge` creates a doc when it is given no `knowledge_doc_id` and changes the named one when it is given one:\n\n- `name` \u2014 what it is. Just the name: **grouping belongs in `tags`, not in a prefix baked into every title.**\n- `description` \u2014 what the doc is **and what to grep it for**: its vocabulary and the synonyms an ambiguous query would\n use. Surfaced in the listing before any body is read, and truncated at 200 characters.\n- `content` \u2014 Markdown.\n- `tags` *(optional)* \u2014 the labels someone would filter by, e.g. `["H\u1ED3 s\u01A1 NOXH", "Kho\u1EA3n 13"]`. Give **every** one that is\n true of the doc: a corpus is narrowed by intersecting tags, so a doc carrying one label is found down one path only.\n On a change the array **replaces** what is stored, so resend the labels it should keep.\n- `files` *(optional)* \u2014 file ids of the source `.docx`/`.pdf`/`.xlsx`, stored alongside so a reader can open the original.\n\nA change sends only the fields it changes. `edits` (anchored replace, insert, append) makes a surgical change to the\nbody. Refine structure as you learn what users ask: add the synonym that failed to match, split a line that was too\ncoarse, restate a term the heading was carrying.\n\nA new doc is **owned by you and private**. `set_access` shares it: `resources[]` with `resource_type` `knowledge_doc`, and `principals[]` (a\nmember, a member group, or `organization` for everyone), each with a `role` of `user` or `manager`; a principal without a `role` has\nits access taken away. A doc reaches an agent when the member can `use` it. An organization admin can use any doc, and their agent searches what they list unless it passes `all: true`.\n\n## How an agent uses a doc\n\nRetrieval works like a filesystem, and respects access: only docs the caller may use ever surface.\n\n1. **List and search** \u2014 `get_workspace` kind `knowledge` lists the corpus (id, name, tags, a truncated\n description); a search term matches a doc\'s name, description and tags. `get_workspace` with `search` finds where something is said: it\n matches across every readable doc and returns the **doc, line number and matching line**;\n `knowledge_doc_id` or `tag` confines the lines to one doc or to the docs carrying that tag.\n2. **Read** \u2014 `read_knowledge`, a doc whole or by line range, to see the context around a hit.\n\nMatching is **not ranked**: the *agent* does the narrowing. A distinctive phrase is sharply selective, a whole question\nmatches everything. A search always reports `total_matches`, so "too broad" is visible and cheap to fix.\n\nThe `search` is **literal text** \u2014 every character matches itself. Set `regex: true` to read it as a POSIX regular\nexpression (a word boundary is `\\y`, not `\\b`):\n\n```\n{ "search": "C/O (Form E)", "kind": "knowledge" }\n{ "search": "\\\\yNK\\\\y", "kind": "knowledge", "regex": true, "case_sensitive": true }\n```\n\nAs an expression `C/O (Form E)` would search for `C/O Form E`, which is not in the document, and return a confident\nzero; the literal default has no such failure. With `regex` omitted, a literal search that finds nothing while the\npattern, read as an expression, matches (`a|b`, the commonest) returns those lines under a note saying how they were\nread. `regex: false` keeps the literal zero; a search that finds nothing either\nway says so.\n\n- **Tone marks match exactly by default.** `diacritic_insensitive: true` folds them (`ca phe` matches `c\xE0 ph\xEA`); use it\n when the pattern was typed without them, since folding lets a short word match inside unrelated ones.\n- **Case folds by default.** `case_sensitive: true` matches exactly, for an acronym (`NK` vs `nk`).\n- **Whitespace is normalized on both sides.** Non-breaking spaces, soft hyphens and padded runs from PDF, Word or Excel\n bodies fold to single spaces before matching.\n\nA search shows at most 16,000 characters, shared by what it finds in knowledge, in structure and in records. Matched\nlines are admitted first and context fills what remains; anything cut is reported, with the true number of matching\nlines. Lines longer than 600 characters are clipped and marked; `read_knowledge` gives the rest.\n\n## Write for grep\n\nRetrieval addresses **lines**. Every rule follows from that one fact.\n\n- **One self-contained fact per line.** A hit returns *that line*. For dense or tabular data \u2014 a price row, a tariff\n code \u2014 put the whole record on one line.\n- **Repeat the searchable terms on every line; headings do not carry down.** A line reading `Rate: 15%` under a heading\n `Roasted coffee` will never match a search for `coffee`. Restate the identifying terms inline, even when it reads\n redundantly to a human. This is the rule most often got wrong.\n- **Keep a line under ~600 characters,** the identifying terms early and the long tail late.\n- **Put synonyms and translations on the line itself.** A bilingual row (`C\xE0 ph\xEA, \u0111\xE3 rang / Coffee, roasted`) matches\n queries in either language.\n- **For prose, keep a rule and its exception close.** A rule on line 40 and its exception on line 90 can be retrieved apart.\n\nMarkdown headings carry no retrieval weight of their own; a doc\'s `##` headings outside its blocks, two or more, are\nlisted on its page as its sections.\n\nThe **description is the discovery hint**: it is the only clue for *what term to grep for* before a body is read. Name\nthe doc\'s vocabulary in a sentence.\n\n## Classifying a corpus \u2014 tags\n\nA doc carries a SET of labels, not a folder. Order does not matter, a doc can wear several, and the vocabulary is\nwhatever the docs themselves use. `tags` on `set_knowledge` states one doc\'s complete set.\n\n## Deleting and restoring\n\n`set_knowledge` with a `knowledge_doc_id` and `delete: true` deletes a doc: it leaves every listing, search and read. **Its sharing and version history are\nkept**, so a deleted doc is recoverable. `get_workspace` kind `knowledge` with `include_archived: true` lists the deleted\ndocs you manage, and `set_knowledge` with `restore: true` brings one back with the access it had. Each call takes one doc,\nwhich must be one you manage. A doc with no owner is restored only by an admin, who\nbecomes its owner. A doc that an app or workflow still names cannot be deleted.\n\n## Formatting \u2014 what a doc draws\n\nA doc is markdown with GFM tables. Beyond that it draws a few blocks, each in syntax you already write; the platform draws them in its own style, so every doc looks alike.\n\n| Write | Draws |\n|---|---|\n| `> [!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]` or `[!CAUTION]` opening a blockquote | a callout in that tone |\n| `<Note>`, `<Info>`, `<Tip>`, `<Check>`, `<Warning>`, `<Danger>` | the same callouts |\n| a ```mermaid fence | a diagram: flowchart, sequence, timeline, gantt, `pie`, `xychart-beta`, `quadrantChart` (a 2x2; quadrant-1, top right, is drawn as the target), in the platform\'s theme; a flowchart\'s or a 2x2\'s own colour statements are dropped |\n| `<Steps>` holding `<Step title="\u2026">` | a numbered walk |\n| `<Tabs>` holding `<Tab title="\u2026">` | switchable panels |\n| `<Columns cols={2}>` (or `<CardGroup>`) holding `<Card title="\u2026" href="\u2026" icon="\u2026">` | side-by-side cards that stack on a phone; `icon` is a glyph from the model reference (a select option\'s mark), and a name it lacks is refused with the nearest |\n| a table whose header cells are all empty | a table with no header row (a key/value table) |\n| `<Accordion title="\u2026">`, `<AccordionGroup>`, or `<details>` with a one-line `<summary>\u2026</summary>` | a section that opens on press |\n\nEach tag stands on a line of its own, and a tag line inside a fenced code block is code. Attributes are text in double quotes or a number in braces; nothing in a tag runs. A write that adds a tag that does not close, nests wrongly, carries an attribute the tag does not take, or names a component this list lacks (`<Frame>`, `<CodeGroup>`) is refused with the lines to fix; lowercase HTML (`<br>`) stays text.\n\nA chart\'s numbers live in its mermaid source, which agents read and grep like any text: write them there once, not again in a table.\n';
|
|
@@ -27048,7 +27048,7 @@ var APP_RULES = {
|
|
|
27048
27048
|
sentence: "A List over a Query stands in an App with no `scope`: the Query reads no folder."
|
|
27049
27049
|
},
|
|
27050
27050
|
"list.filter": {
|
|
27051
|
-
sentence: "A List's `filters` name a select, a member, a link, a date, a yes/no or a number of the List's own rows \u2014 a lookup through one-row links as the field it reads \u2014 never the status its chips draw, nor one `where` fixes; `values` only on a select, member or link. A List states at most 3
|
|
27051
|
+
sentence: "A List's `filters` name a select, a member, a link, a date, a yes/no or a number of the List's own rows \u2014 a lookup through one-row links as the field it reads \u2014 never the status its chips draw, nor one `where` fixes; `values` only on a select, member or link. A List states at most 3, whatever draws its rows."
|
|
27052
27052
|
},
|
|
27053
27053
|
"list.filter-split": {
|
|
27054
27054
|
sentence: "A `filters` entry on a field a Reading of the List with `by` or `across` splits the rows by \u2014 a press on its part narrows by it too; a member's filter, which narrows to the reader's own rows, is never noted.",
|