@lotics/cli 0.321.126 → 0.321.127
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 +2 -2
- package/docs/build.md +1 -1
- package/package.json +1 -1
package/dist/src/cli.js
CHANGED
|
@@ -1891,7 +1891,7 @@ async function saveAnswerFile(result, dir, timeoutMs) {
|
|
|
1891
1891
|
}
|
|
1892
1892
|
|
|
1893
1893
|
// src/version.ts
|
|
1894
|
-
var VERSION = "0.321.
|
|
1894
|
+
var VERSION = "0.321.127";
|
|
1895
1895
|
|
|
1896
1896
|
// src/cli_dispatch.ts
|
|
1897
1897
|
import { spawn as spawn2 } from "node:child_process";
|
|
@@ -1900,7 +1900,7 @@ import { spawn as spawn2 } from "node:child_process";
|
|
|
1900
1900
|
var getting_started_default = '# Getting started\n\nA workspace is where one business keeps what it knows and does its daily work. **Records** are what it tracks, one table per kind of thing and one row per entry. **Apps** are the screens a team works in, one per main kind of record, each given to everyone who works its rows. **Documents** are the quotes, invoices and slips it sends, each a template filled from a record, or from the many rows of a period or a statement. A paper is the workspace\'s once it is made from a template or uploaded and filed on its record; a file left on the host\'s own disk, the user\'s included, reaches no one in the workspace. A procedure or policy no table holds is a **knowledge doc**; a price list, a customer list or the open orders are rows.\n\nOpen the one page for the job. Pages are read with the `docs` tool (`docs path="design"`; `lotics docs design` on the CLI).\n\n- **Build a workspace, or add an app:** `docs path="build"`. A bakery built call by call: tables with a check, the paper, the app, what the owner will ask an agent, the owner\'s rows, then pressing it.\n- **Which apps a business needs, and who gets each:** `docs path="app_architecture"`.\n- **Judge what you built:** `docs path="design/the-rubric"`. Each question answered by a call.\n- **Change an app:** `docs path="reference/changing-an-app"`. `get_app`, then `set_app` with `nodes` and `base_version_id`. A table is changed with `get_table`, then `set_tables` with its `table_id` (`data_model`).\n- **Enforce a rule on a table:** `docs path="workflows/table-checks"`. A condition no create, update or delete may meet, whoever makes it, and its language.\n- **Make a document:** `docs path="document_templates"`. A template, its slots and loops, and the act that files it on a record.\n- **Enter data, count, answer a question:** `docs path="working_in_a_workspace"`. The right tool for each job; the value each field takes is `field_values`, choosing rows is `filters`.\n- **Rows owed on a weekly pattern (a diary every weekday, a class every Tuesday):** `docs path="reference/cadence"` for a table\'s `records.cadence`; the Act that `makes` them is `reference/act-node`.\n- **Rows an act proposes for a person to tick (a statement matched to the notes it pays):** the workflow body is `docs path="workflows/a-reviewed-act"`, calling the act is `agent_surface/a-reviewed-act`.\n- **Reach a connected service, or do what a button cannot:** `docs path="workflows"`. Triggers, steps and expressions; each service step is in `workflow_steps`.\n- **Who can reach what, or why something was refused:** `docs path="permissions"`.\n\nHow each record is drawn is `design`; a key\'s page in `reference` is read when a write or refusal names it; each screen in a complete workspace is `examples`.\n';
|
|
1901
1901
|
|
|
1902
1902
|
// docs/build.md
|
|
1903
|
-
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; sending an earlier tree restores the app, never a table or a row a write made, so try a write on a throwaway row. What no one could guess from the data goes into a knowledge doc with `set_knowledge` (`knowledge_docs`).\n\nBefore the first table, `set_workspace` states the business\'s `timezone` (how every date buckets and what "today" is), `default_currency` (what an amount with no stated currency means) and `organization_language` (the language its papers, invitations and members default to, `vi` until set): every row and paper made after reads them.\n\n## 0. The day\'s work\n\nBefore the first table, ask the person who asked for the papers and lists the business keeps, as the files themselves (its sheets, forms, slips), unless they are attached or the person said to go ahead without them: they name the day\'s work and hold rules no assumption reaches. Then name the jobs done most often and first in the day, the ones the request names and the rest a business of its kind does daily (what comes in, what goes out, what is counted or billed), and the exceptions each meets (the common ones: going back a step, correcting a locked record, work in parts or split, data late or out of order, a cancel, closing only once the work before is done; build those this work meets, not the list). Build every one of those jobs first, each from the screen it starts on, from the papers and, where they are silent, from how this kind of business runs; name each assumption in your report for the owner to change. Who does a job matters where the work says so: a step another person approves, data not everyone may see, and who each app is given to (`get_workspace` kind `member` lists the organization\'s people, not who does what here). Whether to ask more than the papers is your call; two questions usually settle the rest: what work happens most often, and what must never go wrong.\n\n## 1. Tables and their checks: `set_tables`\n\nLinked tables go in one call, since they name each other by `ref`, which becomes the table\'s alias; `records` and checks may follow in the next call, so a refusal costs a patch. One table per kind of thing, one column per fact, a link wherever one record points at another (`data_model`). A view can ask a shape of the rows (a floor plan: the places as rows of their own; a roster: one row per person per day; lanes: the day or the hours on the row), so choose each job\'s view in `design/treatments` before its tables. 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": "\\"Pay by the pickup day, \\" + formatDate(record.due_on)"},\n "baking_has_a_pickup_day": {"on": ["create", "update"], "field": "due_on",\n "fail_when": "record.stage != \\"taken\\" && isNull(record.due_on)",\n "message": "\\"A cake past Taken has its 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, where an Act\'s `when` and `requires` hold only its own press: what a stage needs is a check (`baking_has_a_pickup_day`); a check\'s language is `workflows/table-checks`, an effect after a write a table workflow (`workflows/table-workflows`). A check\'s `message` is an expression, so fixed text is a quoted string. A check refuses the write, a table workflow\'s too, so it states what must never happen in this kind of business, said or not (paid above the invoice, stock below zero); a fact going out of line (stock short of what lines take, totals that do not match) is an issue the row keeps (`design/issues`).\n\nA `date` field is a day, a moment with `"format": "datetime"` or a month (a period) with `"format": "month"`; 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. A paper the owner hands over as a Word or Excel file becomes a template of that type; an html template is for a paper with no file of its own, and prints to the sheet\'s edge unless it states `@page { margin }`.\n\n```\nset_template {"type": "html", "name": "Order slip",\n "template": "<style>@page { margin: 15mm }</style><h1>{{organization.name}}</h1><h2>{{reference}}</h2><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, and `{{organization.name}}` prints the business\'s name, never passed; the cakes loop under their link\'s name (`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. State only the difference.\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"}, "due_on", "pay_by", "slip",\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 {"type": "Act", "key": "collect", "label": "Collected", "when": {"stage": ["ready"], "paid": true}, "set": {"stage": "collected"}}\n ]}\n ]\n }\n}\n```\n\n**A status the work walks in order states `Steps`.** Bare where no stage has a form, it draws as the line of steps (the counter\'s); a state a row moves between (active, paused, ended) states none (`design`, Stages). Where a stage has its own form, `Steps` replaces the page\'s fields and Lists, a Section per stage that has its own form or list, the Acts beside it; an Act asking a value or filing a paper needs no Section:\n\n```json\n{"type": "Steps", "children": [\n {"type": "Section", "at": ["taken"], "children": ["due_on", "pay_by", {"type": "List", "entity": "cake_line", "create": ["item", "quantity"]}]},\n {"type": "Section", "at": ["ready"], "children": ["slip"]}\n]}\n```\n\n**Give each main List a band** of what its person watches, a figure or a chart in its `children`; a count is already the summary line\'s.\n\n**A press can be a mistake.** An Act also moves a row back (`when` the later stage, `set` the earlier), standing beside the Act that moves it on. A close whose work can be left unfinished waits on it (`when`, a Check), and work that can be abandoned (a cancelled order) closes at an option `dropped` names. **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\nA refused write writes nothing and lists every finding of the step it reached, the tree\'s form before the rest; the body it judged, and a dry run\'s, is held for an hour under the `held_id` the answer states, so send only what changes: `held_id` with `body` and `nodes` (`tables` for `set_tables`, `edits` for `set_workflow`) merges into the held call, so a key left out stays and `null` removes it; `held_id` alone writes it as held, with the `force` it was judged under. `dry_run` answers what a change to an app in use would grant and take away. Then share each app (`app_architecture`). An Act\'s or stage\'s `owner` decides who presses.\n\n## 4. What the owner\'s assistant may read and do: Query and Workflow nodes\n\nWhat the owner\'s agent is asked and no screen draws is a Query or Workflow node beside the Lists (`agent_surface/declaring-more`). A node\'s `description` is written for an agent that has not seen the screen (orders waiting for pickup). 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`). Only a List or Record of a table draws it; a table its Query or Workflow nodes only read is named in the App\'s `uses`, never drawn.\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`). Leave some rows in before handing over: the owner\'s own where they gave them, and a few example rows where a list or a board would otherwise stand empty (the coming rows of anything that recurs among them), written like the owner\'s own at the stages the work passes through. An example never changes an owner\'s row (its stage, its stock, what it holds) nor takes a number the business\'s papers are numbered by. They show you and the owner each screen with something on it. Say in the handover which rows are examples and that you will clear them whenever the owner asks; the owner\'s rows for one table leave another\'s examples standing.\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 owner\'s stage for it. Every Act runs as `act_<key>`, the one name, handed what it asks. A dry run walks the moves and files nothing; then press for real each paper Act you may press, 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. A press is made by the member who makes it, so an Act another member owns is proved by a dry run as that member (`as_member`), which renders its paper and keeps the file; an example row at a later step is created there with that file in its files field, and the owner\'s rows move only by their Acts. Prove a rule by sending the write with `dry_run: true`; never switch a check off. Only an admin passes `as_member`. 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 leave standing instructions there (`instructions`, one entry per rule, keyed by the job it serves): who the business is, its people\'s words, and what the rows cannot tell an agent (the day its records begin). 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; only what no daily job needs is named as not built.\n';
|
|
1903
|
+
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; sending an earlier tree restores the app, never a table or a row a write made, so try a write on a throwaway row. What no one could guess from the data goes into a knowledge doc with `set_knowledge` (`knowledge_docs`).\n\nBefore the first table, `set_workspace` states the business\'s `timezone` (how every date buckets and what "today" is), `default_currency` (what an amount with no stated currency means) and `organization_language` (the language its papers, invitations and members default to, `vi` until set): every row and paper made after reads them.\n\n## 0. The day\'s work\n\nName the jobs done most often and first in the day, the ones the request names and the rest a business of its kind does daily (what comes in, what goes out, what is counted or billed), and the exceptions each meets (the common ones: going back a step, correcting a locked record, work in parts or split, data late or out of order, a cancel, closing only once the work before is done; build those this work meets, not the list). Build those jobs first, each from the screen it starts on, from what you have and, where it is silent, from how this kind of business runs; name each assumption in your report for the owner to change. Who does a job matters where the work says so: a step another person approves, data not everyone may see, and who each app is given to (`get_workspace` kind `member` lists the organization\'s people, not who does what here). Whether to ask the person who asked is your call; three questions usually settle a workspace: what work happens most often, the papers and lists the business keeps (attached as files), and what must never go wrong.\n\n## 1. Tables and their checks: `set_tables`\n\nLinked tables go in one call, since they name each other by `ref`, which becomes the table\'s alias; `records` and checks may follow in the next call, so a refusal costs a patch. One table per kind of thing, one column per fact, a link wherever one record points at another (`data_model`). A view can ask a shape of the rows (a floor plan: the places as rows of their own; a roster: one row per person per day; lanes: the day or the hours on the row), so choose each job\'s view in `design/treatments` before its tables. 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": "\\"Pay by the pickup day, \\" + formatDate(record.due_on)"},\n "baking_has_a_pickup_day": {"on": ["create", "update"], "field": "due_on",\n "fail_when": "record.stage != \\"taken\\" && isNull(record.due_on)",\n "message": "\\"A cake past Taken has its 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, where an Act\'s `when` and `requires` hold only its own press: what a stage needs is a check (`baking_has_a_pickup_day`); a check\'s language is `workflows/table-checks`, an effect after a write a table workflow (`workflows/table-workflows`). A check\'s `message` is an expression, so fixed text is a quoted string. A check refuses the write, a table workflow\'s too, so it states what must never happen in this kind of business, said or not (paid above the invoice, stock below zero); a fact going out of line (stock short of what lines take, totals that do not match) is an issue the row keeps (`design/issues`).\n\nA `date` field is a day, a moment with `"format": "datetime"` or a month (a period) with `"format": "month"`; 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. A paper the owner hands over as a Word or Excel file becomes a template of that type; an html template is for a paper with no file of its own, and prints to the sheet\'s edge unless it states `@page { margin }`.\n\n```\nset_template {"type": "html", "name": "Order slip",\n "template": "<style>@page { margin: 15mm }</style><h1>{{organization.name}}</h1><h2>{{reference}}</h2><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, and `{{organization.name}}` prints the business\'s name, never passed; the cakes loop under their link\'s name (`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. State only the difference.\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"}, "due_on", "pay_by", "slip",\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 {"type": "Act", "key": "collect", "label": "Collected", "when": {"stage": ["ready"], "paid": true}, "set": {"stage": "collected"}}\n ]}\n ]\n }\n}\n```\n\n**A status the work walks in order states `Steps`.** Bare where no stage has a form, it draws as the line of steps (the counter\'s); a state a row moves between (active, paused, ended) states none (`design`, Stages). Where a stage has its own form, `Steps` replaces the page\'s fields and Lists, a Section per stage that has its own form or list, the Acts beside it; an Act asking a value or filing a paper needs no Section:\n\n```json\n{"type": "Steps", "children": [\n {"type": "Section", "at": ["taken"], "children": ["due_on", "pay_by", {"type": "List", "entity": "cake_line", "create": ["item", "quantity"]}]},\n {"type": "Section", "at": ["ready"], "children": ["slip"]}\n]}\n```\n\n**Give each main List a band** of what its person watches, a figure or a chart in its `children`; a count is already the summary line\'s.\n\n**A press can be a mistake.** An Act also moves a row back (`when` the later stage, `set` the earlier), standing beside the Act that moves it on. A close whose work can be left unfinished waits on it (`when`, a Check), and work that can be abandoned (a cancelled order) closes at an option `dropped` names. **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\nA refused write writes nothing and lists every finding of the step it reached, the tree\'s form before the rest; the body it judged, and a dry run\'s, is held for an hour under the `held_id` the answer states, so send only what changes: `held_id` with `body` and `nodes` (`tables` for `set_tables`, `edits` for `set_workflow`) merges into the held call, so a key left out stays and `null` removes it; `held_id` alone writes it as held, with the `force` it was judged under. `dry_run` answers what a change to an app in use would grant and take away. Then share each app (`app_architecture`). An Act\'s or stage\'s `owner` decides who presses.\n\n## 4. What the owner\'s assistant may read and do: Query and Workflow nodes\n\nWhat the owner\'s agent is asked and no screen draws is a Query or Workflow node beside the Lists (`agent_surface/declaring-more`). A node\'s `description` is written for an agent that has not seen the screen (orders waiting for pickup). 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`). Only a List or Record of a table draws it; a table its Query or Workflow nodes only read is named in the App\'s `uses`, never drawn.\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`). Leave some rows in before handing over: the owner\'s own where they gave them, and a few example rows where a list or a board would otherwise stand empty (the coming rows of anything that recurs among them), written like the owner\'s own at the stages the work passes through. An example never changes an owner\'s row (its stage, its stock, what it holds) nor takes a number the business\'s papers are numbered by. They show you and the owner each screen with something on it. Say in the handover which rows are examples and that you will clear them whenever the owner asks; the owner\'s rows for one table leave another\'s examples standing.\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 owner\'s stage for it. Every Act runs as `act_<key>`, the one name, handed what it asks. A dry run walks the moves and files nothing; then press for real each paper Act you may press, 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. A press is made by the member who makes it, so an Act another member owns is proved by a dry run as that member (`as_member`), which renders its paper and keeps the file; an example row at a later step is created there with that file in its files field, and the owner\'s rows move only by their Acts. Prove a rule by sending the write with `dry_run: true`; never switch a check off. Only an admin passes `as_member`. 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 leave standing instructions there (`instructions`, one entry per rule, keyed by the job it serves): who the business is, its people\'s words, and what the rows cannot tell an agent (the day its records begin). 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; only what no daily job needs is named as not built.\n';
|
|
1904
1904
|
|
|
1905
1905
|
// docs/design.md
|
|
1906
1906
|
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 table\'s `records` states of a row is its face, and every app that links to the table reads it. 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 stage, deadline and figure it draws unasked (a Record\'s `row` leaves one out), 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`) continues from the highest issued, or from the field\'s `next`\n where its numbers are already past that; as the title it yields 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, or a link to a row of its own whose title is that record): 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, a record\'s child List in the order its rows were added.\n- Someone is a face wherever read: a link to a table stating `records.party` draws its row\'s face, as a member\n field does; select options naming people or organisations who are neither each take the `mark`\n `{"kind": "avatar", "name": "person"}`, not a colour dot, so a person reads as a person.\n- Each record is whole within its app: its page holds what the record is (its facts and its papers) and its child\n rows, in parts a person moves between, so someone arriving at it understands it without guessing. Rows of another\n app\'s job read in place as read-only lines \u2014 their name and figures \u2014 and the app states no page for an entity\n another app works. A register opens on its rows with the figures its job reads; a filter leaving one hides that the rest exist.\n Completeness is of the work, never of decoration: a part, column or Reading nobody\'s work reads stays out.\n- A thing shows its picture, a file its preview, planned work its days on a time axis, things kept at places the floor they stand on (a plan), a quantity a meter (`records.limits`) or\n a chart, a register its Readings; long text reads whole (a markdown Field; `block: true` on plain long text).\n- A number a reader judges \u2014 against a target or a bound, over time, as a mix of parts, through steps \u2014 is drawn as a\n picture wherever it stands: a list\'s columns, a record, a card, a band. A Reading stands in each of those places, and\n which picture each shape of Reading draws is `reference/reading-node`.\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`, apart from the workspace\'s other apps.\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, since the counterparty\'s ledger alone hides it from the order.\n\n<!-- generated:start words -->\n\n**The words most builds state.** A node\'s page holds 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- `tells` (map of alias \u2192 (`true` | `"field"` | `"link.field"` | `{ "group": id }`)): Members find out in their inbox that a deadline of `due` is three days off and again when it has passed, one card per member counting its rows\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\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 | Reading)): Fields read after the row\'s title, in this order, each drawn though no row holds it, and one the `records` line also names leaves that line\n- `label` (text): The register\'s name in the app\'s lists and tab strip\n- `filters` (list of (alias | Tiered filter | Listed filter)): Fields the reader narrows by every day, beside the stage chips\n- `children` (list of (Tab | Reading | Act | List) (at least one)): Its Tabs, band Readings 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 | Tab in a Record | Statement | Comments | Act | Check) (at least one)): Parts (Section, Side, and one Steps, bare or holding the Sections that are its path), and the Fields, Fieldsets, Lists, Readings, Statements and Comments stated 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 (absent, the rows are counted), 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\nA row takes what the person has, in the order it arrives \u2014 a supplier\'s paper after the delivery, a payment before its\ninvoice, a price filled in later. What is missing or out of order is by default an issue on the row, not a refusal;\nrefusal is kept for what must never happen and for the step that cannot be taken without a fact, which names it (an\ninvoice made without the buyer\'s tax code).\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: 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 deadline in `records.due` already marks its row late and is counted; no issue, Check or Reading says it again. 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\n\nAn issue is a promise that someone will act every time it stands.\nDeclare an issue where each flagged case needs someone to act, since a rule that flags rows nobody fixes trains everyone\nto ignore the colour; name those you assumed in the handover. 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. A warning an\n Act\'s `confirm` shows stands before the press: an issue that holds only at the stage the press lands on says nothing there.\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()` (expiring within 30 days) is judged again nightly.\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- Read-only in this app is a Check refusing `"update"` (paid in full), in no `records.issues`; a lock on every door is\n a row\'s `locked`, set by `update_records`: a locked row is corrected by a change stated with a reason (`request_change`) that a table manager approves, or the table\'s `locked_change: "tell"` writes at once.\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, a page\'s `press` naming up to three controls pressed first (an act\'s form, a list\'s add form, a row\'s menu; the page drawn can write nothing) \u2014 at a desk\'s width and a phone\'s, naming the columns a table left off at each width, and under `Measured on this picture:` what a measurement of the shot found: the words a box cuts (px across, lines below), a page wider than its screen;\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, each under the heading of its kind: `Stated, and drawn differently:` (what the tree states that the app leaves out, moves, draws once or that changes nothing), `Suggestions:` (what the tree does not state) and `About this write:`. A note of the first two kinds is said by the write that earns it and counted on the next; `get_app` lists those that stand. 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 done most often, and each their kind of business cannot run without: from the screen it starts on, which press does it? Find each on a `screenshot_app` shot, as a member who does it where access differs (`as_member`); one who cannot open the app is first invited (`set_members`) and given it (`set_access`).\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`)?\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 exporting List\'s workbook made, those this kind of business sends unasked too, with no blank? Press each paper Act and read its file; prove a List\'s `export: true` with `run_app_query` and `export`.\n7. Can each row be recorded with what the person has now, its gap an issue, while only the step that needs the fact refuses? 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`).\n8. Does each daily job survive its exceptions (a step back, a locked record corrected, work in parts, late data, a cancel, a close before its work is done)? Prove each write with a `dry_run`.\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, one diary of everyone\'s bookings | 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| Each person or room booked by the hour, where who is free matters | List `layout: {"lanes": {"by": \u2026}}` by that person or room, 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 Section whose work they end; 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| Jobs that run over several days, each with a start and an end date | List `layout: {"lanes": {"by": \u2026}}` by who or what does them, or `layout: {"gantt": {"start": \u2026}}` where the jobs follow each other | `reference/lanes`, `reference/gantt` |\n| Kept at a place: pallets, stock on shelves or in bins, anything found by its location on a floor or a map | List `layout: {"plan": \u2026}` draws the floor, flat or in 3D, each thing where it stands; the places are rows of their own stating `plan_place`, so the tables follow this choice | `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), or work owed every so many days, months or years (a machine\'s service every 6 months, an insurance every year) | `records.cadence: [{"entity": \u2026, "on": "<a multi-select of mon\u2013sun>", "start": \u2026, "end": \u2026, "planned": \u2026, "except": \u2026}]`, or `{"entity": \u2026, "every": {"months": 6}, "from": "<a date of the row>", "planned": \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: one row per person per day (a rota, attendance) | List `layout: "roster"` over the people, with the List of those rows inside | `reference/roster` |\n| Hours per person per day (a timesheet), a daily count, a meter reading | a roster whose cells List states one `{ field, edit: true }` number: each day is a box the number is typed in, a row\'s total beside its name and a day\'s total in a foot | `reference/roster` |\n| Values typed down a list (prices, counts) | a List\'s column `{ field, edit: true }`: each row\'s value is its own cell, saved as that one field when typed; a press on the row still opens it, and on a phone the line reads the value, edited on the record | `reference/edit-column` |\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 it pays for its run | 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 leads with its picture, and where no row in view holds one no row keeps a place for it \u2014 a record\'s own page keeps it, where a person adds the photo; 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. 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` a deadline, never the day a row is held on; an end that is a promise (a loan\'s return day) is a `due`, since only a stated deadline is marked late. A `no_overlap` by a person or a value alone keeps one row at\na time each, read by what they hold.\n\nWhere a resource has several units (40 scaffold boards), a booking states how many it takes\n(`quantity`, a number of the row) and the item states how many there are (`limit`, `"item.stock"`, a number of the one\nrow the `by` link names): a booking that would take more than are free on any day is refused, saying how many are free.\nWhat counts is the most held at one moment, so hires of 10 on days 1\u20132 and\n10 on days 8\u20139 leave 20 boards free for a hire of 5 over days 1\u201310. A row with no quantity holds nothing, an item with no\nstock bounds nothing, a stock that does not compute refuses the booking, and lowering the stock below what is held from\ntoday on is refused. A booking holds the days it states while it stands at a state `while` names. Rows\ncompete by a field holding one value each; by a link, they draw as lanes `by` it, each head saying what is free. An end may be a formula of the row (an\nappointment\'s start plus its length), never one that reads the clock.\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, and where it states a `quantity` or a `limit` the lane\'s head says how much is free on the day in view ("3 of 6 free"), the count a booking is refused by, whatever the view filters hide. 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; a link the table requires puts every row in a lane as it is made, so only rows with no day reach the 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.\nWorked: `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`). Work owed every so many days, months or years (a service, a renewal) is a cadence `every` from the day it starts (`from`, a date of the row, never today): it counts from that day each time, so a late service never moves the next one, and the Act that makes rows lists what is owed in the next twelve weeks; a yearly one beyond them shows "next on" its date on the row\'s line. Where the schedule should count from the day the work was done instead, the Act that records it `set`s `from` to that day. 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. A team\'s discussion on a record is a `Comments` node (`reference/comments-node`). 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 by default that\nAct\'s `asks`, since a field to remember is left empty. 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); work done in parts (two deliveries, part payments) is a child row each, the parent moving on when they add up. An Act also moves a row back (`when` the later\nstage, `set` the earlier), and without one a row moved on by mistake stays until an admin edits the table. What a\n`workflow` or a paper did stands, so a way back there is a correction of its own.\n\n#### Buttons\n\nPeople mostly work through agents, so an app draws few buttons. Where no Act of a record\'s page states `button: true` or `false`, the Act\nyou state that moves the row to the next stage of its status draws as the page\'s button (a move the platform drafted stays in the status\'s own control), a move that\ncloses the record only when stated and no stage of the work follows it (a cancel listed after it is none); every other Act waits in the header\'s \u22EF. `button: true` on each step a person does at that screen (a count received, a signed\npaper, an approval), `button: false` on one only agents run (an invoice made from delivered orders, a payment matched\nfrom a statement): once an Act of the page states `true` or `false`, the page draws exactly what is stated. A page leads with the move to its next stage; where a step that moves no stage is due first (opening a register before closing it), state `button: "lead"` on it (the first, where two do); the move to the next stage stays beside it. A move into the last stage states the condition it is due on (`when` or a Check) where the work before it can be unfinished. A drawer draws its\nsteps whatever `button` says. Rows never draw a button: every row act waits in its \u22EF, and where many rows are worked,\ntick them and state an act `on: "rows"`.\n\n#### Stages\n\nWork nobody approves needs no approval stage: the row saved is the fact (a goods receipt nobody approves moves stock as\nit is saved); an approval and its owner enter where this trade has a decider, named in the handover.\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: one with no one in it stops the step, and the app says so) 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 table whose people should be told states `tells: true` on its `status` and names each deadline that tells in `records.tells`; absent, no one is told. Whoever a row waits on then has one card in their inbox per stage, counted ("3 orders wait on you: Packed") and mailed once when it opens; a row joins it on reaching the stage, on a change of owner to them or when its deadline is three days off or passed, and leaves it when it moves on. It counts only rows the member can open in the app; the member who made a change is counted without being told, and work already waiting is recorded without telling anyone. A stage states `"tells": false` to be left out. `records.tells` names by a date\'s alias who is told: `true` for whoever the row waits on at its stage (else the owner of its first stage), a member field, `link.field` or `{ "group": <id> }`; a row at a closed option or settled is never told. 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 the work walks through in order states `Steps` on its page, bare where no stage has a form, and it draws as a line across the page, each step naming its owner: only the author knows whether its options are a journey. A state a row moves between (active, paused, ended) states none, and draws in the head alone, as a select where a person moves it by hand. Where each stage has its own form to fill or its own list, the Record states each as a Section inside `Steps`, and the path draws down the page, each step holding what its stage holds; an act that asks one value and an act that files a paper need none. 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 bare `Steps` draws it as a line of steps: 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. `over` a date makes a figure a tile of the List\'s own period: its number, its change from the period before and its history. Any other figure that counts rows (no `value`) is said on the list\'s summary line, where a press narrows the rows to it; one that adds up a number stands as a tile, or on that line where it stands alone. A list\'s Tabs are one chip in its controls. 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 usually 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 figure reads under its field\'s `label` over every row it sums, whatever stage each stands at: "Sell total" holds over all of them, where "Billed" holds only over rows already billed. 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. A figure stated per party (owed, overdue, short) opens on the rows that make it,\nlisted on that party\'s page and adding up to it. Many Readings stand on several Sheets, each a View the reader picks. 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. 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. Its parts stack, one scroll with each headed. A record a person comes to for several jobs can group its parts into Tabs (`{ "type": "Tab", "label", "children" }`), one per job, each named for what a person opens it for and holding that job\'s Sections, Lists and fields; one shows at a time. Once a record states a Tab, every part stands in one, and `Steps` and the Side beside them; what a person needs whichever tab is open belongs in the head\'s `facts`, the steps or the Side, which stay in view. State few Tabs, each a page worth opening: a part of a few fields or one short List stands in a neighbouring Tab under its own heading, and a short record needs none. A part is one area of the record\'s data a person comes to for its own job; its related lists and field groups sit inside it under their headings. A status\'s stages are not areas (Stages). 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 your tree draws, 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, since a column shows it empty or wrong at earlier stages. 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; the platform lists under a record only a child your tree draws elsewhere (a List of it in another record, or a Record page of it; a child a root List is over is that List\'s), so a child no List or Record draws is never listed, saved, added to or deleted from through the app, and a table the app only links to is read as a face to pick a row by. 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 where an agent doing\nthat job is asked for or plainly saves more than it costs, named in the handover; 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 it pays for its run. Worked: `examples/calls`.\n\n ';
|
package/docs/build.md
CHANGED
|
@@ -8,7 +8,7 @@ Before the first table, `set_workspace` states the business's `timezone` (how ev
|
|
|
8
8
|
|
|
9
9
|
## 0. The day's work
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
Name the jobs done most often and first in the day, the ones the request names and the rest a business of its kind does daily (what comes in, what goes out, what is counted or billed), and the exceptions each meets (the common ones: going back a step, correcting a locked record, work in parts or split, data late or out of order, a cancel, closing only once the work before is done; build those this work meets, not the list). Build those jobs first, each from the screen it starts on, from what you have and, where it is silent, from how this kind of business runs; name each assumption in your report for the owner to change. Who does a job matters where the work says so: a step another person approves, data not everyone may see, and who each app is given to (`get_workspace` kind `member` lists the organization's people, not who does what here). Whether to ask the person who asked is your call; three questions usually settle a workspace: what work happens most often, the papers and lists the business keeps (attached as files), and what must never go wrong.
|
|
12
12
|
|
|
13
13
|
## 1. Tables and their checks: `set_tables`
|
|
14
14
|
|