@lotics/cli 0.321.89 → 0.321.90
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 +3 -3
- package/docs/data_model.md +1 -1
- package/docs/design.md +2 -0
- 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.90";
|
|
1853
1853
|
|
|
1854
1854
|
// src/cli_dispatch.ts
|
|
1855
1855
|
import { spawn as spawn2 } from "node:child_process";
|
|
@@ -1861,7 +1861,7 @@ var getting_started_default = '# Getting started\n\nA workspace is where one bus
|
|
|
1861
1861
|
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';
|
|
1862
1862
|
|
|
1863
1863
|
// docs/design.md
|
|
1864
|
-
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| A figure a record works out from its own figures (a payslip\'s net, an invoice\'s total) | a `Statement`: its lines in the order the arithmetic runs | `reference/statement-node` |\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. A part that is the work at every open stage is no step and states no `at`; `when` shows a part only at some stages.\n\n#### Stage dates and history\n\nA step reads as done only where the row shows it was reached, by a stamped date or a history move: a finished row with neither ticks none of its earlier steps, so a path whose steps should read states `dates`. Who 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';
|
|
1864
|
+
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| A figure a record works out from its own figures (a payslip\'s net, an invoice\'s total) | a `Statement`: its lines in the order the arithmetic runs | `reference/statement-node` |\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\nWork the owner named no decider for has no status: the row saved is the fact (a goods receipt nobody approves moves\nstock as it is saved), and a stage, its owner or an approval enters with the person the owner said decides.\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. A part that is the work at every open stage is no step and states no `at`; `when` shows a part only at some stages.\n\n#### Stage dates and history\n\nA step reads as done only where the row shows it was reached, by a stamped date or a history move: a finished row with neither ticks none of its earlier steps, so a path whose steps should read states `dates`. Who 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';
|
|
1865
1865
|
|
|
1866
1866
|
// docs/app_architecture.md
|
|
1867
1867
|
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';
|
|
@@ -1888,7 +1888,7 @@ var AGENTS_default = "# @lotics/cli \u2014 agent index\n\nThe model an agent nee
|
|
|
1888
1888
|
var cli_reference_default = "# @lotics/cli \u2014 CLI Command Reference\n\nPer-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. Start at [AGENTS.md](../AGENTS.md) for the model this reference assumes; `lotics --help` is the authoritative, always-current verb list.\n\n| Command | What it does |\n|---|---|\n| `lotics` / `lotics --help` | Show full help: capabilities, the verb list (\xA7 COMMANDS), flags, config. `lotics <verb> --help` prints that verb's entries alone (`lotics app --help`, `lotics file download --help`); `lotics report --help` prints the report frame. |\n| `lotics auth login` | Sign this terminal in, on a machine holding no key; a person with no account creates one on the page it opens. It takes no argument and sends no mail. **Two steps, and it does not wait for the person.** The first prints the page to open \u2014 `https://lotics.ai/cli_login/<request_id>` \u2014 and the code that page must show, records the request, and exits 0. They sign in there if asked, check the code, pick the organization and press Confirm. A person with no account creates one there, by email and a password or with Google: the page shows the code beside the button, and one press creates the account and its first workspace and signs the terminal in; creating the account accepts the Terms and Privacy Policy. A signed-in account with no workspace gets one button that creates the workspace and signs the terminal in. On a private instance, whose people arrive by invitation, the page sends a signed-out person to sign in. **Then the next command that needs a credential collects the key** before it does its own work, so the second step is just re-running whatever was wanted; a command run before Confirm exits 1 naming the page and the code again, and once the 15 minutes are up it says to ask again. The handful that run WITHOUT a credential \u2014 `docs` among them \u2014 claim nothing, so one of those run after Confirm still answers as though signed out. `--wait` keeps one command instead, holding the terminal until Confirm; `--local` pins this directory to that org rather than setting the global default, and implies `--wait` (a pin names THIS directory, so only the terminal that stays in it can write one). `--json` prints `organization_id`, `workspace_id` and `organization_name` when it finishes signed in, and `request_id`, `confirm_url`, `code`, `expires_at` when it is the first step. The request's secret is never printed and the org's key never leaves the store. |\n| \u2014 | **A flag is refused on a verb that does not read it**, naming the verbs that do, before any request or credential: `--check` on `lotics run` would otherwise be parsed and ignored, and the write it was meant to stop would run. `--json`, `--workspace`, `--api-key` and `--timeout` are read by every verb. |\n| \u2014 | **Every call a verb makes waits for the server's answer**; `--timeout <ms>` (a whole number of milliseconds from 1 to 2147483647) stops each wait early. The wait ends without an answer when `--timeout` passes or no answer arrives from the server. A read with no answer changed nothing: the command exits non-zero naming the request id. A write with no answer exits non-zero with `error_code: \"outcome_unknown\"` and the request id under `--json`, because it cannot say whether the call took effect: read before running it again. The one fetch outside this is the download from an object-storage signed URL, which carries no request id and is stopped by `--timeout` alone. Under `--json` every error is one object on stdout: `error`, with `error_code` and `request_id` where the error has them. |\n| `lotics auth api-key [key]` | `whoami` \u2192 **upsert** the key's org as a profile in the global store (never overwrites). The profile records the instance the key was verified against (`LOTICS_API_URL`, default `https://api.lotics.ai`), and every later command for that org goes there. `--local` additionally pins this directory to it (pointer) instead of setting the global default. |\n| `lotics auth web` | Send a magic link email to access the web app (requires auth) |\n| `lotics auth whoami` | Print active account name, email, org, resolved workspace, the instance the credential belongs to, which **kind** of credential this machine holds (a sign-in from `auth login`, or an API key \u2014 read from the saved profile, and from the server when the profile does not say, which covers `--api-key`/`LOTICS_API_KEY` and a profile saved before the field existed; unknown only when neither can say), and the resolution **source** (flag/env/local/app-manifest/global). `--json` adds `workspace_id`, `api_url`, `credential_kind` + `source`. |\n| `lotics auth logout [<name\\|id>]` | In a pinned dir: delete the local pin. Else: remove the profile (default the active org), `--all` for every one. What happens server-side depends on which KIND of credential it is. A **sign-in** (`auth login`) is revoked \u2014 logging that terminal out ends its credential rather than leaving a live one behind; a server that cannot be reached, or a credential already dead, never blocks the local forget, and one line names the org and Settings \u2192 Security \u2192 *Keys and terminals*. An **API key** (`auth api-key`) is only forgotten here \u2014 an admin issued it and it is routinely on a server and on other machines, so one terminal signing out must not kill it for everyone; the line says it is still active and names both pages, because Settings \u2192 API keys is admin-only and the credential may well be the holder's own sign-in, which they revoke themselves at Settings \u2192 Security \u2192 *Keys and terminals*. A profile saved before the kind was recorded states nothing, so the SERVER is asked (`auth whoami`) and it is revoked only if the answer is a sign-in: an older server, a credential minted before the column, and a request that fails all leave it alone. |\n| \u2014 | **A refused credential says which way it is dead, and names the remedy that ends its kind.** `This credential expired.` / `was revoked.` / `belongs to a member who is no longer active in this organization.` carries `Run \\`lotics auth login\\` to sign in again.` for a sign-in and `Ask an admin for a new API key (Settings \u2192 API keys).` for an issued key. A credential minted before that was recorded still gets BOTH in one sentence, because nothing on the row tells them apart \u2014 so a headless box is never sent looking for a browser alone. A key the server does not recognize at all gets one flat `Invalid or disabled API key.` \u2014 deliberately, so a guessed key learns nothing, not even that it named a row. The body carries `reason` for a script to branch on, since the code stays `unauthorized` for every 401. Changing or resetting the account's password revokes its sign-ins, never an issued key. |\n| `lotics org` | List saved orgs (profiles) from the global store with the instance each belongs to, marks active for this directory (a local pin wins over the global default). |\n| `LOTICS_ORG=<name\\|id>` | Scope every command in this shell to one saved org. **Resolved once, before any command dispatches**, so a value matching no saved credential refuses every verb with one sentence \u2014 a read, a write, and a local check that needs no credential alike \u2014 and refuses it before the first byte is written. It refuses even when a credential arrives another way, because `--api-key` / `LOTICS_API_KEY` outrank it in the precedence chain and a write must never fall through to whatever THOSE name while the variable says otherwise; when the variable resolves and a key is also given, the key decides and the command says so. The refusal lists the orgs this machine holds, so it is answerable without another command (`lotics org` is refused by the same rule). A name is whatever the credential was SAVED under \u2014 a server-side rename never moves it, and the new name resolves too, so both keep working and `lotics org` prints the pair. |\n| `lotics org use <name\\|id> [--local]` | Switch the active org by org name (case-insensitive, ambiguous \u2192 error) or id. No flag \u2192 global `active_org`; `--local` \u2192 a `.lotics/config.json` pointer in the current dir. |\n| `lotics workspace` | List workspaces in the active org, marks current with `(current)` |\n| `lotics workspace select <id>` | Set the workspace in the **active scope** \u2014 a local pin if the dir has one, else the active org's global profile. Records the workspace's NAME beside its id, which is what the `lotics \u2192 <org> / <workspace>` echo prints; `workspace list`, `workspace create`, `workspace rename` and `org use` record it too, so a target is named rather than identified. Until one command has listed it, the echo prints the id and says the name is not known yet. |\n| `lotics workspace create <name> [--timezone <Area/City>] [--currency <ISO>]` | Create a new workspace (organization owner only), auto-switches to it. Neither flag is defaulted from THIS machine: an extra workspace is routinely created by an operator for somebody else. Without `--timezone` the new workspace inherits the zone of the org's OLDEST workspace; without `--currency` it takes the org's default. Both ride the create, so the workspace is never briefly denominated in a currency nobody asked for. `--currency` takes an ISO-4217 code (case-insensitive; anything else is refused). |\n| `lotics workspace rename <name>` | Rename the **current** workspace (an admin of that workspace only) \u2014 the endpoint takes its target from the request's workspace, never a path id, so switch with `workspace select <id>` first and read the `lotics \u2192 <org> / <workspace>` echo before trusting it \u2014 both halves are names, and the rename moves the cached one in the same act. Carries the workspace's existing `default_currency` and `timezone` through unchanged: the endpoint takes the whole settings triple, so sending only a name would blank the other two. |\n| `lotics workspace settings [--name <n>] [--currency <ISO>] [--timezone <Area/City>]` | Change the CURRENT workspace's name, default currency or timezone \u2014 `PATCH /v1/workspace`, an admin of that workspace only. Only what you name changes; the endpoint takes the whole triple, so the CLI carries the two you did not. `rename` is this verb with the name alone, which is why it can never forget the other two. Both values are invisible once they are wrong: the currency decides how every money field RENDERS and the zone decides how every date BUCKETS, on a workspace whose whole purpose may be to look like the customer's own. `--json` prints the updated workspace. |\n| `lotics workspace delete <id> --yes` | Delete a workspace by id (organization owner only). **Soft delete** \u2014 `archived_at` is set, so it drops out of listings, can no longer be selected, and its tables/records go dark, while the data is retained and recoverable. Its **apps are cascade-archived** too \u2014 every app entry point (embedded, public link, standalone subdomain, incl. anonymous public links) stops serving. Refuses the org's **only** active workspace (400) and any workspace outside the caller's org (404). Requires `--yes` to confirm (destructive; the CLI is used non-interactively). |\n| `lotics workspace doctor` | An admin of that workspace only. Report workspace-wide dangling schema references via `GET /v1/workspaces/dangling-references` \u2014 every active app/workflow artifact whose prefixed schema id no longer resolves, printed as `<referent.kind> \"<name>\" (<id>) \u2192 <namespace> <id> (missing)`; healthy prints a one-line all-clear. **Exits non-zero (exit 1) on findings** so scripts can gate on it. Resolves the first workspace like every data command (runs before the global workspace resolution). Admin-only. |\n| `lotics tools` | List tools by category with descriptions |\n| `lotics tools <name>` | Full description, input JSON Schema, and the output schema where the tool answers a shape, for one tool; a workflow step says to call it from a workflow body, not `lotics run` |\n| `lotics run <tool> '<json>'` | Execute a tool (text output via toModelOutput). Args may also come from a file (`lotics run <tool> @args.json`) or stdin behind the `-` sentinel (`cat args.json \\| lotics run <tool> -`) \u2014 both bypass the OS `ARG_MAX` limit for large payloads (a knowledge-doc `content`, a bulk update). A leading `@` on the args is unambiguously a file path (JSON args start with `{`). **Stdin is asked for, never guessed.** `lotics run <tool>` with no payload runs the tool with no arguments and returns at once. `lotics report` takes the same sentinel. In PowerShell use `@file`: quotes inside an inline argument are consumed by the shell, and the CLI reports the JSON it received with its quotes gone \u2014 the error names both escapes. |\n| `lotics run <tool> --json '<json>'` | Execute a tool (full JSON output) |\n| `lotics run <tool>` \u2014 **file cells** | A file in a tool's result carries its `fil_\u2026` id and metadata and **no `url`**, on every tool and in both output modes. That is not a broken file \u2014 this surface resolves no URL for a cell. Reach the bytes with `lotics file download <file_id>`, which takes the id straight from the cell; the text output says so whenever a result carries one. |\n| \u2014 | **Every tool is invoked here, including the ones that RUN something** (`run_app_workflow`, `run_app_query`) and every one that builds: `set_tables` (a list of table documents), `set_app` (one app), `set_workflow`. A command exists only for work that touches a local file: `app apply`, `app create --custom`, `app pull`, `app deploy`. |\n| \u2014 | **An app's queries and workflows take more than their params and inputs** (`lotics docs agent_surface`). `run_app_query '{\"app_id\",\"alias\",\"params\"}'` also takes `filters` and `sort` over the query's output columns, `fields` (the columns to return), `count` with `count_by` or `count_where`, `aggregate`, `limit` (200 rows at most; 50 where none is stated) and `cursor`, and `runs` \u2014 up to 20 reads in one call, each `{\"alias\", \u2026}`, a refused one answered with its `error`; one call's rows total at most 262,144 bytes. `export: {\"key\", \u2026narrowing}` instead of the read arguments makes the file an app's Export makes (`lotics docs agent_surface`). `run_app_workflow '{\"app_id\",\"alias\",\"inputs\"}'` also takes `dry_run: true` \u2014 a rehearsal on the real inputs, nothing written or sent; the answer is what the run would return, with the reads it made under `dry_run.reads`, the calls it would make under `dry_run.writes` and the papers it rendered under `dry_run.papers` and the parts of the answer it could not say under `dry_run.unpredicted`; a workflow no dry run is offered of answers `status: \"not_previewed\"` \u2014 and `runs` \u2014 up to 50 runs in order, the first refused, failed or not previewed ending the call, an input `{\"from_run\": <index>, \"path\": \"data.<key>\"}` reading an earlier run's answer. |\n| \u2014 | **The exit code reports the WORK, not just the call \u2014 for the tool that RUNS one.** `run_app_workflow` whose envelope carries a failed `status` (`error`/`failed`/`cancelled`, or `not_previewed` \u2014 a dry run asked for and not given) exit non-zero and print `<tool> \u2192 <status>: <message>` to stderr, so `lotics run \u2026 && next-step` cannot walk past a refused run. The rule is an allowlist of FAILURE \u2014 an unrecognized status exits 0, so a status added later never turns a working script red. A parked run (`awaiting_input`) is not a failure: it is waiting for an answer and the work is still live. Only a TOP-LEVEL `status` counts; one inside the data belongs to the data. Any OTHER tool's `status` is data, and exits 0. |\n| `lotics run <tool> '<json>' -o <dir>` | Also save every **signed link** the answer carries \u2014 an object with a `url`, a `filename` and the `expires_at` its signature ends at, at any depth, such as `screenshot_app`'s images. Each is fetched into `<dir>` (created if missing) under its `filename`, taking a free spelling beside a file of that name already there, and a link's `snapshot` text is written beside it as `<name>.txt`. The written paths follow the answer on **stdout**, one per line (on stderr under `--json`, whose stdout stays the one object). A link is signed for an hour; one the store no longer serves exits non-zero. A workspace file states no `expires_at` and is left to `lotics file download`. |\n| `lotics run set_members '{\"members\": {\"<email or member id>\": {\"role\": \"member\", \"name\": \"\u2026\"}}}'` | Invite to this workspace (`name` is the name the invitation carries) or set a person's role in it (`role`: `member` or `admin`; `null` takes the person, or the invitation pending to that address, out of it); `groups` keeps the member groups in the same call. An admin of this workspace or an organization owner. Renaming or removing a person, restoring one, co-ownership and a member who signs in by a name are a person's in Settings \u2192 Members, and no tool takes them. The whole input is checked before an email is sent. A member's `lotics tools` lists neither `set_members` nor `set_workspace`. View-as is the web app's preview alone; the CLI acts as the signed-in member. |\n| `lotics run <tool> --print-created` | Report the records the call created, grouped by table, with a paste-ready `delete_records` per table and the mandatory caveat naming what cannot be auto-undone (external integrations, notifications, possible sub-workflows). Works for any tool that returns a `side_effects` block, not workflows alone. |\n| `lotics run <tool> --cleanup` | Implies `--print-created`, then runs those deletes \u2014 harvested records **only**, never files / external calls / notifications. **Not a rollback**; a rollback is structurally impossible here. A partial cleanup exits non-zero so a script cannot read it as success. |\n| `lotics file upload <file\\|dir...>` (alias `lotics upload`) \xB7 `--stdin` \xB7 `--base64` \xB7 `--url <url>` | Upload files/directories. **The transport is chosen by size and is not a flag**: under 8 MiB the file is POSTed to `/v1/files`, several such files to a request up to half that route's 100 MiB cap; at or above it the CLI takes presigned part URLs and PUTs the bytes straight to object storage, so they never pass through the API. That threshold matches the AWS CLI's own `multipart_threshold`, and the number matters less than there being nothing to choose \u2014 one verb, any size, up to the 2 GiB a workspace may store. A large upload reads one part at a time, so memory stays flat regardless of file size, and a failure part-way abandons the parts already sent rather than leaving them billable and invisible. A directory expands to its immediate files; `--as <name>` renames a single upload. **Three alternative byte sources, for a caller that never had the bytes on disk** \u2014 an attachment decoded in memory, a generated document, a signed download link \u2014 each mutually exclusive with the others and with a path argument: `--stdin` takes raw bytes on stdin, `--base64` takes base64 on stdin (the shape attachments arrive in), `--url <url>` fetches the URL first. `--stdin`/`--base64` REQUIRE `--as`, because stdin carries no filename and the mime type is derived from it; `--url` falls back to `Content-Disposition` then the URL's last path segment. `--base64` decodes STRICTLY \u2014 `Buffer.from(s, \"base64\")` silently skips invalid characters and truncates on bad padding, so a corrupted pipe would otherwise store a short file that only fails when a human opens it. The `--url` fetch happens in the CLI, not the server: the URL comes from the operator running the command, so routing it through the backend would add an SSRF surface to buy what `curl` already does. |\n| `lotics file download <file_id> [<path>]` \xB7 `-o <dir>` | (alias `lotics download`) Download a stored file: `GET /v1/files/{id}/signed_url` \u2192 fetch the presigned URL and write it where you asked. **The two spellings mean two different things, and neither is read by shape: the positional `<path>` is the FILE to write, `-o <dir>` is the DIRECTORY to save into.** That is `cp` and `curl -o`, so nothing here consults an extension. A named file is written as named, its parent created, overwriting what is there \u2014 the point of naming it is that the next command opens that exact path. A directory is created if missing and written into under the stored filename (the response's `Content-Disposition`), taking a free spelling beside a file of that name already there so a repeat download never clobbers the first; with no destination at all, that filename lands in cwd. Give the destination once \u2014 a positional and `-o` together is refused, as is a positional that names an existing directory or ends in a separator (`a directory goes in -o`). The first argument is a **file id**, so a path in that slot is refused rather than sent as an id. The written path goes to **stdout** (under `--json`, `{file_id, path, filename, stored_filename}`) and the narration to stderr, so a download pipes into whatever opens it. `lotics file download record <record_id> <field_alias> [-o <dir>]` (the field named by the alias `query_records` shows it under) spreads every file on a record's file field over a DIRECTORY \u2014 there is no single file for N files to be. |\n| `lotics file list [--limit <n>] [--cursor <token>]` | The workspace's files, newest first \u2014 id, upload time, bytes, MIME type, filename on stdout, one per line (`--json` for the object). `GET /v1/files` with no `file_ids`. A file holding the content of a knowledge doc or template you cannot use is left out. **A page, not a dump**: the store only ever grows, so the last line prints the command for the next page and `next_cursor` is null on the last one. The cursor is opaque and keyset \u2014 pass it back as given \u2014 so an upload landing mid-sweep cannot make a walk skip or repeat a row. Every other file verb takes an id, so this is the only answer to \"what is in here\" short of reading Postgres. |\n| `lotics knowledge list [--include-hidden \\| --deleted]` | `GET /v1/knowledge_docs` \u2014 a table of id, name, tags, description (`--json` for the docs). **REST, not `get_workspace` kind `knowledge`**: the tool answers what the ASSISTANT may browse, and a hidden doc is out of that corpus by definition, so a tool-backed listing could never show one and the person who hid it would have no way back to it. Hidden docs are left out unless `--include-hidden` asks; those rows are marked `(hidden)`. **`--deleted` is the one tool-backed form**: it calls `get_workspace` with `kind: \"knowledge\"` and `include_archived: true`, page by page, and prints the deleted docs you can manage (id, name, deleted time, description); it cannot be combined with `--include-hidden`. |\n| `lotics knowledge create --name <n> [--description <d>] [--tags <a,b>] (--from <file.md> \\| --content <str>)` | Read the body client-side (a file XOR an inline string \u2014 exactly one required), then call `set_knowledge` with `{ name, description, content, tags? }` and no `knowledge_doc_id`, which makes a doc (description defaults to `\"\"`). `--tags` files the doc as it is made, which is the only moment a corpus reliably gets labelled. Prints the new id to stdout. Large files ride the POST body fine. |\n| `lotics knowledge get <id> [-o <file.md>]` | `GET /v1/knowledge_docs/{id}` (`getKnowledgeDoc`) \u2192 the doc with its **hydrated `content`** (the one whole-content read for a non-sandbox client; the tool `read_knowledge` reads a line range). `-o` writes the body via `writeFileAtomic`; else the body goes to stdout. `--json` prints the full doc instead. |\n| `lotics knowledge update <id> [--from <file.md> \\| --content <str>] [--name <n>] [--description <d>] [--tags <a,b>]` | Call `set_knowledge` with a `knowledge_doc_id` and **only** the provided fields (a body from --from/--content becomes `content`; the tool diffs + CASes the content change internally, so the CLI passes no `expected_content_file_id`). `--tags` REPLACES the doc's label set \u2014 the single-doc form, where the caller is looking at one doc and can state what it should carry. At least one field required; --from and --content are mutually exclusive. |\n| `lotics knowledge tag <id...> [--add <a,b>] [--remove <c,d>]` | `PATCH /v1/knowledge_docs` with `{ knowledge_doc_ids, add_tags?, remove_tags? }` \u2014 one transaction over the whole set. A **DIFF applied to each doc's own labels**, never a replacement: the docs named on one command line carry different labels, so one array across them would strip whatever the others were filed under. Removal matches case-insensitively; adding a label a doc already carries writes nothing. Ids may be separate arguments or comma-separated. At least one of --add/--remove required. |\n| `lotics knowledge hide <id...>` / `lotics knowledge unhide <id...>` | `PATCH /v1/knowledge_docs` with `{ knowledge_doc_ids, hidden }`. Hiding takes docs out of every **listing** \u2014 the Library's list, and the corpus `get_workspace` lists and its `search` searches \u2014 while leaving IAM untouched and keeping them readable **by id** (`read_knowledge` with an id, a code run staging one, an app agent's declared set). So it can never silently break an app that depends on a doc, and unhiding costs nothing. Refuses the no-argument form rather than reading it as \"everything\". |\n| `lotics knowledge rm <id...>` | Delete docs via `set_knowledge` (`{ knowledge_doc_id, delete: true }`), one call per id: each must be a live doc you manage that no app or workflow names, and the command reports which succeeded and which failed. Sharing and history are kept. The REST execute path does not gate `needsApproval`, so this runs unattended. |\n| `lotics knowledge restore <id...>` | Bring deleted docs back via `set_knowledge` (`{ knowledge_doc_id, restore: true }`), one call per id: each must be a deleted doc you manage, and the command reports which succeeded and which failed. Refuses the no-argument form. |\n| `lotics app create <name> --custom [path]` | **A custom-code app**: creates the app (`POST /v1/apps`) and links `[path]` (default `./<name>`, made when absent) to it by writing `package.json#lotics` (the app and its workspace, which is how `app deploy` in that directory finds both) \u2014 into the project's own `package.json` when it has one, every other key kept, otherwise a `package.json` holding the link alone. Nothing else is written and nothing is installed: the project is yours. `app deploy` needs `@lotics/app-sdk` (React 19) and an `npm run build` that writes a static `dist/` with an `index.html`. A directory already linked to an app is refused before the app row exists. The app has no version until the first `lotics app deploy`. `--custom` is required: a JSON app is made by `lotics app apply` (the tool `set_app`). The SDK's reference is `node_modules/@lotics/app-sdk/AGENTS.md` once the project installs it. |\n| `lotics app pull [app_id] [path]` | **An app's live definition, pulled.** The app is read with `get_app`: its author is shown a body, a JSON **tree** (with the addresses of its nodes) pulled as that tree and a custom-code app (its identity and Query nodes) as its source; an app whose stored tree does not read in this release is pulled as it is stored, with a warning giving the reason `get_app` gives (where the stored value is not a JSON object, nothing is pulled and the reason is the error); an app that shows the caller no body (the caller does not author it, or it has no version) is refused. **A JSON app**: the tree is written as JSON to `[path]` (a directory receives `./<name>.app.json`; default `./<name>.app.json`), and the app's id and current version beside it in `<file>.lotics.json` (`{ \"app_id\": \"\u2026\", \"version_id\": \"\u2026\", \"digest\": \"\u2026\" }`, the digest being the file as the CLI last left it; a record without all three is refused by `app apply`, naming `lotics app pull`) \u2014 a custom-code project records both in `package.json#lotics`, a single file has no such place \u2014 so the next `lotics app apply <file>` edits that app, and is refused if the app has since moved past that version. An existing file is overwritten only when its `.lotics.json` names this same app and the file is unchanged since it was last pulled or applied; a file with edits, or whose record names the app but no digest, is refused, naming `--force`, which overwrites it. `--force` is a flag of `app pull` alone. `--json` prints `{workspace_id, app_id, path, outcome}`. **A custom-code app**: its live source, as a project ready to deploy on it. The target is `[path]`, else this directory when it is the app's project (or no app is named), else `./<name>`. **The app's own project is brought up to date in place** \u2014 but only when it holds no edit since the version `package.json#lotics.current_version_id` names: its source (packed as a deploy packs it) is compared with that version's archive, ignoring `.lotics/` and `package.json#lotics`, and any difference refuses the pull, naming the changed files; a pull never merges, so local work is never lost. Already at the live version is a no-op that says so. **An empty or new directory receives the source whole**; any other directory is refused. Downloads come from `GET /v1/apps/{id}/versions/{version_id}/source`. `package.json#lotics` is then set to exactly the app, its workspace and the pulled version, dropping every other key an older CLI wrote there, so the next `lotics app deploy` builds on the live version; then `.lotics/` is written (`GET /v1/apps/{id}/types`) and dependencies installed (`npm ci` with a lockfile, else `npm install`, both `--ignore-scripts`). |\n| `lotics app apply <file> [--app <app_id>] [--check] [--json]` | **A JSON app, one at a time, through the tool `set_app`.** The file is an app's tree (`lotics docs reference`: the App node with the nodes under it, its tables and templates named by alias). **No app known** (no `--app`, no `<file>.lotics.json` beside it): the file is sent as `{ \"body\": \u2026 }` to make a new app, named by the body's `name`, and the id made is printed, then recorded with its version in `<file>.lotics.json`. **An app known**: its current tree is read (`get_app`) and the **RFC 7396 merge patch** that turns it into the file is sent as `body` with the `app_id` and the version the patch was computed against as `base_version_id` \u2014 a key the file drops is `null` in the patch, a list is replaced whole, what the file leaves alone is left alone, and a tree the app already has sends nothing and says so. **A file pulled at a version the app has since left is refused** where the stored tree changed since the pull (a version that moved only for a workflow's body applies) before anything is sent, naming both versions and `lotics app pull <app_id> <path>`: pull the current tree into another path, carry the edits over, apply that file. `--app` naming an app other than the sibling file's is refused too. A write that races the apply is refused by the server, which names the app's current version. A file that sets an object key to `null` is refused naming the key, since a merge patch reads `null` as a removal. `--app` names the app, else the sibling file does; an app whose `get_app` shows no body (it is not yours) is refused, **over a stored tree that does not read in this release the file is sent whole** (`set_app` with `app_id`, the file as `body` and the version read as `base_version_id`; no merge patch is computed against a tree that does not read) where it states `\"type\": \"App\"`, and any other file is refused, naming that only a whole tree replaces it; a custom-code app takes its identity (name, description, icon, colour) and, where the file states `children`, its Query nodes, which replace every query it holds; a file stating none leaves its queries alone and no `<file>.lotics.json` records it, since an identity write makes no version \u2014 its source deploys with `app deploy`. **The file is never rewritten**: a node the tree leaves out draws as the rows call for it and is stored nowhere (`lotics docs design`). It prints what `set_app` answered and reports its `outcome`: its notes and findings, every finding at once, and the saves, adds and Deletes the write grants and removes. **`--check` sends `dry_run`** (a flag of `app apply` alone, as is `--app`) \u2014 what would refuse the tree, and what it would grant and remove \u2014 and writes nothing, the file and its sibling included; an `outcome` of `refused` exits 1. A tree the app already has, or one `set_app` answers `unchanged`, records the version the app stays at in the sibling. **To go back to an earlier version, apply the earlier tree again.** Resolves and ANNOUNCES its workspace first. `--json` prints `{workspace_id, app_id, outcome, write}`, `outcome` being `set_app`'s: `created`, `updated`, `unchanged` or `refused` (with `--check`, what it would be). |\n| `lotics app deploy [-m <message>]` | **Build this directory and upload it as a new version of the live app.** Rewrites `.lotics/` with the declarations of the app's live bindings (`GET /v1/apps/{id}/types`, replacing each file there), then runs the project's `npm run typecheck` (warned about when absent; a type error in the app's own files stops the deploy, one inside an installed package is reported and does not) and `npm run build`, tars the source (without `node_modules`, `dist`, `.git`, `*.tsbuildinfo`) and `dist/`, and posts both to `POST /v1/apps/{id}/versions` on the version `package.json#lotics.current_version_id` names, then stamps the new one there. The version carries the app's queries, workflows, agents and capabilities forward unchanged \u2014 those are written through their tools. A project with no `build` script, or whose `package.json#lotics` still declares `queries`, `workflows`, `agents` or `capabilities`, is refused before anything is built; the refusal names the tool that sets each. **A 409 because another version went live since this directory's last deploy** (a deploy from elsewhere, a rollback) prints the server's sentence and the version that is live, and names `lotics app pull`: run in this directory, it brings an unedited project up to date, and lists the files a project with edits changed, to carry over into a fresh pull. `-m` (or a bare positional) is the version's message, optional. The workspace comes from `package.json#lotics.workspace_id` unless `--workspace` / `LOTICS_WORKSPACE` names another. |\n| `lotics docs` \\| `lotics docs <area>[/<section>]` \\| `lotics docs [<area>[/<section>]] --grep <text>` | **This CLI's own references, carried inside the binary** \u2014 the model reference, this index, and every doc under `docs/` \u2014 so the doc a reader opens describes the binary answering, listed by the job a reader comes to do. Capped at ONE PAGE: a doc that does not fit prints its opening and the addresses of what it holds (`lotics docs <area>/<section>`, each section's size beside it, or a table's row names), and every address prints within a page. **A reference the binary's copy lacks, or a part of one the server serves, is read from the server's `docs` tool** with this machine's credential, after the copy's refusal \u2014 a page the server added since this binary was built, which a server refusal can cite. A name matching more than one reference, or a part missing from a guide to this CLI, is answered by the copy alone. **`--grep` searches the references the server serves** (not this CLI's own guides, which it refuses), with this machine's credential, narrowed to the area or section named: literal text unless `--regex`; a literal search that finds nothing while the pattern read as an expression matches (`a|b`) returns those lines under a note saying so, and `--literal` keeps the literal zero; with `--case-sensitive`, `--diacritic-insensitive`, `--context-lines <n>` and `--limit <n>` \u2014 the dialect the knowledge lines of `get_workspace` with `search` are read in \u2014 each hit under the address that opens its page; any of those options without `--grep` is refused. A custom-code app's SDK reference ships inside `@lotics/app-sdk` in the app's `node_modules`. |\n| `lotics upgrade` | Update this CLI in place. Runs the same installer a person would, chosen by how THIS copy arrived: an npm install upgrades through npm, a script install re-runs the script \u2014 the runtime knows which (the executable is compiled, the npm bin runs under node), so nobody has to. It downloads nothing itself; resolving a version, verifying the checksum and replacing a running executable already exist in the installers, and a second copy of that inside the binary would be a second thing to get right. Replacing the binary while it runs is safe \u2014 a rename leaves the running image mapped on unix, and on Windows the installer moves the old aside precisely because the file is in use. Already current is a no-op that says so. Needs no auth. |\n| `lotics docs reference` \\| `lotics docs reference/<section>[/\u2026]` | **The reference for tables and apps, from inside the binary** \u2014 at this CLI's version; `lotics docs` lists it under \"Build an app\", after `design`. Its first page is what the documents compose with, the working order (jobs \u2192 tables and fields \u2192 `records` \u2192 one app per job \u2192 one `set_tables` call with every table, then every `set_app` call) and the section addresses; every page of it is whole. Every key of a table document and an app body, every field `type` with the config each one needs, the option / view / inline-template shapes, `records` (how a row of a table is recognised), `write_rules`, the apps (each register, record, act and check), the row format (relative dates `@today` / `@month-start` with whole-day offsets; links as `\"<table-ref>:<row-ref>\"` or a stored record's id), the rules, the caps of one `set_tables` call, and a worked example; **Offline, no account.** |\n| `lotics report '<json>'` \\| `lotics report @report.json` | File a report with the Lotics team about what got in your way. **Covers the classes telemetry structurally cannot see**: a capability that does not exist (no command ran, so nothing was recorded), a command that exited 0 having done the wrong thing, an error whose message did not name the remedy, and anything that made authoring slower than it should be. **A frame, not a paragraph** \u2014 `{goal, actual, expected?, tried?, wanted?}`, `goal` and `actual` required, unknown keys dropped rather than refused. **No severity or category.** Ingest is inline JSON, `@file`, or `-` for stdin. A bare sentence is refused with the frame printed beside it, so the fix is one step; a bare invocation prints the frame BEFORE asking for a credential, since someone whose key will not resolve is exactly who has something to report. **Not spooled**: unlike telemetry it posts inline, prints whether it landed, and exits non-zero if it did not, echoing the report back so a failed send never loses it. Runs regardless of `LOTICS_TELEMETRY` \u2014 invoking it IS the consent that passive collection needs an opt-in for \u2014 but with telemetry off there are no recorded commands to attach, and it says so rather than implying context it does not have. Requires auth. Never paste records, file contents, or credentials. **Prints the id of each frame filed** \u2014 a filing nobody can cite cannot be answered about. The ids come from the server, so an instance that only logs the frames prints the count alone; the CLI never mints one of its own, which would hand back a token that resolves to nothing. |\n\n";
|
|
1889
1889
|
|
|
1890
1890
|
// docs/data_model.md
|
|
1891
|
-
var data_model_default = '# The data model \u2014 tables, their fields, and how they relate\n\nThe decisions here outlive any one app, and most become expensive the moment a second screen depends\non them. They stand apart from building an app on purpose: **every workspace starts with tables\nand many never get an app**, so schema design is not a chapter of app building.\n\nThe rules below share one signature. **Both sides read correctly on their own**, so nothing reports\nthe problem \u2014 no error, no empty column, no failing query. Each is found by looking for it. Then,\nunder **Fields**, what each field type takes.\n\n## One fact, one column\n\n**Read the table\'s existing fields first (`get_table`), and add nothing that stores a fact the table already\nstores.** A value written as text and the same value held as a `link` are one fact in\ntwo columns \u2014 a customer\'s city typed into a text box beside a link to the city record, a status\nword beside the select that decides it, a total beside the formula that computes it.\n\nTwo columns for one fact do not stay equal. Some writer sets only one of them, and nothing reports\nthe divergence: both rows still look correct on their own. A reader that then matches on the text\nhalf treats "Acme" and "Acme Ltd" as different records, so an import creates a duplicate every time\nit runs.\n\n- **Prefer the link, the select, or the formula.** Text is a RENDERING of a record; compose it when\n you read, rather than storing it a second time.\n- **Renaming, retyping or re-pointing the existing field beats adding another.** A field\'s key is\n stable, so a rename breaks nothing that addresses it by key.\n- **Superseding a field means DELETING it**, not leaving it beside its replacement with a\n description that says which one is real.\n- **Empty is not the same as redundant.** A field nothing fills may still be the only home for a\n real distinction \u2014 read what it MEANS before removing it.\n- **A stored field becomes required only once every row holds a value**, so it always holds one: state its `default`,\n which the same write fills into every row holding it empty (a draft takes it when submitted), or fill the empty cells\n first; without either, the write is refused while a row holds it empty. A computed field\'s flag is checked as each row is written.\n Making a field required rebuilds the JSON apps that create its rows, so their creates set it; a workflow its author\n wrote, or a custom-code app\'s, that creates rows of the table without it refuses the change, naming each \u2014 a `default`\n lifts that, as does setting the field in each create; an autonumber, a derived date and a computed field fill\n themselves, and a copied field (`default_from`) fills only when the row sets its link.\n Changing a stage\'s date, the status\'s `default` or the status is refused while a stored create relies on the stamp, naming each workflow.\n\n## One entity, one table \u2014 and the test is measurable\n\nVariation belongs in a column \u2014 a multi-select role, a kind, a stage \u2014 not in a second table. Two\ntables for one kind of thing give the same real-world entity two rows, two ids and two halves of its\nhistory, and each screen shows whichever half it happens to link to.\n\nSplit tables are often right. A supplier book beside a customer book is a normal shape, and merging\non suspicion is a large repoint bought for nothing. So do not argue it in the abstract:\n\n> **List both tables\' names and look for one that appears in both.**\n\nNone means the split is holding. One means it has broken \u2014 the usual cause is a party you begin to\ninvoice as well as buy from \u2014 and the fix is to merge before a second screen depends on the copy.\n\n## One vocabulary wherever values are COPIED between tables\n\nTwo `select` fields for one concept carry different option keys even when their labels match. Copy an option by its\nalias or label: the record tools match an option by alias or label, so a value copied by alias lands\non the option of that alias on the other field. Prefer a link to a shared reference table where the set is open or\ngrowing. Where one side holds more values than the other, the wider side must **refuse** what the narrower one cannot\nexpress rather than quietly picking the nearest value.\n\nA value read through a link or a lookup reads exactly as the same field would on its own row: an option written by its alias in\na body and read as that alias, a member or a link by its id. A value a check matches\nacross tables is a link to one table, or a select whose options state the same aliases: two selects that state no alias in common never compare, and a save that compares them is refused, in a check\'s lookup too. A filter or a write on another table\'s select takes a value read from this one by its alias, else its label.\n\nA lookup reads as one flat list of the values it looks up, in a check and in every body: `first(record.x)` is the one value through a one-row link and `includes(record.x, v)` asks whether any row holds `v`; two selects that state no alias in common never compare. A single member, a single select, a number or a text reads as the value itself, and `first(...)` of one is refused when the body is saved. A rollup that adds up (a sum, a count) over no rows is 0, never empty, as `sum` over an empty list is; a min, a max or an average over no rows is empty.\n\n## A copy boundary accounts for EVERY source field\n\nEach field on the source gets a column on the destination, a deliberate drop with the reason written\ndown, or a refusal.\n\nA field with nowhere to land is data destroyed at the boundary, and it is invisible afterwards: the\ndestination is not empty and not obviously wrong \u2014 just a number that no longer agrees with where it\ncame from.\n\n## Provenance is a LINK, not a flag and not a copy\n\nA row created BY another row carries a link to it.\n\nThat link is what makes "is this the estimate or the actual", "where did this come from" and "have we\nalready imported this" answerable at all. A boolean records that something was true once; a link\nstays true, survives a rename, and lets the next write UPDATE the original instead of adding a second\nrow beside it.\n\n## Say what makes two rows the SAME row\n\nState it as the table\'s `natural_key` (`reference/write-rules`); a text key is also `unique`.\n\nAnything that imports, reconciles or de-duplicates has to decide identity, and with no declared key it falls back to\ncomparing displayed text \u2014 which is how one company arrives three times under three spellings. Name the key: a reference\nnumber, a tax id, a link plus a period. Then match on record ids and option aliases, never on rendered labels.\n\n## A row that belongs to another by its VALUES holds a link\n\nAn adjustment belongs to its person\'s month, a payment to its customer\'s statement: the row holds an ordinary link to\nthat row, set when the row is made \u2014 by the screen that adds it under its parent, or by a table workflow that finds the\nparent from the row\'s values. A rollup through the link then reads live, and the link stays a person\'s to correct.\n\n## A stage\'s moment is a date on the row\n\nWho changed what, and when, is the platform\'s audit trail, which an agent already reads (`query_audit_logs`) under\nits own access to the table \u2014 so it is never a table of yours, and an app shows none of it: a history an app shows is\ntable-backed (`records.status.dates`, `records.status.history`, an event table an act makes).\n\nWhen the business reports, filters or prints the moment a row reached a stage (completed on, cancelled on), that\nmoment is a `date` field of the row, as `completed_at` and `canceled_at` are in SQL. State it as `records.status.dates`\n(`reference/status`): option \u2192 date. The record write path stamps it as a row is made at the option or moved into it,\nwhoever writes, so no one has to remember; a value the same write states wins, which loads past data as it happened. The\nplatform never clears a stamp: each date is when the row last entered the option, and leaving keeps it, and putting a\nchange back restamps nothing. A date range is a span, never a moment, so it is refused. It is the one way a status is\ntimed: a stage\'s `within` runs from its date, a straight-line process is one select whose options are its steps, each\ndated, and the stage is never read off a run of dates.\n\n`records.status.history` is for a business that reports on every move \u2014 moves per person, or time in a stage a row\nre-enters \u2014 and the platform appends one row per move. An event that carries facts of its own (a reason, an amount, a\nsignature, an inspection\'s findings) is its own table with those fields, made by the act that records it.\n\n## Keep derived chains shallow\n\nFormulas and rollups are computed and STORED when a row is written, and one that reads another recomputes with it. A\nrollup over a formula over a formula is paid three times on every touch, and again for every row upstream of it.\n**Depth costs more than row count**: chain depth is yours to keep down, row scanning is the platform\'s. A figure that\nreads itself back through its rows\' links (a task\'s total counting a subtask that lists the task) never settles: the\nwrite that closes the loop is refused, naming the row and the link, and so is a later write reaching it until a link is\nremoved. A figure read through a chain of rows settles up to 256 rows deep in one write.\n\n## Fields\n\nA field is stated inside its table\'s document in a `set_tables` call, keyed by alias. A name people read (a\ntable\'s, a field\'s, an option\'s) is in the owner\'s language; an alias stays English. Every field `type`, the\nkeys each one takes (notation, defaults, options, links, formulas, rollups, lookups, copies) and a worked\nexample are in `docs path="reference/field"`; this page holds the choices around them.\n\n### Types and formats\n\n`type` is one of `text`, `number`, `date`, `boolean`, `select`, `member`,\n`link`, `files`, `formula`, `rollup`, `lookup`, `autonumber`.\n\nA URL, an email, markdown, a checkbox, a datetime, money, a quantity or a percentage is a `format`\nor a `notation` on another type, never a `type`:\n\n| Wanted | Field |\n|---|---|\n| URL or external link | `{ type: "text", format: "link" }` |\n| Email or phone | `{ type: "text" }` |\n| Markdown | `{ type: "text", format: "markdown" }` |\n| Checkbox | `{ type: "boolean" }` |\n| Money | `{ type: "number", notation: { style: "currency", currency: "USD" } }` |\n| Quantity | `{ type: "number", notation: { style: "unit", unit: "kg" } }` |\n| Percentage | `{ type: "number", notation: { style: "unit", unit: "percent" } }` |\n| Datetime | `{ type: "date", format: "datetime" }` |\n| Month (a payroll or billing period) | `{ type: "date", format: "month" }` |\n| Date range | `{ type: "date", format: "date_range" }` |\n| Time of day (a class at 16:00, any day) | `{ type: "text", format: "time" }` |\n\nA unit is written in any of its words, the workspace\'s language included, and stored as its code: `ng\xE0y` and `days` are\n`day`, `gi\u1EDD` is `h`. A time of day is stored `HH:mm`; `min` and `max` bound one by another time field (an end after its\nstart), and a table\'s `no_overlap` spans two of them (`reference/write-rules`).\n### Changing a field\n\nRead the table with `get_table`, which answers its document exactly as `set_tables` takes it, then send `set_tables` with\nthe `table_id` and only what changes. The table is edited by an RFC 7396 merge patch of its document, so what the patch\nleaves alone is left alone and `null` deletes the field it names. Every key a table and a field take is in\n`docs path="reference/tables"` and `reference/field`.\n\nA table is named by its alias wherever a call names one (`table_id`, a link\'s `table`, a lookup, `records.history`), and a new table in the call is named by its `ref`, which becomes its alias. The alias is kept while the table exists, archived or not: asking for one an archived table holds is refused, offering to restore that table or to choose another alias. A filter in a table document (a rollup\'s `filter`, `options_where`, a colour\'s condition, a check\'s lookup) takes the record tools\' operators and values (`is`, `is_any_of`, `gte`, a plain date as a day). An `autonumber` field takes `next` (`"next": 232`): the number its next row gets, refused below the highest already issued.\n\n- **A list is replaced whole**, so an option cannot be nulled. To rename, recolour, add or remove an option, restate the\n field\'s whole `options` list, each option with its alias (`reference/field/select`). A rename changes the label and every\n record keeps its value; an alias left out is removed, which needs `force` while rows hold it.\n- **A number field becomes an `autonumber`** when every row holds its own whole number of 1 or more: the numbers are kept\n and the next row takes the one after the highest (a `next` must be above it). Otherwise the call is refused, saying how\n many rows are blank, repeated or not whole, with up to 5 row ids. No other type converts to or from an autonumber; add\n one as a new field, which numbers the rows already there from 1 (or from `next`) in creation order.\n- **Splitting an option is a rename plus an add.** The old option keeps its alias and takes the first part\'s label, so its\n rows and every app reference to it keep working; the second part is a new option. Rows that belong to the second part\n are then moved by a filtered `update_records`.\n- **A status history holds every option its status ever had** and follows them in the same write: an option added or renamed\n on the status is added or renamed on the history, which a call never restates. Removing an option on the status leaves it\n on the history, because the moves already written hold it. A call that changes nothing of the status\'s options leaves the\n history alone, and options only the history holds stay. Deleting a row deletes its history rows with it, and restoring\n the row restores them; they never hold a delete back.\n- A link names its table by id, or by the `ref` of another table of the same call, and states its `multi`. A two-way link\n states `pair` on one table, as `true` or as a free alias, and the platform makes the partner on the other table with the\n inverse cardinality; a many-to-many link states both sides, since the inverse of many is not decided.\n A link to its own table pairs with itself when `pair` is `true`, and with a second field of that table when `pair` names it\n (a parent and its children).\n A link already holding rows is paired the same way, with its partner stated beside it in the call: the partner is filled from\n the links the rows hold and no cell of the link is rewritten. `pair: null` lets a pair go, both fields staying one-way links\n with their values; a field that holds one row, the partner or the link itself, refuses a pair two rows would crowd, naming the rows.\n The partner may stand on a table the call does not name: `pair: "<alias>"` makes it there, or pairs the one-way link that table\n already holds under that alias, and the answer lists that table among the call\'s. Only someone who manages that table may.\n- A formula\'s `output_type` is inferred from its expression; state it only to override.\n- **A call\'s removals are judged together, on what the call leaves.** A table and the links and lookups naming it, removed in one call, pass; every reader left outside the call is named in one answer, not one per retry. An app reading a field or an option that leaves is rebuilt in the same call, and the answer (a dry run too) lists each node of its tree that changed: a column, a filter, a sort key, a field of a part that only drew the field, a child List the platform composed is dropped when its link leaves, with the part left holding nothing by that and the page the platform composed for its rows; a step the platform composed is dropped when every option it stands at leaves; a filter whose field the rows no longer draw is left out; and an option leaves every list of options it stood in. What has no meaning without it refuses the call, naming the node: an act that sets a removed option, a part or step holding content you stated that is left with nothing, a child List you stated more of whose link leaves, a list that held only the removed option. An app drawing a field that is retyped, or a link pointed at another table, is rebuilt too, its tree unchanged: where the field no longer lets the tree draw what it drew, the call refuses, naming the node, and a field that became a formula, rollup, lookup or autonumber leaves the app\'s allowlist of saves. A workflow body its author wrote is never rewritten: it is checked again against the tables as the call leaves them, and the call refuses, naming the workflow, only if it no longer checks. A table\'s check or workflow that reads a retyped field or a link pointed elsewhere is judged the same way and refuses, naming it, only if it no longer holds. Deleting one field through the table\'s field route drops no node: an app whose tree draws the field refuses it, naming the node.\n- **A field something reads cannot go.** A query, a workflow, a check, an app only its owner can rebuild, or another\n table\'s formula, rollup, lookup or copy that reads the field refuses its deletion, naming the reader. Change or remove\n the reader first, or in the same call.\n- **`force` consents to losing values:** deleting a field rows hold, removing an option rows hold, and a change of type\n or format that does not convert every value (a date made a month cuts a day other than the 1st, a text made a time\n clears a cell holding none). Unforced, the call is refused naming the cells; the API\'s table and field routes take\n `force` in the body and refuse with `error_code` `ConversionNeedsForce`, its `findings` counting the `cells` per field. A formula, lookup or rollup holds what it computes, so it is deleted without it.\n- A field the call makes required with a `default` answers how many rows took it: `defaulted` per field alias on\n `set_tables`, `rows_defaulted` on the API\'s table and field routes.\n- A money formula is proven by its numbers. `query_records` with `aggregate` the affected totals before the change and after, and\n compare. A new field in a formula is tested for the value you want, never for differing from an empty cell, which reads\n `""` and differs from every option.\n- A check\'s expressions are written in the language of `workflows/table-checks`.\n- Views are written with `set_table_views`, not `set_tables`: `views` is keyed by a view\'s id (patch; `null` deletes) or a new key (create), and `order` lists view ids or new keys. `get_table` lists each view\'s id and name and returns the definitions with `views: true`.\n- A refused edit writes nothing and lists everything wrong; `dry_run` is for reading the grants it would make or deciding `force`.\n\nA worked call: add the option `cancelled` to `stage` (the whole list restated), add a check, and consent to losing\nwhat rows hold.\n\n```json5\n{\n "tables": [\n {\n "table_id": "<id of the table>",\n "fields": {\n "stage": {\n "options": [\n { "alias": "draft", "label": "Draft" },\n { "alias": "confirmed", "label": "Confirmed" },\n { "alias": "cancelled", "label": "Cancelled", "color": "red" }\n ]\n }\n },\n "checks": {\n "returns_after_leaves": {\n "on": ["create", "update"],\n "when": "!isNull(record.returns)",\n "fail_when": "record.returns < record.leaves",\n "message": "\\"Return before departure\\"",\n "field": "returns"\n }\n }\n }\n ],\n "force": true,\n "dry_run": true\n}\n```\n\nSplitting `queued` into waiting and underway is one call of the same shape:\n\n```json5\n{ "tables": [{ "table_id": "<id of the table>", "fields": { "stage": { "options": [\n { "alias": "draft", "label": "Draft" },\n { "alias": "queued", "label": "Waiting" },\n { "alias": "underway", "label": "Underway", "color": "green" }\n] } } }] }\n```\n\n`table_id` picks the table patched; `fields` merges by alias, so only `stage` changes; `checks` adds one under its alias\n(`null` removes it); `force` consents to losing values (leave it out unless rows hold a removed option); `dry_run`\nchecks and writes nothing, for reading the grants or deciding `force` before the call that writes.\n';
|
|
1891
|
+
var data_model_default = '# The data model \u2014 tables, their fields, and how they relate\n\nThe decisions here outlive any one app, and most become expensive the moment a second screen depends\non them. They stand apart from building an app on purpose: **every workspace starts with tables\nand many never get an app**, so schema design is not a chapter of app building.\n\nThe rules below share one signature. **Both sides read correctly on their own**, so nothing reports\nthe problem \u2014 no error, no empty column, no failing query. Each is found by looking for it. Then,\nunder **Fields**, what each field type takes.\n\n## One fact, one column\n\n**Read the table\'s existing fields first (`get_table`), and add nothing that stores a fact the table already\nstores.** A value written as text and the same value held as a `link` are one fact in\ntwo columns \u2014 a customer\'s city typed into a text box beside a link to the city record, a status\nword beside the select that decides it, a total beside the formula that computes it.\n\nTwo columns for one fact do not stay equal. Some writer sets only one of them, and nothing reports\nthe divergence: both rows still look correct on their own. A reader that then matches on the text\nhalf treats "Acme" and "Acme Ltd" as different records, so an import creates a duplicate every time\nit runs.\n\n- **Prefer the link, the select, or the formula.** Text is a RENDERING of a record; compose it when\n you read, rather than storing it a second time.\n- **Renaming, retyping or re-pointing the existing field beats adding another.** A field\'s key is\n stable, so a rename breaks nothing that addresses it by key.\n- **Superseding a field means DELETING it**, not leaving it beside its replacement with a\n description that says which one is real.\n- **Empty is not the same as redundant.** A field nothing fills may still be the only home for a\n real distinction \u2014 read what it MEANS before removing it.\n- **A stored field becomes required only once every row holds a value**, so it always holds one: state its `default`,\n which the same write fills into every row holding it empty (a draft takes it when submitted), or fill the empty cells\n first; without either, the write is refused while a row holds it empty. A computed field\'s flag is checked as each row is written.\n Making a field required rebuilds the JSON apps that create its rows, so their creates set it; a workflow its author\n wrote, or a custom-code app\'s, that creates rows of the table without it refuses the change, naming each \u2014 a `default`\n lifts that, as does setting the field in each create; an autonumber, a derived date and a computed field fill\n themselves, and a copied field (`default_from`) fills only when the row sets its link.\n Changing a stage\'s date, the status\'s `default` or the status is refused while a stored create relies on the stamp, naming each workflow.\n\n## One entity, one table \u2014 and the test is measurable\n\nVariation belongs in a column \u2014 a multi-select role, a kind, a stage \u2014 not in a second table. Two\ntables for one kind of thing give the same real-world entity two rows, two ids and two halves of its\nhistory, and each screen shows whichever half it happens to link to.\n\nSplit tables are often right. A supplier book beside a customer book is a normal shape, and merging\non suspicion is a large repoint bought for nothing. So do not argue it in the abstract:\n\n> **List both tables\' names and look for one that appears in both.**\n\nNone means the split is holding. One means it has broken \u2014 the usual cause is a party you begin to\ninvoice as well as buy from \u2014 and the fix is to merge before a second screen depends on the copy.\n\n## One vocabulary wherever values are COPIED between tables\n\nTwo `select` fields for one concept carry different option keys even when their labels match. Copy an option by its\nalias or label: the record tools match an option by alias or label, so a value copied by alias lands\non the option of that alias on the other field. Prefer a link to a shared reference table where the set is open or\ngrowing. Where one side holds more values than the other, the wider side must **refuse** what the narrower one cannot\nexpress rather than quietly picking the nearest value.\n\nA value read through a link or a lookup reads exactly as the same field would on its own row: an option written by its alias in\na body and read as that alias, a member or a link by its id. A value a check matches\nacross tables is a link to one table, or a select whose options state the same aliases: two selects that state no alias in common never compare, and a save that compares them is refused, in a check\'s lookup too. A filter or a write on another table\'s select takes a value read from this one by its alias, else its label.\n\nA lookup reads as one flat list of the values it looks up, in a check and in every body: `first(record.x)` is the one value through a one-row link and `includes(record.x, v)` asks whether any row holds `v`; two selects that state no alias in common never compare. A single member, a single select, a number or a text reads as the value itself, and `first(...)` of one is refused when the body is saved. A rollup that adds up (a sum, a count) over no rows is 0, never empty, as `sum` over an empty list is; a min, a max or an average over no rows is empty.\n\n## A copy boundary accounts for EVERY source field\n\nEach field on the source gets a column on the destination, a deliberate drop with the reason written\ndown, or a refusal.\n\nA field with nowhere to land is data destroyed at the boundary, and it is invisible afterwards: the\ndestination is not empty and not obviously wrong \u2014 just a number that no longer agrees with where it\ncame from.\n\n## Provenance is a LINK, not a flag and not a copy\n\nA row created BY another row carries a link to it.\n\nThat link is what makes "is this the estimate or the actual", "where did this come from" and "have we\nalready imported this" answerable at all. A boolean records that something was true once; a link\nstays true, survives a rename, and lets the next write UPDATE the original instead of adding a second\nrow beside it.\n\n## Say what makes two rows the SAME row\n\nState it as the table\'s `natural_key` (`reference/write-rules`); a text key is also `unique`.\n\nAnything that imports, reconciles or de-duplicates has to decide identity, and with no declared key it falls back to\ncomparing displayed text \u2014 which is how one company arrives three times under three spellings. Name the key: a reference\nnumber, a tax id, a link plus a period. Then match on record ids and option aliases, never on rendered labels.\n\n## A row that belongs to another by its VALUES holds a link\n\nAn adjustment belongs to its person\'s month, a payment to its customer\'s statement: the row holds an ordinary link to\nthat row, set when the row is made \u2014 by the screen that adds it under its parent, or by a table workflow that finds the\nparent from the row\'s values. A rollup through the link then reads live, and the link stays a person\'s to correct.\n\n## A stage\'s moment is a date on the row\n\nWho changed what, and when, is the platform\'s audit trail, which an agent already reads (`query_audit_logs`) under\nits own access to the table \u2014 so it is never a table of yours, and an app shows none of it: a history an app shows is\ntable-backed (`records.status.dates`, `records.status.history`, an event table an act makes).\n\nWhen the business reports, filters or prints the moment a row reached a stage (completed on, cancelled on), that\nmoment is a `date` field of the row, as `completed_at` and `canceled_at` are in SQL. State it as `records.status.dates`\n(`reference/status`): option \u2192 date. The record write path stamps it as a row is made at the option or moved into it,\nwhoever writes, so no one has to remember; a value the same write states wins, which loads past data as it happened. The\nplatform never clears a stamp: each date is when the row last entered the option, and leaving keeps it, and putting a\nchange back restamps nothing. A date range is a span, never a moment, so it is refused. It is the one way a status is\ntimed: a stage\'s `within` runs from its date, a straight-line process is one select whose options are its steps, each\ndated, and the stage is never read off a run of dates.\n\n`records.status.history` is for a business that reports on every move \u2014 moves per person, or time in a stage a row\nre-enters \u2014 and the platform appends one row per move. An event that carries facts of its own (a reason, an amount, a\nsignature, an inspection\'s findings) is its own table with those fields, made by the act that records it.\n\n## Keep derived chains shallow\n\nFormulas and rollups are computed and STORED when a row is written, and one that reads another recomputes with it. A\nrollup over a formula over a formula is paid three times on every touch, and again for every row upstream of it.\n**Depth costs more than row count**: chain depth is yours to keep down, row scanning is the platform\'s. A figure that\nreads itself back through its rows\' links (a task\'s total counting a subtask that lists the task) never settles: the\nwrite that closes the loop is refused, naming the row and the link, and so is a later write reaching it until a link is\nremoved. A figure read through a chain of rows settles up to 256 rows deep in one write.\n\n## Fields\n\nA field is stated inside its table\'s document in a `set_tables` call, keyed by alias. A name people read (a\ntable\'s, a field\'s, an option\'s) is in the owner\'s language; an alias stays English. Every field `type`, the\nkeys each one takes (notation, defaults, options, links, formulas, rollups, lookups, copies) and a worked\nexample are in `docs path="reference/field"`; this page holds the choices around them.\n\n### Types and formats\n\n`type` is one of `text`, `number`, `date`, `boolean`, `select`, `member`,\n`link`, `files`, `formula`, `rollup`, `lookup`, `autonumber`.\n\nA URL, an email, markdown, a checkbox, a datetime, money, a quantity or a percentage is a `format`\nor a `notation` on another type, never a `type`:\n\n| Wanted | Field |\n|---|---|\n| URL or external link | `{ type: "text", format: "link" }` |\n| Email or phone | `{ type: "text" }` |\n| Markdown | `{ type: "text", format: "markdown" }` |\n| Checkbox | `{ type: "boolean" }` |\n| Money | `{ type: "number", notation: { style: "currency", currency: "USD" } }` |\n| Quantity | `{ type: "number", notation: { style: "unit", unit: "kg" } }` |\n| Percentage | `{ type: "number", notation: { style: "unit", unit: "percent" } }` |\n| Datetime | `{ type: "date", format: "datetime" }` |\n| Month (a payroll or billing period) | `{ type: "date", format: "month" }` |\n| Date range | `{ type: "date", format: "date_range" }` |\n| Time of day (a class at 16:00, any day) | `{ type: "text", format: "time" }` |\n\nA unit is written in any of its words, the workspace\'s language included, and stored as its code: `ng\xE0y` and `days` are\n`day`, `gi\u1EDD` is `h`. A time of day is stored `HH:mm`; `min` and `max` bound one by another time field (an end after its\nstart), and a table\'s `no_overlap` spans two of them (`reference/write-rules`).\n### Changing a field\n\nRead the table with `get_table`, which answers its document exactly as `set_tables` takes it, then send `set_tables` with\nthe `table_id` and only what changes. The table is edited by an RFC 7396 merge patch of its document, so what the patch\nleaves alone is left alone and `null` deletes the field it names. Every key a table and a field take is in\n`docs path="reference/tables"` and `reference/field`.\n\nA table is named by its alias wherever a call names one (`table_id`, a link\'s `table`, a lookup, `records.history`), and a new table in the call is named by its `ref`, which becomes its alias. The alias is kept while the table exists, archived or not: asking for one an archived table holds is refused, offering to restore that table or to choose another alias. A filter in a table document (a rollup\'s `filter`, `options_where`, a colour\'s condition, a check\'s lookup) takes the record tools\' operators and values (`is`, `is_any_of`, `gte`, a plain date as a day). An `autonumber` field takes `next` (`"next": 232`): the number its next row gets, refused below the highest already issued.\n\n- **A list is replaced whole**, so an option cannot be nulled. To rename, recolour, add or remove an option, restate the\n field\'s whole `options` list, each option with its alias (`reference/field/select`). A rename changes the label and every\n record keeps its value; an alias left out is removed, which needs `force` while rows hold it.\n- **A number field becomes an `autonumber`** when every row holds its own whole number of 1 or more: the numbers are kept\n and the next row takes the one after the highest (a `next` must be above it). Otherwise the call is refused, saying how\n many rows are blank, repeated or not whole, with up to 5 row ids. No other type converts to or from an autonumber; add\n one as a new field, which numbers the rows already there from 1 (or from `next`) in creation order.\n- **Splitting an option is a rename plus an add.** The old option keeps its alias and takes the first part\'s label, so its\n rows and every app reference to it keep working; the second part is a new option. Rows that belong to the second part\n are then moved by a filtered `update_records`.\n- **A status history holds every option its status ever had** and follows them in the same write: an option added or renamed\n on the status is added or renamed on the history, which a call never restates. Removing an option on the status leaves it\n on the history, because the moves already written hold it. A call that changes nothing of the status\'s options leaves the\n history alone, and options only the history holds stay. Deleting a row deletes its history rows with it, and restoring\n the row restores them; they never hold a delete back.\n- A link names its table by id, or by the `ref` of another table of the same call, and states its `multi`. A two-way link\n states `pair` on one table, as `true` or as a free alias, and the platform makes the partner on the other table with the\n inverse cardinality; a many-to-many link states both sides, since the inverse of many is not decided.\n A link to its own table pairs with itself when `pair` is `true`, and with a second field of that table when `pair` names it\n (a parent and its children).\n A link already holding rows is paired the same way, with its partner stated beside it in the call: the partner is filled from\n the links the rows hold and no cell of the link is rewritten. `pair: null` lets a pair go, both fields staying one-way links\n with their values, and deleting one field of a pair leaves the other a one-way link; a field that holds one row, the partner or the link itself, refuses a pair two rows would crowd, naming the rows.\n The partner may stand on a table the call does not name: `pair: "<alias>"` makes it there, or pairs the one-way link that table\n already holds under that alias, and the answer lists that table among the call\'s. Only someone who manages that table may.\n- A formula\'s `output_type` is inferred from its expression; state it only to override.\n- **A call\'s removals are judged together, on what the call leaves.** A table and the links and lookups naming it, removed in one call, pass; every reader left outside the call is named in one answer, not one per retry. An app reading a field or an option that leaves is rebuilt in the same call, and the answer (a dry run too) lists each node of its tree that changed: a column, a filter, a sort key, a field of a part that only drew the field, a child List the platform composed is dropped when its link leaves, with the part left holding nothing by that and the page the platform composed for its rows; a step the platform composed is dropped when every option it stands at leaves; a filter whose field the rows no longer draw is left out; and an option leaves every list of options it stood in. What has no meaning without it refuses the call, naming the node: an act that sets a removed option, a part or step holding content you stated that is left with nothing, a child List you stated more of whose link leaves, a list that held only the removed option. An app drawing a field that is retyped, or a link pointed at another table, is rebuilt too, its tree unchanged: where the field no longer lets the tree draw what it drew, the call refuses, naming the node, and a field that became a formula, rollup, lookup or autonumber leaves the app\'s allowlist of saves. A workflow body its author wrote is never rewritten: it is checked again against the tables as the call leaves them, and the call refuses, naming the workflow, only if it no longer checks. A table\'s check or workflow that reads a retyped field or a link pointed elsewhere is judged the same way and refuses, naming it, only if it no longer holds. Deleting one field through the table\'s field route drops no node: an app whose tree draws the field refuses it, naming the node.\n- **A field something reads cannot go.** A query, a workflow, a check, an app only its owner can rebuild, or another\n table\'s formula, rollup, lookup or copy that reads the field refuses its deletion, naming the reader. Change or remove\n the reader first, or in the same call.\n- **`force` consents to losing values:** deleting a field rows hold, removing an option rows hold, and a change of type\n or format that does not convert every value (a date made a month cuts a day other than the 1st, a text made a time\n clears a cell holding none). Unforced, the call is refused naming the cells; the API\'s table and field routes take\n `force` in the body and refuse with `error_code` `ConversionNeedsForce`, its `findings` counting the `cells` per field. A formula, lookup or rollup holds what it computes, so it is deleted without it.\n- A field the call makes required with a `default` answers how many rows took it: `defaulted` per field alias on\n `set_tables`, `rows_defaulted` on the API\'s table and field routes.\n- A money formula is proven by its numbers. `query_records` with `aggregate` the affected totals before the change and after, and\n compare. A new field in a formula is tested for the value you want, never for differing from an empty cell, which reads\n `""` and differs from every option.\n- A check\'s expressions are written in the language of `workflows/table-checks`.\n- Views are written with `set_table_views`, not `set_tables`: `views` is keyed by a view\'s id (patch; `null` deletes) or a new key (create), and `order` lists view ids or new keys. `get_table` lists each view\'s id and name and returns the definitions with `views: true`.\n- A refused edit writes nothing and lists everything wrong; `dry_run` is for reading the grants it would make or deciding `force`.\n\nA worked call: add the option `cancelled` to `stage` (the whole list restated), add a check, and consent to losing\nwhat rows hold.\n\n```json5\n{\n "tables": [\n {\n "table_id": "<id of the table>",\n "fields": {\n "stage": {\n "options": [\n { "alias": "draft", "label": "Draft" },\n { "alias": "confirmed", "label": "Confirmed" },\n { "alias": "cancelled", "label": "Cancelled", "color": "red" }\n ]\n }\n },\n "checks": {\n "returns_after_leaves": {\n "on": ["create", "update"],\n "when": "!isNull(record.returns)",\n "fail_when": "record.returns < record.leaves",\n "message": "\\"Return before departure\\"",\n "field": "returns"\n }\n }\n }\n ],\n "force": true,\n "dry_run": true\n}\n```\n\nSplitting `queued` into waiting and underway is one call of the same shape:\n\n```json5\n{ "tables": [{ "table_id": "<id of the table>", "fields": { "stage": { "options": [\n { "alias": "draft", "label": "Draft" },\n { "alias": "queued", "label": "Waiting" },\n { "alias": "underway", "label": "Underway", "color": "green" }\n] } } }] }\n```\n\n`table_id` picks the table patched; `fields` merges by alias, so only `stage` changes; `checks` adds one under its alias\n(`null` removes it); `force` consents to losing values (leave it out unless rows hold a removed option); `dry_run`\nchecks and writes nothing, for reading the grants or deciding `force` before the call that writes.\n';
|
|
1892
1892
|
|
|
1893
1893
|
// docs/filters.md
|
|
1894
1894
|
var filters_default = '# Filters \u2014 choosing records by their fields\n\nOne grammar for every tool that takes a filter: `query_records` (rows and `aggregate`), `update_records`\nand `delete_records` by filter, a view\'s filter, a rollup\'s filter, and the filters a caller passes\nto an app\'s query.\n\n## The shape\n\nA filter is a single condition, or a group of conditions.\n\n```\n{ "node_type": "condition", "field_key": "status", "operator": "has_any_of", "value": ["done"] }\n{ "node_type": "group", "logic": "and" | "or", "children": [ \u2026conditions or groups ] }\n```\n\nGroups nest up to 4 levels. AND(OR(status = A, status = B), age > 40):\n\n```\n{ "node_type": "group", "logic": "and", "children": [\n { "node_type": "group", "logic": "or", "children": [cond1, cond2] },\n cond3\n] }\n```\n\nEvery `field_key` resolves against the table being filtered \u2014 read each table\'s fields (`get_table`)\nand carry no name across tables: sibling tables holding the same concept routinely name it\ndifferently. A field is named by its alias (`"status"`), as `get_table` shows it, and a select option the same way\n(`"done"`); its label or key is taken too, on a select, a formula that yields one or a lookup of one, and a value none of them holds is refused naming the options. A traversal\'s `path` and the field of its condition are named the same way, each on the table the\npath has reached.\n\n## One family of operators\n\nA condition may state these operators; each reads as the type\'s own below. Which field kinds take each:\n\n| Operators | Field kinds | Meaning |\n|---|---|---|\n| `is`, `is_not` | a field holding one value: text, number, date, yes/no (`is` only, or `is_not` with a yes/no value), a select or member that is not multi, a link of cardinality one | equal to one value; on a select, member or link, to the one option, member or record |\n| `is_any_of`, `is_none_of` | text, number, date, select, member, link | equal to any of a list; on a select, member or link, `has_any_of` and `has_none_of` |\n| `lt`, `lte`, `gt`, `gte` | number, date | below, at most, above, at least |\n| `is_empty`, `is_not_empty` | every kind but yes/no | no value, or one |\n\n`is` and `is_not` on a field that holds several options, members or records (a multi select, a many-link) are refused:\nstate `has_any_of`, `has_none_of` or `has_all_of`, which say whether the row must hold exactly them or just some.\nA date is `"2026-10-15"` for that whole day, whatever time a value holds. An `is_any_of` or `is_none_of` on a number\nor a date, and an `is_not` on a date, stand for a group of conditions, which a traversal\'s single condition cannot hold;\na list that a workflow computes is expanded when the step runs, so a saved workflow states it as it states any list.\nThe depth a filter may nest is the depth you write: the groups an operator stands for do not count.\n\n```\n{ "node_type": "condition", "field_key": "due", "operator": "gte", "value": "2026-10-01" }\n{ "node_type": "condition", "field_key": "status", "operator": "is_any_of", "value": ["done", "shipped"] }\n```\n\n## Text\n\n| Operators | Value |\n|---|---|\n| `equals`, `not_equals` | a string \u2014 ignores case, keeps accents |\n| `contains`, `does_not_contain`, `starts_with`, `ends_with` | a string \u2014 ignore case, keep accents |\n| `is_any_of`, `is_none_of` | a string array \u2014 ignore case, keep accents |\n| `contains_any_of` | a string array \u2014 the cell contains any of them, ignoring case, keeping accents |\n| `is_empty`, `is_not_empty` | none |\n\n```\n{ "node_type": "condition", "field_key": "title", "operator": "is_any_of", "value": ["hello", "world"] }\n```\n\n`contains "c\xE1"` finds `C\xE1 h\u1ED3i`, not `C\xE0 chua`. Keeping accents reads `h\xF2a` and `ho\xE0` as one spelling. A condition with `ignore_accents: true` makes `contains`, `does_not_contain`, `starts_with`, `ends_with`, `contains_any_of` ignore accents too: `ca` and `c\xE1` find both, and so on a record link\'s `contains`, `not_contains`, `starts_with` and `ends_with`. Any other operator refuses it. A condition with `whole_words: true` makes `contains` and `contains_any_of` on text, and `contains` on a record link (which reads each linked row\'s name), match a term only as a whole token: the character before and after the match is the edge of the text or an ASCII character that is no letter or digit (`2025SGSIN-1` is not in `2025SGSIN-12`; `\u01A1ng` is not in `D\u01B0\u01A1ng`, and a non-ASCII character never ends a token). Any other operator refuses it. A text value is a string, never an array; `is_any_of` matches several. Its array has no length cap \u2014\npass the whole list in one condition rather than splitting it across calls.\n\n## Number\n\n| Operators | Value |\n|---|---|\n| `equals`, `not_equals`, `greater_than`, `less_than`, `greater_than_or_equal_to`, `less_than_or_equal_to` | a number |\n| `is_empty`, `is_not_empty` | none |\n\nA number whose `notation` reads its unit or currency on each row (`{ "per_row": <select> }`) is\nread in each row\'s own, so a comparison on it states `unit_option`: the option of that select its\nvalue is in.\nRows holding another option are out; measured units of one dimension convert.\n\n```\n{ "node_type": "condition", "field_key": "amount", "operator": "greater_than", "value": 100, "unit_option": "USD" }\n```\n\n## Boolean\n\n`equals` with `true` or `false`.\n\n## Select\n\n| Operators | Value |\n|---|---|\n| `has_any_of` (any of them \u2014 "A or B"), `has_none_of`, `has_all_of` (a multi-select only) | an ARRAY of option aliases, even for one |\n| `is_empty`, `is_not_empty` | none |\n\n```\n{ "node_type": "condition", "field_key": "status", "operator": "has_any_of", "value": ["done", "in_progress"] }\n```\n\n## Member\n\n| Operators | Value |\n|---|---|\n| `has_any_of`, `has_none_of`, `has_all_of` | an array of member ids |\n| `is_current_member`, `is_not_current_member`, `is_empty`, `is_not_empty` | none |\n\n## Date\n\n| Operators | Value |\n|---|---|\n| `before`, `after`, `on_or_before`, `on_or_after`, `on`, `starts_before`, `starts_after`, `ends_before`, `ends_after` | a point |\n| `between`, `overlaps`, `contains`, `within` | `{ start: point \\| null, end: point \\| null }` |\n| `time_of_day` | `{ start_time: "HH:mm" \\| null, end_time: "HH:mm" \\| null }` |\n| `duration_equals`, `duration_greater_than`, `duration_less_than` | `{ amount, unit: "minutes" \\| "hours" \\| "days" }` |\n| `is_empty`, `is_not_empty` | none |\n\nA date value is a point. A bare `"YYYY-MM-DD"` is the point of that whole day (`"YYYY-MM-DDTHH:mm"` of that minute),\nand a stated date is compared as written, with no timezone shift: `on "2026-10-15"` matches every value from 00:00 to\n23:59 of that day, on a date or a datetime field. `before` the day is earlier than its start, `after` later than its end,\n`on_or_before` and `on_or_after` include it. A relative or period point counts today in the field\'s timezone. The\nobjects below say the same, and add a time, an offset or a period:\n\n```\n{ "type": "exact", "date": "2025-03-14", "time": "09:00" } time optional\n{ "type": "relative", "offset": -7, "unit": "minutes" | "hours" | "days" | "weeks" | "months" | "years" }\n{ "type": "period", "period": "day" | "week" | "month" | "quarter" | "year", "boundary": "start" | "end", "offset": 0 }\n```\n\n## Link\n\n| Operators | Value |\n|---|---|\n| `has_any_of` (linked to any \u2014 filters by record identity), `has_none_of`, `has_all_of` (a multi-link only) | an array of record ids (`rec_\u2026`) |\n| `contains`, `not_contains`, `starts_with`, `ends_with` \u2014 deprecated: the text a link stores changes with every rename; filter by record, and by a linked record\'s field through a lookup of it | a string, matched against the linked record\'s display text |\n| `is_empty`, `is_not_empty` | none |\n\n```\n{ "node_type": "condition", "field_key": "customer", "operator": "has_any_of", "value": ["rec_abc123"] }\n```\n\n## Through a link\n\nA traversal chooses records by a field of the records they link to. `path` lists link fields, each of the table\nbefore it (up to 3), and `condition` names a field of the last table reached:\n\n```\n{ "node_type": "traversal", "path": ["customer"], "condition": { "field_key": "tier", "operator": "has_any_of", "value": ["gold"] } }\n```\n\n## Sort\n\nA view\'s sort is a list, applied in order: `[{ "field_key": "due", "order": "asc" | "desc" }]`.\n\n## Counting, aggregating and reading by id\n\n`query_records` takes `filters` in one table and answers rows, or, with `aggregate`, statistics over them: `count`, or an\noperation by the field\'s type, optionally broken down by `group_by`. Records are read one table at a time. A question over\nseveral tables is one number from `tables`, a list of entries that each state their own `table_id` and filter, since each\ntable spells its fields its own way; it combines with no top-level `table_id`, `view_id`, `search` or `filters`.\n\n- **Values held in another table.** A filter value (a customer\'s name, a code) is not looked up for you. Find where it\n lives with `get_workspace` and `search`, which names the tables and docs that hold the words, then state it in that\n table\'s own filter. When `is_any_of` on a text field names values, the answer lists the ones no row of the table\n matched, so a total that misses part of what you asked for says so; pass `tables` to count them across the tables\n that hold them.\n- **By id.** `record_ids` reads those records, deleted ones included, with their `display`, `links`, `archived_at`,\n `created_at` and `updated_at`; `table_id` may be left out. It takes at most 200 ids on every origin (an agent, a workflow\n step, an app) and combines with `field_keys` and `comments` only. A long cell reads cut; `field_keys` names the cells\n read whole. `update_records` takes up to 1,000 ids, and with\n `restore: true` brings deleted records back.\n';
|
package/docs/data_model.md
CHANGED
|
@@ -188,7 +188,7 @@ A table is named by its alias wherever a call names one (`table_id`, a link's `t
|
|
|
188
188
|
(a parent and its children).
|
|
189
189
|
A link already holding rows is paired the same way, with its partner stated beside it in the call: the partner is filled from
|
|
190
190
|
the links the rows hold and no cell of the link is rewritten. `pair: null` lets a pair go, both fields staying one-way links
|
|
191
|
-
with their values; a field that holds one row, the partner or the link itself, refuses a pair two rows would crowd, naming the rows.
|
|
191
|
+
with their values, and deleting one field of a pair leaves the other a one-way link; a field that holds one row, the partner or the link itself, refuses a pair two rows would crowd, naming the rows.
|
|
192
192
|
The partner may stand on a table the call does not name: `pair: "<alias>"` makes it there, or pairs the one-way link that table
|
|
193
193
|
already holds under that alias, and the answer lists that table among the call's. Only someone who manages that table may.
|
|
194
194
|
- A formula's `output_type` is inferred from its expression; state it only to override.
|
package/docs/design.md
CHANGED
|
@@ -418,6 +418,8 @@ admin edits the table. What a `workflow` or a paper did stands, so a way back th
|
|
|
418
418
|
|
|
419
419
|
#### Stages
|
|
420
420
|
|
|
421
|
+
Work the owner named no decider for has no status: the row saved is the fact (a goods receipt nobody approves moves
|
|
422
|
+
stock as it is saved), and a stage, its owner or an approval enters with the person the owner said decides.
|
|
421
423
|
Name each job's work plan by its shape: a status a person sets; a pipeline, where who holds the row and for how long
|
|
422
424
|
matter; or tasks, where only how many are done counts (`records.task`). A pipeline states each stage once in
|
|
423
425
|
`records.status.stages` — its `owner` (a member field, a link's member field, or `{ "group": <id> }`, a member group) and its target
|