@lotics/cli 0.321.124 → 0.321.126

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/docs/design.md CHANGED
@@ -3,7 +3,7 @@
3
3
  An app is a tree of components: a List of one table, the Record a row opens, its Sections, the Acts that move it. The
4
4
  tree states COMPOSITION — which fields, lists and acts each job's screen holds; how each piece looks is the platform's,
5
5
  one way per concept. A node the tree leaves out draws its default, from the table's facts (`records`, the stage, the
6
- write rules): a List's Readings band, the stage buttons, the picture. What a write stores, and the Section that follows the table: `reference/changing-an-app`. State a node to change it,
6
+ write 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,
7
7
  or `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
8
8
  or 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`.
9
9
 
@@ -15,38 +15,37 @@ or its entity is read-only (`edit: false`); a stepped status is not, since Acts
15
15
  - What needs attention leads the row as an issue its table declares (`design/issues`): a derived flag is an issue, in the
16
16
  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
17
17
  reads in the success tone. `records.mark` is a category's own mark, a select whose options carry a brand or glyph.
18
- - A list's columns: the name and its lead, the status, then the columns the job reads on every row, as many as fit a desk. Each
19
- fact once: a column the row draws itself stands once. A generated number (`autonumber`) as the title yields
20
- 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
18
+ - 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
19
+ 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`
20
+ 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
21
21
  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.
22
22
  - A list worked by a date states `sort` on that date's column, newest first; without one, a register reads newest made
23
- first and a record's child List in the order its rows were added.
24
- - Someone is a face wherever they are read: a link to a table stating `records.party` draws its row's face; a member
25
- field is one already; select options naming people or organisations who are neither each take the `mark`
26
- `{"kind": "avatar", "name": "person"}`, never a colour dot.
23
+ first, a record's child List in the order its rows were added.
24
+ - Someone is a face wherever read: a link to a table stating `records.party` draws its row's face, as a member
25
+ field does; select options naming people or organisations who are neither each take the `mark`
26
+ `{"kind": "avatar", "name": "person"}`, not a colour dot, so a person reads as a person.
27
27
  - Each record is whole within its app: its page holds what the record is (its facts and its papers) and its child
28
28
  rows, in parts a person moves between, so someone arriving at it understands it without guessing. Rows of another
29
29
  app's job read in place as read-only lines — their name and figures — and the app states no page for an entity
30
- another app works. A register opens on its rows with the figures its job reads, never on a filter that leaves one.
30
+ another app works. A register opens on its rows with the figures its job reads; a filter leaving one hides that the rest exist.
31
31
  Completeness is of the work, never of decoration: a part, column or Reading nobody's work reads stays out.
32
- - A thing shows its picture, a file its preview, a plan its days on a time axis, a quantity a meter (`records.limits`) or
33
- a chart, a register its Readings, and long text reads whole (a markdown Field; `block: true` on plain long text).
32
+ - 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
33
+ a chart, a register its Readings; long text reads whole (a markdown Field; `block: true` on plain long text).
34
34
  - A number a reader judges — against a target or a bound, over time, as a mix of parts, through steps — is drawn as a
35
35
  picture wherever it stands: a list's columns, a record, a card, a band. A Reading stands in each of those places, and
36
36
  which picture each shape of Reading draws is `reference/reading-node`.
37
37
  - An option with a `color` draws its dot where its select is drawn; one without reads as its word. A `mark` where a
38
38
  brand or glyph names the option, on every option of a select read down a column (how it was paid, the channel).
39
- - Every app states its tile's `color` and `icon`, each apart from the workspace's other apps where it can be: an
40
- app stating no icon draws the one glyph every such app shares.
39
+ - Every app states its tile's `color` and `icon`, apart from the workspace's other apps.
41
40
  - The paperwork is the proof of the work: a files field per purpose (what arrived, what was issued to the customer, the
42
41
  carrier, the authority) in the Section where that work happens, and the source of a
43
42
  figure (a screenshot, an email, a sheet) on its row. Every files field is drawn somewhere. A paper a counterparty
44
43
  sends (a supplier's invoice, a delivery receipt) is added on the record it arrives with — the order it is for — and
45
- listed again where it is settled, never only in the counterparty's ledger.
44
+ listed again where it is settled, since the counterparty's ledger alone hides it from the order.
46
45
 
47
46
  <!-- generated:start words -->
48
47
 
49
- **The words most builds state.** A node's page holds its rules and every other word: `reference/list-node`, `reference/records`, `reference/field`.
48
+ **The words most builds state.** A node's page holds every other word: `reference/list-node`, `reference/records`, `reference/field`.
50
49
 
51
50
  **Table**
52
51
 
@@ -107,6 +106,7 @@ or its entity is read-only (`edit: false`); a stepped status is not, since Acts
107
106
  - `figure` (alias): The one number the row stands for, read at its right (a total, a quantity left)
108
107
  - `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
