@lotics/cli 0.315.18 → 0.316.0

package/docs/design.md

@@ -1,113 +1,77 @@
 # Designing an app
 
-Start here to build an app. This page is the method and the choice of treatment for each thing a job
-reads; every key it names is a key of `model.json`, and the page of the `model` reference stating a
-treatment's keys stands beside it in § Treatments. A treatment worked through in an app of a complete model
-is a page at `examples/<treatment>` — `lotics docs`, or the `docs` tool.
-
-A model states COMPOSITION — which fields, lists and acts each job's screen holds. How each piece looks is
-the platform's, one way per concept, and no key changes it. What the model leaves unnamed is never drawn,
-and a list the model leaves as a table is drawn as one, even where a calendar, a face or a picture would
-answer the reader at a glance. That is the most common failure of a model, so the apply refuses an app leaving
-out a treatment it requires — a register's readings, a record's sections and children, its status moves, a picture,
-rows in time, a template's act — until the model states it or declines it.
-
-## The method
-
-1. **People and jobs, before any table.** Name each person by the work they do, then each JOB in one
-   sentence: who does it, what exists when it is done, the record it moves. The sentence is the app's
-   `name` and `description`. A job is a desk a person works every day from its own list; one app per job,
-   each one working register over one entity — an app per table, or one app holding every table, is no job's
-   screen. What was brought into that register's rows or done to them — the files imported, the runs of a
-   batch — is read beside it as a log of the same app (`logs`, at most three), never an app of its own.
-   A job is the record it moves and the rhythm it moves at — the first list it opens on. What that record
-   owns (a vehicle's papers, its services, its fines) is sections, blocks and acts of it, never an app;
-   work over another record or at another rhythm (the week's dispatch runs, beside each vehicle's file) is
-   another app, even when one person works both.
-   A list worked only in passing on the way through another job — the rates a quote is priced from, the
-   transfers its receipts are matched to, the statement sent from its records — is a block, a section or an
-   act of that job's app, never an app of its own. A small business usually lands at four to six.
-2. **The entities the jobs touch.** A status is a state the work sits in, six options or fewer: a touch
-   ("called") is a row of a log, a money fact ("paid in full") a formula the figure shows. A quantity is a
-   number with its `unit`, never words in a text field; a quantity of several kinds is child rows, one per
-   kind, totalled at the foot of their block.
-3. **How each row is recognised** — a `records` entry for every entity an app lists, opens or picks: its
-   `title` (who or what it is, never a code — the code is a `subtitle`), up to two `subtitle` fields the job
-   reads at first glance, its `image`, its `party`, its `status` and which options are `closed`, its
-   `figure`, its `due` dates.
-4. **Each app's composition** — the register's `columns` in the order the job reads them, as many as fit a
-   desk (one that does not fit is drawn nowhere in the row; what is read only on the way deeper is the
-   record's), the `filters` it narrows by every day (at most 3, each a field the rows show, or a formula yes/no of fields they show), its `layout`
-   and `readings`; the record's `sections` in the order the work reaches them, each one's `fields`, `blocks`
-   and `acts`; the `checks` that warn or refuse. A rule the business states — a field needed before an act,
-   a quantity bounded, a picker narrowed, a duplicate reused — is the model's (an act's `requires`, a check's
-   `blocks`, `write_rules`), and every write re-checks it; a check without `blocks` only warns.
-5. **What a person would ask an agent in each app.** Write the asks down per app — every act, each list
-   narrowed the way a person narrows it, one record with its lines and papers, every figure, data brought
-   in — and beside each the query or workflow of the app that answers it (`agent_surface`). What the screen
-   reads and does is generated. An ask no screen makes is declared: a read in `queries` (`model/queries`),
-   a write in `workflows` (`model/workflows`). A figure an agent calls states its `alias`. An ask with
-   nothing to answer it is a gap in the model, closed before the apply. An app is built to be run by an agent:
-   every flow a person works can be driven end to end through its workflows, the person is asked only where
-   their judgement or authority is needed, and the screens show what was done and let a person do or put back
-   any step by hand.
-6. **A treatment for every list and every entity** — the next section. Choose it from what the rows ARE,
-   before writing any register.
-7. **Plan, apply, look.** The `check_model` tool (`lotics model check` on the CLI) checks the
-   whole model beside the workspace's rows and writes nothing — the patch adopting each app's decisions in
-   `designs`, and the app's body as they leave it its `draft`; `apply_model` (`lotics model apply`) mints each app live. Then look at each app —
-   § Look at it — and judge it against § The visual bar. A correction is a change to the model, applied again.
+The treatment each thing a job reads takes. Every prop named here is a prop of a component of the app tree, and the page of the `model` reference stating a treatment's props stands beside it. A treatment worked through in an app of a complete workspace is a page at `examples/<treatment>`. The method, the apps a business needs and the checks a tree meets are in `first_build`.
+
+The common treatments are the chooser in `first_build`, § 3; every treatment is listed at `design/treatments`.
+
+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
+tree states COMPOSITION — which fields, lists and acts each job's screen holds. How each piece looks is the platform's,
+one way per concept, and no prop changes it. A component bound to a table draws well with no props, because its defaults
+come from the table's facts (`records`, the stage, the write rules): a node the tree leaves out draws that default — a
+List's Readings band, the stage buttons, the picture, a Record's designed Sections, a head kept to its budget. State a
+node to change its default, or `false` at it to turn it off (`"readings": false`, `"row": { "status": { "edit": false } }`,
+`"row": { "image": false }`). A Field the screens draw is a control, a save, unless it states `edit: false`: an entity drawn read-only gets none, and a stepped status is never a default edit, since Acts move it. A List left as a table is drawn as one, even where a calendar, a face or a picture would
+answer the reader at a glance, and that is the most common failure of an app: the answer of `set_app` notes what the
+rows call for that no default draws (rows in time, a template's Act, a timeline), and the tree states the ones the job
+needs.
 
 ## Treatments
 
-A finding naming a section below is a treatment the model left out. A decided one refuses the apply, and the
-check gives each app it refuses a patch stating its decided treatments: merge the patches in the order the check gives
-them, or state why the app stays as it is in its `declines` (`model/declines`), under the key the finding names —
-then check again. A note refuses nothing.
+A treatment named in a section below is one the answer of `set_app` notes when the rows call for it and neither the
+tree nor a platform default draws it, naming the node that would state it. Nothing is written into the tree for the
+author: state the ones the job needs. A note refuses nothing.
 
-| The rows are | The treatment | Its keys |
+| The rows are | The treatment | Its props |
 |---|---|---|
-| People or organisations | `records.<entity>.party`, with a photo or logo as its `image` | `model/records` |
-| Things with a photo, a scan or a paper | `records.<entity>.image`; `layout: "cards"` where the picture is how a row is found | `model/records`, `model/cards` |
-| Read by their day | `layout: "calendar"`; on a record, an `agenda` block | `model/calendar`, `model/timeline-and-agenda` |
-| Booked on a resource | `layout: "lanes"` with `lanes`, and `write_rules` `no_overlap` | `model/lanes`, `model/write-rules` |
-| A plan of spans | `layout: "gantt"` with `gantt` | `model/gantt` |
-| Stood at a place — pallets, bins | `layout: "plan"`; places state `plan_place` | `model/plan` |
-| Who did what on which day | `layout: "roster"` with `roster` | `model/roster` |
-| A log of what happened | a `timeline` block | `model/timeline-and-agenda` |
-| Opened to be worked on | the record's `sections`, in the order the work reaches them — `at` where it moves in steps | `model/record-page` |
-| A record whose page is its own arrangement of pieces the app already states | `record.compose` | `model/composed-page` |
-| Rows that each belong to another row | a `rows` block on that row's record; a `list` block where read-only, stating `fields` for rows another app works | `model/blocks`, `model/list-block` |
-| Moving through a status | an act per move, `status.history`, and the register's `readings` | `model/acts`, `model/status`, `model/readings` |
-| Steps people drop out of between | a `funnel` block on the record whose child rows count them | `model/reading-blocks` |
-| A record's own numbers nobody keys, read at a glance | a `figures` block of two to eight tiles | `model/reading-blocks` |
-| 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 | `model/tabs` |
-| Papers a case gathers | a rows block with `expect`; the papers made, an act's `templates` | `model/blocks`, `model/papers-and-recordings` |
-| Rows that are each a place a record is sent | a rows block with `expect` on the link to those places and `post`: each ticked, the post written there and read as its feed shows it | `model/publish-desk` |
-| Papers an agent reads, where the owner asked for one | an act's `intake` with `fills` | `model/papers-and-recordings` |
-| Calls and visits | an act's `record` | `model/papers-and-recordings` |
-| 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` | `model/acts` |
-| Documents covering lines | a rows block with `under` | `model/blocks` |
-| Rows on file a record takes in | a rows block with `pick` | `model/blocks` |
-| One owner's question across jobs | a dashboard app | `model/dashboards` |
+| People or organisations | `records.party`, with a photo or logo as its `image` | `model/records` |
+| Things with a photo, a scan or a paper | `records.image`; List `layout: "cards"` where the picture is how a row is found | `model/records`, `model/cards` |
+| Read by their day | List `layout: "calendar"`; on a record, a child List with `layout: {"agenda": …}` | `model/calendar`, `model/layouts` |
+| Booked on a resource | List `layout: {"lanes": {"by": …}}`, and the table's `no_overlap` | `model/lanes`, `model/write-rules` |
+| A log of what happened | a child List with `layout: "timeline"` | `model/layouts` |
+| Opened to be worked on | the Record's Sections, in the order the work reaches them — `at` where it moves in 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 | `model/section-node` |
+| Rows that each belong to another row | a child List on that row's Record, with `create` and `remove`; a List with `same` or `app` where read-only, for rows another app works | `model/list-node` |
+| Moving through a status | an Act per move, `status.dates` for the moment of each stage, and the register's Readings | `model/act-node`, `model/status`, `model/reading-node` |
+| 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 | `model/tab-node` |
+| Papers a case gathers | a List with `expect`; the papers made, an Act's `templates` | `model/list-node`, `model/act-node` |
+| A plan of spans | List `layout: {"gantt": {"start": …}}` | `model/gantt` |
+| Stood at a place on a plan, flat or in 3D — pallets, bins | List `layout: {"plan": …}`; places state `plan_place` | `model/plan` |
+| 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 | `model/list-node` |
+| 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 | `model/list-node` |
+| 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` | `model/record-places-pins-and-cadence` |
+| Photos that must be taken on site | `records.on_site: {"photos": […]}`: a photo taken through the camera keeps where the device stood, and a record holding one taken away says so | `model/record-places-pins-and-cadence` |
+| The real size of the thing (a carton, a piece of furniture, a pallet) | `records.size: {"across": …, "along": …, "up": …}`: three number fields in one length unit, read as one fact "400 × 300 × 250 mm" after the subtitle; a plan register draws each box at that size | `model/record-places-pins-and-cadence`, `model/plan` |
+| 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 | `model/record-places-pins-and-cadence` |
+| Who did what on which day | List `layout: "roster"` with the List of its cells inside | `model/roster` |
+| 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 | `model/outside-node` |
+| A record whose page is its own arrangement of pieces the app already states | Record `compose` | `model/composed-page` |
+| Steps people drop out of between | a Reading with `steps` on the record whose child rows count them | `model/reading-node` |
+| A record's own numbers nobody keys, read at a glance | consecutive Readings with no `entity` (two to eight tiles) | `model/reading-node` |
+| 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 | `model/publish-desk` |
+| Papers an agent reads, where the owner asked for one | an Act's `intake` with `fills` | `model/act-node` |
+| Calls and visits | an Act's `record` | `model/act-node` |
+| A tool on a record that the model cannot draw (a drawing editor, a folded-box preview) | a custom-code app over the same table, opened by an Act's `open` | `model/act-node` |
+| 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` | `model/act-node` |
+| Documents covering lines | a List with `under` | `model/list-node` |
+| Rows on file a record takes in | a List with `pick` | `model/list-node` |
+| One owner's question across jobs | an App of Tabs and Readings and no register | `model/app-node` |
 
 ### Faces and pictures
 
 #### Party
 
-`records.<entity>.party` is `"person"` where the rows are people (a contact, a patient, a driver) and
+`records.party` is `"person"` where the rows are people (a contact, a patient, a driver) and
 `"organization"` where they are companies (a customer, a supplier, a carrier). Every surface drawing one of
 its rows — the register's row, a link's chip, a picker's option, the record's header — then draws a face:
 its `image` (a photo, a logo), else its initials. Without it, a person is drawn as a thing. A workspace
-member is a `select_member` field, and is drawn by their face already. Worked: `examples/party`.
+member is a `member` field, and is drawn by their face already. Worked: `examples/party`.
 
 #### Image
 
-`records.<entity>.image` names the files field that pictures a row — a product's photo, a damage photo, a
+`records.image` names the files field that pictures a row — a product's photo, a damage photo, a
 scan, a receipt. Every row of it then leads with its picture, or its paper's preview, wherever it is drawn;
-a link to it previews the file. Never a field an act keeps the paper it makes in (`into`). Register
+a link to it previews the file. Never a field an Act keeps the paper it makes in (`into`). List
 `layout: "cards"` where the picture is how a row is found. A files field the record keeps as a folder of
-papers is a `files` block, read whole. Worked: `examples/cards`.
+papers is drawn as a Field, read whole. Worked: `examples/cards`.
 
 #### A link opens its row
 
@@ -115,10 +79,10 @@ On a record, a link to one row opens its peek: a drawer on a desk, a sheet on a
 row's face — mark, name, status, line and its figure by its field's name — and nothing to edit. A link read in a
 row's cell or on its line opens from its name; a link the record keeps as a field rests as its picker, and
 its way out stands at the field's label where the row has somewhere to go. The peek's one act leaves for
-the app whose register is that entity's rows — the first, in the model's order, that the member
-can open — at the row's address, or goes to the row inside this app where the entity is the app's own,
-one of its books' or a log's, in that list — a log's rows only from their own app. With no such app the peek has no act, and a link answered in what an act asks opens
-no peek. The model states none of it: give the entity an app of its own and
+the app whose register is that table's rows — the first, in the member's own order of apps, that the member
+can open — at the row's address, or goes to the row inside this app where the table is the app's own,
+one of its Books' or a log's, in that list — a log's rows only from their own app. With no such app the peek has no act, and a link answered in what an Act
+asks opens no peek. No prop states it: give the table an app of its own and
 its links lead there. The app opened decides what the member reads of the row; a row it withholds
 lands them on its not-found.
 
@@ -126,157 +90,167 @@ lands them on its not-found.
 
 Rows that each stand on a day, or hold a run of days or hours, are read where they stand in time — never
 as two date columns. A row holds a span when its `records` line (title and subtitle) holds two dates, its
-`records.frees` names the day it ends, or `write_rules.<entity>.no_overlap` books it on a row its `by` links to (a
+`records.frees` names the day it ends, or the table's `no_overlap` books it on a row its `by` links to (a
 chair, a machine). A `no_overlap` by a person or a value alone keeps one row at a time each — a member's periods in
 turn — read by what they hold.
 
 #### Calendar
 
-`register.layout: "calendar"`: the rows by their day — a month, a week, a day or a list; an entry at its
+`layout: "calendar"`: the rows by their day — a month, a week, a day or a list; an entry at its
 hour where its date holds one, over its span where its line holds a second date. An entry pressed opens a card on
-it: the row, Delete, its acts, Reschedule (the day alone moves; its hour and its length stay) and Open. Worked:
+it: the row, Delete, its Acts, Reschedule (the day alone moves; its hour and its length stay) and Open. Worked:
 `examples/calendar`.
 
 #### Lanes
 
-`register.layout: "lanes"` with `lanes` naming a one-row link whose target's rows are the lanes (a chair, a
+`layout: {"lanes": {"by": …}}` with `by` naming a one-row link whose target's rows are the lanes (a chair, a
 machine, a room), each drawn even when empty: every row a block from the first date on its line to the
 second, and a free stretch adds a row there. `loads` reads what a lane carries against what it holds. A
 `no_overlap` `by` the same link refuses two rows on one resource at once. Worked: `examples/lanes`.
 
 #### Gantt
 
-`register.layout: "gantt"` with `gantt.start` (and `end`, else the entity's first `due`): one bar a row over
-its run of days — a shipment, a hire, a task of a project — read against today. `gantt.milestones` marks
+`layout: {"gantt": {"start": …}}` (and `end`, else the table's first `due`): one bar a row over
+its run of days — a shipment, a hire, a task of a project — read against today. `milestones` marks
 dates on the bar, `planned` the plan under it, `progress` how far it is done, `after` the rows it waits on;
-the register's `group` is its lanes. Worked: `examples/gantt`.
+the List's `group` is its lanes. Worked: `examples/gantt`.
 
 #### Roster
 
-`register.layout: "roster"` with `roster` naming the child whose rows fill the days — one link back to the
-register's entity and a date on its line: what each row did on each day (shifts, runs, attendance). With
-`expect` (and `of`) the columns are the options of a select instead of days: which papers each row holds.
+`layout: "roster"` with a List inside it over the child whose rows fill the days — one link back to the
+register's table and a date on its line: what each row did on each day (shifts, runs, attendance). With
+`expect` (and `of`) on the cells the columns are the options of a select instead of days: which papers each row holds.
 Worked: `examples/roster`.
 
 #### Agenda
 
-An `agenda` block on a record: a child's planned entries by day, soonest first, today marked, each with its
+A child List with `layout: {"agenda": {…}}` on a record: a child's planned entries by day, soonest first, today marked, each with its
 picture; within a day by the hour, or by a single select of the part of the day. `start` counts Day 1 from a
 date of the record (a trip, a course).
 
 #### Timeline
 
-A `timeline` block on a record: a child read as a log of dated entries, newest first, with a composer — the
+A child List with `layout: "timeline"` on a record: a child read as a log of dated entries, newest first, with a composer — the
 calls, visits and notes about the record, each with who and when, and its files where the child's `image`
-names them. Entries planned ahead are an `agenda`; the status's moves are its history. Worked:
+names them. Entries planned ahead are an agenda; the status's moves are its history. Worked:
 `examples/party`.
 
 ### Moves and numbers
 
 #### Moves
 
-Rows a status stages towards its `closed` options move by acts: each moves one option on to the next (`when` the
-status holds it, `set` to the next), at the foot of the section whose work it ends. A status with nothing closed is a
+Rows a status stages towards its `closed` options move by Acts: each moves one option on to the next (`when` the
+status holds it, `set` to the next), at the foot of the Section whose work it ends. A status with nothing closed is a
 condition a person sets. A value decided as a row reaches an outcome — why it was lost, refused, voided — is that
-act's `asks`, never a field the reader must remember to fill. An act reaching past the workspace — sending an invoice
+Act's `asks`, never a field the reader must remember to fill. An Act reaching past the workspace — sending an invoice
 to a service, a letter by mail — runs its `workflow`, and what the workflow keeps from the answer (an invoice's id,
-its link) is named in `writes`, the act's as what it sets is. A stage the work only steps aside into from one step
-and leaves only back to it — a pause, a repair — is a detour: its option and its section stand before that step,
-entered by its own act; listed after, it reads as the work's next step.
+its link) is named in the Act's `set`. A stage the work only steps aside into from one step
+and leaves only back to it — a pause, a repair — is a detour: its option and its Section stand before that step,
+entered by its own Act; listed after, it reads as the work's next step.
 
 #### Stages
 
 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
-matter; or tasks, where only how many are done counts (`records.<entity>.task`). A pipeline states each stage once in
-`records.<entity>.status.stages` — its `owner` (a member field, a link's member field, or a `role`) and its target
-`within` days — and the server holds it: only the owner's acts move the row on, and a level an amount skips stands
-named with why. Late rows, rows due soon, a warning the line draws and rows waiting on the reader stand first in a
-register; a register whose job is a strict order, a first-come queue, states `register.attention: false`.
-
-#### History
-
-`records.<entity>.status.history` names a child the app's own writes append one row to per status move: its
-link to the row, the new status, the moment and who. The rail reads it. A record's activity shows every move as a change, so `record.history: true` adds
-nothing — and beside `record.activity: false`, which shows them nowhere, it is
-refused. Worked: `examples/approval`.
+matter; or tasks, where only how many are done counts (`records.task`). A pipeline states each stage once in
+`records.status.stages` — its `owner` (a member field, a link's member field, or `{ "group": <id> }`, a member group) and its target
+`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
+named with why. A move forward passes each owned stage between that binds the row, each its owner's. A stage's `when`
+names the rows it binds, held as an Act's `when` holds them on the row's own fields, as the row stood before a write
+and as the write leaves it; with none, it binds every row. Expense claims over a limit wait for the finance group while
+smaller ones go straight to payment: `"finance_review": { "owner": { "group": <id> }, "when": { "amount": { "gt": 5000000 } } }`.
+A row at a stage leaves it by its owner whatever its `when`; `dropped` names the closed options
+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
+register; a register whose job is a strict order, a first-come queue, states `attention: false`.
+
+#### Stage dates and history
+
+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
+to the business — reported, filtered, printed — it is a date on the row that `records.status.dates` stamps as the row
+enters the option, whoever writes: the one way a status is timed, and the moment a stage's `within` runs from (each stage, and
+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 move whose
+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
+status move (its link to the row, the new status, the moment and who) for a business that reports on every move: moves
+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
+its 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
+stage is signed once per person, read off who moved the row.
 
 #### Readings
 
-`register.readings` stand above the rows and read the rows in view. Lead with the job's headline number —
-its exception as a formula's yes/no in a `metric`'s `where` (what is late, what is short), never a stage the
-status chips already count — then at most the mix (`breakdown`) and the movement (`trend`), varied by job.
-A `pivot` reads on a dashboard. A dashboard app (`dashboard`) answers one owner's question across jobs, each
-reading windowed by the period the reader picks, and a `list` reading hands over the rows to act on. A
-dashboard of many readings states `tabs` (2 to 5) and each reading the `tab` it stands under, so one sheet draws at a time. A
-record's `metric`, `breakdown` and `trend` blocks read its own child rows. Sums of each row's child rows are a tab's `totals`. Worked: `examples/approval`, `examples/dashboard`.
+A List's Readings stand above the rows and read the rows in view. Lead with the job's headline number —
+its exception as a formula's yes/no in a Reading's `where` (what is short), never a stage the
+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, and so is a sum: a status register with no single select to split by gets no default band.
+A grid (`by` and `across`) reads on a dashboard. A dashboard — an App of Readings and no register — answers one owner's question across jobs, each
+Reading windowed by the period the reader picks, and a List hands over the rows to act on. A
+dashboard of many Readings states Tabs (2 to 5) and each Reading the `tab` it stands under, so one sheet draws at a time. 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`.
 
 #### Funnel
 
-A `funnel` block reads a record's child rows as steps, each a number column summed over them — a week's channels
+A Reading with `steps` reads a record's child rows as steps, each a number column summed over them — a week's channels
 from impressions to bookings, an order's lines from ordered to shipped. It states how much of the first step
-each later one keeps, the share lost between two neighbours, and the last over the first. State two to eight
-`steps` in one unit; where the path turns — reach, then conversion — state two blocks one straight after the
+each later one keeps, the share lost between two neighbours, and the last over the first. State two to six
+`steps` in one unit; where the path turns — reach, then conversion — state two Readings one straight after the
 other, so the second's bars are read over its own first step: they draw on one grid, every bar starting at one
 edge and every value ending at another, each under its own label. A step no row holds a number in reads as not measured: leave it empty, never a zero nobody measured.
 
 #### Priced lines
 
-A quote's items, an estimate's works, a repair sheet's damages are lines priced off a book: an entity whose
+A quote's items, an estimate's works, a repair sheet's damages are lines priced off a book: a table whose
 `records` names each item, puts the code people type on its line and its price as its `figure`. The line links to
-it, asks the link and its quantities in its block's `create`, and copies the price (`default_from`), so the quote
+it, asks the link and its quantities in its List's `create`, and copies the price (`default_from`), so the quote
 keeps what was quoted when the book moves. A line's amount is a formula, the record's total a rollup over the rows
-the block shows — what is not paid for is a second rollup, never a filter on the first, so each group subtotals.
-Group the lines by the parts the record is quoted in (a container, a room, a leg), a field the line asks. The book
-is its keeper's desk, an app of its own.
+the List shows — what is not paid for is a second rollup, never a filter on the first, so each group subtotals.
+Group 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
+an app (`first_build` § 3).
 
 ### The record
 
 #### Sections
 
-`record.sections`, in the order the work reaches them: the fields people write, a `files` block per paper the record
-keeps, a block per child, the acts at each one's foot. A register laid out in time (calendar, lanes, roster) opens the
-default record: every field a person writes. `record.compose` is not for a record a standard section order would
-do, and never for behaviour, which belongs in an act.
+The Record's Sections, in the order the work reaches them: the fields people write, a Field per paper the record
+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
+default record: every field a person writes. `compose` is not for a record a standard Section order would
+do, and never for behaviour, which belongs in an Act.
 
 #### Children
 
-Rows that each belong to one row of another entity (a one-row link to it) are drawn under that row: a `rows` block on
-its record, a `timeline` where they are a log, an `agenda` where they are planned on a day and within it, a roster of
-them, or lanes of them by that link. Which children a record lists is the author's — one of them at least. A block
+Rows that each belong to one row of another table (a one-row link to it) are drawn under that row: a List on
+its Record, `layout: "timeline"` where they are a log, `layout: {"agenda": …}` where they are planned on a day and within it, a roster of
+them, or lanes of them by that link. Which children a record lists is the author's — one of them at least. A List
 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
-still owed — on a block that adds no rows. Rows on
+still owed — on a List that adds no rows. Rows on
 file before the row they come to belong to — a job's cost lines before the supplier bill over them — are picked into
-it: a rows block with `pick`, often with `create: false` and `remove: false`.
+it: a List with `pick`, often with no `create` and no `remove`.
 
 ### Papers
 
 #### Expect
 
-A rows block with `expect` naming the child's title — a single select of kinds, or a one-row link to a
+A List with `expect` naming the child's title — a single select of kinds, or a one-row link to a
 catalog: one line per kind, the ones not yet filled standing empty, filled in place. `of` narrows the kinds
 to the record's own multi-select of those it needs. The papers a case gathers, the fees a record knows it
 owes. Worked: `examples/case`.
 
-`only` lists the kinds a block holds a line for, so each kind stands in the section whose job it is, once. The act making a paper (`paper: "<child>.<kind>"`) is its line's button while it applies, the upload in the ⋯.
+`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>"`) is its line's button while it applies, the upload in the ⋯.
 
 #### Templates
 
-A paper the business makes is an act's `template`, kept in the record's files field `into` — or several at
-once, `templates`: listed where the act stands, each made one as its file, each not yet made a placeholder,
+A paper the business makes is an Act's `template`, kept in the record's files field `into` — or several at
+once, `templates`: listed where the Act stands, each made one as its file, each not yet made a placeholder,
 the reader ticking which to make. Worked: `examples/case`.
 
 #### Intake
 
-A paper the business is brought and reads is an act's `intake`: the press takes the papers, an agent reads
+A paper the business is brought and reads is an Act's `intake`: the press takes the papers, an agent reads
 them, and each is filed as the line of its kind in the child the record `expect`s, while `fills` writes what
 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. Worked: `examples/case`.
 
-An agent act — an `intake`, a `record`'s `fills` — spends a run on every press, so it is stated only where the
+An agent Act — an `intake`, a `record`'s `fills` — spends a run on every press, so it is stated only where the
 owner asked for an agent to do that job; otherwise a paper brought is its `expect` line, and a person types what it states.
 
 #### Under
 
-A rows block with `under`: the documents that cover lines (an invoice over its fee lines) stand as headings
+A List with `under`: the documents that cover lines (an invoice over its fee lines) stand as headings
 over the lines they cover, and a line no document covers offers to make one. A document entered as it arrives over lines
 already on file (a supplier bill) picks them with `pick` instead; choose one per document.
 
@@ -284,37 +258,49 @@ already on file (a supplier bill) picks them with `pick` instead; choose one per
 
 #### Record act
 
-An act's `record`: the press records a call, visit or meeting — audio, transcript, screen where captured — and
+An Act's `record`: the press records a call, visit or meeting — audio, transcript, screen where captured — and
 files it as a new row of the record's `timeline` child (`into`), stamped `at` and `by`; `fills` lets an agent fill
 that row's fields from the transcript, where the owner asked. Worked: `examples/calls`.
 
+### Other apps
+
+#### Open act
+
+An Act's `open`: the id of another app — usually a custom-code app drawing what the model cannot — that the press
+opens at this record. It is navigation only: no workflow of either app runs, and what the tool writes it writes
+through its own declared workflows. It stands alone with `label` and `when`, on one record of the app's own (an Act
+in a Record's section, or a compose `Act` piece naming it). The target must be an app of the workspace that reaches the
+record's table — a register over it, or custom code declaring no table or declaring it; anything else is refused at
+save. A reader without `use` on the target meets that app's own "cannot open" state.
+
 ## The visual bar
 
 - A person shows a face, a thing its picture, a file its preview, a plan its days on a time axis, a
-  quantity a meter (`records.limits`) or a chart, a register its `readings` under its title, and long text
-  reads whole (a `text` block).
-- Every app states its tile's colour (`theme.color`), apart from the workspace's other apps where it can be,
+  quantity a meter (`records.limits`) or a chart, a register its Readings under its title, and long text
+  reads whole (a markdown Field is a prose block; `block: true` makes a plain long text one).
+- Every app states its tile's colour (the App's `color`), apart from the workspace's other apps where it can be,
   so the launcher tells the desks apart before their names are read.
 - Every category the job reads is coloured: each select option's `color`, and a `mark` where a brand or a
   glyph names it — on every option of a select read down a column (how it was paid, the channel, the mode).
-- Someone is a face wherever they are read. A person is a member field and a party a row of an entity stating
+- A yes that needs attention (papers the customer still owes) is a `Check` of its List over a yes/no formula, so it
+  reads in the warning tone on the row's line; every other yes reads in the success tone.
+- Someone is a face wherever they are read. A person is a member field and a party a row of a table stating
   `party`; where a select's options name people or organisations who are neither, every option's `mark` is
   its face (`{"kind": "avatar", "name": "person"}`), never a colour dot.
-- Every files field is drawn somewhere — a section's `fields`, a `files` block, the `image`, or where the
-  act making it stands.
+- Every files field is drawn somewhere — a Section's Fields, a Field of the Record, the `image`, or where the
+  Act making it stands.
 - The paperwork is the proof of the work, so every paper the job takes in and every document it issues has a
-  place on the record, in the section where that work happens: a files field per purpose (what arrived, what
+  place on the record, in the Section where that work happens: a files field per purpose (what arrived, what
   was issued to the customer, to the carrier, to the authority), each kept visible after the stage that made it,
   and a source — a screenshot, an email, a sheet — on the row whose figure came from it.
 - A screen with none of these is bland, and bland is a finding: text drawn where a treatment above exists
-  is a change to the model.
+  is a change to the tree.
 
 ## Look at it
 
 After an apply, the `screenshot_app` tool draws each app as its people see it — the register, and a record
 by its `path` — at a desk's width and a phone's, one screen a shot, naming the columns a table left off at
-each width: `screen` names which screen of a long record. From the CLI, `-o <dir>` saves the shots. Beside the shots, its `verdict` is what a plan of the workspace's
-model finds of the app now, beside its rows: what the next apply would refuse it for and the notes on it, the
-`patch` adopting the decisions among them, and the app's body as the patch leaves it (`draft`). Judge each shot
-against § The visual bar, change the model, and apply again. The `rollback_app` tool returns an app to an earlier
-version; the tables and rows stay as they are.
+each width: `screen` names which screen of a long record. From the CLI, `-o <dir>` saves the shots. Beside the shots, `verdict` is what a write of the app's stored tree would refuse it for now, beside its rows, and
+the notes on it. Judge each shot against § The visual bar, change the tree with `nodes`, and write again. To go back,
+send the tree you saved before the change as `body` with `app_id`, nulling an App prop stated since (`words`, `scope`,
+`period`, `icon`); the tables and rows stay as they are.