109
108
  - `due` (list of alias (at least one)): Dates that are deadlines (stored, or computed as a date)
109
+ - `tells` (map of alias → (`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
110
110
  - `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
111
111
  - `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)
112
112
  - `limits` (map of alias → (alias | number)): A number read against a bound
@@ -116,7 +116,7 @@ or its entity is read-only (`edit: false`); a stepped status is not, since Acts
116
116
 
117
117
  **`records.status`**
118
118
 
119
- - `field` (alias, required): The single select that is the row's state, its options in the order the work goes through them, drawn as a line of steps on a record page where no Section states `at`
119
+ - `field` (alias, required): The single select that is the row's state, its options in the order the work goes through them
120
120
  - `closed` (list of alias (at least one)): Options that end the work
121
121
  - `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)
122
122
  - `dates` (map of alias → alias): Option alias → 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
@@ -134,7 +134,7 @@ or its entity is read-only (`edit: false`); a stepped status is not, since Acts
134
134
 
135
135
  - `entity` (alias, required): The table whose rows the List draws
136
136
  - `create` (boolean | list of alias (at least one)): The fields an add asks
137
- - `columns` (list of (alias | Edit column | Reading)): Fields read after the row's title, in this order, each drawn though no row holds it
137
+ - `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
138
138
  - `label` (text): The register's name in the app's lists and tab strip
139
139
  - `filters` (list of (alias | Tiered filter | Listed filter)): Fields the reader narrows by every day, beside the stage chips
140
140
  - `children` (list of (Tab | Reading | Act | List) (at least one)): Its Tabs, band Readings and Acts over ticked rows or every row in view
@@ -151,7 +151,7 @@ or its entity is read-only (`edit: false`); a stepped status is not, since Acts
151
151
  **Record**
152
152
 
153
153
  - `entity` (alias, required): The table whose rows open on this page
154
- - `children` (list of (List over a Query in a Record | alias | Field | Fieldset | Section | Steps | Side | Outside | List | Reading | Statement | Comments | Act | Check) (at least one)): Parts (Section, Side, and one Steps holding the Sections that are its path), and the Fields, Fieldsets, Lists, Readings, Statements and Comments stated directly
154
+ - `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
155
155
  - `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
156
156
  - `row` (Record row): How the App reads this entity's rows wherever it lists them
157
157
  - `door` (`"page"` | `"drawer"`): How a row opens, on a page or in a drawer
@@ -195,7 +195,7 @@ or its entity is read-only (`edit: false`); a stepped status is not, since Acts
195
195
  **Reading**
196
196
 
197
197
  - `label` (text): What the figure is called
198
- - `value` (alias | `{ "avg": alias }`): A number field summed over the rows, or `{ avg }` averaged over the rows holding one
198
+ - `value` (alias | `{ "avg": alias }`): A number field summed over the rows (absent, the rows are counted), or `{ avg }` averaged over the rows holding one
199
199
  - `by` (alias | Tiered filter): Splits the rows into parts
200
200
  - `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 }`)
201
201
  - `entity` (alias): The List's rows
@@ -206,35 +206,38 @@ or its entity is read-only (`edit: false`); a stepped status is not, since Acts
206
206
  ## Issues
207
207
 
208
208
  A row takes what the person has, in the order it arrives — a supplier's paper after the delivery, a payment before its
209
- invoice, a price filled in later. What is missing or out of order is an issue on the row, never a refusal of the write;
209
+ invoice, a price filled in later. What is missing or out of order is by default an issue on the row, not a refusal;
210
210
  refusal is kept for what must never happen and for the step that cannot be taken without a fact, which names it (an
211
211
  invoice made without the buyer's tax code).
212
212
 
213
213
  Whatever goes wrong on a row and needs a person to act — a line delivered short, a price missing, a customer over their
214
214
  credit limit, a permit about to expire — is an issue its table declares in `records.issues`. A declared issue stands in
215
- every app that draws its row, with no app stating it: first on the row's line (`+N` the others), in the record's callout (a count of child rows as pills on those rows), in the List's filter of what needs checking with how many rows hold it, and those rows first. It never makes an
215
+ every 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
216
216
  app 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
217
- status, a category a select. A record's callout says each issue by its label and what it means: a text issue's own sentence, a yes/no issue's field `description` — give a yes/no issue's field one, or its line shows the name alone.
217
+ status, 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` — give a yes/no issue's field one, or its line shows the name alone.
218
218
 
219
- Declare an issue only where the owner confirms each flagged case is a problem: a rule that flags rows nobody fixes trains
220
- everyone to ignore the colour, real issues included. Where a flagged row may be accepted as it is (a price agreed by
219
+
220
+ An issue is a promise that someone will act every time it stands.
221
+ Declare an issue where each flagged case needs someone to act, since a rule that flags rows nobody fixes trains everyone
222
+ to ignore the colour; name those you assumed in the handover. Where a flagged row may be accepted as it is (a price agreed by
221
223
  exception), give the acceptance a field the formula reads, so accepting it clears the issue.
222
224
 
223
225
  - An issue is a formula of the row stating `output_type`: `"boolean"` stands while true; `"text"` stands while not empty,
224
226
  its words the sentence the reader sees — use it when the sentence must say what or how much ("Short 4 of 10").
225
- Its label is its name. Put the moment it matters in the formula, so it clears itself when the work is done.
227
+ 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
228
+ Act's `confirm` shows stands before the press: an issue that holds only at the stage the press lands on says nothing there.
226
229
  - The list is priority: an issue blocking the next step leads, then the earlier in the list.
227
230
  - `{ "rows": <link> }` on a parent rolls up every issue its child table declares, through a many-link paired to the
228
231
  child's one-row link back. The platform keeps a count on the parent per child issue, `<link>_<issue>`, labelled
229
232
  "<link label> · <issue label>"; never write it. The parent reads "2 rows left: Lines · Short".
230
- - A formula reading `now()` or `isToday()` (overdue, expiring within 30 days) is judged again every night, to the day.
233
+ - A formula reading `now()` or `isToday()` (expiring within 30 days) is judged again nightly.
231
234
  - An app's `Check` says what the issue does not: `on`, what it refuses in that app (`"update"`, `"all"`, or that
232
235
  entity's Acts), and `resolve`, the Act that clears it; one stating neither is refused, and one without `on` names a
233
236
  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
234
237
  the parent while it runs, so its own `workflow` cannot send mail, notify, run an agent or wait — start that work from a
235
238
  workflow the act starts after.
236
- - A lock is a Check, not an issue: a yes/no such as paid in full refusing `"update"`, in no `records.issues`, since nothing
237
- is wrong with the row.
239
+ - Read-only in this app is a Check refusing `"update"` (paid in full), in no `records.issues`; a lock on every door is
240
+ 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.
238
241
  - `get_table` reports each issue: rows holding it now, opened in the last 30 days, median days to clear.
239
242
 
240
243
  An order whose lines can arrive short or unpriced, invoiced only when no line is short:
@@ -257,9 +260,9 @@ An order whose lines can arrive short or unpriced, invoiced only when no line is
257
260
  ## Look at it
258
261
 
259
262
  After an apply, `screenshot_app` draws each app as its people see it — the register, and a record by its `path` or its `record_id`
260
- (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 — at a desk's width and a phone's, naming the columns a table left off at each width;
263
+ (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) — 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;
261
264
  `-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
262
- stored tree would be refused for now, and its notes. Answer `design/the-rubric`, change the tree with `nodes`, and write again. To go back,
265
+ stored 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,
263
266
  send the tree saved before the change as `body` with `app_id`, nulling an App prop stated since (`words`, `scope`,
264
267
  `period`, `icon`); tables and rows stay as they are.
265
268
 
@@ -267,13 +270,14 @@ send the tree saved before the change as `body` with `app_id`, nulling an App pr
267
270
 
268
271
  Whether the build does the owner's work, answered by a call each, never from what you meant to write:
269
272
 
270
- 1. Each job the owner named, and each their kind of business cannot run without: which screen does it, and which press? Find each on a `screenshot_app` shot of the person who does it (`as_member`); one who cannot open the app is first invited (`set_members`) and given it (`set_access`) — an app nobody shares opens for admins alone.
273
+ 1. 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`).
271
274
  2. 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`).
272
- 3. Is each kind of row in its treatment (`design/treatments`)? Timed work reads in a calendar or lanes, and a weekly plan as the dated rows it makes.
275
+ 3. Is each kind of row in its treatment (`design/treatments`)?
273
276
  4. Does each screen show the least its next step needs, each fact once, the signal that a step is due leading?
274
277
  5. Is anything cramped at desk or phone width?
275
- 6. 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 the file it files; prove a List's `export: true` with `run_app_query` and `export`.
278
+ 6. 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`.
276
279
  7. 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`).
280
+ 8. 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`.
277
281
 
278
282
  A failed answer is a change to the tree, or a gap named to the owner.
279
283
 
@@ -287,32 +291,34 @@ Each kind of row's view is chosen before its List is written:
287
291
  |---|---|---|
288
292
  | People or organisations | `records.party`, with a photo or logo as its `image` | |
289
293
  | 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` |
290
- | Read by their day | List `layout: "calendar"`; on a record, a child List with `layout: {"agenda": …}` | `reference/calendar`, `reference/layouts` |
294
+ | Read by their day, one diary of everyone's bookings | List `layout: "calendar"`; on a record, a child List with `layout: {"agenda": …}` | `reference/calendar`, `reference/layouts` |
291
295
  | Ranked by a figure, or worked by a date | List `sort: {"field": …, "desc": true}` on that column | |
292
- | Booked on a resource | List `layout: {"lanes": {"by": …}}`, and the table's `no_overlap` — a list of rules where a row holds two (a room and a teacher) | `reference/lanes`, `reference/write-rules` |
296
+ | Each person or room booked by the hour, where who is free matters | List `layout: {"lanes": {"by": …}}` by that person or room, and the table's `no_overlap` — a list of rules where a row holds two (a room and a teacher) | `reference/lanes`, `reference/write-rules` |
293
297
  | A day's work given out to people or vehicles | List `layout: {"lanes": {"by": …}}` over rows holding a day and no hour | `reference/lanes` |
294
298
  | A log of what happened | a child List with `layout: "timeline"` | `reference/layouts` |
295
- | Opened to be worked on | the Record's Sections — each one area of the record's data, its lists and field groups inside it; a status's stage acts stand at the foot of the rows they move; a stage that holds something of its own, a note included, is a Section inside `Steps`; fields only one kind of row holds (a delay's cause, a safety issue's hours lost) in a Section whose `when` names that kind | |
299
+ | Opened to be worked on | the Record's Sections — 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 | |
296
300
  | Rows that each belong to another row | a child List on that row's Record, with `create` and `remove` — and a child's own rows a List in that child's page, as deep as the data goes, and every row's ⋯ offers Duplicate; a List with `same` where read-only | |
297
301
  | 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` |
298
302
  | Moving through a status | an Act per move, `status.dates` for the moment of each stage, and the register's Readings | |
299
303
  | 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 | |
300
304
  | Papers a case gathers | a List with `expect`; the papers made, an Act's `templates` | |
301
- | A plan of spans | List `layout: {"gantt": {"start": …}}` | `reference/gantt` |
302
- | Stood at a place on a plan, flat or in 3D — pallets, bins | List `layout: {"plan": …}`; places state `plan_place` | `reference/plan` |
305
+ | Jobs that run over several days, each with a start and an end date | List `layout: {"lanes": {"by": …}}` by who or what does them, or `layout: {"gantt": {"start": …}}` where the jobs follow each other | `reference/lanes`, `reference/gantt` |
306
+ | 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": …}` 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` |
303
307
  | Checked item by item against a standard | a List with `checklist: {"photo": …, "clause": …, "failed": […], "passed": …}`: each row a mark (passed at `closed`, failed at a `failed` option, or by the yes/no `passed` names — 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 | |
304
308
  | A place before and after the work | a List with `compare: {"before": …, "after": …}`: two files fields read side by side, or two value fields read as one struck-then-new column | |
305
309
  | Spots on a drawing | `records.pin: {"on": …, "x": …, "y": …}` 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` |
306
310
  | 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` |
307
311
  | 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` |
308
- | The rows a weekly pattern owes (a class's lessons on Tue and Thu at 16:00) | `records.cadence: [{"entity": …, "on": "<a multi-select of mon–sun>", "start": …, "end": …, "planned": …, "except": …}]` 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` |
309
- | Who did what on which day | List `layout: "roster"` with the List of its cells inside | `reference/roster` |
312
+ | 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": …, "on": "<a multi-select of mon–sun>", "start": …, "end": …, "planned": …, "except": …}]`, or `{"entity": …, "every": {"months": 6}, "from": "<a date of the row>", "planned": …}`, 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` |
313
+ | 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` |
314
+ | 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` |
315
+ | 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` |
310
316
  | 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` — 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 | |
311
317
  | Steps people drop out of between | a Reading with `steps` on the record whose child rows count them | |
312
318
  | A record's own numbers nobody keys, read at a glance | consecutive Readings with no `entity` (up to eight tiles) | |
313
319
  | 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` |
314
320
  | 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` |
315
- | Papers an agent reads, where the owner asked for one | an Act's `intake` with `fills` | |
321
+ | Papers an agent reads, where it pays for its run | an Act's `intake` with `fills` | |
316
322
  | Calls and visits | an Act's `record` | |
317
323
  | Changes a workflow proposes that a person approves row by row — 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` | |
318
324
  | Documents covering lines | a List with `under` | |
@@ -335,7 +341,7 @@ or several members, draws their faces as a stack that names them on hover. Worke
335
341
 
336
342
  `records.image` names the files field that pictures a row — a product's photo, a damage photo, a
337
343
  scan, a receipt. Every row of it then leads with its picture, or its paper's preview, wherever it is drawn —
338
- a row holding no picture leads with the placeholder; a link to it previews the file. `image` may instead name a
344
+ a row leads with its picture, and where no row in view holds one no row keeps a place for it — 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
339
345
  one-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
340
346
  its own words — 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
341
347
  `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
@@ -347,12 +353,21 @@ Every row an app draws opens on its page, the one you state or the one a write s
347
353
 
348
354
  ### Rows in time
349
355
 
350
- Rows that each stand on a day, or hold a run of days or hours, are read where they stand in time — never
351
- as two date columns. A row holds a span when two dates a person states are ordered, the second after the first by a
356
+ Rows 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
352
357
  `min` or a table check, both required or the second the row's `due`; else it is an appointment when one required date
353
358
  is stated that no Act stamps, that a new row does not start at `today` and that is not derived. A stamp is an event,
354
- and a `due` is a deadline, never the day a row is held on. A `no_overlap` by a person or a value alone keeps one row at
355
- a time each — a member's periods in turn — read by what they hold.
359
+ and 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
360
+ a time each, read by what they hold.
361
+
362
+ Where a resource has several units (40 scaffold boards), a booking states how many it takes
363
+ (`quantity`, a number of the row) and the item states how many there are (`limit`, `"item.stock"`, a number of the one
364
+ row the `by` link names): a booking that would take more than are free on any day is refused, saying how many are free.
365
+ What counts is the most held at one moment, so hires of 10 on days 1–2 and
366
+ 10 on days 8–9 leave 20 boards free for a hire of 5 over days 1–10. A row with no quantity holds nothing, an item with no
367
+ stock bounds nothing, a stock that does not compute refuses the booking, and lowering the stock below what is held from
368
+ today on is refused. A booking holds the days it states while it stands at a state `while` names. Rows
369
+ compete 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
370
+ appointment's start plus its length), never one that reads the clock.
356
371
 
357
372
  #### Calendar
358
373
 
@@ -367,11 +382,11 @@ runs to. The bare word takes both from the rows' facts and is refused, naming `d
367
382
  machine, a room), each drawn even when empty: every row a block from the first date on its line to the
368
383
  second, and a free stretch adds a row there. `loads` reads what a lane carries against what it holds: hours summed
369
384
  within each day (across days, the fullest day, named), any other number the most its rows add up to at one time. A
370
- `no_overlap` `by` the same link refuses two rows on one resource at once. A lane per person: `by` a member field
385
+ `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
371
386
  and `of` a group of the workspace by its id, each member of it a lane, idle ones too. Worked: `examples/lanes`.
372
387
 
373
388
  A day's work given out (stops to drivers, jobs to technicians): rows holding a day and no hour read at one day as cards
374
- in lanes, those no lane holds, or holding no day, first in a tray. Each lane's head reads its count, its loads and its
389
+ in 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
375
390
  row'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
376
391
  dragged go to a lane in one write, every row checked before any is written, and the List's first `sort`, ascending on a
377
392
  number the app writes, is a card's place in its lane.
@@ -398,7 +413,7 @@ a multi-select whose options are aliased `mon` to `sun`, and its times two `form
398
413
  as a week strip wherever a person writes it; a Section holding the cadence's fields draws them as one week pattern; the
399
414
  row's line reads it as one fact ("Tue, Thu · 16:00–17:30"); a roster of the child reads each row's own days. An Act
400
415
  `makes: "<child>"` lists the rows still owed under the row each is made for, a group's count and tick at its head, a
401
- row that would be refused unticked with why, and writes the ticked ones (`reference/record-places-pins-and-cadence`). A row that differs from a changed pattern is proposed as a move, ticked only where no person edited its day, end or a copied field and no row links to it; the class says how many rows differ.
416
+ row 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.
402
417
 
403
418
  #### Agenda
404
419
 
@@ -410,7 +425,7 @@ date of the record.
410
425
 
411
426
  A child List with `layout: "timeline"` on a record: a child read as a log of dated entries, newest first, with a composer — the
412
427
  calls, visits and notes about the record, each with who and when, and its files where the child's `image`
413
- names them. An app's Record draws no comment thread: a team's discussion on a record is a child table. Entries planned ahead are an agenda; the status's moves are its history. Worked:
428
+ names 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:
414
429
  `examples/party`.
415
430
 
416
431
  ### Moves and numbers
@@ -419,47 +434,49 @@ names them. An app's Record draws no comment thread: a team's discussion on a re
419
434
 
420
435
  The 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
421
436
  status holds it, `set` to the next), at the foot of the Section whose work it ends. A status with nothing closed is a
422
- condition a person sets. A value decided as a row reaches an outcome — why it was lost, refused, voided — is that
423
- Act's `asks`, never a field the reader must remember to fill. An Act reaching past the workspace — sending an invoice
437
+ condition a person sets. A value decided as a row reaches an outcome — why it was lost, refused, voided — is by default that
438
+ Act's `asks`, since a field to remember is left empty. An Act reaching past the workspace — sending an invoice
424
439
  to a service, a letter by mail — runs its `workflow`, and what the workflow keeps from the answer (an invoice's id,
425
440
  its link) is named in the Act's `set`. Work sent back for changes moves back to the earlier
426
441
  step; 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
427
- stage's `when` (below); an issue to resolve is a row of its own. An Act also moves a row back (`when` the later
442
+ stage'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
428
443
  stage, `set` the earlier), and without one a row moved on by mistake stays until an admin edits the table. What a
429
444
  `workflow` or a paper did stands, so a way back there is a correction of its own.
430
445
 
431
446
  #### Buttons
432
447
 
433
- People mostly work through agents, so an app draws no button by default: an Act is offered everywhere, and a record's
434
- header ⋯ and a row's ⋯ list it. Rows never draw a button: every row act waits in its ⋯, and where many rows are worked,
435
- tick them and state an act `on: "rows"`. An Act on a record or drawer states `button: true` only for a step a person
436
- does at that screen (a count received, a signed paper, an approval), never for work an agent does (an invoice made
437
- from delivered orders, a payment matched from a statement). Every other Act waits in the record's ⋯.
448
+ People 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
449
+ you 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
450
+ closes 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 ⋯. `button: true` on each step a person does at that screen (a count received, a signed
451
+ paper, an approval), `button: false` on one only agents run (an invoice made from delivered orders, a payment matched
452
+ from 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
453
+ steps whatever `button` says. Rows never draw a button: every row act waits in its ⋯, and where many rows are worked,
454
+ tick them and state an act `on: "rows"`.
438
455
 
439
456
  #### Stages
440
457
 
441
- Work the owner named no decider for has no status: the row saved is the fact (a goods receipt nobody approves moves
442
- stock as it is saved), and a stage, its owner or an approval enters with the person the owner said decides.
458
+ Work nobody approves needs no approval stage: the row saved is the fact (a goods receipt nobody approves moves stock as
459
+ it is saved); an approval and its owner enter where this trade has a decider, named in the handover.
443
460
  Name each job's work plan by its shape: a status a person sets; a pipeline, where who holds the row and for how long
444
461
  matter; or tasks, where only how many are done counts (`records.task`). A pipeline states each stage once in
445
- `records.status.stages` — its `owner` (a member field, a link's member field, or `{ "group": <id> }`, a member group) and its target
462
+ `records.status.stages` — 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
446
463
  `within` days — 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
447
464
  named with why. A move forward passes each owned stage between that binds the row, each its owner's. A stage's `when`
448
465
  names 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
449
466
  and as the write leaves it; with none, it binds every row. Expense claims over a limit wait for the finance group while
450
467
  smaller ones go straight to payment: `"finance_review": { "owner": { "group": <id> }, "when": { "amount": { "gt": 5000000 } } }`.
451
468
  A row at a stage leaves it by its owner whatever its `when`; `dropped` names the closed options
452
- that leave the work undone (cancelled, rejected), which whoever holds the row moves it to from any stage. A stage's owner gates who moves a row out of it; who may move a row into a stage ("only a bookkeeper marks an invoice paid") is a check. Late rows, rows due soon, a warning the line draws and rows waiting on the reader stand first in a
469
+ that 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
453
470
  register; a register whose job is a strict order, a first-come queue, states `attention: false`.
454
471
 
455
- A status draws one of three ways, by what the author states, never by habit. With nothing `closed` it is a condition a person sets: its select, no steps. With `closed` it is a path: one a person moves by hand (no Act moves it, or its `row` states `status: { edit: true }`) keeps its select alone, and one Acts move draws its stages as a line of steps across the page, each only moving the row on. Where a stage holds something of its own — fields, blocks, an act that asks or files a paper, a note — the Record states it as a Section inside `Steps`, and the path draws down the page, each step holding what its stage holds. A part that is the work at every open stage is no step and states no `at`; `when` shows a part only at some stages.
472
+ A 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.
456
473
 
457
474
  #### Stage dates and history
458
475
 
459
476
  A 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
460
477
  to the business — reported, filtered, printed — it is a date on the row that `records.status.dates` stamps as the row
461
478
  enters the option, whoever writes: the one way a status is timed, and the moment a stage's `within` runs from (each stage, and
462
- each open option of a status with stages, naming none gets `<option>_at`). A straight-line process is one select of its steps in order, each dated (a record that states no `Steps` draws it as a line of steps by itself: no date fields or formulas copy it); a move whose
479
+ each 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
463
480
  day 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
464
481
  status move (its link to the row, the new status, the moment and who) for a business that reports on every move: moves
465
482
  per person, or time in a stage a row re-enters. An event with facts of its own — a reason, an amount, a signature — is
@@ -468,13 +485,13 @@ stage is signed once per person, read off who moved the row.
468
485
 
469
486
  #### Readings
470
487
 
471
- A List usually opens with one band of figures or a chart, chosen for what that person watches. Its Readings stand above the rows and its filters and read the rows under the open tab, never narrowed by the controls below them. Lead with the job's headline number —
488
+ A 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 —
472
489
  its exception as a formula's yes/no in a Reading's `where` (what is short), never a stage the
473
- status chips already count, nor the overdue rows the register's summary line counts from `records.due` — then at most the mix (`by` a field) and the movement (`by` a date), varied by job. A movement over a date is stated, never defaulted; so is a sum, but for the one a status register with a money figure leads with by default: that figure over its open rows, titled by them ("Price (open)"). A register with no such figure and no single select to split by gets no default band.
490
+ status chips already count, nor the overdue rows the register's summary line counts from `records.due` — 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.
474
491
  A grid (`by` and `across`) reads on a Sheet. A Sheet — a View of Readings at the App's root, beside its Lists or alone —
475
492
  answers one owner's question across jobs, each Reading windowed by the reader's period (the App's `period`), and a
476
493
  List on it hands over the rows to act on. A figure stated per party (owed, overdue, short) opens on the rows that make it,
477
- listed 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. Sums of each row's child rows are a Tab's `totals`. Worked: `examples/approval`, `examples/dashboard`.
494
+ listed 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`.
478
495
 
479
496
  #### Funnel
480
497
 
@@ -498,7 +515,7 @@ an app (`app_architecture`).
498
515
 
499
516
  #### Sections
500
517
 
501
- A record is a head, its parts and at most one Side. Its parts stack, one scroll with each headed; state `parts: "tabs"`, or a `tab` on a Section, to show one part at a time, and Sections stating one `tab` share a tab. A part is one area of the record's data a person comes to for its own job, like the tabs of a settings page; its related lists and field groups sit inside it under their headings. A status's stages are not areas: their acts stand at the foot of the rows they move, and a stage that holds something of its own — fields, blocks, acts, a note — is a Section inside `Steps`, one `Steps` to a record. State each
518
+ A 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
502
519
  part whole for the work there: a field may stand in any number of parts, and a field an Act requires draws beside it
503
520
  unstated. 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
504
521
  them) goes in a Side: it leaves the head and stays on the rows; what only a stage's Act writes (an invoice's number,
@@ -507,7 +524,7 @@ stands in the head or the Side, never a Section. `row` changes how the app's row
507
524
  Sections draws once, in the first; a Check stated in a Section guards the whole record.
508
525
 
509
526
  The Record's Sections, in the order the work reaches them: the fields people write, a Field per paper the record
510
- keeps, a child List per child, the Acts at each one's foot. A register's `columns` are in the order the job reads them, as many as fit a desk; what is read only on the way deeper is the Record's, and a figure that is final only from a stage is a Field of that stage's Section, never a column read on every row at every stage. A register laid out in time (calendar, lanes, roster) opens the
527
+ keeps, 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
511
528
  default record: every field a person writes. Behaviour belongs in an Act.
512
529
 
513
530
  A Section of more than about six fields reads as Fieldsets of related facts: a patient's record holds "Contact" and
@@ -519,7 +536,7 @@ short field, one leaves the half beside that field empty.
519
536
 
520
537
  Rows that each belong to one row of another table (a one-row link to it) are drawn under that row: a List on
521
538
  its Record, `layout: "timeline"` where they are a log, `layout: {"agenda": …}` where they are planned on a day and within it, or
522
- `layout: {"gantt": …}` where they are bars on a schedule. Which children a record lists is the author's — one of them at least. A List
539
+ `layout: {"gantt": …}` where they are bars on a schedule. Which children a record lists is the author's — 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
523
540
  listing only some of them narrows by its `where`: a select (one leg's fees), or a yes/no — a formula's for what is
524
541
  still owed — on a List that adds no rows. A child List stating no `create` asks the table's required fields, natural key and
525
542
  title; where defaults fill them all, it adds none. Rows on
@@ -549,8 +566,8 @@ A paper the business is brought and reads is an Act's `intake`: the press takes
549
566
  them, and each is filed as the line of its kind in the child the record `expect`s, while `fills` writes what
550
567
  they state into the record's fields — a single link as a row the agent finds among those the app reads — 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`.
551
568
 
552
- An agent Act — an `intake`, a `record`'s `fills` — spends a run on every press, so it is stated only where the
553
- owner asked for an agent to do that job; otherwise a paper brought is its `expect` line, and a person types what it states.
569
+ An agent Act — an `intake`, a `record`'s `fills` — spends a run on every press, so it is stated where an agent doing
570
+ that 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.
554
571
 
555
572
  #### Under
556
573
 
@@ -564,5 +581,6 @@ already on file (a supplier bill) picks them with `pick` instead; choose one per
564
581
 
565
582
  An Act's `record`: the press records a call, visit or meeting — audio, transcript, screen where captured — and
566
583
  files it as a new row of the record's `timeline` child (`into`), stamped `at` and `by`; `fills` lets an agent fill
567
- that row's fields from the transcript, where the owner asked. Worked: `examples/calls`.
584
+ that row's fields from the transcript, where it pays for its run. Worked: `examples/calls`.
568
585
 
586
+
@@ -1,9 +1,8 @@
1
1
  # Document Templates
2
2
 
3
- Turn workspace data into finished documents — invoices, contracts, reports, letters,
4
- labels, emails — by filling a reusable template instead of writing a file from scratch.
5
- You register a template once, then generate a filled file (or a rendered email) from it as
6
- many times as you like, feeding it data from records, a workflow, or an agent run.
3
+ Turn workspace data into finished documents — invoices, contracts, letters, emails — by filling a template registered
4
+ once, with data from records, a workflow or an agent run. A paper the owner hands over as a Word or Excel file
5
+ becomes a template of that type; an `html` template is for a paper with no file of its own.
7
6
 
8
7
  This is a **capability + usage** guide. A tool's exact input schema is in its own description.
9
8
 
@@ -67,10 +66,10 @@ this host, give the person the file and a `person` drop link.
67
66
 
68
67
  ### By type
69
68
 
70
- - **`html`** — a full HTML document with inline CSS and `{{variable}}` placeholders, rendered to PDF; anything whose layout
71
- you control. `variables` are plain text, rich `html`, an auto-rendered `table` or a `list`; `format` (a named page size:
69
+ - **`html`** — a full HTML document with inline CSS and `{{variable}}` placeholders, printed to PDF.
70
+ `variables` are plain text, rich `html`, an auto-rendered `table` or a `list`; `format` (a named page size:
72
71
  A0–A6, Letter, Legal, Tabloid, Ledger) and `orientation` are optional; any other size is the page's own CSS,
73
- `@page { size: 50mm 30mm }`. A change may send `edits`, anchored replacements in the stored markup, in place
72
+ `@page { size: 50mm 30mm }`, and it prints to the sheet's edge unless it states `@page { margin: 15mm }`. A change may send `edits`, anchored replacements in the stored markup, in place
74
73
  of the whole `template`; `template_file_id` names an uploaded text file holding the markup, in place of `template`.
75
74
  - **`pdf-form`** — an existing PDF filled in place. `set_template` with the uploaded `template_file_id`
76
75
  answers `page_count` and `pages` (each page's `page_index`, unrotated MediaBox `width` and `height`, `origin_x`, `origin_y`
@@ -82,9 +81,9 @@ this host, give the person the file and a `person` drop link.
82
81
  ASCII and switches to Arimo past it.
83
82
  - **`excel`** — a `.xlsx` or `.xlsm` with `{{marker}}`s in the cells to fill, and a `variables` map. `sheet` names the sheet
84
83
  that is the paper in a workbook holding others, and the template leaves the rest out; a formula reading a sheet left out
85
- is refused. A macro workbook is kept without its macros and the buttons that run them. Markers are validated at create
86
- time: a structural error blocks the save, and a declared variable with no marker comes back in `unmarked_variables`
87
- (skipped). `set_template` with `dry_run: true` runs every check and stores nothing; a refusal lists every error with its code and cell, and `warnings[]` (`severity`, `code`, `message`, `sheet_name?`, `cell?`) comes back with the answer. Pass
84
+ is refused. A macro workbook is kept without its macros. Markers are validated at create
85
+ time: a structural error blocks the save, and a declared variable with no marker comes back in `unmarked_variables`.
86
+ `set_template` with `dry_run: true` runs every check, storing nothing; a refusal lists every error with its code and cell, and `warnings[]` (`severity`, `code`, `message`, `sheet_name?`, `cell?`) comes back with the answer. Pass
88
87
  raw numbers, ISO dates and booleans at generate time; the cell's number format shows them. A cell's format also decides
89
88
  what text becomes: text that reads as a number (`5%`) is written as one, unless the cell is formatted as text (`@`).
90
89
  A date cell reads a day or a moment written with no zone (`2026-09-30T08:15`) as that clock, and a moment written with
@@ -150,12 +149,15 @@ A field named like a function is read as the field, and calling the function the
150
149
  ```
151
150
  get_template {"template_id": "dtl_…"} # its declared variables
152
151
  generate_document {"document_template_id": "dtl_…", "filename": "invoice-1042",
153
- "data": {"company_name": "Acme", "total": 1042, "items": [...]}}
152
+ "data": {"client_name": "Acme", "total": 1042, "items": [...]}}
154
153
  ```
155
154
 
156
155
  - `data` is a map keyed by your variable names. Scalars for scalar/form fields; arrays for
157
156
  `table`/`list`/loop variables. `filename` excludes the extension (the type sets it). Pass a select, a
158
157
  member or a link as `query_records`' `display` words, a number and a date raw.
158
+ - A Word, Excel, html or email template may print `{{organization.name}}` and `{{workspace.name}}`: the platform fills them from the
159
+ template's own workspace, so `data` never carries them. A `data` key `organization` (or `workspace`) that states a
160
+ `name` prints that name instead.
159
161
  - `generate_document` renders the template's own type and returns a generated file object; take
160
162
  its `file_id` onward.
161
163
  - A PDF no template is wanted for takes `html`, a `filename` and its `data` in place of `document_template_id`: the markup is